One-Page Cheat Sheet
Reflexes (symptom → answer)
| See this | Answer this |
|---|
| Customer wants a human | Escalate (structured handoff summary) |
| Wrong/inconsistent output format | Few-shot examples |
| Tool ignored or misused | Improve the tool description |
| Fabricated parameter values | Description: "value must come from prior tool call" |
| "Must / never / compliance" | Hook or in-tool code, never prompt-only |
| Sources/citations lost between agents | Structured output: content + metadata separated |
| Context overflow in one agent | Subagents explore, return summaries |
| Slow, incoherent long chat | Summarize old turns, keep last 5–6 verbatim |
| Huge tool responses | Trim to relevant fields |
| Bulk non-urgent work | Batch API (50% off, ≤ 24 h) |
| Guaranteed JSON | Tool whose input_schema = target schema + tool_choice (current docs: add strict: true, or Structured Outputs) |
| Missing data in source | Optional fields + return null |
| Edit tool keeps failing | Read, then Write |
| Search file contents | Grep (Glob = file names only) |
| Files changed on disk | Resume + say which files changed |
| Compare 2 approaches | Fork the session |
| Stale tool results in old session | New session + summary + fresh tool calls |
| Risky/unfamiliar change | Plan mode first |
| Tiny clear change | Direct execution |
Numbers
| Fact | Value |
|---|
| Pass score | 720 / 1000 |
| Questions / time | 60 / 120 min |
| Domain 1 weight (orchestration) | 27% — the biggest |
| Cache TTL | 5 min default, 1 h option |
| Cache read / write cost | 0.1× / 1.25× (5-min write) / 2× (1-h write) |
| Batch API | 50% off, results ≤ 24 h, match by custom_id |
| CLAUDE.md import depth | 4 hops (older material says 5) |
| Refund hook threshold (canonical example) | $500 |
Flags
| Flag | One-liner |
|---|
--system-prompt | REPLACES default prompt (loses tool guidance) — the trap |
--append-system-prompt(-file) | ADDS to default — the fix |
--bare | No auto-discovery (no CLAUDE.md, skills, MCP) |
-p | Headless; still loads CLAUDE.md unless --bare |
--output-format | text / json / stream-json |
--max-turns, --max-budget-usd | CI cost caps (both print mode only; max-turns exits with an error at the limit) |
--dangerously-skip-permissions | = bypassPermissions; deny rules still block |
--continue / --resume <name> / --fork-session | Last session / named session / branch |
Loop control
- Continue while
stop_reason == "tool_use"; stop at "end_turn". - Tool results append to conversation → model reasons about next step.
- ❌ Don't parse text for "done". ❌ Don't use turn caps as the main stop.
- Loop ended unresolved? Orchestration code escalates programmatically.
MCP
- Scopes: local → project (
.mcp.json, in git) → user. First wins whole entry. - Tools:
mcp__server__tool. Prompts: /mcp__server__prompt. - Execution failure →
isError: true + what to try next. - Missing param → protocol error (exam-era answer; current docs prefer
isError: true so the model can self-correct). - Zero results → normal result, NOT error.
- Your own errorCategory + isRetryable fields in the result payload (a convention, not MCP spec) fix retry/escalate confusion.
Wrong-answer smells
"automatically" · "unrestricted" · "always/never" · "without review" · "full access" · re-doing work · raw dumps · fixing downstream · prompt-only guarantees · extremes.
Next: Question Anatomy