Repo layout, CLI-first tooling, and AGENTS.md/CLAUDE.md conventions all decide how well AI coding agents work, and what a merge gate can catch.
Four structural choices do most of the work: how the repository is split, one monorepo or many small repos, whether the tools an agent can call are stateless and scriptable or stateful and interactive, whether a convention file gives the agent context that survives between sessions, and whether module boundaries keep a single task's diff inside a bounded, reviewable area. Each affects a different failure mode, and none of them is optional just because the workflow on top is solid.
Codebase structure is the part of agentic coding that workflow advice cannot fix. How to do agentic coding covers the process layer: writing a spec before code, giving the agent a tight feedback loop, reviewing diffs instead of prompts. None of that changes what happens when the repository itself works against the agent: a change that should touch one file instead touches nine, a tool the agent needs returns nothing it can parse, or the file meant to carry project context sits three directories away from where the agent is looking. This is the structural layer underneath the workflow, and it decides how much of that workflow advice actually pays off.
Monorepo or many small repos: the real tradeoff
A monorepo's advantage for an agent is not tidiness. It is that everything the agent might need to read to trace a change sits inside one context window instead of behind a repo switch. Nx, which builds monorepo tooling, argues that an agent working across service boundaries in a single repo can trace a change from a frontend action through an API call to a database update without losing context, and reports a side-by-side test where an agent working in an Nx monorepo finished cross-project work four times faster than an equivalent polyrepo setup.
Sources: Nx: The Monorepo Advantage for AI Agents
That is a vendor making the case for its own category, and the counter-argument is worth taking seriously: the real variable is not where code lives but whether dependency relationships are queryable by a machine. Riftmap's analysis of the debate points out that a monorepo's genuine advantage comes from build systems like Bazel or Nx maintaining a live graph of what depends on what, information a polyrepo scatters across manifests that no single tool reads. By that logic, a polyrepo paired with a tool that parses those manifests into one graph can recover most of the benefit without merging any repositories at all.
Sources: Riftmap: the monorepo vs polyrepo debate
Stripe's own numbers cut against a simple "bigger repo is better" reading too. Stripe runs its autonomous coding agents, called Minions, against a backend of hundreds of millions of lines spread across a handful of large repositories, and still found that raw visibility was not enough on its own: almost all of its agent rules are applied conditionally per subdirectory rather than as one flat file, and agents reach roughly 400 internal tools through a dedicated internal platform instead of one undifferentiated toolset. The repository being large did not make the agents reliable by itself. Scoping what applies where, inside that repository, did.
Sources: Stripe: Minions, Stripe's one-shot, end-to-end coding agents
A monorepo hands an agent more to see. It still has to be told which parts of what it sees apply to the file it is actually editing.
Stateless, CLI-first tools an agent can actually call
The tools that work best for an agent behave identically on every call: structured, parseable output, no prompt waiting on stdin partway through, and no hidden session state the agent has to track between invocations. Anthropic's own guidance for building tools that agents call frames the same requirement from the other side: tools are contracts between a deterministic system and a non-deterministic caller, and a tool that returns raw technical identifiers or ambiguous parameters gets misused in ways a human user rarely would. A command-line tool that is stateless by construction removes an entire category of that misuse before it can happen.
Sources: Anthropic Engineering: Writing effective tools for AI agents
The cost of getting this wrong shows up directly in token spend. One documented comparison of a device-compliance task found a Model Context Protocol based approach consuming roughly 145,000 tokens against about 4,150 tokens for an equivalent CLI-based approach, a difference of roughly 35 times for the same underlying job. The gap was not the protocol itself. It was that the MCP server exposed broad, stateful session behavior where the task only needed a narrow, repeatable command.
Sources: Why CLI Tools Are Beating MCP for AI Agents
Same task, two integration styles: roughly 4,150 tokens through a CLI versus roughly 145,000 through an MCP server. The protocol was not the problem. The stateful session it carried was.
In practice, an agent-composable command has a short list of traits worth checking for before wiring it up.
- Structured output, JSON or plain parseable text, instead of a rendered UI or a table meant for human eyes
- No interactive prompts mid-command; every required input arrives as a flag or an argument
- Idempotent behavior, so calling it twice with the same input is safe
- A dry-run or plan mode the agent can call before the command that actually changes something
Stripe caps its Minions at two rounds of CI per task and keeps local linting under five seconds, on the reasoning that a slow, stateful feedback loop has diminishing returns for an agent past a couple of iterations. Design the fast, deterministic layer first, and let the agent loop there before it ever touches something stateful.
AGENTS.md and CLAUDE.md carry context, they do not create it
AGENTS.md and CLAUDE.md are plain markdown files at a repository's root that an agent reads automatically before doing anything else, and their job is to stop project context that would otherwise live only in a senior engineer's head from being re-explained every session. AGENTS.md came out of OpenAI Codex, Cursor, Google's Jules, Amp, and Factory converging on one format instead of shipping five incompatible ones, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation rather than by any single vendor. It is reportedly in use across more than 60,000 open-source repositories.
Sources: AGENTS.md specification
CLAUDE.md is Claude Code's own version of the same idea, read at the start of every session. Anthropic's guidance for writing one is specific: start simple and expand only from actual friction in your workflow, and keep the file concise, since every line in it is context spent on every single session whether or not that session needs it. The "/init" command generates a starting file by reading the project directly, which matters structurally, because a file an agent can regenerate from the repository is a file that can be checked against the repository.
Sources: Anthropic: Using CLAUDE.md files
The evidence on how much these files help is more modest than the enthusiasm around them. An evaluation of AGENTS.md across several models on SWE-bench found that the file's presence produced inconsistent results: gains were often small, single-digit percentage points, and sometimes there was no measurable improvement at all depending on the model. The file is not a performance lever by itself. It only pays off when what it claims about the codebase is true and specific enough for the agent to act on.
Sources: Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
In practice, a convention file earns its keep when it ties to structure rather than aspiration.
- The exact commands to build, test, and lint, not a description of them
- Conventions scoped to a subdirectory where they genuinely differ, the way Stripe applies rules conditionally per path instead of one flat file for a huge codebase
- Explicit boundaries: which directories or modules a given task should never touch
- A pointer to where specs or design docs live, so the file stays a map rather than a duplicate of the documentation
A file that says all of this and is still ignored is a separate, more common failure than not having one at all; why your CLAUDE.md gets ignored covers what causes that drift and how to catch it.
How module boundaries decide what a reviewer or merge gate can catch
Review quality falls off once a diff passes a certain size, and this was measured long before coding agents existed. A widely cited SmartBear study of code review at Cisco Systems, covering roughly 2,500 reviews and 3.2 million lines of code, found that reviews under 200 lines caught defects at several times the rate of larger ones, and recommended capping a single review at 200 to 400 lines to keep that detection rate up. Agents do not break this finding; they just make it come up more often, because an agent will produce a 900-line diff without hesitation if nothing about the codebase stops it from touching that much at once.
Sources: SmartBear: Best Practices for Code Review
Codebase structure is what decides whether that stop exists. A task scoped to a single-responsibility module with a clear boundary has nowhere sensible to spread: the agent's diff for "add a rate limiter" stays inside the rate limiter. A codebase where a shared utility file is imported by forty unrelated features turns that same task into a diff that ripples outward regardless of how narrow the request was, because touching the shared file is the only way to satisfy it. The size problem people blame on agents is frequently a boundary problem the codebase already had.
| Structural pattern | Typical agent diff | Effect on the merge gate |
|---|---|---|
| Shared modules, no ownership boundary | Touches many unrelated files for one requested change | Reviewer cannot isolate risk; defect-detection drops as diff size grows |
| Bounded, single-responsibility modules | Stays inside the module the task named | Review scope matches task scope; findings trace back to intent |
| Monorepo, no directory-scoped conventions | Agent sees everything and applies the same rules everywhere | Same file-count risk as unbounded modules, just with more visible context |
| Monorepo with directory-scoped AGENTS.md/CLAUDE.md rules | Agent applies only the conventions relevant to the touched path | Expectations are legible per directory, closer to how Stripe scopes its Minions |
None of these four rows require a new tool. They describe how the same repository behaves depending on whether module boundaries and convention files were drawn with an agent's diff in mind, or drawn for a human who was always going to read the whole file anyway.
Where structure stops and review has to start
Good structure changes what has to be reviewed, not whether it has to be. A bounded diff from a well-organized repository is smaller and easier to reason about than an unbounded one, but it is still a diff an agent wrote without the judgment a human brings to their own code, and someone or something still has to check it before it merges.
This is the layer TLM Forge works at, rather than the one this post has been about: it does not restructure a repository. It sits at the point where a diff, however well-scoped, is about to become permanent. A spec and a goal contract get signed off before code exists, a threat-modeler and a red-team reviewer look at the design and the diff in fresh context instead of defending the agent's own reasoning, and a scored gate blocks the merge until every unresolved critical issue is gone, and the team behind it enforces test-driven development so a passing suite is something a reviewer can rerun, not just take on faith. Structure and enforcement solve different problems. A repository organized the way this post describes just hands that gate a smaller, clearer diff to score.
Frequently asked questions
01Does a monorepo automatically make AI coding agents work better?
No. A monorepo gives an agent visibility across services without switching context, but Stripe and others still add directory-scoped rules on top of a single repo, because raw visibility does not tell an agent which conventions apply to the file it is editing.
02Do I need both an AGENTS.md and a CLAUDE.md file?
Not necessarily. AGENTS.md is a vendor-neutral standard several agent tools read; CLAUDE.md is Claude Code's own convention. Many teams keep a CLAUDE.md that mirrors AGENTS.md content so one file stays authoritative and the other stays current.
03Why do coding agents work better with CLI tools than with interactive apps?
A CLI command returns the same structured output every time and never waits on a prompt an agent cannot answer. Interactive or stateful tools require the agent to track session state across calls, which is exactly where reliability breaks down.
04How small should a module be for an AI agent to edit safely?
There is no fixed line count. The useful test is whether a task scoped to that module can be described, edited, and reviewed without touching unrelated files. If a small change routinely ripples into a dozen files, the module boundary is wrong, not the agent.
05Does good codebase structure remove the need for code review on AI-generated diffs?
No. Structure changes the size and clarity of what has to be reviewed, not whether review is needed. A well-bounded diff is easier for a human or a merge gate to check thoroughly; it is not a substitute for checking it.