Claude Code Ultimate Guide - Project Context

Claude Code Ultimate Guide - Project Context

Purpose

This repository is the comprehensive documentation for Claude Code (Anthropic's CLI tool). It teaches users how to use Claude Code effectively through guides, examples, and templates.

Meta-note: This repo documents Claude Code, so its own configuration should be exemplary.

Repository Structure

guide/                    # Core documentation
├── ultimate-guide.md     # Main guide (~20K lines, the reference)
├── cheatsheet.md         # 1-page printable summary
├── architecture.md       # How Claude Code works internally
├── methodologies.md      # TDD, SDD, BDD workflows
├── data-privacy.md       # What data is sent to Anthropic
├── security-hardening.md # Security best practices
└── workflows/            # Step-by-step workflow guides

examples/                 # Production-ready templates
├── agents/               # Custom agent templates
├── commands/             # Slash command templates
├── hooks/                # Event hook examples (bash/powershell)
├── skills/               # Skill module templates
└── scripts/              # Utility scripts (audit, health check)

machine-readable/         # For LLM consumption
├── reference.yaml        # Condensed index (~2K tokens)
└── llms.txt              # AI indexation file

whitepapers/              # Focused whitepapers (FR + EN)
├── fr/                   # 10 source files in French (.qmd)
└── en/                   # 10 translated files in English (.qmd)
# Published at: https://www.florian.bruniaux.com/guides

tools/                    # Interactive utilities
├── audit-prompt.md       # Setup audit prompt
└── onboarding-prompt.md  # Personalized learning prompt

docs/                     # Public documentation (tracked)
└── resource-evaluations/ # External resource evaluations (68 files)

claudedocs/               # Claude working documents (gitignored)
├── resource-evaluations/ # Research working docs (prompts, private audits)
└── *.md                  # Analysis reports, plans, working docs

Key Files

Commands

Version Management

# Check version consistency across all docs
./scripts/sync-version.sh --check

# Fix version mismatches (updates from VERSION file)
./scripts/sync-version.sh

# Bump version
echo "3.7.0" > VERSION && ./scripts/sync-version.sh

Whitepaper Generation (PDF + EPUB)

# --- PDF (default format: whitepaper-typst → Typst → PDF) ---

# Single file
cd whitepapers/fr && quarto render 00-introduction-serie.qmd

# All FR whitepapers
cd whitepapers/fr && quarto render *.qmd

# All EN whitepapers
cd whitepapers/en && quarto render *.qmd

# Preview with hot-reload
cd whitepapers/fr && quarto preview 00-introduction-serie.qmd

# Batch with error summary (loop)
cd whitepapers/fr && for f in *.qmd; do echo "→ $f" && quarto render "$f" 2>&1 | grep -E "(Output created|ERROR)"; done

# --- EPUB (format: epub → Pandoc → EPUB3) ---

# Single file
cd whitepapers/fr && quarto render 00-introduction-serie.qmd --to epub

# All EPUBs (FR + EN) → epub-output/{fr,en}/
cd whitepapers && ./render-epub.sh all
cd whitepapers && ./render-epub.sh fr   # French only
cd whitepapers && ./render-epub.sh en   # English only

PDF stack : Quarto → Typst 0.13 → PDF. Template : whitepapers/_extensions/whitepaper/. Palette Bold Guy (warm beige + orange brûlé).

EPUB stack : Quarto → Pandoc → EPUB3. CSS : whitepapers/epub-styles.css. Cover : _extensions/whitepaper/assets/claude-code-ai-logo.jpg.

Skill disponible : /pdf-generator pour aide contextuelle (template YAML, stack, dépannage).

Before Committing

# Verify versions are synchronized
./scripts/sync-version.sh --check

Slash Commands (Maintenance)

Custom slash commands available in this project:

Examples:

/release patch                 # Bump patch + release (3.20.4 → 3.20.5)
/release minor                 # Bump minor + release (3.20.4 → 3.21.0)
/update-infos-release          # Update CC releases only
/update-infos-release patch    # Update CC + bump guide (3.9.11 → 3.9.12)
/update-infos-release minor    # Update CC + bump guide (3.9.11 → 3.10.0)
/version                       # Show versions and content stats
/changelog 10                  # Last 10 CHANGELOG entries
/sync                          # Check guide/landing sync status
/audit-agents-skills           # Audit current project
/audit-agents-skills --fix     # Audit + fix suggestions
/audit-agents-skills ~/other   # Audit another project
/security-check                # Quick scan config vs known threats
/security-audit                # Full audit with posture score /100
/update-threat-db              # Research + update threat-db.yaml

These commands are defined in .claude/commands/ and automate:

• Claude Code releases tracking (YAML + Markdown + Landing badge)
• Guide version management (VERSION file + sync across all docs)
• CHANGELOG updates
• Landing site synchronization verification
• Git commit and push to both repositories

Conventions

Documentation Style

• Accuracy over marketing: No invented percentages or unverified claims
• Practical examples: Every concept has a concrete example
• Source attribution: Credit community contributions with links
• Version alignment: All version numbers must match VERSION file

File Organization

• New guides → guide/
• New templates → examples/{agents,commands,hooks,skills}/
• Navigation updates → Update both README.md and guide/README.md

Versioning

• VERSION file is the single source of truth
• Run ./scripts/sync-version.sh after changing version
• Files that contain version: README.md, cheatsheet.md, ultimate-guide.md, reference.yaml

Current Focus

Check IDEAS.md for planned improvements and CHANGELOG.md [Unreleased] for work in progress.

Model Configuration

Recommended mode: /model opusplan

Rationale: This documentation repository benefits from hybrid intelligence:

• Planning phase (Opus + thinking): Architecture decisions, research synthesis, multi-file analysis
• Execution phase (Sonnet): Doc updates, version syncing, template edits, formatting

OpusPlan workflow:

1. /model opusplan → Set hybrid mode
2. /plan or Shift+Tab × 2 → Plan with Opus (thinking enabled)
3. Shift+Tab → Execute with Sonnet (faster, cheaper)

Typical task breakdown:

Cost optimization: OpusPlan pays Opus only for planning (typically 10-20% of tokens), Sonnet handles 80-90% of execution work.

Landing Site Synchronization

Important: Ce guide a un site landing associé qui doit être mis à jour après certains changements.

Landing repo: /Users/florianbruniaux/Sites/perso/claude-code-ultimate-guide-landing/

Éléments à synchroniser

Triggers de sync

Après ces modifications, rappeler de mettre à jour le landing:

1. Version bump → Modifier VERSION ici, puis landing
2. Ajout/suppression templates → Recalculer count, mettre à jour landing
3. Modification Golden Rules ou FAQ → Répercuter sur landing
4. Changement significatif du guide (>100 lignes)

Rebuild du guide reader (à chaque release)

Le landing expose le contenu du guide sur cc.bruniaux.com/guide/. Le contenu est généré depuis ce repo au moment du build — jamais commité dans le landing.

# Depuis le repo landing, avant chaque push sur main :
cd ../claude-code-ultimate-guide-landing
node scripts/prepare-guide-content.mjs && pnpm build

Quand le faire : à chaque release (/release patch|minor|major) pour que le site reflète la dernière version du guide.

Commande de vérification

./scripts/check-landing-sync.sh

Ce que fait le script (4 vérifications):

Output attendu (si synchronisé):

=== Landing Site Sync Check ===

1. Version
   Guide:   3.8.1
   Landing: 3.8.1
   OK

2. Templates Count
   Guide:         53 files
   index.html:    53
   examples.html: 53
   OK

3. Quiz Questions
   questions.json: 159
   index.html:     159
   quiz.html:      159
   OK

4. Guide Lines
   Actual:  9881
   Landing: 9800+ (approximate)
   OK (within tolerance)

=== Summary ===
All synced!

En cas de mismatch:

• Le script indique quel fichier est désynchronisé
• Exit code = nombre d'issues trouvées
• Consulter landing/CLAUDE.md pour les numéros de ligne exacts à modifier

Écosystème Complet (4 Repositories)

Ce guide fait partie d'un écosystème de 4 repositories interconnectés, séparant les audiences (devs vs knowledge workers) et les use cases (documentation vs vitrine).

Architecture

        REPOS SOURCES (Documentation)
        ┌──────────────────┬──────────────────┐
        │                  │                  │
    ┌───▼───┐          ┌───▼───┐
    │ Guide │          │Cowork │
    │ Code  │◄────────►│ Guide │
    │ vX.Y  │ liens    │ v1.0  │
    └───┬───┘          └───┬───┘
        │                  │
        │ source           │ source
        │                  │
        LANDING SITES (Vitrine)
        ┌──────────────────┬──────────────────┐
        │                  │                  │
    ┌───▼───┐          ┌───▼───┐
    │ Code  │◄────────►│Cowork │
    │Landing│cross-links│Landing│
    │ vX.Y  │          │ v1.0  │
    └───────┘          └───────┘

1. Claude Code Ultimate Guide (ce repo)

Pour qui: Développeurs utilisant Claude Code CLI

2. Claude Cowork Guide (repo dédié)

Pour qui: Knowledge workers utilisant Claude Desktop (non-devs)

Migration: Le dossier cowork/ a été migré du repo principal vers ce repo dédié (v1.0.0, commit 7a686a8).

3. Code Landing Site

Pour qui: Visiteurs découvrant le guide Code

4. Cowork Landing Site

Pour qui: Visiteurs découvrant le guide Cowork

Synchronisation Inter-Repos

Déclencheurs de mise à jour multi-repos:

Scripts de vérification:

# Vérifier sync Code Landing
./scripts/check-landing-sync.sh

# Vérifier sync Cowork
cd ../claude-cowork-guide && ./scripts/check-version-sync.sh

Relations & Liens

Guide Code → Cowork Guide:

• guide/cowork.md: Summary avec liens vers repo dédié
• guide/README.md: Table avec 6 liens vers guides Cowork
• machine-readable/reference.yaml: 23 entrées pointant vers GitHub

Landing Code ↔ Landing Cowork:

• Cross-links bidirectionnels (hero, ecosystem, sections)
• Navigation fluide entre les 2 audiences

Principe: Séparation claire des audiences, navigation facilitée, synchronisation maintenue.

Historique de l'Écosystème

Résultat: 7 commits, 4 repos synchronisés, -8,297 lignes (cleanup massif), écosystème opérationnel.

Research Resources

Perplexity Pro disponible: Pour toute recherche nécessitant des sources fiables ou des informations récentes sur Claude Code, Anthropic, ou les pratiques de développement assisté par IA:

• Demande-moi de faire une recherche Perplexity (plus efficace que WebSearch basique)
• Je te fournirai les résultats avec les sources
• Utile pour: nouvelles features Claude Code, best practices communauté, comparaisons d'outils, documentation officielle mise à jour

Claude Code Releases Tracking

Ce repo maintient un historique condensé des releases officielles de Claude Code.

Fichiers

Vérifier les nouvelles versions

./scripts/update-cc-releases.sh

Le script:

1. Fetch le CHANGELOG officiel depuis GitHub
2. Compare avec notre version trackée
3. Affiche les nouvelles releases à condenser

Workflow de mise à jour

1. Vérifier: ./scripts/update-cc-releases.sh
2. MAJ YAML: Ajouter nouvelle entrée dans claude-code-releases.yaml
   • Mettre à jour latest et updated
   • Ajouter l'entrée dans releases (condensée: 2-4 highlights max)
   • Ajouter aux breaking_summary si applicable
   • Ajouter aux milestones si feature majeure
3. MAJ Markdown: Mettre à jour claude-code-releases.md en cohérence
4. Landing sync: ./scripts/check-landing-sync.sh
5. Commit: docs: update Claude Code releases (vX.Y.Z)

Format des entrées YAML

- version: "2.1.13"
  date: "2026-01-20"
  highlights:
    - "Feature principale"
    - "Autre feature notable"
  breaking:
    - "Description du breaking change (si applicable)"

Resource Evaluation Workflow

External resources (articles, videos, discussions) are evaluated before integration into the guide.

Process

1. Research: Initial Perplexity search → Save prompt + results in claudedocs/resource-evaluations/ (private) 1b. Cross-reference: Si ressource liée à Claude Code, vérifier les claims contre https://code.claude.com/docs/llms-full.txt (source officielle ~98KB)
2. Evaluation: Systematic scoring (1-5) → Create evaluation file in docs/resource-evaluations/ (tracked)
3. Challenge: Technical review by agent to ensure objectivity
4. Decision: Integrate (score 3+), mention (score 2), or reject (score 1)

File Organization

Scoring Grid

See full methodology: docs/resource-evaluations/README.md

Quick Lookups

For answering questions about Claude Code: 0. Doc officielle Anthropic (LLM-optimized): https://code.claude.com/docs/llms.txt (index ~65 pages) ou https://code.claude.com/docs/llms-full.txt (doc complète ~98KB) pour les faits officiels

1. Search machine-readable/reference.yaml first (has line numbers to full guide)
2. Use those line numbers to read relevant sections from guide/ultimate-guide.md
3. Check examples/ for ready-to-use templates
4. Check guide/claude-code-releases.md for recent features/changes
5. Si info manquante ou incertaine → demander une recherche Perplexity (communauté, comparaisons, retours)