claude-code-ultimate-guide/docs/drafts/README-new.md

Claude Code Ultimate Guide

Learn the WHY, not just the what. After 6 months of daily practice, this guide teaches you to think like an agentic developer — from core concepts to production mastery.

If this guide helps you, give it a star ⭐ — it helps others discover it too.

---

🎯 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)
• ✅ Master methodologies — TDD, SDD, BDD with AI collaboration (not just templates)
• ✅ Security mindset — Threat modeling for AI systems (only guide with 22 CVEs + 341 malicious skills database)
• ✅ Test your knowledge — 257-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 learning style:

Your Goal	Use This Guide	Use everything-claude-code
Understand WHY patterns work	✅ Deep explanations + architecture	❌ Config-focused
Quick setup for projects	⚠️ Available but not primary focus	✅ Battle-tested production configs
Learn trade-offs (agents vs skills)	✅ Decision frameworks + comparisons	❌ Lists patterns, no trade-off analysis
Security hardening	✅ Only threat database (22 CVEs)	⚠️ Basic patterns only
Test understanding	✅ 257-question quiz	❌ Not available
Methodologies (TDD/SDD/BDD)	✅ Full workflow guides	❌ Not covered
Copy-paste ready templates	✅ 111 templates	✅ 200+ templates

Recommended workflow:

1. Learn concepts here → Understand mental models, trade-offs, security
2. Leverage production configs there → Quick project setup from battle-tested patterns
3. Return here for deep dives → When you need to understand why something isn't working or design custom workflows

Both resources are complementary, not competitive. Use what fits your current need.

---

⚡ Quick Start

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

