What turns a model into an agent is not the model — it is the engineering of the two layers around it: the environment it acts in, and the context it reasons over. That is the subject of this book. This opening chapter states the thesis and grounds it in the frame the book stands on — Agent = Model + Harness — then maps the chapters and marks the scope. It defines vocabulary and direction; the next chapter argues the case, and the rest build it.

The frame: an agent is a model plus a harness

Start with the distinction that organizes everything else. An agent, in Anthropic’s framing, is a system where models “dynamically direct their own processes and tool usage.” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original The working shorthand is tighter still: agents are “LLMs autonomously using tools in a loop.” Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original That is the model side — the source of the agent’s autonomy.

The harness is everything else: the deterministic code wrapped around the model. Claude Code, for instance, “provides the tools, context management, and execution environment that turn a language model into a capable coding agent.” [Official] How Claude Code works · AnthropicT1-official original A general-purpose harness such as the Claude Agent SDK is one concrete instance of that wrapper. Effective harnesses for long-running agents · Justin Young (2025)T1-official original

The boundary that makes the frame sharp is the contrast with a workflow, where models and tools are instead “orchestrated through predefined code paths.” Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original A workflow’s control flow is fixed in code; an agent’s control flow is driven by the model. So the same three ingredients — a model, some tools, some glue — give you a workflow or an agent depending on who decides what happens next.

This is why this book is scoped the way it is: the model is a given (you choose a capable one and prompt it well — prompting is its own discipline, out of scope here), and of the harness around it, this book develops the two layers where most of the leverage lives — the environment and the context.

The harness owns three layers

A harness decomposes into three layers, and its defining job is owning the boundary between them.

• Context — the assembled window the model reasons over. It is “a critical but finite resource for AI agents” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original — a budget, not free memory.
• Environment — the substrate the agent acts in: the repository, the filesystem, scripts, a running process. A long-running harness “asks the model to set up the initial environment” before work begins. Effective harnesses for long-running agents · Justin Young (2025)T1-official original
• Context-assembly — the boundary between them. Rather than dumping the environment into the window, agents keep lightweight references and “use these references to dynamically load data into context at runtime using tools.” Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original

Owning that boundary is what makes a harness a harness. The mechanics of assembly — caching, compaction, just-in-time loading — are deep enough to be their own chapter (the context-assembly chapter, later in this book); here we only name the three layers and locate the boundary the harness controls.

The components a harness wires together

Zoom into the harness and it is a parts list. Shipping harnesses name the same parts. The Claude Agent SDK gives you “the same tools, agent loop, and context management that power Claude Code” [Official] Agent SDK overview · AnthropicT1-official original ; tools are “the primary building blocks of execution for your agent” Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original ; and the harness can “spawn specialized agents to handle focused subtasks” Agent SDK overview · AnthropicT1-official original that “use their own isolated context windows.” Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original

That this is a real taxonomy, and not one vendor’s idiosyncrasy, shows up cross-vendor:

So a harness wires together, at least: a tool interface, context/memory management, a control loop with stop conditions, and sub-agent orchestration — and, by extension, guardrails/permissions and observability. Each part is deep-diveable on its own; this chapter is the parts diagram, not the parts.

The nested loop: an inner cycle inside an outer one

The harness runs a nested loop, and knowing which loop you are designing is half of harness engineering.

The inner loop is the model’s own cycle. Claude Code’s “agentic loop is powered by two components” How Claude Code works · AnthropicT1-official original — the model reasoning and the tools acting — repeating until the task is done. The internals of that cycle (how a turn is structured, how tool results return) are a companion-volume concern; here it is enough that an inner loop exists and the model drives it.

The outer loop is the harness wrapping that cycle. A long-running harness exists to “bridge the gap between coding sessions” Effective harnesses for long-running agents · Justin Young (2025)T1-official original so the model can make incremental progress across many context windows.

How the vocabulary settled

The frame above is recent. The words arrived on a short, dated arc, and it is worth seeing the shape because the vocabulary is still moving.

• 2025-06-17 — Andrej Karpathy popularizes the “agents” framing in a widely-cited keynote: “This is the Decade of Agents.” [Practitioner] Andrej Karpathy: Software in the Age of AI · Andrej Karpathy (Latent Space transcript-mirror) (2025)T3-practitioner original
• 2025-11-26 — Anthropic adopts “harness” in an official engineering venue, describing a “long-running agent harness” working “across many context windows.” Effective harnesses for long-running agents · Justin Young (2025)T1-official original
• 2026-02-05 — Mitchell Hashimoto names the discipline: “I’ve grown to calling this ‘harness engineering.’” [Practitioner] My AI Adoption Journey · Mitchell Hashimoto (2026)T3-practitioner original
• 2026-03-10 — LangChain gives the formula its cleanest published form: “Agent = Model + Harness.” The Anatomy of an Agent Harness · Vivek Trivedy (2026)T2-release-notes original

The shape is the story: the concept (autonomous agents) predates a word for its wrapper (harness) by months, and the compact formula arrives last, once the wrapper has a name.

The shape of this book

This book takes two of the harness’s layers — the environment and the context — and develops them as one discipline. The chapters move from the substrate outward to the window, and inside the window from the problem to the response:

Environment — the substrate the agent acts in.

• Repo & doc design — making the repository high-signal to read and self-correcting to act in.
• The instruction layer — the always-loaded config file as a context budget, not documentation.
• Skills & progressive disclosure — procedural knowledge that loads only when relevant.
• Guardrails, permissions & reversibility — expressing intent in policy and containing failure in mechanism.
• Environments at scale — bounding what the agent must load when the repo is too big to hold.

Context — the window the model reasons over.

• Context rot — the evidence that long windows degrade, and why that is the problem the rest answers.
• Context assembly — the engineering response: caching, compaction, just-in-time loading, budgeting the window.
• Memory — persisting context across sessions, and the anti-patterns that reintroduce the rot.

A closing chapter composes all of it into one design workflow.

What this book leaves to companion volumes

The frame names more of the harness than one book should carry. The rest is deliberately out of scope here — each is planned as a companion volume in the series, and this book points outward to it rather than pretending to deliver it:

• The inner loop’s internals — how a turn and its tool results are structured.
• The Agent SDK’s surface — the concrete harness instance whose API we cited above.
• Sub-agent orchestration — the isolation primitive, orchestrator–worker topologies, and when not to use them.
• Tools & MCP — designing the tool interface and the protocol that serves it.
• Build vs. buy — whether to configure an existing harness or build your own.
• Evaluation & operations — measuring and running agents in production.

These are companion concerns, not missing chapters: this book stands on its own for the environment and the context.

What is still settling

This chapter captures a frame mid-crystallization, so a few honest limits travel with it.

• The vocabulary is young. “Harness” entered Anthropic’s official vocabulary only in late 2025; “harness engineering” and “Agent = Model + Harness” are 2026 coinages. Expect the terms to keep shifting, and re-check the landscape rather than treating today’s words as settled.
• The definitional spine is single-vendor-dense. The definitions of “agent” and “harness” rest largely on Anthropic’s framing. The one independent corroboration here (LangGraph) agrees on the components list, not on the definitions — so do not over-claim convergence beyond the parts list.
• One provenance anchor is a transcript, not a primary. Karpathy’s line is quoted from a published transcript of a spoken keynote, faithful to that mirror and the talk date, but it is “Karpathy said X in a talk,” not “Karpathy wrote X.”

Quick reference

• Agent = Model + Harness. The model supplies autonomy; the harness supplies everything around it.
• Agent vs. workflow: an agent’s control flow is model-driven; a workflow’s is fixed in code.
• Three layers: environment (substrate) → context-assembly (the boundary) → context (the finite window). The harness owns the boundary.
• Components: tool interface, context/memory, control loop, sub-agent orchestration (+ guardrails, observability).
• Nested loop: the model’s inner reason→act→observe sits inside the harness’s outer cross-session orchestration, where control lives.
• This book’s scope: the environment and the context — the two highest-leverage layers; the rest is named here and left to companion volumes.

Practice

The introduction drew the frame and stated the thesis: an agent is a model plus a harness, and the leverage is in two of the harness’s layers — the environment and the context. This chapter makes the case for that thesis — why those two layers, and not the model, are where the discipline of building agents actually lives. It argues; it does not yet build.

What autocomplete cannot do

Start with the gap this book is about. Code completion suggests the next token from the surrounding text; it has no autonomy. An agent, in Anthropic’s framing, is a system where models “dynamically direct their own processes and tool usage.” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original The working shorthand is tighter: agents are “LLMs autonomously using tools in a loop.” Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original

The model supplies that autonomy. But a model alone, prompted in a vacuum, is still close to autocomplete — it can only act on what is in front of it. What makes it an agent is everything the harness arranges around the model: the substrate it can act in, and the window it gets to reason over. Claude Code, for instance, “provides the tools, context management, and execution environment that turn a language model into a capable coding agent.” [Official] How Claude Code works · AnthropicT1-official original

Two layers, one discipline

The frame named three layers; two of them are the agent’s whole relationship with the world.

• Environment — the substrate the agent acts in: the repository, the filesystem, scripts, a running process. A long-running harness even “asks the model to set up the initial environment” before work begins. Effective harnesses for long-running agents · Justin Young (2025)T1-official original Shape the environment well and the agent reads high signal and gets honest feedback; shape it poorly and no amount of prompting recovers.
• Context — the assembled window the model reasons over. It is “a critical but finite resource for AI agents” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original — a budget, not free memory. What you spend it on, and what you leave out, decides what the agent can actually do on any given turn.

These read as two topics — “set up the repo” and “manage the window” — but they are one discipline seen from two ends. The environment is the large, durable store of everything the agent could use; the context is the small, finite slice it does use on a turn; and the harness’s defining job is owning the boundary between them, keeping “lightweight references” and using them to “dynamically load data into context at runtime using tools.” Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original

Why it is underappreciated

The model gets the headlines — new versions, benchmarks, prompting tricks. That is the inner loop, and it matters. But the model is, increasingly, a given: you choose a capable one and prompt it well. The lever you actually own as an architect is the outer loop — and most of the outer loop’s effect on output quality flows through these two layers.

This is underappreciated for a structural reason: the work is invisible when it succeeds. A well-designed environment shows up as the agent “just knowing” where things are; a well-budgeted context shows up as the agent staying coherent over a long task. Nobody points at the absence of a failure. So the discipline is easy to skip and easy to under-credit — right up until an agent re-reads the same file every turn, loses the thread across sessions, or confidently acts on stale memory, and the cause turns out to be the environment or the context, never the model.

What is still settling

Two honest limits travel with this book, and they shape how to read it.

• Most of this discipline is converged craft, not measured effect. Independent practitioners, standards bodies, and vendors agree on the direction of most practices here, but controlled effect sizes are rare. Where a claim is craft consensus, the chapters say so; where there is a measured result, they name it — and they never launder a heuristic into a number.
• The vocabulary is young. “Environment engineering” and “context engineering” are recent coinages over practices that predate the names. Treat the framing as a useful organizing lens, not a settled taxonomy, and re-check the landscape rather than the labels.

Quick reference

• Autocomplete → agent: the model supplies autonomy; the environment and context supply what the autonomy acts on. Engineering those two layers is the discipline.
• Environment = the durable substrate (repo, filesystem, processes); context = the finite window. The harness owns the boundary.
• One subject, two ends: maximize signal in the environment; spend the context budget deliberately. Neither works alone.
• Why underappreciated: the work is invisible when it succeeds, and the model gets the attention — but the leverage is here.
• The arc: environment (substrate) → context rot (the problem) → context assembly (the response) → memory (persistence).

Practice

The previous chapter argued that the environment and the context are where the discipline lives. This chapter takes the first layer — the environment — at its most concrete: the repository the agent reads and acts in. Every move here is converged craft, not measured effect; the convergence across independent practitioners is the signal, and stating that honestly is part of the chapter’s job.

The repository is the environment

A coding agent does not see your project the way you do. It sees what the harness loads into its context — and most of that is your repository: the files, their names, the docs, the tests. So the repository is not just where the work happens; it is the environment the agent operates in, and its structure is, in effect, the prompt.

The practitioner premise is blunt: the tokens you put in the model’s context “are the ONLY lever you have to affect the quality of your output.” [Practitioner] Advanced Context Engineering for Coding Agents (ACE-FCA) · Dex Horthy (HumanLayer) (2025)T3-practitioner original If context is the only lever, then how the repository is structured — what an agent reads when it lands cold — is a primary determinant of output quality.

The first move follows directly: give the agent a predictable entry point. The cross-tool AGENTS.md convention exists for exactly this — “a dedicated, predictable place to provide the context and instructions to help AI coding agents work on your project,” AGENTS.md · Agentic AI Foundation (Linux Foundation)T2-release-notes original a README written for agents rather than humans.

Two halves: shaping the input, shaping the feedback

The five moves in this chapter are not five unrelated tips. They split cleanly into two halves of one discipline.

• Shaping the input — legibility (a readable entry-point map), examples-as-constraints (show, don’t tell), and negative space (subtract first) all govern what the agent reads.
• Shaping the feedback — failure breadcrumbs (durable records of past mistakes) and structural fitness (deterministic sensors) govern what the agent gets back after it acts.

Legibility and structural fitness are one property

The two halves meet in a single idea. A repository is legible to an agent to exactly the degree its structure is machine-checkable. Böckeler’s definition of a harnessable environment is the “structural properties of the environment itself that make it legible, navigable, and tractable to agents,” [Practitioner] Harness engineering for coding agent users · Birgitta Böckeler (2026)T3-practitioner original and she notes that “clearly definable module boundaries afford architectural constraint rules.” Harness engineering for coding agent users · Birgitta Böckeler (2026)T3-practitioner original

So the structure that makes a repo navigable (a human-facing, legibility reading) is the same structure that makes it enforceable (a machine-facing, fitness reading). The entry-point map is the readable face; the sensor suite is the enforced face; they are one property, not two.

Show, don’t tell — and subtract first

Two input-shaping moves turn out to be the same instruction. Anthropic’s official guidance is to “reference specific files, mention constraints, and point to example patterns,” [Official] Best practices for Claude Code · AnthropicT1-official original illustrated with a worked prompt — “HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget.” Best practices for Claude Code · AnthropicT1-official original A reference implementation constrains output more reliably than a paragraph of prose rules.

The complementary move is negative space: deliberately curating what the agent reads instead of over-documenting. Context engineering is “deliberately structuring how you feed context to the AI,” [Practitioner] Advanced Context Engineering for Coding Agents (ACE-FCA) · Dex Horthy (HumanLayer) (2025)T3-practitioner original to the point of “designing your ENTIRE WORKFLOW around context management.” Advanced Context Engineering for Coding Agents (ACE-FCA) · Dex Horthy (HumanLayer) (2025)T3-practitioner original

For a context-bounded agent these are one instruction: a worked example is simultaneously more constraining and cheaper in tokens than a prose rule — so the cleanest way to subtract prose is to point at an example.

The ratchet: every failure becomes an affordance

The feedback half is where the discipline compounds. The practice Hashimoto names is to treat each agent mistake as permanent: “anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.” [Practitioner] My AI Adoption Journey · Mitchell Hashimoto (2026)T3-practitioner original The concrete artifact is an instructions file where “each line… is based on a bad agent behavior” — which he reports “almost completely resolved them all.” My AI Adoption Journey · Mitchell Hashimoto (2026)T3-practitioner original

Decision records do the same for why: ADRs give “enough structure to ensure key points are addressed, but in natural language,” [Practitioner] Using Architecture Decision Records (ADRs) with AI coding assistants · Chris Swan (2025)T3-practitioner original so an agent recovers the rationale behind a choice instead of re-deriving or contradicting it.

