Chapters
Every chapter, grouped by Part. Use the card metadata to calibrate how much trust to place in a chapter's specific claims.
Part 1
-
Agentic Loops: stop_reason and Tool-Result Handling
The first chapter of Domain 1 and the substrate the rest of the book assumes — the agent loop as a control structure whose branch condition is stop_reason. Teaches the tool-use round-trip from first principles, the turn model, error and parallel tool-result handling, termination budgets, and every stop_reason value an architect must recognize.
claude-code -
Coordinator–Subagent Patterns: Hub-and-Spoke and Isolated Context
The coordinator–subagent (orchestrator-worker) pattern — a lead agent that decomposes a task and spawns isolated-context subagents. Teaches why a second agent ever helps, when the pattern earns its 3–10x token cost, the full single-vs-multi trade-off (including reliability and maintainability), why decomposition must split by context and not by role, and the one variant that works across domains.
claude-code -
Subagent Invocation: AgentDefinition, the Agent Tool, and allowedTools
The mechanics beneath the coordinator–subagent pattern — how a subagent is actually invoked. The Agent tool and its three creation paths, the AgentDefinition contract, why "Agent" must be in allowedTools, the single prompt-string channel into a fresh context, what crosses back out, and what a subagent does not inherit (including parent permissions).
claude-code -
Multi-Step Workflows: Programmatic vs Prompt-Based Handoff
A multi-step task's control flow is enforced either in your code (programmatic) or in the model (prompt-based). When to choose each, why every step boundary is a handoff that leaks fidelity, the Writer/Reviewer pattern as the handoff that works, how a written artifact makes a handoff survivable, and how a programmatic validation gate rejects-and-retries a bad step before it propagates.
claude-code -
Agent SDK Hooks: Intercepting, Gating, and Normalizing the Loop
A hook is a typed callback the SDK fires at a named lifecycle event — the architect's control plane to intercept, gate, and normalize the agent loop without touching the model. The events to know, the two interception modes (PreToolUse gates, PostToolUse normalizes), the four PreToolUse decisions including what defer does, and the deny-beats-defer-beats-ask-beats-allow precedence.
claude-code -
Task Decomposition: Sequential Pipelines vs Adaptive
Once you've decided to decompose, the structural choice is fixed-in-advance (a sequential pipeline — predictable, cheap, auditable) versus decided-at-runtime (adaptive — the orchestrator scales effort to the task). Why open-ended work can't be hardcoded, why predictable work shouldn't be adaptive, the quantified token cost of choosing adaptive, and the failure modes at both extremes.
claude-code -
Session State: resume, fork, and Scratchpads
A session is the persisted conversation, not the filesystem. The architect's tools for carrying or branching state across context windows — continue, resume, and fork, with their literal Python/TS spellings — plus the encoded-cwd resume trap and the discipline of capturing durable artifacts as application state rather than shipping transcripts.
claude-code
Part 2
-
Effective Tool Interfaces: Descriptions, Boundaries, and Naming
A tool's caller-facing contract — description, input examples, operation boundary, name, and response shape — is what a non-deterministic model reads to select and use it. Why the description is the highest-leverage surface, how input_examples show correct usage, when to consolidate, how to namespace, and the object schemas (input and output) every interface stands on.
claude-code -
Structured Error Responses: isError, Retryability, and the Protocol-Error Split
A tool's failure contract — which channel a failure travels down, what its text says, and whether the schema could have prevented it. The two regimes (Messages-API is_error vs MCP isError + JSON-RPC), why is_error turns a failure into a recoverable signal, the normative execution-vs-protocol error split, and the difference between steering a retry and preventing the error.
claude-code -
Tool Distribution and tool_choice: auto, any, Forced, and none
Controlling whether and which tool the model may call — the four tool_choice modes, the extended-thinking constraint, the any+strict guarantee of a schema-valid call, and the prompt-cache invalidation cost — plus allowedTools scoping versus bypassPermissions, with parallel execution as its own orthogonal axis.
claude-code -
MCP Server Configuration: .mcp.json, Scopes, and Env-Var Expansion
Wiring an MCP server so it resolves predictably across personal, team, and machine contexts. The two config paths and strictMcpConfig, claude mcp add --scope, the three scopes and their precedence, the local-scope-versus-local-settings trap, env-var expansion for secrets, verifying the connection via system:init, and the transports atop a mid-revision wire protocol.
claude-code -
Built-in Tools: The Roster, Execution Order, and Permission Gating
The fixed roster of built-in tools every agent ships with — Read, Write, Edit, Bash, Grep, Glob — their exact, case-sensitive names, the read-only-versus-state-modifying line that decides which run in parallel, the six permission modes, the five-step evaluation order, and the allow/deny rules that gate them. Closes on the allowlist-is-not-a-sandbox trap.
claude-code
Part 3
-
CLAUDE.md Hierarchy & @import: Four Scopes That Concatenate
How Claude Code assembles persistent instructions from four CLAUDE.md scopes that concatenate without precedence — the opposite of the strict five-level settings hierarchy (Managed > CLI > Local > Project > User) — plus the @import mechanism (depth-5, first-use approval), the AGENTS.md bridge, and the managed claudeMd / claudeMdExcludes controls.
claude-code -
Slash Commands & Skills: Stored Prompts, Lazy-Loaded Capabilities
Two ways to extend the workflow — a slash command (a stored prompt recognized at message start) and a skill (a lazy-loaded, auto-invocable, directory-bundled capability). The merged model, the full lazy-load lifecycle (description budget, $ARGUMENTS substitution, compaction carry-forward, live change detection), the SKILL.md frontmatter, the four scopes, and what disable-model-invocation does to the description.
claude-code -
Path-Scoped Rules: Modular, Glob-Triggered Instructions
The .claude/rules/ system — a modular, eager-loaded instruction layer parallel to CLAUDE.md, with optional glob path-scoping so a rule loads only when Claude reads matching files. Covers unconditional vs path-scoped rules, user-level vs project rules and their load order, the glob format, and the directory and symlink mechanics.
claude-code -
Plan Mode vs Direct Execution: Research Before You Edit
Plan mode restricts Claude to read-only research and a written proposal — no edits — and approving the plan exits the mode into a write mode. Choosing plan versus going direct is a risk-containment decision, not a named-mode toggle; "direct execution" is simply working in a write mode. The opusplan alias pairs the mode with a model-per-phase split — Opus plans, Sonnet executes.
claude-code -
Iterative Refinement: The Loop, the Interview, and Test-Driven Prompting
Agentic work is iterative. The explore-plan-implement-commit rhythm, the interview pattern (Claude interviews you, writes a spec, a fresh session implements), and test-driven prompting are the durable disciplines — methodology that survives any tool rename, hence a stable principle.
claude-code -
CI/CD Integration: Headless Runs, Output Formats, and GitHub Actions
Running Claude Code in CI — the headless `claude -p` entry point and `--bare` for reproducibility, the three output formats, schema-validated structured output via `--json-schema`, the permission flags that lock down a run with no human to prompt, and the GitHub Actions wrapper with its credential model.
claude-code
Part 4
-
Explicit Criteria over Vague Instructions
The controllable lever for output quality is the specification, not the model. Name the success criteria and the output shape explicitly; positive instruction beats negative; the model will not infer a requirement you did not state. This is durable methodology — a stable principle, not a feature surface.
claude-code -
Few-Shot Prompting for Ambiguous Cases
Examples are the most reliable way to steer format, tone, and structure — and the only clean way to pin down an ambiguous case. The pattern is 3-5 relevant, diverse, structured examples, with at least one placed on the edge case showing the desired handling.
claude-code -
Structured Output via Tool Use and JSON Schema
Forcing a known-shape JSON result has two generations. The classic pattern borrows the tool-call channel as a typed output slot; the modern features (strict tool use and output_config.format) use grammar-constrained decoding to make a non-conforming shape unrepresentable. The JSON-Schema subset, additionalProperties false, and the per-request limits are the surfaces to know.
claude-code -
Validation, Retry, and Feedback Loops
Constrained decoding eliminates schema errors, never semantic ones — valid JSON can still hold wrong data. The architect's job is the layer above the schema, discriminating the two error kinds, encoding semantic checks into the schema itself, and closing a bounded validate-feed-back-retry loop that escalates to a human on exhaustion.
claude-code -
Batch Processing: The Message Batches API
When nothing is waiting on the answer, batch trades latency for half the price. The Message Batches API processes up to 100,000 async requests at a 50 percent discount with a 24-hour SLA, and its one non-negotiable contract is custom_id matching, because results come back in any order.
claude-code -
Multi-Pass Review: Independent Reviewers and Attention Dilution
A fresh context catches what a self-review cannot, because attention dilutes as the window fills and an implementer is biased toward its own code. The same independent-reviewer pattern scales from a two-session Writer/Reviewer pair to a fleet of specialists guarded by a verification pass.
claude-code
Part 5
-
Long-Conversation Context: Accumulation, Degradation, Compaction
Context is a finite, accumulating resource, and a long conversation degrades before it overflows. This chapter frames the exam angle — cumulative context, the lost-in-the-middle and summarization failure modes, and lossy automatic compaction — and points to the design book where the degradation mechanics are proven in depth.
claude-code -
Escalation and Ambiguity Resolution
When an agent is uncertain or blocked, the reliable architecture makes it surface the decision rather than guess at intent. AskUserQuestion is the structured mechanism, the interview pattern is its proactive form, and the check-in is a control point where a human resolves what the model cannot.
claude-code -
Error Propagation Across Multi-Agent Systems
In a chain of agents an error does not stay local — an upstream ambiguity becomes a downstream wrong decision, and concurrent faults compound into degradation no single component test reproduces. The defenses are structured error context across boundaries, independent validation, and circuit breakers.
claude-code -
Large-Codebase Context: Compaction, Scratchpads, Delegation
A large codebase has more relevant files than any window holds, and reading them all is the trap, not the solution. The three levers that extend the horizon are compaction, scratchpads that externalize state to disk, and subagent delegation that pays exploration cost in a separate context.
claude-code -
Human Review and Confidence Calibration
Not every output earns automatic trust. The architect calibrates which results proceed and which route to a human, using checkable confidence signals and a tiered funnel — cheap auto-checks, then an isolated judge, then a person — so the human sees only the decisions where their judgment changes the outcome.
claude-code -
Information Provenance: Citations and Temporal Validity
An architect tracks where each claim came from and when its data is valid. The native Citations API ties quoted text to real document spans so a source cannot be fabricated; the provenance triple is the schema-friendly fallback; and a model's knowledge cutoff bounds what it can be trusted to know without a dated source.
claude-code