Interactive onboarding (no clone 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 | Examples | Quiz

Prerequisites & Minimal CLAUDE.md Template

Prerequisites: Node.js 18+ | Anthropic API key

# Project: [NAME]

## Tech Stack
- Language: [e.g., TypeScript]
- Framework: [e.g., Next.js 14]
- Testing: [e.g., Vitest]

## Commands
- Build: `npm run build`
- Test: `npm test`
- Lint: `npm run lint`

## Rules
- Run tests before marking tasks complete
- Follow existing code patterns
- Keep commits atomic and conventional

Save as CLAUDE.md in your project root. Claude reads it automatically.

---

📁 Repository Structure

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

    root --> guide[📖 guide/<br/>19K lines]
    root --> examples[📋 examples/<br/>111 templates]
    root --> quiz[🧠 quiz/<br/>257 questions]
    root --> tools[🔧 tools/<br/>utils]
    root --> machine[🤖 machine-readable/<br/>AI index]
    root --> docs[📚 docs/<br/>56 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 (~19K 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
│  ├─ mcp-servers-ecosystem.md  Official & community MCP servers
│  └─ workflows/          Step-by-step guides
│
├─ 📋 examples/           111 Production Templates
│  ├─ agents/             6 custom AI personas
│  ├─ commands/           22 slash commands
│  ├─ hooks/              18 security hooks (bash + PowerShell)
│  ├─ skills/             1 meta-skill (Claudeception)
│  └─ scripts/            Utility scripts (audit, search)
│
├─ 🧠 quiz/               257 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)
│  └─ llms.txt            Standard LLM context file
│
└─ 📚 docs/               55 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 — Internal mechanics (context flow, tool orchestration, memory management)
• Trade-offs — Decision frameworks for agents vs skills vs commands
• 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.

---

🛡️ Security Threat Intelligence (Only Comprehensive Database)

Outcome: Protect production systems from AI-specific attacks.

Only guide with systematic threat tracking:

• 22 CVE-mapped vulnerabilities — Prompt injection, data exfiltration, code injection
• 341 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.

---

📝 257-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.

---

📚 111 Annotated Templates

Outcome: Learn patterns, not just configs.

Educational templates with explanations:

• Agents (6), Commands (22), Hooks (18), Skills
• 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.

---

🔍 55 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

Junior Developer — Foundation path (7 steps)

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

Senior Developer — Intermediate path (6 steps)

1. Core Concepts — Mental model
2. Plan Mode — Safe exploration
3. Methodologies — TDD, SDD, BDD reference
4. Agents — Custom AI personas
5. Hooks — Event automation
6. CI/CD Integration — Pipelines

Power User — Comprehensive path (8 steps)

1. Complete Guide — End-to-end
2. Architecture — How Claude Code works
3. Security Hardening — MCP vetting, injection defense
4. MCP Servers — Extended capabilities
5. Trinity Pattern — Advanced workflows
6. Observability — Monitor costs & sessions
7. Agent Teams — Multi-agent coordination (Opus 4.6 experimental)
8. Examples — Production templates

Product Manager / DevOps / Designer

Product Manager (5 steps):

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

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

DevOps / SRE (5 steps):

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

Product Designer (5 steps):

1. Working with Images — Image analysis
2. Wireframing Tools — ASCII/Excalidraw
3. Figma MCP — Design file access
4. Design-to-Code Workflow — Figma → Claude
5. 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. Start small — First project: 10-15 lines CLAUDE.md max
2. Read before edit — Always Read → Understand → Edit (never blind Write)
3. Test-first — Write test → Watch fail → Implement → Pass
4. Use /compact before context hits 70% — prevention beats recovery
5. Review everything — AI code has 1.75× more logic errors (source)
6. Context = Gold — Clear CLAUDE.md > clever prompts

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

---

🌍 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)

Complementary Resources

Project	Focus	Best For
everything-claude-code	Production configs (31.9k⭐)	Quick setup, battle-tested patterns
claude-code-templates	Distribution (200+ templates)	CLI installation (17k⭐)
anthropics/skills	Official Anthropic skills (60K+⭐)	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
awesome-claude-skills	Skills taxonomy	62 skills across 12 categories
awesome-claude-md	CLAUDE.md examples (31★)	Annotated configs with scoring
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 security scanning	Anthropic (official)
This Guide's Threat DB	Intelligence layer (22 CVEs, 341 malicious skills)	Community

Workflow: Use GitHub Action for automation → Consult Threat DB for threat intelligence.

Threat Database

22 CVE-mapped vulnerabilities and 341 malicious skills tracked in machine-readable/threat-db.yaml:

Threat Category	Count	Examples
Prompt Injection	14 CVEs	Indirect injection (CVE-2024-1546), context poisoning
Data Exfiltration	5 CVEs	Training data extraction (CVE-2024-0241), secret leakage
Code Injection	3 CVEs	Tool manipulation, workflow abuse
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	MCP vetting, injection defense, audit workflow	25 min
Data Privacy Guide	Retention policies (5yr → 30d → 0), GDPR compliance	10 min
Sandbox Isolation	Docker sandboxes for untrusted MCP servers	10 min
Production Safety	Infrastructure locks, port stability, DB safety	20 min

Security Commands

/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

18 production hooks (bash + PowerShell) in examples/hooks/:

Hook	Purpose
dangerous-actions-blocker	Block rm -rf, force-push, production ops
prompt-injection-detector	Detect injection patterns in CLAUDE.md/prompts
unicode-injection-scanner	Detect hidden Unicode (zero-width, RTL override)
output-secrets-scanner	Prevent API keys/tokens in Claude responses

Browse All Security 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 →

---

📖 About

Origins & Philosophy

This guide is the result of 6 months of daily practice with Claude Code. I don't claim expertise—I'm sharing what I've learned to help peers and evangelize AI-assisted development best practices.

Philosophy: Learning journey over reference manual. Understanding why before how. Progressive complexity — start simple, master advanced at your pace.

Created with Claude Code. Community-validated through contributions and feedback.

Key Inspirations:

• Claudelog.com — Excellent patterns & tutorials
• zebbern/claude-code-guide — Comprehensive reference with security focus
• ykdojo/claude-code-tips — Practical productivity techniques

Privacy & Data

Claude Code sends your prompts, file contents, and MCP results to Anthropic servers.

• Default: 5 years retention (training enabled) | Opt-out: 30 days | Enterprise: 0
• Action: Disable training | Full privacy guide

---

📚 What's Inside

Core Documentation

File	Purpose	Time
Ultimate Guide	Complete reference (~19K lines), 10 sections	30-40h (full) • Most consult sections
Cheat Sheet	1-page printable reference	5 min
Visual Reference	20 ASCII diagrams for key concepts	5 min
Architecture	How Claude Code works internally	25 min
Methodologies	TDD, SDD, BDD reference	20 min
Workflows	Practical guides (TDD, Plan-Driven, Task Management)	30 min
Data Privacy	Retention & compliance	10 min
Security Hardening	MCP vetting, injection defense	25 min
Sandbox Isolation	Docker Sandboxes, cloud alternatives, safe autonomy	10 min
Production Safety	Port stability, DB safety, infrastructure lock	20 min
DevOps & SRE	FIRE framework, K8s troubleshooting, incident response	30 min
AI Ecosystem	Complementary AI tools & integration patterns	20 min
AI Traceability	Code attribution & provenance tracking	15 min
Search Tools Cheatsheet	Grep, Serena, ast-grep, grepai comparison	5 min
Learning with AI	Use AI without becoming dependent	15 min
Claude Code Releases	Official release history	10 min

Examples Library (111 templates)

Agents (6): code-reviewer, test-writer, security-auditor, refactoring-specialist, output-evaluator, devops-sre ⭐

Slash Commands (22): /pr, /commit, /release-notes, /diagnose, /security, /security-check **, /security-audit **, /update-threat-db **, /refactor, /explain, /optimize, /ship...

Security Hooks (18): dangerous-actions-blocker, prompt-injection-detector, unicode-injection-scanner, output-secrets-scanner...

Skills (1): Claudeception — Meta-skill that auto-generates skills from session discoveries ⭐

Plugins (1): SE-CoVe — Chain-of-Verification for independent code review (Meta AI, ACL 2024)

Utility Scripts: session-search.sh, audit-scan.sh

GitHub Actions: claude-pr-auto-review.yml, claude-security-review.yml, claude-issue-triage.yml

Integrations (1): Agent Vibes TTS - Text-to-speech narration for Claude Code responses

Browse Complete Catalog | Interactive Catalog

Knowledge Quiz (257 questions)

Test your Claude Code knowledge with an interactive CLI quiz covering all guide sections.

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 | Contribute Questions

Resource Evaluations (55 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 | Evaluation Methodology

---

🤝 Contributing

We welcome:

• ✅ Corrections and clarifications
• ✅ New quiz questions
• ✅ Methodologies and workflows
• ✅ Resource evaluations (see process)
• ✅ Educational content improvements

See CONTRIBUTING.md for guidelines.

Ways to Help: Star the repo • Report issues • Submit PRs • Share workflows in Discussions

---

📄 License & Support

Guide: CC BY-SA 4.0 — Educational content is open for reuse with attribution.

Templates: CC0 1.0 — Copy-paste freely, no attribution needed.

Author: Florian BRUNIAUX | Founding Engineer @Méthode Aristote

Stay Updated: Watch releases | Discussions | Connect on LinkedIn

---

📚 Further Reading

This Guide

• CHANGELOG — Guide version history (what's new in each release)
• Claude Code Releases — Official Claude Code release tracking

Official Resources

• Claude Code CLI — Official website
• Documentation — Official docs
• Anthropic CHANGELOG — Official Claude Code changelog
• GitHub Issues — Bug reports & feature requests

Research & Industry Reports

• 2026 Agentic Coding Trends Report (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 (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

Community Resources

• everything-claude-code — Production configs (31.9k⭐)
• awesome-claude-code — Curated links
• SuperClaude Framework — Behavioral modes

Tools

• Ask Zread — Ask questions about this guide
• Interactive Quiz — 257 questions
• Landing Site — Visual navigation

---

Version 3.26.0 | Updated daily · Feb 12, 2026 | Crafted with Claude