How much surrounding code do you hand an agent at the start of a session, and what does too much cost?

## Context is neither free nor neutral The intuition that more context can only help treats everything you hand over as inert reference material the run consults if needed. It is better to assume the opposite: **what you put in front of a session is read as a statement about how this codebase works, and tends to be imitated.** That makes context selection a decision with consequences, not an act of generosity. You are starting a many-turn run to add a retry policy to a parcel-tracking service's outbound webhook sender. You could hand over the sender package, the whole service, the neighbouring service that consumes the deliveries, and the last few months of related changes. The question is which of those alters a decision the run has to make. ## The test: does this change a decision? For the retry work, three things pass that test and almost nothing else does: - **the receiver's contract**, because it decides which failures are worth retrying at all; - **the stored shape of a delivery record**, because it decides whether a field may be added; - **one healthy current sender path**, because it decides the shape of the code you want back. | what you could hand over | which decision it changes | what it invites | |---|---|---| | the receiver's contract | what counts as a delivered event | little — it is a fact the run must not contradict | | the stored shape of a delivery record | whether a field may be added | little — it is the fence in evidence form | | one healthy current sender path | the house shape for this kind of code | imitation of that path's habits, good and bad | | the tired path you are replacing | none — it is the thing being removed | a replacement shaped like the original | | the whole service tree | none you can name in advance | material you never read, imitated as a model | Two rows in that table are the whole lesson. **Handing over the code you are replacing is the most natural mistake on this list**, because it is exactly the shape you were trying to get away from. Handing over one example of the kind of code you *do* want is the same act pointed at a different target. ## Three costs of the surplus 1. **Imitation.** Style, structure and habits present in the session tend to reappear in the output. Sometimes that is the point; when the supplied material is the thing being replaced or a part of the codebase nobody defends, it is a tax you chose. 2. **Attribution.** This is the cost people miss. When a wrong result arrives, you want to know which part of your instructions produced it, so you know what to change. If you handed over a large body of material, the answer could be your request *or* something you supplied, and your next move is a guess rather than an edit. 3. **Endorsement.** Material you put in front of a run is material you are implicitly holding up as fit to copy. Hand over a subtree you have not read and you have delegated the standard along with the work — and you still answer for what comes back. ## The opposite mistake is the more common one None of this argues for starving the session. Too little context has its own, very visible failure: a helper reinvented that already existed two files away, a convention missed, a contract contradicted because it was never shown. **What the run could see determines what it could get right**, and that cuts in both directions. The honest answer to "how much?" is *it depends*, and the dependency is nameable: does this material change a decision the run must make, or is it only nearby? ## When you cannot decide, prefer the contract to the implementation A useful default: hand over what something **promises** rather than how it currently **does** it. The receiver's contract constrains without supplying a shape to copy; the current implementation supplies a shape and constrains nothing. The first tends to produce code that is right; the second tends to produce code that looks like what was already there — which is what you want when you are matching house style and exactly what you do not want when you are replacing something. How large a unit of work the session can hold at once, and how you cut the work so it fits, is a separate question from this one. This one is about selection: even with unlimited room, the material you choose is a set of claims about what good looks like here. ## What a good answer sounds like Name the rule and then name the costs. *I hand over the contract, the record shape, and one current example of the thing I want; I keep out the code I am replacing; and when the result is wrong I want to be able to say whether my request or my context caused it.* That is a senior answer because it treats context as something you are accountable for having chosen, rather than as free help.