Every agent — whether you hand-roll it on the Messages API or use the Agent SDK — runs the same cycle: gather context → take action → verify the result → repeat. In API terms, one iteration looks like this:

stop_reason is the loop's steering wheel. The values you must be able to route on:

Two details that show up as distractors: Claude can emit several tool_use blocks in one response (parallel tool calls) — you must return all the matching tool_result blocks in a single following user message. And a failed tool execution is still returned as a tool_result, just with "is_error": true — you don't abort the conversation, you let the model see the failure and adapt.

The third loop step — verify — is the one weak agents skip. Verification means a programmatic check: run the tests, validate the JSON against the schema, re-query the record you just wrote. An agent that "checks its own work" by asking the model whether it did a good job is not verifying anything.

The exam's favorite architectural decision: when do you add subagents? The honest default is a single agent — simpler, cheaper, no coordination overhead. Subagents earn their cost in three situations:

• Context isolation. A subtask would flood the main context with material the parent doesn't need afterwards (a 50-file search, a long document read). The subagent burns its own context and returns only a distilled result.
• Parallelism. Independent workstreams — research four vendors, review five services — can run concurrently.
• Specialization. A focused system prompt and a narrow toolset make a subagent measurably better at one job (a reviewer with read-only tools, a test-runner with Bash only).

When you do go multi-agent, topology is the question that matters. The pattern Anthropic teaches — and the exam rewards — is hub-and-spoke (coordinator–subagent):

The coordinator decomposes the task, spawns subagents with self-contained instructions, merges their results, and owns every routing decision. A flat topology — peer agents messaging each other directly — is anti-pattern #7: no single place holds the full picture, errors vanish between peers, conversations diverge, and debugging becomes archaeology.

Corollary the exam loves: because a subagent starts with a fresh, empty context, its prompt must carry everything it needs — the goal, the constraints, the format of the answer it should return. "The subagent will see the conversation" is never true.

Decompose along independence lines. Good split: "audit these 8 services for the deprecated API" → 8 parallel subagents, one per service, results merged by the coordinator. Bad split: slicing one tightly-coupled refactor into steps that each depend on the previous agent's in-context knowledge — every handoff loses information. If step B needs most of what step A learned, they belong in one agent.

State lives in three places, and the exam tests whether you know which:

The architectural rule: anything that must survive the conversation cannot live only in the conversation. A long-running migration agent should write a checkpoint after each batch (e.g. progress.json, a DB row) so a crash means resuming from batch 47, not starting over. Multi-session workflows (support tickets, week-long projects) key durable state by user or ticket id, and each session loads it as context at start.

Idempotency rides along: if a step can be retried after a crash, executing it twice must be safe — "check then write" beats "append blindly."

Distributed-systems rules apply, with one twist: the consumer of your error messages is a model, and models can only act on what they can read. Hence anti-pattern #5: a subagent that fails must never return an empty result. It returns a structured error the coordinator can reason about:

{
  "status": "failed",
  "category": "rate_limit",        // vs "auth", "not_found", "invalid_input"…
  "retryable": true,
  "attempted": "queried vendor API for Q3 invoices",
  "context": "429 after 3 attempts with backoff; endpoint healthy per status page"
}

With that, the coordinator can choose: retry with backoff (transient), reroute to another approach (terminal), continue with partial results and say so, or escalate. With an empty result it can only guess — and a guess propagated through a synthesis step becomes a confident wrong answer.

Partial failure policy belongs in the design. If 3 of 4 research subagents succeed, does the report ship with a stated gap, or block? Either can be right; deciding at 2 a.m. in production is wrong. The exam expects you to name the policy explicitly.

Verification is programmatic. The reliable pattern for "did the agent's code change work" is: run the test suite. For "is the extraction right": validate against the schema, spot-check against source. Retries are bounded (2–3 with backoff), and what you retry is the operation, not the same failing prompt verbatim — feed the error back so the next attempt differs.

CLAUDE.md is persistent context loaded automatically at session start. Files layer — broader scopes first, more specific scopes override:

Team conventions belong in the project file — it rides along in git so every teammate and every CI run gets it. A good project CLAUDE.md is lean: build/test commands, architectural map, hard conventions. It's loaded into every session, so every line taxes every request; move long reference material into separate docs the agent can read on demand, or into path-scoped rules: files under .claude/rules/ with glob frontmatter (e.g. paths: ["src/api/**"]) that activate only when matching files are touched.

Imports let the root file pull in others with @path/to/file.md. Personal-only scratch config can live in git-ignored local variants, but the exam's framing is: shared → project file; personal → user file; org mandate → enterprise policy.

Three extension mechanisms, distinguished by who triggers them and where they run:

