跪拜 Guibai
← All articles
Frontend · Agent

Give AI Agents a Map, Not a Maze: Restructuring a Frontend Monorepo for Stable Iteration

By 小龙6666 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

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.

Summary

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.

Takeaways
— AGENTS.md serves as the sole entry point for agents, listing tech stack, commands, and directory safety boundaries.
— The .agent/ directory stores skills, specs, and context snapshots (routes, menus, component inventories) that would otherwise be implicit human knowledge.
— scripts/verify is the only validation command, running typecheck, lint, test, and build in a fixed order and gating commits.
— Directory splitting is based on business domains (features/ or domains/) rather than technical layers, so a change stays within one folder.
— Dependency rules are hard: packages/ can be imported by apps/ but never the reverse, preventing shared-layer pollution.
— Cross-application contract types live in packages/shared-types/ so any change surfaces as a TypeScript compile error across apps.
— Route and menu snapshots in .agent/contexts/ give the agent runtime information it cannot access during development.
— Each iteration writes a spec file in .agent/specs/ with application scope, expected behavior, acceptance command, and forbidden directories.
— Reuse is layered: stable base components in ui-core, contracts and clients in shared packages, business combinations stay in domains; cross-domain reuse requires a promotion step after stability is proven.
— A component registry snapshot in .agent/contexts/ tells the agent what already exists and where to find it, generated by script to avoid staleness.
Conclusions

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.

Concepts & terms
AGENTS.md
A machine-readable instruction file placed at the repository root that tells an AI agent the project's tech stack, commands, directory boundaries, and rules it must follow.
.agent/contexts/
A read-only directory holding snapshots of runtime state, such as route tables, menu trees, and component inventories, that agents cannot see directly.
Promotion of shared components
The process of moving a component from a domain into shared packages only after it proves stable and business-agnostic, rather than proactively centralizing it.
scripts/verify
A single script that runs the full validation pipeline (typecheck, lint, test, build) in a fixed order, acting as the only gate for agent changes.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