Governing the Machine — Eliminating AI Churn with Codified Project Rules

As I integrated AI coding assistants like Cursor and Gemini into my monorepo workflow, I hit a point of diminishing returns. Because these models are trained on a vast range of coding styles, they lack inherent knowledge of the specific boundaries of a custom, layered architecture. In a complex system, this leads to “AI Churn”—where fixing the AI’s architectural mistakes takes longer than writing the features themselves.

The Problem: The Hallucination Bottleneck

In a monorepo structured with Atomic Design and strict package boundaries, the AI often struggled with three critical issues:

1. Brittle Deep Imports: The AI would “see” a file in the directory tree and suggest importing it directly from an internal folder (e.g., ❌ @repo/wp-utils/src/types). This bypassed my public API and created unmaintainable coupling.
2. Hook Integrity Erosion: AI models frequently prefer default exports. However, when a React hook is default-imported, it can be renamed to an identifier that lacks the use prefix. This blinds the eslint-plugin-hooks-rules linter, allowing conditional hook calls to slip through and cause runtime crashes.
3. Workspace Desync: Without guidance, the AI would sometimes attempt to install internal packages from the public NPM registry rather than resolving them locally within the monorepo.

The Solution: Codified Architectural Guardrails

I realized that for AI to be a high-precision partner, I needed to treat it like a new engineer on the team who needs a clear, enforceable “Style Bible.” I moved my architectural standards out of my head and into Project Rules (.mdc files).

I created a dedicated linking-standards.mdc file to enforce a “Lean Standard” for the entire repository. This file provides the LLM with persistent context that it must evaluate before making a suggestion.

Technical Deep Dive: Enforcing the Public API

The core of my governance strategy relied on two high-impact rules:

1. Strict Public API Enforcement The rule explicitly forbids any import containing /src/ from another package. This forces the AI to use the explicit exports I defined in each package.json, ensuring our bundle sizes remain optimized and tree-shakeable. I also mandated the use of the workspace:* protocol for all internal dependencies. This ensures that the AI always points to the local version of our @repo/ui library, ensuring 1:1 version parity across the entire codebase.

2. Named Exports for Hook Safety To protect “Hook Integrity,” I mandated named exports for all reusable UI elements and hooks. This ensures the use prefix is retained throughout the codebase. By preventing the AI from default-importing and renaming hooks, I kept my automated linting tools functional and prevented an entire class of runtime errors that occur when hooks are called conditionally under “mystery names.”

The Outcome: A Deterministic Workspace

By implementing these rules, I transformed the AI from a source of technical debt into a highly reliable architectural assistant. The AI stopped “inventing” import paths because it was restricted to the legal entry points of my system. Global renames and symbol tracking are now 100% reliable, and my development environment is deterministic. This wasn’t just a workflow tweak—it was about leading an AI-native engineering environment where the human architect sets the laws that the machine must follow.