Quick reference

Every trap from all 30 lessons — 179 of them — grouped by domain. This is revision material, not a substitute for the lessons: the traps make sense once you've read the reasoning behind them. Print-friendly with Ctrl/Cmd + P.

Agentic Architecture & Orchestration

27% · 16 questions · 7 lessons

1.1 Parsing natural-language "done" signals to decide when the loop ends
1.1 Treating the presence of assistant text as a completion indicator
1.1 Setting an arbitrary iteration cap as the primary stopping mechanism
1.1 Forgetting to append tool results before the next request
1.1 Replacing model-driven tool selection with a hard-coded tool sequence
1.2 Decomposing a broad topic so narrowly that whole areas are never assigned to any subagent
1.2 Blaming downstream subagents for coverage gaps that originate in the coordinator's decomposition
1.2 Routing every query through the full subagent pipeline regardless of its complexity
1.2 Letting subagents pass results directly to each other, bypassing the coordinator
1.2 Assuming a subagent can see the coordinator's conversation history
1.2 Accepting the first synthesis pass without checking it for coverage gaps
1.2 Giving parallel subagents overlapping scope so they duplicate each other's work
1.3 Expecting a coordinator to spawn subagents when its allowedTools doesn't include "Task"
1.3 Assuming a subagent inherits the coordinator's conversation history or remembers earlier invocations
1.3 Passing a vague pointer or lossy recap instead of the complete findings the subtask depends on
1.3 Flattening findings into prose so source URLs, document names, and page numbers are lost
1.3 Spawning parallel subagents one per turn instead of as multiple Task calls in one response
1.3 Scripting a subagent with step-by-step procedures instead of goals and quality criteria
1.4 Strengthening the system prompt to fix an ordering rule that must hold every time
1.4 Treating a high prompt-compliance rate as good enough for identity or financial steps
1.4 Adding few-shot examples of the correct order instead of a programmatic prerequisite
1.4 Gating on whether the upstream tool was called rather than on what it returned
1.4 Treating a multi-concern request as one undifferentiated issue, or splitting it with no shared context
1.4 Escalating with the raw transcript or a one-line note to a human who can't see the conversation
1.5 Enforcing a hard business limit only through system-prompt instructions
1.5 Asking the model to interpret mixed timestamp and status-code formats instead of normalizing them in a hook
1.5 Normalizing tool data after the agent has already reasoned over it
1.5 Blocking a violating call without redirecting it to an alternative workflow such as human escalation
1.5 Using an after-the-fact alert where the rule required preventing the action
1.6 Reviewing a large multi-file change in one pass and expecting consistent depth across every file
1.6 Splitting a review into per-file passes and dropping the cross-file integration pass
1.6 Fixing a complete subtask list up front for an open-ended investigation
1.6 Using open-ended adaptive decomposition for a review whose steps are known and repeatable
1.6 Starting an open-ended task by producing output before mapping the codebase's structure
1.6 Treating the initial plan as final instead of revising it as dependencies are discovered
1.7 Resuming a session after code changes without telling the agent what changed
1.7 Resuming a session whose tool results are largely stale instead of starting fresh with a structured summary
1.7 Forcing a full re-exploration when only a few known files changed
1.7 Comparing two approaches one after the other in a single session, so the second inherits the first's edits and reasoning
1.7 Starting every work session from scratch and rediscovering context that was still valid
1.7 Expecting forked branches to stay in sync or share later discoveries with each other

Claude Code Configuration & Workflows

20% · 12 questions · 6 lessons

