Patterns for navigating and maintaining boundaries in monorepo projects. Works with the `/focus` command to scope agent context to specific areas.
Patterns for navigating and maintaining boundaries in monorepo projects. Works with the /focus command to scope agent context to specific areas.
Every monorepo project should have a Monorepo Map section in its root AGENTS.md. This is a routing table that tells the agent where to find each area and its documentation.
## Monorepo Map
| Area | Path | AGENTS.md | Description |
|------|------|-----------|-------------|
| domain | `src/domain/` | `src/domain/AGENTS.md` | Business logic, entities, ports |
| connectors | `src/connectors/` | `src/connectors/AGENTS.md` | Platform integrations |
| api | `src/api/` | `src/api/AGENTS.md` | FastAPI routes and DTOs |
| workers | `src/workers/` | `src/workers/AGENTS.md` | Background jobs and schedulers |
| frontend | `frontend/` | `frontend/AGENTS.md` | React SPA |
| shared | `src/shared/` | `src/shared/AGENTS.md` | Cross-cutting utilities |
The map exists to prevent the agent from randomly exploring the codebase. When asked to work on something, the agent should:
Each area's AGENTS.md should include an Imports / Exports / Boundaries section that declares its dependencies:
## Boundaries
### Imports (this area depends on)
- `src/domain/entities` — Order, Product, Money value objects
- `src/shared/logging` — structured logger setup
### Exports (other areas may use)
- `src/connectors/amazon/client.py` — AmazonClient class
- `src/connectors/shopify/client.py` — ShopifyClient class
### Never Touches
- `src/api/` — connectors do not know about API routes
- `frontend/` — connectors have no frontend awareness
- `src/workers/` — connectors are called BY workers, never call them
Why this matters: Without explicit boundaries, the agent will create convenient but architecturally wrong shortcuts (e.g., a connector importing from the API layer to reuse a Pydantic model).
When a change requires modifying multiple areas:
1. src/domain/entities/ — add the entity dataclass
2. src/domain/ports/ — add the repository Protocol
3. src/connectors/ — implement the repository adapter
4. src/api/schemas/ — add request/response Pydantic models
5. src/api/routes/ — add the endpoint
6. frontend/ — add the UI (if applicable)
Each step happens in its own area and respects that area's patterns.
The shared/ area (or equivalent) contains cross-cutting utilities. Rules for shared code:
domain/Examples of good shared code:
Examples of code that should NOT be shared:
When the user asks you to work on something in a monorepo:
/focus command — sets the active working areatemplates/AGENTS.md — includes monorepo map template sectionrules/python/imports.md — Clean Architecture import boundaries