Context selection over a codebase

Read these first

• Repo-scale code retrieval
• Context engineering — selection

What you will know

• Choose which files enter context for a specific task

  A sound choice preserves dependency boundaries and hidden constraints without importing unrelated modules.

• Stay inside a token budget on a large repository

  The cap must leave room for instructions, tool output, and the agent's generated patch rather than consuming the entire window.

• Show too much context degrading a code edit

  Irrelevant symbols can distract the model, introduce conflicting signals, and reduce the space available for a precise answer.

• Decide between a whole file and a relevant span

  A span may omit imports, surrounding control flow, or local conventions that determine whether an edit is safe.

• Write the default inclusion policy and justify its exceptions

  The policy should make conservative assumptions explicit, especially for tests, configuration, generated files, and dependency boundaries.

Chapters

1. 1

   The window is a running total, not a per-request allowance

   Filling 180k of a 200k window with repository code works for two attempts and then the agent truncates its own patch mid-function. The same window has to hold the system prompt and tool definitions, every diagnostic and diff the loop accumulates, and the patch still to be written. Do the arithmetic for four attempts at roughly 18k of test output plus a 6k patch each, and derive the ceiling the first turn's fill is actually allowed.

   Read chapter
2. 2

   Eviction is the other half of the budget

   The first turn's fill is the half of the window a builder chooses; test output, diagnostics and superseded diffs are the half it inherits, and by attempt three that half is what overflows even when the initial cap was sized correctly. Retrieval score cannot rank it, so it needs its own rule: drop the diffs and diagnostics of attempts that have been replaced, truncate a tool result that comes back at 60k instead of the 18k budgeted, and re-read any file whose copy in context went stale when the agent edited it. Then name what must survive every eviction — the task statement, the file currently being edited, the most recent diagnostics — because holding a budget through a run that misbehaves is a different discipline from sizing one.

   Read chapter
3. 3

   Each extra file adds a plausible wrong answer

   Adding VAT handling to billing/invoice.py with all 40 currency-mentioning files in scope produces a patch importing format_currency from legacy reporting, which rounds differently from the one billing uses. Nothing in the retrieved text says which implementation this module is entitled to, so the model resolves by preference. This is the mechanism behind recall rising from 0.71 to 0.94 while first-attempt CI pass rate falls from 58% to 41% — though distraction is not the only candidate, since extra files also displace the useful ones within the window. Separate the two by holding the file set fixed and permuting the order, or by padding with inert filler that adds no rival implementations and seeing whether the pass rate still falls.

   Read chapter
4. 4

   A span carries the code but not the file's local rules

   The 30-line refresh_token span out of a 900-line auth module produces a patch calling datetime.utcnow() directly, while every neighbouring function takes time from an injected clock and honours a module flag that disables refresh in tests. Imports, module constants and the conventions of surrounding declarations are what the span dropped. Attaching the file header and the enclosing declarations restores them for a fraction of the 900 lines.

   Read chapter
5. 5

   Whatever enters context becomes editable in practice

   A checkout task given the full implementation of packages/shared-auth comes back with a correct checkout patch and a convenient tweak to a shared helper, and CI is green because shared-auth's other fourteen consumers are not in this run. A model shown an implementation will edit it when that is the easier fix. Express the dependency boundary through what enters context: public interface, type stubs and docstrings, implementation withheld unless the task is that package.

   Read chapter
6. 6

   A default inclusion policy is judged by its exceptions

   Sorting candidates by retrieval score and filling to the cap is the wrong fill order; fill by role instead — the file being changed, the tests stating the behaviour it must preserve, the interfaces it depends on. Then the exceptions: checked-in protobuf output excluded in favour of the .proto, a vendored fork carrying an undocumented local patch, a tests tree larger than the source. Includes the answer to "index everything and use a bigger window".

   Read chapter