claude-code-ultimate-guide/README.md

Claude Code Guide

---

Transparency note: This guide reflects my personal experience after several months of daily Claude Code usage. I'm sharing what I've learned, not claiming expertise. The tool evolves constantly, and so does my understanding. Feedback welcome.

---

Privacy Notice: 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

---

Start here:

• Cheat Sheet — print this, start coding
• 15-min Quick Start — first workflow
• Audit your setup — quick scan

Go deeper (optional): Learning paths by role | Full guide

---

Why This Guide?

Installation, agents, MCP servers, hooks, skills, and CI/CD integration—documented through several months of daily practice. A structured learning journey sharing what I've learned so far.

By Florian BRUNIAUX | Founding Engineer @Méthode Aristote | Connect on LinkedIn

The Problem: Most Claude Code resources are scattered blog posts or dense reference manuals. You're left piecing together workflows and discovering critical concepts too late.

This guide: A structured learning journey with ready-to-use examples. Your mileage will vary—the goal is to save you the exploration time I've already spent.

Traditional Docs	This Guide
Lists features	Teaches workflows
Reference lookup	Progressive learning
Theoretical concepts	Production-ready patterns
"Figure it out"	"Here's exactly how"

Reading time: The Quick Start takes ~15 minutes. Full guide is ~3 hours but most people read by section as needed.

If this guide saves you hours of trial-and-error, please star it.

Prerequisites

• Node.js 18+ (or use the shell installer on macOS/Linux)
• Anthropic API key — Get one here

---

Choose Your Path

🧭 Not Sure Where to Start?

If you...	Start here	Depth
Just installed Claude Code	Quick Start	Essentials
Want to understand core concepts	Junior Path	Foundation
Already use AI coding tools	Senior Path	Intermediate
Need to configure a team setup	Power User Path	Comprehensive
Need to evaluate/approve adoption	PM Path	Overview
Want TDD/BDD with Claude	Workflows	Practical
Need a dev methodology reference	Methodologies	Reference
Want to understand internals	Architecture	Deep dive
Need data privacy guidance	Data Privacy	Quick read
Need security hardening	Security Hardening	Essential
Want to track costs & sessions	Observability	Monitoring
Choosing turnkey vs. autonomous approach	Adoption Guide	Quick read
Want to check your current setup	Audit Your Setup	Quick scan
Want AI assistants to know Claude Code	LLM Reference	Reference
Want personalized recommendations	Deep Audit	Quick scan
Want to test your knowledge	Knowledge Quiz	Interactive
Want a guided tour	Personalized Onboarding	Interactive
Having issues with Claude Code	/diagnose command	Quick fix
Want mobile access to Claude Code	Mobile Access Setup	WIP

⚡ Audit Your Setup

Already have Claude Code installed? Quickly scan your configuration:

curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh | bash

Instant checks: Config files, tech stack, extensions, security hooks, MCP servers, CLAUDE.md quality

Want deeper analysis? Use tools/audit-prompt.md for personalized recommendations (~3 min).

🤖 LLM Reference

Give any AI assistant instant Claude Code expertise (~2K tokens):

curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml

Use cases: Paste output into ChatGPT/Claude/Gemini, add to system prompts, or reference in Claude Code with @machine-readable/reference.yaml

What's inside: Decision trees, command reference, context zones, MCP servers, agent templates, troubleshooting—optimized for machine consumption. Points to line numbers in the full guide for deep dives.

🔬 Deep Audit (Personalized Recommendations)

Get a comprehensive, context-aware audit that analyzes your project's README, CLAUDE.md files, and business domain to provide tailored recommendations:

🔒 Privacy: The audit downloads reference files from this repo, then analyzes YOUR local files with your Claude CLI. Your project files are sent only to your Anthropic API endpoint, not to this repository or any third party.

Quick Version (~10 sec):

curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh | bash -s -- --json | claude -p "Analyze this Claude Code setup. Give: 1) Health score 0-100 2) Top 3 quick wins 3) CLAUDE.md template for detected stack. Be concise."

Full Audit with Context (~30 sec, recommended):

