A single repository structure, or monorepo, holds multiple independently deployable services, libraries, and applications in one version-controlled repository. It is not a monolith: projects can still build, test, and deploy separately. The repository, dependency graph, and conventions are shared. section 10.1.1
For AI-assisted development, the appeal is system context. An agent can search across project boundaries without separate checkouts and query declared dependencies instead of relying solely on people to explain what connects to what. The dependency graph also helps identify what a change may affect. section 10.1.1
A useful monorepo depends on more than putting projects in the same folder:
- Make every project findable and readable without a separate checkout. section 10.1.1
- Declare dependencies so the build system can answer cross-project queries. section 10.1.1
- Enforce shared rules at the repository root with tooling rather than relying on memory. section 10.1.1
Listing 10.1 Hierarchical AGENTS.md - root as router, package as domain expert
# Root AGENTS.md (context router) To modify the checkout flow, read @packages/checkout/AGENTS.md To add a shared utility, read @libs/AGENTS.md To understand service boundaries, query the project graph: nx graph --focus=checkout Deprecated packages are tagged with `status:deprecated` - never modify them. Convention: all inter-service communication via message queues. Never direct HTTP. # packages/checkout/AGENTS.md (domain-specific) This is the production checkout service. Owner: payments-team (Slack: #payments-eng) SLA: 99.99% - changes require payments-team approval. DO NOT: make direct DB calls. All data access via message queue (see ADR-047). ALWAYS: run affected tests and lint before submitting. Testing: property-based tests in __tests__/properties/ - add new ones for any new business rule.
A hierarchical AGENTS.md example routes agents from root guidance to package-specific ownership, constraints, and testing instructions. section 10.1.1
The throughput wall
A team moving from 15 to 48 pull requests per day can overwhelm a monorepo CI pipeline designed around 15-minute runs. Fifty sequential iterations at that feedback time take 12.5 hours, compared with 25 minutes at 30 seconds per iteration. While waiting, an agent may also pursue unnecessary alternatives and clutter its context. section 10.3
Treat consolidation as a tradeoff, not a complete solution. Repository-wide visibility still needs navigable dependencies, and faster agent-driven changes can expose a CI bottleneck. Check feedback capacity as well as context and navigation when scaling the workflow. section 10.1.1 section 10.3 section 10.0