• Slash commands — markdown files in .claude/commands/ (project) or ~/.claude/commands/ (personal). User-invoked (/review-pr 123), with $ARGUMENTS (or $1, $2) interpolation and frontmatter for description, allowed-tools, and model. Best for repeatable prompts a human fires deliberately.
• Skills — a folder with SKILL.md (name + description frontmatter, instructions, optional scripts/resources). Loaded via progressive disclosure: only the one-line description sits in context until the task matches, then the full skill loads. Best for procedural know-how Claude should apply on its own when relevant — and for anything too long to keep permanently in CLAUDE.md.
• Subagents — markdown definitions in .claude/agents/ with frontmatter name, description, optional tools and model. Run in an isolated context with only the tools you grant. Best for delegated roles: a code-reviewer that can read but never edit, a test-runner with Bash only.

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews diffs for correctness and convention violations
tools: Read, Grep, Glob        # read-only — least privilege
---
You are a strict reviewer. Report findings as file:line with severity…

Decision shorthand: always-on fact → CLAUDE.md · human-triggered workflow → slash command · model-triggered know-how → skill · isolated role with restricted tools → subagent.

Plan mode makes Claude research and propose before touching anything: read-only exploration, then a plan you approve, then execution. It earns its keep on multi-file refactors, unfamiliar codebases, and anything risky; it's overhead for a one-line fix. Permission modes set the floor: default (ask per action), acceptEdits (auto-approve file edits), plan (read-only), bypassPermissions (no prompts — only in disposable sandboxes).

Hooks are shell commands the harness itself runs at lifecycle events — PreToolUse, PostToolUse, UserPromptSubmit, Stop, and friends, configured in settings. Two properties make them exam-critical:

• They are deterministic — they run every time, whether or not the model "remembers."
• They can block: a PreToolUse hook exiting with code 2 stops the tool call and feeds its stderr back to Claude as instruction.

// settings: run the formatter after every file edit — guaranteed
"hooks": {
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{ "type": "command", "command": "npx prettier --write \"$FILE\"" }]
  }]
}

This is anti-pattern #1's other half: a CLAUDE.md line saying "always run prettier" is a request the model usually honors; a PostToolUse hook is a guarantee. Compliance rules, secret-scanning, protected-path guards, mandatory formatting — anything with "must" in it — belong in hooks (or CI), never in prompt text alone.

Headless mode is Claude Code without the interactive session: claude -p "<prompt>" runs one task and exits — the building block for CI jobs, pre-commit tooling, and scheduled automation.

claude -p "Review this diff for security issues. Output JSON: \
{findings:[{file,line,severity,issue}]}" \
  --output-format json \
  --allowedTools "Read,Grep,Glob" \
  --max-turns 15

The flags that matter architecturally:

• --output-format json (or stream-json) — machine-parseable results for the pipeline step that consumes them.
• --allowedTools — an explicit allowlist. CI runs unattended, so nobody is there to approve prompts; you pre-authorize the minimum (read-only for review jobs) instead of bypassing permissions wholesale.
• --max-turns — a runaway bound, because unattended loops need ceilings.

The PR-review pattern (GitHub Action or equivalent): trigger on PR → run claude -p with the diff and explicit review criteria → post findings as comments. False-positive control is a design task, and the exam knows the levers: state concrete criteria and severity definitions in the prompt, require file:line evidence for each finding, set a severity threshold below which the job stays silent, and keep review jobs read-only so a bad day can't push code. A noisy reviewer gets ignored within a month — precision beats recall in automated review.

The exam's model of a good prompt is an engineering spec, not a wish. Three moves cover most questions:

• Convert adjectives into criteria. "Be concise" → "3 sentences max." "Flag risky clauses" → "Flag clauses matching any of: uncapped liability, auto-renewal > 12 months, unilateral termination." If a human reviewer couldn't apply your instruction consistently, neither can the model.
• Few-shot the ambiguity, not the obvious. Examples are for the cases where the rule bends: the sarcastic complaint that's actually churn risk, the "question" that's really a refund demand. 3–5 well-chosen edge cases beat 20 easy ones — and include a counter-example ("this one looks like X but is Y, because…").
• Structure with XML tags. Delimit inputs (<document>, <transcript>) so instructions can't blur into data; put the role and non-negotiables in the system prompt; put per-request content in user messages.

One more production reality: instructions in the system prompt set policy; content arriving at runtime (user text, scraped pages, tool output) is data. A prompt that lets fetched content override policy is an injection hole — the exam frames this as "why did the agent follow instructions found in the document?"

"Please respond with JSON" is a request. The production pattern is a contract with three parts:

