Claude Code Ultimate Guide

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 ⭐ — it helps others discover it too.

StarMapper

Choose Your Path

Who you are	Your guide
🏗️ Tech Lead / Engineering Manager	Deploying Claude Code across your team →
📊 CTO / Decision Maker	ROI, security posture, team adoption →
💼 CIO / CEO	Budget, risk, what to ask your tech team (3 min) →
🎨 Product Manager / Designer	Vibe coding, working with AI-assisted dev teams →
✍️ Writer / Ops / Manager	Claude Cowork Guide (separate repo) →
👨‍💻 Developer (all levels)	You're in the right place — read on ↓
🧭 Career pivot / new AI role	AI Roles & Career Paths →

🎯 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 — 48 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 28 CVEs + 655 malicious skills database)
✅ Test your knowledge — 374-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 (28 CVEs)	Basic patterns only
Test understanding	374-question quiz	Not available
Methodologies (TDD/SDD/BDD)	Full workflow guides	Not covered
Copy-paste ready templates	275 templates	200+ templates

Ecosystem Positioning

                    EDUCATIONAL DEPTH
                           ▲
                           │
                           │  ★ This Guide
                           │  Security + Methodologies + 24K+ 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

5 unique gaps no competitor covers:

Security-First — 28 CVEs + 655 malicious skills tracked (no competitor has this depth)
Methodology Workflows — TDD/SDD/BDD comparison + step-by-step guides
Comprehensive Reference — 24K+ lines across 16 specialized guides (24× more reference material than everything-cc)
Educational Progression — 374-question quiz + 7-module structured learning path (beginner → advanced)
Interactive Assessment — /self-assessment skill with personalized learning path recommendations

Recommended workflow:

Learn concepts here (mental models, trade-offs, security)
Use battle-tested configs there (quick project setup)
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

New to Claude Code? → 7-Module Learning Path — 8-11 hours, beginner to advanced

Quickest path: Cheat Sheet — 1 printable page with daily essentials

Interactive onboarding (no setup needed):

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 | Learning Path | Visual Diagrams | Examples | 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:

