AI engineering · Module 09a · Level 3: Configure your tools
Repository setup for agents
An agent is only as good as what it can find, build and check. The same model does far better in a repository where instructions sit next to the code, one command runs the right tests, and the dependency graph can be asked "what depends on this?". This module covers the repository standards that help any coding agent, then the two big structural choices: one repository or many, and which build system. Each comes with its pros and cons for agents.
A 5-minute conversation: Sam asks, Priya explains
- Sam Should we move everything into one big repository so the agents work better?
- Priya Maybe, but not first. The same model does far better in a repository where instructions sit next to the code, one command runs the right tests, and the build can tell you what depends on what. Those standards help in any layout. Then come the big choices: one repository or many, and which build system.
- Priya Imagine a contractor arriving at a building site. One site has a map, a labelled cabinet for each trade, and a board showing which rooms depend on which pipes. On the other, each trade has its own yard across town and the pipe plan lives in someone's head. Same contractor, very different results.
- Sam So the map is what matters?
- Priya One writer put it well: what matters is whether your dependency graph is declared to a machine or remembered by people. An agent can query a machine. It can't query your senior engineer's memory.
- Sam What are the standards?
- Priya A short root AGENTS.md, and one per package with its own build and test commands; agents read the nearest file. Copilot also reads path-specific instruction files. The environment preinstalled, for example with copilot-setup-steps or a dev container. One command to check a change, scoped to what changed, because a full test suite in a big repository times out. CODEOWNERS, branch rules and a pull request template. And generated and vendored code kept out of the agent's way.
- Sam Now show me monorepo versus polyrepo.
- Priya Say an agent changes how a shared money library rounds amounts. In a monorepo with a build graph, it asks the build which projects depend on the library, gets three, runs just their tests, finds one failing, fixes it, and ships everything in one pull request. In a polyrepo, it releases the library, then has to find the consumers, then opens a pull request in each and merges them in order.
- Priya Your turn. Does that mean a monorepo always wins?
- Priya No. A polyrepo with versioned contracts, automated dependency bumps and cross-repo search works well. A monorepo with one giant instruction file and a forty-five minute test suite works badly.
- Sam What's on the page to try?
- Priya An advisor: five questions about your teams, coupling, languages, releases and platform team, and it recommends a layout and a build system with its reasons. And a ten-point checklist to score how agent-ready your repository is.
- Sam Pros and cons, briefly?
- Priya Monorepo: the agent sees every consumer, one atomic change, one set of instructions and checks. But it needs scoping and build investment. Polyrepo: small focused repositories, independent releases and permissions. But the agent can't see consumers, and cross-cutting changes become several pull requests. The evidence comes mostly from vendors on both sides, so measure your own pain first.
- Sam And build systems?
- Priya Native tools like npm, Gradle, Go and Cargo: agents know them best, but there's no cross-project graph. Nx and Turborepo add a graph, affected-only tasks and caching on top, mainly for JavaScript and TypeScript. Bazel and Buck2 are unified and hermetic: the agent's result matches CI, and you can query exactly what depends on what. The cost is BUILD files the agent must keep correct, and a platform team. Pants infers most dependencies, which suits Python. And CMake generates C and C++ builds, but it isn't a monorepo orchestrator.
- Sam What about each tool?
- Priya Claude Code layers CLAUDE.md per directory, can exclude other teams' files, make sparse worktrees, and add sibling repositories with add-dir. Copilot reads AGENTS.md at any level plus path-specific instructions, and its cloud agent can span several repositories in an organisation. Codex merges AGENTS.md down the folder tree. Cursor's cloud agents can open pull requests across repositories. Antigravity reads AGENTS.md or GEMINI.md per folder.
- Sam The memory hook?
- Priya Give the agent the map, not just the maze.
- Sam Common mistakes?
- Priya One giant root instruction file. Telling the agent to run all the tests. No environment setup. Letting it read generated code. Polyrepos without contracts. Adopting Bazel for agents alone. And copying standards by hand across many repositories.
- Sam And the lab?
- Priya Score your repository, split the instructions per package, add environment setup, and try your build tool's affected command on a shared library. Run one cross-project task scoped and unscoped, and write down, with evidence, whether your layout is really holding agents back.
1. The idea
A new contractor arrives at a large building site. On one site there's a site map, a labelled cabinet for each trade, and a board that says which rooms depend on which pipes. On another, each trade has its own locked yard across town, and the pipe plan lives in someone's head. The contractor is equally skilled in both, but only one site lets them work out what their change will affect before they start digging.
Three decisions shape how well agents work in your code:
| Decision | Options | What it changes for an agent |
|---|---|---|
| Repository standards | Instructions, setup, one-command checks, ownership rules | Whether the agent can start, build, test and follow your conventions without guessing. Matters in every layout. |
| Repository layout | Monorepo (all projects in one repository), polyrepo (one repository per service or module), or a hybrid | What the agent can see and change in one session, and whether a cross-project change is one pull request or several. |
| Build system | Native per-language tools (npm/pnpm, Gradle, Maven, Go, Cargo, CMake), monorepo task runners (Nx, Turborepo), or unified build systems (Bazel, Buck2, Pants) | How fast and reliable the agent's checks are, and whether it can ask the build "what does this change affect?". |
One idea links all three, put well by Daniel Westgaard: what matters is "whether your dependency graph is declared to a machine or remembered by people." An agent can query a machine. It can't query your senior engineer's memory.
2. How it works
The repository standards every agent benefits from
These come from GitHub's guidance for Copilot's cloud agent, the AGENTS.md standard and Claude Code's large-codebase guide. They work with every tool, whatever your layout:
The same change, two layouts
An agent must change how a shared money-formatting library rounds amounts. Three services use it. Watch it in a monorepo with a build graph, and in a polyrepo.
What the agent can ask each build system
3. Try it yourself
Which layout and build system fit you?
Answer five questions about your organisation. The recommendation explains its reasoning; there's no single right answer for everyone.
How agent-ready is your repository?
Tick what your repository already has.
4. Why it matters at work
Monorepo, polyrepo or hybrid: pros and cons with agents
| Layout | Pros for agents | Cons for agents |
|---|---|---|
| Monorepo | Sees every consumer of a change; one atomic pull request across projects; one continuous context instead of a reset at each repository boundary; one set of instructions, skills and checks; build tools that answer "what depends on this?" | Huge trees fill the context unless scoped (nested instructions, sparse checkouts, excluded generated code); full test suites time out unless tests are scoped to affected projects; needs build infrastructure and shared standards; infrastructure code often still lives elsewhere |
| Polyrepo | Small, focused repositories are easy for an agent to understand; independent CI, releases and permissions; mixed stacks coexist; a mistake's blast radius is one repository | The agent can't see who consumes its change; cross-cutting changes become several PRs that must merge in order; versions drift between repositories; standards must be copied into every repository; some agent modes are limited to one repository per task |
| Hybrid | A monorepo per product or domain, with stable contracts (OpenAPI, protobuf) between them; or a "synthetic monorepo" layer that maps dependencies across repositories | More moving parts; cross-repository changes stay non-atomic ("eventually consistent", in Nx's words about its own Polygraph tool) |
Evidence is thin and mostly from vendors. Nx (which sells monorepo tools) argues agents hit read, write and memory limits in polyrepos, and cites Airbnb compressing an 18-month migration into 6 weeks with agents in a monorepo. Riftmap (which sells cross-repository graphs) argues the real variable is a queryable dependency graph, which a polyrepo can have too, and cites data showing more variable pull-request cycle times in monorepos. No independent comparison exists yet. Both agree on the essential point: agents need to know what a change affects.
Build systems: pros and cons with agents
| Build system | What it is | Pros for agents | Cons for agents | Best for |
|---|---|---|---|---|
| Native tools (npm/pnpm workspaces, Gradle, Maven, Go modules, Cargo workspaces) | Each language's standard build and package tools | Agents know them extremely well from training data; no new language; easy for every contributor | No cross-language graph; "what's affected?" needs extra tooling; tests often run whole packages or the whole repository; caching is per tool | Polyrepos, and small or single-language monorepos |
| Nx, Turborepo | Task runners layered on top of native tools, mainly for JavaScript/TypeScript monorepos (Nx also supports other languages via plugins) | Keep native tools; add a project graph, affected-only tasks and local/remote caching; Nx ships an MCP server and agent-oriented CI features; Turborepo describes itself as "the build system for coding agents" | Graph quality depends on declared dependencies; not hermetic like Bazel; another config layer to keep correct | JS/TS monorepos of any size |
| Bazel | Open-source, multi-language build system; targets declared in BUILD files written in Starlark | Hermetic, sandboxed builds give the same result in the agent's sandbox and in CI; rebuilds only what changed; bazel query answers "what depends on this?"; remote caching and execution; proven above 100,000 source files | BUILD files are another language the agent must write correctly, and a new failure mode; steep setup and migration; needs dedicated build engineers | Large polyglot monorepos (C++, Java, Go, mobile) with a platform team |
| Buck2 | Meta's rewrite of Buck, written in Rust, open source since 2023 | One incremental graph; remote execution built in; rules in Starlark; about 2× faster than Buck1 in Meta's tests; composes many languages in one build | Smaller community and ecosystem than Bazel; same BUILD-file burden; fewer examples in agents' training data | Very large polyglot monorepos willing to adopt early |
| Pants | Build system focused on Python, Go, Java, Scala, Kotlin, Shell and Docker | Infers most dependencies from imports, so little BUILD-file boilerplate for agents to maintain; runs only tests affected by a change | Narrower language set; smaller community | Python-heavy or mixed Python/Go/JVM monorepos |
| CMake | Kitware's build-system generator for C and C++: it writes the native build files (for example for Ninja or Make), which then build the code | The C/C++ standard, so agents know it well; works with IDEs and language servers through generated compile commands | Not a monorepo orchestrator: no affected-project queries or remote cache of its own; large CMake trees are hard for agents to reason about | C/C++ projects; at monorepo scale, often paired with or replaced by Bazel or Buck2 |
What to choose, by situation
| Situation | Recommended |
|---|---|
| One product, one or a few teams, mostly one language | Monorepo with native workspaces; add Nx or Turborepo (JS/TS) when CI gets slow |
| Frontend and backend that change together | Monorepo, so one agent can change the API and its callers in one pull request |
| Many teams, polyglot, very large, with a platform team | Monorepo with Bazel (or Buck2), remote caching and execution |
| Python-heavy monorepo | Pants, or native tools plus a task runner |
| C/C++ product | CMake with Ninja; consider Bazel only when scale and many languages demand it |
| Independent services owned by separate teams, different release cycles, strict access boundaries | Polyrepo with shared contracts, a template repository for AGENTS.md and checks, and cross-repository search for agents |
If you keep separate repositories
- One template: a template repository with AGENTS.md, the check script, CI, CODEOWNERS and the PR template, so every repository starts agent-ready.
- Contracts as the interface: OpenAPI, protobuf or JSON Schema in a contracts repository, versioned; agents change the contract first, then each consumer.
- Shared skills as a plugin (Module 12), instead of copying skills into each repository.
- Cross-repository context: a code-search MCP server, or a tool that can open several repositories in one session (section 5).
- Automated dependency updates (Dependabot or Renovate), so version drift doesn't build up silently.
The honest caveatsMost claims about repository layout and agents come from vendors with a product to sell, on both sides. Moving to a monorepo or to Bazel is a large, multi-month investment with its own risks; don't migrate for agents alone. Start with the standards in section 2, which help in any layout, and measure where your agents actually struggle (Module 21a) before changing structure.
5. In your five tools
How each tool handles monorepos and multiple repositories. Checked 31 October 2026.
| Tool | In a monorepo | Across several repositories |
|---|---|---|
| Claude Code | Root and per-directory CLAUDE.md (subdirectory files load on demand); claudeMdExcludes for other teams' packages; Read deny rules for generated and vendored code; worktree.sparsePaths for sparse worktrees; code intelligence plugins for symbol lookups; per-package skills | --add-dir or additionalDirectories to open sibling checkouts; projects coordinate several cloud sessions across repositories |
| GitHub Copilot | AGENTS.md at any level; .github/copilot-instructions.md; path-specific .github/instructions/*.instructions.md with applyTo globs; copilot-setup-steps.yml preinstalls dependencies | The cloud agent in a cloud sandbox can span several repositories in one organisation; in GitHub Actions mode it is limited to one repository |
| Codex CLI | AGENTS.md merged from the root down to the working folder; AGENTS.override.md takes precedence in its folder; combined files capped at 32 KiB by default | Codex cloud environments are set up from the repositories you choose; locally, run a session per checkout and coordinate through contracts |
| Cursor | Nested AGENTS.md and .cursor/rules/*.mdc with file globs; environment in .cursor/environment.json | Cloud agents can work across several repositories and open a PR in each |
| Antigravity CLI | AGENTS.md or GEMINI.md per folder; .agents/rules/*.md with a glob mode | Subagents can work in separate git worktrees; open other repositories in their own sessions |
6. Remember it
Memory hook: "Give the agent the map, not just the maze"Whatever the layout, the agent needs instructions next to the code, one command to check its work, and a dependency graph it can query.
How this hook works: what “Give the agent the map, not just the maze” means
What the slogan means, phrase by phrase
- “the map”
- Nested AGENTS.md files, a queryable build graph, code intelligence, CODEOWNERS: things that tell the agent where it is and what depends on what.
- “not just the maze”
- Access to files alone. An agent that can open everything but can't ask what depends on what explores, guesses and burns tokens.
Why this picture fits: a monorepo without a graph is a bigger maze; a polyrepo with a parsed dependency graph has a map. The layout matters less than the map.
The story → the concept
| Building site | Repository |
|---|---|
| Site rules at the gate, trade notes at each cabinet | Root and nested AGENTS.md |
| Tools laid out before work starts | Setup script, dev container, copilot-setup-steps.yml |
| The pipe board | The build graph (Nx, Bazel, Pants…) |
| One shared site | Monorepo |
| Separate yards across town | Polyrepo |
| Who signs off each room | CODEOWNERS |
The trap it saves you from
Migrating to a monorepo and expecting agents to improve on their own. Without scoped instructions, scoped tests and a graph, a bigger repository just gives the agent more to read.
7. Common mistakes
One giant root instruction fileEvery package's conventions in one file: the agent loads all of it for every task. Use a short root file plus one per package.
"Run all the tests"In a big repository the full suite times out. Give per-package or affected-only test commands.
No environment setupAgents that discover dependencies by trial and error waste their session. Preinstall them.
Letting the agent read generated and vendored codeIt fills the context with code nobody edits. Deny those paths.
Polyrepos without contractsAn agent changing one service can't see its consumers. Make the interface explicit and versioned.
Adopting Bazel for agents aloneIt's a large investment; its payoff is speed, hermeticity and graph queries at scale, not a better agent in a small repository.
Copying standards by hand across many repositoriesThey drift within months. Use a template repository and a shared plugin.
8. Hands-on lab (roadmap week 9)
- Score your repository with the checklist above and fix the two cheapest gaps.
- Split the instructions: a short root AGENTS.md, and one per package or major folder with its own build and test commands.
- Add environment setup: a setup script or dev container, and
copilot-setup-steps.ymlif you use Copilot's cloud agent. - Make "what's affected?" answerable: try your build tool's affected or query command on a shared library. If you have none, note what an agent would need to find the consumers.
- Run the same cross-project task twice: once with the agent scoped to one package, once with the consumers available. Compare the result.
- Decide: write down whether your layout and build system are holding agents back, with evidence, before proposing any migration.
9. Self-check quiz
A monorepo has AGENTS.md at the root and in packages/api/. Which instructions win for a file in packages/api/?
The AGENTS.md standard: the nearest file takes precedence; explicit prompts override everything.
Whatever the layout, what most helps an agent judge a change's blast radius?
Monorepo build tools give you one as a side effect; polyrepos need contracts or a parsed cross-repository graph.
What does a monorepo give an agent changing a shared library that a polyrepo doesn't?
In a polyrepo it's a library release plus a PR per consumer, merged in order.
Which Bazel property helps agents most?
Plus caching and graph queries. The cost: BUILD files the agent must keep correct.
What is CMake?
It generates native build files; affected-project queries and remote caching need other tools.
Your agents struggle in your polyrepo estate. First step?
Instructions, setup, checks and contracts help in any layout; migrations are big bets that need evidence.
10. Go deeper
| Resource | Time | Why |
|---|---|---|
| Set up Claude Code in a monorepo or large codebase (Claude Code docs) | 20 min | Nested instructions, exclusions, sparse worktrees, code intelligence, per-package skills. |
| Get the best results from Copilot cloud agent (GitHub Docs) | 15 min | Instructions files, copilot-setup-steps.yml, task scoping. |
| AGENTS.md (Agentic AI Foundation) | 5 min | The open format, its sections, and nested files in monorepos. |
| How Claude Code works in large codebases (Anthropic) | 15 min | Scoped test commands, LSP, ownership of the agent setup. |
| The monorepo advantage for AI agents (Victor Savkin, Nx, July 2026) and Monorepo vs polyrepo: the debate is measuring the wrong thing (Daniel Westgaard, Riftmap, June 2026) | 25 min | The two sides, each from a vendor with a stake. |
| Code intelligence as agentic tooling (Thoughtworks Radar, April 2026) | 3 min | Why agents should use language servers and codemods, not just text search. |
| Bazel, Buck2, Pants, Turborepo, CMake | 30 min | Each build system in its own words. |