Cheatsheet 5 — Anti-patterns & Traps
The distractor catalogue. Read this last, the night before.
The ten Core Reflexes
When you're stuck, run these in order.
| # | Reflex |
|---|---|
| 1 | Deterministic enforcement beats prompt instructions when errors are financial, compliance, or irreversible. Prompts have a non-zero failure rate. |
| 2 | More context is never the answer. Not a bigger window, not less summarization. Restructure instead. |
| 3 | Tool descriptions are where selection problems get fixed — not the system prompt, not the tool names. |
| 4 | Fewer, better-scoped tools beat more tools. Least privilege per agent. |
| 5 | Subagents inherit nothing. Every delegating prompt carries all identifiers, paths, constraints, and prior findings literally. |
| 6 | An access failure is not an empty result. isError: true, with a category and retryability. |
| 7 | Explicit criteria beat exhortation. "Be conservative" and "only flag high-confidence issues" do not work. |
| 8 | Schemas guarantee syntax, not semantics. Cross-field arithmetic needs a computed check. |
| 9 | Blame the layer the evidence implicates, usually the coordinator's decomposition — not the downstream agents working correctly in the scope they were given. |
| 10 | Self-reported confidence and sentiment are uncalibrated. Neither is a valid trigger until measured against labeled data. |
Options that do not exist
Pure recall. If you see these, they're wrong.
| Fake | Reality |
|---|---|
CLAUDE_HEADLESS env var |
Use -p / --print |
--batch flag on the CLI |
The Message Batches API is an API surface, not a CLI flag |
--ci, --non-interactive |
-p / --print |
A commands array in .claude/config.json |
One Markdown file per command in .claude/commands/ |
parallel: true for subagents |
Multiple Task calls in one response |
A tools array that makes MCP tools "preferred" |
Improve the tool description |
The trap catalogue
🚫 "Increase the context window"
Appears in Domains 1, 4, and 5. Wrong for attention dilution, wrong for lost-in-the-middle, wrong for context degradation, wrong for summarization loss. The fixes are structural: split passes, key findings first, section headers, scratchpads, subagent delegation, a pinned facts block.
🚫 "Make the prompt instruction firmer"
Wrong whenever the consequence is a refund, a permission, a deletion, or a compliance requirement. Use a hook or a programmatic gate. Right only for style and formatting preferences.
🚫 "Tighten the JSON schema"
Wrong for anything semantic: sums that don't reconcile, the right value in the wrong field, the due date read as the issue date. A schema cannot express a cross-field relationship.
🚫 "Be conservative" / "only flag high-confidence issues"
The named failing instruction for false positives. Replace with explicit criteria plus code examples, including what does not qualify.
🚫 "Escalate on complexity" / "on frustration" / "on low confidence"
None are triggers. The three real triggers: explicit request for a human · policy exception or gap · inability to make progress.
🚫 "97% accuracy exceeds our threshold, automate"
Aggregate metrics mask per-category failure. Measure per document type AND per field; automate per cell.
🚫 "Ask the same instance to review its own work" / "enable extended thinking to review"
Review requires independence, not depth. Fresh context, separate instance.
🚫 "Pick the most likely customer match"
Multiple matches → ask for another identifier. Downstream actions are irreversible.
🚫 "Select the more authoritative source" / "use the most recent" / "average them"
Conflicting figures → report all, with attribution and dates.
🚫 "The subagents are underperforming"
When the coordinator's subtasks clustered narrowly, the subagents did their jobs. The decomposition is the bug.
🚫 "Terminate the workflow on error" AND "suppress the error and continue"
Both wrong, symmetrically. Complete what you can, report what you couldn't, annotate the gap.
🚫 "Increase the retry limit"
Wrong when the information is absent from the source. Nullable field, "unclear" enum, or human review.
🚫 "Batch the pre-merge CI review"
No latency SLA, up to 24 hours. Batch what nobody is waiting for. The nightly aggregate report, yes; the blocking PR check, never.
🚫 Infrastructure answers
Deploying/hosting MCP servers, vector databases, embeddings, fine-tuning, rate limits, pricing, auth protocols, cloud-provider config. All out of scope. An option reaching for them is a distractor.
🚫 Over-engineering
When the stem asks for the most effective first step, the answer is the smallest high-leverage change that addresses the root cause. "Rebuild the pipeline," "split across repositories," "add a new orchestration layer" — usually wrong when a description rewrite or a single hook would do.
The distractor families
Ten shapes that recur. Naming them speeds elimination.
| Family | Shape |
|---|---|
| More capacity | Bigger window, higher token limit, more retries |
| Firmer prompt | Same guidance, stronger wording, ALL CAPS |
| Wrong layer | Fixes the symptom's location, not its cause |
| Non-existent option | A plausible flag, file, or parameter that doesn't exist |
| Over-engineering | A large rebuild where a targeted change suffices |
| Out-of-scope tech | Vectors, embeddings, fine-tuning, infra |
| Metric misread | Aggregate accuracy, tool-call counts, sentiment scores |
| Self-assessment | The model judging its own output or confidence |
| Half-right | Correct diagnosis, wrong remedy — or vice versa |
| Absolutist | "Always," "never," with no situational condition |
Multiple-response items
Each item tells you how many to select. When it asks for two or three:
- The correct set is usually complementary, not redundant — a detection mechanism plus a prevention mechanism, or a structural fix plus a measurement.
- If two options say nearly the same thing, both are probably wrong — the exam doesn't usually reward picking a near-duplicate pair.
- Apply the reflexes to each option independently. Don't let one strong option pull a weak neighbour in with it.
The last-five-minutes list
If you remember nothing else:
- Hooks over prompts for anything that costs money.
- Descriptions over prompts for tool selection.
- Subagents know nothing you don't tell them.
isErrorfor access failures, not[].- Explicit criteria over "be careful."
- Schemas don't check arithmetic.
- Never a bigger context window.
- Blame the coordinator.
- Measure per type and per field.
-pfor CI,.claude/commands/for team commands,~/.claude/isn't shared.