Avant-proposPourquoi ce livre existe

Si tu utilises Claude Code depuis plus de deux semaines, tu as sans doute remarqué un motif : les 10 premières minutes de chaque session sont consacrées à ré-expliquer ta stack, tes conventions, ce que tu as corrigé hier. Tu corriges les mêmes dérives encore et encore. Tu découvres que Claude a écrit une commande destructrice dans ton .env. Tu cesses de lui faire confiance pour quoi que ce soit de sérieux.

Rien de tout cela n'est la faute de Claude. C'est un artefact d'un LLM lancé sans contexte projet, sans garde-fous, sans mémoire. Ce manuel corrige ça, pas avec un framework ni une abstraction lourde, mais avec un petit ensemble de fichiers qui vivent dans ton repo et transforment Claude Code en collaborateur reproductible et opinionné.

À la fin du livre, tu auras :

• Un contexte projet permanent (un CLAUDE.md chargé à chaque session)
• Des garde-fous défensifs qui bloquent les commandes destructrices
• Des sub-agents spécialisés pour l'audit code, la sécu, et ton domaine métier
• Un système de skills pour les connaissances métier qui survivent aux re-clones
• Un workflow plan-first avec un « staff engineer » qui relit avant que tu codes
• Une boucle d'audit qui détecte la dérive avant toi

L'ensemble prend ~30 minutes à amorcer et quelques heures à affiner. Le gain composé se mesure en jours économisés par trimestre.

Ceci est la V2 du manuel. Nouveau : chapitres complets sur les skills, le workflow plan-first inspiré du créateur de Claude Code Boris Cherny, la boucle d'audit, les worktrees parallèles, et la matrice mémoire à 4 lieux. Les deux études de cas en annexe (un dev solo et une knowledge worker) montrent le setup en vrai.

Pour quiCe livre est pour toi si…

Oui, c'est pour toi

• Tu es développeur (toute stack, tout niveau) et tu utilises Claude Code au quotidien, ou veux le faire.
• Tu es un knowledge worker, rédacteur, chercheur, analyste, qui utilise Claude Code pour écrire, faire de la recherche, générer du contenu, et tu veux un setup stable et reproductible plutôt que de recommencer à chaque session.
• Tu es solo founder ou lead d'une petite équipe et tu veux multiplier ton output sans embaucher.
• Tu fais partie d'une équipe qui veut une baseline partagée et opinionnée pour que tout le monde configure Claude pareil, et que le setup lui-même soit reviewable en PR.
• Tu n'es pas natif anglais, tout le livre est en français avec la même profondeur, aucun raccourci.

Ce livre n'est PAS pour toi (encore) si…

• Tu n'as jamais ouvert un terminal. Commence par la doc officielle Anthropic, code.claude.com/docs. Reviens quand tu as installé Claude Code et eu une 1ère session.
• Tu veux 500 pages de référence encyclopédique. Ici c'est 52 pages, lisibles en 2 heures. Si tu veux le format encyclopédie avec 181 templates de skills et 271 questions de quiz, le Ultimate Guide de Florian Bruniaux est excellent.
• Tu attends que ce livre écrive du code à ta place. Ce livre parle de configurer Claude Code, pas de te remplacer par lui. Tu écriras toujours le code, les plans, les décisions. Claude sera juste plus utile, plus rapide, plus fiable.

Ce que tu auras à la fin

• Un repo où chaque nouvelle session Claude Code charge ton contexte automatiquement, refuse les opérations destructrices, et se souvient de ce que tu lui as appris la semaine dernière.
• Une petite boîte à outils d'assistants spécialisés (sub-agents) à qui tu fais assez confiance pour déléguer.
• Une discipline, planifier avant de coder, capter les leçons après, qui se compose dans le temps.

Note sur le vocabulaire : ce livre utilise quelques termes spécifiques (hook, sub-agent, frontmatter, skill, MCP). Chacun est défini à sa première apparition et à nouveau dans le glossaire (Annexe F). Pas besoin de les apprendre avant ; continue.

Comment lireCe livre

Trois parcours de lecture

Conventions typographiques

• code dans le texte, chemins de fichiers, commandes, noms de variables
• Gras, concepts introduits pour la première fois
• Italique, citations de l'interface utilisateur ou premier usage d'un terme externe

Badges de difficulté

Chaque chapitre porte un badge :

DÉBUTANT   Les 30 premières minutes de setup ; aucun pré-requis Claude Code.

INTERMÉDIAIRE   Construit sur les bases ; suppose qu'au moins un hook et un agent sont configurés.

AVANCÉ   Patterns de workflow et méta-outillage. À lire après une semaine d'usage du setup.

Encadrés

Chapitre 00 DÉBUTANTChoisir son interface

Avant de configurer quoi que ce soit, sache où tu vas l'installer. Toutes les surfaces Claude Code supportent les mêmes mécanismes, mais Claude Code reste distinct du produit Claude.ai (chat).

Les 6 surfaces officielles Claude Code

Toutes lisent la même config .claude/ dans ton repo. Tu peux switcher entre elles sans rien re-configurer.

Recommandation par profil

Chapitre 01 DÉBUTANTPhilosophie & ROI

La différence entre quelqu'un qui utilise Claude et quelqu'un qui en tire 10× plus, ce n'est pas le prompt. C'est ce qui se passe autour du prompt.

Le problème du « vibe-coding »

Quand tu utilises Claude sans configuration, voici ce qui se passe à chaque session :

1. Tu réexpliques ta stack (« on est en Next.js 16, attention au breaking de revalidate… »).
2. Tu réexpliques tes conventions (« camelCase pour les fonctions, kebab-case pour les fichiers… »).
3. Claude part dans une direction, tu corriges (« non, ici on utilise pas alert(), c'est un toast »).
4. Claude lance une commande dangereuse, tu valides 4 pop-ups pour des trucs anodins.
5. Tu oublies de lancer pnpm verify avant un push, la CI crash.
6. Tu refais la même séquence demain.

Multiplie par 250 sessions par an. Tu réalises que tu as passé des semaines à faire du contexte jetable.

L'idée centrale

Tout ce que tu dis à Claude plus de 3 fois doit vivre dans un fichier. Tout ce que Claude fait plus de 3 fois sans intervention humaine doit être un hook.

Les 3 principes

Le ratio temps investi / temps gagné

Total setup : une demi-journée. Gain estimé : 15-30 min par jour de travail actif. Sur 200 jours par an, ça fait 50-100 heures économisées.

Ce que ce setup ne fait PAS pour toi (nouveau en V2)

C'est tentant de lire le reste du livre comme « la config magique qui résout tout ». Elle ne le fait pas. Connaître les limites à l'avance évite la déception après.

• Elle ne va pas rendre Claude plus rapide. Le nombre de tokens augmente légèrement (CLAUDE.md, skills, prompts d'agents consomment tous du contexte). Le ROI est dans les corrections évitées, pas la génération plus rapide.
• Elle ne va pas écrire tes tests pour toi. Un agent code-auditor flagge les tests manquants ; il ne les écrit pas.
• Elle ne remplace pas le jugement humain. Plan-reviewer (Chapitre 07) est un 2e avis, pas un gate. C'est toi qui décides.
• Elle ne va pas fixer ta codebase rétroactivement. Un setup propre appliqué à 50k LOC en bordel laisse le bordel. Le setup se compose pour l'avenir.
• Elle ne supprime pas le besoin de relire le code. Si tu délègues tout aveuglément sans jamais lire le diff, tu as remplacé un problème par un pire.

Chapitre 02 DÉBUTANTLe setup minimum viable

Objectif : transformer ton Claude en 30 minutes. Aucun pré-requis. Juste 3 fichiers à créer. À la fin, une nouvelle session dans ton repo chargera ton contexte automatiquement, refusera les opérations destructrices, et n'aura plus de pop-ups pour les commandes git/ls/cat habituelles.

Étape par étape

1. Installer Claude Code

Selon ton OS et ta surface :

# macOS, Linux, WSL, installation native (recommandée, auto-update)
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

# macOS via Homebrew
brew install --cask claude-code

# Windows via WinGet
winget install Anthropic.ClaudeCode

Puis dans n'importe quel dossier de projet :

cd ton-projet
claude

Pour les IDE : Extensions → chercher « Claude Code » (VS Code, Cursor, JetBrains). Pour le navigateur : claude.ai/code. Pour l'app : télécharger depuis claude.ai. Toutes ces surfaces lisent les mêmes fichiers .claude/.

2. Créer CLAUDE.md à la racine du projet

C'est le brain de ton projet. Claude le charge automatiquement à chaque session. Template minimal :

# <Nom du projet>

Description en 1 phrase de ce que fait le projet.

## Stack technique
- Langage : <TypeScript 5 | Python 3.12 | Go 1.22 | ...>
- Framework : <Next.js 16 | FastAPI | Rails | ...>
- DB : <Postgres | SQLite | MongoDB | ...>
- Tests : <vitest | pytest | jest>
- Déploiement : <Vercel | Fly.io | Railway | ...>

## Commandes utiles
- `<commande dev>`, lancer le serveur local
- `<commande verify>`, type-check avant push
- `<commande test>`, lancer la suite de tests

## Conventions
- <Règle de nommage> (ex : camelCase JS, kebab-case fichiers)
- <Règle de structure> (ex : chaque page a son `actions.ts`)
- <Règle de comportement> (ex : jamais `alert()`, toujours toast)

## Gotchas
- <Piège connu de la stack>
- <Piège interne au projet>

## Workflow Git
- Branche cible : `<main | master>`
- Format de commit : `type(scope): description`

## Règles impératives
- **Ne jamais** <X> sans confirmation
- **Toujours** <Y> avant <Z>

3. Créer .claude/settings.json

Le fichier qui contrôle les permissions et les hooks. Template minimal qui élimine 80 % des pop-ups :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(git show:*)",
      "Bash(git branch:*)",
      "Bash(ls:*)",
      "Bash(cat:*)",
      "Bash(find:*)",
      "Bash(head:*)",
      "Bash(tail:*)",
      "Bash(wc:*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(sudo*)",
      "Bash(curl* | bash*)"
    ]
  }
}