3.1 Putting team-wide conventions in ~/.claude/CLAUDE.md and expecting teammates to get them
3.1 Assuming instructions that work on your machine are reaching everyone because they're "in CLAUDE.md"
3.1 Importing every standards file into every package regardless of what that package does
3.1 Letting one root CLAUDE.md grow into a monolith instead of splitting it into .claude/rules/ topic files
3.1 Rewording instructions to fix inconsistent behavior before checking which memory files actually loaded
3.1 Copying the same project-wide rule into every subdirectory's CLAUDE.md
3.2 Putting a team-wide command in ~/.claude/commands/, where only you can use it
3.2 Editing the shared team skill to suit personal preferences instead of creating a differently named personal variant
3.2 Letting a codebase-analysis skill run inline so its verbose output floods the main conversation
3.2 Assuming a skill is isolated or tool-restricted by default without setting context: fork or allowed-tools
3.2 Relying on developers to remember a skill's required parameter instead of setting argument-hint
3.2 Putting an occasional, task-specific workflow in CLAUDE.md so it loads in every session
3.3 Copying a cross-cutting convention into a CLAUDE.md in every directory that contains matching files
3.3 Leaving area-specific conventions in the root CLAUDE.md, where they load in every session
3.3 Writing a glob anchored to one directory when the files are spread throughout the tree
3.3 Relying on Claude to infer which section of a large CLAUDE.md applies to the current file
3.3 Packaging file-type conventions as skills, which apply only when someone invokes them
3.4 Starting a large restructuring in direct execution and letting the code "reveal" the design
3.4 Planning a one-line, well-understood fix that has a clear stack trace
3.4 Writing exhaustive upfront instructions instead of exploring the codebase first
3.4 Waiting to switch to plan mode until complexity appears, when the task already states it
3.4 Running long discovery inline until the main context is exhausted, instead of using the Explore subagent
3.4 Staying in plan mode through implementation after the approach has already been decided
3.5 Rewriting a prose description more forcefully when examples would remove the ambiguity
3.5 Reporting "it doesn't handle edge cases" instead of giving the failing input and expected output
3.5 Asking for the implementation first and writing tests afterwards
3.5 Starting implementation in an unfamiliar domain without first having Claude ask clarifying questions
3.5 Fixing interacting issues one at a time, so each fix undoes or conflicts with the last
3.5 Bundling unrelated, independent issues into one message when sequential fixes would be easier to verify
3.6 Invoking Claude Code in CI without -p, so the job hangs waiting for interactive input
3.6 Parsing free-form review text with regexes instead of requesting --output-format json with a --json-schema
3.6 Re-running the full review after each push without prior findings, so the same comments are posted again
3.6 Having the same session that generated the code review its own changes
3.6 Generating tests without showing the existing test files, so it re-suggests scenarios already covered
3.6 Leaving testing standards and available fixtures undocumented, then blaming the model for low-value tests

Prompt Engineering & Structured Output

20% · 12 questions · 6 lessons

4.1 Adding "be conservative" or "only report high-confidence findings" to fix false positives
4.1 Writing criteria as goals ("check that comments are accurate") instead of report conditions
4.1 Filtering findings by the model's self-reported confidence instead of by category
4.1 Keeping a noisy category enabled because some of its findings are real
4.1 Defining severity levels with adjectives alone and no code examples
4.1 Treating false positives as a cosmetic annoyance rather than a trust problem
4.2 Adding more paragraphs of instructions when output format keeps varying
4.2 Choosing examples of easy, clear-cut cases instead of the ambiguous ones
4.2 Showing only the answer in an example, without the reasoning for rejecting alternatives
4.2 Expecting examples to work only as a lookup table of pre-specified cases
4.2 Using examples that all share one document layout when production documents vary
4.2 Adding dozens of examples where 2–4 targeted ones would do
4.3 Prompting for JSON in text and parsing whatever comes back
4.3 Leaving tool_choice on "auto" when the step must always produce structured output
4.3 Marking fields required when the source document may not contain them
4.3 Using a closed enum with no "other" or "unclear" option for open-ended categories
4.3 Assuming schema-valid output is semantically correct
4.3 Relying on the schema alone to normalize inconsistent source formats
4.4 Retrying with the identical prompt and hoping for a different result
4.4 Retrying with only the error message, without the original document and failed output
4.4 Retrying repeatedly when the required information isn't in the provided document
4.4 Assuming tool use makes output correct, so no semantic validation is needed
4.4 Extracting only the stated total, with no independent calculation to compare it to
4.4 Logging dismissed findings without recording which code pattern triggered them
4.5 Moving a blocking pre-merge check to the batch API to save cost
4.5 Assuming batches usually finish fast enough to rely on for latency-sensitive work
4.5 Designing a batch request that needs multi-turn tool calling
4.5 Matching batch results to inputs by position instead of by custom_id
4.5 Resubmitting the entire batch when only some requests failed
4.5 Resubmitting oversized documents unchanged after they failed on context limits
4.5 Batch-processing thousands of documents with a prompt never tested on a sample
4.6 Asking the generating session to "review your work carefully" as the quality gate
4.6 Relying on extended thinking in the same session instead of an independent reviewer
4.6 Passing the generator's reasoning to the reviewer "for context"
4.6 Reviewing many files in one pass and expecting consistent depth
4.6 Moving to a larger context window to fix attention dilution
4.6 Keeping only findings that several identical full-PR runs agree on
4.6 Running per-file passes only, with no integration pass for cross-file issues

Tool Design & MCP Integration

18% · 11 questions · 5 lessons

