# Claude Code Ultimate Guide

Website

Stars Quiz Templates

License: CC BY-SA 4.0 Ask Zread

> Master Claude Code with educational depth and practical methodologies. We teach **WHY** it works β†’ Others provide **HOW** to configure. --- ## ⚑ Quick Start **Quickest path**: [Cheat Sheet](./guide/cheatsheet.md) β€” 1 printable page with daily essentials **Interactive onboarding** (no clone 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) | [Examples](./examples/) | [Quiz](./quiz/)
Prerequisites & Minimal CLAUDE.md Template **Prerequisites**: Node.js 18+ | [Anthropic API key](https://console.anthropic.com/) ```markdown # 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 ```mermaid graph LR root[πŸ“¦ Repository
Root] root --> guide[πŸ“– guide/
15K lines] root --> examples[πŸ“‹ examples/
86 templates] root --> quiz[🧠 quiz/
227 questions] root --> tools[πŸ”§ tools/
utils] root --> machine[πŸ€– machine-readable/
AI index] root --> docs[πŸ“š docs/
25 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 (~15K 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 β”‚ └─ workflows/ Step-by-step guides β”‚ β”œβ”€ πŸ“‹ examples/ 86 Production Templates β”‚ β”œβ”€ agents/ 6 custom AI personas β”‚ β”œβ”€ commands/ 18 slash commands β”‚ β”œβ”€ hooks/ 18 security hooks (bash + PowerShell) β”‚ β”œβ”€ skills/ 1 meta-skill (Claudeception) β”‚ └─ scripts/ Utility scripts (audit, search) β”‚ β”œβ”€ 🧠 quiz/ 227 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/ 22 Resource Evaluations └─ resource-evaluations/ 5-point scoring, source attribution ```
--- ## 🎯 What Makes This Guide Unique ### πŸŽ“ Educational Depth We explain **concepts first**, not just configs: - [Architecture](./guide/architecture.md) β€” How Claude Code works internally - [Trade-offs](./guide/ultimate-guide.md#when-to-use-what) β€” When to use agents vs skills vs commands - [Pitfalls](./guide/ultimate-guide.md#common-mistakes) β€” Common mistakes and solutions ### πŸ“ 227-Question Quiz (Unique in Ecosystem) **Only comprehensive assessment available** β€” test your understanding across 9 categories: - Setup & Configuration - Agents & Sub-Agents - MCP Servers & Integration - Trust & Verification - Advanced Patterns [Try the Quiz Online β†’](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/quiz/) | [Run Locally](./quiz/) ### πŸ”¬ Methodologies (Structured Workflows) Complete guides with rationale and examples: - [TDD](./guide/methodologies.md#1-tdd-test-driven-development-with-claude) β€” Test-Driven Development - [SDD](./guide/methodologies.md#2-sdd-specification-driven-development) β€” Specification-Driven Development - [BDD](./guide/methodologies.md#3-bdd-behavior-driven-development) β€” Behavior-Driven Development - [GSD](./guide/methodologies.md#gsd-get-shit-done) β€” Get Shit Done pattern ### πŸ“š 86 Annotated Templates Educational templates with explanations: - Agents (6), Commands (18), Hooks (18), Skills - Comments explaining **why** each pattern works - Gradual complexity progression [Browse Catalog β†’](./examples/) ### πŸ” 22 Resource Evaluations Systematic assessment of external resources (5-point scoring): - Articles, videos, tools, frameworks - Honest assessments with source attribution - Integration recommendations [See Evaluations β†’](./docs/resource-evaluations/) --- ## 🎯 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/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/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 (7 steps) 1. [Complete Guide](./guide/ultimate-guide.md) β€” End-to-end 2. [Architecture](./guide/architecture.md) β€” How Claude Code works 3. [Security Hardening](./guide/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/observability.md) β€” Monitor costs & sessions 7. [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/data-privacy.md) β€” Retention & compliance 4. [Adoption Approaches](./guide/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/devops-sre.md) β€” FIRE framework 2. [K8s Troubleshooting](./guide/devops-sre.md#kubernetes-troubleshooting) β€” Symptom-based prompts 3. [Incident Response](./guide/devops-sre.md#pattern-incident-response) β€” Workflows 4. [IaC Patterns](./guide/devops-sre.md#pattern-infrastructure-as-code) β€” Terraform, Ansible 5. [Guardrails](./guide/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. **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](https://dl.acm.org/doi/10.1145/3716848)) 6. **Context = Gold** β€” Clear CLAUDE.md > clever prompts > 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` --- ## 🌍 Ecosystem ### Positioning: Complementary, Not Competitive **Claude Code has two major community resources:** | Resource | Focus | Best For | |----------|-------|----------| | **This Guide** | πŸŽ“ Educational depth, methodologies | Deep understanding, learning WHY | | [everything-claude-code](https://github.com/affaan-m/everything-claude-code) | βš™οΈ Production configs, plugin install | Quick setup, battle-tested patterns | **Recommended workflow**: Learn concepts here β†’ Leverage production configs there β†’ Return for deep dives Both resources serve different needs. Use what fits your learning style and project requirements. ### 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**) ### Complementary Resources | Project | Focus | Best For | |---------|-------|----------| | [claude-code-templates](https://github.com/davila7/claude-code-templates) | Distribution (200+ templates) | CLI installation (17k⭐) | | [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 | | [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/ai-ecosystem.md)** β€” Complete integration patterns with complementary AI tools --- ## πŸ“– About
Origins & Philosophy This guide is the result of several 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](https://claudelog.com/) β€” Excellent patterns & tutorials - [zebbern/claude-code-guide](https://github.com/zebbern/claude-code-guide) β€” Comprehensive reference with security focus - [ykdojo/claude-code-tips](https://github.com/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](https://claude.ai/settings/data-privacy-controls) | [Full privacy guide](./guide/data-privacy.md)
--- ## πŸ“š What's Inside ### Core Documentation | File | Purpose | Time | |------|---------|------| | **[Ultimate Guide](./guide/ultimate-guide.md)** | Complete reference (~15K lines), 10 sections | ~4 hours | | **[Cheat Sheet](./guide/cheatsheet.md)** | 1-page printable reference | 5 min | | **[Architecture](./guide/architecture.md)** | How Claude Code works internally | 25 min | | **[Methodologies](./guide/methodologies.md)** | TDD, SDD, BDD reference | 20 min | | **[Workflows](./guide/workflows/)** | Practical guides (TDD, Plan-Driven, Task Management) | 30 min | | **[Data Privacy](./guide/data-privacy.md)** | Retention & compliance | 10 min | | **[Security Hardening](./guide/security-hardening.md)** | MCP vetting, injection defense | 25 min | | **[Production Safety](./guide/production-safety.md)** | Port stability, DB safety, infrastructure lock | 20 min | | **[DevOps & SRE](./guide/devops-sre.md)** | FIRE framework, K8s troubleshooting, incident response | 30 min | | **[AI Ecosystem](./guide/ai-ecosystem.md)** | Complementary AI tools & integration patterns | 20 min | | **[AI Traceability](./guide/ai-traceability.md)** | Code attribution & provenance tracking | 15 min | | **[Search Tools Cheatsheet](./guide/search-tools-cheatsheet.md)** | Grep, Serena, ast-grep, grepai comparison | 5 min | | **[Learning with AI](./guide/learning-with-ai.md)** | Use AI without becoming dependent | 15 min | | **[Claude Code Releases](./guide/claude-code-releases.md)** | Official release history | 10 min |
Examples Library (86 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** (18): [/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), [/refactor](./examples/commands/refactor.md), [/explain](./examples/commands/explain.md), [/optimize](./examples/commands/optimize.md), [/ship](./examples/commands/ship.md)... **Security Hooks** (18): [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 (227 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 (22 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 ### Official Resources - [Claude Code CLI](https://code.claude.com) β€” Official website - [Documentation](https://code.claude.com/docs) β€” Official docs - [CHANGELOG](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) β€” Official changelog - [GitHub Issues](https://github.com/anthropics/claude-code/issues) β€” Bug reports & feature requests ### Community Resources - [everything-claude-code](https://github.com/affaan-m/everything-claude-code) β€” Production configs (31.9k⭐) - [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/) β€” 227 questions - [Landing Site](https://florianbruniaux.github.io/claude-code-ultimate-guide-landing/) β€” Visual navigation --- *Version 3.20.0 | January 2026 | Crafted with Claude*