How to Keep an AI Coding Agent From Losing Context

An AI coding agent loses context in a large codebase the moment its window fills up with code that is not directly relevant to the current task, and it starts inferring instead of verifying. The fix is structural: write repo-level briefing files the agent reads before it does anything else, scope each task to one module or directory, search before reading whole files, keep a running notes file the agent re-reads across turns, and know when to end a session instead of pushing it further. This is a single-agent problem. It has nothing to do with running multiple AI coding agents in parallel to increase throughput, that is a different failure mode with a different fix.

One Agent, One Long Task, One Big Repo

Most advice about AI coding agents assumes small repos or short sessions. Neither holds at scale. A codebase with a few hundred thousand lines spread across dozens of services does not fit in any context window, no matter how generous the vendor's marketing page is. An agent working inside it for three hours on a single feature has to make decisions about what to hold onto and what to drop, over and over, without you in the loop for most of those decisions.

Running several agents at once, one per ticket or per service, is a throughput problem, covered in running multiple AI coding agents in parallel, one entry in our broader guide to AI coding tools. Keeping one agent coherent while it works through one large, unfamiliar codebase is a different problem: information density. The rest of this piece is about that second problem.

Why Agents Drift in Large Repos

Anthropic's engineering team has documented the mechanism directly: as the number of tokens in a context window grows, a model's ability to accurately recall and use any single piece of information in it goes down, a pattern they call context rot. They cover it in their post on [effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents). A bigger context window does not solve this. It just moves the point where accuracy starts degrading further out.

In a large codebase this shows up as familiar symptoms: the agent reintroduces a bug it already fixed two files ago, forgets a naming convention you told it about at the start of the session, or reimplements a helper function that already exists three directories over because it never saw it. None of that is the model being lazy. It is the model running out of reliable working memory for a repo it was never briefed on.

Make the Repo Legible Before You Prompt

The single highest-leverage fix is also the least glamorous: write documentation an agent can actually use to orient itself, and put it where the agent will find it automatically. Anthropic builds this into Claude Code directly: the agent reads a CLAUDE.md file at the start of every session, root file for the big picture, subdirectory files for local conventions, as described in [Anthropic's guide to using CLAUDE.md files](https://claude.com/blog/using-claude-md-files). Other tools use similar conventions under names like AGENTS.md. The filename matters less than the discipline of writing it and keeping it current.

A good briefing file for a large codebase answers the questions a new hire would ask on day one: what does this service do, where does it start, what are the load-bearing modules, what conventions are non-negotiable, what has already been tried and abandoned. Skip the boilerplate; an agent does not need your linting rules restated if a config file already enforces them.

# AGENTS.md - payments-service

## What this is
Handles charge creation, refunds, and webhook ingestion for
Stripe and Adyen. Not the billing/invoicing service (that's
../billing-service).

## Where to start
- src/charges/  - charge lifecycle, state machine in state.ts
- src/webhooks/ - inbound events, idempotency keys required
- src/ledger/   - append-only, never mutate rows, only insert

## Conventions
- All money values are integer cents. No floats, anywhere.
- New endpoints go through src/api/router.ts, not ad hoc routes.
- Run `npm run test:charges` before touching src/charges/.

## Known traps
- webhooks/retry.ts looks dead but is called from a cron job
  in infra/, do not delete without checking infra/crontab.yml
- refunds must check ledger balance before writing; see the
  incident writeup at docs/incidents/2025-11-negative-balance.md

Scope Every Task to One Module or Directory

Handing an agent a task like "improve error handling across the API" invites it to touch fifty files it half understands. Handing it "add retry with backoff to the three HTTP calls in src/webhooks/adyen.ts" gives it a boundary it can actually hold in memory alongside the surrounding code.

Scope by directory, not by feature, when the codebase is large. A feature often cuts across a dozen modules; a directory has natural walls. Let the agent finish and verify one directory before it moves to the next, even if that means more round trips with you. This is also the cheapest way to keep the agent from touching code you did not ask about, a failure mode covered in stop AI changing code you didn't ask it to.

Search First, Read Second

Do not let an agent's default move be dumping entire files into context. In a codebase where a single file can run two thousand lines, reading it whole to find one function is how the window fills up with noise. Push a grep-first workflow instead: search for the symbol, function, or string first, read only the matching region plus a little surrounding context, and expand only if that is not enough.

This matters more as repos grow. A two-hundred-line file can be read whole cheaply. A two-hundred-thousand-line service cannot, and an agent that treats both the same way will run out of useful context on the second afternoon of a multi-day task.

Keep a Running Notes File the Agent Re-reads

Long tasks span more turns than any single context window comfortably holds. Anthropic describes a version of this pattern for multi-window agent work: a plain progress file that the agent writes to as it works and re-reads at the start of each new turn or session, discussed in their post on [effective harnesses for long-running agents](https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents). The file is not a transcript. It is a compressed summary: what is done, what is in progress, what was tried and rejected, and why.

Ask the agent to update this file after every meaningful step, not just at the end of a session. If the session gets interrupted or you close the laptop, the next agent, or the same one starting fresh, picks the file up and does not have to reconstruct three hours of work from git diffs alone. Pair it with disciplined commits, covered in how to use git with AI coding agents, so the notes file and the actual state of the repo never drift apart.

When to Start a Fresh Session vs Keep Going

Every session accumulates junk: dead ends, superseded plans, tool output nobody needs anymore. At some point the marginal value of continuing drops below the cost of the noise sitting in context. Watch for the signals rather than pushing on a fixed clock.

Concrete Tactics, In Order

1. Write a root-level briefing file (CLAUDE.md or AGENTS.md) before the first task, not after the tenth mistake.

2. Add subdirectory-level notes for modules with real complexity or known landmines.

3. Scope tasks to one directory or module per working session.

4. Default to grep or search before reading full files.

5. Keep a running progress notes file the agent updates and re-reads every turn.

6. Commit at natural checkpoints so state lives in git, not only in context.

7. End the session when the agent starts re-asking questions you already settled.

8. Re-verify with how to review AI generated code before you ship it once a scoped task completes, since a coherent agent can still produce a wrong diff.

FAQ

How big can a codebase be before an AI coding agent loses context?

There is no fixed line. It depends on the model's context window and how much of the repo is actually relevant to the task, but symptoms usually appear once a task touches more files than a briefing document and search results can summarize in a few thousand tokens. Repos above roughly fifty thousand lines benefit from the structural tactics here regardless of which agent you use.

What is context rot in AI coding agents?

Context rot is the documented drop in a model's ability to accurately recall and use information as the number of tokens in its context window grows, even when the window technically has room left. Anthropic describes it in its research on effective context engineering. The practical implication is that a bigger window is not a substitute for curating what goes into it.

Should I use one CLAUDE.md or AGENTS.md file, or several?

Use one root file for architecture and conventions that apply everywhere, plus subdirectory files for modules with their own quirks, dependencies, or history of bugs. A single sprawling file forces the agent to load context it does not need for narrow tasks.

Does a bigger context window fix the problem of an agent losing context?

Not by itself. A larger window delays when degradation starts but does not remove it, and an agent that is not scoped, briefed, or searching efficiently will still drift, just later in the session. Structural habits matter more than raw window size.

How is this different from running multiple AI coding agents at once?

Running agents in parallel is a throughput technique, splitting independent work across agents to move faster. Keeping one agent from losing context is about coherence inside a single long task in one codebase. You can do both, but they solve different problems.