CCA Foundations
Exam Portal
Everything you need to pass the Claude Certified Architect — Foundations exam — fully integrated in a single file. Reference guides, anti-patterns, FAQ, four quiz formats, flashcards, decision trees, and a study plan.
6 Scenario
Deep Drill
10 questions per scenario — all 3 question types — with full explanations. Choose which scenarios to practice, pick your difficulty, and go.
COMMON
MISTAKES
DRILL
5 mistake patterns. 10 trap questions each.
Every question is engineered to lure you into the wrong answer.
Master these and the exam's hardest distractors won't fool you.
CCA Flashcards
Use these to work through the most common judgment calls on the exam. Each tree maps a diagnostic question to the correct answer strategy.
Every API concept, value, and flag you need to know for the exam.
tool_useExecute tool → continue loopend_turnModel finished → terminatemax_tokensToken limit hit → handlestop_sequenceCustom stop string hit"auto"May return text (not guaranteed tool call)"any"Must call some tool{type:"tool",name:"X"}Must call tool X specifically| Property | Value | Implication |
|---|---|---|
| Cost | 50% savings | Half the price of real-time API |
| Latency SLA | None | Up to 24h — never use for blocking workflows |
| Multi-turn tool calling | Not supported | Cannot execute tools mid-request and return results |
| Request correlation | custom_id | Required to match responses to requests |
| Failure handling | By custom_id | Resubmit only failed items, not whole batch |
| Best for | Overnight / weekly jobs | Reports, audits, nightly test generation |
| Never for | Pre-merge CI checks | Developers are blocked waiting for results |
| Pattern | When to Use | Example |
|---|---|---|
| nullable / optional field | Information may not exist in source | discount: null | number |
| enum + "other" + detail | Fixed categories but extensible | type: "refund"|"other", type_detail: string |
| calculated vs stated | Semantic validation (math checks) | calculated_total, stated_total, discrepancy_flag |
| confidence scores | Human review routing | field_confidence: 0.0–1.0 |
| claim-source mapping | Provenance in multi-source synthesis | claim, source_url, excerpt, date |
| Field | Type | Values / Notes |
|---|---|---|
isError | boolean | true for all error conditions |
errorCategory | string enum | transient | validation | business | permission |
isRetryable | boolean | true only for transient; false for all others |
message | string | Human-readable description for agent/user |
| valid empty result | — | Return isError: false, data: [] — NOT an error |
Every config file, directory, and flag — location, scope, and purpose.
| Location | Scope | Shared via VCS? | Use For |
|---|---|---|---|
~/.claude/CLAUDE.md | User-level | No | Personal preferences, personal tools |
.claude/CLAUDE.md or root CLAUDE.md | Project-level | Yes | Team standards, project conventions |
Subdirectory CLAUDE.md | Directory-level | Yes | Module-specific rules |
.claude/rules/*.md with glob frontmatter | File-pattern | Yes | Conventions for scattered files (e.g., all tests) |
| Location | Scope | Use For |
|---|---|---|
.claude/commands/ | Project-shared | Team-wide slash commands (auto-available on clone) |
~/.claude/commands/ | Personal | Personal slash commands not shared |
.claude/skills/name/SKILL.md | Project-shared | On-demand skills with frontmatter config |
~/.claude/skills/ | Personal | Personal skill variants (won't affect teammates) |
| Option | Purpose | When to Use |
|---|---|---|
context: fork | Run in isolated sub-agent context | Verbose skills (codebase analysis, brainstorming) that would pollute main session |
allowed-tools: [...] | Restrict tool access during skill | Prevent destructive actions (e.g., limit to file writes only) |
argument-hint: "..." | Prompt for required params on invocation | Skills that require a target file, component name, etc. |
| Flag | Purpose | Required For |
|---|---|---|
-p / --print | Non-interactive mode | All CI/CD pipeline invocations |
--output-format json | JSON output | Machine-parseable CI results |
--json-schema | Enforce output schema | Inline PR comment automation |
--resume <name> | Continue named session | Multi-session investigations |
/compact | Reduce context usage | Long exploration sessions nearing token limit |
/memory | View loaded memory files | Diagnosing inconsistent behavior across sessions |
| File | Scope | Credential Handling |
|---|---|---|
.mcp.json (project root) | All team members | Use ${ENV_VAR} expansion — never hard-code |
~/.claude.json | Current user only | Personal tokens, experimental servers |
What each scenario tests and the key traps in each. Study these patterns — exam questions are drawn directly from these scenarios.
| Key Concept | Watch For |
|---|---|
| Tool ordering enforcement | Programmatic prerequisite, NOT prompt instruction |
| Tool description quality | Expand descriptions — don't merge tools as first fix |
| Escalation triggers | Explicit request = immediate escalation, no resolution attempt |
| Multiple customer matches | Ask for more identifiers — never guess by heuristic |
| Escalation calibration | Few-shot examples fix this — not confidence scores or sentiment |
| Key Concept | Watch For |
|---|---|
| Shared vs personal commands | .claude/commands/ = shared; ~/.claude/commands/ = personal |
| Plan mode triggers | Monolith → microservices always = plan mode |
| Path-specific rules | Glob patterns for scattered test files, not subdirectory CLAUDE.md |
| CLAUDE.md new-dev issue | If new dev doesn't get instructions → user-level not project-level |
| Key Concept | Watch For |
|---|---|
| Task decomposition scope | Coverage gaps = coordinator decomposed too narrowly |
| Error propagation | Structured context → coordinator; not generic string, not empty success |
| Parallel execution | Multiple Task calls in ONE response turn — not multiple turns |
| Synthesis tool access | Scoped verify_fact tool for 85% simple case; complex = coordinator |
| Conflicting sources | Annotate both with attribution — don't pick, don't average |
| Key Concept | Watch For |
|---|---|
| Grep vs Glob | Grep = file contents; Glob = file paths — don't swap them |
| Edit fallback | Non-unique anchor → Read + Write (not retry Edit) |
| Context degradation | Scratchpad files to persist findings, not larger model |
| MCP server scope | Team server in .mcp.json; personal in ~/.claude.json |
| Key Concept | Watch For |
|---|---|
| Non-interactive mode | -p flag — not CLAUDE_HEADLESS, not --batch, not stdin redirect |
| Batch API decision | Pre-merge = real-time (blocking); overnight reports = batch |
| Multi-file review | Per-file passes + integration pass — not bigger context window |
| False positive reduction | Explicit categorical criteria — not "be conservative" |
| Independent review | New instance for review — not same session that generated code |
| Key Concept | Watch For |
|---|---|
| Schema design | Optional fields → nullable, not required (prevents hallucination) |
| Syntax vs semantic errors | tool_use fixes syntax; validation pass fixes semantic |
| Retry limits | Absent data can't be retried into existence |
| Aggregate accuracy | 97% overall ≠ safe to automate — check per-type and per-field |
| Few-shot for extraction | Varied document structures need examples, not just instructions |
The distractors that catch unprepared candidates — and exactly why they're wrong.
| Fake Option | Why It Appears | Correct Alternative |
|---|---|---|
CLAUDE_HEADLESS=true | Sounds like a reasonable env var | -p / --print flag |
--batch flag | Sounds like batch processing mode | Message Batches API (separate endpoint) |
required: true in tool_choice | Sounds like it forces tool usage | tool_choice: "any" |
.claude/config.json commands array | Sounds like a config file | .claude/commands/ directory |
parallel: true in AgentDefinition | Sounds like parallelism config | Multiple Task calls in one response |
| Distractor | Why It's Wrong | Correct First Step |
|---|---|---|
| Deploy a separate routing classifier model | Requires ML infra; prompt hasn't been tried yet | Improve tool descriptions |
| Build a keyword-based pre-turn selector | Bypasses LLM's natural language understanding | Improve tool descriptions |
| Consolidate tools into one mega-tool | More effort than needed; loses specificity | Differentiate descriptions first |
| Add 3rd independent review model | Infrastructure overkill; prompt fix first | Explicit categorical criteria |
| Trap Answer | Why Wrong | Correct Answer |
|---|---|---|
| "Add system prompt: customer verification is mandatory" | Probabilistic — LLMs have non-zero failure rate for compliance | Programmatic prerequisite gate |
| "Add few-shot showing get_customer first" | Still probabilistic for critical financial operations | Programmatic prerequisite gate |
| "Instruct Claude: do not fabricate field values" | Prompt instructions are weaker than schema constraints | Make fields nullable in JSON schema |
| "Set tool_choice: auto for guaranteed output" | auto allows text responses; not guaranteed tool call | tool_choice: "any" |
| Concept A | vs | Concept B | Key Difference |
|---|---|---|---|
~/.claude/CLAUDE.md (user) | vs | .claude/CLAUDE.md (project) | User = personal, not shared. Project = version-controlled, shared. |
| Syntax error (malformed JSON) | vs | Semantic error (values don't add up) | tool_use fixes syntax; validation pass fixes semantic. |
| Access failure (tool couldn't run) | vs | Valid empty result (ran, found nothing) | Access = isError:true. Empty = isError:false, data:[]. |
| fork_session (branch exploration) | vs | --resume (continue session) | fork = divergent approaches. resume = continue same thread. |
| Grep (search file contents) | vs | Glob (match file paths) | Grep = what's inside files. Glob = file names/locations. |
| context: fork (skill isolation) | vs | CLAUDE.md (always-loaded) | Skills = on-demand. CLAUDE.md = loaded every session. |
- Read the scenario context first — it anchors which domain and tradeoffs are being tested
- Look for the root cause in the question stem before scanning options
- Prefer programmatic enforcement over prompt instructions when deterministic compliance is required
- Choose proportionate first responses — the simplest solution that solves the stated problem
- Guess if unsure — there is no penalty for wrong answers
- When two options seem correct, pick the one that addresses the root cause, not a symptom
- Treat "prompt-based solutions" as weaker than "schema/code-based solutions" for reliability questions
- Know the exact API vocabulary:
stop_reason,tool_use,end_turn,isRetryable,tool_choice - For escalation questions: customer explicitly requests human → escalate immediately, no resolution attempt
- For batch API questions: always ask "is this workflow blocking?" — if yes, batch is wrong
- Choose answers that involve over-engineering (separate classifier models, keyword pre-selectors) before simpler fixes
- Assume "add more instructions to the system prompt" is the answer for deterministic compliance needs
- Conflate
tool_choice: "auto"with guaranteed tool execution — auto allows text-only responses - Choose Batch API when any person/process is waiting on the result — it has no latency SLA
- Use sentiment analysis or confidence thresholds to decide escalation — explicit request overrides everything
- Pick answers that reference non-existent features:
CLAUDE_HEADLESS,--batchflag,parallel: true - Treat "97% overall accuracy" as sufficient — always check per-type and per-field breakdown
- Swap Grep and Glob — Grep searches file contents, Glob matches file paths
Building production-grade agentic loops, multi-agent orchestration, and session management.
- Use
stop_reasonas your only loop termination signal — it's the authoritative API signal - Implement programmatic prerequisite gates for tool ordering (e.g., block
process_refunduntilget_customersucceeds) - Use
PreToolUse/PostToolUsehooks for cross-cutting concerns (logging, validation, enforcement) - Pass full structured context when spawning subagents — they don't inherit coordinator memory automatically
- Launch multiple Task tool calls in a single response turn for true parallelism
- Use
fork_sessionfor divergent exploration;--resumeto continue the same thread - Scope subagent tool access to only what that agent needs — principle of least privilege
- Parse assistant message text for "task complete" to decide loop termination — brittle and unreliable
- Use arbitrary iteration caps as your primary stop mechanism — they cause premature termination
- Rely on system prompt instructions for tool ordering when financial/legal consequences exist — use programmatic gates
- Assume subagents automatically have coordinator context — always pass it explicitly
- Use multiple sequential turns to launch "parallel" tasks — this is sequential, not parallel
- Give all subagents access to all tools — creates security risk and over-complex error paths
Designing effective tool interfaces, error responses, and MCP server configuration.
- Write tool descriptions that include input formats, example queries, edge cases, and when to use this vs. similar tools
- Return structured error objects with
errorCategoryandisRetryable— not bare error strings - Return
isError: false, data: []for valid empty results — distinguish "not found" from "tool failed" - Store team MCP servers in
.mcp.jsonwith${ENV_VAR}credential expansion - Use
tool_choice: "any"when you need guaranteed tool execution - Keep per-tool tool descriptions distinct — the model uses them for selection; ambiguity causes wrong-tool calls
- Merge two similar tools into one "mega-tool" as your first fix for wrong-tool selection — improve descriptions first
- Return bare error strings from MCP tools — the agent can't determine if it should retry
- Treat an empty result as an error —
data: []withisError: falseis a valid success response - Hard-code credentials in
.mcp.json— use environment variable expansion - Use
tool_choice: "auto"when tool execution is required — auto allows text-only responses - Deploy a pre-turn keyword classifier to route tool selection — use better descriptions instead
Few-shot design, JSON schemas, validation loops, CI/CD prompting, and batch processing.
- Define explicit categorical criteria for what to report vs. skip — vague instructions like "be conservative" don't improve precision
- Make optional schema fields nullable (
field: null | string) — forces the model to output null rather than hallucinate - Use separate review passes (new Claude instance) to validate output — same session has confirmation bias
- Use few-shot examples with varied document structures when extraction quality is inconsistent
- Add calculated vs. stated total fields plus a discrepancy flag for semantic validation
- Use
-p/--printwith--output-format jsonfor all CI pipeline invocations
- Instruct Claude "don't fabricate values" via prompt — make fields nullable in the JSON schema instead
- Make all schema fields required — this causes hallucination when data doesn't exist in the source
- Use the same session for generation and review — reviewer has context bias from generation
- Retry extraction failures indefinitely — absent data can't be retried into existence
- Use Batch API for pre-merge code review — developers are blocked waiting; that's a real-time workload
- Rely on a larger context window to handle context degradation — use scratchpad files to persist findings
Long conversations, escalation patterns, multi-agent error propagation, and human review.
- Extract transactional facts (amounts, dates, IDs) into a persistent "case facts" block outside summarized history
- Use scratchpad files to persist research findings across long Claude Code sessions
- Route to human review when confidence scores fall below a defined threshold — not based on sentiment
- Pass structured error context from subagents to coordinators — include what failed, why, and partial results
- Use
/compactto reduce context usage in long sessions nearing the token limit - Plan error propagation strategy before deployment — define what "structured handoff" means for your use case
- Let conversation summarization silently drop precise transactional data — always preserve it in a structured block
- Use a larger model as the primary fix for context degradation in long sessions — use persistence strategies first
- Return a generic error string from a failed subagent — the coordinator needs structured context to recover
- Return empty success from a failed subagent — silently propagating failure is worse than surfacing the error
- Use sentiment analysis as the escalation trigger — explicit human request always overrides sentiment
- Assume 97% aggregate accuracy is sufficient for full automation — always validate per-type and per-field
All 6 Scenarios.
All 3 Question Types.
54 questions across every scenario — Multiple-Choice, Multi-Select, and Scenario-Based. Filter by scenario or run the full deck.
- 1.1Agentic loop lifecycle — stop_reason control flow
- 1.2Multi-agent coordinator-subagent patterns
- 1.3Subagent spawning via Task tool; context passing
- 1.4Multi-step workflows; programmatic enforcement
- 1.5Agent SDK hooks — PostToolUse; interception
- 1.6Task decomposition — chaining vs dynamic
- 1.7Session state — --resume, fork_session
- 2.1Tool descriptions = primary LLM selection mechanism
- 2.2Structured errors: errorCategory, isRetryable
- 2.3Tool distribution; tool_choice auto/any/forced
- 2.4MCP config — .mcp.json vs ~/.claude.json
- 2.5Built-in tools — Grep/Glob/Read/Write/Edit/Bash
- 3.1CLAUDE.md hierarchy: user → project → directory
- 3.2Slash commands (.claude/commands/) & skills
- 3.3Path-specific rules (.claude/rules/) glob patterns
- 3.4Plan mode vs direct execution decision
- 3.5Iterative refinement — examples, test-driven
- 3.6CI/CD: -p flag, --output-format json
- 4.1Explicit criteria over vague instructions
- 4.2Few-shot: 2–4 targeted ambiguous examples
- 4.3tool_use + JSON schema = reliable output
- 4.4Validation-retry loops; retry won't fix absent data
- 4.5Batch API: 50% savings, 24h window, no SLA
- 4.6Multi-pass review; independent instance
- 5.1Case facts block; trim verbose tool outputs
- 5.2Escalation: explicit requests honored immediately
- 5.3Structured error propagation up agent chain
- 5.4Scratchpad files; /compact; subagent delegation
- 5.5Stratified sampling; field-level confidence
- 5.6Claim-source mappings; annotate conflicts
| tool_choice | Behavior | Use When |
|---|---|---|
"auto" | May return plain text — not guaranteed | General use; tool call not required |
"any" | Must call some tool | Guaranteed structured output needed |
{"type":"tool","name":"X"} | Must call that specific tool | Enforcing tool ordering / specific extraction |
| Error Category | isRetryable | Example |
|---|---|---|
transient | ✓ Yes | Timeout, service unavailable |
validation | ✗ No | Invalid input format |
business | ✗ No | Policy violation |
permission | ✗ No | Unauthorized access |
| Batch API | Real-Time API |
|---|---|
| 50% cost savings | Immediate response |
| Up to 24h processing (no SLA) | Guaranteed low latency |
| No multi-turn tool calling | Full tool calling support |
| ✓ Overnight reports, weekly audits | ✓ Pre-merge checks, interactive |
| ✗ Any blocking workflow | ✗ Cost-sensitive batch jobs |