Context Engineering

Updated 5 Nov 2026

Context engineering means deciding exactly what information an AI sees at each step, not just how you word the instruction. Anthropic's rule of thumb: give the model the smallest set of genuinely useful information that gets the job done. More is not better; past a point, extra text makes the model worse.

What it is#

Every time Claude answers, it reads a block of text called the context window: its instructions, the tools it can use, the conversation so far, files it has opened, search results, and your latest message. That whole block is the "context".

Anthropic's Applied AI team made the term popular in a September 2025 engineering post, describing it as the natural next step after prompt engineering. They define it as the strategies for curating and maintaining the best set of tokens the model sees, including everything that lands there besides the prompt itself.

Why it matters#

1. Context rot. As the window fills, the model gets worse at recalling details from it. Anthropic notes this happens in every model, gently in some, sharply in others. It is a slope, not a cliff: the model still works, just less precisely.

2. The attention budget. Like a person's working memory, a model has a limited amount of attention to spread across what it reads. Every extra token spends some of it. The technical reason: in a transformer, every token relates to every other token, so 10,000 tokens means 100 million relationships, and the model's focus gets stretched thinner as text grows. Models also see shorter texts more often in training, so they have less practice with very long ones.

3. Cost and speed. You pay for every token on every turn, and longer inputs take longer to process. An agent that drags 300,000 tokens of old files along pays for them again on every step.

4. Bigger windows do not fix it. Claude now has a 1 million token window, but Anthropic expects windows of every size to suffer from clutter and relevance problems for the foreseeable future. A bigger desk still gets messy.

What goes into the context window#

Think of the window in two halves. The top is set once and reused: write it carefully and keep it short. The bottom grows every turn, and that is where most of the engineering happens.

How lopsided can it get? In Anthropic's cookbook test, a research agent read eight long documents with no context management. By the end its window held about 335,000 tokens, and 96% of that was raw file contents it had already read and taken notes on.

The techniques, with before and after examples#

There are eight techniques. The first four make each turn's context better. The last four keep long-running work from drowning in its own history.

1. Write the system prompt at the right altitude#

Anthropic describes two failure modes. One is hardcoding brittle if-this-then-that logic to force exact behaviour; it breaks on the first case you did not predict and is painful to maintain. The other is vague, high-level guidance that gives the model nothing concrete, or assumes it knows things it does not. Aim for the middle: specific enough to steer, flexible enough to let the model use judgment.

Before (too rigid):

CopyIf the customer asks about a refund AND the order is older than 14 days AND
the item is in category B AND the customer has fewer than 3 orders, reply
with template R-7. If the order is older than 14 days AND category A, reply
with template R-9. If...

Before (too vague):

CopyYou are a helpful support agent. Be friendly and solve problems.

After (right altitude):

Copy<role>
You handle customer support for Northwind, an online homeware shop.
</role>

<goals>
Resolve the customer's issue in as few messages as possible, while protecting
the business from refund abuse.
</goals>

<refund_policy>
- Full refunds within 30 days of delivery, no questions asked.
- After 30 days, offer store credit instead, unless the item arrived damaged.
- Anything over 200 GBP, or anything unusual, goes to a human: use escalate().
</refund_policy>

<tone>
Warm, plain English, no corporate filler. Short paragraphs.
</tone>

<output>
End every reply with the single next step the customer should take.
</output>

Why it works: it gives goals and principles the model can apply to new situations, one clear rule for the risky edge (escalate), and sections that are easy to update. Anthropic's advice is to start with a minimal prompt on the best model, test it, then add instructions only where it actually fails. Minimal does not mean short; it means nothing unnecessary.

2. Give it a small set of clear tools#

Tools are the contract between the agent and the world. Anthropic flags bloated toolsets as one of the most common failures. Their test: if a human engineer could not say for sure which tool to use in a given moment, the agent will not do better.

Before: 14 tools, including get_customer, fetch_customer, lookup_user, search_customers and customer_details. Each returns the full customer record: 4,000 tokens of addresses, every past order, internal flags and timestamps.

After: 4 tools with distinct jobs.

Copyfind_customer(email or order_id)  -> id, name, plan, open tickets (about 80 tokens)
get_orders(customer_id, last_n=5) -> date, item, status, total for each
issue_refund(order_id, reason)    -> confirmation number
escalate(summary)                 -> hands the case to a human