{
  "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):

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

📁 Repository Structure

graph LR
    root[📦 Repository<br/>Root]

    root --> guide[📖 guide/<br/>24K+ lines]
    root --> learning[🎓 learning-path/<br/>7 modules]
    root --> examples[📋 examples/<br/>275 templates]
    root --> quiz[🧠 quiz/<br/>374 questions]
    root --> tools[🔧 tools/<br/>utils]
    root --> machine[🤖 machine-readable/<br/>AI index]
    root --> docs[📚 docs/<br/>151 evaluations]

    style root fill:#d35400,stroke:#e67e22,stroke-width:3px,color:#fff
    style guide fill:#2980b9,stroke:#3498db,stroke-width:2px,color:#fff
    style learning fill:#27ae60,stroke:#2ecc71,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

📦 claude-code-ultimate-guide/
│
├─ 📖 guide/              Core Documentation (24K+ lines)
│  ├─ learning-path/      7-Module Learning Path (beginners → advanced)
│  ├─ 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/           48 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/           275 Production Templates
│  ├─ CATALOG.md          Auto-generated index by complexity, time, domain
│  ├─ agents/             23 custom AI personas
│  ├─ commands/           redirect stubs (migrated to skills/ in CC 2.1.3)
│  ├─ hooks/              37 hooks (bash + PowerShell)
│  ├─ skills/             64 skills (9 on SkillHub)
│  └─ scripts/            Utility scripts (audit, search)
│
├─ 🧠 quiz/               374 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/               151 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:

Tools Reference: all 40 built-in tools, permission rule formats, per-tool behaviors (timeouts, file-read limits, lossy WebFetch), and how-to for Monitor, Workflow, agent teams, Cron, Tasks API
Architecture — Internal mechanics (context flow, tool orchestration, memory management)
Trade-offs — Decision frameworks for agents vs skills vs commands
Configuration Decision Guide — Unified "which mechanism for what?" map across all 7 config layers
Pitfalls — 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 (48 Mermaid Diagrams)

Outcome: Grasp complex concepts instantly through visual mental models.

48 interactive diagrams across 10 thematic files — GitHub-native Mermaid rendering + ASCII fallback for every diagram:

Foundations — 4-layer context model, 9-step pipeline, permission modes
Architecture — Master loop, tool categories, system prompt assembly
Multi-Agent — 3 topologies, worktrees, dual-instance, horizontal scaling
Security — 3-layer defense, MCP rug pull attack chain, verification paradox
Cost & Models — Model selection tree, token reduction pipeline

Browse all 48 diagrams →

What this means for you: Understand the master loop before reading 24K+ 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:

28 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 → | Security Guide →

What this means for you: Vet MCP servers before trusting them, detect attack patterns in configs, comply with security audits.

📝 374-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 → | Run Locally

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 → | Section 9.20 →

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 — Test-Driven Development (Red-Green-Refactor with AI)
SDD — Specification-Driven Development (Design before code)
BDD — Behavior-Driven Development (User stories → tests)
GSD — 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.

📚 275 Annotated Templates

Outcome: Learn patterns, not just configs.

Educational templates with explanations:

Agents (23), Skills (74), Hooks (37)
Comments explaining why each pattern works (not just what it does)
Gradual complexity progression (simple → advanced)

Browse Catalog →

What this means for you: Understand the reasoning behind patterns, adapt templates to your context, create your own custom patterns.

🔍 151 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 →

What this means for you: Save time vetting resources, understand limitations before adopting tools, make informed decisions.

🎯 Learning Paths

Quick Start — Install & first workflow
Essential Commands — The 7 commands
Context Management — Critical concept
Memory Files — Your first CLAUDE.md
Learning with AI — Use AI without becoming dependent ⭐
TDD Workflow — Test-first development
Cheat Sheet — Print this

Core Concepts — Mental model
Plan Mode — Safe exploration
Methodologies — TDD, SDD, BDD reference
Agents — Custom AI personas
Hooks — Event automation
CI/CD Integration — Pipelines

Complete Guide — End-to-end
Architecture — How Claude Code works
Security Hardening — MCP vetting, injection defense
MCP Servers — Extended capabilities
Trinity Pattern — Advanced workflows
Observability — Monitor costs & sessions
Agent Teams — Multi-agent coordination (Opus 4.7+ experimental)
Examples — Production templates

Product Manager (5 steps):

What's Inside — Scope overview
Golden Rules — Key principles
Data Privacy — Retention & compliance
Adoption Approaches — Team strategies
PM FAQ — Code-adjacent vs non-coding PMs

Note: Non-coding PMs should consider Claude Cowork Guide instead.

DevOps / SRE (5 steps):

DevOps & SRE Guide — FIRE framework
K8s Troubleshooting — Symptom-based prompts
Incident Response — Workflows
IaC Patterns — Terraform, Ansible
Guardrails — Security boundaries

Product Designer (5 steps):

Working with Images — Image analysis
Wireframing Tools — ASCII/Excalidraw
Figma MCP — Design file access
Design-to-Code Workflow — Figma → Claude
Cheat Sheet — 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).

# 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

🔑 Golden Rules

1. Verify Trust Before Use

Claude Code can generate 1.75x more logic errors than human-written code (ACM 2025). 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

28 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	28 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 for thresholds and actions.

🤖 For AI Assistants

Resource	Purpose	Tokens
llms.txt	Standard context file	~1K
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 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:

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:

security_gate_hook_line: 6907                              # line number ref
security_gate_hook: "examples/hooks/bash/security-gate.sh" # file path ref

📄 Whitepapers (FR + EN)

11 focused whitepapers covering Claude Code in depth — PDF + EPUB, available in French and English. 472 pages total.

Coming soon — currently in private access. Public release planned.

#	FR	EN	Pages
00	De Zéro à Productif	From Zero to Productive	20
01	Prompts qui Marchent	Prompts That Work	40
02	Personnaliser Claude	Customizing Claude	47
03	Sécurité en Production	Security in Production	48
04	L'Architecture Démystifiée	Architecture Demystified	40
05	Déployer en Équipe	Team Deployment	43
06	Privacy & Compliance	Privacy & Compliance	29
07	Guide de Référence	Reference Guide	87
08	Agent Teams	Agent Teams	42
09	Apprendre avec l'IA	Learning with AI — UVAL protocol, comprehension debt	49
10	Convaincre son Employeur	Making the Case for AI — ROI dossier for CEO/CTO/CFO	27

