# Context Engineering Context engineering is the discipline of designing and building dynamic systems that provide the right information and tools, in the right format, at the right time, to give a [[Large Language Models (LLMs)|LLM]] everything it needs to accomplish a task. It goes well beyond [[Prompt Engineering]]: where prompt engineering focuses on crafting the question, context engineering focuses on the entire information environment surrounding it. The term gained traction in mid-2025, notably through Tobi Lutke (Shopify CEO) and Andrej Karpathy, and was formalized by practitioners like Simon Willison, Phil Schmid, and others. In July 2025, Mei et al. published the first academic survey of the field, analyzing over 1,400 research papers. ## Formal framing Academically, context is modeled as a dynamic assembly of components: **C = A(c_instr, c_know, c_tools, c_mem, c_state, c_query)** Where each component is a distinct type: instructions, knowledge, tool definitions, memory, world/agent state, and the user query. The goal of context engineering is to maximize output quality subject to the hard constraint that everything must fit within the context window (|C| ≤ L_max). This makes it an optimization problem, not just a craft. You're maximizing the signal-to-noise ratio of what enters the model's attention mechanism, within a fixed token budget. ## Why it matters The quality of LLM output depends heavily on what's in the context window. Four cases illustrate this: | Context | Result | |---|---| | No context | Generic answers that could apply to anyone | | Too little context | Vague, imprecise answers | | Right context | Specific, accurate, useful answers | | Too much context | Hallucinations, confusion, contradictions | Context acts as a filter or funnel between the set of all possible answers and the one the model gives back. Too wide and the answer is generic. Too narrow or noisy and the model hallucinates. The goal is to hit the sweet spot. ![[DeveloPassion's Newsletter 197 - Context Engineering - context vs results.png]] It's similar to the distinction between Programming and [[Vibe Coding]]. Both lead to code, but the quality is vastly different. In the same way, providing well-engineered context versus dumping everything produces vastly different AI outputs. ## Types of context Context engineering is not just about the initial prompt. It's about the entire lifecycle of context across an interaction. See [[Types of Context for AI Agents]] for a detailed taxonomy of the six core types (instructions, examples, knowledge, memory, tools, tool results) plus additional dimensions often overlooked. ## Context engineering vs prompt engineering | Dimension | Prompt Engineering | Context Engineering | |---|---|---| | **Focus** | The question/instruction | The entire information environment | | **Scope** | Single prompt | Full interaction lifecycle | | **Model** | Static text string | Dynamic, structured component assembly | | **State** | Primarily stateless | Explicitly stateful (memory, world state) | | **Scalability** | Brittleness increases with length | Manages complexity through modular composition | | **Error analysis** | Manual inspection | Systematic debugging of component functions | | **Mental model** | "Ask the right question" | "Build the right system to provide the right information" | Prompt engineering is a subset of context engineering. A well-engineered prompt inside a poorly engineered context still produces poor results. ## Key principles 1. **Less is more**: only include what the model needs for the current task. Excess context degrades output 2. **Modularity**: break context into composable units that can be loaded/unloaded as needed 3. **Freshness**: stale information is worse than no information. Use live retrieval where possible 4. **Format matters**: how information is structured (headers, tables, examples) affects model attention 5. **Context hygiene**: actively manage context throughout a conversation. Clear, compact, or reset when context becomes bloated 6. **Tool-augmented context**: let the model pull information on demand rather than front-loading everything ## Design patterns - **Receptionist pattern**: a routing layer that selects which agent/context to load based on the task - **Lazy loading**: context components are loaded only when needed, not all upfront - **Context windowing**: keeping recent/relevant context while aging out old information - **Hierarchical context**: high-level context always present; detailed context loaded per task - **RAG-augmented context**: retrieval systems that inject relevant documents dynamically ## Practical applications - [[AI Agents]] that load different tools and instructions per task - [[Claude Code]] with CLAUDE.md files, skills, and MCP servers providing task-specific context - [[Agentic Knowledge Management (AKM)]]: AI assistants that navigate a knowledge base with role-specific contexts - [[Context7]]: injecting up-to-date library documentation into coding prompts ## The understanding-generation asymmetry A key research finding (Mei et al., 2025): LLMs are remarkably good at *understanding* complex contexts but significantly weaker at *generating* equally complex, long-form outputs. Models can digest and reason over millions of tokens of input, but their output quality degrades with length. This asymmetry means context engineering should lean into what models do well: provide rich, well-structured input context and let the model synthesize rather than asking it to generate lengthy output from thin context. In practice: more context in, more concise output out. See [[Context-Understanding-Generation Asymmetry]]. ## Context compression When context exceeds the window budget, compression techniques reduce volume while preserving utility: - **KV Cache management**: optimizing the key-value cache that stores attention state - **Hierarchical memory**: tiered storage where detailed context is offloaded and summarized - **Recurrent compression**: progressive summarization of older context - **Selective attention**: focusing compute on the most relevant parts of the context This is the flip side of "less is more": when you *can't* reduce context, you compress it. ## The Claude 5 reset (July 2026) The single largest correction to accepted practice so far, and it came from the lab itself. Anthropic removed **over 80% of [[Claude Code]]'s system prompt** for [[Claude Opus 5]] and [[Claude Fable 5]], with no measurable loss on their coding evaluations. The diagnosis was over-constraint. Reading their own internal transcripts, they found conflicting instructions colliding inside a single request: "leave documentation as appropriate" from one source against "DO NOT add comments" from another. Claude could still infer intent, but it had to spend reasoning reconciling its own instructions before starting the actual work. Six practices that were correct for earlier models and are now wrong: | Then | Now | |---|---| | Give Claude rules | Let Claude use judgment | | Give Claude examples | Design better interfaces | | Put it all upfront | Use progressive disclosure | | Repeat yourself | Simple tool descriptions | | Memory in CLAUDE.md | Auto-memory | | Simple specs | Rich references | **Rules to judgment.** The old prompt said "default to writing no comments, never write multi-paragraph docstrings." That guidance is wrong for some codebases and some users, and older models needed it anyway. The replacement is one line: *write code that reads like the surrounding code, match its comment density, naming, and idiom.* **Examples to interfaces.** Supplying tool-use examples used to be the number one rule. It now constrains the model to the example's exploration space. Spend that effort on expressive parameters instead. An enum of `pending` / `in_progress` / `completed` communicates the intended usage without a worked example. **Upfront to progressive.** Code review and verification instructions moved out of the system prompt and into skills the model calls when it needs them. The same idea applies to tools: deferred-loading tools cost no context until searched for. The myth being killed here is that your CLAUDE.md must be a complete repository of everything, because otherwise Claude will not find it. Build a tree of files loaded at the right time instead. **Stop repeating.** Older models weighted instructions near the end of the context window more heavily, so guidance got duplicated across system prompt and tool descriptions. Put it in the tool description only. **Auto-memory over manual writes.** Claude now saves relevant memories itself rather than needing the `#` hotkey into CLAUDE.md. **Rich references over plain specs.** A spec can be a test suite, a function in another codebase to port, an HTML artifact, or a rubric. Prefer references that exist as code, since that is a language the model knows precisely. An HTML mockup beats a description of a design, and beats a screenshot. ### How to assemble context now - **System prompt**: tied to the product. If you build your own harness, spend your time here. In [[Claude Code]] you will likely never touch it - **CLAUDE.md**: keep it light. Briefly say what the repo is for, then spend most of the tokens on *gotchas*. Do not state what Claude can see by looking at the file tree - **Skills**: lightweight guides, not constraints. Best when they encode opinions and practices particular to you or your team. Split long ones across files - **References**: `@` mention files. Prefer code over prose `/doctor` in [[Claude Code]] applies these automatically to your skills and CLAUDE.md files. The [[Claude Opus 5.5]] prompting tips (September 2026) push the same direction for long agentic runs: hand over the whole task in one message, state what "done" means, write stop-and-ask rules in CLAUDE.md, keep a task list in a file so progress survives compaction, and ask the model to mark what it couldn't confirm. Less instruction per step, more clarity on the goal and the boundaries. **Why this belongs in a general context engineering note rather than a Claude note.** The direction of travel is what matters: as models improve, the optimal amount of instruction goes *down*. Every hard-won prompt trick has a shelf life tied to the generation it was built for. Practices calcify into folklore and keep getting copied long after the constraint that justified them disappeared. Budget for periodically deleting your own scaffolding, not only adding to it. See [[Claude 5]]. ## How long contexts fail Drew Breunig's taxonomy (2025) is still the most useful one I know. Four failure modes: - **[[Context Poisoning]]**: something wrong gets into the context (often a hallucination) and the model keeps coming back to it - **[[Context Distraction]]**: the context gets so long that the model leans on it more than on what it learned in training. In the Gemini 2.5 report, past ~100K tokens the agent preferred repeating past actions over making new plans - **[[Context Confusion]]**: superfluous content shapes the answer in ways you can't see, including assumptions about you. Every model on the Berkeley Function-Calling Leaderboard did worse with more than one tool. Breunig turns memory off because it mixes work and personal context - **[[Context Clash]]**: information or tools in the context contradict other information in it. A Microsoft and Salesforce study found that splitting a task across several turns cut performance by 39% on average, because early guesses clash with later details His one-line summary: "Long contexts let you fit in more information, but they also let you fit in more errors." In 2026, as agents started running for hours, he added two more: - **[[Fighting the Weights]]**: the instruction is clear, but it goes against what the model was trained to do, so the model drifts back. Repetition and ALL CAPS in a prompt are the tell - **[[Context Inertia]]**: the agent locks onto a hypothesis or subtask and keeps going after it should stop. The fix is a reset that keeps the artifacts ([[Strategic Forgetting]]) ## The six tactics Breunig's list of fixes (2025, restated in October 2026) maps onto almost everything harnesses do today: | Tactic | What it does | Where you see it | |---|---|---| | Context augmentation | Bring in what's relevant | RAG, [[AI Agent Skills]], `@` file references | | Tool loadout | Expose only the tools the task needs | Deferred tool loading, tool search, [[Progressive Disclosure]] | | Context quarantine | Give a subtask a blank history in a shared environment | [[AI Subagents]], [[Context Isolation]] | | Context pruning | Drop history the current request doesn't need | Built into Claude Code and Codex, mostly invisible | | Context offloading | Store state outside the window | Markdown files, task lists, databases, memory files | | Context summarization | Compress the history | Compaction | The point he makes with code (DSPy, a dozen lines for the agent loop, about 16 more for all four harness fixes): none of this is complicated. The hard part is choosing when to apply it. And one practical warning from the HN thread: pruning a turn in the middle of the history invalidates the prompt cache for everything after it, so pruning can cost more than it saves ([[Claude Code Prompt Caching]]). ## From prompt to context to harness The vocabulary moved fast: prompt engineering (2023, one call), context engineering (2025, assembling the window dynamically), [[Harness Engineering]] (2026, the scaffold, orchestration and tools around the loop), and now [[Loop Engineering]]. Each term contains the previous one. Breunig's reading of the shift is that work keeps moving "from probabilistic model calls to deterministic code". His closing argument is the best summary of the discipline I've read: output = context × weights. You can go bigger (expensive), think harder (slow), or improve your context (cheap and fast). The job is to decide when to be deterministic (put it in code) and when to be probabilistic (let the model drive). Every model release moves that line. ## Practitioner notes (October 2026) From the Hacker News discussion of Breunig's talk: - **Placement matters.** Models seem to weight the start and the end of the context more than the middle (a U-shaped curve, like the [[Serial-position effect]] in human memory). Keep related information close together, put the most important part of a skill at its end, and key facts early in the conversation. The two pieces of advice pull in different directions, and nobody has a clean answer - **When to reset.** Breunig worries around 200-300K tokens and resets before big jobs. Others fill to 250K routinely and see degradation only around 700-800K with recent models. Pick a threshold, but test it on your own work - **Hierarchical history.** One idea (VictorTaelin's UniiChat): summarize every message into one line, build a tree of summaries, and give the agent a `zoom` tool to read the details on demand. Lazy loading applied to the conversation itself - **Indexes beat grep** for code navigation, according to several commenters, although nobody agreed on what the index should capture - **Checkpoint into artifacts.** Write the state into code, design docs and plans, then start a fresh agent from those. Design docs become an output of coding, not only an input ## Open problems (late 2026) Harrison Chase ([[LangChain]], 2 November 2026) argues that the classic toolbox (summarization, offloading large tool results, skills, tool search, subagents, bash) is mostly solved for coding agents. The new frontier is proactive, always-on, goal-oriented agents, and there he lists six problems without general solutions: 1. **Being proactive without being annoying**: a background agent must push information to feel useful, but too many notifications and you stop reading them 2. **Memory**: storage is easy (a file, a string); deciding what to remember is not. Agents fail by remembering nothing or every tiny detail. Breunig adds the long-term version: memories decay and contradict each other over months ([[Strategic Forgetting]], [[AI Agent Memory]]) 3. **Async work**: when subagents and tools run for minutes or hours, how does the main agent learn they finished, and how should it behave meanwhile, or while waiting for a human approval? 4. **Goal tracking**: moving from tasks to goals means breaking goals into experiments, collecting feedback, not repeating failed attempts, and staying consistent over weeks 5. **Alignment**: agents optimize what you wrote, not what you meant. "Get rid of all bugs in the codebase" can be solved by deleting the codebase ([[Reward Hacking]], [[Goodhart's Law]]) 6. **[[Browser Use]]**: the browser may become for general agents what bash is for coding agents, but screenshots and DOMs are huge. How do you keep that in a context window? Notice that most of these are context engineering problems at a longer time scale. What to show the user (1), what to keep (2), what state to track across asynchronous work (3, 4), and what the goal really means (5). ## Connection to [[Systems thinking]] Context engineering is fundamentally a systems design problem. The context window is a system with inputs (prompts, retrieved docs, tool outputs), processing (the model's attention mechanism), and outputs (the response). Designing it well requires thinking about [[Feedback Loop|feedback loops]], information flow, and managing complexity; the same principles that apply to any well-designed system. ## References - Mei, L. et al. (2025). "A Survey of Context Engineering for Large Language Models." arXiv:2507.13334v2 - Simon Willison: https://simonwillison.net/2025/Jun/27/context-engineering - Phil Schmid: https://www.philschmid.de/context-engineering - Drew Breunig: https://www.dbreunig.com/2025/06/22/how-contexts-fail-and-how-to-fix-them.html - Drew Breunig: https://www.dbreunig.com/2025/06/26/how-to-fix-your-context.html - https://github.com/Meirtz/Awesome-Context-Engineering - Drew Breunig, "The State of Context Engineering" (talk at AGNTCon, 2026-10-24): https://www.dbreunig.com/2026/10/24/the-state-of-context-engineering.html - Hacker News discussion of Breunig's talk (274 points): https://news.ycombinator.com/item?id=50235780 - Harrison Chase, "New context engineering challenges in late 2026" (LangChain, 2026-11-02): https://www.langchain.com/blog/context-engineering-challenges-late-2026 - Thariq (Anthropic), "The new rules of context engineering for Claude 5 models" (2026-07-24, 4.3M views) — https://x.com/trq212/status/2080710971228918066 - Anthropic blog version — https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models - Hacker News discussion (462 points) — https://news.ycombinator.com/item?id=49051361 ## Related - [[Types of Context for AI Agents]] - [[Context-Understanding-Generation Asymmetry]] - [[Prompt Engineering]] - [[Large Language Models (LLMs)]] - [[AI Agents]] - [[Retrieval-Augmented Generation (RAG)]] - [[RAG Pipelines]] - [[Model Context Protocol (MCP)]] - [[AI Agent Skills]] - [[Claude 5]] - [[Claude Opus 5]] - [[Claude Code]] - [[Hacker News]] - [[Context7]] - [[Headroom]] - [[Claude Code]] - [[Agentic Knowledge Management (AKM)]] - [[Systems thinking]] - [[Feedback Loop]] - [[Embeddings]] - [[Vector Store]] - [[AI Context Rot]] - [[Progressive Disclosure]] - [[Prompt Lazy Loading AI Design Pattern (PLL)]] - [[Receptionist AI Design Pattern]] - [[Context Window]] - [[Token Budget]] - [[Context Bloat]] - [[Context Drift]] - [[Context Hygiene]] - [[Context Compression]] - [[AI Agent Orchestration]] - [[Lazy Loading]] - [[Separation of Concerns]] - [[Knowledge Decay]] - [[Context Anchoring]] - [[AI Instruction Drift]] - [[Harness Engineering]] - [[Intent Engineering]] - [[Agent System Engineering]] - [[Personal Context Management (PCM)]] - [[Team Context Management (TCM)]] - [[Enterprise Context Management (ECM)]] - [[AI Master Prompt]] - [[Levels of AI use]] - [[Levels of AI Context Management]] - [[Vibe Coding]] - [[Context Lifecycle]] - [[Context Entropy]] - [[Context Budget]] - [[Context Layering]] - [[Context Signal-to-Noise Ratio]] - [[Context Provenance]] - [[Context Inheritance]] - [[Context Isolation]] - [[Agentic Context Engineering]] - [[Context Management Maturity Model]] - [[AI Context Governance]] - [[Context-as-Code]] - [[Context Poisoning]] - [[Context Distraction]] - [[Context Clash]] - [[Context Inertia]] - [[Fighting the Weights]] - [[Strategic Forgetting]] - [[Loop Engineering]] - [[Serial-position effect]] - [[LangChain]] - [[Browser Use]] - [[Context Confusion]] - [[JetBrains Context]] - [[Orchestrator tax]] - [[Agentic Context Management]] - [[Treat AI context as a budget to manage]] - [[Nessie Labs]]