When: Agent consistently selects the wrong tool among similar options

→Review and expand tool descriptions FIRST -- include input formats, example queries, and boundary explanations.

When: Two tools have near-identical names/descriptions causing misrouting

→Rename the tools and rewrite descriptions to clearly distinguish each tool's purpose.

When: Tool descriptions are clear but the agent still misroutes based on keywords like 'account'

→Review the system prompt for keyword-sensitive instructions that create unintended tool associations.

When: A tool encounters a transient failure (timeout, service unavailable)

→Return isError: true with errorCategory: 'transient', isRetryable: true, and what was attempted.

When: A business rule is violated (e.g., refund exceeds policy limit)

→Return isError: true with errorCategory: 'business', isRetryable: false, and a customer-friendly explanation.

When: A query returns zero results but executed successfully

→Return a success response (isError: false) with empty results -- do NOT treat this as an error.

When: A specialized agent misuses tools outside its role (e.g., doc analysis agent doing web searches)

→Replace generic tools with purpose-specific constrained alternatives (e.g., fetch_url -> load_document).

When: 85% of a subagent's verification needs are simple fact-checks with 15% complex

→Give a scoped verify_fact tool for simple lookups; route complex cases through the coordinator.

When: You need to guarantee the model calls a specific tool first in a sequence

→Use tool_choice: {'type': 'tool', 'name': 'extract_metadata'} for the first turn, then switch to 'auto'.

When: Team needs shared MCP tooling with per-developer credentials

→Use project-scoped .mcp.json with ${ENV_VAR} expansion for tokens; document required vars in README.

When: A developer wants to experiment with a personal MCP server

→Configure it in user-scoped ~/.claude.json so it does not affect teammates.

When: A standard integration exists (GitHub, Jira) and you are considering a custom server

→Use the existing community MCP server; reserve custom implementations for team-specific workflows.

When: You need to find all callers of a specific function across the codebase

→Use Grep to search file contents for the function name.

When: You need to find all test files regardless of directory location

→Use Glob with pattern **/*.test.tsx to match by naming convention.

When: Edit fails because the anchor text appears multiple times in the file

→Use Read to load full contents, then Write the modified version as a fallback.

When: A guideline must apply to all team members (current and future)

→Place it in project-level .claude/CLAUDE.md or .claude/rules/, NOT in user-level ~/.claude/CLAUDE.md.

When: CLAUDE.md exceeds 400+ lines mixing multiple concerns

→Split into topic-specific files in .claude/rules/ (e.g., testing.md, api-conventions.md).

When: A new team member is not receiving project guidelines

→Verify the guideline exists in project-level config, not just in existing developers' user-level config.

When: A skill produces verbose output that causes Claude to lose track of the original task

→Add context: fork to the skill's frontmatter to run in an isolated sub-agent context.

When: A developer wants a personal variant of a team skill without affecting teammates

→Create a personal skill in ~/.claude/skills/ with a DIFFERENT name (project skills shadow same-named personal ones).

When: Context is only useful for a specific workflow (e.g., endpoint generation) and not general work

→Create a skill with the exemplar code; invoke on-demand via slash command instead of putting it in CLAUDE.md.

When: Different coding conventions apply to different file types (React components vs API handlers vs tests)

→Create .claude/rules/ files with YAML frontmatter paths glob patterns for each file type.

When: Test files are spread throughout the codebase alongside source files

→Use path-specific rules with **/*.test.tsx glob rather than subdirectory CLAUDE.md files.

When: You want conventions to apply to terraform files in any directory

→Use paths: ['terraform/**/*'] in rule frontmatter instead of a terraform/CLAUDE.md file.

When: Task involves ambiguous requirements with multiple valid integration approaches (e.g., adding Slack support)

→Enter plan mode to explore options and architectural implications before implementing.

When: Task is a well-understood change with clear scope (e.g., bug fix with a clear stack trace)

→Use direct execution -- no need for plan mode.

When: Discovery phase generates verbose output that fills the context window

→Use the Explore subagent to isolate verbose output and return a concise summary to the main conversation.

When: Claude interprets prose requirements differently each iteration, producing inconsistent output structure

→Provide 2-3 concrete input/output examples showing the expected transformation.

When: You are implementing in an unfamiliar domain and want to surface edge cases

→Use the interview pattern: have Claude ask about design considerations before implementing.

When: Multiple bugs interact with each other

→Describe all interacting issues in a single message rather than fixing them sequentially.

When: Running Claude Code in an automated CI pipeline

→Use the -p flag for non-interactive mode; use --output-format json with --json-schema for structured output.

When: The same Claude session generated code and you need a review

→Use a second, independent Claude instance without access to the generator's reasoning context.

When: Re-running review after developer pushes fixes, and getting duplicate findings on already-fixed code

→Include prior review findings in context, instructing Claude to only report new or still-unaddressed issues.

When: Automated review produces high false positive rates that erode developer trust

→Temporarily disable high false-positive categories; keep only high-precision categories while improving prompts.

When: Severity ratings are inconsistent across similar issues