The agent picks the right tool every time, and each call adds 80 tokens instead of 4,000. Over a 30-turn conversation that is the difference between about 2,400 and 120,000 tokens of customer data sitting in the window.

3. Show a few great examples, not a rulebook#

Anthropic strongly recommends examples, but warns against stuffing in a long list of edge cases. For a model, a good example works like a picture worth a thousand words of rules.

Before: 40 rules covering every odd situation: "if the customer writes in all caps...", "if they mention a competitor...", "if they use an emoji...".

After: 3 to 5 varied, typical examples of ideal replies: one simple refund, one angry customer with a damaged item, one request that should be escalated. The model learns the pattern (tone, length, structure, when to escalate) and applies it to cases you never listed.

4. Retrieve just in time#

Instead of loading everything up front, give the agent lightweight pointers (file paths, saved queries, links) and tools to open them when needed. This is how Claude Code works: it does not read your whole codebase into memory. It searches for file names and text, opens what it needs, and uses commands like head and tail to peek at large files without loading them whole.

Before (everything up front): paste a 200-file codebase into the prompt. Around 400,000 tokens, most irrelevant to the bug, and the important file is buried in the middle.

After (just in time):

CopyTask: "Users can't reset their password"
1. search files for "reset"      -> finds auth/reset.ts, emails/reset.html
2. open auth/reset.ts             -> 180 lines
3. search for "sendResetEmail"    -> finds lib/mailer.ts
4. open the 40 relevant lines of lib/mailer.ts
Total loaded: about 3,000 tokens, all relevant.

Names and folders carry meaning too. A file called test_utils.py in a tests folder means something different from the same name in src/core_logic/. File sizes hint at complexity and dates hint at relevance, so the agent can explore layer by layer, a pattern Anthropic calls progressive disclosure.

The trade-off: exploring is slower than having everything ready, and a poorly guided agent can wander. So many agents use a hybrid: a little context loaded up front (Claude Code always reads your CLAUDE.md file) plus tools to fetch the rest. The hybrid suits steadier material like legal or finance work, where some reference text is always needed.

5. Compaction: summarise when the window gets full#

When the conversation nears its limit, the model writes a high-quality summary of everything so far, and a fresh window starts from that summary. In Claude Code, the summary keeps architecture decisions, unresolved bugs and implementation details, drops repeated tool output, and carries on with the five most recently opened files.

The skill is choosing what to keep. Too aggressive, and a detail that matters later is lost. Anthropic's advice: first tune the summary prompt to keep everything relevant, then trim the excess.

What a good compaction summary looks like:

Copy## Task
Migrate the billing service from Stripe v2 to v3.

## Done
- Updated payment-intent creation in billing/charge.ts
- Webhook handler now verifies v3 signatures (billing/webhooks.ts)

## Decisions
- Keep v2 refunds path until all old invoices settle (agreed with user)

## Open problems
- Test test_partial_refund fails: amount off by 1 cent, likely rounding

## Next step
Fix rounding in billing/money.ts, then run the full test suite.

In Anthropic's cookbook test, compaction turned a 169,000-token window into a summary of about 2,800 tokens, and the agent finished the task. The summary kept all three high-level facts the test checked for, but none of three obscure table values. That is the trade: the substance survives, exact small details may not. You can also give your own summary instructions, for example telling it to keep every number with its source.

6. Clear old tool results#

Once the agent has read a file and acted on it, the raw text rarely needs to stay. Tool-result clearing swaps old results for a short placeholder but keeps the record that the call happened, so the agent knows it can re-run it. Anthropic calls this one of the safest, lightest forms of compaction, and it costs nothing extra to run.

Before: after reading 8 documents, the window still holds all 8 in full: about 323,000 tokens.

After:

Copy[tool_use]    read_file(/research/celegans_review.md)
[tool_result] [cleared to save context]
[tool_use]    read_file(/research/mouse_review.md)
[tool_result] [cleared to save context]
...
[tool_use]    read_file(/research/rhesus_review.md)
[tool_result] (full text: most recent, so kept)

In the cookbook test this kept the peak near 173,000 tokens instead of 335,000. The catch: if the agent's notes were thin, it has to read some files again.

7. Take structured notes outside the window#

The agent regularly writes notes to a file (a to-do list, NOTES.md, a memory folder) and reads them back later. The notes survive summaries, restarts and new sessions.

