Why giving your AI coding agent more context can make it perform worse
When an AI coding agent gets stuck, the instinct is usually to give it more context.
More files. More documentation. More conversation history. A longer CLAUDE.md or AGENTS.md. Maybe the entire repository.
The assumption is simple: if the agent knows more, it should make better decisions.
But experiments suggest otherwise.
In one SWE-agent experiment, showing the agent a relevant file in a 100-line window produced an 18.0% success rate. Showing the entire file dropped that to 12.7%.
The agent had more information. Its performance got worse.
This is one of the most important lessons in building reliable AI coding workflows:
Your context window is a budget, not a bucket.
The goal isn't to give an agent as much information as possible. It's to give it the right information at the right time.
Showing too little information can hurt performance. But showing everything can hurt, too.
This is not an argument for always using shorter prompts. It's an argument for being deliberate about what goes into them.
Context has two failure modes
When an agent performs poorly, context problems generally fall into two broad categories.
Context starvation
The agent doesn't have enough information to complete the task.
For example: • It edits a function without seeing its callers.
• It changes an API without seeing the expected response format.
• It modifies a test without understanding the production behavior.
• It follows a coding convention that the repository no longer uses.
The solution is to provide the missing information.
Context dilution
The agent has the necessary information, but it is surrounded by so much unrelated material that the relevant details become harder to use.
For example: • A simple bug fix comes with the entire conversation history.
• A small refactor includes documentation for unrelated modules.
• A coding task begins with thousands of tokens of general instructions.
• Tool output overwhelms the actual error or result the agent needs to inspect.
The solution is to remove noise and make relevant information easier to find.
These problems need opposite remedies. Adding more context may fix starvation while making dilution worse.
A practical diagnostic
When an agent produces a poor result, try a simple experiment:
Reduce the context payload by roughly half and rerun the task.
• If performance improves or stays about the same, the original context may have contained unnecessary information.
• If performance gets worse, the removed information may have been important.
This isn't a universal benchmark or a substitute for controlled evaluation. It's a useful debugging technique for understanding whether your agent needs more information or better information selection.
Bigger context windows don't eliminate the problem
Model context windows have grown significantly. That makes it possible to include more code, documentation, tool output, and history in a single request.
But greater capacity doesn't guarantee that every additional token is useful.
Research into long-context behavior has documented limitations commonly described as the lost-in-the-middle effect: information can be harder to use when it appears in certain positions within a long input.
Chroma's Context Rot study examined 18 models and reported declining reliability as input length increased across several tasks. The study is useful evidence of the problem, although it comes from a company that sells vector database technology and should be considered alongside other evidence.
The practical takeaway is straightforward:
A model's maximum context length is a capacity limit, not a recommended prompt size.
Think of it like memory in a software system. Having more available memory doesn't mean every object should remain in memory forever. Good systems still manage what they load, retain, cache, and discard.
The same principle applies to AI agents.
Four ways to manage context
If context is a budget, how should we spend it? There are four useful techniques.
A. Compact the context
Long-running agents accumulate information:
• Previous decisions
• Intermediate reasoning summaries
• Tool results
• Failed attempts
• Old instructions
• Repeated descriptions of the task
Some of that information is valuable. Some is no longer relevant.
Compaction means preserving the important state while removing unnecessary detail.
For example, instead of retaining a long debugging conversation, keep a concise summary: Task:
Fix incorrect pagination in the customer API.
Findings:
Files:
Next step:
Add a regression test for page 2, then correct the offset calculation.
This gives the next model call a useful starting point without carrying every previous interaction forward.
The key is to preserve facts, decisions, constraints, and next steps—not every detail of the journey.
B. Offload large tool outputs
Tools can return far more information than an agent needs.
A repository search might return hundreds of matches. A test command might produce thousands of lines. A log file might contain one useful error buried in repetitive output.
Instead of inserting everything into the model's context, keep the full output outside the conversation and expose a smaller, relevant result.
For example: Test suite: 248 tests
Passed: 247
Failed: 1
Failing test:
tests/customers.test.ts::pagination_returns_second_page
Relevant error:
Expected customer ID 21, received customer ID 1.
If the agent needs more detail, it can fetch the relevant section. This is the principle behind tool-output off: store the full result, but bring only the necessary portion into context.
C. Use progressive disclosure
Don't load every instruction, document, or tool description at the beginning of every task.
Start with a small amount of general guidance. Let the agent discover more specific information when the task requires it.
For example, a repository might contain: AGENTS.md
docs/
architecture.md
testing.md
deployment.md
database.md
The root AGENTS.md can explain the project's structure and point the agent toward specialized documents.
A database task can load database.md. A deployment task can load deployment.md.
This keeps the initial context focused while making deeper information available on demand.
The distinction matters: good context engineering doesn't mean hiding information forever. It means avoiding unnecessary information before it becomes relevant.
D. Reset the context when the task changes
Long-running conversations can accumulate outdated assumptions, completed work, failed experiments, and irrelevant details.
Sometimes summarizing the existing conversation isn't enough. Starting a fresh model call with a concise handoff is cleaner.
Think of an engineer handing work to a teammate at the end of a shift.
The handoff should include:
• What has been completed
• What remains unresolved
• Which files have changed
• What has been tested
• Which decisions must not be revisited
• What the next step should be
The new agent doesn't need the entire history. It needs the current state of the work.
Reset the conversation, not the project's knowledge.
Keep durable information in files, tests, issue descriptions, and other artifacts that survive the context reset.
The takeaway
A bigger context window gives your agent more room. It doesn't automatically give the agent better judgment.
Reliable agentic development requires deliberate choices about what enters the context, what stays outside it, what gets retrieved on demand, and when the agent should start fresh.
Don't ask how much context your agent can hold. Ask which information deserves to be there.
How long is your CLAUDE.md or AGENTS.md today—and when was the last time a human actually edited it?
This post is based on Chapter 6 of The Agentic Development Lifecycle.
Read the full chapter: Context Engineering — The Budget, Not the Bucket