What Makes a Codebase Easy for AI Coding Agents to Work In

An agent that breezes through a task on a sample project can stall on the same kind of task in your repository, and the model did not get worse between the two runs. What changed is how much work it takes to find the right place to edit and how expensive it is to confirm the edit was right. Those two costs depend heavily on the repository, not only on the agent, and the repository is the part you can change.

A substantial share of cost goes into orientation

Dosu replayed 60 pull requests from the cal.diy repository across 112 agent sessions, running Claude Code on Opus 4.8 and Codex on GPT-5.5. Planning and gathering context took 67% of the dollars and 65% of the active time. Writing code, including the build and test commands around it, was 26% of the dollars. Claude Code pushed 185M tokens through its context window to produce 0.94M tokens of output, roughly 198 tokens read for every one written.

A second replay of 49 pull requests from vercel/ai, on Opus 5.5 and GPT 6.1 Sol, split each session at the first detected file edit. Decant attributed 40.8% of Claude Code's cost estimate and 31.8% of Codex's to the stretch before that edit.

Both are cost measurements on replayed public tickets, not correctness benchmarks, and neither establishes a rate for your repository. In the cal.diy replay, Claude Code's average run grew 4.5 times from self-contained tasks to cross-cutting ones, from $1.11 to $4.96, while the share spent orienting stayed near 44%. Cross-cutting tasks cost more in this sample. The study did not independently control diff size and comprehension scope.

What turns one question into twenty file reads

Three conditions do most of the damage, and they show up in session logs before they show up in a bill.

Two plausible homes for the same change. A duplicated module, a legacy handler that still compiles next to its replacement, or a utility that exists in three packages all force the agent to read both paths and guess. It often guesses correctly, after paying to look.

Conventions that live in people's heads. Which directory new handlers go in, which of two test commands is the real one, which deprecated helper you are migrating away from. An agent cannot read any of that from the code, so it infers a convention from whatever it happens to open first.

Verification that costs more than the edit. When the only way to check a change is a fifteen-minute suite, the agent waits, or skips the check, or runs it and gets an intermittent failure it cannot attribute to its own work. A flaky test is worse than a slow one, because the agent cannot tell a real regression from noise and will often re-investigate code that was never broken.

Close the information gap before you reorganize anything

Order the fixes by what they cost to make, not by how satisfying they are. Instructions and commands are cheap and land this week. Restructuring modules is expensive and should wait until session logs say the structure is what is costing you.

Write down what the code cannot reveal. An AGENTS.md or CLAUDE.md earns its place by answering the questions an agent would otherwise pay to investigate: where new code belongs, which command verifies a change, which pattern is current and which is being retired. Keep out anything the agent can derive by reading the repository. Claude Code's own guidance is to keep each file under 200 lines, because longer files consume more context and reduce adherence, and to write instructions concrete enough to check. "Use 2-space indentation" gives an agent something to comply with. "Format code properly" does not.

Treat the file as an experiment rather than a guaranteed saving. A 2026 study by ETH Zurich and LogicStar, Evaluating AGENTS.md, compared agents working with generated context files, developer-written ones, and none at all. In the settings it tested, context files raised inference cost by more than 20% on average without a statistically significant gain in task success, and repository overviews in particular added little. The study supports avoiding redundant overviews, but does not establish that a short file containing a test command and a directory rule saves money. Treat that narrower file as a hypothesis and measure it on your own tasks.

Make a clean checkout work in one command. make bootstrap or the equivalent, with pinned dependencies, example environment values, and a non-zero exit when it fails. Then put routine work behind named commands such as make test-unit and make typecheck, and have CI call those same commands. Test it somewhere disposable. A laptop with cached credentials and a database already running will hide the step that blocks every fresh agent session.

Give the agent a check it can afford to run. Three tiers work well: a changed-files lint and format pass, a package-scoped test command, and the full suite as a separate thing nobody runs per edit. Time each one in your repository and make failure output name the test and the expected value. Then fix the intermittent failures. Unstable fixtures, live network calls, and shared state between tests convert every agent run into a debugging session about your test suite.

Encode boundaries as checks, not prose. If billing/domain must not import billing/infrastructure, an import linter in CI tells the agent exactly what it broke, at the moment it broke it. The same rule written as a paragraph in an instruction file is something the agent has to remember and you have to keep true.

Delete the path production does not use. Trace callers and tests first, then remove the dead implementation and update the references. This is the expensive item on the list, which is why it belongs at the bottom, but it is the only one that removes the ambiguity permanently for every later task in that area.

Writing for agents is mostly writing for humans

The question keeps coming up as if the two goals diverge. For the most part they do not. Clear names, focused modules, and one obvious home for each behavior reduce the search for a new engineer and for an agent, for the same reason in both cases.