And structural sensors close the loop automatically: deterministic checks “cheap and fast enough to run on every change, alongside the agent,” [Practitioner] Harness engineering for coding agent users · Birgitta Böckeler (2026)T3-practitioner original that “catch the structural stuff reliably: duplicate code, cyclomatic complexity, missing test coverage, architectural drift.” Harness engineering for coding agent users · Birgitta Böckeler (2026)T3-practitioner original Böckeler observed an agent that “violated the rules a handful of times… and then self-corrected” from sensor feedback. Maintainability sensors for coding agents · Birgitta Böckeler (2026)T3-practitioner original

What is still settling

Three honest limits travel with this chapter.

• No effect sizes exist. Every move here is converged craft — observed practice agreed on by independent practitioners — not a controlled study. There is no measured “examples cut errors by X%.” Treat the direction as well-supported; do not generalize any number.
• The strongest recovery evidence is n=1. Hashimoto’s “resolved them all” and Böckeler’s self-correction observation are first-person field reports, author-is-subject — directionally supportive, no statistical weight.
• More context files is not automatically better. There is one measured result adjacent to this material, and it cuts the other way — repository context files can reduce task success and add cost. That study, and what it implies for the instruction layer, is the next chapter; flagged here so “add more docs” is not read as the lesson.

Patterns

The five moves, in the reference template. Each is a converged-craft practice; apply the ones your repo lacks.

Entry-point map (AGENTS.md). Sketch: one predictable, agent-addressable file at the repo root. When to use: always — it is the agent’s cold-start map. AGENTS.md · Agentic AI Foundation (Linux Foundation)T2-release-notes original Mechanics: place AGENTS.md at root; point to where things live, not every detail. Remember: it is a map, not the whole manual — keep depth in linked files.

Examples as constraints. Sketch: point at a reference implementation instead of writing a prose rule. When to use: whenever a convention has an existing instance. Best practices for Claude Code · AnthropicT1-official original Mechanics: “follow the pattern in X”; cite the file, name the constraint. Remember: a worked example is more constraining and cheaper in tokens than prose.

Negative space. Sketch: deliberately prune what the agent reads. When to use: when docs have grown faster than they’re curated. Advanced Context Engineering for Coding Agents (ACE-FCA) · Dex Horthy (HumanLayer) (2025)T3-practitioner original Mechanics: design the workflow around what to omit; subtract before adding. Remember: this is a design choice about omission, separate from context-rot evidence (later chapter).

Failure breadcrumbs. Sketch: turn each observed mistake into a durable record. When to use: any recurring agent error. My AI Adoption Journey · Mitchell Hashimoto (2026)T3-practitioner original Mechanics: one instructions-file line per prevented behavior; ADRs for decisions. Using Architecture Decision Records (ADRs) with AI coding assistants · Chris Swan (2025)T3-practitioner original Remember: a repo affordance the agent reads — not runtime telemetry.

Structural sensors. Sketch: deterministic checks that run on every change. When to use: wherever structure is machine-checkable (types, boundaries, coverage). Harness engineering for coding agent users · Birgitta Böckeler (2026)T3-practitioner original Mechanics: wire tests/linters/architectural rules into the loop; let the agent self-correct from them. Maintainability sensors for coding agents · Birgitta Böckeler (2026)T3-practitioner original Remember: sensors catch structural issues reliably — not correctness or over-engineering.

Quick reference

• The repo is the environment — its structure is the prompt the agent reads.
• One principle: maximize signal in, maximize machine-checkable feedback out.
• Input half: entry-point map · examples-as-constraints · negative space.
• Feedback half: failure breadcrumbs · structural sensors.
• Legibility = fitness: the structure that makes a repo navigable is what makes it enforceable.
• Evidence: converged craft, no effect sizes; the strongest recovery evidence is n=1.

Practice

The previous chapter ended on a hook: adding more documentation for an agent is not automatically better, and there is a measured result that proves it. This chapter is that result’s home. The file in question — CLAUDE.md, or the cross-tool AGENTS.md — looks like documentation, but it behaves like a permanent line item in the agent’s context budget, and that single fact drives everything here.

The always-loaded file is a budget

A CLAUDE.md is “a special file that Claude reads at the start of every conversation,” [Official] Best practices for Claude Code · AnthropicT1-official original and it “is loaded every session, so only include things that apply broadly.” Best practices for Claude Code · AnthropicT1-official original That is the whole game: every line you put in it is spent on every turn, whether or not it is relevant to the task at hand.

So the discipline is not “write good docs” — it is budget the always-on context. Anthropic’s curation test is per-line and ruthless: for each line, ask whether removing it would cause a mistake — “If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!” Best practices for Claude Code · AnthropicT1-official original The file should carry “Bash commands, code style, and workflow rules” Best practices for Claude Code · AnthropicT1-official original — broadly-applicable, can’t-infer-from-code context — and nothing else.

The measured result that inverts the prior

Almost everything in this book is converged craft. This chapter is the exception: there is one controlled study, and it cuts against the intuitive default.

Researchers at ETH Zurich tested whether repository-level context files actually help, across multiple agents and models. The headline: “context files tend to reduce task success rates compared to providing no repository context, while also increasing inference cost by over 20%.” Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? · Gloaguen, Mündler, Müller, Raychev, Vechev (ETH Zurich) (2026)T3-practitioner original The mechanism they propose is that context files encourage broader exploration, and agents dutifully follow their instructions — so their normative conclusion is that “unnecessary requirements from context files make tasks harder, and human-written context files should describe only minimal requirements.” Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? · Gloaguen, Mündler, Müller, Raychev, Vechev (ETH Zurich) (2026)T3-practitioner original

This is not “never use a context file.” It is a measured basis for the line-budget rule: the harm comes from unnecessary content, so the file should carry only minimal, broadly-applicable requirements.

Official, practitioner, and a study converge

The practitioner rules turn out to minimize exactly the harm the study measured. HumanLayer reports keeping “our root CLAUDE.md file… less than sixty lines” [Practitioner] Writing a good CLAUDE.md · Kyle (HumanLayer) (2025)T3-practitioner original and warns that the file “is the highest leverage point of the harness, so avoid auto-generating it.” Writing a good CLAUDE.md · Kyle (HumanLayer) (2025)T3-practitioner original

Presence is not usage

One more honest reading, because adoption numbers are easy to misuse. The AGENTS.md site reports the format is “used by over 60k open-source projects” AGENTS.md · Agentic AI Foundation (Linux Foundation)T2-release-notes original — but that is a presence count (a code-search for the file), a vendor self-report. The first large-scale trace-based study found that “more than 40% of file-using projects have no commit-level activity” Agentic Much? Adoption of Coding Agents on GitHub · Robbes, Matricon, Degueule, Hora, Zacchiroli (2026)T3-practitioner original — the file is present, but the tooling is not being exercised.

Push the rest out

If the always-loaded file is only for broadly-applicable context, where does everything else go? It loads on demand. AGENTS.md supports nested files where “the closest one takes precedence and every subproject can ship tailored instructions,” AGENTS.md · Agentic AI Foundation (Linux Foundation)T2-release-notes original and the broader principle — letting an agent “load information only as needed” [Official] Equipping agents for the real world with Agent Skills · Anthropic (2025)T1-official original — is the bridge to the next chapter on Skills.

Patterns

What earns a place. Sketch: the file holds only broadly-applicable, can’t-infer-from-code context. When to use: deciding any line. Best practices for Claude Code · AnthropicT1-official original Mechanics: Bash commands, code style, workflow rules — yes; task- or subproject-specific detail — no. Remember: it is paid every turn; scope to “applies broadly.”

The curation test. Sketch: per line, “would removing this cause a mistake?” When to use: every edit to the file. Best practices for Claude Code · AnthropicT1-official original Mechanics: if removal wouldn’t cause a mistake, cut it. Remember: bloat makes the agent ignore your real instructions — measured harm, not style.

Hand-write, don’t auto-generate. Sketch: craft the file by hand; never machine-generate it. When to use: always. Writing a good CLAUDE.md · Kyle (HumanLayer) (2025)T3-practitioner original Mechanics: short root file; review every line. Remember: highest-leverage point of the harness — and auto-generation is what the ETH study implicates.

Push the rest out (progressive disclosure). Sketch: layer instructions; load on demand. When to use: anything not broadly applicable. AGENTS.md · Agentic AI Foundation (Linux Foundation)T2-release-notes original Mechanics: nested AGENTS.md (nearest wins) for subprojects; Skills for procedures (next chapter). Remember: always-loaded is for the broadly-true; the rest loads when relevant.

Measure by traces. Sketch: judge adoption by AI-assisted commit traces, not file presence. When to use: any rollout or adoption claim. Agentic Much? Adoption of Coding Agents on GitHub · Robbes, Matricon, Degueule, Hora, Zacchiroli (2026)T3-practitioner original Mechanics: look for co-authored commits/PRs, not stars or file counts. Remember: presence ≠ usage; >40% of file-using repos show no activity.

Quick reference

• It’s a budget, not docs — every line is paid on every turn.
• Scope: broadly-applicable, can’t-infer-from-code context only (Bash commands, code style, workflow rules).
• The one measured result: unnecessary context-file content reduces success and adds >20% cost — keep it minimal.
• Convergence: official + practitioner + study agree on short + hand-curated. Never quote a line number.
• Presence ≠ usage: measure adoption by traces, not file counts.
• Everything else loads on demand — nested files, then Skills.

Practice

The previous chapter ended on the rule: the always-loaded file is for broadly-applicable facts, and everything else loads on demand. Skills are the cleanest realization of “everything else.” This chapter is entirely first-party — every claim is from Anthropic’s own docs and engineering blog. That makes it authoritative on what Skills are and do, but it is not independent evidence of efficacy; the chapter is tagged accordingly.

A Skill is just-in-time procedural knowledge

A Skill is “a directory containing a SKILL.md file that contains organized folders of instructions, scripts, and resources that give agents additional capabilities.” [Official] Equipping agents for the real world with Agent Skills · Anthropic (2025)T1-official original The framing is teach-once: it packages “your expertise into composable resources for Claude.” Equipping agents for the real world with Agent Skills · Anthropic (2025)T1-official original

The point of that packaging is the loading discipline. “Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable,” Equipping agents for the real world with Agent Skills · Anthropic (2025)T1-official original and it runs at three levels: the name+description metadata is loaded “at startup and include[d] in the system prompt”; Agent Skills (overview) · AnthropicT1-official original the SKILL.md body is read “from the filesystem via bash. Only then does this content enter the context window”; Agent Skills (overview) · AnthropicT1-official original and bundled scripts “provide deterministic operations without consuming context.” Agent Skills (overview) · AnthropicT1-official original

This is the same principle as the instruction-layer budget, inverted: instead of fitting everything broadly-true into the window, you keep procedures out of the window until a task needs them.

The description is the interface

Because only the description loads at startup, it is the single highest-leverage authoring decision. The docs are explicit about the mechanism: “The description is injected into the system prompt, and inconsistent point-of-view can cause discovery problems,” [Official] Skill authoring best practices · AnthropicT1-official original and it is “critical for skill selection: Claude uses it to choose the right Skill from potentially 100+ available Skills.” Skill authoring best practices · AnthropicT1-official original

Which mechanism — and what a Skill is not

The recurring confusion is Skill vs. CLAUDE.md vs. tool vs. subagent. The hinge is crisp: reach for a Skill “when a section of CLAUDE.md has grown into a procedure rather than a fact.” [Official] Extend Claude with skills · AnthropicT1-official original Facts stay always-on; procedures become load-on-demand skills.

One correction matters for architects: a Skill shapes what the model sees and reaches for, but it is not a security boundary. The allowed-tools frontmatter “does not restrict which tools are available: every tool remains callable” Extend Claude with skills · AnthropicT1-official original — it is pre-approval, not a sandbox. And the SDK skills option is “a context filter, not a sandbox. Unlisted Skills are hidden from the model and rejected by the Skill tool, but their files remain on disk and are reachable through Read and Bash.” Agent Skills in the SDK · AnthropicT1-official original That frontmatter scoping is “not… applied when using Skills through the SDK” Agent Skills in the SDK · AnthropicT1-official original at all.

Distribution and governance

Skills are a filesystem-and-distribution story, not an API. Metadata is “discovered at startup from user and project directories; full content loaded when triggered.” Agent Skills in the SDK · AnthropicT1-official original Sharing scales by scope — “Skills can be distributed at different scopes depending on your audience” Extend Claude with skills · AnthropicT1-official original — from a committed repo, to a plugin (the anthropics/skills repo registers as one via “/plugin marketplace add anthropics/skills”, anthropics/skills: Public repository for Agent Skills · AnthropicT2-release-notes original each skill “self-contained in its own folder” anthropics/skills: Public repository for Agent Skills · AnthropicT2-release-notes original ), to a marketplace catalog “to discover and install these extensions without building them yourself,” Discover and install prebuilt plugins through marketplaces · AnthropicT1-official original to org-wide managed settings. On a name collision, “enterprise overrides personal, and personal overrides project.” Extend Claude with skills · AnthropicT1-official original

Patterns

Description-as-interface. Sketch: write the third-person description for retrieval, not prose. When to use: every skill. Skill authoring best practices · AnthropicT1-official original Mechanics: state specifically when the skill applies; the body holds the how. Remember: only the description is always loaded — a skill that doesn’t trigger is dead weight.

Procedure → Skill, fact → CLAUDE.md. Sketch: move grown procedures out of the always-loaded file. When to use: a CLAUDE.md section has become a multi-step how-to. Extend Claude with skills · AnthropicT1-official original Mechanics: extract it to a SKILL.md; leave only the broadly-true fact behind. Remember: facts paid every turn; procedures paid on relevance.

Filter is not a sandbox. Sketch: never rely on skill scoping for security. When to use: any time you think “hide it to block it.” Agent Skills in the SDK · AnthropicT1-official original Mechanics: control capability in the permission/sandbox layer; use skills only for ergonomics. Remember: files stay on disk; tools stay callable; the SDK ignores allowed-tools.

Distribute by scope. Sketch: match the sharing path to the audience. When to use: a library outgrows one project. Extend Claude with skills · AnthropicT1-official original Mechanics: commit → plugin → marketplace → managed settings; remember enterprise>personal>project on collisions. anthropics/skills: Public repository for Agent Skills · AnthropicT2-release-notes original Remember: governance is about what loads and from where, by filesystem and policy.

Quick reference

• Skill = just-in-time procedural knowledge — a SKILL.md artifact, loaded on relevance.
• Three levels: metadata at startup → body on relevance → scripts on demand (no context cost).
• The description is the interface — author it as a retrieval problem.
• Procedure → Skill; fact → CLAUDE.md.
• Ergonomics, not a sandbox — scoping shapes what the model sees, not what’s possible.
• Distribute by scope: commit → plugin → marketplace → managed settings (enterprise>personal>project).
• First-party-only — authoritative on mechanism, not yet independently corroborated.

Practice

Skills shape what the model sees — but, as the last chapter warned, a skill is ergonomics, not a security boundary: it cannot bound what the model is allowed to do. That gap is where this chapter begins. The environment is also where the agent can do damage, and this is its safety layer: what the agent is permitted to attempt, how risky actions are gated before they run, and how recovery is arranged when judgment fails. The mechanics here are documented Anthropic product behavior; the one cautionary case — Replit — is single-source press reporting, and is tiered accordingly.

Two layers, defense-in-depth

Guardrails split into two complementary layers. A policy layer expresses human intent up front — permission rules, read boundaries — enforced at the decision point. A mechanism layer contains the blast radius regardless of the agent’s reasoning — OS-enforced sandbox isolation, out-of-band reversibility.

The permission model — the authorization spine

