Context engineering: what an AI agent needs to see
Learn how to choose an agent's instructions, code and test results, avoid stale information, and distinguish context engineering from prompting and RAG.
Context engineering means choosing the instructions and information an AI model receives for its next step. For a coding task, that may include relevant files, agreed requirements and actual test results—not every file or every earlier message.
Imagine an agent fixing an upload bug. It needs to know that a file exactly at the size limit should be accepted, which code checks that limit and which test failed. A long conversation about an earlier, disproved guess can make that information harder to find.
An agent can have access to a whole repository and still miss the file that explains a bug. Access tells you what it could read. To understand its next action, inspect what it actually received: the request, selected files, previous messages and tool results.
Available files are not necessarily read files#
Each model call has an input. It can include instructions, the user’s request, selected conversation history, tool descriptions and results returned by those tools. A file sitting in the repository is not automatically part of that input. The application or agent must load it.
The same applies to saved memory. Find out which notes were loaded, whether they are current and whether they describe a confirmed result or an old guess. Saying that an agent “has memory” does not answer those questions.
Anthropic’s context-engineering guide describes managing this input as work continues. The job is not finished after writing the first prompt.
Give the agent the facts needed for this bug#
In this illustrative example, an upload rejects a file exactly at the allowed size. The requirement says it should be accepted. An earlier conversation blamed the browser, but a direct request to the server now fails too.
Task: explain why a file at the allowed size is rejected.
Available to retrieve
- Current requirementFiles at the limit are allowed.
- RepositoryUpload handler, validator, UI, other services.
- Run artifactsThe failed request and complete test log.
- Earlier discussionAn unproven browser explanation.
Selected for the next call
- InstructionInvestigate before changing another file.
- EvidenceThe server rejected the boundary request.
- Code and provenanceRelevant validator excerpt + revision.
- Requirement and unknownInclusive limit; proxy limit not checked.
Still available, not copied wholesaleFull logs, unrelated files and old discussion stay outside this call. Retrieve them when the next question needs them.
Illustrative context packet. Selection preserves provenance and uncertainty; it does not make a retrieved statement authoritative.
The next call should receive the agreed size rule, the relevant code and that reproduction result. It should also know that the proxy’s limit has not been checked. This does not prove which layer contains the bug; it gives the investigation a better starting point than the old browser-only guess.
Attach the code revision to an excerpt so the agent can notice when it is reading an older version. Keep a reference to the full log, but include the relevant failure in the immediate input. The model should not have to reread pages of routine output to find the same assertion.
Separate facts from instructions#
A source file tells the model how the application currently works. An instruction tells it what to do or avoid. Both occupy input space, but they can cause different problems.
Too much routine output can hide a failure. Too many unrelated procedures can hide the rule for the current task. Conflicting instructions are a different issue: “never change the schema” and “perform this migration” need a decision about which instruction applies. Making the prompt shorter does not settle that conflict.
HumanLayer’s instruction-file guidance recommends short shared guidance with references to specialist material. For this upload fix, load the size rule and the supported test command. Load a migration procedure only if the task actually requires one. Do not turn a suggested prompt length into a universal limit on how many instructions a model can follow.
Find out what is wrong with the input#
HumanLayer’s workflow considers size, correctness, completeness and trajectory. The last term means the direction earlier messages encourage the next step to take. Here is how those questions apply to the upload example.
| Situation | Take | Because |
|---|---|---|
| Routine logs hide the failing assertion. | Size | Include the important failure and keep a reference to the rest of the log. |
| An old note says only the browser checks upload size. | Correctness | Replace the outdated statement with what the current investigation found. |
| The input does not say whether a file at the limit is allowed. | Completeness | Find the agreed requirement or ask for the missing decision. |
| Every new attempt still assumes the browser is at fault. | Trajectory | Start from the direct server failure rather than continuing the disproved guess. |
- Situation
- Routine logs hide the failing assertion.
- Take
- Size
- Because
- Include the important failure and keep a reference to the rest of the log.
- Situation
- An old note says only the browser checks upload size.
- Take
- Correctness
- Because
- Replace the outdated statement with what the current investigation found.
- Situation
- The input does not say whether a file at the limit is allowed.
- Take
- Completeness
- Because
- Find the agreed requirement or ask for the missing decision.
- Situation
- Every new attempt still assumes the browser is at fault.
- Take
- Trajectory
- Because
- Start from the direct server failure rather than continuing the disproved guess.
This is a way to diagnose the input, not a formula for predicting accuracy. Each problem needs a different correction. Deleting half the text might reduce size while removing the one fact the agent needed.
How this differs from prompting and other agent work#
Making “fix the upload” into a clear instruction is prompt engineering. Choosing the code, requirement and failure report that accompany it is context engineering. The two overlap, but changing the wording cannot supply a missing fact on its own.
The test runner itself belongs to the harness, the software that gives the agent tools and a working environment. Returning a failed test for another permitted coding attempt is part of a loop. These names describe different pieces of the same task, not competing replacements for one another.
RAG, or retrieval-augmented generation, retrieves information to include when generating a response. It can help find the upload policy. The application still needs to handle an outdated document, a missing exception or two sources that disagree.
A matching search result can still be wrong#
In the example, the agreed requirement says what should happen. The code and reproduction show what happens now. A search result containing “upload limit” may establish neither. Keep the source, version and relevant scope with a finding so the next worker can judge it.
A retrieved document may also contain instructions aimed at the agent rather than useful information about the task. Treat retrieved text as data and limit what the tools permit. The harness guide explains why telling a model not to take an action is different from making that action unavailable.
Return findings instead of every search step#
A separate agent can investigate which upload paths check the size limit. It returns the paths, supporting references and areas it did not inspect. The main conversation receives the useful result without every search and file read. This is context isolation, and it can be useful even when the agents run one after another.
Inspect the findings before relying on them. “Every upload uses the shared validator” is not supported by checking only the browser route. Require the worker to say what it examined. A separate conversation is not automatically an independent review or a security boundary.
Tools can also return selected data rather than every available result. Anthropic’s code-execution example for MCP explores discovering relevant tools and filtering results before sending them to a model. Loading detail only when it is needed is often called progressive disclosure. The exact loading behaviour depends on the client, not simply on using MCP.
At a handover, save the current findings, decisions and unanswered questions with references. Preparing a shorter handover explains how to choose what the next task needs rather than summarise to an arbitrary length.
Notice when the conversation stops helping#
A model’s context window sets a limit on how much input can fit. It does not promise that every task remains equally reliable up to that limit. An old assumption or a buried requirement can cause trouble before the window is full.
Some practitioners call a useful session the smart zone and a confused session the dumb zone. These are informal labels, not two physical regions of the prompt. The context-rot guide explains when to continue, shorten the history, restart or delegate a specific investigation.
Change one problem and compare the results#
Find the first wrong action in a failed task and inspect the input at that point. Was the requirement missing? Was an old statement treated as current? Did the tool return so much output that the relevant error was hard to find? Change the cause you can identify.
Then compare representative tasks before and after the change. For the upload bug, check whether the agent finds the relevant validator, keeps the agreed inclusive limit and tests the boundary. Include unsuccessful attempts and the review work left to a person. A shorter prompt that produces the wrong fix is not an improvement.
IF YOU REMEMBER ONE THING
Inspect what the agent actually received before its first wrong action. Missing information, wrong information and too much irrelevant information need different fixes.
Questions people also ask
3 QUESTIONSDo I need RAG to do context engineering?
No. Selecting repository files and including a test result already changes the model's input. RAG, or retrieval-augmented generation, is one way to find information to include. It is not required for deciding what the model should receive.
Should a repository instruction file contain every procedure?
Keep the shared rules and a guide to finding task-specific instructions there. Load a migration or release procedure when the task needs it. Permissions and other safety restrictions must still be enforced by the tools, even when their full explanation is not included in a model call.
Must research subagents run in parallel?
No. A separate agent can do a detailed investigation and return the useful findings without filling the main conversation with every file read. Running several investigations at once helps only when they can proceed separately and someone checks how their results fit together.