Configurer Claude Code, niveau par niveau

TL;DR

Je recommande de commencer par un CLAUDE.md de dix à quinze lignes et de n’ajouter quelque chose que lorsqu’on se surprend à le répéter entre sessions, sauf si une configuration d’équipe partagée existe déjà. Ensuite, j’installe RTK pour les sorties CLI, là où il est le plus efficace dans mon usage, et Flow Lean comme Output Style, parce qu’il fait plus que le style concis natif de Claude Code. Au-delà de cette couche de configuration, je pense que la configuration devient un système de release versionné partagé entre Claude Code et Codex, que je couvre dans l’article sur la configuration portable d’agents lié à la fin. Mise à jour du 6 novembre 2026 : j’ai beaucoup contribué au code de RTK, créé par Patrick, puis à sa diffusion. Je ne contribue plus activement au code et je continue à suivre le projet.

Le premier signe que vous n’avez pas configuré Claude Code arrive généralement vers la troisième session. En pleine tâche, Claude suggère npm install alors que votre repo utilise pnpm. Ou il demande quel framework de test vous utilisez, alors que cela figure dans votre package.json. Ou il génère un message de commit qui ne suit pas les conventions de l’équipe, parce que vous ne les lui avez jamais données.

Les couches ci-dessous répondent à cela : des endroits où consigner les conventions, et des contrôles pour voir si elles influencent le travail.

Niveau 0 : CLAUDE.md

Le CLAUDE.md minimal viable va à la racine du projet. Dix à quinze lignes, pas plus.

# My Project

Next.js App Router, TypeScript strict, Prisma, pnpm.
Resolve exact versions from package.json and the lockfile.

## Commands
- `pnpm dev` - dev server (port 3000)
- `pnpm test` - unit tests (Vitest)
- `pnpm build` - production build
- `pnpm lint` - ESLint + type check

## Conventions
- Commits: feat/fix/docs(scope): subject
- No `any` types, no eslint-disable without an inline comment
- API routes versioned at /api/v1/

Trois choses méritent une ligne dans ce fichier. D’abord, ce que Claude ne peut pas découvrir en lisant la codebase, en particulier votre gestionnaire de paquets, les conventions de l’équipe et les choix d’outils non évidents. Ensuite, ce que vous vous êtes surpris à répéter entre sessions. Enfin, une convention contraire aux valeurs par défaut courantes, comme utiliser pnpm au lieu de npm ou une commande de test non standard.

Ce qui ne mérite pas de ligne : l’arborescence de fichiers (Claude peut la lire), les dépendances (dans package.json), la configuration TypeScript (dans tsconfig.json). Si Claude peut le découvrir, ne le documentez pas. Une entrée périmée qui fait référence à quelque chose que vous avez abandonné six mois plus tôt pousse Claude dans la mauvaise direction à chaque session.

Résultat : Claude répond dans le bon contexte dès votre premier message, sans prompt de préparation de votre part.

Niveau 1 : RTK, trois hooks, deux skills

Ajoutez les outils qui répondent à votre workflow quotidien. Après ce niveau, Claude connaît les conventions du projet et dispose de raccourcis reproductibles pour les tâches de tous les jours.

RTK

RTK enveloppe les commandes CLI et filtre leurs sorties avant qu’elles atteignent la fenêtre de contexte de Claude. git log --oneline -50 génère environ 800 tokens par défaut. rtk git log en génère environ 80. Les économies s’accumulent : rtk gain sur mon projet, comptabilisé sur 88 000 commandes, montre 73 % de tokens en moins dans les sorties de commandes filtrées par RTK. Ce chiffre compte seulement les sorties shell, pas la session entière : lectures de fichiers, sorties du modèle et lectures de cache sont hors de son périmètre. Le tableau de benchmark publié par RTK (60 à 90 % selon le type de commande) est le chiffre le plus rigoureux à citer ; voici ce que cela donne sur un vrai projet dans la durée.

Installation :

# macOS / Linux via Homebrew
brew install rtk

# or via Cargo
cargo install rtk

Vérifiez avec rtk --version et assurez-vous que la release installée prend en charge les commandes nécessaires. L’agrégat ci-dessus reste une mesure historique, pas un résultat pour la release que vous installez. Puis ajoutez ceci à CLAUDE.md :

