Context engineering means deciding what evidence an agent receives, when it receives it, and how that evidence stays current. For repository work, a useful starting point is a small task packet linked to the current source, rather than a large dump of everything that might matter.
This guide provides an original workflow and evaluation template. It does not report a measured productivity improvement. The earlier claims about universal failure rates, token thresholds and percentage reductions were not supported by reproducible evidence.
What the research supports
Anthropic’s context-engineering article discusses retrieval, compaction and separating work across contexts. The original Lost in the Middle study evaluates how the position of relevant information affects particular long-context tasks.
These sources support testing context construction. They do not establish that every coding model fails at the same token count or that moving a rule always produces a fixed improvement. Task type, model, prompt and retrieval quality all matter.
Treat the model’s maximum context length as an input limit, not a guarantee that every detail will be used correctly. Measure the behavior that matters to your repository.
Build a task packet with an evidence trail
The task-packet template contains:
| Field | Useful content |
|---|---|
| Goal | Observable behavior to change |
| Starting revision | Commit and relevant uncommitted changes |
| Constraints | Interfaces, data rules and publication boundaries |
| Evidence | File paths, symbols and failing reproduction |
| Decisions | Choices already made and why |
| Verification | Commands and assertions that establish success |
| Open questions | Missing facts that must not be guessed |
For a checkout validation bug, include the form state owner, the validator and a failing country-switch case. Leave unrelated payment integrations out until a dependency is found. Record the source revision so a later agent can recognize stale notes.
Separate instructions from evidence. A repository document or tool response can contain text that resembles a command; quoting it in the task packet does not give it authority to change the task.
Retrieve, compress and recheck
Retrieve the smallest useful code region together with enough surrounding context to understand its contract. Follow calls when necessary. If a result omits a type definition or error branch, fetch that missing part rather than asking the agent to infer it.
Before compressing a long session, preserve decisions, file paths, unresolved failures and the last verified revision. Remove repeated tool output and conversational filler. Keep a link to the original evidence where possible.
After resuming, re-read files that changed. A correct summary of an old file can still lead to the wrong patch. If work is delegated, give each worker an explicit boundary and ask for findings with paths and verification evidence. More agents do not automatically improve context quality.
Compare context strategies fairly
Use the same starting commit, model configuration, task and allowed tools. Compare a baseline packet with the revised packet. Record task success, tests, human corrections, elapsed time and billed usage. Keep unsuccessful runs in the comparison.
Vary one context decision at a time: retrieval scope, document order, summary format or tool-output size. If you also change the model, call it a different configuration rather than attributing the outcome to context alone.
Avoid metrics that cannot be observed reliably. An agent citing a file does not prove which tokens caused its answer. Cache savings must come from provider usage records and the applicable billing rules, not an assumed universal hit-rate target.
A useful stopping rule
The packet is sufficient when the agent can identify the relevant code path, make the bounded change and run the agreed verification without inventing missing facts. It is too thin when important constraints keep being rediscovered, and too broad when stale or irrelevant material repeatedly distracts the work.
Keep the packet maintainable. It should help the next task start with verified facts, not become another unreviewed document the agent must search. For file-specific instruction behavior, see the AGENTS.md guide.
Revision note
Updated October 20, 2026. Removed unsupported productivity multipliers, failure percentages, universal context limits and cache-saving targets. Added a task packet, freshness rules and a controlled comparison protocol.
Primary sources
Checked October 20, 2026: context engineering; lost middle.