AI Coding Agents
Developer Experience
Coding agents in monorepos, with clear boundaries
September 24, 2026 - 2 minute read
AI coding agents in monorepos face an information problem before they face a coding problem. One repository can contain many runtimes, owners, deployment units, generated files, and test commands. Directory proximity does not always reveal which packages can depend on each other or which checks a change requires.
A dependency graph gives the agent a better map. Nx documents how its affected command uses project and task graphs to select work influenced by a change. Other monorepo tools provide similar concepts. The important property is a machine-readable relationship between changed files and required validation.
Give coding agents in monorepos local context
Place stable instructions at the repository root, then add narrower guidance where a subtree genuinely differs. Root instructions should name the package manager, workspace layout, global safety rules, and the cheapest reliable validation commands. Package instructions should cover local generators, ownership boundaries, and focused tests.
Factory's AGENTS.md documentation supports nested instruction files. Droid discovers guidance along the path it inspects, so a web application can carry different commands from a Go service without duplicating the entire root file.
Keep the instructions concise. Link to maintained design documents rather than copying them. Remove stale package inventories, and make every rule verifiable. “Run pnpm --filter checkout test after changing checkout” gives the agent a usable boundary. “Test carefully” does not.
Scope AI coding agents in monorepos
Start each task with one owning package and a defined dependency radius. Ask the agent to identify consumers before editing a shared library. For cross-package changes, require a plan that lists interfaces, generated outputs, and test targets.
Useful repository signals include:
- Workspace manifests and lockfiles
- Project and task graphs
- Code ownership files
- API schemas and generated-code markers
- Package-level test and build commands
- Deployment ownership and release boundaries
Run the agent from the narrowest useful working directory. Factory's Droid Exec accepts --cwd for package-level scope and can create isolated git worktrees for concurrent jobs. Isolation prevents two agents from changing the same checkout while they work on different packages.
Validate the affected graph
An affected-only test is fast, but it is only as trustworthy as the graph behind it. Add a periodic full build to catch missing dependency edges. When an affected check misses a real consumer, fix the graph or workspace metadata instead of permanently expanding every pull request gate.
Shared packages deserve stronger evidence. Test direct consumers, inspect public API changes, and review lockfile movement. If a generated client changes, verify both the source schema and regenerated output. If a package controls deployment, keep production actions outside the coding task unless explicitly approved.
Large repositories become manageable when boundaries are explicit and executable. AI coding agents in monorepos can then focus on a bounded package, trace known consumers, and return a small change with the exact checks reviewers expect.