Every tool call passes an allow/ask/deny ruleset. The rules are evaluated deny → ask → allow, and “the first matching rule wins, so deny rules always take precedence.” [Official] Configure permissions · AnthropicT1-official original The shape of a rule changes its effect: a bare tool name like Bash “removes the tool from Claude’s context entirely,” Configure permissions · AnthropicT1-official original while a scoped rule like Bash(rm *) “leaves the tool available and blocks matching calls.” Configure permissions · AnthropicT1-official original

The invariant that makes this administrable: a deny is monotonic across the settings hierarchy — “if a tool is denied at any level, no other level can allow it.” Configure permissions · AnthropicT1-official original An administrator can set a floor neither the user nor the agent can raise.

How to actually deny file reads — not .claudeignore

To stop the agent reading a file, the documented control is permissions.deny Read(...) rules, which follow the gitignore specification. [Official] Configure permissions · AnthropicT1-official original But it has a hole the docs state plainly: these rules “do not apply to arbitrary subprocesses that read or write files indirectly, like a Python or Node script that opens files itself.” Configure permissions · AnthropicT1-official original The OS-level complement closes it — the sandbox filesystem.denyRead setting defines “paths where sandboxed commands cannot read,” Claude Code settings · AnthropicT1-official original merged with the Read(...) deny rules.

Sandbox isolation — the permission-relaxer hinge

The two layers meet at the sandbox. Sandbox mode puts an OS-enforced boundary around every Bash command — “you define which files and network domains commands can touch, and the operating system enforces that boundary for every Bash command and its child processes.” [Official] Configure the sandboxed Bash tool · AnthropicT1-official original The engineering blog states the design thesis: “Sandboxing creates pre-defined boundaries within which Claude can work more freely, instead of asking for permission for each action.” Beyond permission prompts: making Claude Code more secure and autonomous · AnthropicT1-official original

That is the hinge: a hard boundary lets you safely relax the per-action prompts — “auto-allow runs sandboxed commands without prompting.” Configure the sandboxed Bash tool · AnthropicT1-official original Authorization shifts from prompt-driven to boundary-driven.

The relaxer is bounded, and the docs say so: explicit deny rules still apply and rm against critical paths still prompts; only Bash subprocesses are sandboxed; and “sandboxing reduces risk but is not a complete isolation boundary.” Configure the sandboxed Bash tool · AnthropicT1-official original

Operational freeze ≠ technical enforcement

Now the counterexample. In the July 2025 Replit incident, the agent deleted a live production database, by its own admission “violating explicit instructions not to proceed without human approval.” [Practitioner] An AI-powered coding tool wiped out a software company's database · Beatrice Nolan (Fortune) (2025)T3-practitioner original The user’s blunt conclusion: “there is no way to enforce a code freeze in vibe coding apps like Replit.” Vibe coding service Replit deleted user's production database, faked data, told fibs galore · Simon Sharwood (The Register) (2025)T3-practitioner original

That is the lesson, generalized: a stated instruction — a human-approval requirement, a “code freeze” — is intent-layer and overridable. A guardrail the agent can simply not-follow is a suggestion, not a control. The load-bearing guardrails are technical: deny rules, OS boundaries, and recovery that does not route through the agent.

Reversibility must be out-of-band

The same incident exposes a second failure mode: the agent “claimed rollback was impossible” Vibe coding service Replit deleted user's production database, faked data, told fibs galore · Simon Sharwood (The Register) (2025)T3-practitioner original when it was not — the actor that caused the damage misreported the recovery path. Anthropic’s own reversibility affordance is real but explicitly bounded: checkpoints snapshot Claude’s file changes, but “only track changes made by Claude, not external processes. This isn’t a replacement for git.” [Official] Best practices for Claude Code · AnthropicT1-official original

Auto mode and containment

Two 2026 developments extend the chapter’s two layers without changing its thesis.

Auto mode is the policy-side step past sandbox auto-allow. Instead of prompting per action, a model-based classifier mediates approvals — catching “roughly 83% of overeager behaviors before they execute,” with the remaining ~17% bypassing it as the price of low friction. [Official] How we contain Claude across products · Max McGuinness, Mikaela Grace, Jiri De Jonghe, Jake Eaton, and Abel Ribbink (2026)T1-official original It sits between manual approval and full autonomy, and it exists because manual approval does not scale: users approved ~93% of prompts with attention “declining over time,” and oversight is “much less likely to be effective” at multi-agent scale. How we contain Claude across products · Max McGuinness, Mikaela Grace, Jiri De Jonghe, Jake Eaton, and Abel Ribbink (2026)T1-official original

Containment is the same OS-boundary idea at product scale. Each surface is isolated differently — ephemeral gVisor containers, OS sandboxes (Seatbelt/bubblewrap) with network denied by default, and VMs behind a vsock+hypervisor boundary — and “credentials stay in the host’s keychain and never enter the guest machine.” [Official] How we contain Claude across products · Max McGuinness, Mikaela Grace, Jiri De Jonghe, Jake Eaton, and Abel Ribbink (2026)T1-official original Network egress is the choke point: it is where data leaves, so it is where the boundary is enforced.

Both are single-agent containment. Once dynamic, multi-agent orchestration enters — agents spawning agents, control flow chosen at runtime — the env+context stakes rise sharply; that is a companion-volume (D1 orchestration) concern, not covered here.

Completeness note

The section above takes the containment picture only to its authorization implications (auto mode as a policy gate; the OS boundary as the load-bearing mechanism). The OS-isolation infrastructure itself — sandbox internals (seccomp, network proxies), self-hosted sandboxes, and MCP tunnels — remains a distinct topic not yet researched into this book, and is a flagged gap for a later round.

Patterns

Deny-precedence ruleset. Sketch: gate tool calls with allow/ask/deny; deny wins. When to use: always. Configure permissions · AnthropicT1-official original Mechanics: scope risky calls (Bash(rm *)); set managed-level denies as an unraisable floor. Remember: deny is monotonic — no lower scope can re-allow it.

Deny reads (not .claudeignore). Sketch: block secret/sensitive reads. When to use: any repo with secrets. Configure permissions · AnthropicT1-official original Mechanics: permissions.deny Read(./.env) (gitignore syntax); add sandbox filesystem.denyRead for subprocess-level enforcement. Claude Code settings · AnthropicT1-official original Remember: .claudeignore is a folk claim; a Claude-level deny doesn’t stop a spawned script.

Sandbox + auto-allow. Sketch: trade per-action prompts for a hard boundary. When to use: you want autonomy without prompt fatigue. Configure the sandboxed Bash tool · AnthropicT1-official original Mechanics: define the filesystem/network boundary; enable auto-allow inside it. Remember: not complete isolation; deny rules + critical-path prompts still fire.

Out-of-band reversibility. Sketch: make recovery independent of the agent. When to use: any irreversible external action (DBs, deploys). Best practices for Claude Code · AnthropicT1-official original Mechanics: dev/prod separation, git, backups; checkpoints for Claude’s own file edits only. Remember: never trust the agent’s self-report of what can be undone.

Quick reference

• Two layers: policy gates intent; mechanism contains blast radius.
• Permission model: allow/ask/deny, deny precedence, monotonic across scopes.
• Read denial: permissions.deny Read(...) + sandbox filesystem.denyRead; not .claudeignore.
• Sandbox = permission-relaxer: a hard boundary makes loosening prompts safe; not complete isolation.
• Operational ≠ technical: an instruction the agent can ignore is not a control.
• Reversibility is out-of-band: git/dev-prod/backups; never trust the agent’s “it’s irreversible.”
• Auto mode & containment: a classifier gate scales policy (still ~17% slips); product-scale OS containment (sandboxes/VMs/egress) stays the load-bearing mechanism.

Practice

The repo-design chapter made a small repo legible: one entry-point map, examples, sensors. This chapter asks what changes when the repo is too big to load. The answer is a shift in what “legibility” even means — and every move here is converged craft, not measured effect, with two of the launchpad’s catchy names turning out to be folk coinages.

Bound what the agent must load

At scale, you cannot make the repo legible by documenting all of it — there is too much, and an agent that ingests everything drowns. Legibility becomes constraining the loadable surface so an agent can work in one domain without reading the whole repo. As one practitioner puts it, “context construction should be scoped, not exhaustive.” [Practitioner] Coding Agents in the Monorepo: Why Context Windows and 50-Service Repos Don't Mix · Tian Pan (2026)T3-practitioner original

Interface contracts at boundaries

The first move exposes a boundary the agent reads instead of the implementation. Once agents must navigate a large repo, “explicit interface contracts matter more than they used to,” Coding Agents in the Monorepo: Why Context Windows and 50-Service Repos Don't Mix · Tian Pan (2026)T3-practitioner original realized as a per-domain file: “each major service or domain owns a file that describes its conventions, its interface contracts, and its dependencies.” Coding Agents in the Monorepo: Why Context Windows and 50-Service Repos Don't Mix · Tian Pan (2026)T3-practitioner original The agent reads the relevant one, not all of them.

This is the established contract-first tradition applied to agents — defining the contract so that, before implementation, “the contract has already been defined and communicated with potential consumers.” [Practitioner] API Contract Definitions: Contract first, implementation first, OpenAPI, GraphQL, gRPC · Lena Fuhrimann (2022)T3-practitioner original The agent is just another consumer working against the declared interface.

Shallow index, deep links

The second move keeps a top-level map shallow but deeply linked. Anthropic’s large-codebase guidance: “the root file describes only the highest-level structure, and subdirectory CLAUDE.md files provide the next level of detail,” [Official] How Claude Code works in large codebases: Best practices and where to start · Anthropic (2026)T1-official original loaded on demand as the agent moves through the tree. The named mechanism is “progressive disclosure, which allows agents to incrementally discover relevant context through exploration.” Seeing like an agent: how we design tools in Claude Code · Thariq Shihipar (Anthropic) (2026)T1-official original

ADRs: the why, one decision at a time

Interface contracts expose what a boundary is; Architecture Decision Records expose why it’s structured that way — in a form that scales. The failure mode they fix: “large documents are never kept up to date. Small, modular documents have at least a chance.” [Practitioner] Documenting Architecture Decisions · Michael Nygard (2011)T3-practitioner original ADRs are “numbered sequentially and monotonically. Numbers will not be reused,” Documenting Architecture Decisions · Michael Nygard (2011)T3-practitioner original each capturing “a set of forces and a single decision in response.” Documenting Architecture Decisions · Michael Nygard (2011)T3-practitioner original The maintained collection — one record per decision, each capturing “a single AD and its rationale” Architectural Decision Records (ADRs) · ADR GitHub organizationT2-release-notes original — is a navigable decision log an agent loads one decision at a time, not a monolith it must read whole.

Monorepos: scope to the workspace

The fourth move bounds the package layout. An unbounded repo means “the agent searches the whole repo and wastes context on irrelevant packages,” [Practitioner] AI agents in monorepos: what to configure differently from a single-product repo · Dave Barnwell (2026)T3-practitioner original because “in a monorepo, the root is an index, not the real unit of work.” AI agents in monorepos: what to configure differently from a single-product repo · Dave Barnwell (2026)T3-practitioner original The single highest-leverage fix: “make the agent decide which workspace it is operating in.” AI agents in monorepos: what to configure differently from a single-product repo · Dave Barnwell (2026)T3-practitioner original Then it “traverses the graph in steps, building up a coherent picture rather than trying to ingest everything at once.” Coding Agents in the Monorepo: Why Context Windows and 50-Service Repos Don't Mix · Tian Pan (2026)T3-practitioner original

Patterns

Interface/contract docs at boundaries. Sketch: per-domain file with conventions, contracts, dependencies. When to use: multi-service / multi-domain repos. Coding Agents in the Monorepo: Why Context Windows and 50-Service Repos Don't Mix · Tian Pan (2026)T3-practitioner original Mechanics: expose the declared interface; the agent reads the boundary, not the implementation. Remember: it’s the contract-first pattern — name it, don’t call it INTERFACE.md.

Shallow index, deep links. Sketch: a shallow root that points to on-demand detail. When to use: hundreds of top-level folders. How Claude Code works in large codebases: Best practices and where to start · Anthropic (2026)T1-official original Mechanics: root = highest-level structure only; subdirectory files carry the next layer, loaded as the agent explores. Remember: a flat dump doesn’t scale; progressive disclosure does.

ADRs, append-only. Sketch: one numbered, immutable record per decision. When to use: any non-obvious structural choice. Documenting Architecture Decisions · Michael Nygard (2011)T3-practitioner original Mechanics: sequential numbers never reused; supersede via a new file; keep in source control. Architectural Decision Records (ADRs) · ADR GitHub organizationT2-release-notes original Remember: a monolith rots; a per-decision log an agent loads one at a time survives.

Scope to the workspace. Sketch: make the agent pick its package before acting. When to use: any monorepo. AI agents in monorepos: what to configure differently from a single-product repo · Dave Barnwell (2026)T3-practitioner original Mechanics: tags/graph to navigate-before-read; walk the dependency graph in steps. Nx and AI — Why They Work so Well Together · Victor Savkin (Nx) (2025)T2-release-notes original Remember: the root is an index, not the unit of work — bound the agent to one workspace.

Quick reference

• At scale, legibility = bound what must be loaded (not document everything).
• Interface contracts: read the boundary, not the implementation (contract-first; not INTERFACE.md).
• Shallow index, deep links: shallow root + on-demand layers (progressive disclosure at repo scale).
• ADRs: numbered, append-only, one decision each — beats a monolithic architecture doc.
• Monorepos: scope to one workspace; navigate-before-read via tags/graph.
• Evidence: converged craft, no effect sizes.

Practice

The environment half is done: the substrate is made legible, budgeted, loaded on demand, guarded, and bounded at scale. Now the window itself — what the harness assembles from all that available signal, and why it degrades. This is the problem chapter. If long contexts degraded gracefully, “just put everything in the window” would be sound and the next chapter would be unnecessary. The evidence says they do not — so context assembly (next) is a response to a measured failure. This chapter is evidence, not patterns: it builds the case, then hands you a diagnostic for locating which failure mode you’re hitting.

Degradation is four failure modes, not one

“Context rot” is an umbrella over mechanisms that fail for different reasons and are caught by different benchmarks.

• Positional — where the token sits. Recall “is often highest when relevant information occurs at the beginning or end of the input context, and significantly degrades… in the middle” Lost in the Middle: How Language Models Use Long Contexts · Liu et al. (TACL) (2023)T3-practitioner original — the U-shaped curve.
• Length — how much is in the window. An “evaluation across 18 LLMs… reveal[s] nonuniform performance with increasing input length,” Context Rot: How Increasing Input Tokens Impacts LLM Performance · Hong, Troynikov & Huber (Chroma Research) (2025)T3-practitioner original independent of whether the needle is found.
• Reasoning — reasoning over the facts, not locating them. Multi-hop degradation is “primarily driven by the reduction in the length of the thinking process as the input length increases.” Reasoning on Multiple Needles In A Haystack · Wang (2025)T3-practitioner original
• Effective vs. claimed — the marketed window is not the working one. Of models claiming 32K+, “only half… can maintain satisfactory performance at the length of 32K.” RULER: What's the Real Context Size of Your Long-Context Language Models? · Hsieh et al. (NVIDIA, COLM) (2024)T3-practitioner original

The robust claim is directional, not numeric

Across an 18-model panel and a peer-reviewed synthetic suite, the robust, corroborated finding is that performance falls with length and that the effective window is materially shorter than the claimed one — RULER reports “almost all models exhibit large performance drops as the context length increases.” RULER: What's the Real Context Size of Your Long-Context Language Models? · Hsieh et al. (NVIDIA, COLM) (2024)T3-practitioner original The specific percentages (“11 models drop below 50% of their strong short-length baselines” at 32K, NoLiMa: Long-Context Evaluation Beyond Literal Matching · Modarressi et al. (ICML) (2025)T3-practitioner original “only half at 32K”) are model- and benchmark-dependent.