Adapte la liste allow à ta stack (ajoute "Bash(pnpm verify)", "Bash(npm test:*)", etc.).

4. Ajouter .claude/ au .gitignore (sélectivement)

Tu veux versionner les fichiers d'équipe mais pas les logs locaux :

# Claude Code, versionner agents/commands/hooks/settings.json,
# mais pas les logs ni les overrides perso
.claude/*
!.claude/agents/
!.claude/commands/
!.claude/hooks/
!.claude/settings.json
.claude/logs/
.claude/settings.local.json

5. Tester

Lance Claude Code. Pose une question : « Lis CLAUDE.md et résume la stack en 3 lignes. » S'il te répond correctement avec ce que tu as mis dans le fichier → ✅ ça marche. Sinon : vérifie que le fichier est bien à la racine du projet, pas dans src/ ou ailleurs.

Ce que tu as gagné en 30 minutes

• Plus jamais besoin de réexpliquer la stack ou les conventions.
• Plus de pop-ups pour les commandes git/ls/cat classiques.
• Les commandes dangereuses (rm -rf, sudo) sont bloquées.
• Le repo est prêt pour les niveaux suivants.

Checkpoint, à quoi ressemble une session bien configurée (nouveau en V2)

Après avoir lancé claude dans un repo fraîchement configuré, tu devrais voir quelque chose comme :

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  todo-api · session démarrée · Ven 22 Mai 09h22
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Branch       : main
  Working tree : clean
  Derniers commits :
    a3b1f0  feat(api): add DELETE /todos/:id
    9d2e84  fix(db): handle missing connection string
    1c7a55  chore: bump express to 4.21
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Si tu vois ça, 3 choses marchent : le hook SessionStart tourne, ton CLAUDE.md est chargé silencieusement, et ta commande git status est autorisée par l'allowlist. Si quelque chose cloche, va voir Debug d'un hook silencieux au chapitre 03.

Chapitre 03 DÉBUTANTHooks

Un hook est un script déclenché par un événement. Zéro token, zéro intervention de Claude, zéro friction. C'est la couche d'« automatisation déterministe » que Claude ne voit même pas.

Les 4 événements clés (parmi ~25)

Claude Code expose environ 25 événements. Ce manuel couvre les 4 qui gèrent 80 % des besoins. Liste complète dans la doc officielle code.claude.com/docs/en/hooks.

Hook #1, PostToolUse : auto-format après chaque écriture

Crée .claude/hooks/post-edit-format.sh :

#!/usr/bin/env bash
# Auto-format des fichiers après Write/Edit.
# Adapte le formatter à ta stack : prettier, black, gofmt, rustfmt...
set -e

INPUT="$(cat 2>/dev/null || echo '{}')"
FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
[ -z "$FILE" ] || [ ! -f "$FILE" ] && exit 0

case "$FILE" in
  *.ts|*.tsx|*.js|*.jsx|*.mjs) ;;
  *) exit 0 ;;
esac

cd "$(dirname "$0")/../.."
pnpm exec prettier --write "$FILE" >/dev/null 2>&1 || true
exit 0

N'oublie pas chmod +x .claude/hooks/post-edit-format.sh.

Hook #2, PreToolUse : garde-fou défensif

Ce hook est le plus important. Il bloque les commandes destructrices avant qu'elles ne tournent. Crée .claude/hooks/pre-tool-guard.sh :

#!/usr/bin/env bash
# Garde-fous : bloquer les actions destructrices avant exécution.

INPUT="$(cat 2>/dev/null || echo '{}')"
TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)

# 1. Bloquer toute écriture dans .env*
if [ "$TOOL" = "Edit" ] || [ "$TOOL" = "Write" ]; then
  FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null)
  case "$FILE" in
    *.env|*.env.*|.env)
      echo "BLOCKED: fichier .env protégé. Utilise les env vars du provider." >&2
      exit 2
      ;;
  esac
fi

# 2. Bloquer les Bash dangereux
if [ "$TOOL" = "Bash" ]; then
  CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)

  if echo "$CMD" | grep -qE 'rm[[:space:]]+-[a-zA-Z]*[rf][a-zA-Z]*[[:space:]]+(/|~|\.\./|\$HOME)'; then
    echo "BLOCKED: rm -rf sur un chemin dangereux." >&2
    exit 2
  fi

  if echo "$CMD" | grep -qE 'git[[:space:]]+push.*(--force|--force-with-lease)'; then
    echo "BLOCKED: git push --force. Demande confirmation explicite." >&2
    exit 2
  fi
fi

exit 0

Hook #3, SessionStart : récap projet

À l'ouverture d'une session, affiche l'état du projet en 5 lignes. Crée .claude/hooks/session-start.sh (cf. version EN, identique sauf strings d'affichage).

Activer les hooks dans settings.json

{
  "permissions": { /* ... cf. Chapitre 02 ... */ },
  "hooks": {
    "SessionStart": [
      { "matcher": "*", "hooks": [
        { "type": "command", "command": ".claude/hooks/session-start.sh" }
      ]}
    ],
    "PreToolUse": [
      { "matcher": "Edit|Write|Bash", "hooks": [
        { "type": "command", "command": ".claude/hooks/pre-tool-guard.sh" }
      ]}
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [
        { "type": "command", "command": ".claude/hooks/post-edit-format.sh" }
      ]}
    ]
  }
}

Tester un hook sans redémarrer la session

# Simuler un événement PreToolUse
echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' \
  | .claude/hooks/pre-tool-guard.sh
echo "Exit code: $?"
# Doit imprimer "BLOCKED: rm -rf..." et exit 2

Debug d'un hook silencieux (nouveau en V2)

Le bug le plus fréquent c'est « le hook ne fait rien ». Trois diagnostics rapides avant de fouiller le script :