Anthropic's favourite example is Claude playing Pokemon. Without being told how, it kept running tallies across thousands of game steps, such as how many steps it had spent training on one route and how many levels it had gained toward a target. It drew maps of explored areas and kept notes on which attacks worked against which opponents. After a context reset, it read its notes and carried on with multi-hour plans.

A practical NOTES.md for a long task:

Copy# NOTES.md: competitor pricing research
## Goal
Table of 12 competitors: plans, prices, free tier, last checked date.

## Progress
- [x] 1-7 done (see pricing.csv)
- [ ] 8. Acme Data: pricing page needs login, try their docs
- [ ] 9-12 not started

## Learnings
- Most sites hide enterprise prices; record "contact sales".
- Prices in EUR on 3 sites; converted at the date checked.

With Claude's API, the memory tool does this as a file folder the agent manages itself. In the cookbook, a second session that could read the first session's notes opened 4 documents instead of 8 and peaked at about 173,000 tokens instead of 334,000.

8. Split work across subagents#

A lead agent keeps the high-level plan and hands focused jobs to subagents, each with its own clean window. A subagent might read tens of thousands of tokens, but it reports back only a condensed summary, often 1,000 to 2,000 tokens. The messy search detail stays isolated; the lead just synthesises. Anthropic found this beat a single agent substantially on complex research.

Example: "Compare the AI data-licensing deals of 5 companies."

CopyLead agent: makes plan, spawns 5 subagents
  Subagent A: company 1 -> reads 14 pages (60,000 tokens) -> returns 1,500-token brief
  Subagent B: company 2 -> reads 9 pages  (40,000 tokens) -> returns 1,200-token brief
  ... (C, D, E run in parallel)
Lead agent sees: about 7,000 tokens of briefs, not 250,000 tokens of web pages
Lead agent writes the comparison.

Which long-task technique to use#

They combine. A long-running research agent might clear old file reads, compact the conversation when it passes a threshold, and save findings to memory for next week. Anthropic reported that context editing alone improved a long-task evaluation by 29%, and adding the memory tool cut token use by 84% across a hundred-turn run.

Worked examples, end to end#

Example A: a CLAUDE.md for a website repo#

Claude Code loads CLAUDE.md into every session automatically, so it is the always-on part of the hybrid approach. Everything in it is paid for on every turn, so it should hold only what Claude cannot easily discover by itself and gets wrong without.

Bad CLAUDE.md: 600 lines. A full copy of the README, every folder explained, the whole design system pasted in, a changelog, and 50 "never do X" rules collected over months.

Good CLAUDE.md (about 40 lines):

Copy# Project: marketing site (Next.js 15, Tailwind, deployed on Vercel)

## Commands
- pnpm dev        start locally on :3000
- pnpm test       unit tests (Vitest)
- pnpm lint       must pass before any commit

## Where things live
- app/            pages (App Router)
- components/ui/  shared components; reuse before creating new ones
- content/        page copy in MDX; edit copy here, not in components
- docs/brand.md   colours, fonts, voice: read before any visual change

## Conventions
- Server components by default; add "use client" only when needed
- Colours come from tailwind.config.ts tokens, never hex in components
- British English in all copy

## Watch out for
- The contact form posts to /api/lead, which emails via Resend.
  Never change its field names: the CRM import depends on them.

## Done means
lint + tests pass, page checked at 375px and 1440px widths.

What makes it work: commands Claude would otherwise guess, a map of where things live, pointers to longer docs (docs/brand.md) instead of pasting them in, the one fragile thing that is not obvious from the code, and a clear definition of done. The brand guide is fetched just in time, only when a visual change happens.

Example B: a customer support agent, one turn at a time#

A customer writes: "My lamp arrived broken, order 4471." Here is what the well-engineered agent's window holds at that moment:

The badly engineered version of the same agent loads the full customer record (4,000 tokens), every past order (6,000), the whole 30-page policy PDF (15,000), and the raw history of every earlier chat (8,000): about 33,000 tokens. It is slower, about 17 times more expensive per turn, and more likely to quote the wrong policy section because the right one is buried.

Example C: a research agent that runs for hours#

Task: "Build a market map of 40 AI training-data companies: what they sell, who they sell to, pricing model, notable deals."

1. Plan and notes first. The lead agent writes RESEARCH_PLAN.md with the 40 companies, the fields to fill, and a progress checklist. This file is the agent's anchor if anything resets.

