The reflex

The instinct is understandable. The agent is about to change a shared utility, so you attach utils.ts, then its test, then the three callers you know of, then the README, then the generated types. Five minutes later you've pasted 12 files into the prompt and the agent still gets it wrong because the one file that defines the edge case — the migration script from last quarter — isn't in the stack.

Bigger context windows made this reflex worse. It feels free to attach everything, so teams do. The result is an agent that reads 4,000 lines and acts on 40 of them, because the relevant signal was diluted by noise.

What actually happens inside the context window

A model doesn't weight every file equally. It weights the first few, the last few, and whatever is mentioned explicitly in your question. The middle of a 12-file paste is effectively background noise. You're paying for tokens you're not using.

There's a second cost: once the agent has read 12 files, it assumes the answer lives in one of them. It stops asking clarifying questions, stops checking the actual schema, and starts reasoning from the least-wrong file it was given.

The failure mode isn't "not enough context." It's "too much undifferentiated context."

The 30-minute fix

Instead of pasting files reactively, maintain a short file-level manifest that maps a task type to the files the agent should read first. It doesn't need to be perfect.

# AGENT_CONTEXT.md
task: "change shared API response shape"
files:
  - src/http/contracts/order.ts
  - src/http/contracts/order.test.ts
  - docs/api/order.md
read_first: src/http/contracts/order.ts
don_not_inject: src/**/*.generated.ts

The point isn't that the manifest is complete. The point is that the agent starts with three files that matter, and it knows it's allowed to ask for more instead of guessing from the 12 you dumped.

For API work specifically, the highest-leverage artifact isn't any code file — it's the contract. If the agent reads the OpenAPI spec first, it doesn't need you to paste three call sites, because the types and the example payloads already tell it what shape the system expects. We built Powerduck around this: the spec lives locally, the agent points at the spec file, and the generated types and examples derive from it. No more guessing which callers to attach.

The two rules that survive contact with production

1. Cap the initial context, don't maximize it. Start with 3–5 files. Let the agent ask for more. The cost of one extra round-trip is minutes; the cost of a wrong edit across 4,000 lines of context is a broken build.

2. Distinguish "read this" from "this is the source of truth." Most files you paste are reference material. One file — the contract, the schema, the migration, the test that encodes the invariant — is the source the agent should treat as authoritative. Mark it explicitly. Otherwise the agent will weight the README's informal example over the actual schema.

What to do this week

  • Open your last five agent sessions. Count the files attached on the first turn. If it's more than five, you're paying the dilution tax.
  • Pick one high-frequency task ("change the API shape", "add a CLI flag", "fix the flaky test in X") and write a 20-line manifest for it. Iterate on it once a week.
  • Stop auto-attaching the README. It's almost always the file the agent least needs, and it's almost always the one you attach first.

The goal isn't a perfect RAG system. It's an agent that reads the right three files instead of guessing across the wrong twelve.