# Claude Code Ultimate Guide

Website

Stars Last Update Quiz Templates Threat Database MCP Server

Mentioned in Awesome Claude Code License: CC BY-SA 4.0 SkillHub Skills Ask Zread

> **6 months of daily practice** distilled into a guide that teaches you the WHY, not just the what. From core concepts to production security, you learn to design your own agentic workflows instead of copy-pasting configs. > **If this guide helps you, [give it a star ⭐](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/stargazers)** β€” it helps others discover it too. --- ## Choose Your Path | Who you are | Your guide | |---|---| | πŸ—οΈ **Tech Lead / Engineering Manager** | [Deploying Claude Code across your team β†’](docs/for-tech-leads.md) | | πŸ“Š **CTO / Decision Maker** | [ROI, security posture, team adoption β†’](docs/for-cto.md) | | πŸ’Ό **CIO / CEO** | [Budget, risk, what to ask your tech team (3 min) β†’](docs/for-cio-ceo.md) | | 🎨 **Product Manager / Designer** | [Vibe coding, working with AI-assisted dev teams β†’](docs/for-product-managers.md) | | ✍️ **Writer / Ops / Manager** | [Claude Cowork Guide (separate repo) β†’](https://github.com/FlorianBruniaux/claude-cowork-guide) | | πŸ‘¨β€πŸ’» **Developer (all levels)** | You're in the right place β€” read on ↓ | | 🧭 **Career pivot / new AI role** | [AI Roles & Career Paths β†’](guide/roles/ai-roles.md) | --- ## 🎯 What You'll Learn **This guide teaches you to think differently about AI-assisted development:** - βœ… **Understand trade-offs** β€” When to use agents vs skills vs commands (not just how to configure them) - βœ… **Build mental models** β€” How Claude Code works internally (architecture, context flow, tool orchestration) - βœ… **Visualize concepts** β€” 41 Mermaid diagrams covering model selection, master loop, memory hierarchy, multi-agent patterns, security threats, AI fluency paths - βœ… **Master methodologies** β€” TDD, SDD, BDD with AI collaboration (not just templates) - βœ… **Security mindset** β€” Threat modeling for AI systems (only guide with 24 CVEs + 655 malicious skills database) - βœ… **Test your knowledge** β€” 271-question quiz to validate understanding (no other resource offers this) **Outcome**: Go from copy-pasting configs to designing your own agentic workflows with confidence. --- ## πŸ“Š When to Use This Guide vs Everything-CC Both guides serve different needs. Choose based on your priority. | Your Goal | This Guide | everything-claude-code | |-----------|------------|------------------------| | **Understand why** patterns work | Deep explanations + architecture | Config-focused | | **Quick setup** for projects | Available but not the priority | Battle-tested production configs | | **Learn trade-offs** (agents vs skills) | Decision frameworks + comparisons | Lists patterns, no trade-off analysis | | **Security hardening** | Only threat database (24 CVEs) | Basic patterns only | | **Test understanding** | 271-question quiz | Not available | | **Methodologies** (TDD/SDD/BDD) | Full workflow guides | Not covered | | **Copy-paste ready** templates | 218 templates | 200+ templates | ### Ecosystem Positioning ``` EDUCATIONAL DEPTH β–² β”‚ β”‚ β˜… This Guide β”‚ Security + Methodologies + 22K lines β”‚ β”‚ [Everything-You-Need-to-Know] β”‚ SDLC/BMAD beginner ─────────────────────────┼─────────────────────────► READY-TO-USE [awesome-claude-code] β”‚ [everything-claude-code] (discovery, curation) β”‚ (plugin, 1-cmd install) β”‚ β”‚ [claude-code-studio] β”‚ Context management β”‚ SPECIALIZED ``` **4 unique gaps no competitor covers:** 1. **Security-First** β€” 24 CVEs + 655 malicious skills tracked (no competitor has this depth) 2. **Methodology Workflows** β€” TDD/SDD/BDD comparison + step-by-step guides 3. **Comprehensive Reference** β€” 22K lines across 16 specialized guides (24Γ— more reference material than everything-cc) 4. **Educational Progression** β€” 271-question quiz, beginner β†’ expert path **Recommended workflow:** 1. Learn concepts here (mental models, trade-offs, security) 2. Use battle-tested configs there (quick project setup) 3. Return here for deep dives (when something doesn't work or to design custom workflows) **Both resources are complementary, not competitive.** Use what fits your current need. --- ## ⚑ Quick Start **Quickest path**: [Cheat Sheet](./guide/cheatsheet.md) β€” 1 printable page with daily essentials **Interactive onboarding** (no setup needed): ```bash claude "Fetch and follow the onboarding instructions from: https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/tools/onboarding-prompt.md" ``` **Browse directly**: [Full Guide](./guide/ultimate-guide.md) | [Visual Diagrams](./guide/diagrams/) | [Examples](./examples/) | [Quiz](./quiz/) --- ## πŸ”Œ MCP Server β€” Use the guide from any Claude Code session No cloning needed. Add to `~/.claude.json` and ask questions directly from any session: ```json { "mcpServers": { "claude-code-guide": { "type": "stdio", "command": "npx", "args": ["-y", "claude-code-ultimate-guide-mcp"] } } } ``` 17 tools: `search_guide`, `read_section`, `get_cheatsheet`, `get_digest`, `get_example`, `list_examples`, `search_examples`, `get_release`, `get_changelog`, `compare_versions`, `list_topics`, `get_threat`, `list_threats`, plus `init_official_docs`, `refresh_official_docs`, `diff_official_docs`, `search_official_docs` (v1.1.0 β€” official Anthropic docs tracker) β€” plus 13 slash commands `/ccguide:*` and a Haiku agent. **Onboarding one-liner** (once MCP is configured): ```bash claude "Use the claude-code-guide MCP server. Activate the claude-code-expert prompt, then run a personalized onboarding: ask me 3 questions about my goal, experience level, and preferred tone β€” then build a custom learning path using search_guide and read_section to navigate the guide with live source links." ``` β†’ [MCP Server README](./mcp-server/README.md) --- ## πŸ“ Repository Structure ```mermaid graph LR root[πŸ“¦ Repository
Root] root --> guide[πŸ“– guide/
22K lines] root --> examples[πŸ“‹ examples/
218 templates] root --> quiz[🧠 quiz/
271 questions] root --> tools[πŸ”§ tools/
utils] root --> machine[πŸ€– machine-readable/
AI index] root --> docs[πŸ“š docs/
115 evaluations] style root fill:#d35400,stroke:#e67e22,stroke-width:3px,color:#fff style guide fill:#2980b9,stroke:#3498db,stroke-width:2px,color:#fff style examples fill:#8e44ad,stroke:#9b59b6,stroke-width:2px,color:#fff style quiz fill:#d68910,stroke:#f39c12,stroke-width:2px,color:#fff style tools fill:#5d6d7e,stroke:#7f8c8d,stroke-width:2px,color:#fff style machine fill:#138d75,stroke:#16a085,stroke-width:2px,color:#fff style docs fill:#c0392b,stroke:#e74c3c,stroke-width:2px,color:#fff ```
Detailed Structure (Text View) ``` πŸ“¦ claude-code-ultimate-guide/ β”‚ β”œβ”€ πŸ“– guide/ Core Documentation (22K+ lines) β”‚ β”œβ”€ ultimate-guide.md Complete reference, 10 sections β”‚ β”œβ”€ cheatsheet.md 1-page printable β”‚ β”œβ”€ architecture.md How Claude Code works internally β”‚ β”œβ”€ methodologies.md TDD, SDD, BDD workflows β”‚ β”œβ”€ diagrams/ 41 Mermaid diagrams (10 thematic files) β”‚ β”œβ”€ third-party-tools.md Community tools (RTK, ccusage, Entire CLI) β”‚ β”œβ”€ mcp-servers-ecosystem.md Official & community MCP servers β”‚ └─ workflows/ Step-by-step guides β”‚ β”œβ”€ πŸ“‹ examples/ 204 Production Templates β”‚ β”œβ”€ agents/ 9 custom AI personas β”‚ β”œβ”€ commands/ 26 slash commands β”‚ β”œβ”€ hooks/ 31 hooks (bash + PowerShell) β”‚ β”œβ”€ skills/ 14 skills (9 on SkillHub) β”‚ └─ scripts/ Utility scripts (audit, search) β”‚ β”œβ”€ 🧠 quiz/ 271 Questions β”‚ β”œβ”€ 9 categories Setup, Agents, MCP, Trust, Advanced... β”‚ β”œβ”€ 4 profiles Junior, Senior, Power User, PM β”‚ └─ Instant feedback Doc links + score tracking β”‚ β”œβ”€ πŸ”§ tools/ Interactive Utilities β”‚ β”œβ”€ onboarding-prompt Personalized guided tour β”‚ └─ audit-prompt Setup audit & recommendations β”‚ β”œβ”€ πŸ€– machine-readable/ AI-Optimized Index β”‚ β”œβ”€ reference.yaml Structured index (~2K tokens) β€” powers landing site CMD+K search β”‚ β”œβ”€ claude-code-releases.yaml Structured releases changelog β”‚ └─ llms.txt Standard LLM context file β”‚ └─ πŸ“š docs/ 115 Resource Evaluations └─ resource-evaluations/ 5-point scoring, source attribution ```
--- ## 🎯 What Makes This Guide Unique ### πŸŽ“ Deep Understanding Over Configuration **Outcome**: Design your own workflows instead of copy-pasting blindly. **We teach how Claude Code works and why patterns matter**: - [Architecture](./guide/core/architecture.md) β€” Internal mechanics (context flow, tool orchestration, memory management) - [Trade-offs](./guide/ultimate-guide.md#when-to-use-what) β€” Decision frameworks for agents vs skills vs commands - [Configuration Decision Guide](./guide/ultimate-guide.md#27-configuration-decision-guide) β€” Unified "which mechanism for what?" map across all 7 config layers - [Pitfalls](./guide/ultimate-guide.md#common-mistakes) β€” Common failure modes + prevention strategies **What this means for you**: Troubleshoot issues independently, optimize for your specific use case, know when to deviate from patterns. --- ### πŸ–ΌοΈ Visual Diagrams Series (41 Mermaid Diagrams) **Outcome**: Grasp complex concepts instantly through visual mental models. **41 interactive diagrams** across 10 thematic files β€” GitHub-native Mermaid rendering + ASCII fallback for every diagram: - [Foundations](./guide/diagrams/01-foundations.md) β€” 4-layer context model, 9-step pipeline, permission modes - [Architecture](./guide/diagrams/04-architecture-internals.md) β€” Master loop, tool categories, system prompt assembly - [Multi-Agent](./guide/diagrams/07-multi-agent-patterns.md) β€” 3 topologies, worktrees, dual-instance, horizontal scaling - [Security](./guide/diagrams/08-security-and-production.md) β€” 3-layer defense, MCP rug pull attack chain, verification paradox - [Cost & Models](./guide/diagrams/09-cost-and-optimization.md) β€” Model selection tree, token reduction pipeline [Browse all 41 diagrams β†’](./guide/diagrams/) **What this means for you**: Understand the master loop before reading 22K lines, see multi-agent topologies at a glance, share visual security threat models with your team. --- ### πŸ›‘οΈ Security Threat Intelligence (Only Comprehensive Database) **Outcome**: Protect production systems from AI-specific attacks. **Only guide with systematic threat tracking**: - **24 CVE-mapped vulnerabilities** β€” Prompt injection, data exfiltration, code injection - **655 malicious skills catalogued** β€” Unicode injection, hidden instructions, auto-execute patterns - **Production hardening workflows** β€” MCP vetting, injection defense, audit automation [Threat Database β†’](./machine-readable/threat-db.yaml) | [Security Guide β†’](./guide/security/security-hardening.md) **What this means for you**: Vet MCP servers before trusting them, detect attack patterns in configs, comply with security audits. --- ### πŸ“ 271-Question Knowledge Validation (Unique in Ecosystem) **Outcome**: Verify your understanding + identify knowledge gaps. **Only comprehensive assessment available** β€” test across 9 categories: - Setup & Configuration, Agents & Sub-Agents, MCP Servers, Trust & Verification, Advanced Patterns **Features**: 4 skill profiles (Junior/Senior/Power User/PM), instant feedback with doc links, weak area identification [Try Quiz Online β†’](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/quiz/) | [Run Locally](./quiz/) **What this means for you**: Know what you don't know, track learning progress, prepare for team adoption discussions. --- ### πŸ€– Agent Teams Coverage (v2.1.32+ Experimental) **Outcome**: Parallelize work on large codebases (Fountain: 50% faster, CRED: 2x speed). **Only comprehensive guide to Anthropic's multi-agent coordination**: - Production metrics from real companies (autonomous C compiler, 500K hours saved) - 5 validated workflows (multi-layer review, parallel debugging, large-scale refactoring) - Decision framework: Teams vs Multi-Instance vs Dual-Instance vs Beads [Agent Teams Workflow β†’](./guide/workflows/agent-teams.md) | [Section 9.20 β†’](./guide/ultimate-guide.md#920-agent-teams-multi-agent-coordination) **What this means for you**: Break monolithic tasks into parallelizable work, coordinate multi-file refactors, review your own AI-generated code. --- ### πŸ”¬ Methodologies (Structured Development Workflows) **Outcome**: Maintain code quality while working with AI. Complete guides with rationale and examples: - [TDD](./guide/core/methodologies.md#1-tdd-test-driven-development-with-claude) β€” Test-Driven Development (Red-Green-Refactor with AI) - [SDD](./guide/core/methodologies.md#2-sdd-specification-driven-development) β€” Specification-Driven Development (Design before code) - [BDD](./guide/core/methodologies.md#3-bdd-behavior-driven-development) β€” Behavior-Driven Development (User stories β†’ tests) - [GSD](./guide/core/methodologies.md#gsd-get-shit-done) β€” Get Shit Done (Pragmatic delivery) **What this means for you**: Choose the right workflow for your team culture, integrate AI into existing processes, avoid technical debt from AI over-reliance. --- ### πŸ“š 204 Annotated Templates **Outcome**: Learn patterns, not just configs. Educational templates with explanations: - Agents (6), Commands (26), Hooks (31), Skills - Comments explaining **why** each pattern works (not just what it does) - Gradual complexity progression (simple β†’ advanced) [Browse Catalog β†’](./examples/) **What this means for you**: Understand the reasoning behind patterns, adapt templates to your context, create your own custom patterns. --- ### πŸ” 115 Resource Evaluations **Outcome**: Trust our recommendations are evidence-based. Systematic assessment of external resources (5-point scoring): - Articles, videos, tools, frameworks - Honest assessments with source attribution (no marketing fluff) - Integration recommendations with trade-offs [See Evaluations β†’](./docs/resource-evaluations/) **What this means for you**: Save time vetting resources, understand limitations before adopting tools, make informed decisions. --- ## 🎯 Learning Paths
Junior Developer β€” Foundation path (7 steps) 1. [Quick Start](./guide/ultimate-guide.md#1-quick-start-day-1) β€” Install & first workflow 2. [Essential Commands](./guide/ultimate-guide.md#13-essential-commands) β€” The 7 commands 3. [Context Management](./guide/ultimate-guide.md#22-context-management) β€” Critical concept 4. [Memory Files](./guide/ultimate-guide.md#31-memory-files-claudemd) β€” Your first CLAUDE.md 5. [Learning with AI](./guide/roles/learning-with-ai.md) β€” Use AI without becoming dependent ⭐ 6. [TDD Workflow](./guide/workflows/tdd-with-claude.md) β€” Test-first development 7. [Cheat Sheet](./guide/cheatsheet.md) β€” Print this
Senior Developer β€” Intermediate path (6 steps) 1. [Core Concepts](./guide/ultimate-guide.md#2-core-concepts) β€” Mental model 2. [Plan Mode](./guide/ultimate-guide.md#23-plan-mode) β€” Safe exploration 3. [Methodologies](./guide/core/methodologies.md) β€” TDD, SDD, BDD reference 4. [Agents](./guide/ultimate-guide.md#4-agents) β€” Custom AI personas 5. [Hooks](./guide/ultimate-guide.md#7-hooks) β€” Event automation 6. [CI/CD Integration](./guide/ultimate-guide.md#93-cicd-integration) β€” Pipelines
Power User β€” Comprehensive path (8 steps) 1. [Complete Guide](./guide/ultimate-guide.md) β€” End-to-end 2. [Architecture](./guide/core/architecture.md) β€” How Claude Code works 3. [Security Hardening](./guide/security/security-hardening.md) β€” MCP vetting, injection defense 4. [MCP Servers](./guide/ultimate-guide.md#8-mcp-servers) β€” Extended capabilities 5. [Trinity Pattern](./guide/ultimate-guide.md#91-the-trinity) β€” Advanced workflows 6. [Observability](./guide/ops/observability.md) β€” Monitor costs & sessions 7. [Agent Teams](./guide/workflows/agent-teams.md) β€” Multi-agent coordination (Opus 4.6 experimental) 8. [Examples](./examples/) β€” Production templates
Product Manager / DevOps / Designer **Product Manager** (5 steps): 1. [What's Inside](#-whats-inside) β€” Scope overview 2. [Golden Rules](#-golden-rules) β€” Key principles 3. [Data Privacy](./guide/security/data-privacy.md) β€” Retention & compliance 4. [Adoption Approaches](./guide/roles/adoption-approaches.md) β€” Team strategies 5. [PM FAQ](./guide/ultimate-guide.md#can-product-managers-use-claude-code) β€” Code-adjacent vs non-coding PMs **Note**: Non-coding PMs should consider [Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide) instead. **DevOps / SRE** (5 steps): 1. [DevOps & SRE Guide](./guide/ops/devops-sre.md) β€” FIRE framework 2. [K8s Troubleshooting](./guide/ops/devops-sre.md#kubernetes-troubleshooting) β€” Symptom-based prompts 3. [Incident Response](./guide/ops/devops-sre.md#pattern-incident-response) β€” Workflows 4. [IaC Patterns](./guide/ops/devops-sre.md#pattern-infrastructure-as-code) β€” Terraform, Ansible 5. [Guardrails](./guide/ops/devops-sre.md#guardrails--adoption) β€” Security boundaries **Product Designer** (5 steps): 1. [Working with Images](./guide/ultimate-guide.md#24-working-with-images) β€” Image analysis 2. [Wireframing Tools](./guide/ultimate-guide.md#wireframing-tools) β€” ASCII/Excalidraw 3. [Figma MCP](./guide/ultimate-guide.md#figma-mcp) β€” Design file access 4. [Design-to-Code Workflow](./guide/workflows/design-to-code.md) β€” Figma β†’ Claude 5. [Cheat Sheet](./guide/cheatsheet.md) β€” Print this
### Progressive Journey - **Week 1**: Foundations (install, CLAUDE.md, first agent) - **Week 2**: Core Features (skills, hooks, trust calibration) - **Week 3**: Advanced (MCP servers, methodologies) - **Month 2+**: Production mastery (CI/CD, observability) --- ## πŸ”§ Rate Limits & Cost Savings **cc-copilot-bridge** routes Claude Code through GitHub Copilot Pro+ for flat-rate access ($10/month instead of per-token billing). ```bash # Install git clone https://github.com/FlorianBruniaux/cc-copilot-bridge.git && cd cc-copilot-bridge && ./install.sh # Use ccc # Copilot mode (flat $10/month) ccd # Direct Anthropic mode (per-token) cco # Offline mode (Ollama, 100% local) ``` **Benefits**: Multi-provider switching, rate limit bypass, 99%+ cost savings on heavy usage. β†’ **[cc-copilot-bridge](https://github.com/FlorianBruniaux/cc-copilot-bridge)** --- ## πŸ”‘ Golden Rules ### 1. Verify Trust Before Use Claude Code can generate 1.75x more logic errors than human-written code ([ACM 2025](https://dl.acm.org/doi/10.1145/3716848)). Every output must be verified. Use `/insights` commands and verify patterns through tests. **Strategy:** Solo dev (verify logic + edge cases). Team (systematic peer review). Production (mandatory gating tests). --- ### 2. Never Approve MCPs from Unknown Sources 24 CVEs identified in Claude Code ecosystem. 655 malicious skills in supply chain. MCP servers can read/write your codebase. **Strategy:** Systematic audit (5-min checklist). Community-vetted MCP Safe List. Vetting workflow documented in guide. --- ### 3. Context Pressure Changes Behavior At 70% context, Claude starts losing precision. At 85%, hallucinations increase. At 90%+, responses become erratic. **Strategy:** 0-50% (work freely). 50-70% (attention). 70-90% (`/compact`). 90%+ (`/clear` mandatory). --- ### 4. Start Simple, Scale Smart Start with basic CLAUDE.md + a few commands. Test in production for 2 weeks. Add agents/skills only if need is proven. **Strategy:** Phase 1 (basic). Phase 2 (commands + hooks if needed). Phase 3 (agents if multi-context). Phase 4 (MCP servers if truly required). --- ### 5. Methodologies Matter More with AI TDD/SDD/BDD are not optional with Claude Code. AI accelerates bad code as much as good code. **Strategy:** TDD (critical logic). SDD (architecture upfront). BDD (PM/dev collaboration). GSD (throwaway prototypes). --- ### Quick Reference | # | Rule | Key Metric | Action | |---|------|------------|--------| | 1 | Verify Trust | 1.75x more logic errors | Test everything, peer review | | 2 | Vet MCPs | 24 CVEs, 655 malicious skills | 5-min audit checklist | | 3 | Manage Context | 70% = precision loss | `/compact` at 70%, `/clear` at 90% | | 4 | Start Simple | 2-week test period | Phase 1β†’4 progressive adoption | | 5 | Use Methodologies | AI amplifies good AND bad | TDD/SDD/BDD by context | > Context management is critical. See the [Cheat Sheet](./guide/cheatsheet.md#context-management-critical) for thresholds and actions. --- ## πŸ€– For AI Assistants | Resource | Purpose | Tokens | |----------|---------|--------| | **[llms.txt](./machine-readable/llms.txt)** | Standard context file | ~1K | | **[reference.yaml](./machine-readable/reference.yaml)** | Structured index with line numbers | ~2K | **Quick load**: `curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml` ### reference.yaml β€” Structure & Landing Site Search `reference.yaml` is organized into several top-level sections: | Section | Content | |---------|---------| | `lines` | Line number references for key sections in `ultimate-guide.md` | | `deep_dive` | Key β†’ file path mappings for all guides, examples, hooks, agents, commands | | `decide` | Decision tree (when to use what) | | `stats` | Counters (templates, questions, CVEs…) | **The `deep_dive` section powers the [landing site](https://cc.bruniaux.com) CMD+K search.** The build script (`scripts/build-guide-index.mjs`) parses it to generate 160 search entries. #### How the search index works The CMD+K search on the landing site is an **explicit index** β€” not a full-text search. Only entries listed in `deep_dive` are indexed. Keywords are derived mechanically from the key name and file path, not from the file content. **Consequence**: adding a new guide section requires explicitly adding an entry to `deep_dive`, then running `pnpm build:search` in the landing repo. #### Maintaining reference.yaml **Adding a new entry** to `deep_dive`: ```yaml deep_dive: # existing entries... my_new_section: "guide/my-new-file.md" # local guide file my_hook_example: "examples/hooks/bash/foo.sh" # example file my_section_ref: "guide/ultimate-guide.md:1234" # with line number anchor ``` **Critical: avoid duplicate keys.** If a key appears twice in `deep_dive`, the YAML parser fails and the landing site search index becomes empty (0 entries). The build exits with a warning but no hard error: ``` [build-guide-index] ERROR: Failed to parse YAML: duplicated mapping key [build-guide-index] Generating empty guide-search-entries.ts ``` Use distinct names β€” e.g. if you need both a line-number reference and a file path for the same concept, suffix the line-number key with `_line`: ```yaml security_gate_hook_line: 6907 # line number ref security_gate_hook: "examples/hooks/bash/security-gate.sh" # file path ref ``` --- ## πŸ“„ Whitepapers (FR + EN) A series of 11 focused whitepapers covering Claude Code in depth. Each covers a specific topic and is available in both **French and English**. > **Coming soon** β€” currently in private access. Public release planned. - **00** β€” *De ZΓ©ro Γ  Productif / From Zero to Productive* β€” Foundations, first steps - **01** β€” *Prompts qui Marchent / Prompts That Work* β€” Prompting method, context, hooks - **02** β€” *Personnaliser Claude / Customizing Claude* β€” CLAUDE.md, custom agents, skills - **03** β€” *SΓ©curitΓ© en Production / Security in Production* β€” 17 security hooks, threat DB, permissions - **04** β€” *L'Architecture DΓ©mystifiΓ©e / Architecture Demystified* β€” Agent loop, context, token pricing - **05** β€” *DΓ©ployer en Γ‰quipe / Team Deployment* β€” CI/CD, observability, 50+ devs adoption - **06** β€” *Privacy & Compliance* β€” Anthropic data, ZDR, retention policies - **07** β€” *Guide de RΓ©fΓ©rence / Reference Guide* β€” Complete synthesis + advanced workflows - **08** β€” *Agent Teams* β€” Multi-agent orchestration and coordination - **09** β€” *Apprendre avec l'IA / Learning with AI* β€” UVAL protocol, comprehension debt, 30-day plan - **10** β€” *Budget IA / AI Budget* β€” Token costs, model selection, cost optimization ## πŸ—‚οΈ Recap Cards (FR + EN) 57 single-page A4 reference cards β€” printable, one concept per card. Organized in 3 series: > **Coming soon** β€” currently in private access. Public release planned alongside the whitepapers. Available in French and English. - **Technique (22 cards)** β€” Commands, permissions, configuration, MCP, models, context window - **MΓ©thodologie / Methodology (22 cards)** β€” Daily workflow, agents, hooks, CI/CD, multi-agent, debug - **Conception / Design (13 cards)** β€” Mental models, prompting, security by design, cost patterns --- ## 🌍 Ecosystem ### Claude Cowork (Non-Developers) **Claude Cowork** is the companion guide for non-technical users (knowledge workers, assistants, managers). Same agentic capabilities as Claude Code, but through a visual interface with no coding required. β†’ **[Claude Cowork Guide](https://github.com/FlorianBruniaux/claude-cowork-guide)** β€” File organization, document generation, automated workflows **Status**: Research preview (Pro $20/mo or Max $100-200/mo, macOS only, **VPN incompatible**) ### Claude Code Plugins (Marketplace) Production-ready plugins from this guide, installable in one command: ```bash claude plugin marketplace add FlorianBruniaux/claude-code-plugins claude plugin install session-summary@florian-claude-tools ``` > **[FlorianBruniaux/claude-code-plugins](https://github.com/FlorianBruniaux/claude-code-plugins)** β€” Session analytics, more plugins coming ### Complementary Resources | Project | Focus | Best For | |---------|-------|----------| | [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | Production configs (45k+ stars) | Quick setup, battle-tested patterns | | [claude-code-templates](https://github.com/davila7/claude-code-templates) | Distribution (200+ templates) | CLI installation (17k stars) | | [anthropics/skills](https://github.com/anthropics/skills) | Official Anthropic skills (60K+ stars) | Documents, design, dev templates | | [anthropics/claude-plugins-official](https://skills.sh/anthropics/claude-plugins-official) | Plugin dev tools (3.1K installs) | CLAUDE.md audit, automation discovery | | [skills.sh](https://skills.sh/) | Skills marketplace | One-command install (Vercel Labs) | | [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) | Curation | Resource discovery | | [awesome-claude-skills](https://github.com/BehiSecc/awesome-claude-skills) | Skills taxonomy | 62 skills across 12 categories | | [awesome-claude-md](https://github.com/josix/awesome-claude-md) | CLAUDE.md examples | Annotated configs with scoring | | [AI Coding Agents Matrix](https://coding-agents-matrix.dev) | Technical comparison | Comparing 23+ alternatives | **Community**: πŸ‡«πŸ‡· [Dev With AI](https://www.devw.ai/) β€” 1500+ devs on Slack, meetups in Paris, Bordeaux, Lyon β†’ **[AI Ecosystem Guide](./guide/ecosystem/ai-ecosystem.md)** β€” Complete integration patterns with complementary AI tools --- ## πŸ›‘οΈ Security **Comprehensive MCP security coverage** β€” the only guide with a threat intelligence database and production hardening workflows. ### Official Security Tools | Tool | Purpose | Maintained By | |------|---------|---------------| | [claude-code-security-review](https://github.com/anthropics/claude-code-security-review) | GitHub Action for automated security scanning | Anthropic (official) | | This Guide's Threat DB | Intelligence layer (24 CVEs, 655 malicious skills) | Community | **Workflow**: Use GitHub Action for automation β†’ Consult Threat DB for threat intelligence. ### Threat Database **24 CVE-mapped vulnerabilities** and **655 malicious skills** tracked in [`machine-readable/threat-db.yaml`](./machine-readable/threat-db.yaml): | Threat Category | Count | Examples | |----------------|-------|----------| | **Code/Command Injection** | 5 CVEs | CLI bypass (CVE-2025-66032), child_process exec | | **Path Traversal & Access** | 4 CVEs | Symlink escape (CVE-2025-53109), prefix bypass | | **RCE & Prompt Hijacking** | 4 CVEs | MCP Inspector RCE (CVE-2025-49596), session hijack | | **SSRF & DNS Rebinding** | 4 CVEs | WebFetch SSRF (CVE-2026-24052), DNS rebinding | | **Data Leakage** | 1 CVE | Cross-client response leak (CVE-2026-25536) | | **Malicious Skills** | 341 patterns | Unicode injection, hidden instructions, auto-execute | **Taxonomies**: 10 attack surfaces Γ— 11 threat types Γ— 8 impact levels ### Hardening Resources | Resource | Purpose | Time | |----------|---------|------| | **[Security Hardening Guide](./guide/security/security-hardening.md)** | MCP vetting, injection defense, audit workflow | 25 min | | **[Data Privacy Guide](./guide/security/data-privacy.md)** | Retention policies (5yr β†’ 30d β†’ 0), GDPR compliance | 10 min | | **[Sandbox Isolation](./guide/security/sandbox-isolation.md)** | Docker sandboxes for untrusted MCP servers | 10 min | | **[Production Safety](./guide/security/production-safety.md)** | Infrastructure locks, port stability, DB safety | 20 min | ### Security Commands ```bash /security-check # Quick scan config vs known threats (~30s) /security-audit # Full 6-phase audit with score /100 (2-5min) /update-threat-db # Research & update threat intelligence /audit-agents-skills # Quality audit with security checks ``` ### Security Hooks **30 production hooks** (bash + PowerShell) in [`examples/hooks/`](./examples/hooks/): | Hook | Purpose | |------|---------| | [dangerous-actions-blocker](./examples/hooks/bash/dangerous-actions-blocker.sh) | Block `rm -rf`, force-push, production ops | | [prompt-injection-detector](./examples/hooks/bash/prompt-injection-detector.sh) | Detect injection patterns in CLAUDE.md/prompts | | [unicode-injection-scanner](./examples/hooks/bash/unicode-injection-scanner.sh) | Detect hidden Unicode (zero-width, RTL override) | | [output-secrets-scanner](./examples/hooks/bash/output-secrets-scanner.sh) | Prevent API keys/tokens in Claude responses | **[Browse All Security Hooks β†’](./examples/hooks/)** ### MCP Vetting Workflow **Systematic evaluation before trusting MCP servers:** 1. **Provenance**: GitHub verified, 100+ stars, active maintenance 2. **Code Review**: Minimal privileges, no obfuscation, open-source 3. **Permissions**: Whitelist-only filesystem access, network restrictions 4. **Testing**: Isolated Docker sandbox first, monitor tool calls 5. **Monitoring**: Session logs, error tracking, regular re-audits **[Full MCP Security Workflow β†’](./guide/security/security-hardening.md#vetting-mcp-servers)** --- ## πŸ“– About This guide is the result of **6 months of daily practice** with Claude Code. The goal isn't to be exhaustive (the tool evolves too fast), but to share what works in production. **What you'll find:** - Patterns verified in production (not theory) - Trade-off explanations (not just "here's how to do it") - Security first (24 CVEs tracked) - Transparency on limitations (Claude Code isn't magic) **What you won't find:** - Definitive answers (tool is too new) - Universal configs (every project is different) - Marketing promises (zero bullshit) Use this guide critically. Experiment. Share what works for you. **Feedback welcome:** [GitHub Issues](https://github.com/FlorianBruniaux/claude-code-ultimate-guide/issues) ### About the Author **Florian Bruniaux** β€” Founding Engineer @ [MΓ©thode Aristote](https://methode-aristote.fr) (EdTech + AI). 12 years in tech (Dev β†’ Lead β†’ EM β†’ VP Eng β†’ CTO). Current focus: Rust CLI tools, MCP servers, AI developer tooling. | Project | Description | Links | |---------|-------------|-------| | **RTK** | CLI proxy β€” 60-90% LLM token reduction | [GitHub](https://github.com/rtk-ai/rtk) Β· [Site](https://www.rtk-ai.app/) | | **ccboard** | Real-time TUI/Web dashboard for Claude Code | [GitHub](https://github.com/FlorianBruniaux/ccboard) Β· [Demo](https://ccboard.bruniaux.com/) | | **Claude Cowork Guide** | 26 business workflows for non-coders | [GitHub](https://github.com/FlorianBruniaux/claude-cowork-guide) Β· [Site](https://cowork.bruniaux.com/) | | **cc-copilot-bridge** | Bridge between Claude Code & GitHub Copilot | [GitHub](https://github.com/FlorianBruniaux/cc-copilot-bridge) Β· [Site](https://ccbridge.bruniaux.com/) | | **Agent Academy** | MCP server for AI agent learning | [GitHub](https://github.com/FlorianBruniaux/agent-academy) | | **techmapper** | Tech stack mapping & visualization | [GitHub](https://github.com/FlorianBruniaux/techmapper) | [GitHub](https://github.com/FlorianBruniaux) Β· [LinkedIn](https://www.linkedin.com/in/florian-bruniaux-43408b83/) Β· [Portfolio](https://florian.bruniaux.com/) --- ## πŸ“š What's Inside ### Core Documentation | File | Purpose | Time | |------|---------|------| | **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (20K+ lines), 10 sections | 30-40h (full) β€’ Most consult sections | | **[Cheat Sheet](./guide/cheatsheet.md)** | 1-page printable reference | 5 min | | **[Visual Reference](./guide/core/visual-reference.md)** | 20 ASCII diagrams for key concepts | 5 min | | **[Architecture](./guide/core/architecture.md)** | How Claude Code works internally | 25 min | | **[Methodologies](./guide/core/methodologies.md)** | TDD, SDD, BDD reference | 20 min | | **[Workflows](./guide/workflows/)** | Practical guides (TDD, Plan-Driven, Task Management) | 30 min | | **[Data Privacy](./guide/security/data-privacy.md)** | Retention & compliance | 10 min | | **[Security Hardening](./guide/security/security-hardening.md)** | MCP vetting, injection defense | 25 min | | **[Sandbox Isolation](./guide/security/sandbox-isolation.md)** | Docker Sandboxes, cloud alternatives, safe autonomy | 10 min | | **[Production Safety](./guide/security/production-safety.md)** | Port stability, DB safety, infrastructure lock | 20 min | | **[DevOps & SRE](./guide/ops/devops-sre.md)** | FIRE framework, K8s troubleshooting, incident response | 30 min | | **[AI Ecosystem](./guide/ecosystem/ai-ecosystem.md)** | Complementary AI tools & integration patterns | 20 min | | **[AI Traceability](./guide/ops/ai-traceability.md)** | Code attribution & provenance tracking | 15 min | | **[Search Tools Cheatsheet](./guide/cheatsheet.md)** | Grep, Serena, ast-grep, grepai comparison | 5 min | | **[Learning with AI](./guide/roles/learning-with-ai.md)** | Use AI without becoming dependent | 15 min | | **[Claude Code Releases](./guide/core/claude-code-releases.md)** | Official release history | 10 min |
Examples Library (218 templates) **Agents** (6): [code-reviewer](./examples/agents/code-reviewer.md), [test-writer](./examples/agents/test-writer.md), [security-auditor](./examples/agents/security-auditor.md), [refactoring-specialist](./examples/agents/refactoring-specialist.md), [output-evaluator](./examples/agents/output-evaluator.md), [devops-sre](./examples/agents/devops-sre.md) ⭐ **Slash Commands** (26): [/pr](./examples/commands/pr.md), [/commit](./examples/commands/commit.md), [/release-notes](./examples/commands/release-notes.md), [/diagnose](./examples/commands/diagnose.md), [/security](./examples/commands/security.md), [/security-check](./examples/commands/security-check.md) **, [/security-audit](./examples/commands/security-audit.md) **, [/update-threat-db](./examples/commands/update-threat-db.md) **, [/refactor](./examples/commands/refactor.md), [/explain](./examples/commands/explain.md), [/optimize](./examples/commands/optimize.md), [/ship](./examples/commands/ship.md)... **Security Hooks** (31): [dangerous-actions-blocker](./examples/hooks/bash/dangerous-actions-blocker.sh), [prompt-injection-detector](./examples/hooks/bash/prompt-injection-detector.sh), [unicode-injection-scanner](./examples/hooks/bash/unicode-injection-scanner.sh), [output-secrets-scanner](./examples/hooks/bash/output-secrets-scanner.sh)... **Skills** (1): [Claudeception](https://github.com/blader/Claudeception) β€” Meta-skill that auto-generates skills from session discoveries ⭐ **Plugins** (1): [SE-CoVe](./examples/plugins/se-cove.md) β€” Chain-of-Verification for independent code review (Meta AI, ACL 2024) **Utility Scripts**: [session-search.sh](./examples/scripts/session-search.sh), [audit-scan.sh](./examples/scripts/audit-scan.sh) **GitHub Actions**: [claude-pr-auto-review.yml](./examples/github-actions/claude-pr-auto-review.yml), [claude-security-review.yml](./examples/github-actions/claude-security-review.yml), [claude-issue-triage.yml](./examples/github-actions/claude-issue-triage.yml) **Integrations** (1): [Agent Vibes TTS](./examples/integrations/agent-vibes/) - Text-to-speech narration for Claude Code responses **[Browse Complete Catalog](./examples/README.md)** | **[Interactive Catalog](./examples/index.html)**
Knowledge Quiz (271 questions) Test your Claude Code knowledge with an interactive CLI quiz covering all guide sections. ```bash cd quiz && npm install && npm start ``` **Features**: 4 profiles (Junior/Senior/Power User/PM), 10 topic categories, immediate feedback with doc links, score tracking with weak area identification. **[Quiz Documentation](./quiz/README.md)** | **[Contribute Questions](./quiz/templates/question-template.yaml)**
Resource Evaluations (115 assessments) Systematic evaluation of external resources (tools, methodologies, articles) before integration into the guide. **Methodology**: 5-point scoring system (Critical β†’ Low) with technical review and challenge phase for objectivity. **Evaluations**: GSD methodology, Worktrunk, Boris Cowork video, AST-grep, ClawdBot analysis, and more. **[Browse Evaluations](./docs/resource-evaluations/)** | **[Evaluation Methodology](./docs/resource-evaluations/README.md)**
--- ## 🀝 Contributing We welcome: - βœ… Corrections and clarifications - βœ… New quiz questions - βœ… Methodologies and workflows - βœ… Resource evaluations (see [process](./docs/resource-evaluations/README.md)) - βœ… Educational content improvements See [CONTRIBUTING.md](./CONTRIBUTING.md) for guidelines. **Ways to Help**: Star the repo β€’ Report issues β€’ Submit PRs β€’ Share workflows in [Discussions](../../discussions) --- ## πŸ“„ License & Support **Guide**: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/) β€” Educational content is open for reuse with attribution. **Templates**: [CC0 1.0](https://creativecommons.org/publicdomain/zero/1.0/) β€” Copy-paste freely, no attribution needed. **Author**: [Florian BRUNIAUX](https://github.com/FlorianBruniaux) | Founding Engineer [@MΓ©thode Aristote](https://methode-aristote.fr) **Stay Updated**: [Watch releases](../../releases) | [Discussions](../../discussions) | [Connect on LinkedIn](https://www.linkedin.com/in/florian-bruniaux-43408b83/) --- ## πŸ“š Further Reading ### This Guide - **[CHANGELOG](./CHANGELOG.md)** β€” Guide version history (what's new in each release) - [Claude Code Releases](./guide/core/claude-code-releases.md) β€” Official Claude Code release tracking ### Official Resources - [Claude Code CLI](https://code.claude.com) β€” Official website - [Documentation](https://code.claude.com/docs) β€” Official docs - [Anthropic CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) β€” Official Claude Code changelog - [GitHub Issues](https://github.com/anthropics/claude-code/issues) β€” Bug reports & feature requests ### Research & Industry Reports - **[2026 Agentic Coding Trends Report](https://resources.anthropic.com/hubfs/2026%20Agentic%20Coding%20Trends%20Report.pdf)** (Anthropic, Feb 2026) - 8 trends prospectifs (foundation/capability/impact) - Case studies: Fountain (50% faster), Rakuten (7h autonomous), CRED (2x speed), TELUS (500K hours saved) - Research data: 60% AI usage, 0-20% full delegation, 67% more PRs merged/day - **Evaluation**: [`docs/resource-evaluations/anthropic-2026-agentic-coding-trends.md`](docs/resource-evaluations/anthropic-2026-agentic-coding-trends.md) (score 4/5) - **Integration**: Diffused across sections 9.17 (Multi-Instance ROI), 9.20 (Agent Teams adoption), 9.11 (Enterprise Anti-Patterns), Section 9 intro - **[AI Fluency Index](https://www.anthropic.com/research/AI-fluency-index)** (Anthropic, Feb 23, 2026) - Research on 9,830 Claude.ai conversations: iteration multiplies fluency behaviors 2Γ— (2.67 vs 1.33) - **Artifact Paradox**: polished outputs (code, files) reduce critical evaluation β€” βˆ’5.2pp missing context, βˆ’3.7pp fact-checking, βˆ’3.1pp reasoning challenge - Only 30% of users set collaboration terms explicitly β€” CLAUDE.md addresses this structurally - **Evaluation**: [`docs/resource-evaluations/2026-02-23-anthropic-ai-fluency-index.md`](docs/resource-evaluations/2026-02-23-anthropic-ai-fluency-index.md) (score 4/5) - **Integration**: 3 callouts in Β§2.3 (plan review), Β§3.1 (CLAUDE.md), Β§9.11 (Artifact Paradox) + [diagram](./guide/diagrams/06-development-workflows.md#ai-fluency--high-vs-low-fluency-paths) - **[Outcome Engineering β€” o16g Manifesto](https://o16g.com/)** (Cory Ondrejka, Feb 2026) - 16 principles for shifting from "software engineering" to "outcome engineering" - Author: CTO Onebrief, co-creator Second Life, ex-VP Google/Meta - Cultural positioning: numeronym naming (o16g like i18n, k8s), Honeycomb endorsement - **Status**: Emerging β€” on [watch list](./docs/resource-evaluations/watch-list.md) for community adoption tracking ### Community Resources - [everything-claude-code](https://github.com/affaan-m/everything-claude-code) β€” Production configs (45k+⭐) - [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) β€” Curated links - [SuperClaude Framework](https://github.com/SuperClaude-Org/SuperClaude_Framework) β€” Behavioral modes ### Tools - [Ask Zread](https://zread.ai/FlorianBruniaux/claude-code-ultimate-guide) β€” Ask questions about this guide - [Interactive Quiz](./quiz/) β€” 271 questions - [Landing Site](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) β€” Visual navigation --- *Version 3.34.3 | Updated daily Β· Mar 11, 2026 | Crafted with Claude*