From 08facfdbdc4d84b041557d7bbfff2e407a6a26e3 Mon Sep 17 00:00:00 2001
From: Florian BRUNIAUX <florian@bruniaux.com>
Date: Mon, 12 Jan 2026 10:37:09 +0100
Subject: [PATCH] feat(llm-ref): add machine-optimized YAML index for Claude
 Code

- Create claude-code-reference.yaml (~2K tokens vs 70K full guide)
- Add deep_dive section with 38 line references to main guide
- Structure: decision tree first, then prompting formula, commands, etc.
- Update README.md with LLM Reference in Core Documentation
- Update llms.txt with Machine-Optimized Reference section
- Bump version to 2.9.2

Use case: Claude Code self-reference for fast user question answering

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CHANGELOG.md               |  18 +++
 README.md                  |   3 +-
 claude-code-reference.yaml | 281 +++++++++++++++++++++++++++++++++++++
 llms.txt                   |  10 ++
 4 files changed, 311 insertions(+), 1 deletion(-)
 create mode 100644 claude-code-reference.yaml

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b29ac9a..0d2084c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,24 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## [Unreleased]
 
+## [2.9.2] - 2026-01-12
+
+### Added
+- **claude-code-reference.yaml** - Machine-optimized LLM index (~2K tokens)
+  - **Decision tree** as first section (most used lookup)
+  - **Prompting formula** (WHAT/WHERE/HOW/VERIFY pattern)
+  - **38 deep_dive line references** to english-ultimate-claude-code-guide.md
+  - 22 sections covering: commands, shortcuts, CLI flags, context management, memory files, MCP servers, think levels, cost optimization, anti-patterns, troubleshooting
+  - Flat YAML structure (max 1 level nesting) for optimal LLM parsing
+  - ~97% token reduction vs full guide (2K vs 70K tokens)
+- **README.md** - Added LLM Reference row in Core Documentation table
+- **llms.txt** - Added Machine-Optimized Reference section with YAML file description
+
+### Stats
+- 1 new file created (claude-code-reference.yaml, 282 lines)
+- 2 files modified (README.md, llms.txt)
+- Use case: Claude Code self-reference for fast user question answering
+
 ## [2.9.1] - 2026-01-12
 
 ### Fixed
diff --git a/README.md b/README.md
index 2ead72d..358f114 100644
--- a/README.md
+++ b/README.md
@@ -139,6 +139,7 @@ curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-
 |------|---------|-----------------|
 | **[Ultimate Guide](./english-ultimate-claude-code-guide.md)** | 8500+ lines, 32K+ words, 10 sections | ~3 hours (or by section) |
 | **[Cheat Sheet](./cheatsheet-en.md)** | 1-page printable reference | 5 minutes |
+| **[LLM Reference](./claude-code-reference.yaml)** | Machine-optimized index (~2K tokens) | For Claude/AI assistants |
 | **[Setup Audit](./claude-setup-audit-prompt.md)** | Optimize your configuration | ~10 minutes |
 | **[Examples Library](./examples/)** | Production-ready templates | Browse as needed |
 
@@ -315,7 +316,7 @@ If this guide saved you time, helped you master Claude Code, or inspired your wo
 
 ---
 
-*Version 2.9.1 | January 2026 | Crafted with Claude*
+*Version 2.9.2 | January 2026 | Crafted with Claude*
 
 <!-- SEO Keywords -->
 <!-- claude code, claude code tutorial, anthropic cli, ai coding assistant, claude code mcp,
diff --git a/claude-code-reference.yaml b/claude-code-reference.yaml
new file mode 100644
index 0000000..5e95ce9
--- /dev/null
+++ b/claude-code-reference.yaml
@@ -0,0 +1,281 @@
+# claude-code-reference.yaml
+# Quick lookup for Claude Code - ~2K tokens target
+# Source: english-ultimate-claude-code-guide.md
+
+version: "2.9.1"
+updated: "2026-01"
+
+# ════════════════════════════════════════════════════════════════
+# DEEP DIVE - Line references to main guide for detailed info
+# File: english-ultimate-claude-code-guide.md
+# ════════════════════════════════════════════════════════════════
+deep_dive:
+  installation: 185
+  first_workflow: 266
+  essential_commands: 315
+  permission_modes: 596
+  interaction_loop: 908
+  context_management: 944
+  plan_mode: 1458
+  rewind: 1636
+  mental_model: 1675
+  xml_prompting: 1731
+  memory_files: 2218
+  claude_folder: 2349
+  settings: 2400
+  precedence_rules: 2622
+  agents: 2720
+  agent_template: 2793
+  agent_examples: 2901
+  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
+  trinity_pattern: 5171
+  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
+
+# ════════════════════════════════════════════════════════════════
+# 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: "--think or --ultrathink"
+
+# ════════════════════════════════════════════════════════════════
+# 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)"
+  "--headless": "CI/CD mode"
+  "--model X": "select model"
+  "--dangerously-skip-permissions": "auto-accept ALL (danger)"
+  "--debug": "verbose output"
+  "--mcp-debug": "debug MCP servers"
+
+# ════════════════════════════════════════════════════════════════
+# 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"
+
+# ════════════════════════════════════════════════════════════════
+# THINK LEVELS - see deep_dive.trinity_pattern
+# ════════════════════════════════════════════════════════════════
+think:
+  "--think": "~4K tokens - moderate analysis"
+  "--think-hard": "~10K tokens - architecture"
+  "--ultrathink": "~32K tokens - critical redesign"
+
+# ════════════════════════════════════════════════════════════════
+# 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: "use --add-dir to limit loaded dirs"
+
+# ════════════════════════════════════════════════════════════════
+# 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"
+  - "load giant context → load only needed"
+  - "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"
diff --git a/llms.txt b/llms.txt
index 65efe08..0c6e247 100644
--- a/llms.txt
+++ b/llms.txt
@@ -127,6 +127,16 @@ CC BY-SA 4.0 - Free to share and adapt with attribution.
 5. **Want to audit your setup?** Use claude-setup-audit-prompt.md
 6. **Need templates?** Browse examples/ folder for ready-to-use configs
 
+## Machine-Optimized Reference
+
+For fast LLM parsing, see `claude-code-reference.yaml` (~2K tokens) - structured YAML with:
+- Decision tree for task routing
+- Prompting formula (WHAT/WHERE/HOW/VERIFY)
+- Commands, shortcuts, CLI flags
+- Context management zones and symptoms
+- MCP servers, think levels, cost optimization
+- Anti-patterns and troubleshooting
+
 ## Keywords
 
 Claude Code, Anthropic, CLI, AI-assisted development, coding assistant, context management, MCP servers, agents, skills, hooks, commands, Plan Mode, CLAUDE.md, memory files, CI/CD integration, autonomous workflows, developer productivity, AI coding tools