Claude Certified Architect – Foundations
Commonly abbreviated CCAR-F. This single page holds a fast high-level overview to orient you, and a thorough study guide covering the four core areas Anthropic names for this exam — Claude Code, the Claude Agent SDK, the Claude API, and the Model Context Protocol — organized against the five weighted domains and six-scenario bank defined in Anthropic's official CCAR-F Exam Guide. Overview items link straight into their deep-dive sections.
$125 USD 4 core areas: Code · SDK · API · MCP 60 items · 120 min · 4 of 6 scenarios · pass 720/1000Part 1 — High-Level Overview
What & Why
The Claude Certified Architect – Foundations exam, delivered through Anthropic's partner academy at anthropic-partners.skilljar.com, validates that a practitioner can make informed decisions about tradeoffs when implementing real-world solutions with Claude. It is not a coding test and not a trivia quiz about API parameters in isolation — it is a "given this business scenario, which architecture is the right fit?" exam, in the same spirit as cloud-vendor architect certifications, but scoped to agentic AI built on Claude.
Anthropic states the exam tests foundational knowledge across four core areas: Claude Code, the Claude Agent SDK, the Claude API, and the Model Context Protocol (MCP). You are expected to know when to reach for a single prompt versus a tool-using agent versus a multi-agent system, when to build a custom integration versus adopt Claude Code or an MCP server, and how to reason about cost, latency, accuracy, and autonomy tradeoffs — the framing carried through this whole guide, see §2.
Exam at a Glance
| Attribute | Value | Source |
|---|---|---|
| Cost | 125 USD | Official (Anthropic) |
| Core areas tested | Claude Code, Claude Agent SDK, Claude API, MCP | Official (Anthropic) |
| Pre-exam requirement | Review the Exam Guide, Certification Terms & Conditions, and Certification Exam Policy | Official (Anthropic) |
| Number of items | 60 questions / 120 minutes | Official (Exam Guide) |
| Item format | Multiple-choice and multiple-response — each item states how many responses to select | Official (Exam Guide) |
| Scoring | Scaled 100–1,000, pass at 720 | Official (Exam Guide) |
| Validity | 12 months from the date the credential is awarded | Official (Exam Guide) |
| Format | 4 scenarios drawn from a bank of 6 | Official (Exam Guide) |
| Delivery | Proctored: online proctored and/or test center, per program policy. Scheduled through the Anthropic Partner Academy and Pearson VUE | Official (Exam Guide) |
| Result reporting | Pass/fail with scaled score, plus percent-correct by domain on the score report | Official (Exam Guide) |
→ Deep dive: §1 Exam Details & Logistics · → The scenario bank
The 5 Domains (official CCAR-F Exam Guide blueprint)
Anthropic's official CCAR-F Exam Guide defines five weighted domains that sum to 100% of the exam. They cut across the four core content areas (Claude Code, Agent SDK, API, MCP) named on the certification page.
| Domain | Weight | What it tests | Deep dive |
|---|---|---|---|
| Agentic Architecture & Orchestration D1 | 27% | Agent loops, planning, subagents/orchestration, memory, error handling, human-in-the-loop, evaluation, failure modes. | → §3 |
| Tool Design & MCP Integration D2 | 18% | What MCP solves, server/client/host roles, tools/resources/prompts, transports, schema design, permissions. | → §4 |
| Claude Code Configuration & Workflows D3 | 20% | CLI workflow, subagents, hooks, skills, settings & permission modes, MCP integration. | → §5 |
| Prompt Engineering & Structured Output D4 | 20% | System prompts, structuring instructions, examples, chain-of-thought, structured/constrained output, prompt vs fine-tune vs RAG. | → §6 |
| Context Management & Reliability D5 | 15% | Context window budget, prompt caching, retrieval vs long context, context editing/compaction, reliability under failure. | → §7 |
The Scenario Bank (4 of 6, official)
Anthropic's Exam Guide names all six production scenarios the exam is built from, and confirms only 4 of the 6 appear on any given attempt. Knowing the bank in advance means you can rehearse each context specifically rather than studying blind.
| # | Scenario | Be ready to reason about |
|---|---|---|
| 1 | Customer Support Resolution Agent | Building a customer support resolution agent with the Claude Agent SDK, handling high-ambiguity requests (returns, billing disputes, account issues), backend access through custom MCP tools (get_customer, lookup_order, process_refund, escalate_to_human), targeting 80%+ first-contact resolution while knowing when to escalate. |
| 2 | Code Generation with Claude Code | Configuring Claude Code for a real repo — CLAUDE.md project instructions, hooks and permission modes for a coding workflow, when to hand off to a subagent, and how a generated change gets reviewed and verified before it ships. |
| 3 | Multi-Agent Research System | Orchestration patterns (lead agent + subagents, fan-out/parallel workers), why each subagent gets its own context window, and how findings get synthesized without stepping on each other or blowing the cost budget. |
| 4 | Developer Productivity with Claude | Where Claude/Claude Code genuinely speeds up a developer (review, docs, refactors, test generation) versus where keeping a human fully in control matters more than raw automation. |
| 5 | Claude Code for Continuous Integration | Running Claude Code non-interactively in a pipeline — permission modes safe for unattended/CI use, hooks as deterministic policy gates, and rate-limit/cost discipline when a pipeline can trigger many runs. |
| 6 | Structured Data Extraction | Forcing guaranteed-parseable output (typically via a tool schema) for downstream systems, validating extracted fields before they're trusted, and when prompting alone is enough versus when the task needs retrieval or a verification pass. |
What an Architect Decides
The exam is built around a small set of recurring tradeoff decisions. Internalize these before memorizing any API detail — most scenario questions are really asking you to apply one of these five judgment calls to a specific business situation.
Prompt vs Tool-Use vs Agent vs Multi-Agent
Escalate autonomy only as far as the task needs. A single well-crafted prompt beats a tool-using loop for a bounded, one-shot task. → detailsBuild vs Buy
Claude Code / off-the-shelf MCP servers vs a custom Agent SDK or raw-API integration — weigh time-to-value against control and differentiation. → detailsCost vs Latency vs Accuracy
Model family choice, single-pass vs multi-step verification, streaming vs batch, caching vs re-sending context. → detailsHow Much Autonomy to Grant
Read-only vs write access, auto-approve vs human checkpoint, sandboxed vs production credentials. → detailsLong Context vs Retrieval
Stuff everything in context (simple, costly at scale) vs retrieve-on-demand (scales, adds a moving part). → detailsRecommended Materials (be conservative — this exam is new)
This certification launched recently, and the internet already has low-quality "practice exam" listings for it that predate any real test-taker feedback. The only materials worth trusting right now are Anthropic's own documentation and academy courses, plus the primary MCP specification.
docs.claude.com (API, Agent SDK, Claude Code) → the Anthropic Academy courses on the partner academy site → the official modelcontextprotocol.io specification for MCP → hands-on building (a small tool-using agent, a real MCP server, a real repo worked with Claude Code). Skip third-party "dump" question banks for a exam this new — there is no track record to trust them by.Study Plan (Quick Version)
Built on active recall + spaced repetition plus real building — this exam rewards hands-on experience more than reading. About 3 weeks for someone already comfortable writing code against LLM APIs.
- Week 1: Read the Claude API and Agent SDK docs end to end; build a small tool-using agent from scratch (no framework) so the agent loop is muscle memory.
- Week 2: Read the MCP spec; write a real MCP server (stdio transport) with at least one tool and one resource; wire it into Claude Code. Learn Claude Code's subagents, hooks, and skills by using them on a real repo.
- Week 3: Drill the decision tables (§9), study prompt caching and context management, do the worked scenario questions (§15), review the glossary, and re-read the Exam Guide PDF once more if you can access it.
→ Detailed study plan (§12) · ⚡ Cram Jam one-pager · → Exam-day tips & traps (§13)
Part 2 — Thorough Study Guide
1 · Exam Details & Logistics
The Claude Certified Architect – Foundations exam is delivered through Anthropic's partner academy at anthropic-partners.skilljar.com. The facts below are taken verbatim from Anthropic's own official CCAR-F Exam Guide PDF, not from third-party write-ups.
- Exam code CCAR-F; price 125 USD.
- 60 items total — multiple-choice and multiple-response, each item states how many responses to select.
- 120-minute time limit.
- Structure: 4 scenarios drawn from a bank of 6 (see §1a).
- Delivery: proctored — online proctored and/or test center, per program policy. Registration and scheduling run through the Anthropic Partner Academy and Pearson VUE: you create a Pearson VUE account from the confirmation email, then choose either online proctoring or a Pearson test center.
- Passing score: scaled score of 720 on a 100–1,000 scale.
- Validity: 12 months from the date the credential is awarded.
- Result reporting: pass/fail with scaled score, plus percent-correct by domain on the score report — so your post-exam feedback tells you which of the five domains (§ov-domains) to shore up if you don't pass.
- The exam tests foundational knowledge across four core areas: Claude Code, the Claude Agent SDK, the Claude API, and MCP, organized into the five weighted domains in the domain table.
- Candidates must review the Exam Guide, Certification Terms and Conditions, and Anthropic Certification Exam Policy before the exam session.
This program is new and Anthropic's guide is itself subject to change — re-check the current PDF before you book, but treat everything above as official, not a third-party estimate.
Percent-correct by domain: why it changes how you study
Because the score report breaks results out by domain, a near-miss failure tells you exactly where to focus a retake — there's no need to re-drill a domain you already cleared. It also means a study plan that neglects the smaller-weight domains (Context Management & Reliability at 15%, Tool Design & MCP Integration at 18%) still shows up as a visible weak spot on the report even if your overall score would have passed on the strength of the two 20%-weight domains alone.
Closed-book rule
Treat the exam as closed book: assume you cannot open Claude, cannot search the docs, and cannot switch browser tabs during the session. That means the memorization in this guide's Glossary and Decision Guides is not optional background reading — it is what you have available in the room.
Target candidate
Anthropic frames this as validating the ability to make informed tradeoff decisions in real-world Claude implementations — that implies hands-on building, not just reading documentation. If you have never written code that calls the Claude API, built a tool-using agent, or used Claude Code on a real project, do that first; no amount of guide-reading substitutes for having actually hit a tool-use retry loop or a context-window overflow yourself.
1a · The Scenario Bank (4 of 6)
Every attempt draws 4 of these 6 official scenarios. Each is a production context the multiple-choice/multiple-response items are framed around — study each one specifically, not just the domains abstractly.
1. Customer Support Resolution Agent
Building a customer support resolution agent with the Claude Agent SDK, handling high-ambiguity requests — returns, billing disputes, account issues — with backend access through custom MCP tools (get_customer, lookup_order, process_refund, escalate_to_human), targeting 80%+ first-contact resolution while knowing when to escalate. Be ready to reason about tool scoping and permissions on a process_refund-style tool (§4.6), the human-in-the-loop checkpoint before an irreversible refund or account change (§3.6), and what separates a resolvable request from one that should hit escalate_to_human.
2. Code Generation with Claude Code
Configuring Claude Code for real code-generation work in a repo: a project instructions file (§5.1), permission modes appropriate to how much the generated diff should be trusted before a human looks at it (§5.5), and when to hand a sub-task to a subagent rather than have one long session do everything (§5.2). Expect questions on what belongs in CLAUDE.md versus a one-off prompt, and how a generated change gets verified before it merges.
3. Multi-Agent Research System
Designing an orchestration layer — a lead agent decomposing a research task and dispatching subagents, or parallel workers whose findings get merged (§3.3). Be ready to justify when multiple agents are worth the coordination overhead and cost multiplication versus a single agent with a bigger tool set, and how a research subagent's findings should be condensed before they re-enter the orchestrator's context (§7.4).
4. Developer Productivity with Claude
Applying Claude and Claude Code to everyday developer workflows — code review, documentation, refactoring, test generation — and knowing which of those should stay fully automated versus keep a human decision in the loop. Expect the "cheapest fix first" framing (§6): often the right answer is a clearer prompt or a project instructions file, not a bigger model or a new tool.
5. Claude Code for Continuous Integration
Running Claude Code non-interactively in a CI/CD pipeline: which permission mode is safe for unattended execution (§5.5), using hooks as deterministic policy gates around an otherwise probabilistic agent (§5.3), and keeping an eye on rate limits and cost when a pipeline can trigger many runs per day (§3.5, §10).
6. Structured Data Extraction
Extracting structured data a downstream system can trust — forcing guaranteed-parseable output, typically via a tool schema (§6, §8), and validating extracted fields before they're consumed. Expect questions on when prompting alone is enough for an extraction task versus when it needs retrieval for source grounding or a verification pass for accuracy.
Scenario → domain → ready answers
| # | Scenario | Domains it exercises | Have a ready answer for |
|---|---|---|---|
| 1 | Customer Support Resolution Agent | D1 (agent loop, escalation), D2 (MCP tool scoping) | When to escalate vs resolve; how a process_refund-style tool should be gated (§3.6, §4.6) |
| 2 | Code Generation with Claude Code | D3 (Claude Code config), D1 (subagent handoff) | What belongs in CLAUDE.md vs a one-off prompt; which permission mode fits the risk of the generated diff (§5.1, §5.5) |
| 3 | Multi-Agent Research System | D1 (orchestration) | When multiple agents are worth the coordination cost; how subagent findings get condensed before synthesis (§3.3, §7.4) |
| 4 | Developer Productivity with Claude | D4 (prompt engineering), D1 (autonomy) | The cheapest-fix-first framing; which developer tasks stay human-reviewed (§6, §3.6) |
| 5 | Claude Code for Continuous Integration | D3 (Claude Code config), D1 (reliability) | Which permission mode is safe unattended; hooks as deterministic gates (§5.5, §5.3) |
| 6 | Structured Data Extraction | D4 (structured output), D5 (grounding) | Tool-use-as-schema vs prompting alone; when a verification pass is needed (§6, §3.7) |
2 · The Architect's Tradeoff Framing
Anthropic's own description of this exam is explicit: it validates the ability to make informed decisions about tradeoffs. Every domain below is really an application of the same handful of judgment calls to a different layer of the stack.
Prompt vs tool-using agent vs multi-agent system
- Single prompt — the task is bounded, the model has (or you can give it) everything it needs in the input, and there's one shot at the answer. Cheapest, fastest, most predictable. Use for classification, extraction, summarization, rewriting.
- Tool-using agent — the task requires information or actions the model doesn't have in its context: querying a live system, running code, searching the web, calling an internal API. Adds latency and cost (multiple model turns) and a new failure surface (tool errors, malformed calls) in exchange for capability the prompt alone can't provide.
- Multi-agent system — the task decomposes into genuinely independent subtasks that benefit from separate context windows, separate tool access, or parallel execution (e.g., one subagent researches while another writes). Adds coordination overhead, cost multiplication, and new failure modes (subagents stepping on each other, inconsistent shared state). Only reach for this when a single agent's context or tool set would get overloaded or when subtasks are truly parallelizable.
The full topology ladder
The scenario bank tends to hide one of five topologies inside a business situation. Recognizing which rung the scenario is describing — and whether it needs the next rung — is most of the work.
| Topology | What it buys | Cost (latency / tokens) | Typical failure modes | Right answer when… |
|---|---|---|---|---|
| Single prompt | One clean pass, fully predictable, easiest to test | Lowest — one model turn | Fails silently on inputs it wasn't designed for; no recovery path | Task is bounded and everything needed is already in the input |
| Prompt chain | Decomposes a multi-step task into fixed, inspectable stages (e.g. draft → critique → revise) | Low-medium — a few fixed turns, no branching | A bad early stage poisons every stage after it; rigid if the task doesn't decompose that way | The steps are known in advance and always run in the same order |
| Single agent with tools | Access to live data/actions outside the model's own knowledge | Medium — variable turns, one tool call per round trip | Tool misuse, looping/thrashing, context fills with tool output over a long session | The task needs live information or an action, but is one bounded job |
| Orchestrator with subagents | Keeps the parent's context clean; each subtask gets a scoped tool set and its own window | Medium-high — orchestrator turn plus each subagent's own turns | Synthesis step drops or garbles subagent findings; orchestrator itself becomes a bottleneck | One agent's exploration would otherwise flood its own context, but the task is still basically one thread |
| Multi-agent (parallel/fan-out) | Genuine parallelism across independent subtasks; can cut wall-clock time on decomposable work | Highest — cost multiplies by agent count, coordination overhead on top | Agents step on shared state, duplicate work, or produce inconsistent results that don't reconcile | Subtasks are truly independent and the coordination cost is worth the parallel speedup |
Build vs buy
Claude Code and existing MCP servers are pre-built solutions to common problems (an agentic coding CLI, an integration to a common SaaS tool). A custom Agent SDK application or raw API integration is more work but gives you control over the exact loop, UI, and constraints. Buy/adopt when the problem is generic and well-served; build custom when you need a bespoke user experience, non-standard permission model, or tight integration with proprietary systems.
Cost vs latency vs accuracy
These three pull against each other. A larger, more capable model is typically slower and pricier per token but more accurate on hard tasks; a smaller model is fast and cheap but may need more scaffolding (verification passes, retries, narrower tasks) to hit the same accuracy. Streaming improves perceived latency without changing total cost; batch processing cuts cost by trading away latency guarantees; prompt caching cuts both cost and latency on repeated context at the price of some cache-management complexity. See the full comparisons in §8 and §9.
How much autonomy to grant
Autonomy is a dial, not a switch: read-only tools vs tools that write/delete; auto-approved tool calls vs a human-in-the-loop checkpoint before anything irreversible; a sandboxed environment vs direct production credentials. The right setting depends on the blast radius of a mistake and how verifiable the agent's output is before it takes effect. See §3.6.
3 · Domain — Agentic Architecture & Orchestration D1 · 27%
This domain tests whether you can design the loop that turns a goal into actions: how the agent plans, calls tools, keeps state, recovers from errors, and knows when to stop or ask for help.
3.1 · The Agent Loop
The canonical agent loop, whether hand-rolled against the raw API or driven by the Claude Agent SDK / Claude Code, is: gather context → take action → verify work → repeat. Concretely against the Claude API this looks like: send messages (with tool definitions) → the model responds with either a final answer or one or more tool_use content blocks → your code executes the requested tool(s) → you send the results back as tool_result content blocks in a new user turn → repeat until the model returns a final answer (stop_reason: end_turn) or you hit a limit.
- The loop terminates on a natural stop, a turn/step budget, a token budget, or an explicit human interrupt — an architect must always define at least one of these, or an agent can loop indefinitely on a stuck task.
- Extended thinking lets the model reason step by step before acting, useful for tasks that benefit from deliberate planning; it trades latency and tokens for better decisions on hard problems, so reserve it for cases that actually need it.
3.2 · Planning
- Implicit planning — the model plans inline as part of its response (or its thinking), then acts. Simplest, works well for moderate-complexity tasks.
- Explicit plan-then-execute — have the model produce a plan artifact first (a task list, a set of steps) that a human or a checkpoint can review before any tool executes. Claude Code's plan mode is a concrete instance of this pattern: it lets the agent research and propose a plan without making any edits until approved.
- Longer or riskier tasks favor explicit plans with checkpoints; short, low-risk tasks favor letting the model plan and act in the same pass.
3.3 · Subagents & Orchestration
- Subagents are separate agent instances, each with their own context window, system prompt, and (often) a restricted tool set, invoked by an orchestrating agent for a bounded piece of work. Claude Code and the Agent SDK both support this pattern natively.
- Why use them: keep the parent agent's context clean (a subagent's internal exploration doesn't pollute the main context), enforce narrower tool/permission scope per subtask, and parallelize independent work.
- Orchestration patterns: a lead agent that decomposes a task and dispatches subagents (fan-out), a pipeline where each agent's output feeds the next, and parallel workers whose results are merged by an orchestrator. More agents means more coordination logic and more chances for inconsistent or conflicting results — only add agents when the task genuinely decomposes.
3.4 · Memory & State
- In-context memory — the running conversation/context window itself; free but bounded and it decays in relevance as it fills (see §7).
- Persistent memory — state written outside the context window (files, a memory tool, a database) that the agent reads back in later sessions or turns. Necessary for anything that must survive a context reset or span multiple sessions.
- File-based state — the simplest durable memory: have the agent write progress/notes/plans to files it can re-read. This is how Claude Code persists project conventions (e.g. a project instructions file read at session start) and how long-running agent tasks checkpoint progress.
- An architect must decide what needs to persist (facts, decisions, progress) versus what can be safely discarded when context is trimmed.
3.5 · Error Handling & Retries
- Tool errors should be returned to the model as a
tool_resultmarked as an error, with a clear message — the model can often self-correct (retry with different arguments, pick a different tool) if given a legible error rather than a raw stack trace. - Retries with backoff apply at the infrastructure level too: rate limits (HTTP 429) and transient server errors (5xx) should be retried with exponential backoff; the API surfaces rate-limit and retry-relevant response headers for this purpose.
- Bounded retries — always cap retry attempts per tool call and per overall task; an agent that retries forever on a persistently failing tool burns cost without making progress. A common pattern is to fail closed after N attempts and either ask a human or degrade gracefully.
Reliability failure modes beyond the single bad tool call
§3.8 covers agent-level failure modes (looping, context rot, tool misuse). The table below covers failure modes at the level of a whole task or run — the ones an architect designs infrastructure around, not just a prompt.
| Failure | Symptom | Root cause | Mitigation |
|---|---|---|---|
| Tool thrash | Agent alternates between two or more tools repeatedly without settling on one | Overlapping tool descriptions, or a task the model can't disambiguate from the tools it's been given | Narrow/clarify tool descriptions, reduce overlapping tools, cap alternation before escalating |
| Context exhaustion | Agent truncates output, drops earlier constraints, or the request fails outright near the token limit | Long-running session accumulates tool output/history faster than it's trimmed | Proactive compaction (§7.4), scoped tool sets, subagents for exploration (§3.3) |
| Silent wrong answer | Response looks confident and well-formed but is factually wrong, with no error signal | No grounding/verification mechanism; the model isn't required to cite or check its claim | Require tool-grounded evidence or citations for factual claims, add a verification pass (§3.7) |
| Partial failure mid-task | Some steps of a multi-step task completed, others didn't, and the system doesn't know which | No per-step state tracking; a crash or timeout mid-sequence leaves an inconsistent result | Idempotent steps, persisted per-step state (§3.4), resume-from-last-known-good rather than restart-from-scratch |
| Non-determinism across runs | Same input produces materially different outputs or different tool-call sequences on repeat runs | Model sampling variance, plus any tool/environment state that itself isn't fixed between runs | Evals that tolerate reasonable variance rather than exact-match, lower temperature for tasks that need consistency, treat exact reproducibility as untestable by design |
3.6 · Human-in-the-Loop Checkpoints
- Place a human checkpoint before irreversible or high-blast-radius actions: deleting data, sending external communications, spending money, deploying to production, modifying access controls.
- Claude Code's permission modes are a direct implementation of this: interactive approval by default, a plan mode that blocks all edits until a plan is approved, an auto-accept-edits mode for low-risk local iteration, and a fully autonomous mode intended only for sandboxed/trusted environments. See §5.5.
- Checkpoints can be per-action (approve this specific tool call) or per-plan (approve the whole plan up front, then let execution run unattended) — the tradeoff is oversight granularity versus operator throughput.
Autonomy spectrum
| Level | Risk profile | Reversibility of actions | Required when… |
|---|---|---|---|
| Fully autonomous | Highest — no human sees an action before it takes effect | Assumes actions are reversible or low-consequence; a mistake ships immediately | Sandboxed/trusted/CI environments, low-blast-radius tools, or a track record proving the failure rate is acceptable |
| Checkpointed (per-plan) | Medium — one review gate before a batch of actions runs unattended | Everything after the checkpoint executes without further review, so reversibility of the whole plan matters, not just one step | The plan is coherent and inspectable as a whole, and per-action approval would be pure overhead |
| Approval-gated (per-action) | Low — nothing high-risk executes without a specific yes | Only relevant to gated actions; ungated (e.g. read-only) actions still run freely | Actions are irreversible, expensive, or externally visible (deletes, sends, spend, prod deploys) |
| Suggestion-only | Lowest — the agent never acts, only proposes | N/A — nothing executes without a human separately performing the action | The domain is too high-stakes, too novel, or too under-evaluated to trust any automated execution yet |
3.7 · Evaluation & Guardrails
- Evals — a held-out set of representative tasks with known-good outcomes, run whenever the prompt, tools, or model change, so regressions are caught before production rather than by users.
- Guardrails operate at multiple layers: input validation/classification before the agent sees a request, tool-level constraints (schema validation, allow-lists, scoped credentials), and output validation before an action takes effect or a response reaches a user.
- Guardrails and evals are complementary, not substitutes: evals catch systemic quality regressions during development; guardrails catch bad individual outcomes at runtime.
3.8 · Failure Modes of Agents
| Failure mode | What it looks like | Mitigation |
|---|---|---|
| Looping / thrashing | Agent repeats the same failing action, or oscillates between two states without progress. | Turn/step budgets, detect repeated identical tool calls, escalate to a human after N attempts. |
| Context rot | Long-running agent's context fills with stale tool output; quality degrades as the window fills. | Context editing/compaction, subagents for exploration, summarize-and-discard old tool results. |
| Tool misuse | Wrong tool chosen, or right tool called with malformed/hallucinated arguments. | Clear tool descriptions and strict schemas, narrower tool set per task, validate arguments before execution. |
| Overconfident/ungrounded output | Agent states something as fact it did not actually verify with a tool. | Require tool-grounded evidence for factual claims, citations, verification steps. |
| Runaway cost/scope | Agent keeps calling tools or spawning subagents well past the useful point. | Explicit budgets (tokens, turns, dollars, subagent count), human checkpoints at scope boundaries. |
| Unsafe autonomous action | Agent takes an irreversible action without approval it should have required. | Human-in-the-loop checkpoints on high-blast-radius tools; least-privilege tool/credential scoping. |
4 · Domain — Tool Design & MCP Integration D2 · 18%
4.1 · What MCP Is & the Problem It Solves
The Model Context Protocol (MCP) is an open, standardized protocol (JSON-RPC based) for connecting AI applications to external systems — tools, data sources, and prompts — without writing a bespoke integration for every combination of model and system. Before MCP, connecting N applications to M tools/data sources meant up to N×M custom integrations; MCP turns that into N clients and M servers that all speak the same protocol, the same problem language server protocol (LSP) solved for editors and languages.
4.2 · Hosts, Clients, Servers
- Host — the AI application the user interacts with (Claude Code, Claude Desktop, a custom Agent SDK app). It manages the overall session and security policy.
- Client — lives inside the host, maintains a 1:1 connection to a single MCP server, and handles the protocol-level exchange.
- Server — an external program that exposes tools, resources, and/or prompts over MCP. It can be a thin wrapper over an existing API, a local script, or a full standalone service.
| Role | Responsibility | Concrete example |
|---|---|---|
| Host | Owns the user-facing session, security policy, and which servers are even allowed to connect | Claude Code, Claude Desktop, a custom Agent SDK application |
| Client | Maintains one 1:1 protocol connection to a single server and handles the message exchange | The connector object living inside the host, one per configured server |
| Server | Implements the actual tools/resources/prompts and enforces authorization for whatever it exposes | A wrapper over an internal ticketing API, a database-query server, a filesystem server |
4.3 · Tools, Resources, Prompts (and Sampling)
| Primitive | Controlled by | Purpose |
|---|---|---|
| Tools | Model-controlled | Executable functions the model can invoke (call an API, run a query, take an action) — this is what most people mean when they say "MCP server." |
| Resources | Application-controlled | Read-only, addressable data the host can attach to context (a file, a database record, a document) without the model needing to call a tool for it. |
| Prompts | User-controlled | Reusable, parameterized prompt templates the server exposes, typically surfaced to the user as a menu of actions (e.g. a slash command). |
| Sampling | Server-initiated | Lets a server request a completion from the client's model — inverts the usual direction, useful when a server needs LLM reasoning as part of its own logic without holding its own API key. |
Which primitive to choose, given the situation
| Situation | Who initiates | Pick |
|---|---|---|
| The model needs to take an action or fetch data based on its own in-context reasoning | Model | Tool |
| The host wants to attach known, relevant data up front without a model round trip to fetch it | Application/host | Resource |
| The user wants a one-click/one-command way to kick off a standard, parameterized workflow | User | Prompt |
| The server itself needs LLM reasoning as part of its own internal logic, without holding a model API key | Server | Sampling |
4.4 · Transports
| Transport | Use when |
|---|---|
| stdio | The server runs as a local subprocess on the same machine as the host — simplest setup, no network exposure, common for local dev tools and CLI integrations like Claude Code. |
| Streamable HTTP | The server runs remotely / as a standalone service that multiple clients or users connect to over the network; supports streaming responses back to the client. |
Choose stdio for local, single-user, trusted tooling; choose HTTP when the server needs to be shared, remotely hosted, or independently scaled.
| stdio | Streamable HTTP | |
|---|---|---|
| Deployment shape | Local subprocess launched by the host itself | Standalone service, deployed and run independently of any one host |
| Auth model | Implicit — trusts whatever local process/user context launched it | Explicit — the server must authenticate/authorize each remote client itself |
| Multi-client support | Effectively single-client — one subprocess per host session | Designed for many concurrent clients/users against one running server |
| When to pick | Local dev tools, CLI integrations, trusted single-user tooling | Shared/team tooling, anything remotely hosted or independently scaled |
4.5 · Writing Good Tool Descriptions, Schemas & Granularity
- Descriptions are prompts. The model chooses and fills in tools based on the tool's name, description, and parameter schema — vague descriptions cause wrong-tool selection and malformed arguments just as surely as a vague instruction would.
- Be explicit about types, constraints, and defaults in the JSON schema; enumerate allowed values where possible rather than relying on free text.
- Granularity: too many narrow tools burdens the model with tool-selection overhead and eats context (every tool definition costs tokens); too few overly broad tools push complexity into ambiguous free-form arguments. Aim for tools that map to a single, clear action a user would recognize.
- Idempotency and side effects should be documented in the description itself: is calling this tool twice safe? Does it write, or only read? An architect should mark and treat destructive/non-idempotent tools differently (e.g. require confirmation) than safe, idempotent read tools.
| Rule | Why it matters to tool selection | Failure it prevents |
|---|---|---|
| Granularity — one clear action per tool | The model matches intent to a tool by name/description; a tool doing three things forces it to guess which one applies | Wrong tool chosen, or a right tool called for the wrong sub-purpose |
| Naming — specific, action-oriented names | Name is the first, cheapest signal the model uses to shortlist candidate tools | Tool confused with a similarly-scoped tool of a different name |
| Description quality — states what it does, inputs, and constraints | The description is effectively a mini system prompt for that one action | Malformed or hallucinated arguments; wrong-tool selection |
| Schema strictness — explicit types, enums, required fields | Removes ambiguity about what a valid call looks like before the model even reasons about it | Type errors, missing required fields, invalid enum values |
| Idempotency — documented and honest | Tells the model (and any retry logic) whether calling twice is safe | Duplicate side effects from a naive retry after a timeout |
| Side effects — clearly marked read vs write/delete | Lets permission layers and the model itself treat destructive calls with more caution | An auto-approved read-only policy accidentally covering a write tool |
| Error return shape — structured, legible, consistent | The model can only self-correct a failed call if the error tells it what was wrong | Blind retries with the same bad arguments, or the model giving up prematurely |
4.6 · Permissions & Side Effects
- Scope credentials behind an MCP server to the minimum the tools need — the server, not the model, should enforce the actual authorization boundary.
- Distinguish read-only tools (safe to auto-approve) from write/delete tools (candidates for a human-in-the-loop checkpoint, see §3.6).
- Hosts like Claude Code apply their own permission layer on top of whatever the server allows — a tool being exposed by a server does not mean it is automatically approved for use; see §5.5.
5 · Domain — Claude Code Configuration & Workflows D3 · 20%
Claude Code is Anthropic's agentic coding CLI: an agent loop wired directly into a developer's terminal and codebase, with tools for reading/editing files, running shell commands, searching, and calling out to MCP servers.
| Surface | What it is | When to reach for it | Tradeoff |
|---|---|---|---|
| CLI / core loop | The interactive (or non-interactive) terminal session itself, scoped to the working directory | Default entry point for any task in a real repo | Simplicity vs. no durable configuration unless paired with the surfaces below |
| Settings & permission modes | Project/user config controlling allowed tools, hooks, and how much autonomy the agent has | Whenever the default interactive-approval posture doesn't match the task's risk | Looser modes buy throughput, at the cost of oversight (§3.6) |
| Subagents | Separate agent instances with their own context/tools for a bounded subtask | A subtask (broad search, isolated exploration) would otherwise flood the main session's context | Cleaner main context vs. coordination/synthesis overhead |
| Hooks | Shell commands run automatically at defined agent-loop points | A policy must be enforced deterministically, not left to the model's judgment | Reliable enforcement vs. added configuration surface to maintain |
| Skills | Packaged instructions/scripts loaded on demand for a matching task | A specialized, recurring procedure should be codified once and reused, not re-explained | Keeps default context lean vs. another artifact to keep in sync with reality |
| MCP servers | External tools/resources connected in as Claude Code acts as an MCP host | The task needs capability beyond the built-in file/shell/search tools | Extends reach vs. an added trust/permission boundary to manage (§4.6) |
| Headless / CI use | Non-interactive invocation for scripted or pipeline use | The workflow should run unattended on a trigger (a PR, a schedule) | Automation at scale vs. no human in the loop unless hooks/gates are designed in (§1a scenario 5) |
5.1 · CLI & Core Workflow
- Runs interactively in a terminal (or non-interactively for scripting/CI), operating on the current working directory as its project scope.
- A project-level instructions file (conventionally
CLAUDE.md) gives Claude Code durable, repo-specific context — conventions, commands, architecture notes — read automatically at session start rather than repeated in every prompt. - Supports custom, reusable slash commands for repeatable workflows the team wants to standardize.
5.2 · Subagents
Claude Code can dispatch work to subagents: separate agent instances with their own context window and, optionally, a restricted tool set and system prompt, invoked for a bounded piece of work (e.g. a broad codebase search) so the exploration doesn't consume the main session's context. This is the concrete Claude Code instance of the orchestration pattern in §3.3.
5.3 · Hooks
Hooks are user-defined shell commands that run automatically at defined points in the agent loop — for example before a tool executes, after a tool executes, or when a session starts/ends — configured in settings. They let an architect enforce deterministic policy (block a dangerous command, auto-format edited files, log every tool call) around the model's otherwise probabilistic behavior, which the model itself cannot be relied on to always self-enforce.
5.4 · Skills
Skills are packaged, reusable sets of instructions (and optionally scripts/resources) that Claude Code loads on demand when a task matches what the skill covers, rather than keeping every possible instruction in context all the time. This keeps the default context lean while still letting an organization codify specialized procedures (a deploy runbook, a house code-review checklist) that Claude Code can invoke by name or by task match.
5.5 · Settings & Permission Modes
- Behavior is configured via settings files (project-level and user-level), covering allowed/denied tools, hook definitions, and other operating parameters.
- Permission modes control how much autonomy the agent has before it must stop and ask: interactive approval of each sensitive action by default, a plan mode that only researches and proposes without editing anything, a mode that auto-accepts file edits while still gating other sensitive actions, and a fully autonomous mode that skips prompts entirely — intended only for sandboxed/trusted/CI environments, not a default for unattended production use. This maps directly onto the "how much autonomy to grant" tradeoff in §2.
5.6 · MCP Integration
Claude Code acts as an MCP host: it can connect to external MCP servers (project-scoped or user-scoped configuration) to give the agent tools and resources beyond the built-in file/shell/search tools — the same MCP concepts from §4 apply directly, with Claude Code's own permission layer sitting on top of whatever the server exposes.
6 · Domain — Prompt Engineering & Structured Output D4 · 20%
An architect doesn't need to memorize every prompting trick, but needs to recognize which technique fits which problem and when prompting stops being the right lever at all.
The technique ladder
- Clear, direct instructions — state the task, the desired format, and the constraints explicitly rather than implying them; this alone fixes most prompt failures.
- System prompt for role & standing context — put stable context (persona, house rules, output format) in the system prompt rather than repeating it every turn.
- Examples (few-shot) — show the model 1–3 examples of input→output when the desired format or judgment is hard to describe in words alone.
- Chain-of-thought / extended thinking — ask the model to reason step by step, or enable extended thinking, for tasks with real reasoning difficulty; costs latency and tokens, so reserve it for tasks that need it.
- XML tags / structured prompt sections — separate instructions, context, and examples with clear delimiters so the model doesn't conflate them, especially in long prompts.
- Prefilling / constrained output — steer the exact start of the response, or use tool schemas to force structured output, when downstream code needs a guaranteed format.
Prompt vs fine-tune vs retrieval
Prompting (with good instructions/examples) is the cheapest, fastest lever and should be exhausted first. Retrieval (see §7.3) is the answer when the model needs facts it doesn't have and can't fit in context. Fine-tuning is the heaviest lever — reach for it only when prompting and retrieval both plateau and you have enough high-quality task-specific data to justify the cost and maintenance burden.
Technique-by-technique tradeoffs
| Technique | What it improves | Token cost | When it stops helping |
|---|---|---|---|
| System prompt | Stable persona/rules applied consistently without repeating them per turn | Fixed, once per request (cacheable, §7.2) | Once the persona/rules are already clear — stuffing more into it doesn't fix a task-specific ambiguity |
| Clear, direct instructions | Fixes the most common failure: the model doing a plausible but not-quite-asked-for thing | Low — a few sentences | Once the task and format are already unambiguous; more instructions add noise, not signal |
| Multishot examples | Communicates a format or judgment call that's hard to state in words | Medium — each example costs real tokens, every turn (unless cached) | Beyond 2–3 well-chosen examples, extra examples usually add cost without adding new signal |
| Chain of thought / extended thinking | Deliberate step-by-step reasoning on genuinely hard problems | High — thinking tokens plus longer responses | On tasks that don't need multi-step reasoning; it adds latency/cost with no accuracy gain there |
| XML structuring | Keeps instructions, context, and examples from bleeding into each other in a long prompt | Low — a handful of tags | Short, simple prompts with nothing to disambiguate don't need it |
| Prefilling | Forces the response to start in a specific format (e.g. skip a preamble, start valid JSON) | Negligible | Doesn't help when the problem is the content of the response, not its starting shape |
| Role prompting | Frames the lens the model reasons from (e.g. "as a security reviewer") | Negligible | Doesn't substitute for actually giving the model the domain facts it needs |
| Chaining (prompt chain) | Breaks a complex task into fixed stages, each independently checkable | Medium-high — multiple full turns instead of one | Overkill for a task that a single well-instructed prompt already handles reliably |
Forcing structured, parseable output
| Method | Reliability | Token cost | Typical failure mode |
|---|---|---|---|
| Prefilling the response start | Moderate — steers the opening but not the whole body | Negligible | Model drifts out of the intended shape later in a long response |
| XML-tag wrapping | Moderate — easy for a human/parser to locate, but the model can still emit malformed content inside the tags | Low | Unescaped special characters, or the model breaking out of the tag structure under pressure |
| Tool-use as schema | Highest — the response is (or is guided toward) a structured tool call validated against a JSON schema | Medium — full tool definition plus schema counted every call unless cached | Schema itself is too loose (missing required/enum constraints), so "valid" output is still wrong |
| Post-hoc validation | Backstop, not a guarantee — depends entirely on how good the validator is | Extra call/step cost for the validation pass itself | Validator catches malformed output but the pipeline still needs a retry/repair path for failures |
7 · Domain — Context Management & Reliability D5 · 15%
7.1 · Context Window Budget
Everything sent to the model on a turn shares one finite context window: the system prompt, tool definitions (every tool's name/description/schema costs tokens whether or not it's called), the conversation history, any retrieved documents, and prior tool results. As history and tool output accumulate, older or less relevant content crowds out useful signal — even well before hitting the hard token limit, quality can degrade as the window fills (see "context rot", §3.8). Budget the window deliberately: trim stale tool output, summarize long histories, and keep the tool set scoped to what the current task actually needs.
| What consumes context | Lever to control it |
|---|---|
| System prompt | Keep it stable and lean; put it first so it's cacheable (§7.2) since it repeats every request |
| Tool definitions | Scope the tool set to what the current task needs — every defined tool costs tokens whether or not it's called (§4.5) |
| Conversation history | Compact/summarize long-running sessions (§7.4); cap turns where the task allows it |
| Retrieved chunks | Tighten retrieval so only genuinely relevant chunks are attached (§7.3) |
| Tool results | Trim or discard stale results once superseded; route large exploratory output through a subagent instead of the main context (§3.3) |
| Extended thinking | Reserve for tasks that need deliberate reasoning — it adds thinking tokens on top of the response (§3.1) |
Context strategies at a glance
| Strategy | Cost | Latency | Fidelity loss | When to pick |
|---|---|---|---|---|
| Stuff the window | Grows with content size, on every request | Higher — more input tokens to process each time | None directly, but quality can still degrade as the window fills (context rot) | Content is small/bounded and reused often (pairs well with caching) |
| Retrieve | Pay for retrieval infrastructure plus only the tokens actually fetched | An extra retrieval round trip, but a smaller final prompt | The retriever can miss or mis-rank relevant content | Corpus is large, changes often, or won't fit any context window |
| Summarize / compact | One extra summarization pass, then a smaller ongoing prompt | Adds a summarization step but shrinks every request after it | Drops raw detail — anything not captured in the summary is gone | Long-running sessions that exceed any single window (§7.4) |
| Offload to files | Cheap to write/read; no extra model call needed | Minimal — a file read/write, not a model round trip | None, as long as the agent reliably re-reads what it wrote | State needs to survive a context reset or span multiple sessions (§3.4) |
| Cache | Full price once, discounted on cache hits | Lower on cache hits — skips reprocessing the cached prefix | None — the cached content is unchanged, just not reprocessed | The same stable prefix is reused across requests faster than the cache expires (§7.2) |
7.2 · Prompt Caching
- Prompt caching lets you mark a prefix of the request (system prompt, tool definitions, a large document) as reusable, so subsequent requests that share that exact prefix skip reprocessing it — cutting both latency and cost on the cached portion.
- Best fit: long, stable content reused across many requests in a short window — a large system prompt, a fixed tool set, a document the user asks multiple questions about, an agent's accumulating-but-shared conversation prefix.
- Cache entries expire after a period of inactivity (on the order of minutes by default, with longer-TTL options available) — caching only pays off when requests against the same prefix happen faster than the cache expires.
- Put the stable, shared content first and the variable, per-request content last, since caching works on a matching prefix — reordering a prompt so volatile content comes early defeats the cache.
| Cacheable content | Ordering rule | Pays off when… |
|---|---|---|
| System prompt | Placed first, ahead of any per-request content | The same system prompt is sent on every request in a session or workflow |
| Tool definitions | Placed with/after the system prompt, still ahead of variable content | The tool set doesn't change between requests |
| Large reference documents | Placed after tools/system prompt, before the per-turn question | Many questions get asked against the same document in a short window |
| Growing conversation prefix | Earlier turns stay in their original order as new turns are appended | A multi-turn agent session reuses its own accumulated history turn after turn |
Caching does not pay off when the shared prefix is small, when requests against it are infrequent enough to fall outside the cache's inactivity window, or when the "stable" content actually changes almost every request — in those cases, shortening the prompt outright beats trying to cache it (§9).
7.3 · Retrieval vs Long Context
| Long context (stuff it all in) | Retrieval (fetch on demand) | |
|---|---|---|
| Simplicity | Simple — no separate index/pipeline | More moving parts — an index, a retriever, ranking |
| Cost at scale | Grows with corpus size; pay to re-send unused content every turn (mitigated by caching) | Pay only for what's fetched, but pay for the retrieval infrastructure |
| Freshness | Requires re-sending the corpus to update it | Index can be updated independently of any given request |
| Precision | Model must find the needle in a large haystack itself | Retriever pre-filters to relevant content, but can miss or mis-rank |
| Good fit | Small-to-medium, bounded corpora reused often (pairs well with caching) | Large or frequently changing corpora, or corpora too big to fit any context window |
7.4 · Context Editing & Compaction
- Context editing is the practice of programmatically trimming or clearing stale content from a long-running agent's context as it works — for example, clearing old tool results once they're no longer needed, so the window stays usable across a long session instead of silently degrading.
- Compaction / summarization replaces a long history with a condensed summary that preserves the decisions and facts that matter while dropping the raw back-and-forth that led there — necessary for agent sessions that run far longer than any single context window.
- An architect should decide, per agent, what must survive verbatim (key decisions, unresolved questions, user-provided constraints) versus what can be safely summarized or dropped (superseded tool output, exploratory dead ends).
8 · The Claude API Reference
A surface an architect must be able to recognize and choose between, not necessarily implement from memory.
| Surface | What it's for |
|---|---|
| Messages | The core request/response endpoint — an array of user/assistant turns, each made of content blocks (text, images, tool_use, tool_result, documents). |
| System prompt | Top-level, standing instructions/persona/context separate from the message turns — the right place for anything true across the whole conversation. |
| Tool use | Define tools (name, description, JSON schema); the model emits tool_use blocks to request calls, you return tool_result blocks with outcomes. |
| Streaming | Server-sent events deliver the response incrementally as it's generated — improves perceived latency for user-facing surfaces; doesn't change total cost or total generation time. |
| Structured output | Constrain the response to a schema — typically via a tool definition the model is forced/guided to "call" with structured arguments — when downstream code needs guaranteed-parseable output. |
| Prompt caching | Mark a stable prefix as cacheable to cut cost/latency on repeated large context (§7.2). |
| Batch processing | Submit many requests for asynchronous, non-urgent processing at a discount versus synchronous calls — trades latency guarantees for cost. |
| Files | Upload files once and reference them by ID across multiple requests, instead of re-sending large content inline every call. |
| Citations | Ground responses in supplied source documents, returning references back to the specific passages used — reduces ungrounded claims, aids verification. |
| Token counting | Count tokens for a given request before sending it, to budget context and cost ahead of time. |
| Stop reasons | Why generation ended — natural completion, hitting a max-token limit, hitting a stop sequence, or requesting a tool call — the caller must branch on this to drive the agent loop correctly. |
Model families — choosing on cost, latency, capability
Claude is offered in a small number of model tiers that trade off capability against cost and latency, refreshed periodically as new generations ship:
| Tier | Typical fit |
|---|---|
| Opus | Highest capability, highest cost/latency — reserve for the hardest reasoning, planning, and orchestration tasks (e.g. a lead agent coordinating subagents). |
| Sonnet | Balanced capability/cost/latency — the default workhorse for most agentic and API tasks, including most subagents. |
| Haiku | Fastest and cheapest — high-volume, low-complexity tasks (classification, extraction, simple tool calls) where speed and cost dominate. |
9 · Decision Guides
Prompt vs tool use vs agent vs multi-agent
| Signal in the scenario | Choose |
|---|---|
| Everything needed is already in the input; one clean pass suffices | Single prompt |
| Needs live data or an action outside the model's knowledge, but it's a bounded, single-purpose task | Tool-using agent (single agent, loop) |
| Task decomposes into independent subtasks needing separate context/tools, or benefits from parallelism | Multi-agent system |
| Task is high-volume, simple, and cost-sensitive | Prompt (or agent) on a cheaper model tier |
Claude Code vs Agent SDK vs raw API
| Signal | Choose |
|---|---|
| Developer wants an interactive coding assistant in their terminal against a real repo, today, with minimal setup | Claude Code |
| Team is building a custom product/UI around an agent and needs full control of the loop, but doesn't want to hand-roll it | Claude Agent SDK |
| Need is a single simple call, or requirements are so custom that even the SDK's opinions get in the way | Raw API |
MCP server vs direct API integration
| Signal | Choose |
|---|---|
| Multiple hosts/clients need the same tool/data access, or a ready-made server for the target system already exists | MCP server |
| One-off, single-application integration with no reuse need | Direct API integration (define the tool inline) |
Three-way: MCP server vs direct API tool definition vs built-in tool
| MCP server | Direct API tool definition | Built-in tool (e.g. Claude Code's file/shell tools) | |
|---|---|---|---|
| Setup cost | Write/host a server once; every client reuses it | Define the tool inline per application; no separate service to run | Zero — already provided by the host |
| Reuse across hosts/clients | High — any MCP-speaking host can connect | None — tied to the one integration that defined it | N/A — tied to that specific host |
| Auth / authorization boundary | Server enforces its own scoped authorization, independent of the calling model | Whatever the calling application implements itself | The host's own built-in permission layer |
| When to pick | Multiple hosts/apps need the same capability, or a ready-made server exists | A one-off, single-application need with no reuse requirement | The capability is already covered natively — no need to reinvent it |
Caching vs shorter prompts vs retrieval
| Signal | Choose |
|---|---|
| Same large context reused across many requests in a short window | Prompt caching |
| Context is mostly unnecessary padding | Shorten the prompt (fix before reaching for infrastructure) |
| Corpus is large, changes often, or won't fit any context window | Retrieval |
Sync vs streaming vs batch
| Signal | Choose |
|---|---|
| Interactive user waiting on a response | Streaming (best perceived latency) |
| Programmatic call, single short-lived request, no user watching it stream | Synchronous (non-streaming) |
| Large volume of non-urgent requests, cost-sensitive | Batch |
Single long context vs retrieval
See the full comparison table in §7.3.
10 · Safety, Governance & Operations
- Guardrails — input classification, tool-level constraints (schema validation, allow-lists), and output validation, layered rather than relied on singly (§3.7).
- Evaluation & testing — held-out eval sets run on every prompt/tool/model change; staged rollouts before full production traffic.
- Observability — log every tool call, its arguments, and its result; trace multi-step/multi-agent runs end to end so failures are diagnosable after the fact, not just in the moment.
- Cost control — per-task token/turn budgets, model-tier mixing (§8), caching (§7.2), batch for non-urgent volume (§8), and alerting on anomalous spend.
- Rate limits & retries — respect rate-limit signals from the API, back off exponentially on 429/5xx, and cap total retries per request (§3.5).
- PII handling — minimize what's sent to the model in the first place, redact or tokenize sensitive fields where the task doesn't need them in the clear, and treat prompts/logs containing PII with the same handling rigor as any other system touching that data.
- Human oversight — checkpoints on high-blast-radius actions (§3.6), least-privilege tool/credential scoping (§4.6), and a clear escalation path when an agent gets stuck or produces low-confidence output.
Reliability, end to end
| Concern | Technique | Cost |
|---|---|---|
| Transient failures | Retry with exponential backoff on rate limits and server errors (§3.5) | Added latency on the failing path, bounded by a retry cap |
| Duplicate side effects on retry | Idempotent tool design, so a safe retry can't double-execute an action (§4.5) | Extra design/implementation effort per tool |
| Hung calls | Timeouts on every tool call and on the overall task | Risk of cutting off a call that would have eventually succeeded |
| Partial task failure | Persist per-step state and resume from the last known-good step rather than restarting (§3.4) | State-tracking infrastructure to build and keep consistent |
| Silent quality regressions | Evaluation and regression testing on every prompt/tool/model change (§3.7) | Maintaining a representative eval set over time |
| Diagnosing failures after the fact | Observability — log every tool call, argument, and result; trace multi-step runs end to end | Logging/storage overhead, plus the discipline to actually review it |
11 · Study Materials
This exam is new enough that there is no established third-party ecosystem of trustworthy prep courses or question banks yet — be skeptical of anything claiming to be a comprehensive "dump" for it.
- Anthropic's public documentation (
docs.claude.com) — the API reference, Agent SDK guide, and Claude Code documentation are the primary, authoritative technical source for everything in Domains 1–3, 5 and §8. - The Anthropic Academy courses on the partner academy platform (
anthropic-partners.skilljar.com) — the source of the exam itself; check there first for an official study track or practice questions once you have access. - The official MCP specification (
modelcontextprotocol.io) — primary source for Domain 2; read the spec directly rather than secondhand summaries, since MCP is still evolving. - Hands-on building — genuinely the highest-value "material" for this exam given its explicit focus on real-world tradeoff decisions: build a small tool-using agent against the raw API, write a real MCP server, and use Claude Code on a real repository (subagents, hooks, skills, permission modes).
12 · Study Plan
About 3 weeks for someone comfortable writing code who has not yet built agentic systems specifically; compress if you already have production Claude experience. Each week ends by doing, not by finishing reading.
| Phase | Focus | Actions (learn → retrieve → apply) |
|---|---|---|
| Week 1 API & agent loop | Messages, tool use, streaming, model tiers | Learn: read the Messages API, tool-use, and streaming docs. Apply: build a minimal tool-using agent loop by hand (no framework) with one real tool and explicit retry/step limits. Retrieve: explain the loop out loud without notes. |
| Week 2 MCP & Claude Code | MCP primitives/transports, Claude Code features | Learn: read the MCP spec and Claude Code docs. Apply: write a real MCP server (stdio) with a tool and a resource; connect it to Claude Code; try plan mode, a subagent, and a hook on a real repo. Retrieve: write the tools/resources/prompts distinction from memory. |
| Week 3 Context, tradeoffs, drill | Caching, retrieval, decision tables, scenarios | Learn: prompt caching and context management docs. Retrieve: redo the decision tables (§9) from a blank page. Apply: work through the worked scenario questions (§15), review the glossary, and re-check every number in §1 against the official Exam Guide if you can reach it. |
13 · Exam-Day Tips & Common Traps
Closed-book & proctoring
- Delivery per the official Exam Guide is proctored — online proctored and/or test center, per program policy, and is expected to be closed book: no Claude, no documentation, no browser tabs, no external tools during the session.
- Set up your test space in advance per whatever the proctoring option you're assigned requires: quiet room, ID ready, nothing else on screen.
Technique
- Identify what the scenario is optimizing for — cost, latency, accuracy, autonomy/safety, or simplicity. Most "best answer" scenario questions turn on which of these the last sentence is actually asking you to prioritize.
- Default to the simplest architecture that satisfies the requirement — the exam's tradeoff framing punishes over-engineering (multi-agent when one agent would do) just as much as under-engineering.
- 60 items across 4 scenarios averages to about 15 items per scenario — the guide doesn't state a fixed per-scenario count, but budget your time per scenario rather than per question so one hard scenario doesn't eat time from the other three.
Recurring traps
- Tools vs resources vs prompts — mixing up which primitive is model-controlled vs application-controlled vs user-controlled (§4.3).
- Long context vs retrieval — picking long context for a large/changing corpus, or retrieval for a small stable one reused often (which caching already handles better, §7.3).
- Multi-agent as a default — reaching for multiple agents when a single agent with better tools/prompting would do (§2, §3.3).
- Ungated autonomy — an agent scenario that omits a human checkpoint before an irreversible action is usually the wrong answer, not an oversight (§3.6).
- Caching vs shortening — reaching for prompt caching when the actual problem is just a bloated prompt that should be shortened first (§7.2, §9).
14 · Glossary
| Term | Definition |
|---|---|
| Agent | A model that plans, calls tools, and acts iteratively toward a goal, rather than answering in a single pass. |
| Agent loop | Gather context → take action → verify → repeat, until a stop condition is met. |
| Agent SDK | Anthropic's SDK for building custom agent applications on top of the agent loop, tool use, and (optionally) subagents/permissions. |
| Claude Code | Anthropic's agentic coding CLI, an MCP host with built-in file/shell/search tools, subagents, hooks, and skills. |
| Compaction | Summarizing/condensing a long agent history to fit within context while preserving what matters. |
| Context editing | Programmatically trimming or clearing stale context (e.g. old tool results) during a long-running agent session. |
| Context window | The finite token budget shared by system prompt, tools, history, and retrieved/attached content on a given request. |
| Extended thinking | A mode where the model reasons step by step before producing its final response, trading latency/tokens for better performance on hard tasks. |
| Guardrail | A runtime constraint (input, tool-level, or output) that prevents a specific bad outcome, distinct from evaluation. |
| Hook | A Claude Code (or Agent SDK) mechanism for running deterministic code at defined points in the agent loop. |
| Host | The MCP-terminology AI application (e.g. Claude Code) that manages the session and connects to MCP servers via clients. |
| MCP | Model Context Protocol — the open protocol standardizing how AI applications connect to tools, data, and prompts. |
| Multi-agent system | An architecture with two or more cooperating agent instances, typically an orchestrator plus subagents. |
| Permission mode | The setting controlling how much autonomy an agent (e.g. Claude Code) has before it must stop and request approval. |
| Prompt caching | Marking a stable request prefix as reusable so repeat requests against it skip reprocessing, cutting cost and latency. |
| Resource (MCP) | Application-controlled, addressable, typically read-only data an MCP server exposes. |
| Sampling (MCP) | A server-initiated request for a completion from the client's model. |
| Skill | A packaged, reusable set of instructions/resources Claude Code loads on demand for a matching task. |
| Stop reason | The API field indicating why generation ended (natural completion, max tokens, stop sequence, tool call). |
| Structured output | Constraining a response to a defined schema, typically via a forced/guided tool call. |
| Subagent | A separate agent instance with its own context window, dispatched by an orchestrating agent for a bounded subtask. |
| System prompt | Top-level standing instructions/context distinct from the per-turn message history. |
| Tool (MCP / API) | A model-invocable, executable function with a name, description, and input schema. |
| Transport (MCP) | The mechanism carrying MCP protocol messages between client and server — stdio (local subprocess) or Streamable HTTP (remote). |
15 · Worked Example Questions
Scenario-style, matching the reported format: a short business situation, four options, one best answer, and a reason every distractor is wrong. These are original practice items written for this guide, not real or leaked exam content.
A support team wants Claude to answer customer questions using their 40-page product manual. The manual changes monthly. Questions are simple lookups; the manual fits comfortably in a single request's context window.
Best answer: Send the manual as part of the prompt with a prompt-caching breakpoint, refreshed after each monthly update.
Why the others are wrong: A full retrieval pipeline is unnecessary machinery for a small, bounded, infrequently-changing document — it adds cost and complexity retrieval doesn't pay for here. A tool-using agent that fetches the manual per question adds a needless round trip for content that's already small enough to keep resident. Fine-tuning on the manual is the heaviest, least appropriate lever for content that changes monthly and can just be re-sent.
An internal agent is being built to triage and close low-priority IT tickets automatically, including deleting stale tickets older than 90 days.
Best answer: Auto-approve read/triage actions, but require a human-in-the-loop checkpoint before any delete action executes.
Why the others are wrong: Full autonomy on deletes risks irreversible data loss from a misjudgment the agent can't undo. Requiring approval on every single action (including read-only triage) defeats the automation goal the project exists for. Disabling the delete capability entirely under-delivers on a legitimate, bounded requirement instead of gating it appropriately.
A team is building an internal tool that lets any of five different in-house apps query a shared inventory database through Claude. They expect to add more consuming apps later.
Best answer: Build one MCP server exposing the inventory tools, and connect each app to it as an MCP client.
Why the others are wrong: Writing a separate direct API integration per app duplicates the same tool logic five times and again for every future app — exactly the N×M integration problem MCP exists to avoid. Giving each app raw database credentials skips any shared authorization/audit layer and multiplies the attack surface. A single monolithic agent that all five apps share removes each app's ability to scope its own context and permissions independently.
A coding agent has been running unattended on a large refactor for two hours. Its recent responses have started making inconsistent decisions that contradict choices it made an hour earlier.
Best answer: The context window has filled with accumulated tool output; compact/summarize the history and re-ground the agent on its key prior decisions.
Why the others are wrong: Switching to a larger/more capable model doesn't fix a context that has decayed in relevance — it delays the same problem. Restarting the agent from scratch discards the two hours of legitimate progress along with the noise. Adding more detailed instructions doesn't address a context-capacity problem; the model isn't confused about what to do, it has lost track of what it already decided.
A batch job needs to classify 2 million support tickets by category overnight, with no user waiting on any individual result.
Best answer: Use the batch processing API on a fast, low-cost model tier.
Why the others are wrong: Streaming optimizes perceived latency for a live viewer, which doesn't exist in this scenario — it adds complexity with no benefit. Synchronous calls at this volume needlessly pay full real-time pricing and hold open connections for no reason. Using the most capable (highest-cost) model tier for a simple classification task ignores the cost/capability tradeoff for no accuracy the task requires.
An architect is designing a tool that lets an agent send a marketing email to a customer list. Some team members want it fully automatic; others are nervous about mistakes.
Best answer: Give the agent a "draft email" tool the model can call freely, but require explicit human approval before the "send email" tool executes.
Why the others are wrong: One combined "draft and send" tool removes any checkpoint before an irreversible, externally visible action. Making the whole workflow manual (no drafting tool at all) throws away the legitimate value of automating the low-risk drafting step. Approving sends in a weekly batch review introduces unacceptable delay for what should be a near-real-time send, without changing that some individual send should still need explicit sign-off.
Developers keep re-explaining the same repo conventions (test commands, folder layout, style rules) to Claude Code at the start of every session.
Best answer: Add a project instructions file (e.g. CLAUDE.md) to the repo root so those conventions load automatically every session.
Why the others are wrong: Pasting the same conventions into every prompt is exactly the repeated manual work the team wants to eliminate. Writing a custom MCP server to serve the conventions as a resource is far more machinery than the problem needs when a simple project file solves it directly. Relying on developers to remember and retype the conventions consistently is the status quo that's already failing.
A single agent is responsible for both researching a topic across dozens of web pages and writing a polished final report. The research phase is consuming most of the context window before writing even starts.
Best answer: Dispatch a research subagent to gather and condense findings, and have the orchestrating agent write the report from that condensed output.
Why the others are wrong: Increasing the context window limit (where possible) treats the symptom, not the cause — unfiltered research content would still crowd out the writing task's own reasoning. Running research and writing as one continuous pass is the current failing approach, not a fix. Splitting into two entirely separate, uncoordinated sessions loses the handoff of findings the report actually depends on.
A new MCP tool description reads: "handles orders". Since deployment, the model has been calling it with malformed or missing arguments.
Best answer: Rewrite the tool's description and parameter schema to be explicit about what the tool does, its required arguments, types, and constraints.
Why the others are wrong: Switching to a more capable model may reduce, but doesn't fix, an underlying schema problem — it's treating a documentation defect as a capability defect. Removing the tool eliminates the malfunction by eliminating the needed functionality. Adding a retry loop around bad calls papers over root cause and still burns turns on calls that were never going to succeed with vague inputs to work from.
A company wants to add Claude-powered search over a rapidly growing, multi-terabyte document archive that changes throughout the day.
Best answer: Build a retrieval pipeline (index the archive, retrieve relevant chunks per query) rather than passing the archive into context.
Why the others are wrong: The archive is far larger than any context window and changes too often for prompt caching to help meaningfully. Long-context stuffing doesn't scale to multi-terabyte, frequently-changing corpora regardless of a given model's maximum window. Fine-tuning the model on the archive would need constant retraining to track a corpus that changes throughout the day, and still wouldn't let the model cite or verify specific current documents the way retrieval can.
An agent occasionally states a specific dollar figure from a financial report as fact, but the figure turns out to be fabricated rather than pulled from the actual document provided.
Best answer: Require citations grounding factual claims in the supplied source document, and treat ungrounded claims as failures the agent should flag rather than assert.
Why the others are wrong: A longer, more emphatic instruction to "be accurate" doesn't give the model a mechanism to verify a specific number against source text. Increasing extended-thinking budget improves reasoning depth but doesn't by itself ground a factual claim in a specific document passage. Switching to a larger model reduces but does not eliminate the risk of an ungrounded claim when no grounding/verification mechanism exists at all.