refactor: restructure repo into thematic directories v3.1.0

Major repository reorganization for improved navigation: New directory structure: - guide/ - Core documentation (ultimate-guide, cheatsheet, adoption) - tools/ - Interactive utilities (audit, onboarding, mobile-access) - machine-readable/ - LLM/AI consumption (reference.yaml, llms.txt) - exports/ - Generated outputs (PDFs) Changes: - Move 10 files to thematic directories with cleaner names - Create README.md index for each new directory - Update 150+ internal links across all documentation - Add "Repository Structure" section to main README - Remove redundant npm install command from README header - Remove unverified cost estimate from prerequisites - Fix broken anchor link (#-quick-start-15-minutes) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-13 15:30:02 +01:00 · 2026-01-13 15:30:02 +01:00 · bc07651cdf
commit bc07651cdf
parent 06b9fe2c51
35 changed files with 450 additions and 282 deletions
--- a/machine-readable/README.md
+++ b/machine-readable/README.md
@ -0,0 +1,33 @@
+# Machine-Readable References
+
+Files optimized for LLM/AI consumption.
+
+## Contents
+
+| File | Description | Tokens |
+|------|-------------|--------|
+| [reference.yaml](./reference.yaml) | Structured index with line numbers for deep dives | ~2K |
+| [llms.txt](./llms.txt) | Standard LLM context file for repository indexation | ~1.5K |
+
+## Usage
+
+### Give Claude Code instant expertise
+
+```bash
+# Paste into any AI assistant
+curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml
+```
+
+### Reference in Claude Code
+
+```
+@machine-readable/reference.yaml
+```
+
+### Add to system prompts
+
+Include the YAML content in your AI assistant's system prompt for Claude Code expertise.
+
+---
+
+*Back to [main README](../README.md)*
--- a/machine-readable/llms.txt
+++ b/machine-readable/llms.txt
@ -0,0 +1,153 @@
+# The Ultimate Claude Code Guide
+
+> A comprehensive, self-contained guide to mastering Claude Code - Anthropic's official CLI for AI-assisted development.
+
+## What This Repository Contains
+
+This repository provides everything needed to go from Claude Code beginner to power user:
+
+1. **Complete Guide** (`guide/ultimate-guide.md`) - 4700+ lines covering all aspects of Claude Code
+2. **Cheatsheet** (`guide/cheatsheet.md`) - 1-page printable daily reference
+3. **Audit Prompt** (`tools/audit-prompt.md`) - Self-contained prompt to analyze your Claude Code setup against best practices
+
+## Target Audience
+
+- **Beginners**: Installation, first workflow, essential commands (15 min to productivity)
+- **Intermediate**: Memory files, agents, skills, hooks configuration
+- **Power Users**: MCP servers, Trinity pattern, CI/CD integration, autonomous workflows
+
+## Key Topics Covered
+
+### Core Concepts
+- Context Management (the most critical concept - context windows, compaction, zones)
+- Plan Mode (safe read-only exploration before making changes)
+- Memory Files (CLAUDE.md for persistent context across sessions)
+- Rewind (undo mechanism for file changes)
+
+### Customization
+- **Agents**: Custom AI personas with specific tools and instructions
+- **Skills**: Reusable knowledge modules for complex domains
+- **Commands**: Custom slash commands for frequent workflows
+- **Hooks**: Event-driven automation (PreToolUse, PostToolUse, UserPromptSubmit)
+
+### Advanced Features
+- **MCP Servers**: Model Context Protocol for extended capabilities
+  - Serena (codebase indexation + session memory)
+  - Context7 (library documentation lookup)
+  - Sequential (structured multi-step reasoning)
+  - Playwright (browser automation)
+- **Trinity Pattern**: Combining Plan Mode + Think Levels + MCP for complex tasks
+- **CI/CD Integration**: Headless mode, GitHub Actions, Verify Gate pattern
+
+### Best Practices
+- Single Source of Truth pattern for conventions
+- Shell Scripts vs AI Agents decision framework
+- Tight feedback loops for rapid iteration
+- Continuous improvement mindset
+
+## File Structure
+
+```
+claude-code-ultimate-guide/
+├── README.md                           # Overview and quick start
+├── CONTRIBUTING.md                     # Contribution guidelines
+├── CHANGELOG.md                        # Version history
+├── LICENSE                             # CC BY-SA 4.0
+├── guide/                              # Core documentation
+│   ├── ultimate-guide.md               # Complete guide (main content)
+│   ├── cheatsheet.md                   # 1-page reference
+│   └── adoption-approaches.md          # Implementation strategy
+├── tools/                              # Interactive utilities
+│   ├── audit-prompt.md                 # Setup audit tool
+│   ├── onboarding-prompt.md            # Personalized onboarding
+│   └── mobile-access.md                # Mobile access setup
+├── machine-readable/                   # LLM/AI consumption
+│   ├── reference.yaml                  # Machine-optimized index
+│   └── llms.txt                        # This file (for AI indexation)
+├── exports/                            # Generated outputs
+│   ├── notebooklm.pdf                  # Visual overview
+│   └── kimi.pdf                        # Full text export
+├── examples/                           # Ready-to-use templates
+│   ├── agents/                         # Custom AI personas
+│   ├── skills/                         # Knowledge modules
+│   ├── commands/                       # Slash commands
+│   ├── hooks/                          # Event automation (bash + PowerShell)
+│   ├── config/                         # Configuration files
+│   └── memory/                         # CLAUDE.md templates
+└── quiz/                               # Interactive knowledge quiz
+```
+
+## Guide Structure (10 Sections)
+
+1. **Quick Start** - Installation, first workflow, essential commands
+2. **Core Concepts** - Context management, Plan Mode, Rewind, Mental Model
+3. **Memory & Settings** - CLAUDE.md files, .claude/ folder, precedence rules
+4. **Agents** - Custom AI personas, Tool SEO, orchestration patterns
+5. **Skills** - Reusable knowledge modules
+6. **Commands** - Custom slash commands, variable interpolation
+7. **Hooks** - Event-driven automation (security, formatting, logging)
+8. **MCP Servers** - Serena, Context7, Sequential, Playwright, Postgres
+9. **Advanced Patterns** - Trinity, CI/CD, feedback loops, vibe coding
+10. **Reference** - Commands, shortcuts, troubleshooting, checklists
+
+## Key Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/help` | Show all available commands |
+| `/status` | Check context usage and session state |
+| `/compact` | Compress context (use when >70%) |
+| `/clear` | Fresh start (reset conversation) |
+| `/plan` | Enter safe read-only planning mode |
+| `/rewind` | Undo recent changes |
+
+## Context Management Rules
+
+- **Green Zone (0-50%)**: Work freely
+- **Yellow Zone (50-70%)**: Be selective with context loading
+- **Red Zone (70-90%)**: Use `/compact` immediately
+- **Critical (90%+)**: Use `/clear` to reset
+
+## Platform Support
+
+- **macOS/Linux**: Full support with bash/zsh examples
+- **Windows**: PowerShell and batch file alternatives provided (note: Windows commands are AI-generated and not tested by the author)
+
+## Related Resources
+
+- Official: https://docs.anthropic.com/en/docs/claude-code
+- DeepWiki: https://deepwiki.com/FlorianBruniaux/claude-code-ultimate-guide
+- Inspiration: https://claudelog.com/
+
+## Author
+
+Florian BRUNIAUX - Founding Engineer at Méthode Aristote
+- GitHub: https://github.com/FlorianBruniaux
+- LinkedIn: https://www.linkedin.com/in/florian-bruniaux-43408b83/
+
+## License
+
+CC BY-SA 4.0 - Free to share and adapt with attribution.
+
+## How to Use This Guide
+
+1. **New to Claude Code?** Start with README.md Quick Start section
+2. **Choose your path** See Learning Paths in README for audience-specific guides
+3. **Want comprehensive learning?** Read guide/ultimate-guide.md
+4. **Need daily reference?** Print guide/cheatsheet.md
+5. **Want to audit your setup?** Use tools/audit-prompt.md
+6. **Need templates?** Browse examples/ folder for ready-to-use configs
+
+## Machine-Optimized Reference
+
+For fast LLM parsing, see `machine-readable/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
--- a/machine-readable/reference.yaml
+++ b/machine-readable/reference.yaml
@ -0,0 +1,288 @@
+# 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: "2.9.9"
+updated: "2026-01"
+
+# ════════════════════════════════════════════════════════════════
+# DEEP DIVE - Line numbers in guide/ultimate-guide.md
+# Usage: Read file at line N for detailed documentation on topic
+# ════════════════════════════════════════════════════════════════
+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
+  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: "--think or --ultrathink"
+  learning: "--learn (want to understand decisions)"
+
+# ════════════════════════════════════════════════════════════════
+# 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"
+  "--learn": "enable learning mode (explanations)"
+  "--learn focus:X": "learn only for domain (git/arch/sec)"
+  "--no-learn": "suppress learning offers"
+
+# ════════════════════════════════════════════════════════════════
+# 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"