claude-code-ultimate-guide/machine-readable/reference.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.12.0"
updated: "2026-01-25"

# ════════════════════════════════════════════════════════════════
# 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:
  # AI-Assisted Development Workflows (from MetalBear/arXiv research)
  exploration_workflow: "guide/workflows/exploration-workflow.md"
  script_generation: "guide/workflows/iterative-refinement.md:192"
  anti_anchoring_prompts: "examples/semantic-anchors/anchor-catalog.md:240"
  session_limits: "guide/architecture.md:272"
  claudemd_sizing: 3054
  scope_success_rates: "guide/adoption-approaches.md:20"
  # Claude Code Releases
  claude_code_releases: "guide/claude-code-releases.md"
  claude_code_releases_yaml: "machine-readable/claude-code-releases.yaml"
  # Template Installation
  install_templates_script: "scripts/install-templates.sh"
  # 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"  # Local example only (gitignored)
  # Learning with AI (guide/learning-with-ai.md)
  learning_quick_check: "guide/learning-with-ai.md:31"
  learning_uval_protocol: "guide/learning-with-ai.md:127"
  learning_claude_config: "guide/learning-with-ai.md:353"
  learning_breaking_dependency: "guide/learning-with-ai.md:470"
  learning_embracing_ai: "guide/learning-with-ai.md:518"
  learning_30day_plan: "guide/learning-with-ai.md:710"
  learning_red_flags: "guide/learning-with-ai.md:770"
  learning_mode_template: "examples/claude-md/learning-mode.md"
  learn_quiz_command: "examples/commands/learn/quiz.md"
  learn_teach_command: "examples/commands/learn/teach.md"
  learn_alternatives_command: "examples/commands/learn/alternatives.md"
  learning_capture_hook: "examples/hooks/bash/learning-capture.sh"
  # Anti-patterns
  vibe_coding_trap: "guide/learning-with-ai.md:81"
  vibe_coding_context_overload: 8746
  vibe_coding_context_overload_source: "Jens Rusitschka, 'Vibe Coding, Level 2' (Jan 2026)"
  vibe_coding_phased_strategy: 8760
  # AI Traceability & Attribution (guide/ai-traceability.md) - Added 2026-01-24
  ai_traceability_guide: "guide/ai-traceability.md"
  ai_traceability_why: "guide/ai-traceability.md:25"
  ai_traceability_disclosure_spectrum: "guide/ai-traceability.md:63"
  ai_traceability_co_authored_by: "guide/ai-traceability.md:89"
  ai_traceability_assisted_by: "guide/ai-traceability.md:109"
  ai_traceability_git_ai: "guide/ai-traceability.md:262"
  ai_traceability_llvm_policy: "guide/ai-traceability.md:169"
  ai_traceability_ghostty_policy: "guide/ai-traceability.md:203"
  ai_traceability_fedora_policy: "guide/ai-traceability.md:227"
  ai_traceability_promptpwnd: "guide/ai-traceability.md:342"
  ai_traceability_implementation: "guide/ai-traceability.md:392"
  ai_traceability_templates: "guide/ai-traceability.md:440"
  # AI Disclosure Templates
  ai_disclosure_contributing: "examples/config/CONTRIBUTING-ai-disclosure.md"
  ai_disclosure_pr_template: "examples/config/PULL_REQUEST_TEMPLATE-ai.md"
  # TTS Integration (Agent Vibes) - Added 2026-01-22
  tts_integration_guide: "examples/integrations/agent-vibes/README.md"
  tts_installation: "examples/integrations/agent-vibes/installation.md"
  tts_voice_catalog: "examples/integrations/agent-vibes/voice-catalog.md"
  tts_troubleshooting: "examples/integrations/agent-vibes/troubleshooting.md"
  tts_workflow: "guide/workflows/tts-setup.md"
  tts_ai_ecosystem: "guide/ai-ecosystem.md:507"
  tts_hook_example: "examples/hooks/bash/tts-selective.sh"
  tts_claude_md_template: "examples/claude-md/tts-enabled.md"
  # Architecture internals (guide/architecture.md)
  architecture_visual_overview: "guide/architecture.md:41"
  architecture_visual_source: "https://www.linkedin.com/posts/mohamed-ali-ben-salem-2b777b9a_en-ce-moment-je-vois-passer-des-posts-du-activity-7420592149110362112-eY5a"
  architecture_master_loop: "guide/architecture.md:72"
  architecture_tools: "guide/architecture.md:155"
  architecture_context: "guide/architecture.md:208"
  architecture_subagents: "guide/architecture.md:315"
  architecture_permissions: "guide/architecture.md:385"
  architecture_mcp: "guide/architecture.md:506"
  architecture_mcp_visual: "guide/images/mcp-architecture-diagram.svg"
  architecture_philosophy: "guide/architecture.md:746"
  # Main guide (guide/ultimate-guide.md) - Updated 2026-01-20
  installation: 196
  first_workflow: 277
  essential_commands: 326
  trust_calibration: 1039
  working_with_images: 422
  wireframing_tools: 492
  figma_mcp: 529
  image_optimization: 594
  permission_modes: 760
  interaction_loop: 1299
  context_management: 1335
  context_triage: 1448
  session_vs_memory: 1481
  fresh_context_pattern: 1525
  subscription_limits: 1933
  subscription_token_budgets: 1948
  subscription_opus_ratio: 1946
  subscription_monitoring: 1985
  plan_mode: 2100
  rewind: 2278
  mental_model: 2360
  xml_prompting: 2419
  semantic_anchors: 2872
  semantic_anchors_catalog: "examples/semantic-anchors/anchor-catalog.md"
  memory_files: 3160
  claude_folder: 3413
  settings: 3464
  precedence_rules: 3686
  agents: 3827
  agent_template: 3900
  agent_examples: 4038
  skills: 4420
  skill_template: 4540
  skill_examples: 4608
  design_patterns_skill: 4799
  design_patterns_skill_location: "examples/skills/design-patterns/"
  design_patterns_skill_modes: "Detection, Suggestion, Evaluation"
  design_patterns_skill_patterns: "23 GoF patterns (Creational 5, Structural 7, Behavioral 11)"
  design_patterns_skill_stacks: "React, Angular, NestJS, Vue, Express, RxJS, Redux, ORMs"
  community_skills_cybersec: 4947
  community_skills_iac: 5030
  # Automatic skill generation (meta-skill)
  claudeception: "https://github.com/blader/Claudeception"
  claudeception_guide: 5095
  # Skill Lifecycle: Automatic improvement (added 2026-01-24)
  skill_lifecycle: 5118
  claude_reflect_system: 5161
  claude_reflect_system_repo: "https://github.com/haddock-development/claude-reflect-system"
  claude_reflect_system_agent_skills: "https://agent-skills.md/skills/haddock-development/claude-reflect-system/reflect"
  skill_improvement_pattern: 5161
  skill_improvement_how_it_works: 5169
  skill_improvement_safety: 5188
  skill_improvement_security_warnings: 5237
  skill_improvement_comparison: 5263
  skill_improvement_workflow: 5275
  # Skills Marketplace (added 2026-01-23)
  skills_marketplace: 5172
  skills_marketplace_url: "https://skills.sh/"
  skills_marketplace_github: "https://github.com/vercel-labs/agent-skills"
  skills_marketplace_install: "npx add-skill <owner/repo>"
  skills_marketplace_top_skills:
    - "vercel-react-best-practices: 35K+ installs"
    - "web-design-guidelines: 26.6K installs"
    - "supabase-postgres-best-practices: 1K+ installs"
    - "better-auth-best-practices: 2K+ installs"
    - "test-driven-development: 721 installs"
  skills_marketplace_status: "Community (Vercel Labs), launched Jan 21, 2026"
  skills_marketplace_changelog: "https://vercel.com/changelog/introducing-skills-the-open-agent-skills-ecosystem"
  # Plugin System & Community Marketplaces (updated 2026-01-24)
  plugins_system: 6863
  plugins_commands: 6876
  plugins_marketplace: 6890
  plugins_community_marketplaces: 7246  # New section with ecosystem stats
  plugins_recommended: "examples/plugins/"
  plugins_se_cove: "examples/plugins/se-cove.md"
  plugins_official_docs: "https://code.claude.com/docs/en/plugins"
  plugins_official_reference: "https://code.claude.com/docs/en/plugins-reference"
  plugins_official_marketplaces: "https://code.claude.com/docs/en/plugin-marketplaces"
  # Community plugin resources
  plugins_wshobson_agents:
    url: "https://github.com/wshobson/agents"
    stats: "67 plugins, 99 agents, 107 skills"
    updated: "2026-01-24"
  plugins_registry_claude_plugins_dev:
    url: "https://claude-plugins.dev"
    stats: "11,989 plugins, 63,065 skills indexed"
  plugins_registry_claudemarketplaces:
    url: "https://claudemarketplaces.com"
    purpose: "Auto-scan GitHub for .claude-plugin/marketplace.json"
  plugins_popular:
    - "Context7: ~72k installs (library docs lookup)"
    - "Ralph Wiggum: ~57k installs (code review)"
    - "Figma MCP: ~18k installs (design-to-code)"
    - "Linear MCP: ~9.5k installs (issue tracking)"
  plugins_awesome_list: "https://github.com/hesreallyhim/awesome-claude-code"
  plugins_awesome_list_stars: "20k+"
  chain_of_verification: "guide/methodologies.md:165"
  chain_of_verification_paper: "https://arxiv.org/abs/2309.11495"
  chain_of_verification_acl: "https://aclanthology.org/2024.findings-acl.212/"
  # Verification Loops & Eval Harness (added 2026-01-23)
  verification_loops: "guide/methodologies.md:145"
  verification_loops_source: "https://www.anthropic.com/engineering/claude-code-best-practices"
  eval_harness: "guide/methodologies.md:161"
  eval_harness_source: "https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents"
  # GSD (Get Shit Done) methodology (added 2026-01-25)
  gsd_methodology: "guide/methodologies.md:47"
  gsd_evaluation: "claudedocs/resource-evaluations/gsd-evaluation.md"
  gsd_source: "https://github.com/glittercowboy/get-shit-done"
  gsd_note: "Overlap with existing patterns (Ralph Loop, Gas Town, BMAD)"
  # Practitioner Insights (external validation)
  practitioner_insights: "guide/ai-ecosystem.md:1209"
  practitioner_dave_van_veen: "guide/ai-ecosystem.md:1213"
  practitioner_matteo_collina: "guide/ai-ecosystem.md:1243"
  practitioner_collina_source: "https://adventures.nodeland.dev/archive/the-human-in-the-loop/"
  # DevOps/SRE Guide (guide/devops-sre.md)
  devops_sre_guide: "guide/devops-sre.md"
  devops_fire_framework: "guide/devops-sre.md:50"
  devops_k8s_troubleshooting: "guide/devops-sre.md:120"
  devops_k8s_prompts: "guide/devops-sre.md:160"
  devops_incident_response: "guide/devops-sre.md:340"
  devops_iac_patterns: "guide/devops-sre.md:520"
  devops_guardrails: "guide/devops-sre.md:650"
  devops_limitations: "guide/devops-sre.md:290"
  devops_quick_reference: "guide/devops-sre.md:750"
  devops_agent: "examples/agents/devops-sre.md"
  devops_claude_md: "examples/claude-md/devops-sre.md"
  # Product Designer (design-to-code workflow)
  product_designer_workflow: "guide/workflows/design-to-code.md"
  product_designer_claudemd: "examples/claude-md/product-designer.md"
  design_system_handoff: "guide/workflows/design-to-code.md:531"
  figma_make_integration: "guide/workflows/design-to-code.md:26"
  pencil_canvas: "guide/ultimate-guide.md:529"
  pencil_workflow: "guide/workflows/design-to-code.md:447"
  pencil_vs_figma: "guide/workflows/design-to-code.md:470"
  commands: 4950
  command_template: 5020
  hooks: 5273
  hook_templates: 5418
  security_hooks: 5680
  mcp_servers: 5984
  serena_indexation: 6078
  serena_mcp: 6037
  doobidoo_memory_mcp: 6385
  mcp_memory_stack_patterns: 6524
  mcp_config: 6149
  mcp_security: 6517
  cicd: 6835
  ide_integration: 7524
  feedback_loops: 7594
  batch_operations: 8024
  pitfalls: 8143
  git_best_practices: 8412
  cost_optimization: 8878
  session_teleportation: 9477
  multi_instance_workflows: 9583
  boris_cherny_case_study: 9617
  anthropic_study_metrics: 9721
  git_worktrees_multi_instance: 10634
  advanced_worktree_tooling: 10661
  anthropic_internal_study: 10782
  multi_instance_costs: 10816
  orchestration_frameworks: 10853
  headless_pm_framework: 10865
  multi_instance_implementation: 10891
  multi_instance_monitoring: 10964
  multi_instance_decision_matrix: 11037
  # External orchestration systems
  external_orchestrators:
    gas_town:
      repo: "https://github.com/steveyegge/gastown"
      author: "Steve Yegge"
      description: "Multi-agent workspace manager using Claude Code instances"
      status: "Experimental (Jan 2026)"
      guide_section: "guide/ai-ecosystem.md:850"
    multiclaude:
      repo: "https://github.com/dlorenc/multiclaude"
      author: "dlorenc"
      description: "Self-hosted multi-agent Claude Code spawner (tmux + git worktrees)"
      status: "Active development (Jan 2026, 383 stars)"
      guide_section: "guide/ai-ecosystem.md:850"
    agent_chat:
      repo: "https://github.com/justinabrahms/agent-chat"
      author: "Justin Abrahms"
      description: "Real-time monitoring UI for Gas Town and multiclaude (SSE + SQLite)"
      status: "Early preview (Jan 2026, v0.2.0)"
      guide_section: "guide/ai-ecosystem.md:850"
  # Section 9.18 - Codebase Design for Agent Productivity
  codebase_design_agents: 9976
  codebase_design_source: "https://marmelab.com/blog/2026/01/21/agent-experience.html"
  codebase_design_author: "François Zaninotto (Marmelab)"
  commands_table: 10213
  shortcuts_table: 10246
  troubleshooting: 10372
  cheatsheet: 10747
  daily_workflow: 13581
  # AI Ecosystem (Section 11, ~line 10525)
  ai_ecosystem: 10525
  ai_ecosystem_complementarity: 10527
  ai_ecosystem_tool_matrix: 10565
  ai_ecosystem_workflows: 10590
  ai_ecosystem_integration: 10716
  ai_ecosystem_detailed: "guide/ai-ecosystem.md"
  ai_ecosystem_goose: "guide/ai-ecosystem.md:1116"
  ai_ecosystem_goose_comparison: "guide/ai-ecosystem.md:1132"
  ai_ecosystem_context_packing: "guide/ai-ecosystem.md:1208"
  # Architecture Diagrams as Context (advanced pattern) - Added 2026-01-25
  architecture_diagrams_input: "guide/ai-ecosystem.md:1379"
  architecture_diagrams_mcp_tools:
    - "Archy MCP: https://www.pulsemcp.com/servers/phxdev1-archy"
    - "Mermaid MCP: 61.4K users"
    - "Blueprint MCP (ArcadeAI)"
  llm_oop_research: "https://dl.acm.org/doi/10.1145/3639474.3640052"
  architecture_diagrams_source: "https://www.linkedin.com/posts/tigraff_uml-claude-wibecoding-activity-7420595633826258944-gGO5"
  ai_ecosystem_voice_to_text: "guide/ai-ecosystem.md:449"
  ai_ecosystem_alternative_providers: "guide/ai-ecosystem.md:959"
  voice_refine_skill: "examples/skills/voice-refine/SKILL.md"
  # Cowork documentation (v1.0 - migrated to dedicated repo)
  cowork_reference: "machine-readable/cowork-reference.yaml"  # Dedicated YAML index (kept local)
  cowork_hub: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/README.md"
  cowork_summary: "guide/cowork.md"  # Summary remains in this repo
  cowork_overview: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/00-overview.md"
  cowork_getting_started: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/01-getting-started.md"
  cowork_capabilities: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/02-capabilities.md"
  cowork_security: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/03-security.md"
  cowork_troubleshooting: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/04-troubleshooting.md"
  cowork_cheatsheet: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/cheatsheet.md"
  cowork_comparison: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/comparison.md"
  cowork_faq: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/faq.md"
  cowork_prompts: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts"
  cowork_workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows"
  cowork_section: "guide/ai-ecosystem.md:760"
  cowork_ultimate_guide: 10759
  # Appendix
  appendix_a_file_locations: 14356
  appendix_b_faq: 14530
  faq_clawdbot_vs_claudecode: 14532
  faq_product_managers: 14601

