Agentic Development Lifecycle：以四種方法管理 AI 編碼智能體上下文

Your context window is a budget, not a bucket - Chapter 6 · Why giving your agent more context can make it worse

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.

More context doesn't automatically mean better results Consider how you debug an unfamiliar codebase. You probably don't read every source file before fixing a bug. You start with the error, identify the relevant module, inspect its dependencies, and follow the evidence. You narrow the problem before expanding your investigation. AI agents need a similar discipline. Every model call receives a context payload: the instructions, relevant code, conversation history, tool results, and other information available for that decision. The size of the context window tells you how much information the model can receive. It doesn't tell you how much information it can use effectively. In the SWE-agent experiment, the results looked like this:

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:

The database query returns the correct number of rows.
The bug is in the page-offset calculation.
Existing tests cover page 1 but not page 2.

Files:

src/api/customers.ts
tests/customers.test.ts

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 offloading: 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.

Your AGENTS.md can become a source of noise Repository-level context files are now common in AI-assisted development. Files such as AGENTS.md, CLAUDE.md, and copilot-instructions.md can help agents understand a codebase without repeatedly rediscovering its conventions. But they can also accumulate stale or redundant guidance. A useful instruction file might explain: • How to run tests • Where important modules live • Which conventions are mandatory • What generated files must not be edited • Where to find specialized instructions An unhelpful one might include pages of generic advice, duplicate documentation, outdated commands, and rules that contradict the codebase. The problem gets worse when agents maintain these files by rewriting them wholesale. Repeated regeneration can gradually erase specific details, simplify important exceptions, or replace concrete instructions with generic summaries. A safer approach is incremental maintenance:
Read the existing file.
Identify the specific information that has changed.
Update only the relevant section.
Preserve useful details and exceptions.
Remove instructions only when they are demonstrably obsolete or redundant. Edit context files. Don't casually regenerate them. Treat them like maintained source code, not disposable prompt text.
Context engineering has a limit Better context selection is important, but it isn't the entire solution to reliable AI development. Eventually, an agent needs more than instructions about the codebase. It needs a system that helps it act correctly and verify its work. That means thinking about three related areas: • Context engineering: What information should the agent receive? • Harness engineering: What tools, constraints, and feedback loops govern its actions? • Environment and repository structure: How can the system make correct actions easier and mistakes easier to detect? A carefully written AGENTS.md cannot compensate for missing tests. A larger context window cannot make an unreliable tool reliable. A detailed instruction cannot guarantee that a change works. Context helps the agent make decisions. The surrounding development system helps those decisions become dependable results. That is where the next stage of agentic development begins. Try this in your repository Pick a coding agent you use regularly and inspect its main context file—perhaps AGENTS.md or CLAUDE.md. Try this small experiment:
Make a copy of the file.
Remove roughly one-third of the instructions that are generic, duplicated, outdated, or irrelevant to most tasks.
Keep essential constraints, commands, architecture notes, and project-specific conventions.
Run the same representative coding task with the original and reduced versions.
Compare the resulting code, test outcomes, and unnecessary tool calls. Don't optimize for the shortest possible file. Optimize for the most useful instructions per token. If performance drops, investigate what important information was removed. If performance stays the same or improves, you've found context that may not have been earning its place.

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