Your Agent Doesn't Need More Tokens. It Needs Fewer Wrong Files.

An agent you trust with a bug fix fails. The reflex: paste the whole repo into context. The 200K window is there, use it.

Two runs later, it still edits the wrong module. Not because it couldn't read the code, but because it was reading fifty files at once and the one that mattered got lost in the pile.

More context is not better context

Large context windows changed what we can hand an agent. They didn't change how agents use it. The model still weights recent tokens and structurally similar patterns — and when you drop in forty unrelated files, the signal-to-noise ratio collapses.

You see this in practice: give an agent the entire node_modules of a project plus three core files, and it starts pattern-matching against libraries instead of your code. The fix it proposes works in a generic sense, but not against your specific bug.

The bottleneck stopped being can the model see the file and became can the model tell which files matter.

What to actually hand it

After a lot of trial and error, the set that consistently works is smaller than people expect:

• The 3–5 files directly involved in the bug or feature, not the whole subsystem.
• The exact error output — stack trace, failing assertion, or the network response that looked wrong.
• One README or design note that explains what the module is for, not just what it does.

That's it. Thirty files of surrounding code usually hurts more than it helps.

The test: if the agent can't solve the bug with those three things, the problem isn't context size — it's that you haven't isolated the boundary of the problem yet. More files won't fix that. Narrowing the problem will.

The spec as the one file that earns its place

When the bug touches an API boundary, the highest-leverage file to include is the contract itself — the OpenAPI spec, not the markdown docs that were written about it after the fact. The spec says what the endpoint actually does, and the agent can re-check its changes against something mechanical.

This is part of why we built Powerduck around a local OAS file: it's the one context piece that stays accurate as the code changes, and the agent can query it directly over MCP instead of waiting for a human to paste the right section. It replaces "here are 20 files, good luck" with "here's the contract, here's the failing request, go."

The counterintuitive part

Less context feels risky. What if the agent misses something important?

But that risk is already there when you dump everything — the agent always misses something. The question is whether it misses the thing that matters, and whether you can verify it didn't.

Three files plus a contract is a set you can actually review. Forty files plus a vague "looks right" is not.

The next time an agent gets something wrong, before you paste more code in, ask: did it have the right three files, or did it have the wrong fifty?