Bonnes pratiques Claude Code : écrire moins, vérifier plus

Le CLAUDE.md de ce blog fait près de 700 lignes. Il contient une section titrée « RÈGLE ABSOLUE », des tableaux de liens, des exemples de code pour chaque cas. En lisant le guide officiel des bonnes pratiques, j'ai compris qu'il cochait à peu près toutes les cases de ce qu'Anthropic déconseille.

Les bonnes pratiques Claude Code sont une page de la documentation officielle d'Anthropic. Elles partent d'un constat : avec les modèles actuels, le premier prompt d'une session fait déjà presque toujours ce qu'il faut. La page ne parle donc pas de « bien prompter ». Elle parle de ce qu'il faut faire quand les valeurs par défaut ne suffisent pas, c'est-à-dire quand votre projet contient des règles, des contraintes ou des connaissances que Claude ne peut pas lire dans le code.

Quatre façons dont une session déraille

Le guide classe les sessions ratées en quatre cas, et chacun a son remède.

Ce tableau m'a plus servi que tout le reste. Quand une session part de travers, je cherche la ligne qui correspond au lieu de reformuler mon prompt au hasard.

Ce que Claude décide, et ce que Claude Code impose

L'idée centrale du guide est une distinction que je n'avais jamais formulée aussi clairement. Il y a deux sortes d'instructions.

Les non déterministes : votre prompt, CLAUDE.md, les skills. Claude les lit, puis décide. Il les suit presque toujours, mais rien ne le garantit.

Les déterministes : les hooks, les règles de refus, les paramètres gérés. C'est le harnais, Claude Code lui-même, qui les applique. Le modèle n'a pas son mot à dire.

La plupart du temps, il faut laisser Claude décider. Presque toute règle a des exceptions, et un modèle qui a le code réel sous les yeux juge mieux qu'une consigne écrite trois mois plus tôt. Le déterministe est réservé à ce qui doit se produire toujours, ou jamais : ne pas toucher au client généré dans src/gen/, lancer le script de licence après chaque création de fichier.

Le guide donne un signal simple pour savoir de quel côté se trouve une règle. Si vous ajoutez des majuscules et des « IMPORTANT » à une ligne de CLAUDE.md et que Claude la rate quand même, elle doit devenir un hook. À l'inverse, un hook qui impose une simple préférence doit redevenir une ligne de texte.

Dire à Claude ce qu'il ne peut pas voir

Claude lit votre code très bien, et plus vite que vous ne pourriez l'expliquer : l'organisation des fichiers, les conventions, le framework de test. Ce qu'il ne trouvera jamais, c'est ce qui n'a jamais été écrit dans le dépôt. La décision prise en réunion. Le déploiement que seul un collègue sait faire. La variable d'environnement dont les tests d'intégration ont besoin.

Avant d'écrire quoi que ce soit pour Claude, le guide propose deux questions. Pourrait-il le trouver en lisant le code ? Irait-il réellement le chercher ? Si c'est oui aux deux, inutile de l'écrire.

Un prompt précis vaut mieux que trois corrections

Le fichier, le symptôme, et à quoi ressemble « corrigé ». J'ai rassemblé les phrases de ce type dans la sélection des prompts Claude Code publiés par Anthropic, qui applique ces principes tâche par tâche.

Une expression garde de la valeur : « sois ambitieux ». Claude interprète une demande de façon prudente et construit la plus petite chose qui y répond. S'il doit gérer les états vides, les erreurs et la navigation au clavier, dites-le. Ça règle la portée, pas l'intensité de réflexion.

Garder CLAUDE.md court

CLAUDE.md est chargé dans chaque session. Chaque ligne prend un peu d'attention sur chaque tâche, qu'elle soit pertinente ou non. Le guide recommande de rester sous les 200 lignes et de n'y mettre que quatre choses :

1. Les commandes pour valider le travail : tests, vérification de types, lint, et comment lancer un seul fichier de test.
2. Les endroits où le code est trompeur : un vieux modèle présent partout qu'il ne faut pas copier.
3. Les décisions absentes du dépôt : le helper d'erreur retenu, le fonctionnement des déploiements.
4. Tout ce que vous avez déjà dû corriger deux fois.