→Add explicit severity criteria with concrete code examples for each level, not general 'be conservative' instructions.

When: A prompt instruction is vague (e.g., 'check comments are accurate')

→Replace with explicit criteria defining exactly what constitutes a problem (e.g., 'flag only when claimed behavior contradicts code').

When: Detailed format instructions produce variable output quality (sometimes detailed, sometimes vague)

→Add 3-4 few-shot examples showing the exact desired format with issue, location, and specific fix.

When: Agent misroutes between tools on ambiguous requests

→Add 4-6 few-shot examples targeting ambiguous scenarios, each showing reasoning for the tool choice.

When: Agent handles individual concerns well (94%) but fails on multi-concern messages (58%)

→Add few-shot examples demonstrating correct reasoning and tool sequencing for multi-concern requests.

When: You need guaranteed structured output with no JSON syntax errors

→Define an extraction tool with JSON schema as input parameters; extract data from the tool_use response.

When: Multiple extraction schemas exist and the document type is unknown

→Set tool_choice: 'any' to guarantee a tool call while letting the model choose which extraction schema.

When: Source documents may not contain all required fields

→Design those schema fields as optional (nullable) to prevent the model from fabricating values.

When: Extraction output has format or structural errors (wrong nesting, bad date format)

→Retry with the original document, the failed extraction, and specific validation errors appended.

When: Required data simply does not exist in the source document

→Do NOT retry -- retries cannot conjure missing information. Accept null/empty or flag for human review.

When: Developers frequently dismiss automated findings and you want to improve accuracy

→Add detected_pattern fields to structured findings to track which constructs produce false positives.

When: Workflow is latency-sensitive and blocks developers (pre-merge checks)

→Use synchronous API calls, NOT batch processing.

When: Workflow is scheduled and latency-tolerant (overnight reports, weekly audits, nightly test generation)

→Use Message Batches API for 50% cost savings.

When: Workflow requires iterative tool calling (analyze file, request related files, continue analysis)

→Do NOT use batch processing -- it cannot execute tools mid-request and return results.

When: Claude-generated code has subtle issues that only surface during human peer review

→Use a second, independent Claude instance to review without access to the generator's reasoning.

When: Single-pass review of many files produces inconsistent depth and contradictory feedback

→Split into per-file local passes plus a separate cross-file integration pass.

When: Developers spend too much time investigating each finding to decide if it is real

→Require Claude to include reasoning and confidence assessment inline with each finding.

When: Customer references specific amounts ('the 15% discount I mentioned') that were summarized away

→Extract transactional facts (amounts, dates, order numbers) into a persistent 'case facts' block outside summarized history.

When: Synthesis agent omits critical findings from the middle of 75K+ token aggregated input

→Place a key findings summary at the beginning; organize the rest with explicit section headers.

When: Tool outputs return 40+ fields per lookup when only 5 are relevant

→Trim verbose tool outputs to only relevant fields before they accumulate in context.

When: Policy is ambiguous or silent on the customer's specific request (e.g., competitor price matching)

→Escalate to a human for policy interpretation -- do not fabricate a policy.

When: get_customer returns multiple matches and the agent guesses wrong 15% of the time

→Instruct the agent to ask for an additional identifier before taking any customer-specific action.

When: The issue is straightforward but the customer explicitly asks for a human agent

→Escalate immediately -- honor the explicit request without attempting to resolve first.

When: A subagent encounters a timeout (transient failure)

→Attempt local recovery; if it fails, propagate structured error context (failure type, what was attempted, partial results) to the coordinator.

When: A subagent encounters a corrupted file (permanent failure)

→Return the error with context to the coordinator -- do NOT retry (corruption is permanent).

When: Some source categories succeed while others fail in a multi-source research task

→Proceed with available data; annotate synthesis output with coverage gaps indicating which sources were unavailable.

When: Discovery phase generates verbose output that fills the main context window

→Use the Explore subagent or context: fork to isolate verbose output; return a concise summary.

When: Extended exploration session shows signs of context degradation (vague references instead of specifics)

→Have agents maintain scratchpad files recording key findings; use /compact to reduce context usage.

When: Multi-phase task needs to persist findings across context boundaries

→Summarize key findings from one phase before spawning sub-agents for the next; inject summaries into initial context.

When: Overall accuracy is 97% but you suspect some document types perform poorly

→Analyze accuracy by document type and field to identify hidden poor-performing segments.

When: You want to reduce human review overhead on high-confidence extractions

→Implement stratified random sampling of high-confidence outputs; only reduce review after validating by segment.

When: Model outputs field-level confidence scores but they do not correlate with actual accuracy

→Calibrate confidence thresholds using labeled validation sets rather than trusting raw model scores.

When: Two credible sources report conflicting statistics on a key metric

→Include both values with explicit source attribution; let the coordinator decide how to reconcile before synthesis.

When: Subagent outputs are compressed and downstream agents lose track of which claims came from where

→Require subagents to output structured claim-source mappings (source URLs, document names, excerpts).

When: Data from different time periods appears contradictory

→Require publication/collection dates in structured outputs to enable correct temporal interpretation.