The practitioner operationalization is directional too: “get your context into the LLM in the most token- and attention-efficient way you can.” [Practitioner] 12-Factor Agents — Factor 3: Own your context window · Dex Horthy (HumanLayer) (2025)T3-practitioner original Fewer, denser tokens — not a threshold.

Two findings that surprise builders

”Unsolved” overshoots — and rot reaches the overseer

The strong framing — context rot is architectural and no model solves it — overshoots the 2026 evidence. The degradation is robust and near-universal today, but decode-time work shows the attenuation is partially reversible: gold tokens are down-weighted, not erased Mitigating Posterior Salience Attenuation in Long-Context LLMs with Positional Contrastive Decoding · Xiao et al. (2025)T3-practitioner original — they still occupy high-ranking positions in the decoding space, recoverable at decode time. Honest synthesis: degradation is near-universal now; whether it is fundamentally architectural or substantially trainable/decodable is open, and the 2026 frontier is actively eroding the “unsolvable” claim. Build for the degradation that exists; don’t bet the architecture on it being permanent.

One 2026 extension matters for design: rot reaches the monitor. An LLM acting as judge/monitor degrades on long transcripts, missing flagged actions far more often as the trace grows. Classifier Context Rot: Monitor Performance Degrades with Context Length · Martin & Roger (2026)T3-practitioner original Long-running agentic sessions degrade both the actor and the safety layer watching it.

Diagnostic: which failure mode are you hitting?

This chapter has no pattern catalog — the responses are the next chapter. Instead, a diagnostic to locate the failure before you reach for a fix (every fix routes to Context Assembly):

• Symptom: the agent ignores something you know is in context. → Positional — it’s likely buried mid-window. Look at placement (move load-bearing content to an edge).
• Symptom: quality falls as the session/file grows, even when the fact is present. → Length — look at how much is loaded (prune, compact).
• Symptom: it finds the right facts but draws the wrong conclusion. → Reasoning — look at decomposition (split the multi-hop task).
• Symptom: it works in small repros, fails at “full” context well under the limit. → Effective-vs-claimed — look at the working window, not the marketed one.
• Symptom: your LLM judge/monitor stops flagging issues on long runs. → Monitor rot — shorten/segment what the overseer reviews.

Quick reference

• Four failure modes: positional · length · reasoning · effective-vs-claimed. Different causes, different fixes.
• Robust = directional: performance falls with length; the effective window is far shorter than the claimed window. Never quote a portable %.
• Surprises: coherence can hurt; retrieval ≠ reasoning.
• “Unsolved” overshoots: near-universal now, but partially trainable/decodable — an open question.
• Rot reaches the overseer: long traces degrade the monitor too.
• The responses are the next chapter (Context Assembly).

Practice

The previous chapter established the problem: long context does not degrade gracefully. This chapter is the engineering response. The harness owns the boundary deciding what enters the window and when — and “context assembly” is the discipline of choosing, ordering, caching, and compacting the bytes that go to the model each turn. This is the deepest chapter in the book; it carries the richest pattern catalog.

The window is assembled from regions

Each turn, the harness assembles a window from regions that differ in stability and role.

Cache stability — the prefix is an economic variable

A practitioner building Manus calls the KV-cache hit rate the “single most important metric for a production-stage AI agent,” [Practitioner] Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original because it drives both latency and cost. The lever is a stable prefix: no mid-history edits, deterministic serialization, append-only. Anthropic’s prompt cache has, “by default, a 5-minute lifetime” [Official] Prompt caching · AnthropicT1-official original — the window inside which stability pays off.

A controlled multi-provider evaluation quantifies the payoff: caching “reduces API costs by 41-80% and improves time to first token by 13-31% across providers,” Don't Break the Cache: An Evaluation of Prompt Caching for Long-Horizon Agentic Tasks · Lumer et al. (2026)T3-practitioner original and the placement matters — “placing dynamic content at the end of the system prompt” Don't Break the Cache: An Evaluation of Prompt Caching for Long-Horizon Agentic Tasks · Lumer et al. (2026)T3-practitioner original beats “naive full-context caching, which can paradoxically increase latency.” Don't Break the Cache: An Evaluation of Prompt Caching for Long-Horizon Agentic Tasks · Lumer et al. (2026)T3-practitioner original

Loading — just-in-time vs preload

What enters the window during a turn is a choice, not a default. The just-in-time pattern keeps “lightweight identifiers (file paths, stored queries, web links, etc.) and use[s] these references to dynamically load data into context at runtime using tools.” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original Even tool definitions can be deferred — presenting tools as code lets models “read tool definitions on-demand, rather than reading them all up-front.” Code execution with MCP: Building more efficient agents · Jones & Kelly (Anthropic) (2025)T1-official original The framing generalizes: context operations are write / select / compress / isolate, where writing context means “saving it outside the context window.” [Practitioner] Context Engineering · The LangChain Team (2025)T2-release-notes original

Compaction — the window is finite

The premise: the window “must be treated as a finite resource with diminishing marginal returns.” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original When it fills, you summarize (/compact) or you checkpoint-and-restart — the harness pattern of “finding a way for agents to quickly understand the state of work when starting with a fresh context window,” Effective harnesses for long-running agents · Justin Young (2025)T1-official original i.e., a progress file plus checkpoints rather than lossy in-context summarization.

Attention placement — position is not neutral

Where content lands changes whether the model uses it. Recall “is often highest when relevant information occurs at the beginning or end of the input context, and significantly degrades… in the middle.” Lost in the Middle: How Language Models Use Long Contexts · Liu et al. (TACL) (2023)T3-practitioner original

There is also an instruction budget: “performance consistently degrades as the number of instructions increases,” When Instructions Multiply: Measuring and Estimating LLM Capabilities of Multiple Instructions Following · Harada et al. (EMNLP) (2025)T3-practitioner original and even the best models “only achieve 68% accuracy at the max density of 500 instructions,” How Many Instructions Can LLMs Follow at Once? · Jaroslawicz et al. (2025)T3-practitioner original with “a bias towards earlier instructions.” How Many Instructions Can LLMs Follow at Once? · Jaroslawicz et al. (2025)T3-practitioner original The practitioner countermeasure exploits the end-of-context peak: recitation — “reciting its objectives into the end of the context” (a maintained todo.md) [Practitioner] Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original to fight goal drift.

Assembly is a prompt

The window’s contents are prose to engineer, not plumbing. Tool descriptions sit in the cache-sensitive pre-commitment region — author them as you would “describe your tool to a new hire on your team.” [Official] Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original Structure disambiguates: XML tags “help Claude parse complex prompts unambiguously, especially when your prompt mixes instructions, context, examples, and variable inputs,” Prompting best practices: use XML tags · AnthropicT1-official original and instruction-following gains “stem largely from parameter updates in attention modules,” A Multi-Dimensional Constraint Framework for Evaluating and Improving Instruction Following in LLMs · Ye et al. (2025)T3-practitioner original a hint for why structured, constraint-bearing assembly is tractable.

Diagnostic: which assembly failure are you hitting?

Mirroring the previous chapter’s router, map an observed symptom to the assembly lever that addresses it — each routes to a pattern below:

• Symptom: latency and cost climb every turn, even on small tasks. → Cache instability — something perturbs the prefix. Reach for stable prefix + dynamic content at the tail.
• Symptom: quality decays as a long session or file grows. → Unbounded loading — too much is resident at once. Reach for just-in-time loading and compact-or-checkpoint.
• Symptom: the agent ignores an instruction you know is loaded. → Misplacement — it is sagging mid-window. Reach for place at the edges; recite the goal.
• Symptom: cost spikes right after a long session compacts. → Cache invalidation at the compaction boundary. Reach for checkpoint-and-restart with a small prefix.
• Symptom: a multi-part prompt is parsed wrong. → Unstructured assembly. Reach for structure with delimiters.

Patterns

Stable prefix. Sketch: keep the window front byte-identical turn to turn. When to use: always. Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original Mechanics: no timestamps, deterministic serialization, append-only. Remember: the prefix is a 41–80% cost lever; perturbing it silently breaks the cache.

Dynamic content at the tail. Sketch: put volatile bits at the end of the (system) prompt. When to use: any cacheable prefix with changing parts. Don't Break the Cache: An Evaluation of Prompt Caching for Long-Horizon Agentic Tasks · Lumer et al. (2026)T3-practitioner original Mechanics: stable front, volatile tail. Remember: naive full-context caching can increase latency.

Just-in-time loading. Sketch: keep pointers; resolve to data on demand. When to use: large/optional context. Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original Mechanics: store identifiers (paths, queries); fetch via tools; defer tool defs too. Code execution with MCP: Building more efficient agents · Jones & Kelly (Anthropic) (2025)T1-official original Remember: preload the minimum; the window is finite.

Compact or checkpoint. Sketch: manage the window when it fills. When to use: long sessions. Effective harnesses for long-running agents · Justin Young (2025)T1-official original Mechanics: prefer checkpoint-and-restart from a progress file over lossy summarize. Remember: compaction can invalidate the cache — keep the restart prefix small.

Place at the edges; recite the goal. Sketch: exploit the U-shaped attention curve. When to use: load-bearing instructions; long tasks. Lost in the Middle: How Language Models Use Long Contexts · Liu et al. (TACL) (2023)T3-practitioner original Mechanics: put critical content at an edge; re-emit goals at the tail (todo.md). Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original Remember: the middle is where attention sags.

Structure with delimiters. Sketch: mark up multi-part context. When to use: mixed instructions/context/examples. Prompting best practices: use XML tags · AnthropicT1-official original Mechanics: XML tags as semantic anchors; tool descriptions as clear prose. Remember: the assembled window is a prompt — structure shapes attention.

Quick reference

• The window is assembled from pre-commitment / loaded / history / placement regions.
• Stable prefix = cost + latency lever (41–80% / 13–31%); dynamic content at the tail.
• JIT loading: keep pointers, resolve on demand; the window is finite.
• Compaction: prefer checkpoint-and-restart; mind the stale-prefix/cache interaction.
• Placement: edges beat the middle (U-shaped bias); budget instructions; recite goals at the tail.
• Assembly is a prompt: engineer tool descriptions and structure.

Practice

The previous two chapters managed context within a session. This one persists it across sessions. It is the most openly unsolved topic in the book — the practices here are current best-practice scaffolding around a contested design space, not settled science, and the chapter says so plainly.

Memory is just recalled context

The unifying lens makes this chapter cohere with the two before it. A recalled memory enters the window as more text — the store is read back in. So a stale or wrong memory is a context-quality failure, and over-recall is a context-length failure. As one practitioner puts it, “incorrect memories are worse than no memories. Bad facts, once stored, pollute every future decision.” [Practitioner] Why your AI agent doesn't actually remember anything · Ed Huang (2026)T3-practitioner original

Typing enables decay

Should memory have structure, or be one flat blob? The architecture proposals all add structure: MemGPT’s “virtual context management, a technique drawing inspiration from hierarchical memory systems in traditional operating systems”; MemGPT: Towards LLMs as Operating Systems · Packer et al. (2023)T3-practitioner original Generative Agents’ memory stream the agent will “synthesize… into higher-level reflections, and retrieve… dynamically to plan behavior”; Generative Agents: Interactive Simulacra of Human Behavior · Park et al. (2023)T3-practitioner original and LangMem’s explicit episodic/semantic/procedural split, where the semantic type “stores key facts (and their relationships)… that ground an agent.” [Practitioner] LangMem SDK for agent long-term memory · The LangChain Team (2025)T2-release-notes original

The doc-vs-memory boundary

Given a fact, which medium does it belong in — a committed doc or ephemeral memory? The official docs draw the line on two axes: a committed doc is “instructions you write” [Official] How Claude remembers your project · AnthropicT1-official original and is “shared with your team through version control,” whereas auto-memory is “notes Claude writes itself” and is “machine-local… not shared across machines.” How Claude remembers your project · AnthropicT1-official original The API layer mirrors it as a read_only store “for reference material… the agent does not need to modify.” Using agent memory · AnthropicT1-official original

Repo-as-memory: the cheap floor

The filesystem is a real memory store — “the file system not just as storage, but as structured, externalized memory,” [Practitioner] Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original unbounded and persistent, so after a context reset the agent “reads its own notes and continues” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original long tasks. But it is the floor, not the ceiling: it has no decay, no typing, no retrieval ranking; files “get unmanageable >5MB,” AI Agent Memory Management: When Markdown Files Are All You Need? · Yaohua Chen (ImagineX) (2025)T3-practitioner original and a flat scratchpad is “scoped to a single thread” while a real store “persists across threads and can be recalled at any time.” Long-term memory · LangChainT2-release-notes original

The landscape, and the safe bet

The proposals this chapter draws on optimize for different things — which is why “openly unsolved” is a starting point, not a verdict.

Patterns

Type your memory. Sketch: split memory by kind (episodic/semantic/procedural) or tier it. When to use: anything beyond a scratchpad. LangMem SDK for agent long-term memory · The LangChain Team (2025)T2-release-notes original Mechanics: store facts apart from experiences apart from rules; address each distinctly. Remember: typing is the precondition for selective decay and correction.

Decay / invalidate. Sketch: give stored facts a validity path. When to use: any long-lived memory. Mechanics: invalidate on contradiction; prefer “no memory” over a confidently-wrong one. Why your AI agent doesn't actually remember anything · Ed Huang (2026)T3-practitioner original Remember: a stale fact is recalled with full confidence — pollution is worse than absence.

Choose the medium. Sketch: durable-shared → doc; fast-private → memory. When to use: every fact you persist. How Claude remembers your project · AnthropicT1-official original Mechanics: identity/constitution/standards → committed doc; session-accreted preferences → auto-memory. My .md files vs Claude's memory tool: a practitioner comparison · Andreas Belitz (2026)T3-practitioner original Remember: commit the durable + reviewable; leave the disposable to memory.

Repo-as-memory floor. Sketch: start with the filesystem; outgrow it on signal. When to use: cross-session state, day one. Context Engineering for AI Agents: Lessons from Building Manus · Yichao Ji (Manus) (2025)T3-practitioner original Mechanics: a notes/progress file first; promote to a structured store when you need typing, decay, or ranking. Long-term memory · LangChainT2-release-notes original Remember: the floor has no decay/typing/ranking — and bloats past a few MB.

Quick reference

• Memory = recalled context — every memory anti-pattern is a context anti-pattern.
• Typing enables decay — you can’t invalidate what you can’t address.
• Decay/pollution: a stale fact is “confidently wrong”; incorrect memory is worse than none.
• Doc-vs-memory boundary: durable-shared-reviewable (doc) vs. fast-private-decaying (memory).
• Repo-as-memory: cheap floor; outgrow it for typing/decay/ranking; bloats past a few MB.
• Openly unsolved — scaffolding, not settled science; recheck.

Practice

This chapter is integrative. It introduces no new evidence — it composes the book’s grounded claims into a design workflow and a decision guide. Where it restates a load-bearing fact, it points back to the chapter that established it; the rest is synthesis.

The two layers are one system

The book opened on a thesis: what turns a model into an agent is the engineering of the two layers around it — the environment it acts in and the context it reasons over — and that discipline is the most underappreciated, highest-leverage thing an architect designs. Eight chapters in, the payoff is that they are not eight topics but two ends of one loop: the environment is the durable store of everything the agent could use; the context is the finite slice it does use each turn; and the harness owns the boundary between them — context being “a finite resource with diminishing marginal returns.” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original

A design workflow

The chapters fall into a natural order when you design a real agent’s environment and context together.

