A Brief Tour of Context Engineering

When I first started building with language models, I thought the prompt was the main thing. If the result was weak, I rewrote the prompt. I added more detail, a better example, maybe a stronger role. That worked when the system was one person asking one model for one answer.

Agents changed that mental model for me. The model is not only reading the prompt. It may also be reading system instructions, developer rules, files, images, tool definitions, tool results, examples, memories, and the conversation that brought it here. The prompt is still important. It is just one part of a much larger working set.

Context engineering is the art and science of managing what the model sees, reads, and thinks about in order to produce the result you want. It is not just about more text. It is deciding what the model sees, when it sees it, how it is ordered, what it should trust, and what should be left out.

That is the shift from prompt engineering to context engineering. We are no longer polishing one instruction. We are shaping attention.

The prompt is only one layer

Look at what enters a serious agent run. There is the user request, but underneath it sits a system prompt. Then developer instructions. Then repository files, screenshots, search results, tool schemas, tool output, examples, and conversation history.

All of that is context. Even the order matters. A useful fact buried underneath ten stale tool results is technically present, but presence is not the same as attention.

This is why I like thinking of context engineering as the invisible craft around the model. The model generates the answer. The system around it decides what world that answer is based on.

Bigger windows do not remove the design problem

Modern models can accept enormous context windows. It is tempting to see that number and think the problem is solved: put the whole repository in, include every document, keep the complete chat, and let the model work it out.

But capacity tells you what can fit, not what will be used well. The original Lost in the Middle research (opens in new tab) showed that model performance could change depending on where relevant information appeared in a long input. Newer systems have improved, but retrieval is only the easiest version of the problem. An agent still has to decide which instruction matters, connect evidence across files, and ignore material that looks relevant but is not.

A larger desk gives you room for more papers. It does not organise the papers for you.

Problem one: Lost in the middle

The first problem is attention across a long sequence. Information near the beginning and the end can be easier for a model to use than something buried in the middle. The fact has not disappeared. It has simply become harder to act on.

You can see why this matters in a repository. The agent reads the task first, then twenty files, then a tool result. The one constraint that should shape the implementation sits inside file twelve. If we rely on the model to treat every token equally, we are leaving the most important decision to chance.

The fix is not always to repeat the constraint. It is to surface it at the point where the model needs it.

Problem two: Distraction

The second problem is distraction. More context can make the model less focused when too much of it is only loosely related to the task.

Imagine asking an agent to fix one authentication bug, then giving it the entire codebase, six old implementation plans, three abandoned approaches, every terminal log from the week, and a long chat about a different feature. There may be useful information inside that pile. There is also a lot competing with the actual job.

This is where longer context can make a result worse. Not because the model ran out of space, but because we diluted the signal.

Problem three: Conflict

The third problem is conflict. A system instruction says one thing. A repository file says another. An old example uses a deprecated pattern. The latest user request quietly changes the goal.

If we pass all of that forward with equal weight, the model has to guess what to trust. Sometimes it follows the newest instruction. Sometimes the most specific one. Sometimes it copies the example because examples are concrete, even when the example is wrong.

Good context does not only contain the right information. It makes authority visible. Stable rules, current task, trusted source files, and untrusted tool output should not look like one flat block of text.

The chat should not be your project memory

This changed the way I work with coding agents. I do not want the chat to become the source of truth for the project. The chat is a temporary workspace for the task in front of me.

The source of truth should live somewhere persistent: a ticket, specification, project ledger, issue, plan, or repository instruction file. That is where I keep the goal, decisions, constraints, and what has already been completed.

Most advice for a full context window is compaction. Summarize the history, squeeze it into a smaller block, and keep the session alive. Compaction is useful, but I also treat it as a diagnostic signal. If I have to compact repeatedly just to finish one task, it is usually telling me the task was too big or the session collected too much exploration.

My version of context engineering starts before the agent ever runs.

Every project I build has a north star: one vision document that explains what the app is and how I am thinking about it. Any agent should be able to read it in one sitting and understand the world it is working in.

From there I break the big picture into features, and features into tasks. Each feature gets its own file: what it does, what done looks like, and nothing else.

My test for a task is simple. An agent with a small context window should be able to finish it. One task touches the animation. Another touches responsiveness. If I could not hand it to a small model, it is not atomic yet.