Where they differ is in what carries a rule. A test that fails on a crossed module boundary gives an agent an unambiguous result it can act on in the same session. A comment asking the reader to keep billing separate depends on the agent reading that file, interpreting it the way you meant, and the comment still being true. Comments remain the right place for intent a check cannot express, such as why an external API needs an unusual retry.

What does not follow is a separate house style for machines. There is no good evidence that agents want longer functions or denser files, and changing repository-wide conventions on that theory costs you the human readers you still have. If you add machine-checkable boundaries, compare completed tasks on similar work before deciding they helped.

A stale instruction file is worse than a missing one

With no instruction file, an agent reads the code. With a file that names a renamed test command, it confidently runs the wrong thing, because the file reads as authoritative and the code does not contradict it directly.

The cheapest fix is a trigger rather than a calendar. Review the instruction file in the same pull request that renames a command, moves a directory, or settles a convention. Claude Code can also audit the files for you: /doctor prompt-audit checks instruction files for outdated or contradictory content and references to commands that no longer exist, reports what it found with proposed edits, and changes nothing until you ask it to. It requires Claude Code v2.1.283 or later.

Monorepos need the check one level down too. Claude Code loads a subdirectory's instruction file when it opens a file in that directory, so a nested file can keep naming a command that the root file stopped using months ago. If you want the full comparison of what keeps these files true as code moves, we wrote one in Best Tools to Keep AGENTS.md Files Up to Date.

Compare completed tasks, not cheaper sessions

A repository change is worth keeping if the agent finishes comparable work with less searching. That is not the same as a smaller bill. A session that costs half as much and leaves the task unfinished is a worse outcome wearing a better number.

So hold the agent, the model, and the task mix steady across the comparison, and report the sample size, the repository revision, and the failed attempts next to every figure. Mark the first file edit in each session and use that marker consistently, which separates the search from the implementation. Then count tokens and turns per completed task, and score completion as its own column.

The signals worth watching in the logs are repeated reads of the same file, searches that return to a path the agent already abandoned, and edits that get reverted a few turns later. Each one is the agent paying twice for the same understanding.

Decant is the open source tool Dosu used for both replays above, and it runs entirely on your machine. You can install Decant and start its web UI with npm i -g @dosu/decant@latest && decant. If you want to drill deeper, decant sync indexes sessions from Claude Code, Codex, Gemini CLI, and OpenCode, decant economics gives the token, cost, and time breakdown, and decant stats --by model rolls it up per model. It makes no outbound network calls at runtime, but it does keep an unencrypted SQLite archive at ~/.decant/decant.db holding prompts and tool output, which can include source code and anything pasted into a session. Check that against your retention policy before you run it on a work machine. For how session logs compare with the other places an agent run gets recorded, see Best Tools for Coding Agent Observability.

FAQ

Should AGENTS.md and CLAUDE.md both exist in the same repo?

One maintained file is easier to keep accurate than two that drift apart. On Claude Code v2.1.277 or later, default AGENTS.md loading requires no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or its ancestors. If you keep both, put an @AGENTS.md import in CLAUDE.md rather than merely mentioning the file. Check which instructions loaded before relying on them.

How long should an instruction file be?

Short enough that every line answers something the agent cannot work out from the code. Claude Code recommends staying under 200 lines per file, because longer files consume more context and reduce how reliably the instructions are followed. Commands, directory rules, and exceptions earn their place. Architecture overviews usually do not, since the agent can read the architecture.

What is the fastest first change in a large legacy repo?

Write down the setup command that works on a clean checkout, the scoped test command, and the one convention agents get wrong most often. It takes an afternoon, requires no restructuring, and the next few sessions will show you whether those three lines removed questions the agent used to investigate.

Does a bigger context window fix exploration overhead?

A bigger window raises the ceiling on what an agent can hold, but it does not tell the agent which files matter. In the replays above, planning and context gathering were where the dollars went, and neither study tested the context window as the limiting factor. Clear names, current instructions, and scoped checks reduce the searching itself.

How do you tell a flaky test from a real regression in an agent run?

A changing result establishes intermittency, not its cause. Compare repeated runs on the base and changed commits with the same setup and inputs, then investigate change-specific races alongside fixtures, network calls, clocks, and shared state. Use that evidence to decide what needs fixing rather than treating an intermittent failure as harmless noise.

Get a baseline before you change anything

Pick the repository where your agents feel slowest, run npx @dosu/decant@latest against your own session logs, and write down the orienting share, the tokens per completed task, and the files the agent keeps re-reading. That list is your actual backlog, and it is usually shorter and more specific than a general cleanup plan.

Look in that list for context your team has already worked out once. Connect the repository to Dosu, then set up the Dosu MCP server with npx @dosu/cli setup so your agents can call read_knowledge before they start searching and write_knowledge when they work something out. Then compare matched completed tasks before and after.