Twenty-five misconceptions
These beliefs are common among capable engineers, and each is the basis of at least one plausible wrong answer. Read the misconception, then the correction. "A clear enough prompt will always be followed." Prompts are probabilistic. For rules that must never break, use hooks and programmatic gates (Ch. 2.4, 2.5).
"Subagents can see what the coordinator saw." They start with a clean context. Anything they need must be in their prompt (Ch. 2.3).
"The loop is done when Claude writes some text." Claude often writes text alongside a tool call. Only stop_reason == "end_turn" means finished (Ch. 2.1).
"An iteration cap is a good stopping rule." It is a safety backstop. As the main rule, it cuts off work arbitrarily (Ch. 2.1).
"Spawning subagents one per turn is parallel." Only several Task calls in one response run concurrently (Ch. 2.3).
"If the report is incomplete, the search agent must be weak." Check the coordinator's decomposition first (Ch. 2.2). "More tools make an agent more capable." Beyond a handful, selection reliability falls (Ch. 3.3).
"Tool confusion needs a routing classifier." Start with better descriptions; rename or split overlapping tools (Ch. 3.1).
"An error is an error." Transient, validation, business and permission errors need different responses, and an empty result is not an error at all (Ch. 3.2).
"Personal MCP servers can go in .mcp.json if they are marked optional." Project config is for shared servers; personal ones go in ~/.claude.json (Ch. 3.4).
"Grep finds files." Grep searches contents; Glob matches paths (Ch. 3.5).
"My ~/.claude/CLAUDE.md applies to the team." It applies only to you (Ch. 4.1). "A subdirectory CLAUDE.md can cover all test files." Tests spread across directories need glob-scoped rules (Ch. 4.3).
"Plan mode is for beginners." It is for complex, architectural or multi-approach work, whatever your seniority (Ch. 4.4).
"Redirecting stdin will make Claude Code run in CI." Use -p (Ch. 4.6).
"Telling the model to be conservative reduces false positives." Specific categorical criteria do; general caution does not (Ch. 5.1).
"A strict schema means correct data." It means valid syntax. Semantics need validation (Ch. 5.3).
"Required fields improve completeness." For absent data they cause invention; use nullable fields (Ch. 5.3).
"Enough retries will fix any extraction." Not when the information is missing from the input (Ch. 5.4). "The Batches API is just a cheaper API." It is cheaper and slower, with no latency guarantee and no mid-request tool calls (Ch. 5.5).
"A model can review its own work if you ask it to be critical." An independent instance is better (Ch. 5.6).
"Bigger context windows solve context problems." They delay them. Structure, trimming and delegation solve them (Ch. 6.1, 6.4).
"Angry customers should be escalated." Escalate on explicit requests, policy gaps and lack of progress, not tone (Ch. 6.2).
"A model's confidence score tells you when to trust it." Only after calibration against labelled data (Ch. 6.5). "When sources disagree, pick the more credible one." Report both with sources and dates and mark the point as contested (Ch. 6.6).