# Claude Code Deep Audit - Context-Aware Version
# Downloads reference files, reads YOUR local files, analyzes with Claude
REF=$(curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/machine-readable/reference.yaml)
SCAN=$(curl -sL https://raw.githubusercontent.com/FlorianBruniaux/claude-code-ultimate-guide/main/examples/scripts/audit-scan.sh | bash -s -- --json 2>/dev/null)
README_CONTENT=$(head -100 README.md 2>/dev/null || echo "No README.md found")
CLAUDE_MD=$(cat CLAUDE.md 2>/dev/null || echo "No CLAUDE.md found")
LOCAL_CLAUDE_MD=$(cat .claude/CLAUDE.md 2>/dev/null || echo "No .claude/CLAUDE.md found")

claude -p "Reference:
$REF

Scan results:
$SCAN

Project README (first 100 lines):
$README_CONTENT

Project CLAUDE.md:
$CLAUDE_MD

Local .claude/CLAUDE.md:
$LOCAL_CLAUDE_MD

IMPORTANT: Focus on INCREMENTAL improvements to existing setup. Don't suggest creating things that already exist. If CLAUDE.md exists, suggest specific improvements to it rather than a full rewrite.

Based on ALL this context, provide:
1. Stack Recap: runtime, framework, test runner, bundler, database, key integrations detected
2. Health Score (0-100) - be strict: penalize missing SSoT pattern if >100 lines without @refs
3. Findings table: Priority|Element|Status|Action (only gaps, not what exists)
4. Top 3 quick wins (<5 min) - MUST be specific to THIS project's domain (not generic advice)
5. If CLAUDE.md exists: list 3-5 specific improvements (not a full template). If missing: provide ~100 line template
6. Suggested agents/commands/hooks that DON'T duplicate existing ones - check extensions count first
7. Ideas to leverage Claude Code for this specific domain and detected integrations"

What you get:

• Stack recap: Runtime, framework, test runner, bundler, database, and key integrations auto-detected
• Strict health score (penalizes large CLAUDE.md without @refs)
• Incremental improvements: Specific fixes for YOUR setup, not generic advice
• Domain-aware suggestions (e.g., EdTech → session planning agents, E-commerce → inventory commands)
• Non-duplicate suggestions: Only recommends agents/commands you don't already have

Want maximum depth? Use tools/audit-prompt.md with claude --ultrathink

🧠 Knowledge Quiz

Test your Claude Code knowledge with an interactive CLI quiz. 159 curated questions covering all 10 guide sections, with immediate feedback and documentation links.

# Quick start
cd quiz && npm install && npm start

# With options
node quiz/src/index.js --profile senior --topics 2,4,7 --count 10

Example Session (click to expand)

============================================================
   CLAUDE CODE KNOWLEDGE QUIZ
============================================================

? Select your profile: Senior Developer (40 min to mastery)
? Select topics to quiz: All topics (recommended)

------------------------------------------------------------
Question 1/20 [Core Concepts]

At what context percentage should you use /compact?

  A) 0-50%
  B) 50-70%
  C) 70-90%
  D) Only at 100%

? Your answer: C

✓ CORRECT!

------------------------------------------------------------
Question 2/20 [Hooks]

What exit code should a PreToolUse hook return to BLOCK an operation?

  A) 0
  B) 1
  C) 2
  D) -1

? Your answer: A

✗ INCORRECT. The correct answer is C) 2

Explanation:
Exit code 2 blocks the operation. Exit code 0 allows it to proceed.
Other exit codes are treated as errors and logged but don't block.

See: guide/ultimate-guide.md#72-creating-hooks

------------------------------------------------------------
   QUIZ COMPLETE
------------------------------------------------------------

Overall Score: 16/20 (80%)

By Category:
  Core Concepts       6/7  (86%)  [████████░░]
  Agents              5/7  (71%)  [███████░░░]
  Hooks               5/6  (83%)  [████████░░]

Weak Areas (< 75%):
  - Agents: Review section 4 in the guide

? What would you like to do? Retry wrong questions only

Features:

• 4 profiles: Junior (15q), Senior (20q), Power User (25q), PM (10q)
• 10 topic categories matching guide sections
• Immediate feedback with explanations and doc links
• Score tracking with category breakdown and weak area identification
• Session history saved to ~/.claude-quiz/
• Replay options: Retry wrong questions or start fresh
• Cross-platform: Works on macOS, Linux, and Windows

See: Quiz Documentation | Contribute Questions

🎯 By Role (Tailored Learning Paths)

Junior Developer (Foundation path) Quick Start — Install & first workflow Essential Commands — The 7 commands Context Management — Critical concept Memory Files — Your first CLAUDE.md TDD Workflow — Test-first development Cheat Sheet — Print this	Senior Developer (Intermediate path) Core Concepts — Mental model Plan Mode — Safe exploration Methodologies — TDD, SDD, BDD reference Agents — Custom AI personas Hooks — Event automation CI/CD Integration — Pipelines
Power User (Comprehensive path) 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 Examples — Production templates	Product Manager (Overview path) What's Inside — Scope Golden Rules — Key principles Data Privacy — Retention & compliance Adoption Approaches — Team strategies Context Management — Why it matters

