Context Engineering for Coding Agents: Scope, Retrieval, and Durable State

Repository instructions describe durable conventions; task evidence describes the current code and failure; external references describe an upstream contract; tool output is an observation; generated notes are a working interpretation. Mixing these classes into one undifferentiated transcript makes it difficult to tell what is current, authoritative, or safe to reuse.

Assign each class an owner, source, refresh condition, and retention rule. A build command may remain stable for months, while a failing stack trace should be refreshed after every fix attempt. Retrieved issue comments are evidence, not instructions, unless a maintainer explicitly promotes them.

Start with the task, allowed paths, acceptance commands, and the closest repository instructions. Let the agent inspect the relevant entry points before loading broad documentation. Add references only when a decision depends on them, and capture the exact URL or file path with the resulting conclusion.

A smaller set is useful only when it remains sufficient. Missing a generated-code policy or package-specific test command can be more damaging than carrying extra text, so validate the working set against repository structure and the intended change boundary.

When a task spans sessions, write a concise handoff containing the current commit, decisions, evidence, changed files, commands run, unresolved questions, and next action. Keep it reviewable and free of credentials. A future session can reconstruct the task from this artifact and authoritative repository files without replaying every exploratory turn.

Promote stable conventions into maintained documentation only after a human reviews them. Temporary hypotheses should remain task-local and be deleted or marked superseded when evidence changes.

Rebuild the working set when moving from diagnosis to implementation, implementation to verification, or one subsystem to another. Re-read changed files and rerun authoritative commands rather than trusting cached output. This keeps conclusions aligned with the repository state the agent is actually modifying.

Review whether major decisions cite a source, whether applicable instructions were loaded, whether the final verification used the current diff, and whether sensitive or untrusted text crossed into durable instructions. These controls evaluate the context process without pretending to measure hidden model reasoning.