How to Work With an AI Coding Agent in a Codebase Too Big to Explain

Agents get worse on large repos because retrieval degrades faster than reasoning does. The model plans against whatever files it happened to find, and in a big tree that is a small and often unrepresentative slice. "A model can only reason about code it can see. If the agent searches the local working directory and finds three relevant files, it plans on three files." - Matt Tanner, Sourcegraph, 21 May 2026. The agent is not confused. It is confidently working from a partial picture, which is why the output looks correct and breaks at a call site nobody opened. There is measured evidence this bites hardest in exactly the repos most professionals work in. METR's randomised controlled trial, published 10 July 2025, put 16 experienced open-source developers through 246 real issues on repositories averaging more than 22,000 GitHub stars and over 1 million lines of code. Developers using AI tools took 19 per cent longer, despite believing they had been sped up. METR points at codebase maturity: high quality standards and many implicit requirements that take humans years to absorb. Winnie, another buildDay registrant, described the symptom from the driver's seat: "I find Codex tends to drift in context during a long and sideways convo/multi-step edits." Drift is what partial retrieval looks like over time.

Put in the things the agent cannot derive by reading the code: build and test commands, the repository layout in one paragraph, conventions that differ from tool defaults, and the traps that have already burned someone. Leave out anything the agent can work out from the files themselves. Anthropic's Claude Code documentation gives a hard number: target under 200 lines per CLAUDE.md file, because "Longer files consume more context and reduce adherence." The file loads at the start of every session, so every line you add is a line you pay for on every task forever. Claude Code's `/doctor` checkup now proposes trims, cutting directory layouts and dependency lists Claude can derive and keeping pitfalls, rationale and conventions. AGENTS.md is the cross-tool version of the same idea. The agents.md specification is stewarded by the Agentic AI Foundation under the Linux Foundation, is used by more than 60,000 open-source projects, and is read by over 20 agents including Codex, Cursor, Gemini CLI, Jules, Zed and Windsurf. One detail people get wrong: Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already has AGENTS.md, do not duplicate it. Create a CLAUDE.md whose first line is `@AGENTS.md`, then add Claude-specific rules under it. A symlink (`ln -s AGENTS.md CLAUDE.md`) works too. Run `/context` in your next session and confirm CLAUDE.md appears under Memory files. If it is not listed, the agent never read it. "My recommendation would be to build context like rules files up gradually, and not pump too much stuff in there right from the start." - Birgitta Boeckeler, Technical Principal at Thoughtworks, martinfowler.com, 5 February 2026. Add a line when the agent makes the same mistake twice, not in advance.

Write a short orientation paragraph at the top of the root instruction file that names each major directory and what lives there, then push the detail into per-directory files that load only when the agent works in that area. Anthropic's monorepo guidance recommends a two-level split: a root CLAUDE.md for repository-wide rules and layout, and a per-subdirectory CLAUDE.md for that area's stack. Their example root file is five lines long and does nothing but name three packages and their tech. That is the whole map. Claude Code loads your working directory's file and every parent's at launch, then loads subdirectory files on demand, so detail arrives only when it is relevant. The alternative is a generated map. Aider has shipped a repository map since 22 October 2023: it uses tree-sitter to extract symbol definitions across the repo, ranks them with a graph algorithm, and fits the result into a budget set by `--map-tokens`, which defaults to 1,024 tokens. One thousand tokens of ranked symbols beats fifty thousand tokens of file dumps. The agent needs a table of contents, not the book. Keep the map current or it becomes a liability. Anthropic's Applied AI team recommends reviewing this configuration every three to six months, because instructions written to work around an older model's limitation turn into overhead once a newer model handles the case on its own. Review CLAUDE.md edits in pull requests like any other documentation change.

Name the files in the prompt, and start the session from the narrowest directory that contains the work. Those two moves do more than any tool. Where you launch the agent decides what it can see. Start from a subdirectory such as `packages/api/` and Claude Code loads that directory's CLAUDE.md plus every ancestor's, with no sibling-package instructions in context and file access limited to that subtree. Start from the repository root and you get everything, including other teams' conventions. Four settings do the rest of the narrowing: - `claudeMdExcludes` in `.claude/settings.local.json` skips instruction files by glob, such as `"/packages/web/"`, so packages you never touch never load - `Read` deny rules in `permissions.deny` block checked-in generated and vendored code, such as `Read(.//dist/)` and `Read(./vendor/**)`. Content searches already respect `.gitignore` by default - `worktree.sparsePaths` checks out only the directories a task needs when the agent creates a worktree, instead of the full tree - `--add-dir ../shared` grants read and edit access to one sibling package when a change genuinely spans two Wasana, a buildDay registrant, described the gap this closes: she had built applications with AI in the browser and wanted to "integrate it with my VS codebase and work at the same time." Browser tools hand the model a whole small project. A real repo makes you choose the slice. The highest-value habit here is still free: paste the three or four file paths that matter into the prompt before you describe the change.