1. Est-il exécutable ? ls -la .claude/hooks/, chaque .sh doit avoir le bit x. chmod +x .claude/hooks/*.sh.
2. Est-il branché dans settings.json ? Vérifie que le matcher et le command path matchent. Une typo dans le path échoue silencieusement.
3. Quel input voit-il ? Ajoute cat > /tmp/hook-debug.json en haut du script pour capturer le JSON réel envoyé par Claude Code. Inspecte, puis retire.

Chapitre 04 INTERMÉDIAIRESlash commands

Une slash command est un raccourci qui te donne un workflow en tapant /<nom>. C'est ta couche de « playbooks réutilisables ».

Deux façons de créer une commande

Chemin A, Simple : .claude/commands/<nom>.md

Un seul fichier markdown avec frontmatter + instructions. Couvre 90 % des cas.

---
description: "Verify + commit + push en 1 commande"
argument-hint: "<message de commit>"
---

# /ship, Verify, commit & push

## Procédure

### 1. Pré-check
Lance la commande typecheck (ex. `pnpm verify`). Si rouge → STOP, montre
les erreurs, demande à l'utilisateur si fix ou abandon. Jamais de commit
avec typecheck rouge.

### 2. État git
Lance `git status --short` et `git diff --stat`. Montre les fichiers
modifiés. Si zéro fichier → « Rien à commit » et stop.

### 3. Construire le commit
Message = `$ARGUMENTS`. Si vide ou < 10 chars, demande un message
plus clair. Formate selon le style projet : `type(scope): résumé`.

### 4. Stage + commit + push
1. `git add` des fichiers précis (pas `git add .` aveugle)
2. `git commit -m "..."` avec le message construit
3. `git push origin <branche cible>`

### 5. Confirmation
Affiche le SHA, le message, le résumé insertions/deletions.

## Garde-fous
- **Jamais** de `--no-verify` sauf demande explicite.
- **Jamais** de force-push sans confirmation explicite.
- Si le push échoue (rejected) : pull `--no-rebase`, résoudre, re-push.

Chemin B, Puissant : .claude/skills/<nom>/SKILL.md

Un dossier dédié avec un SKILL.md + fichiers compagnons (scripts, références). Mieux quand le workflow utilise des scripts bundlés ou de la doc détaillée. Le chapitre 06 détaille la discipline du dossier skill, la même s'applique ici.

3 commandes à coder en semaine 3

/ship "<message>", deploy en 1 ligne

Template ci-dessus. C'est la commande la plus utile. Remplace ta routine commit/push manuelle et garantit que le typecheck passe.

/audit-quick, audit code + sécu en parallèle

---
description: "Audit rapide : code + sécu en parallèle, rapport synthétisé"
---

# /audit-quick, Audit pré-release

Lance ces 2 agents EN PARALLÈLE (même message, plusieurs tool calls) :

**Agent code-auditor** :
> Audite le code, focus : code mort, duplication, anti-patterns,
> `any` injustifiés. Rapport ≤ 500 mots ranked 🔴/🟠/🟡.

**Agent security-auditor** :
> Audite la sécu, focus : RLS, secrets, XSS, exposition PII, OWASP.
> Rapport ≤ 500 mots ranked 🔴/🟠/🟡.

Quand les deux finissent, présente un rapport unifié :
- 🔴 Bloquants
- 🟠 Importants
- 🟢 OK

Termine par UNE recommandation prioritaire.

/standup, récap quotidien

---
description: "Récap matinal : commits 24h, WIP, focus suggéré"
---

# /standup

Lance en parallèle :
- `git log --since='24 hours ago' --oneline`
- `git status --short` + `git diff --stat`

Rapport en 3 sections, ≤ 200 mots :
- 🟢 Fait hier
- 🟡 En cours (WIP)
- 🎯 Focus du jour (suggestion)

Termine par une question : « On attaque le focus #1 ou autre chose ? »

Le pattern $ARGUMENTS

Quand l'utilisateur tape /ship "fix: header typo", la string entre guillemets est disponible dans la slash command via $ARGUMENTS. Utilise-la pour personnaliser le comportement. Formes indexées ($0, $1, $ARGUMENTS[N]) pour accéder aux arguments individuels.

Quand créer une slash vs un sub-agent vs une skill (nouveau en V2)

Erreur courante du débutant : utiliser la mauvaise primitive. Voici la matrice de décision :

Chapitre 05 INTERMÉDIAIRESub-agents

Un sub-agent est un rôle spécialisé avec son propre contexte, son modèle, ses outils et son system prompt. Tu le déclenches sur une tâche précise et il renvoie un résultat structuré.

Pourquoi diviser plutôt que tout faire en un

1. Contexte préservé, chaque agent démarre avec un contexte propre, ne pollue pas la session principale.
2. Périmètre restreint, un agent d'audit n'a pas d'outils Write/Edit. Il ne peut pas casser le code.
3. Modèle adapté, un audit complexe utilise opus, une classification rapide haiku. Tu optimises le coût.
4. Spécialisation, l'agent sécu connaît OWASP ; l'agent métier connaît tes conventions. Pas mélangés.

Anatomie d'un agent

Un agent est un fichier markdown sous .claude/agents/<nom>.md avec un frontmatter YAML et un system prompt en markdown.

---
name: code-auditor
description: >
  Audit READ-ONLY de qualité de code. Use proactively quand l'utilisateur
  dit "audite le code", "review", ou avant un gros refactor.
  Détecte : code mort, duplication, complexité, anti-patterns, `any`
  injustifiés. Ne modifie AUCUN fichier, produit un rapport structuré.
model: opus
tools: Read, Grep, Glob, Bash, WebFetch
---

Tu es un auditeur de code senior pour le projet <nom>. Tu travailles
uniquement en lecture.

## Contexte projet
- Stack : <résumé court>
- Conventions à respecter (cf. CLAUDE.md) : <résumé court>

## Ta mission
Pour chaque fichier audité, identifie :
1. **Code mort** : fonctions, variables, imports inutilisés
2. **Duplication** : patterns répétés à factoriser
3. **Complexité** : fonctions > 30 lignes, conditionnels imbriqués > 3
4. **Anti-patterns** : useEffect mal utilisés, queries non-parallélisées, `any`

## Format de sortie
Pour CHAQUE finding :
- **Sévérité** : 🔴 / 🟠 / 🟡 / 🟢
- **Fichier:ligne**
- **Constat** + **Impact** + **Fix recommandé**

Termine par : Score /10 + Top 3 actions prioritaires.

## Règles
- Read-only : pas d'Edit, pas de Write.
- Ne fais pas du nitpicking de style si le linter le couvre déjà.
- Priorise ce qui a un vrai impact sur la maintenabilité.

Choisir le modèle

Le champ model accepte un alias (sonnet, opus, haiku), un ID complet, ou inherit (défaut). Le pricing varie ; en pratique sonnet et opus coûtent plusieurs fois plus cher que haiku.

Règle empirique : tout audit pouvant perdre des données ou compromettre la prod → opus. Le reste → sonnet par défaut. haiku quand la vitesse prime sur la profondeur.

Restreindre les outils (moindre privilège)

Donne uniquement les outils dont l'agent a besoin. Un auditeur read-only n'a jamais Write/Edit/Bash dangereux.

Combien d'agents au maximum

Démarre avec ces 3 agents qui couvrent 80 % des cas :

1. code-auditor, audit qualité (template ci-dessus)
2. security-auditor, RLS, secrets, OWASP, RGPD (cf. Annexe D)
3. qa-tester, flows utilisateur bout en bout après un gros changement

Ajoute-en plus quand tu identifies un besoin récurrent.

Invoquer un sub-agent

• Automatique, Claude lit la description et déclenche l'agent quand le pattern match.
• Explicite, l'utilisateur dit « Lance security-auditor sur les server actions de la semaine ».
• Via une slash command, qui wrap l'invocation avec du contexte pré-formaté (cf. Chapitre 04).

Écrire la description qui déclenche vraiment (nouveau en V2)

Le champ description du frontmatter d'un agent est lu par Claude pour décider d'invoquer cet agent. C'est du prompt engineering sur une seule phrase. Trois versions du même agent :

Trop vague (déclenche rarement)

description: Audite la qualité du code.

Trop spécifique (déclenche trop)

description: Tourne à chaque save de fichier pour vérifier la qualité,
la perf, la sécu, l'a11y, le nommage, les commentaires, et la solidité
architecturale du code.

Calibrée (déclenche quand il faut)

description: Audit read-only de qualité de code. Use proactively quand
l'utilisateur dit "audite le code", "trouve les optimisations", "review
ce fichier", ou avant un gros refactor. Produit un rapport structuré de
code mort, duplication, anti-patterns, types `any` injustifiés. NE modifie
PAS les fichiers.

Le pattern : ce que ça fait + « Use proactively quand… » avec phrases déclencheurs concrètes + ce que ça produit + ce que ça ne fait pas. La dernière partie compte : elle dit à Claude quand ne pas invoquer cet agent.

Chapitre 06 INTERMÉDIAIRESkills (la bonne méthode)

Une skill est un corpus versionné et structuré de connaissances métier qui vit dans ton repo et que Claude (ou un de tes agents) charge à la demande. C'est la troisième primitive de Claude Code, à côté des hooks et des sub-agents. Les skills existent pour résoudre UN problème spécifique : la connaissance métier qui dérive.

graph LR
    Project[Ton projet] --> CLAUDE[CLAUDE.md]
    CLAUDE -->|référence| Agent[Agent :
commit-reviewer]
    Agent -->|charge à la demande| Skill[Skill :
conventional-commits]
    Skill --> R1[format-type-required.md]
    Skill --> R2[format-scope-optional.md]
    Skill --> R3[breaking-change-marker.md]
    Skill --> R4[...]
    style Skill fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Agent fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px
    

Le problème que les skills résolvent

Imagine que tu répètes à Claude « dans notre codebase, les dates sont stockées en UTC et formatées avec le fuseau de l'utilisateur à l'affichage ». Tu le documentes dans CLAUDE.md. Deux mois plus tard, tu ajoutes une deuxième règle sur les dates. Puis une troisième. Puis ton agent qui review du code commence à avoir ses propres opinions sur les dates parce que personne n'a mis à jour son system prompt. Tu as maintenant trois sources de vérité concurrentes : CLAUDE.md, le prompt de l'agent, et de la mémoire informelle.

Une skill rassemble tout ça à un seul endroit. L'agent cesse d'avoir des opinions ; il charge la skill. CLAUDE.md cesse de lister les règles ; il pointe vers la skill. La skill est structurée pour qu'ajouter une nouvelle règle soit un changement à un seul fichier.

Anatomie d'une skill

La structure officielle (celle des skills publiées par Anthropic) est un dossier sous .agents/skills/<nom>/ contenant :

.agents/skills/conventional-commits/
├── SKILL.md                       ← point d'entrée + metadata
└── references/
    ├── _sections.md               ← définition des catégories
    ├── _template.md               ← template pour nouvelle règle
    ├── _contributing.md           ← guide de style
    ├── format-type-required.md    ← règle 1
    ├── format-scope-optional.md   ← règle 2
    ├── format-description-imperative.md
    └── breaking-change-marker.md  ← règle 4

La convention de nommage <préfixe>-<sujet>.md compte : ça permet de parcourir la skill alphabétiquement et de grouper par catégorie. Les trois fichiers à underscore (_sections, _template, _contributing) sont du scaffolding, pas des règles.

SKILL.md, le point d'entrée

Frontmatter minimum :

---
name: conventional-commits
description: Règles du format Conventional Commits et anti-patterns.
  Use this skill quand tu écris un commit message, reviewes les commits
  d'une PR, ou conçois un workflow CHANGELOG-from-git.
license: MIT
metadata:
  author: ton-nom
  version: "1.0.0"
  date: 2026-05
  abstract: Règles Conventional Commits (type, scope, description, marker
    breaking change) avec exemples Incorrect → Correct et une carte des
    catégories.
---

Le corps de SKILL.md explique ensuite quand appliquer la skill et comment utiliser le dossier references/. Deux sections, c'est tout. Ne mets pas les règles dans SKILL.md ; mets-les dans references/.

Un fichier de référence, le pattern Incorrect → Correct

Chaque fichier de règle suit la même structure : 1–2 phrases pour expliquer pourquoi ça compte, puis la version Incorrect (le piège), puis la version Correct. Exemple concret, depuis references/format-type-required.md :

---
title: Tout commit message doit commencer par un préfixe de type
impact: HIGH
impactDescription: "Sans type, la génération de CHANGELOG saute le commit
  et les reviewers ne peuvent pas filtrer par feature/fix/refactor."
tags: format, type, prefix
---

## Préfixe de type obligatoire

Le premier token du subject line doit être un type reconnu
(`feat`, `fix`, `refactor`, `docs`, `chore`, `test`, `style`,
`perf`, `build`, `ci`, `revert`), suivi d'un scope optionnel
entre parenthèses, puis deux-points et un espace.

**Incorrect :**

```
Add login form validation
```

Ce commit ne peut pas être classé. Les générateurs de CHANGELOG
vont le sauter ou le mettre dans « Autre ».

**Correct :**

```
feat(auth): add login form validation
```

`feat` dit que c'est une nouvelle feature ; `(auth)` la localise ;
la description est à l'impératif présent.

### Cas particuliers

- Un revert : `revert: feat(auth): add login form validation`
- Un breaking : `feat(auth)!: replace cookies with JWT`
- Merges : skip (auto-générés, pas besoin de convention)

Remarque la discipline :

• Le frontmatter déclare impact et impactDescription, Claude peut prioriser quand plusieurs règles s'appliquent.
• Le titre est action-oriented (« doit commencer par un type »), pas abstrait (« sur les types »).
• Incorrect vient avant Correct, ça entraîne le lecteur à reconnaître l'anti-pattern sur le terrain.
• Les cas particuliers sont listés. Ne laisse pas le lecteur deviner.

Wiring de la skill à un agent

Une skill qu'aucun agent ne charge est du poids mort. Le wiring tient en un bloc en tête de prompt d'agent :

# Dans .claude/agents/commit-reviewer.md

## Sources de vérité (à charger AVANT toute review de commit)

→ `.agents/skills/conventional-commits/SKILL.md`
  + `.agents/skills/conventional-commits/references/*.md` (4 règles couvertes)

Si une recommandation que tu veux faire est déjà dans la skill,
cite la référence (ex : `references/format-type-required.md`)
plutôt que de réécrire la règle. La skill fait foi.

C'est tout le pattern : pointe vers la skill, ne la duplique pas. Si tu te retrouves à copier une règle d'une skill dans le prompt d'un agent, arrête. Modifie la skill plutôt, et laisse l'agent la référencer.

Anti-patterns qui tuent les skills

Chapitre 07 AVANCÉDéveloppement plan-first

graph TB
    Idea[Ton idée] --> Step0[Étape 0 : Capture du scope]
    Step0 --> Step1[Étape 1 : Écrire PLAN_slug.md]
    Step1 --> Step15[Étape 1.5 : agent plan-reviewer
verdict 🟢 / 🟡 / 🔴]
    Step15 -->|🟢 GO| Step2[Étape 2 : Code fichier par fichier]
    Step15 -->|🟡 ajuster| Patch[Patch du plan]
    Patch --> Step15
    Step15 -->|🔴 STOP| Rethink[Repenser ou abandonner]
    Step2 --> Step3[Étape 3 : Verify]
    Step3 -->|rouge| Fix[Fix erreurs]
    Fix --> Step3
    Step3 -->|vert| Step4[Étape 4 : Audits ciblés en parallèle]
    Step4 --> Step5[Étape 5 : /ship]
    style Step15 fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px
    style Step5 fill:#dcfce7,stroke:#15803d,stroke-width:2px
    style Rethink fill:#fee2e2,stroke:#b91c1c
    

La façon la plus rapide de gâcher un après-midi avec Claude Code est de taper « construis la feature X » et de le laisser faire. Même si le résultat semble raisonnable, tu découvriras souvent au fichier #6 que l'architecture était fausse dès le fichier #2. Le développement plan-first inverse la boucle : écris le plan dans un fichier markdown, fais-le relire, puis code. Coût : 30 secondes en amont. Gain : éviter le refacto d'1 heure.

« Si mon objectif est d'écrire une Pull Request, j'utilise le Plan mode et je fais des allers-retours avec Claude jusqu'à ce que j'aime son plan. Ensuite, je passe en auto-accept edits et Claude peut généralement faire ça d'un coup. Un bon plan est vraiment important. »
— Boris Cherny, créateur de Claude Code

Le pipeline /new-feature

Crée .claude/commands/new-feature.md avec le pipeline suivant :

---
description: "Pipeline orchestré pour tout chantier conséquent : plan → review → code → verify → audits"
argument-hint: "<description courte de la feature>"
---

# /new-feature, Pipeline guidé

À utiliser quand le chantier touche **≥ 3 fichiers**, OU un module
critique (paiements, auth, calculs), OU une migration DB, OU une
feature transversale. Pour un fix d'un fichier, fais l'Edit direct.

## Étape 0, Capture du scope

Reformule `$ARGUMENTS` en 1-2 lignes. Attends confirmation explicite.

## Étape 1, Écris le plan

Crée `PLAN_<slug>.md` à la racine avec cette structure :

```
# Plan, <titre>

## Scope
- Une phrase : ce qui sera livré.
- Hors scope : ce qu'on NE fait PAS.

## Fichiers à créer / modifier
- `chemin/du/fichier.ts`, créer / modifier, rôle

## Dépendances entre fichiers
1. A doit précéder B parce que…

## Risques connus
- Risque 1 + mitigation
- Risque 2 + mitigation

## Checkpoint utilisateur (✋)
- Décisions à valider avant code : [liste]
- Variantes : [si applicable]
```

## Étape 1.5, Plan review (invoque l'agent plan-reviewer)

Passe le plan à `plan-reviewer`. Affiche son verdict à l'utilisateur
(🟢 GO / 🟡 GO avec ajustements / 🔴 STOP).

**N'écris aucun code avant que l'utilisateur dise « go ».**

## Étape 2, Implémente, fichier par fichier, dans l'ordre des dépendances

Après chaque fichier, lance ton verify (typecheck + tests).
STOP au moindre rouge ; n'empile jamais les erreurs.

## Étape 3, Verify final

Si rouge, STOP et montre les erreurs. Ne lance pas les audits.

## Étape 4, Audits ciblés en parallèle

Selon ce qui a été touché, invoque 2-3 agents en parallèle
(qa-tester toujours, plus sécu/db/design selon le cas).

## Étape 5, Synthèse

Rapport unifié. Suggère /ship si pas de findings 🔴.

L'agent plan-reviewer

L'étape cruciale est la 1.5, une 2e instance Claude, en mode « staff engineer », relit le plan écrit par la 1ère. Crée .claude/agents/plan-reviewer.md :

---
name: plan-reviewer
description: Relit un PLAN_<slug>.md avec l'œil d'un staff engineer
  avant que l'implémentation commence. Use proactively à l'étape 1.5 de
  /new-feature. Détecte : scope flou, hors-scope manquant, risques oubliés,
  alternatives plus simples, checkpoints utilisateur absents. Produit
  un verdict structuré (🟢 GO / 🟡 GO avec ajustements / 🔴 STOP).
model: opus
tools: Read, Grep, Glob, Bash
---

Le system prompt de l'agent (version complète en Annexe D) lui demande de challenger le plan sur 7 axes : clarté du scope, alternative plus simple, complétude de la liste de fichiers, ordre des dépendances, risques connus, checkpoints utilisateur, boucle verify/feedback.

Ce que tu y gagnes

• Évite les refactos. Les mauvais plans sont rattrapés en 30 secondes, pas après une heure de code.
• Force à penser « hors scope ». Le template du plan rend impossible de sauter la déclaration de ce que tu ne fais pas. Le scope creep est coupé à l'étape planning.
• Une trace écrite. PLAN_<slug>.md reste dans le repo. Six mois plus tard, tu relis le plan et le verdict pour comprendre pourquoi le code a cette tête.

Chapitre 08 AVANCÉLa boucle d'audit

graph LR
    Commit[git commit fix:tz-bug] --> Hook[extract-lesson.sh
hook PostToolUse]
    Hook --> Check{Significatif ?
feat/fix/refactor
ou 3+ fichiers
ou zone sensible}
    Check -->|Non| Silent[Sortie silencieuse]
    Check -->|Oui| Nudge[Suggestion
sur stderr]
    Nudge --> You[Tu décides]
    You -->|/extract-lesson| Claude[Claude lit le diff,
extrait 1-3 leçons]
    You -->|skip| Skip[No-op]
    Claude --> Append[Ajoute à CLAUDE.md
§ Lessons learned]
    Append --> Win[Versionné dans Git ·
survit aux re-clones]
    style Win fill:#dcfce7,stroke:#15803d,stroke-width:2px
    style Hook fill:#fef3c7,stroke:#d97706
    

Chaque fois que Claude fait une erreur, ou prend une bonne décision non-évidente, c'est une opportunité de capturer une leçon. La boucle d'audit est la discipline qui consiste à transformer ce moment en une ligne versionnée dans ton repo pour que la même leçon soit chargée à la prochaine session, le mois prochain, et au prochain reclone.

Pourquoi les memories locales ne suffisent pas

Claude Code stocke les user memories dans ~/.claude/projects/<projet>/memory/. Elles survivent entre sessions sur la même machine, mais pas entre machines, pas entre collaborateurs, pas après un wipe. Tout ce que tu veux voir se composer dans le temps doit atterrir dans des fichiers versionnés Git.

Le workflow /extract-lesson

Deux pièces le branchent : un hook qui remarque un commit significatif, et une slash command qui extrait la leçon.

Le hook, extract-lesson.sh

Déclenché sur PostToolUse: Bash, le hook filtre sur les git commit et vérifie si le commit est « significatif » (match feat/fix/refactor, OU touche 3+ fichiers, OU touche une zone sensible comme src/auth/ ou les migrations). Si oui, il imprime un nudge d'une ligne sur stderr :

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  💡 Commit significatif détecté (a3b1f0), extraire une leçon ?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  fix(api): handle TZ shift on Date.toJSON()
  (type fix, 4 fichiers)

  Pour pérenniser :
    • /extract-lesson    → ajoute 1-3 leçons à CLAUDE.md
    • ou ignore si purement mécanique

Détail crucial : le hook compare le HEAD actuel à .claude/logs/last-extract-head. Si HEAD n'a pas bougé (parce que le commit a échoué un pre-commit hook), il reste silencieux. Les faux positifs tuent l'habitude plus vite que les faux négatifs.

La slash command, /extract-lesson

La commande lit le diff et le message du dernier commit (ou d'un SHA donné), puis décide s'il y a vraiment une leçon à pinner. La barre est haute, la plupart des commits n'ont pas besoin de leçon. Les critères, dans l'ordre :

1. Un piège non-évident que quelqu'un pourrait re-découvrir douloureusement (ex : « Date.toJSON() drop silencieusement le timezone offset »).
2. Une convention projet pas encore documentée nulle part.
3. Une décision d'architecture tranchée par ce commit/PR.
4. Un workaround pour une version spécifique d'une lib.

Si rien de tout ça ne s'applique, la commande le dit honnêtement et n'écrit rien. C'est la bonne réponse la plupart du temps.

La forme d'une bonne leçon

Trois lignes, pas plus. Constat / Pourquoi / Règle :

### [22.05.26]

- **`Date.toJSON()` drop silencieusement le timezone offset** (commit `a3b1f0`)
  - **Constat :** sérialiser un `Date` via `JSON.stringify` produit une
    string ISO en UTC sans l'offset d'origine.
  - **Pourquoi :** client et serveur échangent des dates en JSON ; si les
    deux font `new Date(json)` ils reconstruisent en heure locale, ce qui
    décale silencieusement l'heure affichée de l'offset UTC.
  - **Règle :** ne jamais round-trip un `Date` par JSON. Soit envoyer un
    timestamp Unix + offset explicite, soit utiliser une lib comme
    `date-fns-tz` aux deux bouts.

Six mois plus tard, un coéquipier tombe sur le même bug. CLAUDE.md est chargé à chaque session ; la leçon est là. Coût de capture total : 90 secondes. Coût de ne pas la capturer : chaque re-découverte future, multipliée par chaque développeur.

Où atterrissent les leçons

Append dans une section dédiée du CLAUDE.md de ton projet (ou src/CLAUDE.md si tu as déjà splitté) :

## 📚 Lessons learned

> Section maintenue par `/extract-lesson` après commits significatifs.
> Plus récent en haut, date entre crochets.

### [22.05.26]
- **`Date.toJSON()` drop silencieusement le timezone offset** (commit `a3b1f0`)
  - **Constat :** ...
  - **Pourquoi :** ...
  - **Règle :** ...

### [15.05.26]
- ...

Chapitre 09 INTERMÉDIAIREMode Coach

Mode Coach = un système qui te rappelle les bonnes pratiques au bon moment, sans que tu y penses. Trois couches complémentaires : règles dans CLAUDE.md, hook Stop qui observe, slash /coach manuel.

Pourquoi un Coach

Une fois ton setup en place, tu accumules des slash commands utiles (/ship, /audit-quick, /extract-lesson, etc.). Mais dans le feu de l'action, tu oublies de les utiliser. Tu finis par faire git commit + git push à la main, sans verify, et la CI crash.

Le Coach corrige ça en 3 couches.

Couche 1, Règles dans CLAUDE.md

Ajoute une section « Mode Coach » dans CLAUDE.md avec une table de déclencheurs. Relue à chaque session.

## Mode Coach, quand proposer quoi

Déclencheurs à honorer avant d'agir. Si une condition est vraie,
propose la commande/agent plutôt que foncer.

| Déclencheur observé | Action à proposer |
|---|---|
| Tâche touche ≥ 3 fichiers OU feature transversale | `/new-feature <slug>` |
| Modif d'un composant UI | agent design-review avant ship |
| Modif d'un calcul critique | agent domain-expert après la modif |
| Migration SQL | agent `db-schema-reviewer` avant push |
| Server action / route auth modifiée | agent `security-auditor` avant push |
| ≥ 10 fichiers modifiés depuis le dernier commit | `/audit-quick` avant ship |
| Avant tout `git push` | `/ship "<message>"` |

**Règle générale** : si une commande couvre ~80 % de ce qui allait être
fait à la main, propose avant. L'utilisateur peut toujours dire « non,
fais à la main », c'est OK.

Couche 2, Hook Stop qui observe

Le hook Stop se déclenche à la fin du tour de Claude. Il lit l'activity log de la session courante, détecte ce qui a été touché, et imprime des suggestions ciblées dans ton terminal, à zéro token.

Pré-requis : avoir un hook PostToolUse qui log Write/Edit/Bash dans .claude/logs/activity.log. Puis crée .claude/hooks/coach-suggest.sh (cf. version EN, identique sauf strings).

Couche 3, Slash /coach manuel

Pour les moments où tu hésites toi-même. Crée .claude/commands/coach.md :

---
description: "Analyser l'état du repo et recommander la prochaine action"
---

# /coach

Lance en parallèle :
- `git status --short`, `git diff --stat`, `git log --oneline -5`
- Lis `.claude/logs/activity.log | tail -50` si présent

Compare l'état aux déclencheurs Coach du CLAUDE.md. Recommande max 3
actions priorisées :

  1. <commande> → <raison en une phrase>
  2. <commande> → <raison>
  3. <commande> → <raison>

Termine par : « On lance #1 ou tu préfères réfléchir d'abord ? »

Le mécanisme mute

Parfois tu sais ce que tu fais et les suggestions deviennent du bruit. Le hook check un flag .claude/coach-mute et sort silencieusement s'il existe. Deux commandes pour toggler :

• /coach-mute → touch .claude/coach-mute (Coach OFF)
• /coach-on → rm -f .claude/coach-mute (Coach ON)

Chapitre 10 AVANCÉWorktrees parallèles

Boris Cherny lance cinq sessions Claude Code en parallèle, une par git worktree. Pour un dev solo ou une petite équipe, deux à trois est le plafond réaliste, mais le pattern est le même : multiplie ton débit en donnant à chaque tâche indépendante son propre checkout.

Quand ça paye

• Tu veux écrire une feature pendant que la review d'une PR de collègue est ouverte dans un autre onglet.
• Tu fais un gros refacto et tu veux continuer à shipper des petits fixes depuis le checkout principal.
• Tu polish une page publique pendant qu'un chantier backend est en cours.

Quand ça ne paye pas

• Deux chantiers qui touchent les mêmes fichiers, les merges seront cauchemardesques.
• Tu débutes sur Claude Code, une session à la fois reste plus sûr jusqu'à ce que tu aies la mémoire musculaire.
• RAM limitée, trois dev servers concurrents + trois sessions Claude dépassent facilement 6 Go.

Setup

# Depuis ton repo principal sur main/master
mkdir -p ../mon-projet-worktrees
git worktree add ../mon-projet-worktrees/marketing -b chantier/marketing-launch
cd ../mon-projet-worktrees/marketing
npm install   # node_modules par worktree, pas de partage

# Conventions
# - Branch : chantier/<slug>  (pas feature/*, ça dérive)
# - Dossier : ../mon-projet-worktrees/<slug>
# - Durée   : idéalement < 7 jours, sinon merge ou kill

# Merger vers main
pnpm verify          # vert avant merge
git push -u origin chantier/marketing-launch
cd ../../mon-projet-main
git checkout main
git merge --no-ff chantier/marketing-launch
git push origin main

# Nettoyage
git worktree remove ../mon-projet-worktrees/marketing
git branch -d chantier/marketing-launch

Gotchas spécifiques aux worktrees Claude Code

• .env.local n'est pas tracked, donc absent du nouveau worktree. Copie-le manuellement après git worktree add.
• settings.local.json est gitignored aussi, même problème.
• Conflits de ports dev server, si ton défaut est 3000, lance le 2e worktree avec PORT=3001 npm run dev.
• Les hooks tournent par worktree, c'est une feature : chaque worktree a son propre .claude/logs/last-extract-head, donc la boucle d'audit marche bien en parallèle.

Chapitre 11 AVANCÉLa matrice mémoire

graph TB
    Q[Nouvelle info à retenir] --> Q1{≥ 2 agents
en bénéficieraient ?}
    Q1 -->|Oui| L1[CLAUDE.md
§ Lessons learned
versionné · transversal]
    Q1 -->|Non| Q2{Est-ce un domaine
ex SQL, dates, commits ?}
    Q2 -->|Oui| L2[.agents/skills/domain/
versionné · règles structurées]
    Q2 -->|Non| Q3{Un seul agent ·
« ne re-flagge pas » ?}
    Q3 -->|Oui| L3[.claude/agent-memory/agent/
versionné · agent-scoped]
    Q3 -->|Non| L4[~/.claude/projects/.../memory/
LOCAL UNIQUEMENT · sera perdu]
    style L1 fill:#dcfce7,stroke:#15803d,stroke-width:2px
    style L2 fill:#dbeafe,stroke:#1d4ed8,stroke-width:2px
    style L3 fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style L4 fill:#fee2e2,stroke:#b91c1c,stroke-width:2px
    

Les quatre lieux

Règles de décision

1. ≥ 2 agents bénéficieraient de cette info → CLAUDE.md § Lessons learned.
2. 1 agent, et le sujet est un domaine (Postgres, React, dates, commits) → skill sous .agents/skills/.
3. 1 agent, et l'info est purement « ne re-flagge pas » → .claude/agent-memory/<agent>/.
4. Aucun des trois ci-dessus (purement ma préférence, cette machine) → ~/.claude/projects/.

Exemples concrets

Exemple 1. Tu as décidé d'utiliser date-fns plutôt que moment.js sur tout le projet. Plusieurs futurs commits y feront référence. Plusieurs agents (code-auditor, qa-tester) doivent le savoir. → CLAUDE.md § Lessons learned, avec le SHA du commit.

Exemple 2. Ton code-auditor flagge sans cesse les any dans les formatters Recharts, alors que c'est une convention projet documentée. → .claude/agent-memory/code-auditor/feedback_recharts_any_ok.md. L'agent charge sa mémoire et arrête de re-flagger.

Exemple 3. Tu veux un catalogue versionné de règles de versioning d'API REST avec exemples. → .agents/skills/api-versioning/ avec une règle par fichier sous references/.

Exemple 4. Tu préfères des réponses concises de Claude. C'est une préférence perso, cette machine uniquement. → ~/.claude/projects/<projet>/memory/user_communication.md.

Anti-patterns

Chapitre 12 AVANCÉMCP, Connecter à l'extérieur

Le Model Context Protocol donne à Claude accès à des outils externes (DB, navigateur, filesystem, APIs). Configuration dans .mcp.json à la racine :

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest", "--browser=chromium", "--isolated"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
    },
    "tavily": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/",
      "headers": { "X-API-Key": "${TAVILY_API_KEY}" }
    }
  }
}

Quels MCPs installer en premier

Le lock pattern read-only (nouveau en V2)

Pour tout MCP qui touche un système où des mutations sont possibles (DB, repo GitHub, filesystem), épingle la config en read-only via deux couches :

1. Dans .mcp.json (committé), passe le flag read-only au serveur MCP lui-même.
2. Dans .claude/settings.local.json (gitignored, local), restreins la liste des outils MCP aux opérations read-only.

Deux couches redondantes, si quelqu'un édite l'une, l'autre tient. Une seule couche échoue silencieusement. Exemple pour un MCP Postgres :

// .mcp.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://readonly_user:***@host:5432/db",
               "--read-only"]
    }
  }
}

// .claude/settings.local.json (gitignored)
{
  "permissions": {
    "allow": [
      "mcp__postgres__query",
      "mcp__postgres__list_tables",
      "mcp__postgres__describe_table"
    ],
    "deny": [
      "mcp__postgres__execute"
    ]
  }
}

Pour le DDL ou les mutations, Claude rédige du SQL ; tu le colles dans ton vrai SQL editor. Lent par design. Le genre de lenteur qui prévient les accidents.

Chapitre 13 AVANCÉMaintenance long-terme

Ton setup est vivant. CLAUDE.md vieillit, les agents s'endorment, de nouveaux MCPs apparaissent. Voici la maintenance qui le garde sain.

Mémoire persistante des agents

Par défaut, un sub-agent oublie tout entre invocations. Pour les agents critiques, tu peux activer une mémoire trans-sessions versionnée dans Git :

1. Crée le dossier mémoire selon le scope souhaité (cf. table ci-dessous).
2. Ajoute memory: project (ou user, ou local) au frontmatter de l'agent.
3. Claude Code injecte les instructions de read/write et active les outils Read/Write/Edit pour l'agent.

Splitter CLAUDE.md quand il grossit

Quand CLAUDE.md dépasse ~100 lignes, splitte en fichiers thématiques importés via @ :

@AGENTS.md
@.claude/STACK.md
@.claude/CONVENTIONS.md
@.claude/WORKFLOW.md

# <Projet>, hub de configuration

| Tu cherches… | Va dans |
|---|---|
| Commandes + stack + gotchas | `@.claude/STACK.md` |
| Conventions, règles dev, workflow Git | `@.claude/CONVENTIONS.md` |
| Agents, slash commands, mode Coach | `@.claude/WORKFLOW.md` |

CLAUDE.md devient un hub qui pointe ; les fichiers thématiques restent < 80 lignes chacun, lisibles d'un coup d'œil.

Partager le setup en équipe

Tout .claude/ versionné dans Git = chaque membre de l'équipe hérite automatiquement. Pour aller plus loin, packager en plugin (.claude-plugin/<nom>/ avec plugin.json, un template CLAUDE.md, des hooks, agents, skills). Un plugin se partage comme une dépendance. Utile quand plusieurs projets internes partagent la même base.

La checklist /audit-claude-setup (étendue en V2)

Tous les ~30 jours, ou avant une release, lance /audit-claude-setup. La slash command complète vit en Annexe E ; voici la checklist qu'elle implémente :

1. Inventaire. Compte agents, slash commands, hooks, skills, mémoires actives, serveurs MCP. Compare à ton index COMMANDS.md, quelque chose non documenté ?
2. Agents dormants. Un agent qui n'apparaît jamais dans ton activity log est soit redondant, soit avec une description mal calibrée. Décide.
3. Références cassées. Pour chaque fichier mentionné dans CLAUDE.md, vérifie qu'il existe.
4. Permissions inutilisées. Une entrée Bash(*) jamais invoquée est du bruit, restreins-la.
5. Mémoires agent vides. Un agent memory: project dont le MEMORY.md est vide depuis 30+ jours ne capitalise rien. Sous-utilisé ou critères mal calibrés.
6. Hooks lents. Un hook qui prend > 500 ms ralentit chaque session. Profile, fix, ou passe en async.
7. Modèles désalignés. opus pour des agents triviaux gaspille des tokens ; haiku pour des complexes donne de mauvais résultats.
8. Skills orphelines. Une skill qu'aucun agent ne référence est du poids mort. Branche-la ou supprime-la. (nouveau en V2)
9. Duplication skill ↔ prompt d'agent. Si > 50 % du contenu d'une skill est aussi dans le prompt d'un agent, consolide. La skill gagne. (nouveau en V2)

Annexe ACLAUDE.md universel

# <Nom du projet>

Description en une phrase.

## Stack
- Langage / Framework / DB / Tests / Déploiement

## Commandes utiles
- `<dev>`, `<verify>`, `<test>`, `<build>`

## Conventions
- Nommage, structure, comportement

## Gotchas
- Pièges stack et projet connus

## Workflow Git
- Branche, format de commit, PR / push direct

## Règles impératives
- **Jamais** X sans confirmation
- **Toujours** Y avant Z

## Mode Coach (cf. Chapitre 09)
| Déclencheur | Action |
|---|---|
| ≥ 3 fichiers touchés OU module critique | /new-feature <slug> |
| Commit significatif (feat/fix/refactor) | /extract-lesson |
| Avant tout push | /ship "<message>" |

## Lessons learned (cf. Chapitre 08)

> Section maintenue par /extract-lesson. Plus récent en haut.

Annexe B.claude/settings.json complet

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read", "Grep", "Glob",
      "Bash(git status:*)", "Bash(git diff:*)", "Bash(git log:*)",
      "Bash(git show:*)", "Bash(git branch:*)", "Bash(git fetch:*)",
      "Bash(ls:*)", "Bash(cat:*)", "Bash(find:*)",
      "Bash(head:*)", "Bash(tail:*)", "Bash(wc:*)"
    ],
    "deny": [
      "Bash(rm -rf*)", "Bash(rm)", "Bash(sudo*)",
      "Bash(curl* | bash*)"
    ]
  },
  "hooks": {
    "SessionStart": [
      { "matcher": "*", "hooks": [
        { "type": "command", "command": ".claude/hooks/session-start.sh" }
      ]}
    ],
    "PreToolUse": [
      { "matcher": "Edit|Write|Bash", "hooks": [
        { "type": "command", "command": ".claude/hooks/pre-tool-guard.sh" }
      ]}
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [
        { "type": "command", "command": ".claude/hooks/post-edit-format.sh" },
        { "type": "command", "command": ".claude/hooks/activity-log.sh", "async": true }
      ]},
      { "matcher": "Bash", "hooks": [
        { "type": "command", "command": ".claude/hooks/activity-log.sh", "async": true },
        { "type": "command", "command": ".claude/hooks/extract-lesson.sh" }
      ]}
    ],
    "Stop": [
      { "matcher": "*", "hooks": [
        { "type": "command", "command": ".claude/hooks/coach-suggest.sh" }
      ]}
    ]
  }
}

Annexe CLes six hooks (condensés)

Annexe DQuatre templates d'agents

System prompts complets dans templates/.claude/agents/ sur GitHub.

Annexe ESix slash commands

Annexe FGlossaire

Agent (sub-agent)

Un prompt spécialisé + ensemble d'outils + choix de modèle, défini dans .claude/agents/<nom>.md, à qui Claude peut déléguer une tâche. Tourne dans son propre contexte.

$ARGUMENTS

Placeholder pour les arguments passés à une slash command. Exemple : /ship "fix: typo" met $ARGUMENTS à "fix: typo".

Mode Coach

Système à trois couches (règles dans CLAUDE.md, hook Stop avec suggestions, /coach manuel) qui te nudge vers la bonne commande/agent au bon moment.

Frontmatter

Bloc YAML en tête d'un fichier markdown (entre deux lignes ---) qui contient les métadonnées. Utilisé dans les agents, slash commands, et références de skills.

Hook

Script shell que Claude Code lance à l'un des quatre événements (SessionStart, PreToolUse, PostToolUse, Stop) sans impliquer le LLM. Coût en tokens quasi-nul.

Least privilege (moindre privilège)

Pattern qui consiste à ne donner à chaque agent que les outils dont il a besoin (Read-only pour un auditeur, Read+Write pour un générateur). Réduit la surface d'attaque et les erreurs.

MCP

Model Context Protocol, le standard ouvert pour connecter Claude à des outils externes (DB, GitHub, navigateurs). Configuré via .mcp.json.

Matrice mémoire

La règle de décision pour savoir où stocker une info donnée : CLAUDE.md, une skill, une mémoire d'agent, ou la mémoire utilisateur locale. Cf. Chapitre 11.

Page-break-inside: avoid

Règle CSS qui dit au renderer d'impression ou d'EPUB de garder un bloc sur une seule page plutôt que de le couper. Critique pour les blocs de code et les tables.

Permission denylist

Section permissions.deny de settings.json qui bloque des commandes précises (ex : sudo, rm -rf /) quel que soit le match avec l'allowlist.

Plan-first development

Pattern de workflow où l'utilisateur écrit un document PLAN_<slug>.md avant que la moindre ligne de code soit touchée. Relu par une 2e instance Claude (plan-reviewer) avant que l'implémentation démarre. Cf. Chapitre 07.

Skill

Dossier versionné de connaissances métier sous .agents/skills/<nom>/ avec un point d'entrée SKILL.md et des fichiers de règles dans references/. Chargée à la demande. Cf. Chapitre 06.

Slash command

Template de prompt réutilisable défini dans .claude/commands/<nom>.md, invoqué en tapant /nom dans Claude Code.

Worktree

Un 2e répertoire de travail pour le même repo git, sur une branche différente. Te laisse lancer plusieurs sessions Claude Code en parallèle. Cf. Chapitre 10.

Annexe GQuick start 30 minutes

Après ça, les 30 minutes suivantes te donnent les sub-agents (Chapitre 05). L'heure d'après te donne les slash commands (Chapitre 04). N'essaie pas de tout faire d'un coup.

Annexe HDeux études de cas

Deux histoires anonymisées, un dev, une knowledge worker, qui appliquent le setup. Pas de nom de produit, pas de spécificités de domaine. Les enseignements se généralisent.

Cas 1, Dev SaaS solo (6 mois)

Environ 30 k LOC de TypeScript, déploiements quotidiens, ~40 commits par semaine. Stack web moderne avec une DB transactionnelle et un dashboard analytique. Dev solo avec un an d'expérience de code.

« Je passais 15 à 20 minutes par session à ré-expliquer le contexte. Huit builds CI cassés en deux semaines à cause d'un any implicite. Aucune trace écrite des décisions d'archi, toutes les deux semaines je re-débattais d'un truc que j'avais déjà tranché. »

Ce qui a été configuré

• Un hub CLAUDE.md + trois imports thématiques (STACK.md, CONVENTIONS.md, WORKFLOW.md)
• 17 sub-agents (10 techniques, 5 marketing, 2 méta)
• 6 hooks (les 5 standards du livre + le hook extract-lesson)
• 14 slash commands dont /new-feature avec plan-reviewer à l'étape 1.5
• 5 skills, une par domaine technique (SQL best practices, gestion des dates, conventions de commits, etc.)

Résultats à 6 mois

Ce qui a marché

• Plan-first via /new-feature. Zéro refacto majeur en 6 mois, rattrapé au planning, pas après le code.
• Skills > inline prompts. Dérive éliminée après le 1er audit mensuel qui a révélé deux skills dupliquées dans des prompts d'agents.
• La matrice mémoire. Plus de doute sur « où écrire ça ».

Ce qui n'a PAS marché

• 4 sub-agents jamais invoqués. Soit redondants, soit avec une description mal calibrée. 2 fusionnés, 2 supprimés.
• Worktrees parallèles abandonnés après un essai, le laptop n'avait pas la RAM pour 3 dev servers concurrents.
• Un hook TDD-guard parfois trop strict sur les fichiers UI cosmétiques. Mitigation : une entrée ciblée dans agent-memory.

Citation de clôture

« Le setup ne te rend pas plus rapide, il te rend reproductible. C'est l'opposé du glamour, mais c'est ce qui m'a permis de tenir 6 mois sans abandonner. »

Cas 2, Knowledge worker / chercheuse indépendante (3 mois)

Une rédactrice technique freelance et analyste de recherche qui utilise Claude Code comme outil quotidien d'écriture et d'analyse. Pas de code en production, mais usage intensif de longs documents, vérification de faces, prise de notes structurée. Travaille sur deux repos, un pour les livrables client, un pour une base de connaissances perso.

« J'utilisais Claude dans un onglet de navigateur depuis un an. Chaque conversation commençait par coller mon style guide, mes sources, le contexte de mon projet. Je perdais deux heures par semaine rien que sur ce rituel. J'ai essayé Claude Code sur recommandation d'un ami ; avec le setup de ce manuel, le rituel a disparu. »

Ce qui a été configuré

• Un CLAUDE.md à la racine du repo de base de connaissances avec : style guide, sources récurrentes (et format de citation), règles de ton de voix, expressions à proscrire
• 3 sub-agents : fact-checker (vérifie les affirmations contre les sources avant rédaction), tone-reviewer (flagge la dérive du style guide), structure-reviewer (vérifie hiérarchie des titres et distribution de longueurs)
• 4 hooks : session-start.sh montre les « 3 derniers documents touchés », pre-tool-guard.sh bloque les écritures hors de drafts/ et published/, post-edit-format.sh lance prettier sur le markdown, extract-lesson.sh nudge pour capturer les décisions éditoriales
• 3 slash commands : /draft <sujet> (recherche + outline), /polish (les 3 reviewers en parallèle), /cite <url> (fetch + format)
• 1 skill : citation-styles avec règles pour formats académique, journalistique et blog, élimine la ré-explication à chaque essai

Résultats à 3 mois

Citation de clôture

« Je ne suis pas développeuse, et la plupart du contenu sur Claude Code suppose que tu l'es. Ce manuel a expliqué le même setup d'une manière qui colle à mon workflow. Les patterns, planifier avant, capturer les leçons après, une skill par domaine, se traduisent un pour un en écriture. »

Ce que les deux cas partagent

Même résultat, domaines différents : le rituel a disparu, les standards ont tenu, le travail s'est composé. C'est toute la promesse du setup.

Annexe ICheat sheet

Un foldout deux pages. Imprime en A3 (une face par page) ou garde numérique. Tout ce dont tu as besoin sans ouvrir le livre.

Hooks · les 6

Slash commands · les 8

Templates d'agents · les 4

Mémoire · où écrire quoi

La règle de décision, en une phrase

Slash command si c'est un verbe. Sub-agent si c'est un nom avec un boulot. Skill si c'est un corpus de règles. Hook si c'est un réflexe.

Les règles d'or

1. pnpm verify (ou équivalent) doit être vert avant chaque push. Husky pre-push si tu es du genre à oublier.
2. Plan-first quand le chantier touche ≥ 3 fichiers OU un module critique OU une migration DB.
3. Après un commit significatif, décide : capture une leçon, ou laisse le hook silencieux.
4. Chaque info vit dans exactement UN des quatre lieux mémoire. Pas de doublon.
5. Skill > prompt d'agent. Si une règle vit dans les deux, l'agent perd ; la skill gagne.
6. Lance /audit-claude-setup une fois par mois. Skills orphelines, agents dormants, refs cassées.