2. Fan out. It spawns subagents in batches of 5, each covering 8 companies. Each subagent searches, reads 10 to 30 pages, and returns a compact table of rows plus source links, about 1,500 tokens, instead of the 100,000+ tokens it read.

3. Clear as it goes. Old search results and page reads in the lead's window are cleared automatically once used; their facts already live in the returned tables and in market_map.csv.

4. Compact when long. After several hours of back-and-forth with you ("add a column for funding", "drop consumer apps"), the conversation is compacted. Custom summary instructions tell it to keep every decision about scope and columns.

5. Remember for next time. Key findings and your preferences ("exclude consumer apps", "prices in USD") go into memory files, so next month's refresh starts from where this one ended rather than from zero.

Example D: handing work between agents (Claude Code, Codex, Hermes)#

When you switch tools mid-project, the new agent starts with an empty window. Copy-pasting the old chat is the worst option: long, noisy, full of dead ends. Write a short handoff file instead, ideally by asking the outgoing agent to produce it.

Prompt to the outgoing agent:

CopyWrite HANDOFF.md for another AI agent who will continue this work with no
access to our chat. Include: the goal, what is done (with file paths), key
decisions and why, what failed and should not be retried, open problems,
and the exact next step. Under 300 words. No narrative.

What a good HANDOFF.md looks like:

Copy# HANDOFF: lead-capture form rebuild
Goal: replace the old contact form with a 3-step form that writes to the CRM.

Done
- components/LeadForm.tsx: steps 1-2 built and tested
- api/lead/route.ts: validation with zod, posts to CRM sandbox

Decisions
- Kept the old field names (CRM import depends on them)
- No CAPTCHA yet; rate-limit by IP instead (user's call)

Failed, don't retry
- react-hook-form multi-step wizard plugin: breaks server actions

Open
- Step 3 (budget) not built; design in docs/form-spec.md

Next step
Build step 3 in LeadForm.tsx, then run pnpm test.

The incoming agent reads 300 words and is productive in its first turn. Keep HANDOFF.md in the repo and have every agent update it before stopping, and it becomes shared memory that works across tools.

Example E: context engineering in everyday Claude chats#

You do not need to build agents for this to matter. The same rules apply in the Claude app:

• Start a fresh chat for a new topic. A 200-message chat about your website will muddy a question about your tax return.

• Attach only the relevant files. One 5-page brief beats a 300-page folder dump.

• Use Projects for standing context. Put lasting background (brand guide, product facts) in a Project's knowledge and instructions, so you are not re-pasting it.

• Ask for a summary before switching. At the end of a long chat: "Summarise the decisions and open questions in 10 bullets." Paste that into the next chat.

• Point, do not paste. "The pricing is in the second table of the attached PDF" focuses attention better than pasting the whole PDF into the message as well.

Checklist#

Before you ship an agent, or start a long piece of work with one:

• Is the system prompt at the right altitude: goals and principles, not a wall of if-then rules or a vague one-liner?

• Is it split into clear sections (role, rules, tools, output)?

• Could a person always tell which tool to use? Are there any overlapping tools to merge or remove?

• Do tools return only the fields the agent needs?

• Are there 3 to 5 varied, typical examples instead of a long edge-case list?

• Is data fetched just in time with search and read tools, rather than pasted up front?

• Is the always-loaded part (system prompt, CLAUDE.md) short, with links to longer docs?

• Is there a plan for long sessions: compaction, clearing old tool results, or both?

• Does the agent keep notes or memory for work that spans hours or days?

• Would subagents help, for parallel research with compact reports back?

• Have you tested with real, messy tasks and added instructions only where it actually failed?

Common mistakes#

The rule that ties it together, in Anthropic's words: "do the simplest thing that works." Models are getting better at managing their own context, so expect to need less hand-holding over time, but treating context as precious and finite will stay the core skill.

Sources#

• Effective context engineering for AI agents, Anthropic Engineering

• Context engineering: memory, compaction, and tool clearing, Claude Cookbook

• Context compaction as a training objective, Blake Crosley (29% and 84% figures)

• Context engineering for agents explained, Developers Digest

• Anthropic context engineering notes, Agentic AI docs

• Anthropic's context engineering guide explained, The Neuron

• Anthropic context engineering coverage, eWeek