Ça donne un fichier de ce genre :

# Commands
- Install: pnpm install
- Run one test file: pnpm vitest run path/to/file.test.ts
- Typecheck: pnpm tsc --noEmit
 
# Conventions
- Use the error helpers in src/lib/errors.ts, never throw raw strings
- src/legacy/ is still live but don't copy its patterns into new code
 
# Gotchas
- Integration tests need DATABASE_URL set, see .env.example

Dix lignes. Pas de description de l'architecture : Claude la lit tout seul. /init génère une première version, et le vrai travail consiste ensuite à supprimer. /doctor suggère les lignes que Claude peut déduire du code.

Ce qui ne concerne qu'une partie du code va dans .claude/rules/ avec un filtre paths:, chargé seulement quand Claude travaille dans ces fichiers. Les procédures longues, comme une release ou un runbook d'incident, vont dans un skill : Claude ne voit que son nom et sa description tant qu'il n'en a pas besoin. Les préférences personnelles vont dans CLAUDE.local.md, ajouté au .gitignore.

Donner à Claude une vérification à exécuter

C'est la section la plus importante du guide. Claude s'arrête quand le travail semble terminé. S'il n'a rien à exécuter pour savoir s'il l'est vraiment, « semble » est tout ce qu'il a. Et c'est vous qui devenez la suite de tests.

Donnez-lui quelque chose qui renvoie réussite ou échec : un test, le code de sortie d'un build, un linter, une capture d'écran à comparer à la maquette. Il boucle alors seul jusqu'au vert. Le guide propose quatre niveaux de rigueur :

Le hook Stop tient en quelques lignes. Le code de sortie 2 empêche Claude de terminer, et ce qui part sur stderr lui est renvoyé comme raison :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          { "type": "command", "command": "pnpm tsc --noEmit 1>&2 || exit 2" }
        ]
      }
    ]
  }
}

Quel que soit le niveau, exigez des preuves : la commande lancée et sa sortie. « Tous les tests passent » ne dit presque rien. Lire la sortie prend dix secondes, la relancer vous-même en prend plus.

Un détail du guide m'a fait sourire parce qu'il est vrai. Quand vous demandez une revue, ajoutez « ignore le style ». Un relecteur à qui l'on demande de trouver des problèmes en trouvera toujours. Corrigez tout, et vous finissez avec des couches d'abstraction et des tests pour des cas impossibles.

Imposer ce qui ne tolère aucune exception

« Ne jamais lire .env », « toujours lancer le formateur », « ne pas toucher aux migrations » : Claude suivra ces lignes presque à chaque fois. Pour les cas où « presque » ne suffit pas, elles sortent de CLAUDE.md.

Le formateur devient un hook PostToolUse qui s'exécute après chaque Edit ou Write. Que Claude s'en souvienne n'a plus d'importance, puisque ce n'est pas lui qui le lance. Le fonctionnement détaillé est dans le guide complet des hooks Claude Code.

Les secrets passent par des règles de refus :

{
  "permissions": {
    "allow": ["Bash(pnpm tsc --noEmit)"],
    "ask": ["Bash(git push *)"],
    "deny": ["Read(./.env)", "Read(./.env.local)", "Read(./secrets/**)"]
  }
}

Les règles deny s'appliquent dans tous les modes, y compris le mode auto. Attention à leur limite : elles portent sur des appels d'outils, pas sur des intentions. La règle Read bloque bien cat .env, mais pas un script qui ouvre le fichier. Pour une vraie barrière sur le système de fichiers et le réseau, le guide recommande d'activer aussi le sandbox avec /sandbox.

Et gardez cet ensemble petit. Chaque hook se déclenchera un jour à tort, et quelqu'un devra le maintenir. Quarante règles imposées, ce sont surtout des préférences que Claude aurait pu juger seul.

Changer une valeur par défaut, et seulement là

Une session neuve démarre en mode auto, avec un effort moyen, délègue à des sous-agents quand c'est utile et compacte la conversation quand elle grossit. Le guide conseille de ne rien toucher tant qu'une tâche ne coûte pas trop cher, et de regarder /usage avant de changer quoi que ce soit.

