Fieldnotes / engineering

Context engineering

Explanation

What the model can see

Context is the information supplied for a particular invocation. A file on disk is not automatically part of that input.

Distinguish information that exists from information actually supplied to the model.

  1. 0s A contract file exists in the repository. That does not mean the model has read it.
  2. 7s The application selects information. Only selected content enters this input.
  3. 14s The model receives the assembled input. It can use the supplied contract.
  4. 21s Context is specific to this invocation. Check what was actually included.

Retrieve relevant evidence

The task is to fix invoice latency. Retrieval should bring in the code and contract that constrain that change, not every nearby document.

Relevance is a selection problem. Retrieved content still needs checking for authority and applicability.

  1. 0s The task is to fix invoice latency. Find evidence that constrains this change.
  2. 7s Retrieve the endpoint and v1 contract. They explain behavior that must remain.
  3. 14s Supply those records to the model input. Include where each record came from.
  4. 21s More material is not always more useful. Select evidence that changes the decision.

Preserve a constraint

Existing clients expect total_cents. An optimization must keep that field. The constraint needs to be visible when the agent chooses its edit.

State what must remain unchanged and reference the authoritative contract. The model still needs verification.

  1. 0s Clients expect the field total_cents. Latency work must preserve that contract.
  2. 7s Include the unchanged-field requirement. Keep its contract reference with it.
  3. 14s The agent proposes a compatible edit. The field name stays total_cents.
  4. 21s A visible constraint guides the edit. A check must still verify the result.

Make a useful handoff

A resumed task needs a concise record of the goal, important constraints, evidence and unresolved work. Summarization can lose crucial details.

A handoff is a shorter representation, not perfect memory. Preserve references so the next session can retrieve omitted detail.

  1. 0s The current session must hand work over. A vague summary can lose the contract.
  2. 7s Record the goal and unchanged field. Keep evidence and open questions too.
  3. 14s The next session receives the handoff. It can retrieve the source when needed.
  4. 21s Shorten incidental history first. Do not silently drop decisive constraints.

Verify the patch

A saved compatibility fixture checks that the optimized endpoint still returns the required field. Run it against the actual changed code.

Good context reduces ambiguity; it does not prove the result correct. Verification closes the gap.

  1. 0s The patch claims to preserve compatibility. The claim still needs evidence.
  2. 7s Run the v1 response fixture. Check the actual response field.
  3. 14s The response still has total_cents. The checked contract is satisfied.
  4. 21s Keep the result with the patch revision. Context and verification work together.
Read the guide

The idea

Context is the information supplied to a model for a particular invocation: instructions, conversation, tool descriptions, and retrieved results. Files on disk are not automatically visible. Retrieval brings evidence in; trimming removes material; compaction replaces detail with a shorter representation. These are separate choices, not a guarantee that the agent remembers correctly. Anthropic’s engineering account describes this continuing curation process [1].

Where it helps

A senior engineer knows which API contract must survive a refactor; a newly resumed agent needs that requirement supplied again. Lost in the Middle found sensitivity to evidence position on the models and retrieval tasks it studied [2]. That motivates testing your workflow, not assuming every current model fails identically. More input is not automatically better or cheaper: caching changes processing cost and latency, while additional retrieval has its own overhead [1, 4].

Use this when a team first delegates debugging or changes that span several agent sessions. It turns the engineer’s implicit working knowledge into an inspectable handoff and makes missing context a testable failure.

Suppose an agent is fixing slow invoice requests. Existing clients require the v1 response field total_cents. A handoff saying “optimize invoice endpoint; unit tests pass” omits that constraint. A resumed agent might rename the field to amount while fixing the timeout. Preserve the contract reference, the unchanged field requirement, and a compatibility fixture; rerun that fixture against the actual patch. This is an illustrative failure, not a measured model result.

What you will be able to check

  • Build a task packet containing the goal, constraints, evidence references, and verification command.
  • Detect a lost requirement by restarting from a deliberately incomplete handoff.
  • Separate a reported test result from a result reproduced on the current patch.

What changes in the team

Today
An engineer remembers the v1 contract, searches relevant code, and explains unfinished work verbally to a teammate.
With an agent
The engineer gives an agent a task packet; each handoff records constraints, current patch state, source references, unresolved questions, and checks to rerun.
Still your responsibility
Choose authoritative requirements, check the handoff against them, and approve the patch only after appropriate verification.

Work through an example

  1. Define the slice: fix the invoice timeout while preserving v1 total_cents. Record the contract path and revision, the failing request, and a command that tests compatibility. Do not make “improve performance” the entire brief.
  2. Load the failing trace and endpoint implementation. Follow a caller or schema reference when it answers an open question. Record what was inspected and what remains uncertain; a plausible explanation is still a hypothesis.
  3. Before restarting, write a compact handoff with separate fields for goal, constraints, evidence, changes, checks, and next action. Include exact test commands and their observed status. Inspect it for the v1 requirement instead of assuming summarization preserved it.
  4. Resume with the handoff and source access. Reopen the contract, inspect the current patch, and rerun the compatibility fixture. If the fixture fails, correct the patch and repeat the check; a green result only establishes what that fixture covers. Measure the timeout scenario separately: preserving a response field does not establish a performance improvement.

The engineering decision

Keep non-negotiable constraints explicit. Keep bulky evidence retrievable through precise paths and revision identifiers. Ask whether the next engineer could verify each claim without trusting the previous agent’s prose. Anthropic’s long-running-agent experiments support structured progress artifacts and fresh checks, but describe one workflow rather than a universal recipe [3]. The human still owns requirement interpretation and acceptance.

  • Keeping a path in notes but never loading its contents before the relevant decision.
  • Treating a summarized “tests pass” as current evidence after files have changed.
  • Deleting a subtle compatibility constraint while retaining pages of obsolete tool output.
  • Treating instructions in context as enforced permissions; tool authorization must be controlled outside the prompt.

Try it with your team

Break and repair a handoff

  1. Choose a disposable endpoint fixture with one compatibility rule and a small requested change.
  2. Prepare two handoffs: one omits the rule; one includes the rule, its source, and the test command.
  3. Start fresh agent sessions with each packet and the same source access. Record whether the agent retrieves the rule; do not force a failure if it discovers it independently.
  4. Inspect both patches and run the same fixture. Compare omissions and retrieval behavior, then improve the packet.

You have an answer when…

  • The complete handoff makes the requirement and source identifiable before editing.
  • The team can reproduce the fixture result and explain what it does not cover.

Read further

Restart a small task from its handoff alone. Can the next agent identify the compatibility constraint, retrieve its source, and reproduce the claimed test result before editing?

Original video comparisons