--- title: "Running AI coding agents in a monorepo: what to watch for · Cork" description: "What breaks when AI coding agents work in a monorepo: instruction files, context size, shared packages, affected tests and parallel agents, with fixes for each." canonical: "https://corkcli.com/blog/ai-coding-agents-monorepo" last_updated: "2026-11-14" published: "2026-10-03" author: "Kevin Vera" --- # Running AI coding agents in a monorepo: what to watch for What breaks when AI coding agents work in a monorepo: instruction files, context size, shared packages, affected tests and parallel agents, with fixes for each. By Kevin Vera · October 3, 2026 · [Guides](https://corkcli.com/blog/c/guides) · 6 min read AI coding agents work in monorepos, but five things need attention: which instruction files each agent loads, how much of the repo it reads before acting, changes to shared packages that ripple into other teams' code, running the right tests (only the affected ones, but all of the affected ones), and several agents or teams editing the same shared code at once. The fixes are mostly configuration: nested `AGENTS.md` or `CLAUDE.md` files per package, starting agents in the package directory, affected-only test commands, ownership rules, and some way for parallel agents to see each other's changes to shared code. ## 1. Instruction files: the right rules for the right package Every major agent now reads layered instruction files, and in a monorepo the layering matters. - **Codex** walks from the project root down to the current working directory, reading at most one file per directory (`AGENTS.override.md`, then `AGENTS.md`, then configured fallbacks) and concatenating them root first, so files closer to where you work override earlier guidance. It stops adding files once the total reaches `project_doc_max_bytes`, 32 KiB by default. A large root file can crowd out package files. - **Claude Code** loads `CLAUDE.md` files in the directories above where you launch it, and loads files in subdirectories on demand when Claude reads files there. Path-scoped rules in `.claude/rules/` apply only to matching files. In large monorepos, the `claudeMdExcludes` setting skips other teams' instruction files by path or glob. Claude Code reads `AGENTS.md` when there is no `CLAUDE.md` in the working directory or above it. - **Cursor** supports project rules in `.cursor/rules` (`.mdc` files with `description`, `globs` and `alwaysApply` frontmatter) and nested `AGENTS.md` files in subdirectories. What to do: keep the root file short (repo-wide conventions, how to run tests, how to land changes), put package-specific rules next to the package, and start agents in the package directory when the task is local to it. ## 2. Context size: agents read too much A monorepo has far more files than any context window. An agent asked a vague question will search broadly, open files from unrelated packages, and burn tokens before its first edit. Ways to narrow it: - **Write specific prompts.** Claude Code's cost guidance makes the same point: "add input validation to the login function in auth.ts" costs far less than "improve this codebase". - **Give the agent symbol navigation.** Language server integrations (Claude Code's code intelligence plugins, or the language features in Cursor) let an agent jump to a definition or find references instead of grepping across every package. Claude Code's docs note that monorepos can produce false "unresolved import" diagnostics if the language server is not configured for the workspace. - **Use sparse checkouts for agent worktrees.** `git sparse-checkout set packages/billing packages/shared` limits a working tree to the directories that matter (cone mode, the default, includes everything under the listed directories plus top-level files). Fewer files on disk means fewer files the agent can wander into, though it also hides code the agent might need to check callers in. ## 3. Shared packages: the change that breaks someone else The defining monorepo risk is a change to a shared library that compiles in its own package and breaks a consumer two directories away. An agent editing `packages/shared/date.ts` usually has no idea which of fifty packages import the function it is changing. Before changing anything exported from a shared package: ```bash git grep -n "formatInvoiceDate" -- 'packages/*' ``` Better, use the build tool's graph, which knows real package dependencies. Turborepo's filter syntax selects dependents with a leading ellipsis: ```bash turbo run test --filter=...@acme/shared ``` Nx can show and run what a change affects: ```bash nx affected -t test ``` Put this in the instructions: "Before changing an export in packages/shared, list its dependents and run their tests." ## 4. Tests: affected, not all, and not too few Running the full suite after every agent edit is slow and expensive; running only the edited package's tests misses the consumers. Use your build tool's affected logic: - Turborepo's `--affected` flag is equivalent by default to `--filter=...[main...HEAD]`, the packages changed between `main` and `HEAD` plus their dependents; `TURBO_SCM_BASE` and `TURBO_SCM_HEAD` override the range. - `nx affected -t test` uses git to find changed files, maps them to projects, and follows the project graph to dependents. The default base is `main`; in CI, set the base to the last successful commit on main. Give agents one command that does this, and make it the command they run before landing. ## 5. Parallel agents and ownership Monorepos concentrate many teams, and now many agents, on one repository. Two problems appear: - **Ownership.** GitHub CODEOWNERS (in `.github/`, the root, or `docs/`, last matching pattern wins) requests the owning team's review automatically when an agent's pull request touches their paths, and branch protection can require that approval. - **Concurrent edits to shared code.** Worktrees stop agents from overwriting each other's files on disk, but two agents can still change the same shared function in different branches, and the conflict surfaces only at merge or, worse, at runtime. Splitting tasks by package helps until two tasks both need the shared code. ## How Cork helps Cork addresses the last two problems directly. When an agent starts or gets a prompt, it is briefed with the exact signatures, callers and recent changes of the code it is about to touch, so an agent changing a shared export knows who calls it without searching the whole monorepo. `blast_radius` and `get_symbol` are available as MCP tools when it needs more. When another agent changes code yours depends on (a rename, a new signature), your agent hears it on its next step; a write gate holds an edit against code another agent is changing right now until your agent has their version; and a rename becomes a [semantic lint](https://corkcli.com/blog/semantic-lint) rule your agents are checked against. `git push` becomes one step that rebases onto teammates' commits, reruns the tests and pushes. Cork is the [coordination layer](https://corkcli.com/blog/coordination-layer-ai-coding-agents) for multiplayer coding agents: it keeps Claude Code, Codex and Cursor agents, on one machine or across a team's machines, from overwriting each other on one codebase, and hands each agent what the others already learned. On the paid plan, agents across teammates' machines see each other, which is the usual monorepo case. ```bash curl -fsSL https://corkcli.com/install.sh | sh ``` ## Frequently asked questions ### Should I put one AGENTS.md at the root of a monorepo or one per package? Both. Keep the root file short and repo-wide, and put package rules in that package's directory. Codex combines them root first and caps the total at 32 KiB by default. ### How do I stop Claude Code loading other teams' CLAUDE.md files? Use the `claudeMdExcludes` setting with path or glob patterns for the files to skip. ### How do I make agents run only the affected tests? Give them your build tool's affected command, such as `turbo run test --affected` or `nx affected -t test`, and require it before landing. ### Do worktrees solve parallel agents in a monorepo? They isolate files on disk. They do not stop two agents changing the same shared code in different branches; that shows up at merge time. ## Sources - - - - - - - - - ## Related reading - [Running 10 or more coding agents at once: what breaks and how to fix it](https://corkcli.com/blog/run-10-coding-agents-at-once): What breaks when you run 10 or more AI coding agents at once (rate limits, disk, ports, git races, duplicated work, review load) and practical fixes for each. - [Cork vs Cursor Projects: a coordinator for Cursor agents, or shared state for every agent](https://corkcli.com/blog/cork-vs-cursor-projects): Cork vs Cursor Projects: a Projects coordinator plans work and directs Cursor's agents with shared context files; Cork keeps any agents on one codebase aware of each other. - [Parallel AI coding agents on a team: how to split who works on what](https://corkcli.com/blog/split-work-parallel-ai-coding-agents-team): How a team splits work across parallel AI coding agents: slice by code ownership, name shared files, one branch per agent, small tasks, and live coordination. - [Claude Code subagents vs parallel sessions: when to use which](https://corkcli.com/blog/claude-code-subagents-vs-parallel-sessions): Subagents or parallel Claude Code sessions? Compare context, control, file isolation and cost, with a decision checklist and setup for each, as of October 2026. [All articles](https://corkcli.com/blog.md) · [Cork in Markdown](https://corkcli.com/index.md) · [llms.txt](https://corkcli.com/llms.txt) This page in HTML: https://corkcli.com/blog/ai-coding-agents-monorepo