🗂️ Recap Cards (FR, EN coming)

57 single-page A4 reference cards — printable, one concept per card. Available in French; English version in progress.

Browse online: cc.bruniaux.com/cheatsheets/

Technique (22 cards) — Commands, permissions, configuration, MCP, models, context window
Méthodologie (22 cards) — Daily workflow, agents, hooks, CI/CD, multi-agent, debug
Conception (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 — 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)

All 275 templates from this guide packaged as installable Claude Code plugins — hooks auto-wired, no manual config:

# Add the marketplace
claude plugin marketplace add FlorianBruniaux/claude-code-plugins

# Install the plugins you need
claude plugin install security-suite       # OWASP auditing, cyber-defense pipeline, 13 hooks
claude plugin install devops-pipeline      # CI/CD, git worktrees, GitHub Actions
claude plugin install release-automation   # Changelog + release notes + social content
claude plugin install code-quality         # SOLID refactoring, TDD, GoF patterns, 6 agents
claude plugin install pr-workflow          # Planning gates, PR/issue triage, handoffs
claude plugin install session-tools        # ccboard monitoring, voice refinement, 11 hooks
claude plugin install ai-methodology       # Scaffolding, 6-stage talk pipeline, context-engineering
claude plugin install session-summary      # Session analytics dashboard (15 sections)

FlorianBruniaux/claude-code-plugins — 8 plugins, 275 templates, one marketplace

Complementary Resources

Project	Focus	Best For
everything-claude-code	Production configs (45k+ stars)	Quick setup, battle-tested patterns
claude-code-templates	Distribution (200+ templates)	CLI installation (17k stars)
anthropics/skills	Official Anthropic skills (60K+ stars)	Documents, design, dev templates
anthropics/claude-plugins-official	Plugin dev tools (3.1K installs)	CLAUDE.md audit, automation discovery
skills.sh	Skills marketplace	One-command install (Vercel Labs)
awesome-claude-code	Curation	Resource discovery
youtube-skills	12 YouTube skills (search, transcripts, chapters)	Claude Code, Cursor, Windsurf, Cline
awesome-claude-skills	Skills taxonomy	62 skills across 12 categories
awesome-claude-md	CLAUDE.md examples	Annotated configs with scoring
ctop	Session monitoring (htop for AI agents)	Real-time CPU, memory, tokens, costs
AI Coding Agents Matrix	Technical comparison	Comparing 23+ alternatives

Community: 🇫🇷 Dev With AI — 1500+ devs on Slack, meetups in Paris, Bordeaux, Lyon

→ AI Ecosystem Guide — 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	GitHub Action for automated securit

Claude Code Ultimate Guide

README

Claude Code Ultimate Guide

StarMapper

Choose Your Path

🎯 What You'll Learn

📊 When to Use This Guide vs Everything-CC

Ecosystem Positioning

⚡ Quick Start

🔌 MCP Server — Use the guide from any Claude Code session

📁 Repository Structure

🎯 What Makes This Guide Unique

🎓 Deep Understanding Over Configuration

🖼️ Visual Diagrams Series (48 Mermaid Diagrams)

🛡️ Security Threat Intelligence (Only Comprehensive Database)

📝 374-Question Knowledge Validation (Unique in Ecosystem)

🤖 Agent Teams Coverage (v2.1.32+ Experimental)

🔬 Methodologies (Structured Development Workflows)

📚 275 Annotated Templates

🔍 151 Resource Evaluations

🎯 Learning Paths

Progressive Journey

🔧 Rate Limits & Cost Savings

🔑 Golden Rules

1. Verify Trust Before Use

2. Never Approve MCPs from Unknown Sources

3. Context Pressure Changes Behavior

4. Start Simple, Scale Smart

5. Methodologies Matter More with AI

Quick Reference

🤖 For AI Assistants

reference.yaml — Structure & Landing Site Search

How the search index works

Maintaining reference.yaml

📄 Whitepapers (FR + EN)

🗂️ Recap Cards (FR, EN coming)

🌍 Ecosystem

Claude Cowork (Non-Developers)

Claude Code Plugins (Marketplace)

Complementary Resources

🛡️ Security

Official Security Tools

Comments (0)