# claude-code-reference.yaml # Quick lookup for Claude Code - ~2K tokens target # Source: guide/ultimate-guide.md # Purpose: Condensed index for LLMs to quickly answer user questions about Claude Code version: "3.6.1" updated: "2026-01" # ════════════════════════════════════════════════════════════════ # DEEP DIVE - Line numbers in guide/ultimate-guide.md # Usage: Read file at line N for detailed documentation on topic # For architecture internals, see guide/architecture.md # ════════════════════════════════════════════════════════════════ deep_dive: # Session management session_search: "guide/observability.md:29" session_search_script: "examples/scripts/session-search.sh" # Architecture internals (guide/architecture.md) architecture_master_loop: "guide/architecture.md:60" architecture_tools: "guide/architecture.md:130" architecture_context: "guide/architecture.md:200" architecture_subagents: "guide/architecture.md:280" architecture_permissions: "guide/architecture.md:350" architecture_mcp: "guide/architecture.md:450" architecture_philosophy: "guide/architecture.md:580" # Main guide (guide/ultimate-guide.md) installation: 185 first_workflow: 266 essential_commands: 315 permission_modes: 596 interaction_loop: 908 context_management: 944 context_triage: 1058 session_vs_memory: 1091 plan_mode: 1458 rewind: 1636 mental_model: 1675 xml_prompting: 1731 memory_files: 2218 claude_folder: 2349 settings: 2400 claudemd_injection_warning: 2510 precedence_rules: 2622 agents: 2720 agent_template: 2793 agent_examples: 2901 agent_validation_checklist: 3116 skills: 3279 skill_template: 3357 skill_examples: 3425 commands: 3704 command_template: 3774 hooks: 4027 hook_templates: 4172 security_hooks: 4434 mcp_servers: 4573 mcp_config: 4771 mcp_security: 5373 cicd: 5329 ide_integration: 6018 feedback_loops: 6088 batch_operations: 6426 pitfalls: 6545 git_best_practices: 6814 cost_optimization: 7280 commands_table: 7733 shortcuts_table: 7766 troubleshooting: 7892 cheatsheet: 8265 daily_workflow: 8341 superclaude_modes: 8634 learning_mode: 8645 # ════════════════════════════════════════════════════════════════ # DECISION TREE (most important - en premier) # ════════════════════════════════════════════════════════════════ decide: simple_task: "just ask Claude" complex_task: "/plan first, then TodoWrite" context_high: "/compact (>70%) or /clear (>90%)" repeating: "create agent or command" need_docs: "Context7 MCP" deep_debug: "use extended thinking in prompts" # ════════════════════════════════════════════════════════════════ # PROMPTING FORMULA (see deep_dive.xml_prompting for details) # ════════════════════════════════════════════════════════════════ prompt_formula: WHAT: "concrete deliverable" WHERE: "file paths" HOW: "constraints, approach" VERIFY: "success criteria" example: | Add input validation to login form. WHERE: src/components/LoginForm.tsx HOW: Use Zod, inline errors VERIFY: Empty email shows error # ════════════════════════════════════════════════════════════════ # WORKFLOW (9 steps) - see deep_dive.first_workflow # ════════════════════════════════════════════════════════════════ workflow: 1: "claude" 2: "/status" 3: "Shift+Tab×2 for plan mode (if risky)" 4: "describe task (WHAT/WHERE/HOW/VERIFY)" 5: "review diff" 6: "y/n" 7: "run tests" 8: "commit" 9: "/compact when >70%" # ════════════════════════════════════════════════════════════════ # CRITICAL COMMANDS - see deep_dive.essential_commands # ════════════════════════════════════════════════════════════════ commands: /compact: "compress context - USE AT >70%" /clear: "reset conversation - USE AT >90%" /status: "show context % and cost" /plan: "read-only mode (safe exploration)" /execute: "exit plan mode" /rewind: "undo changes" /model: "switch: sonnet|opus|opusplan" /mcp: "show MCP server status" /context: "detailed token breakdown" # ════════════════════════════════════════════════════════════════ # SHORTCUTS - see deep_dive.shortcuts_table # ════════════════════════════════════════════════════════════════ shortcuts: Shift+Tab: "cycle: default → auto-accept → plan" Esc×2: "rewind/undo" Ctrl+C: "interrupt" Ctrl+R: "retry" "@file": "reference file" "!cmd": "shell command" # ════════════════════════════════════════════════════════════════ # CLI FLAGS - see deep_dive.commands_table # ════════════════════════════════════════════════════════════════ cli: "-c": "continue last session" "-r ": "resume specific session" "-p": "non-interactive (pipe mode)" "--model X": "select model" "--dangerously-skip-permissions": "auto-accept ALL (danger)" "--debug": "verbose output" "--add-dir": "grant tool access to directories outside CWD" # ════════════════════════════════════════════════════════════════ # CONTEXT MANAGEMENT - see deep_dive.context_management # ════════════════════════════════════════════════════════════════ context: zones: green: "0-50% → work freely" yellow: "50-70% → be selective" orange: "70-90% → /compact NOW" red: "90%+ → /clear required" symptoms: short_responses: "/compact" forgetting_instructions: "/clear" inconsistent: "context bleeding → /clear" slow: "/compact or /clear" # ════════════════════════════════════════════════════════════════ # MEMORY FILES - see deep_dive.memory_files # ════════════════════════════════════════════════════════════════ memory: global: "~/.claude/CLAUDE.md (not committed)" project_team: "./CLAUDE.md (committed)" project_personal: "./.claude/CLAUDE.md (not committed)" priority: "project > global" # ════════════════════════════════════════════════════════════════ # .claude/ STRUCTURE - see deep_dive.claude_folder # ════════════════════════════════════════════════════════════════ folder_structure: CLAUDE.md: "local instructions" settings.json: "hooks config (committed)" settings.local.json: "permissions (not committed)" agents/: "custom AI personas" commands/: "slash commands" hooks/: "event scripts" skills/: "knowledge modules" rules/: "auto-loaded rules" # ════════════════════════════════════════════════════════════════ # PERMISSION MODES - see deep_dive.permission_modes # ════════════════════════════════════════════════════════════════ permissions: default: "editing=ask, execution=ask" auto_accept: "editing=auto, execution=ask" plan_mode: "editing=blocked, execution=blocked" switch: "Shift+Tab" # ════════════════════════════════════════════════════════════════ # MCP SERVERS - see deep_dive.mcp_servers # ════════════════════════════════════════════════════════════════ mcp: serena: "symbol search + session memory (write_memory/read_memory)" context7: "library docs lookup" sequential: "structured multi-step reasoning" playwright: "browser automation / E2E" check: "/mcp" config: ".claude/mcp.json or ~/.claude.json" # ════════════════════════════════════════════════════════════════ # ARCHITECTURE INTERNALS - see guide/architecture.md # ════════════════════════════════════════════════════════════════ architecture: master_loop: "while(tool_call) - no DAG, no classifier, no RAG" core_tools: "Bash, Read, Edit, Write, Grep, Glob, Task, TodoWrite" context_budget: "~200K tokens, auto-compact at 75-92%" subagents: "Task tool spawns isolated agents (depth=1 max)" philosophy: "less scaffolding, more model - trust Claude's reasoning" mcp_protocol: "JSON-RPC 2.0, treated as native tools" permissions: "interactive prompts + allow/deny rules + hooks" deep_dive: "guide/architecture.md" # ════════════════════════════════════════════════════════════════ # COST OPTIMIZATION - see deep_dive.cost_optimization # ════════════════════════════════════════════════════════════════ cost: haiku: "simple fixes, reviews ($)" sonnet: "most development ($$)" opus: "architecture, complex bugs ($$$)" opusplan: "plan=opus + execute=sonnet ($$)" tip: "--add-dir grants tool access to additional directories (permissions, not context loading)" # ════════════════════════════════════════════════════════════════ # TOOL SELECTION # ════════════════════════════════════════════════════════════════ tools: file_search: "Glob (not find)" content_search: "Grep (not grep bash)" file_read: "Read (not cat)" file_edit: "Edit (not sed)" multi_file: "MultiEdit" deep_analysis: "Sequential MCP" library_docs: "Context7 MCP" browser: "Playwright MCP" # ════════════════════════════════════════════════════════════════ # ANTI-PATTERNS - see deep_dive.pitfalls # ════════════════════════════════════════════════════════════════ dont: - "vague prompts → be specific" - "accept without reading → read every diff" - "ignore >70% context → /compact" - "skip permissions in prod → never" - "bloated CLAUDE.md → keep concise (<200 lines)" - "only negative constraints → provide alternatives" # ════════════════════════════════════════════════════════════════ # TROUBLESHOOTING - see deep_dive.troubleshooting # ════════════════════════════════════════════════════════════════ fix: "command not found": "npm i -g @anthropic-ai/claude-code" "context too high": "/compact or /clear" "slow responses": "/compact" "MCP not working": "claude mcp list, check config" "permission denied": "check settings.local.json" "hook blocking": "check exit code (0=ok, 2=block)" # ════════════════════════════════════════════════════════════════ # DEBUG COMMANDS # ════════════════════════════════════════════════════════════════ debug: version: "claude --version" update: "claude update" diagnostic: "claude doctor" verbose: "claude --debug" mcp_debug: "claude --mcp-debug" # ════════════════════════════════════════════════════════════════ # AGENT TEMPLATE - see deep_dive.agent_template # ════════════════════════════════════════════════════════════════ agent_template: | --- name: agent-name description: Use when [trigger] model: sonnet|opus|haiku tools: Read, Write, Edit, Bash --- # Instructions here # ════════════════════════════════════════════════════════════════ # HOOK EVENTS - see deep_dive.hooks # ════════════════════════════════════════════════════════════════ hook_events: PreToolUse: "before tool (exit 2 to block)" PostToolUse: "after tool" UserPromptSubmit: "before prompt sent" Notification: "alerts" # ════════════════════════════════════════════════════════════════ # GOLDEN RULES # ════════════════════════════════════════════════════════════════ rules: 1: "Always review diffs before accepting" 2: "Use /compact before >70%" 3: "Be specific (WHAT/WHERE/HOW/VERIFY)" 4: "Plan Mode first for complex/risky" 5: "Create CLAUDE.md for every project" 6: "Commit frequently after each task" # ════════════════════════════════════════════════════════════════ # ONBOARDING MATRIX - Maps user profile → content sections # Used by tools/onboarding-prompt.md for personalized learning paths # ════════════════════════════════════════════════════════════════ onboarding_matrix: # Format: goal.level_time → list of deep_dive keys to cover get_started: beginner_5min: [rules, commands, shortcuts] beginner_15min: [rules, workflow, essential_commands, context.zones] beginner_30min: [rules, workflow, essential_commands, context_management, permission_modes] optimize: intermediate_15min: [context_management, context_triage, plan_mode] intermediate_30min: [context_management, plan_mode, memory_files, cost_optimization] power_30min: [context_triage, cost_optimization, batch_operations] build_agents: intermediate_30min: [agents, agent_template, agent_examples] power_30min: [agents, agent_template, skills, skill_template, commands] power_60min: [agents, skills, commands, hooks, agent_validation_checklist] fix_problem: any_any: [troubleshooting, fix, context.symptoms] learn_everything: beginner_60min: [workflow, essential_commands, context_management, memory_files, plan_mode] intermediate_120min: [plan_mode, agents, skills, hooks, mcp_servers] power_120min: [architecture, mcp_servers, hooks, cost_optimization, cicd] # ════════════════════════════════════════════════════════════════ # ONBOARDING QUESTIONS - Structure for interactive profiling # ════════════════════════════════════════════════════════════════ onboarding_questions: mandatory: goal: ask: "What's your goal right now?" options: get_started: "🚀 Get started quickly" optimize: "📈 Optimize my workflow" build_agents: "🏗️ Build custom agents/skills" fix_problem: "🐛 Fix a problem" learn_everything: "📚 Learn everything" level: ask: "Experience with Claude Code?" options: beginner: "🟢 Beginner (never used / just installed)" intermediate: "🟡 Intermediate (daily use)" power: "🔴 Power User (know basics, want advanced)" optional: time: ask: "How much time do you have?" options: 5min: "⚡ 5-10 min" 15min: "⏱️ 15-30 min" 30min: "🎯 30-60 min" 60min: "📚 1+ hour" 120min: "📖 2+ hours" default: "30min" style: ask: "How do you prefer to learn?" options: explain: "📖 Explanations (tell me why)" examples: "💻 Examples (show me code)" reference: "🎯 Quick reference (just the facts)" handson: "🏋️ Hands-on (let me try)" trigger: "Only ask if time >= 30min" # Logic for progressive questioning question_flow: fix_problem: "goal only → skip to troubleshooting" get_started: "goal → level" optimize: "goal → level → time" build_agents: "goal → level → time" learn_everything: "goal → level → time → style"