Best Practices for Claude Code

1Un bon prompt dit ce qui ne bouge pas

Première famille : borner ce que Claude a le droit de faire, à commencer par la demande elle-même. Face à une demande floue, Claude ajoute du code intermédiaire, des fichiers et des évolutions que personne n'a réclamées (ch. 6). Un verbe comme « refactore » aggrave le problème. Refactorer, c'est réorganiser du code sans changer ce qu'il fait. Or, selon le livre, ces termes ne sont pas neutres : ils « signalent une permission » (ch. 8).

Contre ce débordement, le livre résume un bon prompt en quatre éléments (ch. 7) :

• ce qui doit changer ;
• ce qui ne doit pas changer ;
• les compromis qui comptent ;
• les compromis qui ne comptent pas.

Le livre applique ces quatre éléments dans un exercice de réécriture, sur l'application de diapositives (ch. 8) :

✗ « Ajoute des statistiques d'usage pour suivre la génération de diapositives. »

✓ « Ajoute des statistiques d'usage légères, prêtes pour la production, pour suivre
   la génération de diapositives. La logique doit vivre dans un module ou un service
   dédié et isolé, et ne doit modifier ni la logique de génération existante, ni les
   modèles de données, ni les API. N'introduis aucune nouvelle dépendance ni changement
   d'architecture. Le surcoût à l'exécution doit être négligeable. Si c'est impossible
   sans violer ces contraintes, arrête-toi et explique pourquoi. »

Dans la version ✓, chaque morceau a un rôle :

• Le module isolé et les interdictions disent ce qui ne bouge pas. Un module est un morceau de code rangé à part.
• Le surcoût négligeable est le compromis qui compte.
• La dernière phrase offre à Claude une sortie honnête : s'arrêter et expliquer, au lieu de bricoler.

Pourquoi tant de soin ? Le livre répond par un avertissement : Claude Code « ne protégera pas votre architecture à votre place » (ch. 8). L'architecture est la façon dont le code est découpé et organisé. Claude ne vous arrêtera pas non plus de façon fiable devant un changement risqué. Il est « un multiplicateur » (ch. 8) : des consignes bâclées produisent donc des dégâts plus vite qu'à la main.

2Le CLAUDE.md prévient, il ne répare pas

Un prompt borné ne vaut que pour une demande. Pour borner toutes les sessions d'un coup, le livre passe à un fichier. Le CLAUDE.md est un fichier Markdown à la racine du projet. Claude le lit au démarrage de chaque session, « avant votre prompt, avant votre code » (ch. 10). Ses règles pèsent donc sur chaque réponse.

Le CLAUDE.md n'a pas à s'écrire à la main. La commande /init en écrit un premier brouillon : elle analyse le dépôt, c'est-à-dire le dossier du projet (ch. 10). On y ajoute ensuite ce que Claude ne peut pas deviner :

• les frontières du projet : ici pas de base de données, pas de comptes, pas de pages fabriquées par le serveur (ch. 12) ;
• les versions des outils : Node, Python, Docker et PowerShell, que Claude relève sur la machine (ch. 13).

Deux de ces outils reviennent plus loin. Node fait tourner du JavaScript hors du navigateur, et PowerShell est le terminal de Windows. Voici un exemple de mon cru, pas du livre, dans l'esprit du cours :

# CLAUDE.md
## Périmètre
- Hors périmètre : base de données, comptes utilisateurs, rendu côté serveur
## Environnement
- Windows, PowerShell uniquement ; Node 18 ou plus
## Règles apprises
- Ne pas refactorer la logique de mise en page
- Pas de nouveau fichier pour un changement de mise en page

La section « Règles apprises » de cet exemple suit la règle d'entretien du livre. Dès que vous corrigez Claude deux fois sur le même point, la correction entre dans le fichier (ch. 13). Le livre en tire sa formule. Le CLAUDE.md n'est pas l'endroit où l'on résout les problèmes : c'est celui où l'on empêche les mauvais d'arriver (ch. 13).

3Le mode plan : pas de code avant un plan relu

Deuxième famille : faire réfléchir Claude par écrit avant qu'il code. Un scratchpad (bloc-notes) est un fichier Markdown où Claude écrit son analyse avant de toucher au code. Le mode plan est un réglage de Claude Code qui l'y aide. Dans ce mode, Claude lit les fichiers librement. Ses modifications et ses commandes restent bloquées tant que vous n'avez pas approuvé un plan (ch. 18).

Le livre enchaîne les deux en quatre temps (ch. 18) :

1. on entre en mode plan ;
2. Claude remplit le scratchpad ;
3. on relit ;
4. on passe à un mode qui autorise les modifications.

Le deuxième temps part d'un prompt, que voici (ch. 15) :

« Crée un fichier scratchpad.md. Sers-t'en pour raisonner sur le prochain changement
avant d'écrire du code. Inclus l'objectif, les contraintes, un plan pas à pas et ce qui
ne doit pas changer. Ne modifie encore aucun code. »

Sur l'application de diapositives, Claude en sort trois options d'architecture, avec leurs avantages et leurs inconvénients (ch. 17). Il relève aussi des cas limites, ces situations extrêmes où le code risque de casser :

• un Markdown vide ;
• des séparateurs de diapositives cachés dans un bloc de code ;
• un export PDF géant.

Le scratchpad a un second rôle. Selon le livre, Claude Code est « sans état » d'une session à l'autre (ch. 15) : il ne garde aucun souvenir du raisonnement de la session précédente. Le scratchpad garde ce raisonnement à sa place. Ce point a changé depuis, voir « Toujours valable en 2026 ? ».