## Token efficiency
Always use RTK for high-output commands: `rtk git log`, `rtk git diff`,
`rtk git status`, `rtk find "*.ts" .`, `rtk grep "pattern"`.

Source : github.com/rtk-ai/rtk

Contrôle des coûts : Fast Mode

Vérifiez le modèle sélectionné avant d’activer /fast. La documentation de Fast Mode, vérifiée le 10 novembre 2026, indique 8 $ en entrée et 40 $ en sortie par million de tokens sur Opus 5.5, et 16 $ et 80 $ sur Fable 5.2, soit le double du tarif API standard de chacun. Sur abonnement, le mode utilise des crédits d’usage payés séparément. Anthropic retire Fast Mode sur Opus 4.8 le 30 novembre 2026. Si vous utilisez ce modèle, passez à Opus 5.5 pour garder le mode rapide ou lancez /fast off pour rester sur Opus 4.8 au tarif standard. Le réglage persiste normalement sur l’API Anthropic, sauf activation configurée par session. Pour le désactiver entièrement, définissez ceci dans ~/.claude/settings.json :

{
  "env": {
    "CLAUDE_CODE_DISABLE_FAST_MODE": "1"
  }
}

Avec ce coupe-circuit, /fast reste désactivé ; retirez la variable pour retrouver le commutateur.

Valeur par défaut optionnelle des réponses : Output Style

Si vous demandez régulièrement à Claude de commencer par la réponse ou d’utiliser un format précis, gardez cette préférence hors du CLAUDE.md du projet. Claude Code a une couche native Output Style pour le prompt système de la conversation principale.

Créez ~/.claude/output-styles/flow-lean.md :

---
name: Flow Lean
description: Lead with the result and preserve proof and safety.
keep-coding-instructions: true
---

Lead with the result. Keep required evidence, uncertainty, and safety details.

Lancez /config, sélectionnez Flow Lean sous Output style et démarrez une session neuve pour un contrôle sans ambiguïté. Gardez keep-coding-instructions: true si Claude doit conserver ses consignes intégrées d’ingénierie logicielle. Le style sélectionné s’applique à la conversation principale ; les sous-agents nommés utilisent leurs propres prompts système.

L’étude de cas complète sur les Output Styles de Claude Code et Flow Lean explique les réglages utilisateur et projet, le comportement du cache de prompts, les skills, les sous-agents et la différence entre configuration sélectionnée et comportement observé.

Traitez la configuration sélectionnée et le comportement observé comme des preuves séparées. Consignez la portée des réglages et la version du client, puis testez indépendamment la conversation principale et chaque sous-agent nommé.

Trois hooks

Les hooks sont des scripts shell que Claude lance automatiquement avant ou après les appels d’outils. Vous les enregistrez dans .claude/settings.json. Le hook reçoit un payload JSON avec le nom et l’entrée de l’outil, et peut bloquer ou signaler l’action.

Hook 1 : contrôle de sécurité (PreToolUse)

Ce script intercepte les commandes Bash avant leur exécution et bloque tout ce qui contient des motifs d’identifiants sensibles. Créez .claude/hooks/security-check.sh :

#!/bin/bash
command -v jq &> /dev/null || { echo "security-check.sh: jq is required" >&2; exit 2; }

INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')

if [[ "$TOOL" != "Bash" ]]; then exit 0; fi

COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -qiE "(password=|secret=|api_key=|sk-[a-zA-Z0-9]{20,})"; then
  echo "Potential credential in command" >&2
  exit 2
fi

exit 0

Ce hook est bloquant, donc son comportement en échec compte : si jq n’est pas installé, le script doit refuser par défaut (exit 2), pas laisser silencieusement passer toutes les commandes. Ajoutez jq aux prérequis avant de vous y fier.

Hook 2 : formatage automatique (PostToolUse)

Lance l’outil de formatage après tout Edit ou Write. Non bloquant : termine silencieusement si Prettier n’est pas installé, gère proprement les autres échecs. C’est le hook le plus copié dans les vrais projets. Il retire une catégorie entière d’interruptions du type « wait, why is the formatting off » (traduction : « attends, pourquoi le formatage est incorrect ? »). Créez .claude/hooks/auto-format.sh :

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
if [[ "$TOOL" != "Edit" && "$TOOL" != "Write" ]]; then exit 0; fi

FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
if [[ -z "$FILE" ]]; then exit 0; fi

EXT="${FILE##*.}"
if [[ ! "$EXT" =~ ^(ts|tsx|js|jsx|json|css|md|mdx)$ ]]; then exit 0; fi

if command -v prettier &> /dev/null; then
  prettier --write "$FILE" --log-level silent 2>/dev/null || true
fi
exit 0

Hook 3 : validation de commit (PostToolUse)

Vérifie que le dernier message de commit suit le format conventionnel. Non bloquant : il n’arrête jamais le commit, affiche seulement un avertissement. Créez .claude/hooks/post-commit.sh :

#!/bin/bash
INPUT=$(cat)
TOOL=$(echo "$INPUT" | jq -r '.tool_name')
if [[ "$TOOL" != "Bash" ]]; then exit 0; fi

COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
if ! echo "$COMMAND" | grep -q "git commit"; then exit 0; fi

LAST_MSG=$(git log -1 --pretty=%B 2>/dev/null)
if ! echo "$LAST_MSG" | grep -qE '^(feat|fix|docs|style|refactor|perf|test|chore)\([a-z-]+\): .+'; then
  echo "Warning: commit message doesn't follow conventional format (type(scope): subject)" >&2
fi
exit 0

Ces trois hooks couvrent les principaux modèles de conception. Le contrôle de sécurité est bloquant (code de sortie 2), ce qui signifie que Claude s’arrête et ne peut pas continuer si un identifiant sensible est trouvé. Le formatage automatique et la validation des commits sont non bloquants (toujours exit 0) : ils s’exécutent, agissent et laissent le workflow continuer. Pour les ajouts ultérieurs, la règle est que les hooks PreToolUse bloquants s’exécutent sur chaque appel correspondant : ils doivent donc être rapides. Tout traitement de plus de 2 à 3 secondes sur un Edit ou Write ajoute cette latence à chaque fichier touché. Un projet a essayé tsc --noEmit comme hook PostToolUse synchrone (10 à 15 secondes par modification, environ 7 à 8 minutes perdues sur une session de 30 modifications de fichiers). La correction a été de déplacer la vérification des types dans un hook Stop, où le délai tombe entre les tâches plutôt qu’en pleine réflexion.