Le mode auto est un compromis. Le mode manuel vous fait approuver chaque commande, et au bout de la dixième on approuve sans lire. Le mode auto laisse Claude avancer et fait vérifier les actions risquées par un classifieur distinct : curl | bash, déploiement en production, force push, données envoyées vers l'extérieur. Mais c'est un jugement, pas une règle. Vos « jamais » restent dans des règles de refus.

L'effort remplace la plupart des formules magiques. /effort high pour un bug dans du code qu'on n'a pas écrit ou un test instable. /effort low pour un brainstorming ou un renommage qu'on relit de toute façon. ultrathink dans un prompt pour un seul tour difficile.

Les sous-agents ont un coût que j'avais sous-estimé. Chacun envoie ses propres requêtes et doit reconstruire un contexte que la conversation avait déjà. Ils apportent du parallélisme et un regard neuf, pas une réponse plus intelligente. Pour une tâche simple, model: haiku dans leur définition coûte beaucoup moins cher.

Enfin, /clear entre deux tâches sans rapport. Chaque requête renvoie toute la conversation : une session qui a accumulé trois sujets les relit tous à chaque tour du quatrième.

Piloter la session

Aucune configuration ne remplace la première minute. On regarde ce que fait Claude, et on intervient dès qu'il part ailleurs.

1. Esc l'arrête en pleine action sans rien perdre.
2. Esc deux fois, ou /rewind, ramène le code et la conversation à un prompt antérieur. Ça permet d'essayer d'abord l'approche audacieuse.
3. Après deux corrections ratées, /clear et un meilleur prompt. Une troisième correction alourdit une conversation qui contient déjà deux échecs que Claude continue de relire.

Les checkpoints ne couvrent que les fichiers modifiés par les outils d'édition de Claude. Un fichier changé par une commande Bash n'est pas restauré. Git reste votre filet.

Laisser Claude travailler sans vous

Pour une exécution sans surveillance, une nuit ou dans une CI, le guide pose cinq questions :

1. Sait-elle à quoi ressemble « terminé » ? Une spec, un objectif, un test rouge à passer au vert.
2. Peut-elle vérifier son propre travail ?
3. Qu'a-t-elle le droit de toucher ? Permissions, sandbox, worktree, une seule branche.
4. Qu'est-ce qui l'arrête ? --max-turns, --max-budget-usd.
5. Où va le résultat, et qui le valide ? Une PR, et un humain qui approuve la fusion.

En script, claude -p exécute un prompt et s'arrête. C'est ce qui permet de brancher Claude Code dans un pipeline GitHub Actions ou une boucle shell :

for file in $(cat files.txt); do
  claude --bare -p "Migrate $file to the new logger API and commit. Reply OK or FAIL." \
    --allowedTools "Read,Edit,Bash(git add *),Bash(git commit *)" \
    --permission-mode dontAsk \
    --max-turns 20
done

--bare ignore hooks, skills, serveurs MCP et CLAUDE.md, pour que l'exécution soit identique partout. Les outils sont pré-approuvés, tout le reste est refusé, et le nombre de tours est plafonné. Le conseil qui accompagne l'exemple est le bon : essayez sur trois fichiers, corrigez le prompt, puis lancez le reste.

Les réflexes à abandonner

La dernière section du guide est ma préférée. Elle liste des conseils qui étaient justes il y a un ou deux ans, et que les modèles actuels ont rendus inutiles.

Mon CLAUDE.md de 700 lignes est dans cette colonne de gauche. Les tableaux de liens et les règles éditoriales qu'il contient restent utiles, parce que Claude ne peut pas les deviner. Mais la moitié du reste décrit des choses qu'il lit très bien dans le code.

Le guide d'Anthropic se résume en une phrase qu'on pourrait coller en tête de n'importe quel CLAUDE.md : écrivez ce que Claude ne peut pas voir, donnez-lui un test à faire passer, et imposez par la configuration ce qui ne doit jamais plier. Tout le reste, il le fait mieux sans vous. Le plus difficile n'est pas d'ajouter des règles, c'est d'en supprimer. Pour brancher Claude sur les outils qui vivent hors du dépôt, ticketing ou suivi d'erreurs, la suite logique est le protocole MCP.