Context engineering for coding agents

Give a model your entire repository and one question, and you have not made its job easier. You have made it a search problem before it can be an answering problem. It has to find the corner that matters, in a window where every irrelevant file is competing for attention with the relevant one.

This is the part that gets missed: a bigger context is not a strictly better context. Past a point it is a worse one, and you pay more for it.

The three failure modes

• →Dilution. The signal is present but surrounded. Retrieval accuracy on a fact falls as the volume of unrelated material around it rises, and it falls fastest for material in the middle of a long window.
• →Contradiction. Two versions of the same function, an old comment against new code, a stale README. The model has no way to know which one is current, and it will sometimes pick the wrong one.
• →Drift. Long sessions accumulate decisions that were reversed, paths that were abandoned, and errors that were fixed. All of it is still in the window, still being re-read, still shaping the answer.

Rules that hold up

These are not clever. They are the ones that survive contact with real work.

Relevance beats volume. Ten lines that answer the question outperform a thousand that contain the answer somewhere. If you can point at the code, point at it.

Fresh beats complete. A stale file that contradicts current behaviour is worse than no file at all, because it produces a confident wrong answer instead of a question.

A hard ceiling beats good intentions. Without one, context grows monotonically. Nothing in an agent loop ever decides that it now knows enough.

One task per window. The cheapest context management technique in existence is closing the session.

What this looks like in practice

$capsul context 'why is the webhook handler returning 500' --open src/app/api/polar/webhook/route.ts

The point of building the context separately is that it makes the invisible part visible. You can see what a task costs before you commit to it, and you can compare two framings of the same question.

Measuring it

Context engineering has an honesty problem, and it is worth naming. Almost every claim in this area is made without a control arm, which makes it unfalsifiable. If you are going to change how context is assembled, measure the same task on the same model with and without the change, repeat it enough times to see the noise floor, and publish the interval rather than the median.