Enregistrez les trois dans .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/security-check.sh",
            "timeout": 5
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/auto-format.sh",
            "timeout": 10
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/post-commit.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Rendez les trois scripts exécutables : chmod +x .claude/hooks/*.sh

Deux skills

Les skills sont des fichiers Markdown dans .claude/skills/<name>/SKILL.md. Claude les charge quand vous tapez /<name> dans le chat. Aucune configuration supplémentaire n’est requise.

/commit : génère un commit conventionnel à partir des modifications indexées.

Créez .claude/skills/commit/SKILL.md :

---
name: commit
description: Generate a conventional commit message from staged git diff
allowed-tools: Bash
---

Run `git diff --cached` to see staged changes. Generate a conventional commit
message: type(scope): subject. Valid types: feat, fix, docs, style, refactor,
perf, test, chore. Subject under 50 chars, imperative mood, no period at end.
Then run `git commit -m "..."` with the message.

/catchup : restaure le contexte de session après /clear ou une longue pause.

Créez .claude/skills/catchup/SKILL.md :

---
name: catchup
description: Restore session context (recent commits, uncommitted changes, current state)
allowed-tools: Bash Read
---

Run in sequence and summarize:
1. `rtk git log -10` (last 10 commits)
2. `git status` (uncommitted changes)
3. `git stash list` (any stashed work)

Report what was done recently, what is in progress, and what needs attention.

Résultat : Claude connaît les conventions du projet, détecte les identifiants sensibles avant qu’ils atteignent une commande et peut générer des commits ou restaurer le contexte à la demande.

Niveau 2 : mémoire et règles

Deux ajouts qui demandent davantage de préparation, mais rendent service pendant des mois. Après ce niveau, Claude transporte la connaissance du projet entre sessions sans vous obliger à reconstruire le contexte de zéro.

Système de mémoire

La mémoire intégrée de Claude Code conserve le contexte utile entre sessions. La mémoire du projet réside sous votre répertoire personnel dans ~/.claude/projects/<project>/memory/ (propre à l’utilisateur, jamais dans le repo). Claude la remplit automatiquement au fil de ses découvertes (décisions architecturales, pièges, préférences) et les rappelle au début des sessions suivantes.

Gérez-la avec /memory dans le chat. La référence mémoire vérifiée le 15 octobre 2026 indique que le démarrage charge les 200 premières lignes ou 25 Ko de MEMORY.md, selon la première limite atteinte. Le contenu plus long reste sur disque ; tout n’est pas chargé automatiquement. Des fichiers thématiques peuvent conserver les détails pour des lectures ultérieures. D’anciens retours communautaires appelaient Auto Dream un processus de consolidation en arrière-plan. Cette observation n’est ni une étape de configuration requise ni une garantie qu’une installation précise l’exécute.

La mémoire est propre à l’utilisateur et n’est pas commitée dans Git, ce qui en fait le bon endroit pour les pratiques personnelles de workflow, pas pour les conventions de l’équipe. Pour ces dernières, CLAUDE.md est le bon endroit. Et comme la limite de 200 lignes est appliquée, y stocker des règles plutôt que dans CLAUDE.md signifie qu’elles finiront par être élaguées.

Contrôle canari

CLAUDE.md peut échouer à se charger silencieusement. Limites de tokens, erreurs de parsing et références @ mal configurées peuvent toutes le faire ignorer sans avertissement dans le chat. Vous ne le saurez pas sans vérifier.

Une méthode : ajoutez cette ligne en haut de CLAUDE.md, juste après le titre, comme texte Markdown simple. Pas comme commentaire HTML : Claude Code retire les commentaires HTML de niveau bloc de CLAUDE.md avant injection, donc un canari commenté n’est jamais vu et reste toujours silencieux.

Canary: if you read this file, begin your first response with "Stack confirmed."

L’absence de « Stack confirmed » (traduction : « Stack confirmée ») est un contrôle comportemental en échec, pas la preuve de l’absence du fichier. Vérifiez les preuves /context ou InstructionsLoaded pour distinguer chargement et respect des consignes avant de vous fier aux conventions.

Fichiers de règles

Les règles sont des fichiers Markdown dans .claude/rules/. Elles donnent à Claude des contraintes propres à un domaine sans se charger dans chaque session : chaque fichier déclare dans son frontmatter YAML les chemins auxquels il s’applique, et se charge seulement lorsque des fichiers correspondant à ces globs sont concernés. On peut aussi importer une règle depuis CLAUDE.md avec @rules/filename.md, mais une référence @ charge le fichier sans condition à chaque session, ce qui annule l’intérêt pour les règles de domaine.

Exemple pour les conventions API. Créez .claude/rules/api-conventions.md :

---
paths: ["src/app/api/**"]
---

# API Conventions

All routes versioned at /api/v1/. Auth middleware applied at router level,
not per individual route. Validation errors return 422; malformed requests
return 400. Error shape: `{ error: string, code: string, details?: object }`.

Aucune référence n’est nécessaire dans CLAUDE.md. La lecture d’un fichier correspondant déclenche la règle à portée limitée. Une règle chargée plus tôt peut rester dans la session ; passer au CSS n’établit pas qu’elle a été retirée. Voir le contrat officiel de portée par chemin. Un fichier par domaine (modèles de base de données, conventions d’authentification, standards de tests), chacun limité aux chemins pertinents. Un fichier de règle sans champ paths: se charge à chaque session ; n’omettez ce champ que pour des contraintes réellement globales.

Résultat : Claude conserve la connaissance du projet entre sessions et applique les bonnes contraintes selon la partie de la codebase sur laquelle vous travaillez.

Hygiène du contexte

Quand la tâche en cours perd son cap, préservez décisions, contraintes, preuves et travail restant. Utilisez /compact avec un résumé ciblé, ou transportez cette passation vers une session neuve. Vérifiez l’affichage du contexte du client actif ; ce guide ne suppose pas de pourcentage fixe de compaction automatique.

Deux habitudes aident : commiter avant les grandes opérations (indexer un nouveau module, générer des tests pour tout un répertoire, lancer une migration), et répartir un travail long entre sessions plus courtes plutôt que de tout empiler dans une seule. Choisissez les frontières de session autour de tâches cohérentes et vérifiez ce qui survit à la passation.

La suite

Les trois niveaux ci-dessus couvrent la couche de configuration initiale. Ils donnent à Claude un contexte stable, protègent l’environnement et transportent la connaissance entre sessions. Au-delà, une autre couche change ce que Claude peut faire plutôt que sa connaissance du projet.

Je couvre l’architecture plus large de Claude Code et Codex dans La configuration portable d’agents est un système de release, pas un dossier partagé, notamment les cibles projet et globales, les releases immuables, le routage BM25 et les preuves d’exécution.

Deux guides sont prévus pour prolonger celui-ci, sans date de publication fixée : l’un sur les worktrees (faire tourner Claude en parallèle sur des branches isolées, quel serveur de développement ouvrir par worktree, confirmer qu’on teste la bonne branche avant livraison), l’autre sur la séparation entre ~/.claude/CLAUDE.md et le fichier du projet (quoi mettre dans chacun, ce qui casse si on se trompe, comment le fichier global cumule de la valeur dans chaque projet ouvert). Ils seront liés ici une fois publiés.

Pour l’orchestration multi-agent et le framework complet de skills, la série Context Engineering couvre les deux depuis les bases.

Ce qui reste

Le CLAUDE.md écrit au premier jour ne ressemblera pas à celui utilisé trois mois plus tard. Le mien était trop long, documentait des choses que Claude aurait pu découvrir en lisant le code, et manquait ce qui comptait le plus : les conventions de commit de l’équipe. La première version avait aussi une section expliquant ce qu’était Git. Je n’en suis pas fier. Le fichier que j’utilise maintenant est plus court que ce premier et plus utile.

Commencez petit. N’ajoutez quelque chose que lorsque vous vous surprenez à le répéter entre sessions. La configuration grandit à partir des frictions rencontrées, pas en anticipant tout ce que Claude pourrait avoir besoin de savoir.

Un hook qui détecte les commandes git brutes et suggère des équivalents RTK ne résiste pas au contact du réel. L’idée est bonne, mais si RTK relaie déjà les commandes de façon transparente au niveau shell, le hook se déclenche sur des appels déjà relayés et génère constamment des faux positifs. Quand une couche inférieure traite déjà quelque chose, ajouter une détection au-dessus crée du bruit. Appliquez le même contrôle à chaque hook : confirmez qu’une autre couche ne résout pas déjà le problème.

Si un point ne correspond pas à ce que vous observez, cc.bruniaux.com/guide/ contient la référence actuelle. Claude Code évolue vite et certains détails de syntaxe changent entre versions mineures. Si vous avez trouvé une configuration qui fonctionne mieux que celle décrite ici, je serais intéressé de la découvrir.

---

YSNK

(Vous devriez maintenant savoir)

• Sur l’API Anthropic, /fast double le tarif standard d’Opus 5.5 et de Fable 5.2. Sur abonnement, il utilise des crédits d’usage payants. Opus 4.8 perd ce mode le 30 novembre 2026
• Les Output Styles portent le formatage persistant des réponses dans la conversation principale de Claude Code ; keep-coding-instructions: true conserve les consignes intégrées d’ingénierie
• Un tsc --noEmit synchrone comme hook PostToolUse coûtait à un projet 7 à 8 minutes perdues sur une session de 30 modifications. Déplacer ce contrôle vers un hook Stop a placé le délai entre les tâches plutôt qu’en pleine réflexion
• Une ligne canari doit être du texte Markdown simple, pas un commentaire HTML. Claude Code retire les commentaires HTML de niveau bloc de CLAUDE.md avant injection ; un canari commenté n’est donc jamais vu et reste silencieux indéfiniment
• Claude Code charge au démarrage les 200 premières lignes ou 25 Ko de MEMORY.md, selon la première limite atteinte. Placez les détails dans des fichiers thématiques
• Un hook qui détecte les commandes git brutes pour suggérer des équivalents RTK semble utile jusqu’à ce que RTK relaie déjà ces commandes de façon transparente. Le hook se déclenche alors sur les appels déjà relayés et génère constamment des faux positifs ; vérifiez si une couche inférieure résout déjà le problème avant d’ajouter une détection au-dessus