Decision Trees
Use these to work through the most common judgment calls on the exam
Tree 1 — Enforcement: Programmatic or Prompt?
Does this rule have financial, security, or legal consequences if violated?
YES →
Use programmatic enforcement (hook / prerequisite gate)
NO ↓
Does the rule need to apply 100% of the time (zero acceptable failure rate)?
YES →
Use programmatic enforcement
NO ↓
Is the rule complex enough that schema/hooks would be over-engineered?
YES →
Prompt instruction is acceptable — monitor for failures
NO →
Prefer programmatic — more reliable at low complexity cost
Tree 2 — Escalation Decision
Did the customer explicitly say "I want a human" or equivalent?
YES →
Escalate immediately. No resolution attempt. Period.
NO ↓
Is the policy ambiguous, silent, or undefined for this request?
YES →
Escalate. Don't let the agent improvise on policy gaps.
NO ↓
Is the agent unable to make meaningful progress after genuine attempts?
YES →
Escalate with structured handoff summary.
NO →
Resolve autonomously. Acknowledge frustration if present.
Tree 3 — Batch API vs Real-Time API
Is any person or process waiting (blocked) for this result?
YES →
Real-Time API only. Batch has no latency SLA (up to 24h).
NO ↓
Does the workflow require multi-turn tool calling within a single request?
YES →
Real-Time API. Batch does not support multi-turn tool calls.
NO ↓
Is cost reduction a priority and is 24h completion acceptable?
YES →
Batch API. 50% cost savings. Use custom_id for correlation.
NO →
Real-Time API. Batch only when latency tolerance is confirmed.
Tree 4 — Plan Mode vs Direct Execution
Does the task involve multiple files AND architectural decisions?
YES →
Plan Mode. Explore before committing to prevent costly rework.
NO ↓
Are there multiple valid approaches with different tradeoffs?
YES →
Plan Mode. Evaluate options before writing code.
NO ↓
Is this a single-file, well-understood, clear-scope change?
YES →
Direct Execution. No need for exploration overhead.
UNSURE →
Default to Plan Mode. The cost of exploration is low; rework is high.
API Cheat Sheet
Every API concept, value, and flag you need to know
stop_reason Values
tool_useExecute tool → continue loopend_turnModel finished → terminatemax_tokensToken limit hit → handlestop_sequenceCustom stop string hittool_choice Options
"auto"May return text (not guaranteed tool call)"any"Must call some tool{type:"tool",name:"X"}Must call tool X specificallyMessage Batches API — Key Facts
| 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 |
JSON Schema Design Patterns
| 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 |
MCP Error Response Structure
| 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 |
Configuration Reference
Every config file, directory, and flag — location, scope, and purpose
CLAUDE.md Hierarchy
| 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) |
Slash Commands & Skills
| 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) |
SKILL.md Frontmatter Options
| 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. |
Claude Code CLI Flags
| 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 |
MCP Server Configuration
| 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 |
All configured MCP servers are discovered at connection time and available simultaneously.
Scenario Map
What each scenario tests and the key traps in each
Scenario 1 — Customer Support Resolution Agent
| 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 |
Scenario 2 — Code Generation with Claude Code
| 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 |
Scenario 3 — Multi-Agent Research System
| 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 |
Scenario 4 — Developer Productivity with Claude
| 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 |
Scenario 5 — Claude Code for CI/CD
| 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 |
Scenario 6 — Structured Data Extraction
| 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 |
Exam Traps & Common Wrong Answers
The distractors that catch unprepared candidates — and why they're wrong
Non-Existent Features (Always 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 |
Over-Engineered Distractors (Wrong for "First Step" Questions)
| 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 |
Probabilistic vs Deterministic Traps
| 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" |
Confusable Concepts — High Exam Frequency
| 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. |