---

📚 Complete Toolkit

Core Documentation

File	Purpose	Time Investment
Ultimate Guide	Complete reference, 10 sections	~3 hours (or by section)
Cheat Sheet	1-page printable reference	5 minutes
Architecture & Internals	How Claude Code works under the hood	~25 minutes
Methodologies	15 development methodologies reference	~20 minutes
Workflows	Practical guides (TDD, SDD, Plan-Driven)	~30 minutes
Data Privacy	Data retention and privacy guide	~10 minutes
Security Hardening	MCP vetting, injection defense, CVEs	~25 minutes
Observability	Session monitoring and cost tracking	~15 minutes
LLM Reference	Machine-optimized index (~2K tokens)	For Claude/AI assistants
Setup Audit	Optimize your configuration	~10 minutes
Examples Library	Production-ready templates	Browse as needed

Alternative Formats (Interactive AI, PDFs)

• DeepWiki — AI-powered Q&A, semantic search, instant summaries
• NotebookLM Slides — Visual overview (~20 min)
• Kimi PDF — Full text export (~3 hours)

Repository Structure

claude-code-ultimate-guide/
├── guide/                    # 📖 Core documentation
│   ├── ultimate-guide.md     # Complete reference (~9500 lines)
│   ├── cheatsheet.md         # 1-page printable reference
│   ├── architecture.md       # How Claude Code works internally
│   ├── adoption-approaches.md # Team implementation strategies
│   ├── data-privacy.md       # Data retention and privacy guide
│   ├── methodologies.md      # 15 development methodologies reference
│   ├── observability.md      # Session monitoring and cost tracking
│   └── workflows/            # Practical workflow guides
│       ├── tdd-with-claude.md
│       ├── spec-first.md
│       ├── plan-driven.md
│       └── iterative-refinement.md
│
├── tools/                    # 🔧 Interactive utilities
│   ├── audit-prompt.md       # Setup audit with recommendations
│   ├── onboarding-prompt.md  # Personalized guided tour
│   └── mobile-access.md      # Mobile access setup (ttyd + Tailscale)
│
├── machine-readable/         # 🤖 LLM/AI consumption
│   ├── reference.yaml        # Structured index (~2K tokens)
│   └── llms.txt              # Standard LLM context file
│
├── exports/                  # 📄 Generated outputs
│   ├── notebooklm.pdf        # Visual slides
│   └── kimi.pdf              # Full PDF export
│
├── examples/                 # 📦 Production templates
│   ├── agents/               # Custom AI personas
│   ├── commands/             # Slash commands (/pr, /commit, /diagnose...)
│   ├── hooks/                # Security & automation (bash + PowerShell)
│   ├── skills/               # Reusable knowledge modules
│   ├── scripts/              # Setup & diagnostic utilities
│   ├── github-actions/       # CI/CD workflows
│   ├── config/               # Configuration templates
│   ├── memory/               # CLAUDE.md templates
│   ├── modes/                # Behavioral modes (SuperClaude)
│   └── workflows/            # Advanced workflow guides
│
└── quiz/                     # 🧠 Interactive knowledge quiz (159 questions)

---

🎯 Production-Ready Examples

Copy-paste templates from examples/ for immediate use:

Slash Commands

Command	Purpose	Highlights
/pr	Create PRs with scope analysis	Complexity scoring, auto-split detection
/release-notes	Generate release notes (3 formats)	CHANGELOG + PR body + Slack
/sonarqube	Analyze quality issues	Executive summary, action plans
/commit	Conventional commits	Follows team conventions
/diagnose	Interactive troubleshooting	Bilingual FR/EN, auto-scans environment
/generate-tests	Generate test suites	TDD integration, coverage focus
/review-pr	Review pull requests	Code quality analysis
/git-worktree	Manage git worktrees	Parallel development
/validate-changes	Validate code changes	Pre-commit checks

Security & Automation Hooks

Hook	Event	Purpose
dangerous-actions-blocker.sh	PreToolUse	Block rm -rf /, force push, secrets
prompt-injection-detector.sh	PreToolUse	Detect injection attempts
unicode-injection-scanner.sh	PreToolUse	Detect zero-width, RTL, ANSI escape
repo-integrity-scanner.sh	PreToolUse	Scan README/package.json for injection
mcp-config-integrity.sh	SessionStart	Verify MCP config hash (CVE protection)
output-secrets-scanner.sh	PostToolUse	Detect exposed secrets
notification.sh	Notification	macOS sound alerts
auto-format.sh	PostToolUse	Auto-format with Prettier

