Context Engineering
Definition
Context engineering is the design of everything a model sees before it acts: system prompt, tool definitions, skills, memory, and reference material. It replaces “prompt engineering” once the model is an agent rather than a single-turn responder, because the hard part stops being wording and becomes what to include, when to load it, and what to leave out.
The headline result: Anthropic removed over 80% of Claude Code’s system prompt for Claude 5-generation models with no measurable loss on coding evals. The old prompt was not helping — it was overconstraining.
Core Ideas
The overconstraint problem
Guardrails written for weaker models become contradictions in a stronger one. Internal transcripts showed conflicting instructions inside a single request — “leave documentation as appropriate” from one layer against “DO NOT add comments” from another — as system prompt, skills, and user request collided. The fix was deletion: let the model read the surrounding context and use judgement.
This is the general lesson. A rule that was load-bearing for last year’s model is dead weight, or actively harmful, in this year’s. Re-audit prompts on every model upgrade rather than accreting.
The six shifts
| From | To |
|---|---|
| Rules | Judgement — not “never write multi-line comments” but “match the surrounding code’s comment density, naming, and idiom” |
| Examples | Interface design — examples narrow the exploration space; instead make tool parameters expressive (a status enum implies correct usage on its own) |
| Everything upfront | Progressive disclosure — code review and verification live in separately-callable skills; deferred-loading tools require a ToolSearch before use and cost zero context until then |
| Repetition | Simple tool descriptions — put usage guidance in the tool description once, not duplicated into the system prompt |
CLAUDE.md memory | Auto-memory — the model saves what’s relevant to the work and to you, replacing the manual # hotkey habit |
| Simple specs | Rich references — a spec can be an HTML artifact, a detailed test suite, or a function in another codebase to port; rubrics let verifier agents check against your taste |
Practical rules
CLAUDE.md: keep it light. Spend the tokens on codebase gotchas — things the model cannot infer from reading the repo. Stating the obvious is negative value.- Skills: lightweight and opinionated. Split a long one across files rather than growing one wall of text.
- References: prefer real artefacts. An HTML mockup beats a description of a mockup, which beats a screenshot.
- Tooling:
/doctorin Claude Code rightsizes skills andCLAUDE.mdautomatically.
Model-Specific Prompting: Claude Opus 5
Anthropic’s own prompting guide for Opus 5 is the six shifts applied concretely. The pattern behind almost every item: the model already does the thing, so instructing it to do the thing makes it do it twice.
Remove, don’t add
- Verification. Opus 5 verifies its own work unprompted. Explicit “include a final verification step” or “use a subagent to verify” instructions cause over-verification — wasted tokens, no quality gain. Same for legacy harness scaffolding that bolts on a verify pass.
- Self-correction. “Double-check your answer” / “re-verify before responding” compound with behaviour the model already has.
- Conservative review framing. Opus 5 finds real bugs at high precision and recall. Telling it “only report high-severity issues” or “be conservative” gets taken literally and suppresses real findings — ask for everything, filter in a second pass.
- Vision workarounds tuned for older models may now be counterproductive; tool-driven crop-and-verify loops beat extra thinking.
Constrain deliberately
- Response length. Effort controls how much the model thinks, not how much it says — see Reasoning Effort Control. Lowering effort does not reliably shorten the visible answer; ask for brevity explicitly, and in a long system prompt repeat a short
<tone_preference>reminder near the end. - Narration. Opus 5 announces what it is about to do. Describe the cadence you want (“one sentence before the first tool call; updates only on a finding or a change of direction; lead with the outcome”). Positive examples of the style you want beat prohibitions.
- Written deliverables. Files written to disk run long. Ask for length matched to substance, no padding.
- Task scope. The model can widen a task using its own judgement about what it should be. For narrow work, state the boundary: deliver what was asked at the scope intended, flag a better approach in a sentence and continue rather than quietly transforming the task.
- Subagent spawning. Opus 5 delegates readily; delegation multiplies cost on small tasks. Give explicit criteria (genuinely independent, sizeable, parallelisable) or a hard cap. Never delegate verification of its own work.
Thinking disabled: two failure modes
Thinking is on by default and can only be disabled at effort high or below. With it off:
- Tool calls leak as text — the model writes the call into its visible response instead of emitting a
tool_useblock. The turn completes, the call never runs, and in an agent loop the leaked text poisons later turns. Most common on tool-heavy workloads like search. - Internal XML tags leak —
<thinking>and similar appear in output. A system-prompt rule telling the model not to think makes this worse.
One combined instruction mitigates both — permission to speak before a tool call, an escape hatch when no tool fits, and a general ban on internal tags. Naming the tags specifically works less well than the general form.
The real mitigation is not to disable thinking. For most tasks, thinking on at low effort beats thinking off at comparable cost.
The Counter-Case: Don’t Maintain a CLAUDE.md at All
Alex Jacobs takes the “keep it light” rule to its limit and argues for not writing the file. The essay is comic in tone and the mechanism it describes is real — it is the overconstraint problem observed from the user’s side rather than the model provider’s.
The file becomes a grievance archive
A system prompt maintained over time is a diary where every entry is a thing that hurt you. NEVER create documentation files, Do not add comments that restate the code, When a test fails, fix the code, not the test — each line is a laminated wound, and you walk past all of them to add the next one.
Every line is a law passed in anger
Rules get written at peak frustration and then live forever. Jacobs’ analogy: the worst legislation is passed forty-eight hours after something terrible happened and named after the person it happened to. There is no sunset clause and nobody repeals anything. The model improves every few months; the rules stay frozen at what it was bad at last spring.
The trap is that you cannot tell which lines have gone stale, because finding out means deleting one and seeing what breaks. So a meaningful share of a mature system prompt is plausibly making things worse — steering a smarter model away from things it would have got right.
The concrete failure mode: NEVER create documentation files was written about one unwanted summary.md. Months later the model refuses the README you explicitly asked for, citing your own rule back at you. It keeps commandments handed down in anger, faithfully, to the letter.
The harness argument
The sharper technical point: the weights were not released in a vacuum, they were released inside a harness. Claude is post-trained inside the Claude Code harness, so what ships is not “a model plus a text file” — it is a model shaped run-after-run against that exact context. Every line you add swaps in a context that has never existed before, which is why the resulting weird failure modes are unreproducible: nobody else has your context.
Jacobs also notes that a rule does not reliably fix the thing it was written to fix. The output looks like obedience and you cannot tell from the output whether it is.
The alternative: correct in the session, not in the file
His practice — following Peter Steinberger’s just talk to it — is to correct the model in the chat, at the scene, while the context of the mistake is still in context. The correction dies when the session ends, and that is the point: a spoken correction applies where it belongs instead of binding every future model. Compare the auto-memory shift above, which is the harness-supported version of the same instinct: let what persists be selected by relevance rather than by remembered frustration.
The honest caveat is in the essay itself — even Steinberger keeps an 800-line agent file he calls “organizational scar tissue.”
Contradictions
The two sources on the agent instruction file reach opposite conclusions about whether to write style rules down at all.
Fabien Sanglard — write the rules down. His path: mid-2025 LLM output would not compile; January 2026 output worked but was “spaghetti code with no comments and no structure”; March 2026 agentic IDEs let him iterate on staged code, and quality reached near hand-written — but only by repeating the same review comments (“don’t use magic numbers”, “add a short comment here”) in every new session. agent.md is where that repetition goes to die. When he catches himself giving the same suggestion twice, it becomes a rule in the file.
His rule set is concrete style, not philosophy — minimum words in anything written for humans, no superlatives, extract magic numbers into named constants, early return over the arrow anti-pattern, function names under 30 characters, enums instead of boolean parameters, blank lines between logical blocks, a short comment on what and why, fields private unless the design requires otherwise, layered boundaries with no hole-punching, always braces, the seven-rule Git commit message format, and test-first when the prompt says “bug”.
Alex Jacobs — don’t (see above): every added line swaps in a context the weights were never post-trained inside, and the output looks like obedience whether or not the rule worked.
The tension is real but narrower than it looks. Jacobs argues against remembered frustration — a rule added because the model annoyed you once. Sanglard’s file is almost entirely taste that would be true of a human contributor too, the kind of thing a repo style guide holds. The Anthropic position sits between them: keep CLAUDE.md light and spend the tokens on codebase gotchas the model cannot infer from reading the repo, and note the six shifts move rules → judgement precisely by describing taste (“match the surrounding code’s comment density, naming, and idiom”) rather than enumerating prohibitions — which is what several of Sanglard’s rules already do.
Attention dilution
Sanglard’s practical worry, grounded in the Lost in the Middle paper: as context grows the model attends less to instructions in the middle, favouring the beginning and end. Two mitigations he uses —
- Keep the context short — one new session per feature.
- Ask the harness to reload the file — “Reload agent.md” is enough when he sees quality dropping.
This is the mechanical argument for the same conclusion the six shifts reach from the other direction: a long instruction file is not just wasted tokens, it is unreliably applied tokens. It also matches the Opus 5 guidance above to repeat a short tone reminder near the end of a long system prompt.
He keeps the file itself agent-maintained — he asks the agent to add new rules rather than opening an editor. And the honest limit, in his words: this is not a magic bullet that lets him avoid reading the code. He still verifies and iterates; the gain is that his attention moved from style to architecture and design.
Relationships
- Reasoning Effort Control — the serving-side knob these prompts sit on top of
- Loop Engineering — designing what makes an agent stop, where this page designs what it sees
- Model Context Protocol (MCP) — how tools enter the context in the first place
- Retrieval-Augmented Generation (RAG) — the other main way context gets assembled
- AI Engineering Pitfalls — failure modes on the application side
- Coding Agents and AI Tools — parent topic
- Knowledge Management —
CLAUDE.mdand skills as a maintained knowledge layer - Agent Skill Evolution — the ablation showing an agent given the knowledge base during a run produces less useful traces
- AI-Native SDLC —
CLAUDE.mdand skills as versioned artifacts in a full delivery process
Source References
- The new rules of context engineering for Claude 5 generation models — Thariq Shihipar, Anthropic, 2026-07-24
- Prompting Claude Opus 5 — Anthropic docs
- I Am Morally Opposed to Updating My CLAUDE.md — Alex Jacobs, 2026-08-19
- My agent.md to improve LLM-assisted code quality — Fabien Sanglard, 2026-08-24