Give AI Agents a Map, Not a Maze: Restructuring a Frontend Monorepo for Stable Iteration
Agents routinely break frontend builds when they lack context and rules. This pattern turns the directory structure into an executable contract, cutting iteration errors and making agent-driven development practical for real codebases.
Restructuring a frontend monorepo around AI agents changes the fundamental optimization target. Traditional layouts serve human collaboration, with technical layering and multiple scripts; an agent-friendly layout serves context acquisition cost and modification boundaries. The result is a root AGENTS.md file that lists commands and safety boundaries, a .agent/ directory holding skills, specs, and runtime snapshots, and a single scripts/verify command that runs typecheck, lint, test, and build in a fixed order.
Directory splitting shifts from technical layers (components/ hooks/ utils/) to business domains (features/ or domains/), so each change is contained in one directory. Shared packages get strict one-way dependency rules, and cross-application contracts move into a shared type package that catches breaking changes at compile time. To handle reuse, the structure layers components: stable base components live in ui-core, contracts and client logic in shared packages, and business combinations stay inside domains. Cross-domain reuse uses a promotion step, only moving a component up after it proves stable and business-agnostic.
A component inventory snapshot in .agent/contexts/ tells agents what already exists and where to find it, generated by script to avoid staleness. The whole design converts the implicit knowledge that human developers carry - how to verify, which routes exist, which components are safe to reuse - into versioned files and directory rules, giving an agent a deterministic map instead of requiring it to guess.
Directory structure acts as a communication interface, and when the reader is an agent, rules must be explicit and machine-parseable; the article redefines the optimization target from human search habits to modification boundaries.
The promotion mechanism for shared components is a pragmatic answer to premature abstraction: it makes what belongs in a shared package a data-driven decision rather than an architectural guess, and it avoids the junk-drawer components/ problem.
The reliance on snapshots and spec files reveals that agents are effectively stateless; because they cannot rely on conversational history or team conventions, every useful context must be captured in versioned files.