# ════════════════════════════════════════════════════════════════
# 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 Opus (thinking enabled by default) - Alt+T to toggle"

# ════════════════════════════════════════════════════════════════
# 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"
  /teleport: "bring web session to local CLI"
  /tasks: "monitor background tasks"
  /remote-env: "configure cloud environment"

# ════════════════════════════════════════════════════════════════
# SHORTCUTS - see deep_dive.shortcuts_table
# ════════════════════════════════════════════════════════════════
shortcuts:
  Shift+Tab: "cycle: default → auto-accept → plan"
  Esc×2: "rewind/undo"
  Ctrl+C: "interrupt"
  Ctrl+R: "retry"
  Ctrl+B: "background all tasks"
  "@file": "reference file"
  "!cmd": "shell command"

# ════════════════════════════════════════════════════════════════
# CLI FLAGS - see deep_dive.commands_table
# ════════════════════════════════════════════════════════════════
cli:
  "-c": "continue last session"
  "-r <id>": "resume specific session"
  "--teleport": "bring web session to local CLI"
  "-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"
  fresh_context: "Reset per task for long autonomous sessions - see Section 2.2 Fresh Context Pattern"
  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) + project indexation"
  doobidoo_memory: "semantic memory search + Knowledge Graph dashboard + 13+ clients (⚠️ under testing)"
  doobidoo_install: "pip install mcp-memory-service && python -m mcp_memory_service.scripts.installation.install --quick"
  doobidoo_dashboard: "http://localhost:8000"
  doobidoo_vs_serena: "Serena=key-value (requires known key), doobidoo=semantic search (finds by meaning)"
  doobidoo_backends: "sqlite_vec (local), cloudflare (multi-device), hybrid (local+cloud sync)"
  doobidoo_tools: "store_memory, retrieve_memory, search_by_tag, delete_memory, list_memories, check_database_health, memory_graph"
  doobidoo_data_location: "~/.mcp-memory-service/memories.db"
  mcp_memory_stack: "4 layers: doobidoo (decisions) → Serena (symbols) → grepai (code search) → Context7 (docs)"
  mcp_complementarity_patterns: "onboarding, ADR, debug persistence, multi-IDE coordination"
  serena_indexation: "uvx --from git+https://github.com/oraios/serena serena project index [--force-full|--incremental] [--parallel N]"
  serena_cache: ".serena/cache/typescript/ (add to .gitignore)"
  context7: "library docs lookup"
  sequential: "structured multi-step reasoning"
  playwright: "browser automation / E2E"
  figma: "design file access, tokens, structure (official)"
  ast_grep: "optional plugin for AST-based code search (explicit invocation required)"
  ast_grep_guide: "guide/ultimate-guide.md:6564"
  ast_grep_skill: "examples/skills/ast-grep-patterns.md"
  ast_grep_install: "npx skills add ast-grep/agent-skill"
  ast_grep_when: "structural patterns (>50k lines, migrations, AST rules)"
  ast_grep_not_for: "simple string search, small projects (<10k lines)"
  search_decision_tree: "grep (text) | ast-grep (structure) | Serena (symbols) | grepai (semantic)"
  grep_vs_rag_history: "guide/architecture.md:33"
  check: "/mcp"
  config: ".claude/mcp.json or ~/.claude.json"
  tool_search: "lazy loading MCP tools (v2.1.7+) - 85% token reduction - auto:N threshold config"
  tool_search_config: "ENABLE_TOOL_SEARCH=auto|auto:N|true|false"
  tool_search_deep_dive: "guide/architecture.md:534"

