Lookup table
Cheat sheet
When a situation matches the trigger on the left, the approach on the right is almost always right. Filter by decision axis or module to narrow the table down.
| If you see… | …then the approach is |
|---|---|
| Must it hold 100% of the time? | Use a hook or permission rule (code). Instructions only ever influence, never guarantee. |
| Is the task trivial and local? | Direct execution. Save plan mode for large, interdependent, or architectural work. |
| Architectural fork with real trade-offs? | Plan mode — explore the options, then present them for human approval. |
| Where should config live? | Shared → project file. Personal → home file. Always-on → CLAUDE.md. On-demand → slash command or skill. |
| Shared, evolving workflow? | A project skill in .claude/skills/, committed to version control. |
| Directory-specific rules? | A CLAUDE.md inside that subdirectory — it only loads when you're working there. |
| Concrete exemplar files for a one-off task? | @-reference them directly; don't bloat CLAUDE.md with a one-time need. |
| MCP: tool, resource, or prompt? | Tool = the model calls it. Resource = you @-mention it. Prompt = you invoke it as a slash command. |
| Agent picks the wrong tool? | Improve the tool's description; consolidate tools that semantically overlap. |
| Agent fabricates a parameter? | State in the tool's description exactly where that value must come from. |
| Tool error handling is erratic? | Return structured, type-specific errors (category, retryable flag, what to try next). |
| Continue, resume, or fork a session? | --continue = latest session. --resume <name> = a specific one. Forking = branch to compare two approaches. |
| Resumed a session, but files changed underneath you? | Keep the context; just tell the agent which specific files changed for a targeted re-read. |
| Context degrading (answers turning generic)? | Summarize findings, then continue in a fresh subagent; delegate narrow deep-dives to subagents. |
| Controlling an agentic loop? | Continue while stop_reason is 'tool_use'; exit on 'end_turn'. A turn cap is only a safety backstop. |
| Model 'forgot' earlier turns? | The conversation history wasn't resent — the model itself is stateless. |
| Need a truly guaranteed outcome from an agentic loop? | Enforce it in orchestration code around the loop, not in the prompt. |
| Need strict JSON output? | Define a tool/function schema and read the structured output. Don't prompt-and-parse free text. |
| Model fabricates missing fields? | Make the field optional, instruct 'return null if not stated', or add few-shot examples for a recurring quirk. |
| Retry keeps failing? | Retries fix formatting problems — they never fix data that was never in the source to begin with. |
| Limited human review capacity? | Route low-confidence and ambiguous cases first; audit the rest via stratified random sampling. |
| Values legitimately change over time, or need to reconcile? | Model the history with effective dates; capture both computed and stated values and flag mismatches. |