claude-code-ultimate-guide — CLAUDE.md

# 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
├── cowork.md             # Cowork redirect page
├── core/                 # Architecture, methodologies, releases, known-issues, visual-reference
├── security/             # security-hardening, sandbox-isolation, sandbox-native, production-safety, data-privacy
├── ecosystem/            # ai-ecosystem, mcp-servers-ecosystem, third-party-tools, remarkable-ai
├── roles/                # ai-roles, adoption-approaches, learning-with-ai, agent-evaluation
├── ops/                  # devops-sre, observability, ai-traceability
├── diagrams/             # Mermaid visual diagrams
└── 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

| File | Purpose |
|------|---------|
| `VERSION` | Single source of truth for version (currently 3.34.1) |
| `guide/ultimate-guide.md` | The main reference (search here first) |
| `guide/cheatsheet.md` | Quick reference for daily use |
| `machine-readable/reference.yaml` | LLM-optimized index with line numbers |
| `CHANGELOG.md` | All changes with detailed descriptions |

## Commands

### Version Management
```bash
# 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)

```bash
# --- 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).

### Recap Cards (Fiches Mémo Thématiques)

Fiches A4 1-page imprimables, format intermédiaire entre cheatsheet et whitepapers.

```bash
# Single card
cd whitepapers/recap-cards/fr && quarto render 01-commandes-essentielles.qmd --to recap-card-typst

# All FR cards (via script)
cd whitepapers/recap-cards && ./render-recap-cards.sh fr

# All cards (FR + EN)
cd whitepapers/recap-cards && ./render-recap-cards.sh all
```

**Stack** : Extension `recap-card` (`whitepapers/_extensions/recap-card/`). Format `recap-card-typst`. Même palette Bold Guy.

**Source des fiches** : `whitepapers/recap-cards/fr/*.qmd` (FR), `whitepapers/recap-cards/en/*.qmd` (EN à venir).

**25 fiches planifiées** — 5 prototypes Phase 1-2 livrés : 01, 03, 04, 06, 25.

### Before Committing
```bash
# Verify versions are synchronized
./scripts/sync-version.sh --check
```

### Slash Commands (Maintenance)

Custom slash commands available in this project:

| Command | Description |
|---------|-------------|
| `/release <bump-type>` | Release guide version (CHANGELOG + VERSION + sync + commit + push) |
| `/update-infos-release [bump-type]` | Update Claude Code releases tracking + optional guide version bump |
| `/version` | Display current guide and Claude Code versions with stats |
| `/changelog [count]` | View recent CHANGELOG entries (default: 5) |
| `/sync` | Check guide/landing synchronization status |
| `/audit-agents-skills [path]` | Audit quality of agents, skills, and commands in .claude/ config |
| `/security-check` | Quick config check against known threats database (~30s) |
| `/security-audit` | Full 6-phase security audit with score /100 (2-5min) |
| `/update-threat-db` | Research & update threat intelligence database |

**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

### Command Naming Conventions

Implicit prefixes used in `.claude/commands/`:

| Prefix | Pattern | Examples |
|--------|---------|---------|
| `audit-*` | Quality checks with scored output | `audit-agents-skills`, `audit-deps` |
| `update-*` | Sync or refresh data from external source | `update-infos-release`, `update-threat-db` |
| `security-*` | Security scans, ascending depth | `security-check` (quick), `security-audit` (full) |
| *(no prefix)* | Core guide workflow commands | `release`, `sync`, `version`, `changelog` |

When adding a new command, pick the prefix that matches the action type. Avoid creating new prefix categories unless the existing four don't fit.

## Behavioral Rules

These rules come from observed friction patterns in actual sessions on this repo.

### Always update CHANGELOG.md
After any file modification or feature implementation, update `CHANGELOG.md` under `[Unreleased]`. Never skip this step unless explicitly told to. This is the most common missed step.

### Be exhaustive on first pass
When asked to analyze, audit, or review anything — read every relevant file. Do not do a superficial scan. If unsure of scope, ask rather than delivering shallow results. This applies to resource evaluations, doc audits, and codebase reviews.

### Use absolute paths
When referencing files in documentation, reports, or resource evaluations, always use full absolute paths. Never relative paths.

### Closing checklist
After completing all requested tasks, always confirm unprompted:
1. Files changed (list them)
2. CHANGELOG.md updated
3. Committed and pushed (if applicable) — include the commit hash

### Bias toward action
Do not spend extended time in exploration or planning loops. Produce files and concrete output early, then iterate. If stuck for more than 2 attempts on any step, explain the blocker instead of looping.

## 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**:
| Task Type | Model | Justification |
|-----------|-------|---------------|
| Doc edits, typo fixes | Sonnet | Straightforward, no deep reasoning |
| Version sync, formatting | Sonnet | Mechanical pattern matching |
| Guide restructuring | Opus (plan) → Sonnet (execute) | Needs architecture thinking first |
| Research synthesis | Opus (plan) → Sonnet (write) | Complex analysis, then clear writing |
| Multi-file consistency checks | Opus (plan) → Sonnet (fix) | Dependency analysis, then edits |

**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

| Élément | Source (guide) | Destination (landing) |
|---------|----------------|----------------------|
| Version | `VERSION` | index.html footer + FAQ |
| Templates count | Count `examples/` files | Badges, title, meta tags |
| Guide lines | `wc -l guide/ultimate-guide.md` | Badges |
| Golden Rules | README.md | index.html section |
| FAQ | README.md | index.html FAQ |

### 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**.

```bash
# 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

```bash
./scripts/check-landing-sync.sh
```

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

| Check | Source | Comparaison |
|-------|--------|-------------|
| Version | `VERSION` | index.html (footer + FAQ) |
| Templates | `find examples/` | index.html + examples.html |
| Quiz questions | `questions.json` | index.html + quiz.html |
| Guide lines | `wc -l ultimate-guide.md` | index.html (tolérance ±500) |

**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

| Aspect | Détails |
|--------|---------|
| **GitHub** | https://github.com/FlorianBruniaux/claude-code-ultimate-guide |
| **Local** | `/Users/florianbruniaux/Sites/perso/claude-code-ultimate-guide/` |
| **Contenu** | Guide ~19K lignes, 116 templates, workflows,

... [truncated — full content at source]