Each agent starts fresh. I keep one tracking file that records what was done, what was decided, and what everything depends on. A new agent reads that ledger, sees what happened before it arrived, and picks up cleanly. The debugging journey does not need to come with it. The context is fresh, but the project memory is not lost.

When I hand a task over, I give the agent the task, the relevant files, the skills I want it to reach for, and the ledger. What I deliberately do not give it is the exact steps. If I am too specific, I rob the agent of the chance to do a better job than my instructions. I only tighten up when the output tells me to.

And when a task still feels too big mid-run, I stop and cut it smaller. The first time I skipped all of this, everything ended in compaction and endless back-and-forth. The task never got smaller. Only the context got bigger.

Compaction can repair an overflowing session. Decomposition is how I try to avoid creating one.

Four moves I use when context starts drifting

Pruning comes before all of them. I try to remove irrelevant files, stale plans, old logs, and unapproved ideas before asking the model to reason over them. Then, once a session is running, I think in four moves: rewind, compact, clear, and isolate.

Rewind the wrong turn

Sometimes the session starts well and then moves in the wrong direction. The agent investigates the wrong part of the app, misunderstands a requirement, or spends several turns debugging something unrelated.

In that situation, I do not want to summarize the mistake and carry it forward. I want to go back to the point before it happened.

Claude Code checkpoints (opens in new tab) make this distinction useful. You can restore the conversation, the code, or both. You can also summarize only one side of a selected message. The tool matters less than the principle: if the agent takes a wrong turn, do not compress the wrong turn. Go back before it happened.

Compact when continuity still matters

Compaction says: this is still the same task, but the full history no longer deserves to remain in the working set.

I am not against it. In my own use, Codex has often felt more resilient after compaction. With Claude Code, I have sometimes felt the session lose its original train of thought, so I tend to clear more aggressively. That is my experience, not a benchmark.

What matters is that every summary makes a judgment about what survives. Claude Code's own context-window documentation (opens in new tab) shows that different instructions reload differently after compaction. If a detail matters beyond the current session, I do not leave it to the summary. I write it back to the ticket or ledger.

Repeated compaction is the warning I pay attention to. Sometimes a long feature genuinely needs it. But if I keep compacting just to power through, I stop and ask whether the task should be split.

Clear when the task changes

Clearing is different. It says: this context has done its job.

Once a task is complete and the result has been recorded, I start again. The next agent does not need the abandoned ideas, failed commands, and twenty messages it took to reach the solution. It needs the result and the next small task.

This only works because the chat is not my project memory. If the decisions exist only in the conversation, clearing is frightening. If they live in the repository, clearing is cheap.

Isolate noisy work with subagents

Some work produces a lot of context without needing to live in the implementation thread. Repository exploration, documentation research, logs, and large test output are good examples.

That is where I use subagents. They do the noisy work in their own context and return the useful result. Claude Code documents this as a fresh, isolated context window (opens in new tab), and I use the same pattern in Codex: independent research or review happens away from the main task, then comes back as a concise handoff.

I do not think of subagents as free context. Running several agents can use more tokens overall. The value is isolation and parallelism. The main thread stays focused on the decision it actually needs to make.

Context quality and context economics are different

There is another layer worth mentioning: prompt caching and token counting.

Prompt caching can make repeated context cheaper and faster. If a stable prefix contains system instructions, tools, or reference material, both OpenAI (opens in new tab) and Anthropic (opens in new tab) provide ways to reuse that processing work.

But cached clutter is still clutter. Caching changes the economics of context. It does not make irrelevant information useful.

Token counting gives you visibility before or during a request. I think of it like weighing your bag before a flight. It tells you how much you packed, not whether you packed the right things. Quality comes first. Cost and capacity come after.

Better judgment about context

Anthropic describes context engineering (opens in new tab) as the natural progression of prompt engineering, and that framing matches what I have noticed while building agents. Once the system can search, call tools, read files, and continue for many steps, the hard part is no longer writing one perfect prompt. It is keeping the model's working set useful as the world around it keeps changing.

The goal is not the smallest possible context. Too little context makes the model guess. The goal is the smallest context that preserves the facts, decisions, constraints, and evidence needed for the next action.

For me, that means one north star, features broken into tasks, small self-contained briefs, persistent project state outside the chat, and a deliberate choice about when to rewind, compact, clear, or delegate.

The future is not bigger context. It is better judgment about context.