# ════════════════════════════════════════════════════════════════
# 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"

# ════════════════════════════════════════════════════════════════
# ECOSYSTEM - Related resources & positioning
# ════════════════════════════════════════════════════════════════
ecosystem:
  this_guide:
    focus: "Education - Learn & master"
    unique: ["architecture docs", "TDD/SDD methodologies", "227-question quiz", "YAML index"]
  complementary:
    claude_code_templates:
      url: "github.com/davila7/claude-code-templates"
      focus: "Distribution - Install & use (CLI)"
      stars: "17k+"
    awesome_claude_code:
      url: "github.com/hesreallyhim/awesome-claude-code"
      focus: "Curation - Discover & link"
    claude_code_everything:
      url: "github.com/wesammustafa/Claude-Code-Everything"
      focus: "Visual walkthrough - Screenshots, BMAD method"
    everything_claude_code:
      url: "github.com/affaan-m/everything-claude-code"
      author: "Affaan Mustafa (Anthropic hackathon winner - Zenith project)"
      focus: "Distribution - Plugin-ready configs collection"
      stars: "16k+"
      created: "2026-01-18"
      unique: ["Node.js cross-platform hooks", "15 MCP configs", "Plugin marketplace format"]
      note: "Consolidates existing patterns; author hackathon win was for Zenith project, not this repo"
      caveat: "Node.js hooks not officially recommended by Anthropic (shell preferred)"
    coding_agents_matrix:
      url: "coding-agents-matrix.dev"
      github: "github.com/PackmindHub/coding-agents-matrix"
      maintainer: "Packmind (Cédric Teyton, Arthur Magne)"
      license: "Apache-2.0"
      focus: "Interactive comparison of 23 AI coding agents across 11 criteria"
      updated: "2026-01-19"
      tech_stack: "React, Vite, Tailwind CSS"
      features:
        - "11 technical criteria (CLI, MCP, Skills, Commands, Subagents, Plan Mode, AGENTS.md, BYO LLM, Custom Rules, Dedicated IDE, IDE Extension)"
        - "Sortable columns and multi-filter (AND logic)"
        - "Community-driven updates (GitHub issue templates)"
        - "Open source data structure (JSON-based)"
      agents_snapshot: 23  # As of 2026-01-19 (evolves over time)
      positioning: "Discovery tool - Use Matrix to find/compare agents, use this guide to master Claude Code"
      note: "External resource - verify data freshness as agents/criteria evolve"
  practitioner_insights:
    dave_van_veen:
      url: "davevanveen.com/blog/agentic_coding/"
      author: "Dave Van Veen (PhD Stanford, Principal AI Scientist @ HOPPR)"
      focus: "Production-grade agentic coding guardrails (TDD, worktrees, manual commits)"
      academic: "Co-author 'Agentic Systems in Radiology' (ArXiv 2025)"
      alignment: "Validates patterns already documented in this guide"
      guide_section: "guide/ai-ecosystem.md:1209"
  install_templates: "scripts/install-templates.sh"
  cowork:
    description: "Claude Code for non-developers (desktop app)"
    status: "Research preview - Max/macOS only (Jan 2026)"
    blog: "https://claude.com/blog/cowork-research-preview"
    github: "https://github.com/FlorianBruniaux/claude-cowork-guide"
    guide_summary: "guide/cowork.md"  # Summary in this repo
    guide_full: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/README.md"
    getting_started: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/01-getting-started.md"
    capabilities: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/02-capabilities.md"
    security: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/03-security.md"
    troubleshooting: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/guide/04-troubleshooting.md"
    cheatsheet: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/cheatsheet.md"
    comparison: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/comparison.md"
    faq: "https://github.com/FlorianBruniaux/claude-cowork-guide/blob/main/reference/faq.md"
    prompts: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/prompts"
    workflows: "https://github.com/FlorianBruniaux/claude-cowork-guide/tree/main/workflows"
  landing_sites:
    description: "Marketing sites for guide discovery and navigation"
    architecture: "4-repo ecosystem: 2 sources (docs) + 2 landings (vitrine)"
    code_landing:
      local: "/Users/florianbruniaux/Sites/perso/claude-code-ultimate-guide-landing/"
      purpose: "Marketing site for Claude Code guide"
      audience: "Developers discovering the guide"
      features: ["badges (version, templates, lines)", "quiz (227 questions)", "FAQ", "cross-links to Cowork"]
      sync_with: "Guide Code (version, templates count, guide lines)"
    cowork_landing:
      local: "/Users/florianbruniaux/Sites/perso/claude-cowork-guide-landing/"
      purpose: "Marketing site for Cowork guide"
      audience: "Knowledge workers discovering Cowork"
      features: ["prompts showcase", "workflows preview", "cross-links to Code"]
      sync_with: "Cowork guide (version, prompts count)"
    sync_triggers:
      - "Version bump → Update corresponding landing"
      - "Templates/prompts added → Update counts"
      - "Cross-links modified → Update all 4 repos"
    history:
      - date: "2026-01-20"
        event: "Code Landing sync v3.12.0, 66 templates, cross-links"
        commit: "5b5ce62"
      - date: "2026-01-20"
        event: "Cowork Landing fix (paths, README, UI badges)"
        commits: "cab83f5, af497b7, 539912b"

# ════════════════════════════════════════════════════════════════
# 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"

deep_dive:
  - file: "guide/production-safety.md"
    lines: "1-550"
    topics:
      - "Port stability rules and implementation"
      - "Database safety with backup enforcement"
      - "Feature completeness (no TODOs for core functionality)"
      - "Infrastructure lock patterns"
      - "Dependency safety and npm install blocks"
      - "Pattern following and CLAUDE.md conventions"