Puisque la session suivante s'appuie sur lui, le scratchpad doit rester à jour. Un document de planification périmé est souvent pire que pas de document, car il donne une fausse confiance (ch. 18).

4Trois contraintes tranchent mieux qu'un avis

Le scratchpad ne tranche pas tout. Il laisse un choix ouvert : où stocker les statistiques (ch. 17) ?

• option A : des compteurs en mémoire, écrits dans un fichier JSON, un format de données en texte ;
• option B : un système d'événements, du code qui réagit aux messages envoyés par le reste de l'application ;
• option C : une base SQLite, une base de données tenue dans un seul fichier.

Pour trancher, le livre ne demande pas « qu'en penses-tu ? ». Il nomme la décision dans un ADR (Architecture Decision Record). Un ADR est une fiche numérotée qui consigne une décision d'architecture. Celle-ci s'appelle ADR-001. Le prompt pose ensuite trois contraintes, qu'une solution respecte ou non (ch. 20) :

« Résous les décisions ouvertes de SCRATCHPAD.md liées au suivi d'usage, en particulier
l'ADR-001. Visons une approche plus simple que le système d'événements complet.
Produis un plan d'implémentation avec tous les changements de fichiers.
Contraintes :
- Aucune base de données externe
- Uniquement les modules intégrés à Node.js
- Les données doivent survivre aux redémarrages »

Avec ces contraintes, Claude retient une variante simplifiée de l'option A (ch. 21). Un seul objet, partagé par tout le code, accumule les compteurs en mémoire. Cet objet unique s'appelle un « singleton ». Il n'écrit dans le fichier qu'après une courte pause (ch. 21). Sans les contraintes, Claude aurait pu raisonnablement choisir une architecture plus élaborée (ch. 21).

Le plan qui en sort se relit avant validation, et il est court. Il tient en un fichier créé, trois modifiés, aucune dépendance et huit vérifications (ch. 21 et 22). Une dépendance est une bibliothèque externe ajoutée au projet. Le plan copie aussi la structure des services déjà présents. Le nouveau code entre ainsi dans le style existant au lieu d'en importer un autre (ch. 21). Leçon du module : « les bases de code existantes récompensent la discipline » (ch. 25).

5Un prompt de reprise dit aussi quoi ne pas refaire

Troisième famille : rattraper ce qui dérape, à commencer par l'accident le plus brutal. Pendant l'implémentation du suivi d'usage, Claude lance Get-Process node | Stop-Process -Force. Cette commande PowerShell arrête de force tous les processus Node, c'est-à-dire tous les programmes Node en cours. Un processus fils est un programme lancé par un autre. Selon le livre, arrêter de force un processus Node fils peut fermer le terminal, et l'assistant avec (ch. 23).

La session meurt, mais les fichiers sont intacts. L'interruption touche la session, pas forcément le code (ch. 23). Il faut donc rendre à Claude son contexte, c'est-à-dire ce qu'il savait de la tâche. Le livre le fait avec un prompt de reprise en quatre éléments (ch. 23) :

• ce qui est déjà fait ;
• relire le code d'abord ;
• des tâches non destructives ;
• des interdits.

Ces quatre éléments se résument en quelques lignes. Voici une reconstitution de ce prompt, écrite par moi d'après la description du livre :

« Le suivi d'usage (option A) est implémenté et les tests serveur passent. La session
s'est arrêtée avant la mise à jour de SCRATCHPAD.md. Relis d'abord usageTracker.js,
slides.js et index.js. Puis mets à jour SCRATCHPAD.md. Ne relance pas le serveur et
n'exécute aucun test. »

La dernière phrase de ce prompt porte la règle du livre. Un prompt de reprise ne dit pas seulement quoi faire, il dit aussi quoi ne pas répéter (ch. 23).

6Le code qui marche peut quand même dériver

Comme une session coupée, un plantage se voit tout de suite. La dérive silencieuse, non : le code marche, mais il s'écarte peu à peu de la structure du projet. Le livre en donne trois formes (ch. 31) :

• une logique dupliquée ;
• un utilitaire partagé contourné, c'est-à-dire une fonction commune au projet qu'on n'appelle pas ;
• un comportement posé au mauvais niveau.

Cas concret, inventé pour illustrer la première forme : Claude réécrit un formatage de durée dans le nouveau module. Or le projet en possède déjà un. Tout marche, et la dette technique est entrée. La dette technique est un raccourci qu'il faudra rembourser plus tard.

Contre cette dérive, le livre propose six temps (ch. 33) :

1. cartographier le code concerné ;
2. choisir « l'endroit le plus étroit pour étendre le système » (ch. 32) ;
3. fixer des règles de changement minimal ;
4. implémenter par petits pas vérifiables ;
5. demander à Claude d'auditer sa propre dette technique ;
6. valider ce qui n'a pas changé.

Le sixième temps, valider ce qui n'a pas changé, s'appuie sur un prompt. Ce prompt force Claude à prouver qu'il a compris le code existant (ch. 33) :

« Liste tous les comportements qui doivent rester inchangés après cette modification.
Explique comment l'implémentation actuelle les préserve. »

La réponse de Claude se lit comme un test. Une réponse floue veut dire que la modification n'est pas sûre. Compiler ne prouve rien non plus : un code sans erreur de syntaxe peut quand même dériver. Le livre le résume en quatre mots : « compiler n'est pas relire » (ch. 34).

Enfin, la dérive commence souvent par une phrase. Le livre prévient que trois phrases d'apparence anodine lui ouvrent la porte (ch. 33) :

• « Ajoute-le vite fait » ;
• « Refactore pendant qu'on y est » ;
• « On nettoiera plus tard ».