2.1 Leaving tool descriptions minimal and expecting the model to infer the difference between similar tools
2.1 Describing a tool's implementation instead of its purpose, inputs, outputs, and boundaries
2.1 Rewriting one of two overlapping descriptions while the other stays vague
2.1 Reaching for few-shot examples, a keyword router, or a merged tool before fixing the descriptions
2.1 Keeping one generic tool for jobs that need different input/output contracts
2.1 Ignoring keyword-sensitive system prompt instructions that pull the model toward the wrong tool
2.2 Returning a generic "Operation failed" for every kind of failure
2.2 Retrying errors that are not retryable, such as policy violations or permission denials
2.2 Returning an empty result marked as success when the lookup actually failed
2.2 Treating a successful query with no matches as a failure to retry
2.2 Escalating every transient failure to the coordinator instead of recovering locally
2.2 Propagating an unresolved failure without partial results or a record of what was attempted
2.3 Giving every agent the full tool set "just in case"
2.3 Leaving a specialist with tools outside its role, such as web search on a synthesis agent
2.3 Exposing a generic tool like fetch_url where a constrained, validating tool would do
2.3 Giving one role all of another role's tools to remove a frequent round trip
2.3 Relying on prompt wording to make the model call a required first tool instead of forcing it with tool_choice
2.3 Leaving tool_choice on "auto" when the step must produce a tool call, not conversational text
2.4 Committing a literal token in .mcp.json instead of using environment variable expansion
2.4 Putting a server the whole team needs in ~/.claude.json, where teammates never get it
2.4 Adding a personal experimental server to the project's .mcp.json
2.4 Leaving MCP tool descriptions thin, so the agent falls back to built-in Grep
2.4 Making the agent discover available content through repeated exploratory tool calls instead of a resource catalog
2.4 Building a custom MCP server for a standard integration like Jira that a community server already covers
2.5 Using Grep to find files by name, or Glob to search inside files
2.5 Reading every file upfront to understand a codebase
2.5 Retrying Edit with the same non-unique anchor text
2.5 Searching only for a function's original name when wrapper modules re-export it under other names
2.5 Rewriting a whole file with Write when a targeted Edit with a unique anchor would do

Context Management & Reliability

15% · 9 questions · 6 lessons

5.1 Relying on progressive summarization to carry exact amounts, dates, and customer-stated expectations
5.1 Appending full tool responses to history when only a handful of fields are relevant
5.1 Burying the most important findings in the middle of a long aggregated input
5.1 Sending only the latest user message instead of the complete conversation history
5.1 Letting subagents return verbose reasoning chains to a downstream agent with a tight context budget
5.1 Dropping dates and source locations from subagent outputs, leaving the synthesizer to guess
5.2 Escalating on negative sentiment as a proxy for case complexity
5.2 Routing to humans based on the model's self-reported confidence score
5.2 Investigating or attempting resolution first when the customer has explicitly asked for a human
5.2 Escalating every frustrated customer even when the issue is within the agent's capability
5.2 Stretching an existing policy to cover a case it doesn't address instead of escalating
5.2 Picking the most recent or most likely record when a lookup returns several matches
5.3 Returning a generic status such as "search unavailable" that hides what failed and what was tried
5.3 Catching a failure and returning an empty result marked as success
5.3 Terminating the entire workflow because one subagent failed
5.3 Treating a timeout and a query with zero matches as the same outcome
5.3 Propagating every transient failure to the coordinator instead of retrying locally first
5.3 Presenting a report built from partial sources as if coverage were complete
5.4 Continuing a degraded session and trusting answers that cite "typical patterns" instead of specific classes
5.4 Running every grep and file read in the main session so verbose output floods the coordinator's context
5.4 Keeping key findings only in conversation history, where they are lost at the next context boundary
5.4 Starting a new exploration phase without injecting a summary of what the previous phase found
5.4 Restarting a crashed multi-agent run from scratch because no agent exported its state
5.4 Letting discovery output pile up until the session is unusable instead of compacting
5.5 Automating extraction because aggregate accuracy is high, without checking accuracy per document type and field
5.5 Using the model's raw confidence scores as review thresholds without calibrating them on labeled data
5.5 Stopping all review of high-confidence extractions once they are automated
5.5 Sampling uniformly at random, so rare document types barely appear in the audit
5.5 Sending reviewers a random slice of all extractions instead of the low-confidence and contradictory ones
5.5 Using a single document-level confidence score when errors concentrate in specific fields
5.6 Summarizing findings into prose that drops which source supports which claim
5.6 Picking one value when credible sources report conflicting statistics
5.6 Reconciling conflicts inside the analysis subagent instead of surfacing them to the coordinator
5.6 Omitting publication and collection dates, so a 2021 figure and a 2025 figure look like a contradiction
5.6 Blending contested and well-established findings into one confident narrative
5.6 Forcing financial tables, news, and technical findings into one uniform format