Coding Agent Repository Context: Why Good Prompts Fail Inside Real Codebases

The prompt was precise. The model was capable. The change still came back wrong.

That sentence describes most of the frustration developers hit with coding agents on real repositories. The agent imported a helper that does not exist in this codebase. It used an API shape from a version two majors ahead of the pinned dependency. It edited a generated file. It passed review by eye and failed at runtime.

The instinct is to rewrite the prompt. That instinct is usually wrong for existing-repository work. Prompt quality is a weak lever compared with two stronger ones: what the agent can see, and whether the task you handed it can be checked. This article is about the first lever, and about why the second one decides whether the first one matters.

The Prompt Was Never the Bottleneck

Grant the narrow case first. Prompt quality matters when the task is small and the surrounding world is simple: a standalone function, a well-known library API, a greenfield snippet with no neighbors. In that setting, a clear instruction and a clear example do most of the work.

Now put the same agent inside a repository that has been alive for years. The conventions are implicit. Some dependencies are pinned for reasons nobody wrote down. Part of the tree is generated. A migration is half-finished in one module. Two services share a data shape that must stay compatible. None of this is in the prompt, and none of it is discoverable from the file the agent was asked to edit.

Here is the part most developers miss: the prompt is only one input among many competing for the same window. Before your instruction reaches the model, the harness — the surrounding system that runs the agent, such as an IDE assistant or a terminal-based coding tool — has already assembled a context window. That window contains the harness's own system prompt, environment details, workspace files the harness judged relevant, tool descriptions, any instruction files in the repository, the conversation history, and finally your prompt.

You control some of that. You do not control all of it. The system prompt is typically invisible and unchangeable. Compaction behavior — what the harness discards when the window fills — belongs to the harness. Instruction files, tool responses, and task framing are yours.

The failure mode that follows is quiet. A wrong import compiles. A plausible helper function looks like something a teammate wrote. The diff reads cleanly. Nothing surfaces until someone runs the code, and by then the review has already been approved. This is the worst category of quality failure: invisible at the moment you are most likely to accept it.

So the working thesis for the rest of this piece: coding agent repository context is a selection problem, not a volume problem. The agent is rarely under-prompted. It is frequently under-contextualized and over-instructed.

What the Agent Actually Sees Before It Writes Code

To reason about this properly, you need a mechanical picture of context assembly. The sequence looks roughly like this.

The harness assembles the context window. The model reads that assembled material and builds a mental model of what is available and what was asked. Tool calls fire — file reads, searches, command execution. Tool responses come back and enter the window. Only then does the model generate code.

The critical detail is that the model receives the assembled material as one block rather than as a document a human skims in order. Irrelevant material is not neutral. It competes. Every token of stale documentation, every vendored file pulled into the window, every tool description for a capability the task does not need, takes space that relevant evidence could have occupied.

A single misleading tool response can pull a task off course. Microsoft's developer guidance on how coding agents consume technology describes extensions causing agents to upgrade a project to a different framework version than the developer asked for, or to switch programming languages mid-task. That is one vendor's implementation account, not a field-wide law, but the mechanism it describes is mundane and worth internalizing: the tool returned content, the model latched onto the wrong part of it, and the generated code used an internal-only endpoint. Nothing errored. Everything looked fine from the outside.

The token economics are equally mundane. If a tool returns three thousand tokens of documentation when two hundred would have answered the question, the other twenty-eight hundred tokens pushed something else out of the window. That is drag, and it compounds across every tool call in a session.

The practical split matters here. Instruction files, tool responses, and task framing are yours to shape. The system prompt, the compaction policy, and the harness's own notion of which workspace files are relevant are not. Spend your effort where you have control.

Why More Repository Context Often Makes Agents Worse

The counterintuitive part is that adding a repository context file — a document like AGENTS.md that tells the agent how the repo works — is not a free win. A recent study on repository-level context files found that across multiple coding agents and language models, these files tended to reduce task success rates compared with providing no repository context at all, while increasing inference cost by more than twenty percent.

Treat that as a signal, not settled law. The study covers a limited set of repositories and tasks, context files were only formalized in August 2025, and adoption across the industry is uneven. Many repositories still have no context file at all. The finding is a strong reason to stop assuming context files are automatically helpful. It is not a reason to conclude they are useless.