1. Schema-constrained generation. Define a tool whose input_schema is your output schema, and force it with tool_choice: {"type": "tool", "name": "record_extraction"}. Claude's "tool call" is your structured output — no prose preamble, no markdown fences to strip.
2. Validation. Parse and validate against the schema (types, enums, required fields, ranges) before anything downstream sees it.
3. Bounded retry with the error. On failure, retry (2–3 attempts max) and include the validator's message: "Your last response failed: amount must be a number, got '1,240.50 EUR'." The error in the loop is what makes retries converge instead of coin-flipping.

Hallucination-proofing extraction is its own tested idea: every field a document might legitimately lack must be nullable, with the instruction "return null when absent — never infer." A required "invoice_date" on a document with no date doesn't produce an error; it produces a plausible fabricated date, which is worse. Nullable fields give the model a legal way to say "not there."

"input_schema": {
  "type": "object",
  "properties": {
    "invoice_number": { "type": "string" },
    "due_date":  { "type": ["string","null"], "description": "ISO date; null if absent" },
    "total":     { "type": ["number","null"] }
  },
  "required": ["invoice_number","due_date","total"]   // required ≠ non-null
}

For extraction and classification, drop temperature to 0 — variability is a cost there, not a feature.

One generation pass produces a draft; production quality comes from separating generate and critique:

The details that make it work (and that questions probe):

• Fresh context for the reviewer. A model asked "check your work" inside the same conversation anchors on its own reasoning. A separate call — reviewing the draft as input it has never seen — catches what the generator can't.
• A rubric, not vibes. The critique prompt lists concrete checks ("every claim cites a source section," "all amounts match the table") and returns structured findings.
• Convergence bounds. Fix-and-recheck loops are capped; after N passes, remaining findings escalate rather than looping forever.
• Cost honesty. Three passes ≈ 3× the calls. Reserve multi-pass for high-stakes output (published reports, generated code, legal summaries); a chat reply doesn't need a review pipeline.

Three levers, each with a tradeoff the exam makes you weigh:

Caching mechanics worth knowing cold: the prefix is built in order — tools → system → messages — and you place cache_control breakpoints after the stable parts. Anything volatile (timestamps, user ids, request-specific data) must come after the cached prefix; one changed byte upstream of the breakpoint invalidates the hit. In agent loops, caching the system prompt + tool definitions is the difference between linear and quadratic cost growth as turns accumulate.

The composite pattern for bulk offline work — nightly classification of 100k tickets: shared instruction prefix cached, per-ticket content varying, submitted as a batch. The discounts stack.

Claude chooses tools by reading their descriptions — nothing else. Tool selection bugs are almost always documentation bugs:

• Description = what it does + when to use it + what it returns. "Search the product catalog by keyword; use for availability and price questions; returns up to 20 items with SKU, price, stock" beats "Product search."
• Disambiguate overlapping tools explicitly. If search_orders and get_order coexist, each description says when the other is the right choice ("if you already have an order id, use get_order").
• Tight input schemas. Enums for closed sets, formats spelled out ("ISO 8601 date"), required vs optional made honest, and per-parameter descriptions. Every loose parameter is an invitation to improvise.
• Fewer, better tools. Each definition costs context and adds a selection error mode. Ten sharp tools outperform forty vague ones; consolidate near-duplicates into one tool with a mode parameter when the interface stays clear.

Return values are design too: include the fields the agent needs to continue reasoning (ids for follow-up calls, human-readable status), not a raw DB row dump that floods context.

When a tool fails, the model is the error handler — so the error must be written for a reasoning consumer. The exam's canonical shape:

// returned as a tool_result with "is_error": true
{
  "category": "rate_limit",     // a closed set: rate_limit | auth | not_found | invalid_input | timeout…
  "retryable": true,
  "message": "Inventory API throttled (429). Safe to retry after ~30s.",
  "hint": "If this is the 3rd failure, report inventory as unavailable instead."
}

• Category from a closed set lets behavior branch predictably — and lets your monitoring count failure classes.
• retryable is the load-bearing bit: transient (rate_limit, timeout) → try again with backoff; terminal (not_found, invalid_input) → change the input or the plan, never blind-retry.
• Message and hint tell the model what happened and what a sensible next move is — recovery guidance, not a stack trace.

Two failure modes the exam plants as distractors: raising an exception that kills the whole conversation (a tool failure is information, not a crash), and returning {"error": "something went wrong"} — which gives the model nothing to branch on, so it guesses.

The Model Context Protocol standardizes how external capability plugs into Claude (and any MCP client). A server exposes up to three primitives, distinguished by who controls invocation — the exam's favorite MCP question:

Transports: stdio for a server running as a local child process (dev tools, local scripts — no network hop), HTTP for remote shared services (a team's ticketing bridge, hosted connectors — with real auth). Scopes in Claude Code decide who gets the config:

• local — just you, just this project (default; experiments, personal credentials).
• project — written to .mcp.json, checked into git, shared with the whole team. Secrets stay out — use env-var expansion.
• user — you, across all projects (your personal utilities).

claude mcp add --scope project ticketing -- npx @acme/ticketing-mcp
# → .mcp.json committed; teammates get the server on next session

Anti-pattern #6 is giving every agent the full toolset "for flexibility." It fails on three axes at once:

• Safety: a research subagent with write access to production is an incident with a timestamp not yet filled in. Tool grants are the agent's blast radius.
• Accuracy: tool selection error grows with the option count; an agent choosing among 8 relevant tools outperforms one choosing among 40.
• Cost: every definition rides in every request's context, for every agent, whether used or not.

The discipline mirrors IAM: grant per role, deny by default. The reviewer gets Read, Grep, Glob. The test-runner gets Bash scoped to test commands. The deployer alone holds deploy tools — and its irreversible actions sit behind an approval gate. In Claude Code this is the subagent tools frontmatter plus permission rules; in the Agent SDK, per-agent allowed-tool lists; with MCP, per-agent server selection — same principle, three mechanisms.

Governance rounds it out: log which agent called which tool with which arguments (audit trail), and route high-consequence tools through human confirmation. If reading the log can't tell you which agent broke something, the scoping is too loose.

Anti-pattern #4: assuming a bigger window fixes retrieval. A 200k-token window means the model can hold 200k tokens — not that it attends to all of them equally. Effective use is about placement, structure, and selection:

• Placement: non-negotiable policy lives in the system prompt. In very long contexts, material buried mid-stream is recalled worst — anchor critical constraints where they're privileged, and restate the question after a long document rather than only before it.
• Structure: wrap each source in labeled XML (<contract id="7">…) and have the model quote or cite the relevant section before answering — grounding beats hoping.
• Selection: if the task needs 5 of 400 pages, retrieve those 5 (search/RAG) instead of shipping the filing cabinet. Less irrelevant context is an accuracy win, not just a cost win.
• Agent-loop hygiene: long sessions accumulate stale tool results. Compaction — summarize-and-clear — keeps the working set relevant; old bulky outputs are the first thing to drop.

Context ends — sessions close, windows fill, work moves between agents and humans. What survives is what you deliberately package. The tested pattern is the structured handoff:

## Handoff — payment-service refactor
Goal:        extract billing logic into billing/ module
Decisions:   keep Stripe adapter interface; do NOT touch webhooks (on-call freeze)
State:       7/12 call sites migrated (list in migration.md); tests green as of run #482
Blocked on:  finance sign-off for invoice rounding change
Next steps:  migrate remaining 5 sites, then delete legacy shim

Principles behind it:

• Decisions and constraints outrank narrative. The successor needs what was decided and why, plus what must not be done — not a replay of the whole transcript. A raw dump buries the two lines that matter.
• Externalize, don't rely on memory. The handoff is written to a durable place (file, ticket, DB) and the next session loads it as context — the same external-state rule from D1, applied to knowledge.
• Compaction is a handoff to yourself. When a long session's context is summarized, the same priorities apply: keep goals, decisions, open items, current state; drop verbose tool output and dead-end exploration.

Anti-pattern #2 is routing on the model's self-reported confidence ("escalate when you're unsure"). Self-assessment isn't calibrated — a model can be fluently wrong at 9/10 confidence — and it makes escalation unauditable. The exam wants deterministic triggers, checked in code:

Design the handoff, not just the trigger: the human receives a package — conversation summary, what was attempted, why this escalated, customer state — so escalation is a warm transfer, not a cold restart. And the boundaries themselves live in code or config where they're testable; the prompt merely tells the agent they exist.

D5 closes the loop that D1 opened: errors must propagate with context, and the system must degrade on purpose rather than by accident.

• Propagation: a subagent failure travels up as structured data (category, retryable, what was attempted) and the coordinator — the only component with the full picture — decides: retry, reroute, degrade, or escalate. Handling failures silently at the edge hides them from the one component that could respond well.
• Timeouts and budgets everywhere: per tool call, per subagent, per task (--max-turns in headless runs). An agent that can hang forever eventually will.
• Bounded, differentiated retries: with backoff, only for retryable categories, and each retry varies something — otherwise it's the same failure at higher cost.
• Graceful degradation is declared: "3 of 4 sources analyzed; vendor-API data unavailable" — partial results ship labeled, or the policy says block. Silent gaps become confident wrong reports downstream.
• Observability: log every tool call, hand-off, and decision with ids. When the answer is wrong, you replay the reasoning chain instead of interrogating a black box.