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. Directory proximity does not reveal which packages depend on a changed interface. If the dependency graph omits a checkout application's use of a shared library, affected tests can pass while skipping the consumer that broke.
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.
Trace consumers before choosing the scope
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.
Workspace manifests identify package membership and declared dependencies. The task graph connects those packages to checks that must run together. Ownership files identify who can approve a shared-interface change. Read these signals together so a package filter does not accidentally become the definition of the entire affected scope.
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.