The mechanism behind the result is more interesting than the headline. Both automatically generated and developer-written context files encouraged broader exploration — more file traversal, more testing. Agents also tended to respect the instructions literally. That sounds like good behavior until you notice what it implies: every requirement you add narrows the solution space the agent can search. A context file that says "always use the repository's logging wrapper" is helpful. A context file that lists forty conventions, half of which are aspirational rather than enforced, hands the agent forty constraints to satisfy simultaneously, and some of them will conflict with the task.

The real culprit is unnecessary requirements, not documentation as a concept. The recommendation that follows from the research is minimal requirements, not exhaustive description.

Here is the decision rule I would apply: a context file should encode what the agent cannot discover cheaply. If the agent can find it with one file read or one search, it does not belong in a static document. If discovering it requires knowing which of four similarly named directories is authoritative, that belongs.

The Four Kinds of Context a Repo-Aware Agent Needs

"Give the agent context" is too vague to act on. Split it into four kinds, each with an observable signal that tells you it is missing — and a preferred place to put it.

Navigational context is where things live and which parts of the tree matter. Which directory is authoritative, which is generated, which is vendored and should be ignored. The signal that it is missing: the agent reads the wrong implementation of a function, or edits a file under a build output directory. Preferred carrier: ignore rules and workspace scoping first, a short pointer in the context file second. The failure test is whether the agent still wanders into generated or vendored trees after the rule is in place.

Conventional context is how code in this repository is written. Naming patterns, error handling style, test layout, the local idioms that make a change look native rather than transplanted. The signal: style drift in the diff. The agent's code works but reads like it came from a different project. Preferred carrier: a minimal repository instruction file, and only for conventions the agent cannot infer from neighboring files. The failure test is whether the convention is actually enforced somewhere — if nothing in the repo enforces it, it is a preference, not a rule, and it does not belong in a static document.

Constraint context is the set of facts that are not visible in any single file. Pinned dependency versions. The exact build and test commands. Migration rules. Invariants that span modules — the kind of thing where changing one side of a contract breaks the other. The signal: tests that pass locally and fail in CI, or imports that resolve against a version the project does not use. Preferred carrier: executable checks wherever possible, with a pointer to the command in the context file. The failure test is whether the constraint has a test that would fail without it.

Boundary context is what the agent must not touch. Secrets, generated artifacts, production configuration, files under active migration, anything owned by another team. The signal: edits to files nobody asked about. Preferred carrier: explicit allowed and forbidden paths in the task contract, backed by ignore rules where the harness supports them. The failure test is whether a diff that touches a forbidden path gets caught before review.

That last signal is worth dwelling on. When an agent modifies files outside the stated task, it is usually not being reckless. It is responding to a gap in boundary context. The agent found something that looked related and did what a helpful collaborator would do. The fix is a boundary, not a scolding.

Cutting Repository Noise Without Cutting Signal

The taxonomy tells you what to include. The harder discipline is what to exclude.

Apply the discovery test first. If a cheap file read or a search reveals it, leave it out of the static context file. Prefer pointers over prose: name the file or the command rather than restating its contents. A line that says "test commands live in Makefile, use the test target" is worth more than three paragraphs explaining the test strategy, because the agent can read the Makefile itself.

Keep the context file small enough that a human reviews every line when it changes. Treat it as code with an owner. A context file that nobody reads is a context file that accumulates stale constraints, and stale constraints are worse than no constraints because the agent will try to satisfy them.

Use ignore rules and workspace scoping to keep vendored trees, generated code, and large binaries out of the assembled context. This is the cheapest noise reduction available and it is frequently skipped.

Watch for context collapse. Iterative rewriting of instructions erodes detail over time — each pass summarizes a little more aggressively, and the specific constraint that mattered quietly disappears. Research on evolving agent contexts names this failure mode directly and recommends structured incremental updates that preserve detail rather than periodic rewrites. The practical version: append and amend rather than regenerate.

Name the tradeoff honestly. Aggressive trimming can remove the one constraint that prevented a subtle bug. This is why trimming has to be paired with tests rather than with confidence. The test suite is what tells you whether the constraint you deleted was load-bearing.

Defining Tasks That Can Be Verified, Not Just Generated

Everything above is about what the agent sees. This section is about what you can check, and it is where the real leverage sits.

A generated change compiles and looks plausible. A verified change has an executable check that would fail without it. That distinction is the whole game. If you cannot state the check before handing over the task, you are not handing over a task — you are handing over a hope.

