174192f583
- Add CITATION.cff for academic citations and GitHub citation button - Add "For AI Assistants" section in README with llms.txt reference - Update machine-readable/llms.txt stats (4700+ → 9600+ lines) - Bump version display to 3.8.0 in README footer Improves discoverability in GitHub search, Google Scholar, and AI assistants Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
396 lines
20 KiB
YAML
396 lines
20 KiB
YAML
# 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.7.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"
|
||
# PDF Generation
|
||
pdf_generation: "guide/workflows/pdf-generation.md"
|
||
pdf_generator_skill: "examples/skills/pdf-generator.md"
|
||
whitepapers_example: "whitepapers/README.md"
|
||
# 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 <id>": "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)"
|
||
|
||
tone:
|
||
ask: "How do you prefer me to communicate?"
|
||
options:
|
||
pedagogical: "🎓 Pedagogical - Detailed explanations, understand why"
|
||
direct: "⚡ Direct - Straight to the point"
|
||
coaching: "🧭 Coaching - Guide me with questions"
|
||
adaptive: "🔄 Adaptive - Mix based on complexity"
|
||
|
||
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 >= 15min"
|
||
|
||
# Logic for progressive questioning
|
||
question_flow:
|
||
fix_problem: "goal only → skip to troubleshooting"
|
||
get_started: "goal → tone → level"
|
||
optimize: "goal → tone → level → time → style (if time >= 15min)"
|
||
build_agents: "goal → tone → level → time → style (if time >= 15min)"
|
||
learn_everything: "goal → tone → level → time → style"
|