Language server plugins and delegated search do the most, because both replace many speculative file reads with one precise answer. Grep is the default and it is better than people expect. Anthropic's Claude Code at Scale post, 14 May 2026, names symbol-level navigation as the upgrade on top of it: install a code intelligence plugin so the agent asks a language server for a definition or caller list instead of scanning files. Inside a session: - `/plugin marketplace add anthropics/claude-plugins-official` - `/plugin install typescript-lsp@claude-plugins-official` The marketplace covers TypeScript, Python, Go and Rust among others, and each plugin needs that language's server binary on your machine. The second technique is delegation. Send exploration to a subagent, which runs in its own context window and returns a summary rather than file contents. Anthropic's engineering post on context engineering, published 29 September 2025 by Prithvi Rajasekaran, Ethan Dixon, Carly Ryan and Jeremy Hadfield, describes the economics: "Each subagent might explore extensively, using tens of thousands of tokens or more, but returns only a condensed, distilled summary." Your main session pays for the summary, not the search. If your organisation already runs a code search or indexing service over the repo, expose it as an MCP server so the agent queries the index instead of walking the tree. Sourcegraph reported on 21 May 2026 that 84 per cent of its large enterprise accounts saw lines of code rise steadily after an AI rollout, and that developers responded by searching more, not less.

Write the handover to disk, not to the conversation. A file in the repo survives compaction, session end, machine restarts and teammates. Conversation history survives none of those. Make the handover note a deliberate artefact with four parts: the task, the files in scope, what has been done and verified, and the exact next step. Ask the agent to write it before you finish, then read it back and correct it. Anthropic's context engineering post calls this structured note-taking, "a technique where the agent regularly writes notes persisted to memory outside of the context window," and names the pattern directly: "your custom agent maintaining a NOTES.md file." What survives a compaction pass is the part most people never check. Claude Code's documentation sets it out exactly: - Project-root CLAUDE.md and unscoped rules are re-injected from disk - Auto memory is re-injected from disk - Nested CLAUDE.md files in subdirectories are lost until a file there is read again - Rules with `paths:` frontmatter are lost until a matching file is read again - Invoked skill bodies are re-injected, capped at 5,000 tokens per skill and 25,000 tokens total - Anything you only said in chat is summarised away Claude Code's auto memory follows the same on-disk logic: the first 200 lines of `MEMORY.md`, or the first 25KB, whichever comes first, load at the start of every conversation. For a cross-package change, Anthropic's monorepo guidance is specific: plan first, then ask the agent to write the plan to a markdown file in the repository, because "the saved plan survives where conversation history may not."

Restarting is how you discard a bad retrieval path. Once an agent has decided a change lives in the wrong three files, every later turn builds on that decision, and correcting it inside the same conversation does not remove it from the history. Will, a buildDay registrant, described the loop and the fix in one sentence: "I was getting stuck in a continuous documentation search loop. Eventually I restarted the conversation from scratch." That was the correct move, not a defeat. What made it feel like one was having to rebuild the setup by hand. Do it deliberately instead: - Run `/clear` when you switch to unrelated work. Old conversation crowds out the files you need next and costs tokens on every message - Run `/compact focus on the auth bug fix` before starting a long new task, so the summary keeps what you choose rather than what the automatic pass guesses - Before either, ask the agent to update the handover note on disk, so the restart costs you seconds Callum Holt, Founder of 13Labs, puts it this way: "A session is a workspace, not a relationship. If it has gone sideways, kill it. The only thing worth protecting is the note on disk, and if that note is good, the next session starts better than the one you just threw away." The test for whether your setup works is simple. Start a brand new session, ask the agent what this repository is and where the code for one feature lives, and see how close it gets before reading anything. If it cannot answer, fix the map, not the prompt.

Should I write CLAUDE.md or AGENTS.md? Write AGENTS.md if you use more than one tool, since over 60,000 open-source projects and more than 20 agents read it. Claude Code reads CLAUDE.md only, so add a CLAUDE.md containing `@AGENTS.md` on the first line, or symlink the two files. How long should my instruction file be? Under 200 lines, per Anthropic's Claude Code documentation. It loads on every session, so length costs tokens on every task and reduces how reliably the agent follows it. Push area-specific detail into per-directory files or path-scoped rules instead. Does an agent read the whole repository at the start of a session? No. It reads your instruction files, then greps and opens files as it needs them. That is why an orientation map earns its place: it tells the agent where to look before it starts guessing. What should a handover note contain? Four things: the task, the exact files in scope, what has been done and verified, and the single next step. Keep it in the repo as a markdown file so it survives compaction and session end, unlike anything said only in chat. Is it bad practice to restart an agent session often? No. Restarting discards a wrong retrieval path that would otherwise shape every following turn. Use `/clear` between unrelated tasks and write the handover note first, so a restart costs seconds rather than a rebuild.