So require every task to name its own verification. A failing test to make pass. A command whose output must change. A diff that must not touch certain paths. The repository's own test suite is the natural feedback signal here, and it does double duty: the same mechanism that lets an agent iterate is the mechanism that lets you judge the result. Training setups for coding agents use repository tests as feedback for exactly this reason.

Scope tasks so the blast radius is inspectable. One behavior, one module boundary, one migration step. A task that touches four subsystems produces a diff nobody can review carefully, which means the verification you asked for gets skipped in practice.

Separate investigation from implementation. Some work should produce a plan or an analysis and never touch the codebase. Orchestration systems built around coding agents treat this as a first-class distinction: some issues produce multiple pull requests across repositories, and others are pure investigation that never modifies code. If you blur those two categories, you get agents making speculative edits while you were still asking for a diagnosis.

The decision boundary: when a task cannot be expressed with a check, it is usually not ready to hand to an agent. That is not a limitation of the agent. It is a signal that the task is underspecified, and a human would have struggled with it too.

Where Repository Context Stops Being Enough

The model above holds for a single repository, a bounded session, and one developer. Outside those conditions, it degrades in specific ways — and the important question is which fix belongs where.

Multi-repo changes break the assumption that context transfers. One task can produce several pull requests across repositories, and the context assembled for one repository does not carry to the next. The agent that understood your service's conventions has no idea what the adjacent repository expects. This is not a repository-context problem. It is a task-contract problem: the contract has to name which repository owns which decision.

Long-running sessions break the assumption that conversation history is durable state. Harnesses implement automatic context compaction that monitors token usage and compacts chat history mid-loop to prevent overflow during long tool-calling chains. That is necessary, and it is also a silent deletion mechanism. The constraint you stated forty turns ago may not survive. Long agent runs need external state — a task file, a ticket, a written contract in the repository — not just the conversation. This is an operational control, not something a context file can fix.

Team context breaks the assumption of a single owner. Shared sessions and multi-user agent environments introduce questions a personal context file never had to answer: who owns this session, who submitted which prompt, who can read it, who can approve a privileged operation. Vendor tooling in this space is moving toward session ownership, participant attribution, and permission tiers, which tells you the questions are real. It does not tell you the answers are settled, and it does not make them repository-context decisions.

Underneath all of it sits an observability gap. Without structured logs of session lifecycle and task outcomes, failures become archaeology. The orchestration spec published by OpenAI's Codex team is instructive here: it requires stable key=value log phrasing, an action outcome, and a concise failure reason, and it explicitly avoids logging large raw payloads. That is a reasonable default for anyone running agents at volume — and again, it is harness and operations work, not something you solve by editing AGENTS.md.

What remains unresolved: how much of the reported context-file penalty generalizes across languages, repository sizes, and different agent harnesses. The study is a signal from a limited sample. Anyone claiming a universal rule is extrapolating.

What to Build Next in Your Own Repository

Start with an audit, not a rewrite. Take one repository and list what the agent got wrong in the last ten tasks. Classify each miss against the four context kinds. You will usually find that most failures cluster in one or two categories, which tells you where to spend effort.

Then run a small experiment instead of a rewrite. Pick a set of comparable tasks — same repository, similar scope, similar review depth. Record a baseline: task success, paths touched outside the stated scope, review effort, and recovery time when a change fails. Change one context layer at a time: add ignore rules, then a minimal instruction file, then a task-level boundary. Re-measure after each change. If a layer does not move the numbers, shrink it or revert it. Without that baseline, you will attribute any improvement to whatever you changed last.

Add a verification requirement to every task you hand over. If you cannot state the check, split the task until you can.

Track two numbers over a month: review cost per accepted change, and recovery time per failed change. Those are the signals that tell you whether the setup is working. Not the volume of code produced, and not how impressive the diff looked on the first read.

The adjacent question — which tasks are verifiable at all, and what that implies about trusting an agent on your codebase — is the natural next step once this one is in place.

Here is the part worth internalizing. The durable asset is not the prompt. Prompts are cheap, disposable, and model-specific. The durable asset is the repository's test coverage, its written conventions, and its boundary documentation — the things that make any agent, current or future, cheaper to supervise. Invest there and the return compounds across every model you will ever plug in. Invest in prompt craft alone and you will be rewriting the same instructions next quarter, wondering why the code still comes back wrong.