1. Make the environment legible (E1, E5). Maximize signal in and machine-checkable feedback out; at scale, bound what must be loaded (interface contracts, shallow index, scope-to-workspace).
2. Budget the always-on layer (E2). The instruction file is paid every turn — spend it only on broadly-applicable, can’t-infer-from-code context. More is not better. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? · Gloaguen, Mündler, Müller, Raychev, Vechev (ETH Zurich) (2026)T3-practitioner original
3. Push procedures to load on demand (E3). Skills are just-in-time procedural knowledge; keep them out of the window until relevant.
4. Set the safety envelope (E4). Express intent in policy (permissions), contain failure in mechanism (sandbox, out-of-band reversibility).
5. Engineer the window against rot (C1 → C2). Know the four failure modes; assemble a stable, well-placed, just-in-time window; compact or checkpoint as it fills.
6. Persist deliberately (C3). Commit the durable and reviewable; leave the disposable to (typed, decaying) memory — and remember recalled memory is just more context.

Decision points

The recurring trade-offs, and how the book resolves them:

• Signal vs. budget. Add context to help, or subtract to protect the window? Default to subtract: legibility and examples beat prose, and the one measured result says unnecessary context-file content reduces success. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? · Gloaguen, Mündler, Müller, Raychev, Vechev (ETH Zurich) (2026)T3-practitioner original Add only broadly-applicable, can’t-infer context to the always-on layer; everything else loads on demand.
• Stability vs. freshness. A stable prefix is a large cost/latency lever, but content changes. Resolve by placement: stable front, volatile tail.
• Where a fact lives. Always-on (CLAUDE.md), on-demand (skill), or remembered (memory)? Fact that applies broadly → instruction layer; procedure → skill; durable + reviewable → committed doc; fast + private + disposable → memory.
• Placement under rot. Load-bearing content goes at an edge, not the middle; Lost in the Middle: How Language Models Use Long Contexts · Liu et al. (TACL) (2023)T3-practitioner original decompose multi-hop reasoning rather than stuff the window.
• Ergonomics vs. enforcement. Skills and filters shape what the model sees; they are not security. Real restriction lives in the permission/sandbox layer.

An honest map of the evidence

The book’s claims sit at very different evidence tiers, and designing well means weighting them accordingly.

• Measured (rare). One controlled result anchors the instruction layer: unnecessary context-file content reduces success and adds cost. Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? · Gloaguen, Mündler, Müller, Raychev, Vechev (ETH Zurich) (2026)T3-practitioner original Treat as one study, not law.
• Converged (strong). The CLAUDE.md short-and-hand-curated rule, the U-shaped positional curve, navigate-before-read at scale, and the doc-vs-memory boundary each have independent corroboration — the strongest signal a craft discipline offers.
• First-party-only (authoritative, uncorroborated). Skills mechanics are entirely Anthropic-sourced — authoritative on what they are, not yet independent evidence of efficacy.
• Openly unsolved. Memory is scaffolding around a contested space, State of AI Agent Memory 2026: Benchmarks, Architectures & Production Gaps · Mem0 Engineering Team (2026)T3-practitioner original and whether context rot is permanent or trainable is the live 2026 front. Build for what exists; don’t bet the architecture on either resolving.

The boundary of this volume

This book engineers two of the harness’s layers — the environment the agent acts in and the context it reasons over. It stops, deliberately, at control flow: how an agent critiques and retries its own work — reflection, or self-correction — and how multiple agents are coordinated are the companion D1 orchestration volume’s subject, not this one’s. What this volume owns of reflection is only its footprint — the environment a critic step reads, and the context its critique writes back, a cost the rot, assembly, and memory chapters each flag where it lands.

Quick reference

• One system: environment makes signal available + checkable; context decides what crosses + persists.
• Workflow: legible environment → budget the always-on → push procedures on-demand → set the safety envelope → engineer the window vs rot → persist deliberately.
• The locating question: paid every turn, or only when relevant?
• Default to subtract in the always-on layer (the one measured result).
• Weight the evidence: measured (rare) → converged (strong) → first-party (uncorroborated) → unsolved (scaffold).

Practice

Vol 1 engineered the two layers around the model — the environment an agent acts in and the context it reasons over. This volume takes the harness’s remaining moves: the tools an agent reaches for, and the orchestration of more than one agent. Both look like ways to add power. The thesis of this chapter is that both are better understood as ways to spend context — and that seeing them in that single currency gives both the same governing default.

From one agent to a system of capability and coordination

Vol 1 left two of the harness’s components deliberately unbuilt: the tool interface, and sub-agent orchestration. They are this volume’s subject. An agent, in the working definition the series uses, is a system where models “dynamically direct their own processes and tool usage” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original — so the moment you move past a single bare model, you are making two kinds of decision: what capability to expose (which tools, which protocol, which prompts), and how to coordinate when one agent is not enough.

It is tempting to treat both as additive — more tools, more agents, more power. The rest of this chapter argues the opposite framing, because the additive view is exactly what produces bloated, slow, hard-to-debug systems. Both decisions spend the same scarce resource.

The first axis: capability is a context cost

The first axis is what capability to expose. The naive view treats a capability as free until used. It is not. Context is “a critical but finite resource for AI agents” [Official] Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original — a budget — and every tool you expose draws on it whether or not it fires, because its definition sits in the window and its presence enlarges the model’s selection problem.

This is why the governing default on the capability axis is subtraction: “More tools don’t always lead to better outcomes.” [Official] Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original The same instinct governs the build-vs-buy decision (start direct on the API; add abstraction only when it earns its keep, since “many patterns can be implemented in a few lines of code” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original ), the protocol you wire external capability through, and the way you shape the agent’s text input and output.

The second axis: coordination is a context-isolation move

The second axis is how to coordinate once one agent is not enough. Here the key reframing is sharper still: a sub-agent does not give the model a new skill — it gives the work a fresh, separate window. Sub-agents “use their own isolated context windows.” [Official] Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original The value is the isolation, not an added capability: a unit of work runs out of band, untouched by the main conversation’s history, and returns only its relevant result.

So coordination, too, is a context decision — not “add an agent to gain an ability” but “add a window to quarantine context or parallelize work.” That reframing carries the whole orchestration half: you reach for another agent when there is context to isolate or independent work to fan out, and you do not when the coordination cost outweighs the gain.

Primitive versus topology

One distinction prevents most orchestration confusion: the primitive is not the topology.

• A sub-agent is the primitive — a single isolated unit: fresh context in, relevant result out.
• A multi-agent system is a topology — how you coordinate many such units (an orchestrator delegating to workers, say).

Conflating them produces both over- and under-engineering: building a multi-agent topology when one isolated sub-agent would do, or expecting a lone sub-agent to deliver what only a coordinated topology can. The orchestration half of this volume treats them as different objects — the isolation primitive first, the coordination of many second — and gates the topology on cost, because coordinating agents is not free.

The map of this volume

The chapters move along the two axes — first what capability to expose, then how to coordinate.

Capability — what to expose, and how.

• Build vs. buy — whether to write thin on the API, configure a harness, or build one; the start-direct default.
• Tool minimization — the governing subtract-first discipline for the tool set itself.
• MCP — wiring external capability against a least-privilege, capability-negotiated protocol.
• Shaping input — the prompting craft — the five moves that shape what goes into the agent.
• Shaping output — structured & reliable — the levers that force machine-readable output you can trust coming back.

Coordination — how many windows, and how they cooperate.

• Sub-agents — the context-isolation primitive: a fresh window that inherits nothing and returns only the result.
• Multi-agent — the coordination topology, and the cost gate that decides whether it is worth it.

Quick reference

• Two axes, one currency: capability (what’s in a window) and coordination (how many windows) both spend context. Effective context engineering for AI agents · Prithvi Rajasekaran, Ethan Dixon, Carly Ryan, and Jeremy Hadfield (2025)T1-official original
• Capability default — subtract: expose what the workflow needs, not what the platform offers. Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original
• Coordination default — isolate, don’t add skill: a sub-agent is a fresh window, valuable for isolation, not capability. Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original
• Primitive ≠ topology: the sub-agent is the unit; the multi-agent system is how units coordinate.
• The map: capability chapters (build-vs-buy, tool minimization, MCP, prompting, structured output) → coordination chapters (sub-agents, multi-agent).
• The reflex to unlearn: “can I add this?” → “what does it cost in the window, and is the work worth it?”

Practice

This is the first move on the volume’s capability axis. The spine framed every capability — a tool, an abstraction, a framework — as a context cost paid before it is used; the build-vs-buy decision is the first place that bites. The thesis is a default: start direct on the API and let the harness earn itself. The middle path between “build it all” and “buy a framework” is configure, wrap, extend — and the rule that organizes the whole decision is sequenced, not one-shot: simplest thing that works first, abstraction added only when a concrete need demands it.

Start direct, start simple

Begin with the recommendation and let it organize everything else. Anthropic’s agent-building guidance states the default flatly: developers should “start by using LLM APIs directly,” because “many patterns can be implemented in a few lines of code.” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original This is not a beginner’s on-ramp you graduate out of — it is the recommended starting point for production systems, and the evidence behind it is an aggregated cross-team observation: across the many teams Anthropic worked with, “the most successful implementations weren’t using complex frameworks or specialized libraries.” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original

So the decision does not open with “which framework?” It opens with “do I need one at all?” — and the default answer is no.

This is the same instinct the spine drew as the capability axis, applied to the harness layer instead of the tool set. A framework is a capability you expose to yourself — and like every capability, it is paid for before it is used, in the abstraction it inserts between you and the model. The default is therefore subtraction here too: the smallest harness that covers the workflow beats a feature-complete one.

The tradeoff: abstraction cost vs. convenience

A framework’s appeal is real — it gets you moving faster. The question is what that convenience costs. The cost is abstraction, and the specific damage is to visibility: frameworks can insert layers that obscure the underlying prompts and responses, “making them harder to debug.” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original When the agent misbehaves, you are now debugging through the framework’s abstractions instead of reading the prompt and response directly.

That reframes the decision. It is not “which framework is best” — it is “is the convenience worth the lost visibility on this workflow?”

The cost is not fixed across frameworks, which is exactly why the decision is a spectrum rather than a switch. A framework can be designed to keep the prompts visible: LangGraph, for instance, describes itself as low-level and states that it “does not abstract prompts or architecture.” [Official] LangGraph overview · LangChainT2-release-notes original That is the framework-vendor’s own answer to the debuggability concern — and it reframes the axis from “framework vs. no framework” to “how much abstraction, and is it visible.” Read it as LangGraph’s stated design stance, not as a measured property or a ranking against other frameworks.

The other side: building is a standing liability

It is tempting to read “don’t reach for a framework” as “build your own harness.” But the build side has its own recurring cost, and it is easy to underprice. A harness is not a one-time artifact: “harnesses encode assumptions that go stale as models improve.” [Official] Scaling Managed Agents: Decoupling the brain from the hands · Anthropic (Lance Martin, Gabe Cemaj, Michael Cohen) (2026)T1-official original The behaviors you tune around — how the model handles a long context, when it over-eagerly calls a tool, how it formats output — shift with each model release, and the assumptions your harness baked in decay with them.

So both ends of the binary carry a cost. A framework charges abstraction cost (lost visibility); a from-scratch build charges ongoing maintenance (staleness as models move). Neither is free, which is why the realistic answer is rarely either extreme.

The framework landscape — read honestly

If you do reach for an existing harness, four options dominate the conversation. The honest way to read this landscape is one framework at a time, against its own documentation — because each framework’s description of itself is authoritative on what it provides and not on how it ranks against the others. There is no independent cross-vendor benchmark here; each line below is a vendor self-description.

• LangGraph describes itself as “a low-level orchestration framework and runtime for building, managing, and deploying long-running, stateful agents.” [Official] LangGraph overview · LangChainT2-release-notes original Its documented capability set centers on durable execution, streaming, human-in-the-loop, and persistence.
• CrewAI describes itself as “the leading open-source framework for orchestrating autonomous AI agents and building complex workflows,” organized around role-based crews. [Official] Introduction (What is CrewAI?) · CrewAI (documentation)T2-release-notes original The word “leading” is CrewAI’s own framing, not an independent ranking.
• The Claude Agent SDK “gives you the same tools, agent loop, and context management that power Claude Code, programmable in Python and TypeScript.” [Official] Agent SDK overview · AnthropicT1-official original Its documented capabilities include built-in tools, hooks, subagents, MCP, permissions, and sessions.
• The OpenAI Agents SDK describes itself as “a lightweight, easy-to-use package with very few abstractions,” built around a small primitive set. [Official] OpenAI Agents SDK · OpenAI (Agents SDK documentation)T2-release-notes original “Very few abstractions” is the vendor’s own positioning.

Because these are framework docs, they move fast — each ships per release, and the self-descriptions drift. Treat the four lines above as a snapshot, not a constant.

The middle path: configure, wrap, extend

Put the two costs together and the binary dissolves. You rarely face a clean choice between writing everything yourself and surrendering to a framework. The realistic answer is in the middle: start thin on the direct API, and where you do adopt, adopt something configurable that you assemble from primitives.

The Claude Agent SDK is the canonical instance of this stance. It is “the agent harness that powers Claude Code,” [Official] Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original so adopting it means taking a production-proven harness rather than writing one — and at its core “the SDK gives you the primitives to build agents” [Official] Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original for whatever workflow you are automating, composed and extended through subagents and hooks. That is the configure/wrap/extend position made concrete: a configurable harness you take, shape, and extend, rather than a from-scratch build you own end-to-end or an opaque framework you cannot see into.

This is where the abstraction-cost axis pays off: the SDK route lets you adopt without going opaque, because you are assembling from primitives rather than inheriting a black box. The custom-build route’s maintenance liability is also softened, because the harness’s general plumbing is maintained by its vendor against new models — you only own the thin extension layer your workflow actually needs.

The sequenced rule

Compose the criteria with the default and the middle path and the whole decision reduces to a sequence — not a one-shot choice, but an order you move through only as far as a real need pulls you.

