hack/tools/scripts/llm-key-hunter/results/_cache/content/agenticoding_agenticoding.github.io.json

{"repo": "agenticoding/agenticoding.github.io", "files": {"website/docs/context-engineering.mdx": {"823036f09192e5dd3734307031de1db90c23822f": {"t": 1786068097.3116362, "n": 32641, "h": "e777bff31d4a5586", "c": "---\ntitle: 'Context Engineering'\n---\n\nimport ContextPressureDiagram from '@site/src/components/VisualElements/ContextPressureDiagram';\nimport ContextStreamBlock from '@site/src/components/VisualElements/ContextStreamBlock';\nimport { contextManagementStream } from '@site/src/components/VisualElements/contextStreamData';\nimport ContextMechanismMap from '@site/src/components/VisualElements/ContextMechanismMap';\nimport SkillsInvocationDiagram from '@site/src/components/VisualElements/SkillsInvocationDiagram';\nimport SubAgentDiagram from '@site/src/components/VisualElements/SubAgentDiagram';\nimport ContextSqueezeDiagram from '@site/src/components/VisualElements/ContextSqueezeDiagram';\nimport MCPToolSchemaDiagram from '@site/src/components/VisualElements/MCPToolSchemaDiagram';\nimport ArchitectureDiagram from '@site/src/components/VisualElements/ArchitectureDiagram';\nimport UShapeAttentionCurve from '@site/src/components/VisualElements/UShapeAttentionCurve';\nimport DiagramFrame from '@site/src/components/VisualElements/DiagramFrame';\n\nThe agent loop rebuilds context each turn. Instructions, tool definitions, conversation history, file reads, search results, and your current task — everything enters the same window, and the model predicts from all of it. What enters, where it lands, and when it expires determines whether the model can do useful work.\n\nContext engineering is the practice of shaping each LLM call's context to be optimal for its task. It applies to every call — not just when the window is full. A fresh session with a clear task benefits from the same thinking as a 1M-token conversation approaching compaction.\n\nThis chapter covers the six mechanisms that control what enters the context window and where: **context files**, **MCP tool schemas**, **skills**, **sub-agents**, **context compaction**, and **retrieval**. Each changes the parent context differently: some enlarge its fixed prefix, some append task-specific material, some replace accumulated history, and some keep work in a separate window. The sections that follow start with the fundamental constraint — why position in the window matters — then work through each mechanism.\n\n## The Attention Curve: Why Placement Matters\n\n<DiagramFrame kicker=\"Context management\" title=\"Attention is strongest at the edges\" size=\"standard\" caption={'Attention is reliable near the beginning and end of the window; the middle degrades first as context fills.'}>\n\n<UShapeAttentionCurve />\n\n</DiagramFrame>\n\nDrag the slider to 50%. The diagram is normalized: 50% means halfway through the window, whether the window holds 10K, 100K, or 1M tokens. The same failure exists at every size. What changes is the scale of the weak middle. At 50% fill, those windows contain 5K, 50K, and 500K tokens respectively. The model must find relevant information amid ever more competing context. A larger window gives the agent more room; it does not give the agent uniform recall across that room.\n\nThe valley is not fixed — it deepens as the window fills. Every diagram in this chapter renders this same curve, so watch the middle band: it darkens from benign to degraded to collapsed as context pressure grows.\n\nThree zones emerge from the curve. The **primacy zone** at the start — where system instructions, user rules, and project files land. The **recency zone** at the end — where your current task and recent tool results sit. And the **dead center** — the middle of the window, where attention drops off sharply.\n\n**Why does this happen?** Recall that attention is relevance-weighted context mixing, not memory. For each next token, a causal transformer builds a new weighted mix of the tokens that came before it. That mix is not position-neutral.\n\nThe two edges have structural advantages. Opening tokens are visible to every later computation, and models often turn some of them into attention sinks. The newest tokens are closest to the prediction frontier, where trained models tend to give recent context more weight. Middle tokens get neither advantage: they must compete with the opening context's accumulated influence and the end of the prompt's recency bias.\n\nCausal attention, positional encoding, and learned attention patterns determine how strong each advantage is. The curve differs by model, task, and context length, but the engineering consequence is consistent: information placed in the middle has a lower chance of shaping the next prediction. Initial tokens can receive disproportionately high attention even when they carry no semantic importance.[^attention-sinks]\n\nThis is not a single bug to fix. The lost-in-the-middle effect means the same instruction can be reliable at the top or bottom of the window and unreliable in the middle.[^lost-in-middle]\n\nNow drag the slider toward high utilization. The J-curve is a **long-context failure mode**, not a universal phase change at 70% fill.\n\nAt modest absolute lengths, both primacy and recency can remain useful: the curve is U-shaped. As the sequence becomes much longer, primacy can erode while recency remains strong, turning the U into a J and expanding the unreliable middle. The transition depends on the model, task, and absolute token count — not a fixed utilization percentage. A 10K context at 80% fill contains 8K tokens; a 1M context at the same fill contains 800K. The slider normalizes position, so it cannot predict where a particular model's J-curve begins.\n\nRecent evaluations show that this is not an artifact of an older model generation. Du et al. tested five open and closed models on coding, question-answering, and math tasks: performance fell 13.9–85% as input length grew within the models' claimed windows, even with perfect retrieval and masked or whitespace distractors.[^context-length-alone] Chroma's Context Rot tested 18 frontier models, including GPT-4.1, Claude 4, Gemini 2.5, and Qwen3; every model showed non-uniform degradation as input length grew, with coherent and semantically similar distractors making the decline worse.[^context-rot] This is the constraint that context engineering works within.\n\nEvery mechanism in this chapter — context files, tool schemas, skills, sub-agents, compaction, and retrieval — is a way to keep important information where the model can still attend to it. The job is not to fit everything. The job is to keep the active task, current constraints, and relevant evidence in the high-attention zones.\n\n## The Context Pressure Problem\n\nThe agent rebuilds context each turn: a fixed prefix (system instructions, tool definitions, context files) followed by everything appended so far. When you type your task, it lands at the end — in the recency zone, where attention is strongest. Then the agent starts working. Tool calls, tool results, file reads, search hits — each one appends after your prompt.\n\nYour prompt does not move. The context grows around it. After a few turns, tens of thousands of tokens sit between your task and the end of the window. It is no longer in the recency zone. It is in the middle — the zone the attention curve showed as weakest.\n\nThis is the context pressure problem: the more work the agent does, the further your original instructions drift from where the model can still attend to them.\n\n<DiagramFrame kicker=\"Context management\" title=\"Context pressure moves the task through the window\" size=\"full\">\n\n<ContextPressureDiagram />\n\n</DiagramFrame>\nTry the presets. **Fresh Session** keeps the 1M-token window light — the task gets strong attention. **Heavy MCP (eager)** shows the real danger: a broad MCP catalog plus conversation pushes the task into the weak middle, well before capacity. **Heavy MCP (deferred)** demonstrates the savings from deferred tool loading — same catalog, a fraction of the startup tokens. **Deep Conversation** shows how long conversations alone create pressure — 120 turns of accumulated context push the task down. **Skill-Heavy** shows procedure expansions: turns where a skill or reusable workflow was invoked get a violet accent bar, and their extra 4K tokens per expansion add up fast. **Near Compaction** shows the drain cascade in action — the hatched region models the 165K capacity reserved for the compaction handoff, leaving an 835K effective working window. **Overloaded** is the worst case — older conversation is compacted first until the model fits.\n\nThe connector on the right side shows how tool definitions produce results that land in conversation turns. Notice how the drain cascade works: when total content exceeds the effective window, headroom disappears first, then conversation gets compacted (reduced opacity bands), then context files shrink, and finally tool definitions yield — each slider shows the requested-vs-actual gap when drained.\n\nThe key insight: **it's not about running out of tokens — it's about where your task lands relative to the attention curve.** A 65% full window with heavy tool definitions is worse than an 80% full window where most content is conversation (which sits below the task in the recency zone).\n\n:::note Scope\nThis section describes behavior measured in long-context autoregressive LLMs, especially causal transformers. Diffusion language models denoise a sequence iteratively rather than generate left to right, so they do not share the same causal-mask and recency mechanism. Evaluate their positional reliability separately instead of assuming the same curve.\n:::\n\n## The Six Context Mechanisms\n\nCompare mechanisms through the same context lens: **when tokens load**, **where they land**, **what they cost**, and **what they are useful for**. The figure makes those effects visible before the following sections examine their operational tradeoffs.\n\n<DiagramFrame\n  kicker=\"Context management\"\n  title=\"Six mechanisms share the same context lens\"\n  size=\"wide\"\n  caption={\n    <>The six context mechanisms: where tokens land and when they load.</>\n  }\n>\n  <ContextMechanismMap />\n</DiagramFrame>\n\nThese mechanisms do not sit on one spectrum. Context files and eager MCP schemas enlarge the fixed prefix. Skills and tool-driven retrieval add material when the active task needs it. Sub-agents keep their working trace in another window and return a synthesis. Compaction replaces accumulated conversation with a smaller, lossy state. Effective context engineering means choosing the context effect that matches the knowledge and the task.\n\n## Context Files\n\nContext files are markdown documents injected between the system prompt and your input. They give agents project memory without repeated explanations: architecture, conventions, build commands, constraints.\n\n**Context effect:** they load on every call into the fixed prefix. The tradeoff is **guaranteed delivery vs. pushing your task toward the valley**: every token inflates the prefix your task travels behind. Once the conversation starts building after your prompt, that prefix helps decide where the prompt ends up.\n\n<DiagramFrame\n  kicker=\"Context management\"\n  title=\"File size decides where your prompt lands\"\n  size=\"standard\"\n  caption={\n    'Same conversation, two file sizes. As turns append after the prompt, the prompt drifts from the recency edge: a small file lets it settle near the primacy edge — still strong attention; a big file lands it in the dead middle, where attention collapses.'\n  }\n>\n  <ContextSqueezeDiagram />\n</DiagramFrame>\n\n`AGENTS.md` is the vendor-neutral standard adopted by 60,000+ open-source projects (now governed by the Linux Foundation's Agentic AI Foundation), working across GitHub Copilot, Cursor, Windsurf, and most other AI coding tools (note: Claude Code does not support AGENTS.md — see tip below). Keep it minimal — your README should contain 90% of what AI needs; AGENTS.md adds only AI-specific operational context. That 10% is where the discipline lives — every token in AGENTS.md sits in the attention valley between the prefix and your actual task. Put project knowledge in your README where agents can read it on demand; AGENTS.md is for what changes _how_ the agent operates, not _what_ the project does. Reference external docs by link rather than inlining them — agents can fetch details when needed.\n\n:::tip Claude Code: Using AGENTS.md with Claude Code\nClaude Code uses `CLAUDE.md` instead of `AGENTS.md`. To maintain a single source of truth while supporting both ecosystems, use **@-linking** in your `CLAUDE.md`:\n\n```markdown\n# CLAUDE.md\n\n@/AGENTS.md\n```\n\nThis imports your AGENTS.md content into Claude's context. For details on Claude Code's hierarchical context system, see the [Claude Code documentation](/developer-tools/cli-coding-agents#claude-code).\n:::\n\n:::warning Hierarchical CLAUDE.md: Hidden Context Bloat\nUnlike AGENTS.md (a single file with predictable token cost), Claude Code's hierarchical system merges `CLAUDE.md` files from multiple levels — project root, subdirectories, `.claude/rules/`, user config, and enterprise policy — all automatically loaded based on your working directory. Each additional file lands in the attention valley this chapter describes: every merged file adds more middle-zone content between the prefix and your task. The total context-file token cost becomes invisible unless you audit every level of the hierarchy. If you use Claude Code, keep a single root `CLAUDE.md` that `@`-imports `AGENTS.md` and avoid scattering files throughout subdirectories — the hierarchy multiplies the squeeze.\n:::\n\n:::warning Security Consideration\nContext files are injected directly into system prompts. Security researchers have identified \"Rules File Backdoor\" attacks where malicious instructions are injected using Unicode characters or evasion techniques. Keep context files minimal, version-controlled, and code-reviewed like any other code.\n:::\n\n## MCP Tools\n\nEvery tool the agent can call ships with a schema: name, description, parameters. Built-in tools (Read, Edit, Bash) are modest at ~50–1000 tokens each. MCP servers are a different story entirely.\n\n**Context effect:** eager loading places every schema in the fixed request prefix before the model plans its first action. Deferred loading keeps most schemas out initially, then adds task-relevant definitions when discovery expands them. The tradeoff is placement, not just capacity: eager schemas apply pressure on every call, while deferred schemas spend context only after discovery but remain available for the rest of the session.\n\nThe cost is structural: every tool schema is serialized as JSON with repeated type annotations, nested `required` arrays, and verbose natural-language descriptions. A typical tool runs 300–600 tokens; complex API tools like GitHub's file operations hit 1,000–2,000. These costs compound quickly across multi-server setups. The governing rule is simple: **small, high-frequency toolsets favor eager loading; large, broad catalogs favor deferred loading.**\n\n### Eager vs Deferred Loading\n\nEager loading keeps calls simple because the model already has the schema when it starts planning. Deferred loading protects the startup prompt, but every deferred tool now depends on runtime discovery. A longer task can create more searches as it gains new capability needs; context length alone does not trigger them.\n\n<DiagramFrame\n  kicker=\"Context management\"\n  title=\"Discovery costs context; unused schemas cost more\"\n  size=\"wide\"\n  caption={\n    'One catalog control grows eager schema pressure and the task-relevant Tool Search results. Lazy loading keeps the remaining catalog outside the request.'\n  }\n>\n  <MCPToolSchemaDiagram />\n</DiagramFrame>\n\nDrag the catalog control. As the catalog broadens, the task can need more relevant schemas. Eager loading puts every schema in the fixed prefix; Tool Search brings in only the growing relevant subset and keeps the remainder out of the request.\n\nTool Search can return several matches (up to five), and loaded schemas persist for the rest of the session. A longer task that needs new capabilities can trigger additional searches and expansions; the crossover therefore depends on schema size, result breadth, task breadth, and selection quality.\n\n**Takeaway:** the more your catalog behaves like infrastructure, the more you should optimize for what stays out of the valley instead of immediate tool visibility. The same logic applies one layer up to reusable procedures: if a workflow library is broad, discover it cheaply and load the full instructions only when needed. The same automation-versus-reliability tradeoff applies here.\n\n<details>\n<summary>See the deferred-loading runtime sequence</summary>\n\nWhen a deferred tool is needed, the model must **discover → load → call**:\n\n<ContextStreamBlock\n  entries={contextManagementStream}\n  ariaLabel=\"ToolSearch discovers gh_pr_create on demand, loads its schema, then makes the tool callable\"\n/>\n\nDeferred loading is powerful precisely because it turns schema exposure into a runtime workflow instead of paying the full cost at startup.\n\n</details>\n\n## Skills and Procedures\n\nSkills are the **procedure-side analogue of deferred MCP tools**. The agent sees lightweight discovery metadata first, then loads the full workflow only when the task matches or you invoke it directly.\n\n**Context effect:** the catalog creates a small fixed cost; activation adds the selected procedure near the active turn, where it initially benefits from recency but can drift as work continues. The critical tradeoff is who activates it: auto-discovery is friction-free but probabilistic, while manual invocation is reliable but requires the human to know the skill exists.\n\n### Two Invocation Paths\n\n<DiagramFrame\n  kicker=\"Context management\"\n  title=\"Skills can be operator-triggered or model-invoked\"\n  size=\"wide\"\n  caption={\n    'Skill invocation paths: manual selection is reliable; model matching is automatic but probabilistic.'\n  }\n>\n  <SkillsInvocationDiagram />\n</DiagramFrame>\n\n**Manual invocation**: The user explicitly selects a procedure — a slash command (`/commit`), skill picker, or sub-agent mention. The procedure loads because the human chose it. **Always reliable** — the model cannot misidentify the workflow — but the human must discover the skill and remember its name.\n\n**Model invocation**: The agent sees the procedure catalog in context, matches your intent against the descriptions, and loads the relevant workflow automatically. **Zero friction** — the agent handles discovery — but the model may pick the wrong skill, miss the right one, or waste tokens evaluating irrelevant descriptions.\n\nMost skill systems allow per-skill configuration of this tradeoff. Claude Code exposes `disable-model-invocation` (manual only) and `user-invokable` (model only) as frontmatter fields in each `SKILL.md`. A skill with `disable-model-invocation: true` never auto-triggers — it runs only when explicitly invoked. This lets you match the invocation path to the workflow's reliability requirements: critical workflows (deploy, commit, review) benefit from manual invocation; exploration workflows (search code, explain errors) work well with auto-discovery.\n\n### Different Harnesses, Same Core Pattern\n\nUnlike MCP — a defined protocol — skills are not standardized across tools. Each harness implements them differently. Yet they all follow the same pattern: advertise lightweight discovery metadata upfront, load the full procedure content only when invoked.\n\nClaude Code lists skill names and descriptions, then loads `SKILL.md` when the skill is activated. Pi does the same and also exposes prompt templates as direct slash commands. Codex separates built-in slash commands from a `/skills` browser that inserts skill context only when selected. OpenCode leans more on reusable agents and `@`-invoked subagents, but the idea is identical: keep the startup prompt lean and bring in specialized instructions only when relevant.\n\nThat catalog listing is not free. Procedure metadata — names and descriptions used for discovery — consumes context budget even before any workflow runs. This is the procedure-side analogue of MCP schema pressure: different payload, same design problem.\n\nThe practical framing: **AGENTS.md** holds what the agent should always know — architecture, conventions, constraints. **Skills** hold what the agent should know how to do — specific workflows loaded on demand, with the invocation path controlling who decides which one runs.\n\n## Sub-Agents\n\nSub-agents run in completely separate context windows. A sub-agent might consume 50K–150K tokens researching a codebase, but return only a 2K–5K synthesis to the orchestrator.\n\n**Context effect:** the prompt forks work into a separate window; only the returned synthesis enters the parent near the active turn. The parent pays for that synthesis, not the raw search trail, file reads, and partial interpretations. This keeps the orchestrator clean while making the return boundary intentionally lossy.\n\nThink of a sub-agent like a function call for agents. The prompt is the parameter: \"Find all JWT authentication code and explain the current implementation.\" The synthesis is the return value: \"JWT implementation found at src/auth/jwt.ts using Passport.js...\" You pay for work in both contexts, but the parent receives the compact result instead of inheriting the whole research journey.\n\n<DiagramFrame\n  kicker=\"Context management\"\n  title=\"Sub-agents isolate context then return synthesis\"\n  size=\"standard\"\n  caption={\n    'Sub-agent context isolation: research consumed internally, compact synthesis returned.'\n  }\n>\n  <SubAgentDiagram />\n</DiagramFrame>\n\nThe tradeoffs:\n\n- **No shared state** — each sub-agent starts fresh, so you pay the context-file loading cost again\n- **Synthesis can lose nuance** — the 2K summary omits details the parent might have needed\n- **Cost multiplied** — every sub-agent is a separate API call with its own token consumption\n- **No nesting** — sub-agents cannot spawn sub-agents; the orchestrator is always the root\n- **10 parallel cap** — Claude Code limits concurrent sub-agents to 10\n\nThe trade-off is token cost, not accuracy. You pay to process tokens in both contexts, but the orchestrator stays clean. That often improves first-iteration accuracy enough to save tokens compared with multiple correction cycles from a polluted parent context.\n\nSub-agents are ideal for heavy research, multi-file analysis, and exploratory tasks where the journey matters less than the destination. They can also generate independent plans or implementations when you want to compare options before applying one result.\n\n### Two Sub-Agent Architectures\n\n**Autonomous architecture:** You give the agent tools and a system prompt. The agent autonomously decides what to do, which tools to call, and how to sequence its work.\n\nExample: Claude Code's Explore agent. You send it a task, it autonomously picks tools and sequences, then delivers results. Dynamic and adaptable — it handles any task you throw at it without prior engineering.\n\n**Structured architecture:** You build a deterministic control plane that defines the exact algorithm. The LLM makes tactical decisions within your structure (\"Should I expand this symbol?\" \"Is this chunk relevant?\"), but the overall flow is fixed.\n\nExample: [ChunkHound](https://chunkhound.github.io) [disclosure] uses a fixed multi-hop pipeline where the system controls traversal strategy and the LLM ranks relevance at decision points. Deterministic and reproducible — same input, same results every time.\n\n<DiagramFrame\n  kicker=\"Context management\"\n  title=\"Two sub-agent architectures trade flexibility for reproducibility\"\n  size=\"wide\"\n  caption=\"Deterministic pipelines are structured and reproducible; autonomous exploration is adaptive but non-deterministic.\"\n>\n  <ArchitectureDiagram />\n</DiagramFrame>\n\n**The architectural trade-off:** Autonomous agents are dynamic — they handle any task and adapt on the fly, but are non-deterministic (same prompt yields different paths each run) and bounded by context capacity. Structured agents are reproducible and scale to any information volume with better token efficiency, but only handle the specific task they were engineered for and cost more to build.\n\n### If You Cannot Use Sub-Agents\n\nWithout sub-agents, exploit the attention curve directly:\n\n- Put durable constraints at the start, where primacy is strongest.\n- Put the active task at the end, where recency is strongest.\n- Keep supporting evidence in the middle summarized and referenced, not pasted wholesale.\n- Start a fresh phase when the middle becomes crowded instead of continuing in a degraded thread.\n\nThis is less powerful than isolation, but it still respects the core rule: important facts must land where the model can attend to them.\n\n## Context Compaction\n\n**Context effect:** compaction replaces accumulated conversation with a smaller synthetic state, restoring working room while discarding detail. It is lossy summarization guided by your instruction, but it cannot guarantee what survives. Future relevance is unknowable at compaction time: a debugging trace that looks like noise now may be the clue the next step needed.\n\nThe reliable alternative is **manual handoff with external checkpointing**. Before starting a new phase, write a brief state file with the current goal, changed files, decisions, unresolved errors, and next step. Files provide exact recall; a fresh context provides inference quality.\n\n### The Buffer Tax\n\nCompaction itself consumes working context. The system reserves a buffer to ensure it can still perform the handoff when the session nears capacity — capacity intentionally withheld from normal conversation. This is the compaction buffer: a tax on your effective window.\n\n:::tip Disable auto-compaction\nAuto-compaction trades usable context for a safety margin you don't need when you own handoffs explicitly. Both Claude Code (CLI settings) and [pi](https://pi.dev) let you disable it:\n\n```json\n{ \"compaction\": { \"enabled\": false } }\n```\n\nReclaim the buffer for actual work. Compact only when you choose to — at phase boundaries — and always externalize anything that must survive exactly.\n:::\n\n## Retrieval\n\nThe agents chapter showed that [memory is retrieval](./how-agents-work.mdx#memory-is-retrieval-not-recall) — the model does not remember your project conventions, previous sessions, or domain facts unless the harness retrieves them and feeds them into a later call. ChunkHound, OpenGrok, vector databases, BM25 indexes, web search, knowledge graphs, and memory systems are all retrieval flavors. They solve the same problem: choosing which facts deserve space in the next request.\n\nRetrieval is a context engineering mechanism because it controls what evidence enters the context window and where it lands.\n\n**Context effect:** harness-level RAG injects retrieved content before the user prompt, in the primacy zone. It is always visible but competes with context files for the fixed prefix. Tool-call retrieval — ChunkHound, grep, web search — appends results after the user prompt. Those results enter with recency advantage, then drift toward the middle as the conversation grows.\n\nEach placement has different attention characteristics. Harness-level retrieval is always visible but always costs tokens. Tool-call retrieval loads on demand but competes with every other conversation turn for attention.\n\n### The Token Cost of Discovery\n\nRetrieval decisions are context engineering decisions because every retrieved chunk costs tokens. Three grep searches can return 18,000 tokens. Reading five files can add another 22,000. You are at 40,000 tokens before discovery is finished. Ten semantic chunks from a vector database can cost 15,000 tokens; reading related files adds 25,000; exploring patterns adds another 10,000. You are at 50,000 tokens before implementation starts.\n\nThat is why correct retrieval can still hurt reliability. A long search trail can push the actual task into the forgotten middle. A useful web page can arrive too early, sit too long, and compete with more relevant instructions later. Coherent distractor text is especially dangerous because it looks relevant while degrading reasoning more than obvious noise.[^context-rot]\n\n### Retrieval Quality ≠ Context Quality\n\nThe failure mode most teams hit with retrieval is not \"the retriever found irrelevant chunks.\" It is \"the retriever found relevant chunks, but the model could not use them.\"[^context-injection]\n\nRetrieval quality and context injection quality are separate problems. Finding the right facts is necessary but not sufficient. How those facts are structured, prioritized, and wrapped in the context determines whether the model can attend to them. A chunk that is relevant but arrives in the dead center of a 200K-token window may as well not exist.\n\nThis is why retrieval is a context engineering mechanism, not a precursor to it. The operator decides what to retrieve, where to place it, how much context budget to spend on it, and when to load it. Those are the same decisions that govern every other mechanism in this chapter.\n\n:::warning The Agentic Coding Cost Trap\n\nMost providers apply per-token surcharges past a context threshold:\n\n- **Gemini 3.1 Pro:** 2× input pricing above 200K tokens\n- **GPT-5.5 / GPT-5.4:** 2× input pricing above ~272K tokens\n- **DeepSeek V4 Pro / Flash:** 1.5× pricing above 512K tokens\n- **Claude 4.6/4.7 (Opus/Sonnet):** No surcharge — flat rate to 1M\n\nFor retrieval tasks (summarization, document review), the surcharge buys tokens in the model's strong accuracy zone. For agentic coding, you're paying a premium for tokens in the model's _worst_ accuracy zone — the middle, where your constraints and requirements go to die.\n:::\n\n---\n\n## Key Takeaways\n\n**Context files: guaranteed delivery creates fixed pressure**\nEvery token in AGENTS.md enlarges the prefix on every call and pushes the user task toward the weak middle. Keep operational instructions minimal; leave on-demand project knowledge in referenced documentation.\n\n**MCP tools: schema exposure trades immediate visibility for prefix cost**\nEager loading is simple but charges the full catalog to every request. Deferred loading adds discovery steps, then exposes only relevant schemas. Catalog breadth, schema size, and task breadth determine the crossover.\n\n**Skills: procedure content arrives only when activated**\nA lightweight catalog supports discovery; the selected workflow enters near the active turn. Manual activation favors reliability, while model activation favors convenience.\n\n**Sub-agents: raw exploration stays outside the parent**\nA sub-agent can consume 150K tokens internally while returning only a small synthesis. Use separate windows for research trails and multi-file exploration when the parent needs conclusions rather than the full journey.\n\n**Compaction: working room is recovered by losing detail**\nA summary replaces accumulated history, so facts needed later may disappear. External checkpoint files provide exact recall; a fresh context restores inference quality.\n\n**Retrieval: relevant evidence still consumes attention**\nHarness-level retrieval competes for primacy space; tool-driven retrieval enters with recency and drifts inward. Optimize placement and context injection alongside retrieval quality.\n\n**The U-curve is the constraint**\nPosition matters. Put critical instructions at the edges — primacy (start) and recency (end). Keep supporting evidence in the middle summarized and referenced, not pasted wholesale. Start a fresh phase when the middle becomes crowded.\n\n**Choose the mechanism by the required context effect**\nAlways needed? → Context file. Callable capability? → MCP tool. Reusable workflow? → Skill or prompt template. Heavy research? → Sub-agent. Accumulated history? → External checkpoint and fresh phase, or compaction when necessary. Domain knowledge or project evidence? → Retrieval.\n\n---\n\n[^attention-sinks]: Xiao et al. (2023), [_Efficient Streaming Language Models with Attention Sinks_](https://arxiv.org/abs/2309.17453).\n\n[^lost-in-middle]: Liu et al. (2023), [_Lost in the Middle: How Language Models Use Long Contexts_](https://arxiv.org/abs/2307.03172).\n\n[^context-length-alone]: Du et al. (2025), [_Context Length Alone Hurts LLM Performance Despite Perfect Retrieval_](https://aclanthology.org/2025.findings-emnlp.1264/).\n\n[^context-rot]: Chroma Research (2025), [_Context Rot_](https://www.trychroma.com/research/context-rot).\n\n[^context-injection]: ExplainX (2026), [_RAG Context Injection Pipeline Design_](https://www.explainx.ai/blog/rag-context-injection-pipeline-design-2026).\n\n**Next:** [Chapter 7: Reliability Levers](./reliability-levers.md)\n"}}}}