See All 14 Hooks — Includes session-logger, security-check, claudemd-scanner, and more

GitHub Actions (CI/CD)

Workflow	Trigger	Purpose
claude-pr-auto-review.yml	PR open	Auto code review with inline comments
claude-security-review.yml	PR open	Security scan (OWASP Top 10)
claude-issue-triage.yml	Issue opened	Auto-triage with labels

See Complete Catalog — Includes agents, skills, memory templates, config files, workflows

---

📖 Guide Navigation

Jump directly to any section in the Ultimate Guide:

Section	After this, you can...	When
1. Quick Start	Run Claude Code and complete your first AI-assisted task	Day 1
2. Core Concepts	Manage context efficiently and avoid common pitfalls	Week 1
3. Memory & Settings	Create CLAUDE.md files that improve AI responses	First project
4. Agents	Build custom AI personas for specialized workflows	Advanced
5. Skills	Package reusable knowledge modules for your team	Scaling
6. Commands	Create custom slash commands with variable interpolation	Automation
7. Hooks	Automate security checks and formatting on every action	Production
8. MCP Servers	Extend Claude with databases, browsers, and external tools	Extended
9. Advanced Patterns	Orchestrate Trinity workflows and CI/CD pipelines	Power user
10. Reference	Look up commands, shortcuts, and troubleshooting tips	Daily

---

🔑 Golden Rules

Master these five principles before diving deeper:

1. Always review diffs before accepting changes — Claude suggests, you decide
2. Use /compact before context hits 70% — prevention beats recovery
3. Be specific in requests — Include WHAT, WHERE, HOW, VERIFY
4. Start with Plan Mode for risky/complex tasks — read-only exploration first
5. Create CLAUDE.md for every project — single source of truth

Context Management Quick Reference:

Context %	Status	Action
0-50%	Green	Work freely
50-70%	Yellow	Be selective
70-90%	Orange	/compact now
90%+	Red	/clear required

These thresholds are based on my experience. Your optimal workflow may differ.

---

🌍 About This Guide

Our Philosophy

Learning journey over reference manual. We focus on:

• Understanding why before diving into how
• Real-world patterns you can use immediately
• Progressive complexity — start simple, master advanced at your pace
• Practical workflows over theoretical concepts

Think of this as a structured learning companion — not just documentation.

Origins & Transparency

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.

Key Inspirations:

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

Created with Claude Code. Community-validated through contributions and feedback. Found an issue? Report it | Contribute

Windows Users: Most commands work with Git Bash. Use %USERPROFILE%\.claude\ for paths. PowerShell scripts may need adjustment. Report Windows issues | Help improve support

Language & Translation

Written in English for wider reach. French is my native language—I can translate directly or leverage AI + community for other languages. Request translations via issues.

---

🤝 Contributing

Found an error? Have a suggestion? See CONTRIBUTING.md for guidelines.

Ways to Help:

• Star the repo to increase visibility
• Report issues (especially Windows-specific)
• Submit PRs with corrections or enhancements
• Share your workflows in Discussions
• Request missing topics or examples

---

📚 Related Resources

Complementary Guides

• zebbern/claude-code-guide — Comprehensive troubleshooting with cybersecurity focus
• Claudelog.com — Tips, patterns, tutorials (highly recommended)
• ykdojo/claude-code-tips — Voice workflows, context management, terminal efficiency
• DeepTo Guide — XML prompts, session continuation, image processing
• Shipyard Cheat Sheet — CLI flags, MCP patterns

Community Collections

• awesome-claude-code — Extensive tool library (19.9k stars)
• awesome-claude-skills — Custom skills
• awesome-claude-code-subagents — Full-stack agents

Frameworks & Advanced Reading

• SuperClaude — Advanced configuration framework
• Nick Tune: Coding Agent Workflows — Autonomous patterns

Official Documentation

• Claude Code Docs — Anthropic official reference

---

📄 License

Licensed under CC BY-SA 4.0. Free to share and adapt with attribution and same-license distribution.

---

⭐ Support This Project

If this guide saved you time, helped you master Claude Code, or inspired your workflows:

1. Star this repository — Help others discover it
2. Share your success stories in Discussions
3. Contribute improvements via Pull Requests
4. Connect on LinkedIn to discuss AI-assisted development

---

Version 3.6.0 | January 2026 | Crafted with Claude