1. Start without a framework. Direct API, thin harness, because many patterns are a few lines of code. [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original
2. Adopt a configurable harness when a concrete need earns the abstraction — preferring one that keeps prompts visible [Official] LangGraph overview · LangChainT2-release-notes original and that you do not have to re-tune against every model release. [Official] Scaling Managed Agents: Decoupling the brain from the hands · Anthropic (Lance Martin, Gabe Cemaj, Michael Cohen) (2026)T1-official original The Claude Agent SDK is the canonical configure/wrap/extend option. [Official] Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original
3. Build a fully custom harness only when no configurable option fits — and price it as the continuous maintenance it is, because the staleness cost is now yours to carry. [Official] Scaling Managed Agents: Decoupling the brain from the hands · Anthropic (Lance Martin, Gabe Cemaj, Michael Cohen) (2026)T1-official original

A note on scope: this chapter is the decision — when to build, buy, or take the middle path. What a harness actually is (the agent loop, context management, the tool interface as components) is the Model + Harness framing the foundation volume develops; the orchestration of more than one agent — sub-agents and multi-agent topologies — is the later, coordination half of this volume. Here the decision stops at the single-harness choice.

Patterns

Start direct on the API. Sketch: implement the workflow with direct LLM API calls before reaching for any framework. When to use: always, as the opening move — most patterns are a few lines of code. Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original Mechanics: write the loop yourself; add a tool call, a retry, a parse — measure whether a real need for abstraction appears. Remember: the default answer to “do I need a framework?” is no; the burden of proof is on the abstraction.

Weigh abstraction cost against convenience. Sketch: before adopting a framework, price the visibility you lose. When to use: any time a framework’s speed is tempting. Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original Mechanics: ask how many layers stand between you and the actual prompt/response when debugging; prefer a framework that keeps prompts visible. LangGraph overview · LangChainT2-release-notes original Remember: convenience is bought with abstraction, and abstraction is paid in debuggability.

Price the build as maintenance, not a one-time cost. Sketch: treat a custom harness as a standing liability. When to use: whenever “just build it ourselves” is on the table. Scaling Managed Agents: Decoupling the brain from the hands · Anthropic (Lance Martin, Gabe Cemaj, Michael Cohen) (2026)T1-official original Mechanics: estimate re-tuning cost per model release, not just the up-front build; that recurring cost is the real comparison. Remember: harnesses encode assumptions that go stale as models improve.

Take the configure/wrap/extend middle path. Sketch: adopt a configurable, production-proven harness and extend it from primitives. When to use: when a concrete need has earned abstraction but a from-scratch build is overkill. Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original Mechanics: take a harness like the Claude Agent SDK; compose subagents and hooks; own only the thin extension your workflow needs. Agent SDK overview · AnthropicT1-official original Remember: you get control without the full maintenance burden, and adoption without going opaque.

Read the landscape per vendor, not as a ranking. Sketch: evaluate each framework against its own docs and your workflow. When to use: the moment you decide an existing harness is warranted. Introduction (What is CrewAI?) · CrewAI (documentation)T2-release-notes original Mechanics: match documented capability sets to your workflow’s needs; treat “leading” and “few abstractions” as self-descriptions. OpenAI Agents SDK · OpenAI (Agents SDK documentation)T2-release-notes original Remember: there is no independent cross-vendor benchmark in the vendors’ own marketing copy.

Quick reference

• Default: start direct on the API — most patterns are a few lines of code; the most successful implementations weren’t using complex frameworks. Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original
• The framework cost: convenience is bought with abstraction that obscures prompts and responses, making them harder to debug. Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original
• The build cost: a custom harness is a standing maintenance liability — its assumptions go stale as models improve. Scaling Managed Agents: Decoupling the brain from the hands · Anthropic (Lance Martin, Gabe Cemaj, Michael Cohen) (2026)T1-official original
• Landscape (per each vendor’s own docs, not a ranking): LangGraph = low-level orchestration framework + runtime; LangGraph overview · LangChainT2-release-notes original CrewAI = “leading” open-source role-based orchestration (self-described); Introduction (What is CrewAI?) · CrewAI (documentation)T2-release-notes original Claude Agent SDK = the tools/agent loop/context management that power Claude Code; Agent SDK overview · AnthropicT1-official original OpenAI Agents SDK = “very few abstractions” (self-described). OpenAI Agents SDK · OpenAI (Agents SDK documentation)T2-release-notes original
• Middle path: configure / wrap / extend a configurable harness — e.g. the Claude Agent SDK, built from primitives. Building agents with the Claude Agent SDK · Thariq Shihipar et al. (2025)T1-official original
• The rule: sequenced — start without a framework → adopt a configurable one when a need earns it → build from scratch only when nothing fits.
• Honesty: vendor self-descriptions are not a cross-vendor verdict; the framework lines carry a 90-day recheck.

Practice

This is the governing default of the volume’s capability axis. The spine framed every tool as a context cost; this chapter turns that into a discipline. The move is subtraction: start from the smallest tool set that covers the workflow and justify every addition, because each tool you add is paid twice — in definition tokens at rest and in selection errors at runtime. The principle is Anthropic’s; the unusually strong corroboration is three production teams who cut their tool sets and reported back.

Subtract-first: the smallest set that covers the workflow

Start from the counter-intuitive claim and let it organize the rest. Anthropic’s tool-design guidance states it flatly: “More tools don’t always lead to better outcomes.” [Official] Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original The failure mode is specific — “too many tools or overlapping tools can also distract agents from pursuing efficient strategies.” [Official] Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original The corrective is to build a few thoughtful tools that cover the workflow rather than wrap every API endpoint you happen to have. [Official] Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original

The reason this is a discipline and not a preference is that an extra tool charges you twice.

This is the same logic the volume’s spine drew as the capability axis, now stated as an action. A “complete” tool set — one tool per endpoint, every capability the platform offers — optimizes for coverage of possibilities. A minimal set optimizes for coverage of the workflow, which is the only thing the agent actually has to do. The two come apart fast: most of a complete set’s tools never fire on a given task, but every one of them is in the window distracting selection.

The case studies converge — and how far that licenses you

Subtract-first would be a plausible-but-unproven heuristic if it rested only on the design guidance. It does not. Three first-party engineering reports from 2025, on three different production agents, independently cut their tool sets and reported the same direction.

That is genuine convergence of practice — and it is worth being precise about what kind. These are vendor self-reports, each team measuring its own agent on its own tasks, not independent third-party benchmarks. The figures are real (each is quoted from the primary write-up), but the convergence is in direction, not in a transferable effect size.

The honest reading is the strongest one here: three independent practitioners pointing the same way is better evidence than any single benchmark, and none of these numbers is a law you can quote for your own agent. Subtract-first is well-corroborated as a direction; the size of the win is yours to measure.

Consolidate, and make the response high-signal

Once count is under control, two heuristics carry most of the remaining leverage — and both are really the same context-management instinct applied to tools.

Consolidate overlapping functionality into fewer capable tools, and namespace them so the model can tell them apart. [Official] Define tools · AnthropicT1-official original Two tools that do almost the same thing do not add a capability; they add a coin-flip the model has to win on every relevant turn. Folding them into one tool with a clear name removes the ambiguity at its source.

Return high-signal information, not raw dumps. A tool’s response is as much a context-management decision as its existence: returning a 5,000-token raw payload when the agent needs three fields spends the window you just saved by cutting tool count. [Official] Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original

When you can’t subtract, defer

Some agents genuinely need a large capability surface — a platform with hundreds of legitimate operations. Subtract-first has a dynamic complement for exactly this case: keep the active set small by loading tools on demand rather than presenting all of them upfront. The Tool Search Tool does this — tools are discovered and loaded when relevant, with only the few most-used kept non-deferred in the window. [Official] Tool search tool · AnthropicT1-official original A working default is to keep roughly the 3–5 most-used tools resident and defer the rest. [Official] Tool search tool · AnthropicT1-official original

The order matters: subtract first, then defer what genuinely cannot be cut. On-demand loading is not a license to keep a bloated set and hide it behind search — a hundred half-redundant tools still produce wrong-tool selection once they are loaded. Cut to the workflow, consolidate the overlaps, and only then defer the irreducible remainder.

Measure, don’t guess

Subtract-first becomes empirical, not aesthetic, when you close the loop: build a small agentic eval over realistic tasks, read the tool-calling metrics for redundant or never-used tools, and prune by evidence. That evaluate-then-prune loop is what turns “fewer tools” from a slogan into a measured discipline — and it belongs to the volume’s evaluation material, developed in the Operations volume rather than here. This chapter establishes the principle and its heuristics; the measurement loop that decides which tools to cut is the eval discipline’s job.

Patterns

Subtract to the workflow. Sketch: start from the smallest tool set that covers the actual workflow, justify every addition. When to use: always — it is the default. Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original Mechanics: list the workflow’s real operations; expose those, not every endpoint. Remember: a tool is paid twice — definition tokens at rest, selection errors at runtime.

Consolidate overlaps. Sketch: fold near-duplicate tools into one capable, namespaced tool. When to use: whenever two tools could plausibly answer the same call. Define tools · AnthropicT1-official original Mechanics: merge list_*/search_*-style pairs; give the survivor a clear name. Remember: overlap is a runtime coin-flip, not an added capability.

High-signal responses. Sketch: return scoped, relevant fields — not raw dumps. When to use: any tool whose natural output is large. Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original Mechanics: project to the fields the agent needs; paginate or summarize the rest. Remember: the response is a context-management decision as much as the tool’s existence.

Defer the irreducible remainder. Sketch: when many tools are genuinely required, load on demand and keep ~3–5 resident. When to use: large, legitimate capability surfaces you cannot cut. Tool search tool · AnthropicT1-official original Mechanics: Tool Search Tool; mark the most-used non-deferred. Remember: defer after subtracting — search does not fix a bloated set, it only hides it.

Quick reference

• Default: the smallest tool set that covers the workflow beats a “complete” one. Writing effective tools for agents — with agents · Aizawa (Anthropic) (2025)T1-official original
• Why: every tool is paid twice — definition tokens at rest + selection errors at runtime.
• Evidence: Vercel (→1 tool, 80→100%), GitHub Copilot (40→13, +2–5 pts), Block (30+ APIs → 3 tools, consolidation count) — three independent vendor self-reports converging on subtract-first; direction, not a transferable number.
• Heuristics: consolidate overlapping tools (+ namespace); return high-signal responses, not raw dumps.
• Scale escape hatch: load tools on demand (keep ~3–5 resident) — but only after subtracting.
• Honesty: unanchored aggregate token/eval figures are deliberately omitted; measure your own win.

Practice

The previous chapter set the discipline for the tools you write yourself; this one is about the tools you reach for across a wire. MCP — the Model Context Protocol — is how an agent connects to external data and tools through a standard interface instead of a bespoke integration each time. The thesis: wire external capability against a least-privilege, capability-negotiated protocol, and treat its security properties as obligations you design to — because the spec is explicit that it “cannot enforce these security principles at the protocol level.” And because MCP is mid-transition, design against a known moving target: build to the stable core, isolate what the release candidate changes.

What MCP is, and where its guarantees stop

MCP is an open protocol whose stated job is the integration problem this volume keeps circling: it “is an open protocol that enables seamless integration between LLM applications and external data sources and tools.” [Official] Specification — Model Context Protocol · Model Context Protocol contributors (2025)T1-official original Structurally it is a JSON-RPC client–host–server model: MCP “follows a client-host-server architecture where each host can run multiple client instances,” [Official] Architecture — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original with each client bound one-to-one to a server. The host runs the model and holds the conversation; each client speaks to exactly one server.

The protocol is capability-negotiated: clients and servers declare which features they support at initialization, and “Both parties must respect declared capabilities throughout the session.” [Official] Architecture — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original Nothing is assumed to be present; everything in play is negotiated up front and honored for the session’s duration. And the architecture carries a least-privilege isolation principle — servers “should not be able to read the whole conversation, nor ‘see into’ other servers.” [Official] Architecture — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original The full conversation stays with the host; a server sees only what is routed to it.

Here is the load-bearing honesty, and it shapes the whole chapter. The spec states plainly that “While MCP itself cannot enforce these security principles at the protocol level,” [Official] Specification — Model Context Protocol · Model Context Protocol contributors (2025)T1-official original the responsibility shifts to implementers to build the consent and authorization flows. Capability negotiation, server isolation, and the auth posture in this chapter are design-time obligations, not runtime guarantees.

Three primitives, three control modes

A server exposes capability through exactly three primitives, and the design payload is that each encodes a different answer to who is in control.

Tools are model-controlled. The model itself decides when to call them: the language model can “discover and invoke tools automatically based on its contextual understanding and the user’s prompts.” [Official] Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original This is the primitive that puts the agent in the driver’s seat — and so it is the one tool-minimization’s whole discipline applies to.

Resources are application-driven. They are URI-addressable read context whose inclusion the host decides, “with host applications determining how to incorporate context based on their needs.” [Official] Resources — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original The model does not reach for a resource; the application places it. Resources can be parameterized — “Resource templates allow servers to expose parameterized resources using” [Official] Resources — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original URI templates — so a single resource definition covers a family of addresses.

Prompts are user-controlled. They are templates surfaced “with the intention of the user being able to explicitly select them for use.” [Official] Prompts — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original The user picks them deliberately (a slash command, say) — neither the model nor the application invokes them autonomously.

The tool primitive also fixes two interface details worth carrying into your own server design. The error model is deliberately split: a tool-execution error is reported inside the result with isError true, and such errors “contain actionable feedback that language models can use to self-correct and retry with adjusted parameters,” [Official] Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original whereas a malformed or unknown-tool request is a JSON-RPC protocol error the model is far less likely to recover from. Return business-logic failures as isError results, not protocol errors, so the model can read the feedback and retry. And tool annotations (readOnly, destructive, and the like) are advisory only: clients must “consider tool annotations to be untrusted unless they come from trusted servers.” [Official] Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original An annotation is a hint, not a permission — which is the design-time-obligation theme again, applied to a single field.

The authorization posture: OAuth 2.1, by design

MCP standardizes its authorization on OAuth 2.1 — it “implements a selected subset of their features to ensure security and interoperability while maintaining simplicity:” [Official] Authorization — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original drawing on the established OAuth specification family rather than inventing a new scheme. On that baseline the spec sets four verified design requirements a remote MCP server or host builds to. Three sit on the OAuth posture; the architectural isolation principle above is the fourth, and together they are what “least-privilege by design” means in MCP.

The three OAuth requirements:

• Resource indicators (RFC 8707). Clients MUST “implement Resource Indicators for OAuth 2.0 as defined in” [Official] Authorization — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original RFC 8707, binding a token to the canonical URI of the resource it is meant for. A token minted for server A cannot be replayed against server B, because it carries its intended audience.
• No token passthrough. A server making upstream requests MUST NOT “pass through the token it received from the MCP client.” [Official] Authorization — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original When it needs upstream access it acts as a separate OAuth client with its own token — the client’s token never travels further than the server it was issued for.
• Mandatory PKCE. Clients MUST implement PKCE, which “helps prevent authorization code interception and injection attacks by requiring clients to create a secret verifier-challenge pair” [Official] Authorization — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original (with the S256 method when capable), so only the original requestor can exchange an authorization code for a token.

There are four key principles in the spec’s overview — user consent and control, data privacy, tool safety, and sampling controls — and the same caveat governs all of them: the protocol asks implementers to honor them; it does not enforce them on the wire. [Official] Specification — Model Context Protocol · Model Context Protocol contributors (2025)T1-official original

MCP is mid-transition — and that is the design problem

The current authoritative revision is 2025-11-25, and it is genuinely current. But MCP is at a dated inflection point, and a responsible design accounts for it rather than pretending the spec is static.

Today the protocol is stateful. The lifecycle opens with an initialize handshake that MUST “be the first interaction between client and server,” [Official] Lifecycle — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original inside which client and server negotiate a protocol version. The transport layer defines two standards — stdio, which clients SHOULD “support stdio whenever possible,” [Official] Transports — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original and Streamable HTTP, where the server MAY “assign a session ID at initialization time” [Official] Transports — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original via an Mcp-Session-Id header the client then echoes on every request. That session ID is the protocol-level session.

The announced 2026-07-28 release candidate prunes much of this toward a stateless core — applying the volume’s subtract-first instinct to the protocol itself. The following are announced for 2026-07-28, not current; recheck each after that date:

• The initialize/initialized handshake is removed (SEP-2575). [Official] The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original
• The Mcp-Session-Id header and the protocol-level session are removed (SEP-2567). [Official] The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original
• A formal feature-lifecycle policy deprecates Roots, Sampling, and Logging with “at least twelve months between deprecation and the earliest possible removal.” [Official] The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original
• Tasks becomes a server-directed extension and tasks/list “is removed because it can’t be scoped safely without sessions.” [Official] The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original (Tasks exists today as an in-core experimental feature, added in the current revision “to enable tracking durable requests with polling and deferred result retrieval.” [Official] Key Changes (Changelog) — MCP Specification 2025-11-25 · Model Context Protocol maintainers (2025)T1-official original )
• A new MCP Apps extension “lets servers ship interactive HTML interfaces that hosts render in a sandboxed iframe” (SEP-1865). [Official] The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original
• An Extensions framework where “extensions are identified by reverse-DNS IDs, negotiated through an extensions map on client and server capabilities, live in their own ext-* repositories with delegated maintainers, and version independently of the specification” (SEP-2133). [Official] The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original

Governance moved out of Anthropic — which is why dual-layer reading is the honest default

The reason “current plus announced-coming” is the right way to hold MCP, rather than a quirk, is that the protocol no longer has a single vendor steering it. In December 2025, “Anthropic is donating the Model Context Protocol to the Linux Foundation,” [Official] Donating the Model Context Protocol and establishing the Agentic AI Foundation · Anthropic (2025)T1-official original establishing the Agentic AI Foundation. The donation came with a continuity assurance: the governance model “will remain unchanged: the project’s maintainers will continue to prioritize community input and transparent decision-making.” [Official] Donating the Model Context Protocol and establishing the Agentic AI Foundation · Anthropic (2025)T1-official original

Development now runs through an open process. The current revision moved to “Formalize Working Groups and Interest Groups in MCP governance” (SEP-1302), [Official] Key Changes (Changelog) — MCP Specification 2025-11-25 · Model Context Protocol maintainers (2025)T1-official original and the 2026 roadmap confirms that “Working and Interest Groups are now the primary vehicle for protocol development.” [Official] The 2026 MCP Roadmap · David Soria Parra (Lead Maintainer) (2026)T1-official original The maintainers are candid about what that means for predictability: “A release-oriented roadmap implies a level of predictability that open-standards work rarely has.” [Official] The 2026 MCP Roadmap · David Soria Parra (Lead Maintainer) (2026)T1-official original

Designing against a moving target

Put the two halves together — a stable conceptual core, a churning transport-and-feature surface — and the design rule writes itself: build to the stable core, isolate what the RC changes behind adapters.

The durable parts are the conceptual ones: the host/client/server architecture Architecture — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original and the three-primitive control model Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original are not what the RC touches. Design your integration’s shape against those and it survives the transition. The parts in motion are the mechanical ones — the transport and lifecycle (the handshake, the session ID) Transports — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original Lifecycle — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original heading toward a stateless core, and Tasks Key Changes (Changelog) — MCP Specification 2025-11-25 · Model Context Protocol maintainers (2025)T1-official original heading out of core into an extension. Wrap exactly those behind a thin adapter so the migration, when it lands, is contained to one seam instead of smeared across the codebase.

Patterns

Pick the primitive by control authority. Sketch: map each capability to tool / resource / prompt by who should trigger it. When to use: designing any server’s surface. Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original Mechanics: model-initiated → tool; app-placed read context → resource (template it); user-selected → prompt. Remember: a model-controlled tool hands the model initiative — if the user should decide, that is the wrong primitive.

Design to least-privilege auth. Sketch: OAuth 2.1 with audience-bound tokens, no passthrough, mandatory PKCE. When to use: any remote MCP server. Authorization — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original Mechanics: RFC 8707 resource indicators bind the token; the server uses its own upstream token; PKCE (S256) on every client. Remember: it is the posture you implement, not the threat model — and the protocol does not enforce it for you.

Return self-correctable errors. Sketch: report business-logic failures inside the result, not as protocol errors. When to use: any tool that can fail on bad input. Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original Mechanics: set isError true and include actionable feedback; reserve JSON-RPC errors for malformed/unknown requests. Remember: an isError result is something the model can read and retry; a protocol error usually is not.

Isolate by design, host-side. Sketch: keep the full conversation in the host; route only the relevant slice to each server. When to use: always — especially with multiple servers. Architecture — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original Mechanics: one client per server, capabilities negotiated and respected; no cross-server visibility. Remember: the spec “cannot enforce these security principles at the protocol level” — isolation is your obligation.

Build to the core, wrap the churn. Sketch: design the shape against the stable architecture/primitives; adapter-wrap transport, lifecycle, and Tasks. When to use: any integration meant to outlive the 2026-07-28 RC. The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original Mechanics: one seam for the stateful-vs-stateless transition; recheck the RC mechanisms after 2026-07-28. Remember: a diffuse stateful assumption is a migration; an isolated one is a one-file change.

Quick reference

• What MCP is: an open, JSON-RPC, capability-negotiated client–host–server protocol for connecting agents to external data and tools. Specification — Model Context Protocol · Model Context Protocol contributors (2025)T1-official original Architecture — Model Context Protocol Specification 2025-11-25 · Model Context Protocol contributors (2025)T1-official original
• The honesty: the spec “cannot enforce these security principles at the protocol level” — isolation, negotiation, and auth are design-time obligations, not runtime guarantees. Specification — Model Context Protocol · Model Context Protocol contributors (2025)T1-official original
• Three primitives = three control modes: tools (model-controlled), resources (app-driven), prompts (user-controlled) — choose by who holds the trigger. Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original Resources — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original Prompts — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original
• Tool interface: isError results carry self-correctable feedback (distinct from protocol errors); annotations are untrusted unless the server is. Tools — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original
• Auth posture (four principles): OAuth 2.1 + RFC 8707 resource indicators + no token passthrough + mandatory PKCE — the posture, not the threat model. Authorization — Model Context Protocol Specification (revision 2025-11-25) · Model Context Protocol contributors (2025)T1-official original
• Mid-transition: today stateful (initialize handshake, Mcp-Session-Id); the 2026-07-28 RC announces a stateless core, deprecation policy, Tasks-as-extension, MCP Apps, and an Extensions framework — announced, recheck after 2026-07-28. The 2026-07-28 MCP Specification Release Candidate · David Soria Parra and Den Delimarsky (Lead Maintainers)T1-official original
• Governance: donated to the Linux Foundation (Agentic AI Foundation, Dec 2025); developed through Working Groups — trackable, not vendor-scheduled. Donating the Model Context Protocol and establishing the Agentic AI Foundation · Anthropic (2025)T1-official original The 2026 MCP Roadmap · David Soria Parra (Lead Maintainer) (2026)T1-official original
• Design rule: build to the stable core; isolate what the RC changes behind an adapter.

Practice

The spine framed every tool as a slice of the context budget. This chapter turns to the other thing you put in the window: the prompt itself — the text that shapes what the agent reasons over. Anthropic documents the craft as five moves, and it documents them in an order that is itself a teaching device: clarity first, then examples, then reasoning, then structure, then chaining. This is single-vendor, authoritative-by-construction guidance — Anthropic’s own prompt-engineering docs — so the honest tier is official, not convergence. Two of the five moves have shifted under newer models, and the chapter renders them as the current state, not the technique they once were.

The order is the lesson: five moves on one surface

Anthropic’s prompt-engineering hub lists the techniques as one ordered set — they run “from clarity and examples to XML structuring, role prompting, thinking, and prompt chaining.” [Official] Prompt engineering overview · AnthropicT1-official original That ordering is not a table of contents; it is a gradient of effort. You reach for the cheap, high-leverage move first (say what you want clearly), and you escalate to the expensive, structural moves (chain several prompts) only when the cheaper ones do not carry the task.

This matters for an agent system specifically. The prompt is context, and context is the budget the whole volume is about. A prompt that achieves its effect with clarity and three examples spends far less of the window than one that leans on elaborate structure and a multi-step chain — and it leaves more room for the tools, the conversation history, and the work itself.

Clarity is the foundation — brief the brilliant new employee

The single highest-leverage idea in the craft is to be explicit, because the model does not share your context. Anthropic’s mental model is the one to lead with: “Think of Claude as a brilliant but new employee who lacks context on your norms and workflows.” [Official] Prompting best practices · AnthropicT1-official original The metaphor does real work — almost every other clarity technique is a corollary of “brief the new hire properly.”

Two such corollaries are documented directly. Sequence the instruction when order matters: “Provide instructions as sequential steps using numbered lists or bullet points when the order or completeness of steps matters.” [Official] Prompting best practices · AnthropicT1-official original And supply the why, not just the what — “providing context or motivation behind your instructions, such as explaining to Claude why such behavior is important” [Official] Prompting best practices · AnthropicT1-official original lets the model generalize the instruction to cases you did not enumerate.

Examples are the most reliable lever — and they come with a dosage

Among the five moves, examples carry the strongest reliability claim in the source. Anthropic states that examples are “one of the most reliable ways to steer Claude’s output format, tone, and structure.” [Official] Prompting best practices · AnthropicT1-official original For an agent, that is the cheapest way to pin down a shape you care about — a response format, a tone, a decision boundary — without writing a paragraph of rules the model then has to interpret.

Unusually for prompting guidance, this move comes with a concrete dosage and a selection rule. The dosage is the one verbatim number anchored anywhere in the underlying research: “Include 3–5 examples for best results.” [Official] Prompting best practices · AnthropicT1-official original The selection rule is relevance — make examples that “mirror your actual use case closely” [Official] Prompting best practices · AnthropicT1-official original (the same guidance adds diverse, covering edge cases, and structured, wrapped in tags). Anthropic’s own interactive tutorial independently treats examples as a named foundational technique, dedicating its “Using Examples” chapter to it — corroboration that this is core craft, though as a teaching artifact rather than the normative guidance. [Official] Anthropic's Prompt Engineering Interactive Tutorial · AnthropicT2-release-notes original

What changed: reasoning is now elicited by the model, not the prompt

The third move — eliciting step-by-step reasoning — is the first of two that have shifted under newer models, and the shift is a role-reversal. Manual chain-of-thought (telling the model to “think step by step”) used to be the default reasoning lever. It is now documented as a fallback: “When thinking is off, you can still encourage step-by-step reasoning by asking Claude to think through the problem.” [Official] Prompting best practices · AnthropicT1-official original The conditional — when thinking is off — is the whole point. Adaptive thinking now handles most multi-step reasoning internally as a model feature, so the prompting technique survives mainly for the case where that capability is unavailable.

The practical instruction for an agent builder: do not reach reflexively for “think step by step” in the system prompt. If thinking is available, it is doing that work already, and the manual instruction is redundant context. Reserve the prompting technique for the case it is now documented for.

Structure and roles — durable craft, with one deprecation inside it

The fourth move is the most stable part of the craft — except for one technique that has been retired outright.

Two of the three structuring techniques are documented-once, durable craft. XML tags “help Claude parse complex prompts unambiguously,” [Official] Prompting best practices: use XML tags · AnthropicT1-official original which matters most when a prompt mixes instructions, context, examples, and variable inputs — wrap each content type in its own tag so the model never has to guess where one ends and the next begins. And a role assignment in the system prompt is a one-line steering tool: “setting a role in the system prompt focuses Claude’s behavior and tone for your use case,” [Official] Prompting best practices · AnthropicT1-official original where even a single sentence makes a difference.

The third technique — prefilling the last assistant turn to steer format or skip a preamble — has been deprecated, not refined. On Claude 4.6+ models, “prefilled responses on the last assistant turn are no longer supported,” [Official] Prompting best practices · AnthropicT1-official original and a request that includes a prefilled assistant message now returns a 400 error. This is a former best-practice that became an error, and it must be rendered as the deprecation it is. The documented migration is to structured outputs for format control and to direct system-prompt instructions for skipping preambles.

Chaining is the escape hatch — and it is not orchestration

The fifth and most expensive move is to stop trying to do the job in one prompt and decompose it. Prompt chaining “decomposes a task into a sequence of steps, where each LLM call processes the output of the previous one,” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original and the workflow “is ideal for situations where the task can be easily and cleanly decomposed into fixed subtasks.” [Official] Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original Explicit chaining stays worthwhile “when you need to inspect intermediate outputs or enforce a specific pipeline structure,” [Official] Prompting best practices · AnthropicT1-official original and its canonical shape is self-correction — generate a draft, have the model review it against criteria, have it refine based on the review. [Official] Prompting best practices · AnthropicT1-official original

Here is the boundary the rest of the volume depends on. Chaining is single-thread prompt decomposition: one conversation, a fixed sequence of calls, each feeding the next. It is not multi-agent orchestration — there is no second isolated window, no delegation, no runtime-chosen control flow. Reaching for sub-agents when a sequential pipeline would do is exactly the additive reflex the spine warned against, applied to coordination.

Where this connects

Two threads run out of this chapter. The first is the prefill deprecation: its migration target is structured outputs, the subject of the next chapter, which takes up forcing reliable machine-readable output where prefill used to. The second is the chaining boundary: the moment a task stops being a fixed sequence on one thread and becomes independent or quarantined work across windows, you have crossed from the prompting craft into coordination — the later, orchestration half of this volume, where the sub-agent and multi-agent patterns live. This chapter shapes the input to a single agent thread; those are the two places its edges hand off.

Patterns

Brief the new hire. Sketch: state the goal explicitly, give steps in order when order matters, and explain the motivation. When to use: first — always, before any heavier move. Prompting best practices · AnthropicT1-official original Mechanics: numbered/bulleted steps for ordered work; one sentence of why behind each non-obvious instruction. Remember: under-specification gets filled with a plausible default, rarely the one you wanted.

Show, don’t describe. Sketch: demonstrate the output shape with 3–5 examples instead of a prose rulebook. When to use: whenever you care about a specific format, tone, or decision boundary. Prompting best practices · AnthropicT1-official original Mechanics: mirror the real use case closely; cover edge cases; wrap each example in a tag. Remember: examples are the most reliable steering lever, and 3–5 is the documented dosage.

Structure the messy prompt. Sketch: tag distinct content types and assign a role. When to use: when a prompt mixes instructions, context, examples, and variable input. Prompting best practices: use XML tags · AnthropicT1-official original Mechanics: <instructions>/<context>/<input> tags; a one-line role in the system prompt. Prompting best practices · AnthropicT1-official original Remember: tags remove parsing ambiguity; a role focuses behavior and tone — durable craft, unlike prefill.

Chain only fixed sequences. Sketch: decompose a too-big task into a predefined sequence of calls, each feeding the next. When to use: the task cleanly decomposes into fixed subtasks, or you must inspect intermediate output. Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original Mechanics: the self-correction shape — generate, review against criteria, refine — as separate calls. Prompting best practices · AnthropicT1-official original Remember: this is single-thread; if the work is independent or needs isolation, that is orchestration, not chaining.

Quick reference

• The order is the ladder: clarity → examples → reasoning → structure/roles → chaining; climb only as far as the task forces you. Prompt engineering overview · AnthropicT1-official original
• Lead with clarity: the brilliant-but-new-employee model — be explicit, sequence when order matters, give the why. Prompting best practices · AnthropicT1-official original
• Examples are the most reliable lever: mirror the use case; documented dosage is 3–5 (the one anchored number). Prompting best practices · AnthropicT1-official original
• Changed — CoT: manual “think step by step” is now a fallback for when thinking is off; adaptive thinking does it by default (volatile; recheck per model release). Prompting best practices · AnthropicT1-official original
• Changed — prefill: prefilling the last assistant turn is deprecated on 4.6+ (returns a 400); migrate format control to structured outputs (volatile; recheck per model release). Prompting best practices · AnthropicT1-official original
• Durable structure: XML tags remove parsing ambiguity; Prompting best practices: use XML tags · AnthropicT1-official original a role in the system prompt focuses behavior. Prompting best practices · AnthropicT1-official original
• Boundary: chaining is single-thread decomposition, not orchestration. Building effective agents · Erik Schluntz and Barry Zhang (2024)T1-official original
• Tier honesty: this is single-vendor official guidance (Anthropic’s own docs + one corroborating tutorial), authoritative by construction — not triangulated across independent practitioners, so no convergence claim.

Practice

The previous chapter shaped what goes into the model — the prompting craft. This one shapes what comes out: how you force output a program can parse instead of prose a human must read. It picks up a loose end from there — prefilling the assistant turn, a classic JSON-extraction trick, is being deprecated on the newest models, and the question “what do I reach for instead?” is exactly this chapter’s subject. The answer is four levers, arranged on one surface from the strongest guarantee to the lightest touch. The mechanics are Anthropic’s own API documentation — authoritative by construction, but a moving target: structured outputs is mid-GA-transition and the prefill gate grows with each model release, so this is a chapter to re-check per release, not to memorize.

One problem, four levers

Forcing reliable machine-readable output looks like several unrelated tricks — tool calls, a strict flag, retry loops, prefilling a brace — but they are one problem with four levers, and the levers form a single continuous surface from strongest guarantee to lightest weight.

• Tool use turns a tool definition into an output mechanism: a tool’s input_schema is “[a JSON Schema] object defining the expected parameters for the tool,” [Official] Define tools · AnthropicT1-official original so you define one tool whose schema is the shape you want and parse the call it returns. [Official] Tool use with Claude · AnthropicT1-official original
• Structured outputs / strict: true add a grammar-backed guarantee on top — schema-compliant output by construction. [Official] Structured outputs · AnthropicT1-official original
• The validation + retry loop is the recover path for when the guarantee is unavailable or insufficient — define a schema, “and the SDK validates the output against it, re-prompting on mismatch.” [Official] Get structured output from agents · AnthropicT1-official original
• The prompt-craft recipes — specify the format, prefill, stop sequences — are the lightest-weight, guarantee-free option. [Official] Increase output consistency · AnthropicT1-official original

This is a capability-axis decision in the spine’s sense: the output shape is part of what the agent’s tool surface costs and promises. The rest of the chapter walks the levers in order, and the discipline that orders them — prevent beats recover — falls out at the end.

Tool use: tool_choice forces the call, strict guarantees the args

The first lever is the one most teams already have wired, because they use tool calls for everything else. Using a tool to shape output has two separable moves, and conflating them is the most common framing error.

The first move forces the model to emit a call. The tool_choice option {"type":"tool","name":"..."} “forces Claude to always use a particular tool.” [Official] Define tools · AnthropicT1-official original Give the model a single tool whose input_schema is your target shape, force that tool, and you are guaranteed it calls it.

The second move is not implied by the first. Forcing the call does not make the call’s arguments schema-valid — the model can still emit the wrong types or drop a required field. That guarantee is a separate addition: setting strict: true on the tool “guarantees Claude’s tool inputs match your JSON Schema by constraining the model’s token sampling to schema-valid outputs.” [Official] Strict tool use · AnthropicT1-official original

This chapter treats tool use as an output mechanism only. Which tools to expose, how few, and how to design their surface is the subject of the tool-minimization and MCP chapters earlier in this volume — a different question from “how do I get a known shape back.”

The structured-outputs guarantee — and its limits

The second lever is the strongest, and the one most often overstated. Structured outputs “guarantee schema-compliant responses through constrained decoding,” [Official] Structured outputs · AnthropicT1-official original and the guarantee is mechanistically grounded rather than a strong-prompt effect: structured outputs “use constrained sampling with compiled grammar artifacts” [Official] Structured outputs · AnthropicT1-official original — the schema is compiled into a grammar that constrains which tokens the model may sample. That compiled-grammar mechanism is why the guarantee holds and what distinguishes it from prompt-only JSON, which carries no such constraint.

But the guarantee is conditioned, and the conditions are load-bearing — you must render them every time.

This is the bridge to the first lever: tool_choice forces a call, and strict runs this same constrained-decoding pipeline over the call’s arguments. Schema-shaped return value (structured outputs) and schema-valid tool arguments (strict tool use) are the same guarantee applied to two surfaces.

Prevent beats recover

The third lever closes the loop when the output is still malformed — but its place in the ordering is the real lesson. There are two ways to deal with bad output, and they are not equals.

The recover path responds after the fact. On the tool-use API, when a client tool returns a tool_result with is_error: true, “Claude will then incorporate this error into its response,” [Official] Handle tool calls · AnthropicT1-official original and for an invalid or missing-parameter call, “Claude will retry 2-3 times with corrections before apologizing to the user.” [Official] Handle tool calls · AnthropicT1-official original On the Agent SDK, the same instinct is wired as a loop: you define a JSON Schema “and the SDK validates the output against it, re-prompting on mismatch,” [Official] Get structured output from agents · AnthropicT1-official original erroring out — surfaced as error_max_structured_output_retries — if validation does not succeed within the retry limit.

The prevent path is the second lever: strict / structured outputs eliminate the invalid call by construction, so there is nothing to recover from. The handle-tool-calls docs themselves point at strict as the way to “eliminate invalid calls” rather than retry them. [Official] Handle tool calls · AnthropicT1-official original

Recovery is not free and it is not certain. The SDK names three documented ways generation still fails: “This typically happens when the schema is too complex for the task, the task itself is ambiguous, or the agent hits its retry limit trying to fix validation errors.” [Official] Get structured output from agents · AnthropicT1-official original Each is a reason to prefer prevention: a simpler schema, a less ambiguous task, and a guarantee that needs no retries at all.

The lightest lever: prompt-craft recipes

The fourth lever is the oldest and the weakest — prompt-craft recipes that ask for a shape without constraining the tokens. They carry no schema guarantee at all, which is precisely when you want them: for flexibility beyond a strict schema, or on a path where the guarantee is not available.

The base recipe is to be explicit: “Precisely define your desired output format using JSON, XML, or custom templates so that Claude understands every output formatting element you require.” [Official] Increase output consistency · AnthropicT1-official original Two narrower JSON tricks have long ridden on top: prefilling the assistant turn to “skip the preamble and go straight to the JSON,” [Official] Prompting Claude for JSON mode · AnthropicT1-official original and pairing it with a stop sequence — “You can get rid of text that comes after the JSON by using a stop sequence.” [Official] Prompting Claude for JSON mode · AnthropicT1-official original

Here is where the loose end from the prompting chapter gets tied off. Prefilling the assistant turn is being deprecated on the newest models — it is not supported on Claude Opus 4.7, Opus 4.6, Sonnet 4.6, or Mythos Preview; on those models the documented replacement is structured outputs or system-prompt instructions. [Official] Increase output consistency · AnthropicT1-official original So the classic prefill-{ recipe is now legacy on current models — reach for the guarantee (lever two) or a system-prompt instruction instead. The stop-sequence recipe is unaffected by the gate and remains useful for trimming trailing prose.

These recipes shape the likelihood of a good shape; they do not constrain the grammar. That is the whole reason the docs redirect to structured outputs the moment you need a guarantee — the recipes are for the cases where you deliberately don’t.

A note on evidence

Everything in this chapter is Anthropic’s own API documentation — T1, authoritative by construction. That is the right tier for a vendor-API reference, but it is mono-vendor: there is no independent benchmark of how often structured outputs fail on a complex schema, or of the real-world distribution of refusal-versus-cutoff. This chapter does not invent one. The one number it quotes — “2-3 times” — is the docs’ own documented retry range, not a measured rate. If you want a failure rate for your schemas, you measure it; the docs tell you the guarantee and its conditions, not your distribution.

Patterns

Schema-as-output tool. Sketch: define one tool whose input_schema is your target shape, force it, parse the call. When to use: you already speak tool use and want a known shape back. Define tools · AnthropicT1-official original Mechanics: set tool_choice to {"type":"tool","name":"..."} to force the call; add strict: true to constrain the arguments. Strict tool use · AnthropicT1-official original Remember: tool_choice forces the call; strict is what makes the arguments conform — they are two levers.

Grammar-constrained guarantee. Sketch: use structured outputs / strict for a hard schema guarantee. When to use: you need schema-compliant output by construction, within the supported subset. Structured outputs · AnthropicT1-official original Mechanics: the schema compiles to a grammar that constrains token sampling; same pipeline drives strict tool use. Remember: the guarantee holds except refusals and max_tokens cutoffs, over the supported schema subset — still check stop_reason and a parse failure.

Prevent, then recover. Sketch: prevent invalid output with the guarantee; keep a retry loop for what it can’t reach. When to use: always order it this way. Get structured output from agents · AnthropicT1-official original Mechanics: structured outputs / strict first; fall back to validate-and-re-prompt (the SDK loop, or is_error feedback) where the guarantee is unavailable or insufficient. Handle tool calls · AnthropicT1-official original Remember: recovery costs a round trip per failure and can exhaust retries (complex schema, ambiguous task, retry-limit hit) — prevention costs neither.

Prompt-craft for flexibility. Sketch: specify the format and (optionally) use a stop sequence when you need reach beyond a strict schema. When to use: output flexibility the guarantee can’t express, or a path without it. Increase output consistency · AnthropicT1-official original Mechanics: state the format precisely; stop-sequence to trim trailing prose; do not prefill on current models (Opus 4.7 / Opus 4.6 / Sonnet 4.6 / Mythos Preview) — use system-prompt instructions or structured outputs. Prompting Claude for JSON mode · AnthropicT1-official original Remember: these shape likelihood, not the token grammar — no guarantee.

Quick reference

• One surface, four levers: tool use → structured outputs / strict → validation/retry → prompt-craft — strongest guarantee to lightest weight. Structured outputs · AnthropicT1-official original
• Two levers, not one: tool_choice forces the call; strict guarantees the arguments. Strict tool use · AnthropicT1-official original
• The guarantee, stated honestly: schema-compliant output except refusals and max_tokens cutoffs, over the supported schema subset — never “always valid JSON.” Structured outputs · AnthropicT1-official original
• Prevent beats recover: use the guarantee first; the retry loop is the fallback, not the default. Handle tool calls · AnthropicT1-official original
• Prefill is deprecated on current models (Opus 4.7 / Opus 4.6 / Sonnet 4.6 / Mythos Preview) — use structured outputs or system-prompt instructions; the gate grows per release. Increase output consistency · AnthropicT1-official original
• Volatility: structured-outputs GA is mid-transition and the prefill gate moves — re-check the param name and unsupported-model list per release.
• Evidence: mono-vendor T1 docs; the only number (“2-3 times”) is the docs’ documented retry range, not a measured failure rate. Handle tool calls · AnthropicT1-official original

Practice

The spine’s second axis was coordination, and its reframing was sharp: a new unit of work is not a new skill, it is a fresh window. This chapter develops the primitive that embodies that — the sub-agent. Everything here follows from one claim the rest of the chapter unpacks: a sub-agent’s value is the separate context window, not any capability the model otherwise lacks. Get that backwards and you reach for a sub-agent to “make the model smarter”; get it right and you reach for one to quarantine context.

Isolation, not capability

Start from what a sub-agent is, because the common mental model — “a helper that can do something the main agent can’t” — is wrong and leads to misuse. Across Anthropic’s own descriptions the sub-agent is defined by its isolation, not by any new ability. It is, plainly, “an isolated Claude instance with its own context window.” [Official] How and when to use subagents in Claude Code · Anthropic (2026)T1-official original When a side task would otherwise flood the main conversation, “the subagent does that work in its own context and returns only the summary.” [Official] Create custom subagents · AnthropicT1-official original And from the caller’s side the isolation is total: “The subagent works in its own separate context window. None of its file reads touch yours.” [Official] Explore the context window · AnthropicT1-official original

So the value is the window, not the worker. A sub-agent runs the same model you already have; what it adds is a clean, separate place for that model to do focused work whose verbose middle never lands in your conversation.

The contract: fresh in, relevant result only out

Isolation is only composable if the boundary is well-defined in both directions, and it is. On the way in, a sub-agent inherits nothing: “Each subagent starts fresh, unburdened by the history of the conversation or invoked skills.” [Official] How and when to use subagents in Claude Code · Anthropic (2026)T1-official original The SDK is precise about how fresh: a sub-agent “runs in its own fresh conversation” [Official] Subagents in the SDK · AnthropicT1-official original and does not receive the parent’s conversation history, tool results, or system prompt — the only channel from parent to sub-agent is the prompt string you pass it. On the way out, the return is equally narrow: “only its final message returns to the parent” [Official] Subagents in the SDK · AnthropicT1-official original — every intermediate tool call and result stays inside the sub-agent.

There is one deliberate exception, and naming it sharpens the rule. Fork mode (fork_session) inverts the input side: it carries the parent’s context into the sub-agent, for cases where the side task genuinely needs the conversation so far. The return contract is unchanged — still only the final message comes back. The configuration mechanics of fork mode belong to the SDK reference, not here; what matters for design is that the default is fresh, and fork is the explicit opt-out when isolation-on-input would cost you more than it saves.

Isolation buys separation of concerns

Why is a separate window worth the trouble? Because it makes each unit of work independent and non-interfering. Anthropic’s multi-agent write-up names the payoff directly: a sub-agent “provides separation of concerns—distinct tools, prompts, and exploration trajectories—which reduces path dependency and enables thorough, independent investigations.” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original Sub-agents “facilitate compression by operating in parallel with their own context windows,” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original each compressing its slice of the work rather than sharing one crowded window.

The separate window is not just hygiene, then — it is the property that makes the next move (assigning roles) possible. Two investigations in one window contaminate each other’s reasoning; the same two in separate windows stay clean.

Roles: description + system prompt + scoped tools

If isolation gives you independent units, a role is how you specialize one. A role is not a new mechanism — it is three ordinary knobs set deliberately: a description, a system prompt, and a scoped tool set. The docs make the tool-scoping explicit (“limiting which tools a subagent can use” [Official] Create custom subagents · AnthropicT1-official original ) and the design principle blunt: “each subagent should excel at one specific task.” [Official] Create custom subagents · AnthropicT1-official original

The most productive role decomposition the sources demonstrate is generate-then-verify — focused generators plus a separate reviewer. Claude Code’s code review runs it concretely: “Each agent looks for a different class of issue,” [Official] Code Review · AnthropicT1-official original and then “a verification step checks candidates against actual code behavior to filter out false positives.” [Official] Code Review · AnthropicT1-official original The product announcement says the same in plainer words — the agents “look for bugs in parallel” [Official] Bringing Code Review to Claude Code · Anthropic (2026)T1-official original and then “verify bugs to filter out false positives.” [Official] Bringing Code Review to Claude Code · Anthropic (2026)T1-official original

When a sub-agent earns its keep

Isolation is not free, and the honest rule is a tradeoff, not a default-on. The benefit side: delegating verbose work (running tests, fetching docs, processing logs) keeps that output in the sub-agent so “only the relevant summary returns to your main conversation,” [Official] Create custom subagents · AnthropicT1-official original and the multi-agent architecture “distributes work across agents with separate context windows to add more capacity for parallel reasoning.” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original The cost side, stated just as plainly: “Subagents start fresh and may need time to gather context” [Official] Create custom subagents · AnthropicT1-official original — a latency hit — and the task’s value “must be high enough to pay for the increased performance.” [Official] How we built our multi-agent research system · Anthropic (2025)T1-official original

The quantified side of that cost — how many more tokens, how much more latency — is the Operations volume’s subject; this chapter asserts the tradeoff qualitatively and leaves the numbers to where they can be measured.

Patterns

Quarantine verbose work. Sketch: delegate high-volume, low-relevance work (tests, doc fetches, log scans) to a sub-agent; keep only the summary. When to use: any side task whose output would crowd the main window. Create custom subagents · AnthropicT1-official original Mechanics: pass a focused prompt; the sub-agent’s verbose middle stays in its window, only the final message returns. Remember: the win is the quarantine, not the work — the main agent could do it, just not without the noise.

Clean-room verify. Sketch: generate with one (or several) focused sub-agents, then review with a separate verifier. When to use: anything where self-evaluation would inherit the generator’s blind spots. Code Review · AnthropicT1-official original Mechanics: focused generators look for distinct issue classes; a verifier checks candidates against actual behavior to filter false positives. Remember: the verifier is separate on purpose — a fresh window has no stake in the path it reviews.

Scope the role, not just the prompt. Sketch: define a role by description + system prompt + a deliberately limited tool set. When to use: whenever a sub-agent should excel at one task and not wander. Create custom subagents · AnthropicT1-official original Mechanics: allowlist/denylist its tools; one task per sub-agent. Remember: the tool scope is part of the role — an unscoped sub-agent is an unfocused one.

Default fresh, fork on purpose. Sketch: let sub-agents start fresh; use fork_session only when the task genuinely needs the parent’s context. When to use: fork when re-gathering context would cost more than carrying it in. Subagents in the SDK · AnthropicT1-official original Mechanics: fresh is the default (one prompt string in); fork inverts the input side, return unchanged. Remember: fork trades isolation-on-input for context — reach for it deliberately, not by habit.