marketing-shibata50/claude-code-ultimate-guide
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
claude-code-ultimate-guide/machine-readable/reference.yaml
Florian BRUNIAUX eee6a5a20a docs: add AI Coding Agents Matrix reference to ecosystem section 
Add link to coding-agents-matrix.dev in ai-ecosystem.md and reference.yaml.

This external resource provides a technical comparison of Claude Code vs 22+
alternatives across MCP support, Skills, Commands, Subagents, and Plan Mode.

Minimal integration (1-line note) to acknowledge the ecosystem without
diluting our focus on Claude Code mastery.
2026-01-20 15:00:39 +01:00

532 lines
28 KiB
YAML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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.9.7"
updated: "2026-01-20"
# ════════════════════════════════════════════════════════════════
# 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"
# 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) - 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: 1914
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
community_skills_cybersec: 4788
community_skills_iac: 4871
commands: 4939
command_template: 5009
hooks: 5262
hook_templates: 5407
security_hooks: 5669
mcp_servers: 5810
mcp_config: 6104
mcp_security: 6472
cicd: 6790
ide_integration: 7479
feedback_loops: 7549
batch_operations: 7979
pitfalls: 8098
git_best_practices: 8367
cost_optimization: 8833
session_teleportation: 9432
commands_table: 9608
shortcuts_table: 9641
troubleshooting: 9767
cheatsheet: 10142
daily_workflow: 10218
# AI Ecosystem (Section 11, ~line 10494)
ai_ecosystem: 10494
ai_ecosystem_complementarity: 10494
ai_ecosystem_tool_matrix: 10520
ai_ecosystem_workflows: 10545
ai_ecosystem_integration: 10671
ai_ecosystem_detailed: "guide/ai-ecosystem.md"
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: 10725
# ════════════════════════════════════════════════════════════════
# 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)"
context7: "library docs lookup"
sequential: "structured multi-step reasoning"
playwright: "browser automation / E2E"
figma: "design file access, tokens, structure (official)"
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"
# ════════════════════════════════════════════════════════════════
# 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"
coding_agents_matrix:
url: "coding-agents-matrix.dev"
focus: "Technical comparison - 23 agents, 11 criteria"
updated: "2026-01-19"
agents: 23
criteria: ["MCP", "Skills", "Commands", "Subagents", "Plan Mode"]
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.9.7, 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"
Reference in a new issue View git blame Copy permalink