A coding agent deletes an apparently unused API response field. Local tests pass. The patch is small. An older mobile client still requires the field, but its support commitment lives in a separate migration plan.
This illustrative failure exposes two weaknesses: the development workflow did not supply the compatibility requirement, and its tests did not enforce it.
A more detailed prompt might prevent the next mistake. Context engineering asks how every relevant task will receive that requirement, which version applies, and what happens when the evidence is incomplete.
That is the architectural argument: when agent behavior depends on information moving between repositories, documents, tools, and sessions, those connections become dependencies in the software delivery system. They need explicit interfaces, ownership, and failure handling.
For engineering leaders, the consequence is practical. Code generation can move work forward while leaving reviewers to reconstruct requirements the agent never received.
Diagnose the information gap before adding context
Giving an agent repository access is a reasonable starting point. Code reveals implementation patterns, dependencies, and existing behavior. It may not reveal why a customer must remain on an older API version or which deployment sequence a migration requires.
The assumption that more repository context will close every gap is incomplete. Different failures call for different interventions:
| Failure | Appropriate response |
|---|---|
| The compatibility requirement is unavailable | Publish it in an accessible, authoritative source |
| The requirement exists but is not discovered | Improve the task reference or discovery path |
| Guidance applies to another release | Record scope and retrieve the applicable version |
| Two applicable sources disagree | Have the responsible owner resolve the conflict |
| The agent understands the constraint but implements it incorrectly | Investigate reasoning, tooling, and verification |
Do not diagnose from the final patch alone. Inspect the available task record, retrieved material, and execution results. If the cause remains unclear, test a focused intervention.
In the API example, supplying the migration policy addresses an information gap. Adding a contract test addresses an enforcement gap. Both matter.
What context engineering means for coding agents
Context engineering for coding agents means selecting, supplying, and maintaining the information they use as a task progresses.
A prompt specifies the task and instructions. Repository context supplies code and supporting material. Retrieval selects additional information. Memory preserves state for later use. Documentation is one source within this process.
Crucially, information an agent can access is not necessarily information it has loaded into the model’s working context. Anthropic’s context engineering guidance describes managing that input across instructions, tools, retrieved data, and interaction history.
The relevant input changes with the work. Planning needs constraints and acceptance criteria. Implementation needs interfaces and examples. Verification needs observed results. Resuming an interrupted task needs an accurate account of completed and unresolved work. A larger context window provides capacity. Authority, relevance, and freshness still require decisions.
Define a context contract for one workflow
AI context management becomes an architectural concern when reliable delivery depends on those decisions being repeatable. This concerns the architecture of the delivery system and its ability to preserve application constraints. It can matter within a single team.
Start with a context contract: a lightweight record of the information a workflow requires, where it comes from, and what to do when it cannot be established. This is a proposed working framework, not an industry standard.
For public API changes, the contract could look like this:
| Dimension | What to record | Illustrative API application |
|---|---|---|
| Authority | Canonical source and what it governs | Approved compatibility policy governs field removal |
| Scope | Applicable services, releases, and environments | Policy covers the public API and supported mobile releases |
| Version | Revision or applicability evidence | Identify the code commit and relevant migration decision |
| Ownership | Who resolves ambiguity and maintains guidance | API owner coordinates with the mobile owner |
| Access | Authorized retrieval path | Approved repository or documentation access |
| Verification | Checks and decision conditions | Consumer contracts pass; unresolved support status blocks removal |
Keep references to canonical information. Copying the same policy into multiple agent files creates more places that can diverge.
Make uncertainty change the next action
If supported client versions cannot be established, the task should record that uncertainty and seek a decision from the owner before removing the field.
If an old example permits immediate removal while an applicable migration decision requires a transition period, document which guidance supersedes the other. A recent edit timestamp alone cannot settle applicability.
If a required source is unavailable, the workflow should identify the blocked decision and what can still proceed safely. It should not silently substitute an agent’s recollection.
These rules turn the framework into an operational interface: required inputs, responsible owners, and defined behavior when inputs fail.
Put enforcement outside the model
Use tests and technical controls for constraints that can be enforced. Contract tests should exercise the supported response shape. Dependency checks can enforce module boundaries. Tool permissions should be enforced by the execution environment.
Treat retrieved documents and tickets as evidence with defined authority. Instructions embedded in retrieved content should not expand tool permissions or authorize unrelated actions. A written instruction alone cannot guarantee that boundary.
Organize context by lifespan
A practical AI context architecture can begin with versioned files, targeted references, and repository search. Separate durable guidance, task evidence, and session state because each changes for a different reason.
Durable guidance: recurring constraints
Keep stable, non-obvious requirements near the code they govern. Include useful entry points and commands, with owners responsible for reviewing them when the workflow changes.
An illustrative instruction is:
Before removing a public response field, consult the compatibility policy and supported-client record. Run the consumer contract suite. If removal eligibility is unresolved, ask the API owner for a decision.
This is more actionable than a directory inventory or generic advice to “follow best practices.” Its usefulness still needs evaluation.
Apply shared principles broadly and service-specific requirements locally. Avoid loading one service’s release process into every repository.
Task evidence: the current decision
For teams deciding how to provide context to AI coding agents, a task packet makes the required inputs explicit. For the API cleanup, include the requested removal, acceptance criteria, checked-out revision, applicable policy, supported-client evidence, serializer entry point, and verification commands.
Do not silently change the goal from deleting a field to preserving it. Make the decision visible: removal may need to wait, or proceed through an approved versioned migration. A justified deferral can be a correct outcome.
Session state: observations and remaining work
A handoff should preserve changed files, repository state, checks run, exact failures, unresolved questions, and the next action. Distinguish “the legacy response test fails” from “the legacy test is obsolete.” The first is an observation; the second needs evidence. Before resuming, confirm that the working tree and requirements still match the handoff.
Choose retrieval according to the discovery problem
Preload constraints needed before planning. Retrieve detailed implementation evidence as the task narrows.
The right mechanism depends on what repeatedly prevents discovery:
| Approach | Useful when | Main trade-off | Maintenance responsibility |
|---|---|---|---|
| Preloaded guidance | A constraint applies to most tasks | Repeated input and irrelevant instructions | Guidance owner reviews scope |
| Repository search | Evidence lives in accessible files | Discovery depends on names and terminology | Teams maintain references |
| Indexed retrieval | Relevant knowledge spans many sources | Stale indexes and ranking errors | Index owners maintain freshness and access filters |
| External tools | Tasks require current system records | Availability, latency, and permission dependencies | Integration owners maintain access and failure handling |
Exact search suits known symbols and error messages. Semantic retrieval can find related concepts expressed differently, but relevance scores do not establish authority.
Retrieval-augmented generation is one option. Evaluate shared retrieval infrastructure when ordinary search repeatedly fails to locate necessary evidence and the expected benefit justifies operating another dependency.
Return source identity and version or retrieval time with external results. Enforce authorization before information reaches the agent.
Treat instruction-file benefits as a hypothesis
More guidance is not automatically better, and the available research does not support a universal recipe.
Evaluating AGENTS.md evaluated repository instruction files across coding agents. In its settings, automatically generated files produced no statistically significant improvement in task resolution while increasing average inference costs by about 20–23%.
On the Impact of AGENTS.md Files examined 124 pull-request tasks across 10 repositories using one agent configuration. It reported lower median runtime and output-token use with instruction files. However, comprehensive correctness evaluation was outside its scope; a manual check of 50 sampled tasks screened for obviously incomplete or irrelevant output.
These are different measurements. Faster generation does not establish that accepted changes became cheaper or equally correct. Neither study validates the context contract proposed here.
The practical implication is to evaluate the guidance your workflow actually needs, including its maintenance cost.
Measure accepted outcomes before expanding
Choose one recurring workflow and define success before running the comparison. For API changes, acceptance might require preserved compatibility, appropriate migration evidence, and review approval.
Establish a baseline using representative tasks. Then introduce one focused change, such as the compatibility reference and required supported-client check.
Keep starting repository states, task requirements, permissions, and model settings comparable. Record the model version and agent harness—the software coordinating tool use and execution. Repeat trials where feasible, and keep evaluation checks consistent across conditions.
Measure:
- Correct completion, including justified deferrals where appropriate.
- Compatibility or architectural violations.
- Reviewer corrections and review time.
- Elapsed time and model costs.
- The effort required to maintain guidance and retrieval.
Count all attempts when calculating cost per accepted outcome. Otherwise, a workflow that cheaply generates many rejected patches can appear efficient.
Assign maintenance to existing owners: service engineers maintain domain constraints; platform engineers maintain shared retrieval where needed. Add guidance review to changes that invalidate it.
Expand only when the observed improvement justifies the ongoing work.
Make essential knowledge a delivery dependency
Context engineering gives engineering leaders a concrete design question: which decisions depend on knowledge the workflow does not reliably supply?
Start with one recurring review correction. Trace the missing information to its authoritative source. Define when it must be available, who maintains it, and which check enforces the resulting constraint.
The architectural responsibility is to make these dependencies visible and maintainable. A growing collection of instructions is useful only if it improves the decisions made with it.
Which requirement does your team repeatedly rediscover in review that should become an explicit input to the work?
Top comments (0)