Recettes Claude Code

Recette : déboguer un test en échec

Un test en échec est un signal reproductible : il indique exactement ce que le code avait promis et ce qu'il a réellement fait. Claude Code transforme ce signal en correctif en suivant une boucle en quatre étapes : Reproduire, Isoler, Corriger, Confirmer.

Reproduire signifie exécuter la commande de test afin que Claude voie le message d'erreur exact dans le contexte. Isoler signifie réduire la cause à une seule fonction, une seule assertion ou une seule hypothèse incorrecte. Corriger signifie modifier uniquement le code responsable de l'échec. Confirmer signifie relancer le test et lire un résultat vert avant de clore la tâche.

La discipline essentielle est la suivante : ne demandez pas à Claude de corriger quoi que ce soit avant qu'il ait lu l'erreur. Collez la sortie complète du test (la stack trace, c'est-à-dire la chaîne d'appels de fonctions qui a conduit au plantage) dans votre prompt. Sans elle, Claude devine.

1. Lancez votre suite de tests et copiez la sortie d'échec.
2. Ouvrez Claude Code et collez la sortie avec un objectif clair.
3. Laissez Claude lire les fichiers sources pertinents et proposer un correctif.
4. Appliquez le correctif, relancez les tests et confirmez le vert avant de passer à la suite.

Recette : refactoriser en toute sécurité

Refactoriser signifie modifier la structure interne du code sans changer ce qu'il fait de l'extérieur. Le danger est une rupture silencieuse : on déplace des éléments, et une fonctionnalité cesse de fonctionner sans que personne ne s'en aperçoive. L'antidote est un verrou de tests, une suite de tests automatisés qui prouve le comportement avant de toucher la moindre ligne de logique.

La recette comporte trois étapes dans un ordre strict :

1. Écrire ou générer les tests en premier. Demandez à Claude Code de lire votre fichier et de produire des tests couvrant le comportement actuel. Committez ces tests. Ils constituent votre filet de sécurité.
2. Exécuter les tests en mode surveillance. Utilisez /terminal dans Claude Code ou votre propre shell pour maintenir le lanceur de tests actif. Chaque fois que Claude modifie un fichier, le lanceur ré-exécute et passe au rouge dès qu'un problème apparaît.
3. Demander à Claude Code de refactoriser, une préoccupation à la fois. Des changements petits et ciblés facilitent le traçage des échecs. Si un test passe au rouge, Claude Code peut lire la sortie d'échec et corriger avant de continuer.

Claude Code lit automatiquement la sortie des tests lorsque vous la collez ou la transmettez dans la conversation. Cette boucle de retour, écrire le test, refactoriser, lire l'échec, corriger, est ce qui rend le refactoring assisté par IA fiable plutôt que téméraire.

Recette : construire une fonctionnalité en écrivant le test en premier

Le développement guidé par les tests (TDD) est un flux de travail dans lequel on écrit un test en échec avant d'écrire le code qui le fait passer. Le cycle comporte trois étapes : rouge (le test échoue), vert (le code passe le test), refactorisation (nettoyer sans casser le test). Claude Code s'y prête naturellement car on peut décrire l'intention en langage courant et le laisser générer à la fois le test et l'implémentation dans le bon ordre.

Pour commencer, donnez à Claude Code une description claire de la fonctionnalité et indiquez-lui explicitement d'écrire le test en premier. La phrase clé est : "écris un test en échec, puis fais-le passer." Sans cette instruction, Claude saute souvent directement à l'implémentation.

Une fois que Claude a produit le fichier de test, exécutez-le immédiatement. Vérifiez qu'il est rouge (en échec) avant de demander à Claude d'écrire l'implémentation. Ce point de contrôle unique évite l'erreur la plus courante en TDD : écrire un test qui ne testait en réalité rien.

• Rouge : Claude écrit le test, vous l'exécutez, il échoue.
• Vert : Claude écrit le code minimum pour faire passer le test.
• Refactorisation : Demandez à Claude de supprimer les doublons ou d'améliorer les noms, puis relancez.
• Répétition : Ajoutez le test suivant pour le comportement suivant.

Recette : revoir une pull request

Une pull request (PR) est une proposition de fusion d'un ensemble de modifications de code dans un projet. Les changements sont présentés sous forme de diff (abréviation de différence) : une vue fichier par fichier montrant les lignes supprimées en rouge et les lignes ajoutées en vert. Lire un diff attentivement, c'est ainsi que les bugs et la logique obscure sont détectés avant d'atteindre la production.

Claude Code peut lire un diff et jouer le rôle d'un second relecteur. Vous lui indiquez une branche ou une URL de PR, et il signale les problèmes selon plusieurs dimensions :

• Bugs de correction : erreurs de logique, décalages d'un, cas limites non gérés.
• Problèmes de clarté : noms de variables trompeurs, commentaires manquants sur du code non évident.
• Régressions : modifications qui cassent silencieusement un comportement existant couvert ailleurs dans la base de code.
• Signaux de sécurité : secrets codés en dur, saisies utilisateur non vérifiées, utilisation non sécurisée de dépendances.

La compétence /code-review dans Claude Code orchestre cela automatiquement. Elle lit les modifications indexées ou le diff d'une branche nommée, exécute l'analyse et retourne des résultats structurés. Vous contrôlez la profondeur avec un paramètre d'effort : --effort low pour une passe rapide, --effort high pour une couverture plus large incluant les résultats incertains. Ajoutez --comment pour publier les résultats directement en commentaires inline sur GitHub, ou --fix pour appliquer les corrections sûres à l'arbre de travail.

Recette : construire une fonctionnalité de bout en bout

Une construction de fonctionnalité couvre tout le parcours, d'une demande en langage courant jusqu'à un changement fonctionnel et testé, commité dans votre dépôt. Claude Code gère chaque étape, mais vous obtenez de meilleurs résultats en structurant ce parcours de façon délibérée.

La recette comporte quatre phases :

1. Périmètre. Ouvrez Claude Code à la racine de votre projet et décrivez ce que vous voulez en une phrase claire. Demandez-lui de lister les fichiers qu'il va modifier avant d'écrire quoi que ce soit : /plan ou dites simplement "liste les fichiers que tu vas modifier et pourquoi, puis attends mon accord."
2. Implémentation. Approuvez le plan, puis laissez Claude Code écrire le code. Observez les appels d'outils dans le terminal. Si un appel vous semble incorrect, tapez /stop pour interrompre sans perdre le contexte.
3. Vérification. Demandez à Claude Code d'exécuter les tests ou le linter pertinents : run the tests for this module and show me the output. Pour un changement d'interface, utilisez le skill /run ou demandez-lui de démarrer le serveur de développement et de décrire ce qu'il faut vérifier.
4. Commit. Une fois les tests passés, demandez à Claude Code de stager uniquement les fichiers modifiés et de rédiger un message de commit. Relisez le diff affiché avant de confirmer.

Deux habitudes qui évitent les corrections inutiles : lisez toujours le plan avant de l'approuver, et exécutez toujours les tests dans Claude Code plutôt que de vous fier à une inspection visuelle seule.

Recette : corriger un bug de façon systématique

Se précipiter vers une correction sans comprendre la cause profonde est le moyen le plus rapide de créer deux bugs au lieu d'un. L'approche systématique impose le principe diagnostic d'abord, correctif ensuite. Claude Code soutient cette discipline grâce à un ensemble de commandes qui lisent, tracent et testent avant de toucher au code.

Le workflow comporte quatre phases. Reproduire : confirmer que le bug est réel et isolé. Tracer : trouver la ligne exacte et la raison de l'échec. Formuler une hypothèse : énoncer une cause précise avant d'écrire la moindre correction. Vérifier : relancer les tests après le correctif pour confirmer que le symptôme a disparu et qu'aucun nouveau problème n'est apparu (c'est ce qu'on appelle un test de régression).

Le skill /systematic-debugging de Claude Code impose cet ordre. Vous pouvez également le piloter manuellement avec de simples prompts. Dans tous les cas, la règle clé est : n'acceptez pas un correctif proposé par Claude s'il n'explique pas aussi pourquoi le bug s'est produit.

• Commencez par : what is the root cause of this error?, et non fix this error.
• Demandez à Claude d'afficher la pile d'appels (la chaîne de fonctions qui a conduit au plantage) avant de suggérer un changement.
• Demandez une reproduction minimale : le plus petit morceau de code qui déclenche encore le bug.
• Après le correctif, exécutez claude --print "run the existing test suite and report any failures" pour détecter les régressions.

Recette : migrer ou mettre à jour une dépendance

Une dépendance est une bibliothèque externe dont votre projet a besoin (par exemple, un formateur de dates ou un client HTTP). La mettre à jour consiste à changer un numéro de version, corriger chaque rupture et vérifier que l'application fonctionne toujours. Claude Code transforme cette tâche en plusieurs étapes en une conversation guidée.

La recette comporte quatre phases :

1. Planifier : demandez à Claude Code de lire la version actuelle, de consulter le changelog et de lister les changements incompatibles qui affectent votre code.
2. Modifier : laissez-le éditer package.json (ou le manifeste correspondant) et exécuter la commande d'installation.
3. Exécuter : lancez votre build et votre suite de tests pour que les erreurs remontent immédiatement.
4. Vérifier : examinez le diff, confirmez que les tests passent et effectuez un test rapide de la fonctionnalité concernée.

Comme Claude Code peut lire des fichiers, exécuter des commandes shell et itérer dans une seule session, il détecte les erreurs en cascade (où la correction d'un import en casse un autre) sans que vous ayez à naviguer entre des onglets de terminal. Committez toujours votre code avant de commencer afin de disposer d'un point de retour arrière propre.

Recette : prendre en main une base de code inconnue

Quand vous ouvrez une base de code que vous n'avez jamais vue, vous lancer directement dans l'édition est le moyen le plus rapide de tout casser. Le réflexe professionnel est de cartographier le territoire d'abord : comprendre ce qui existe, où se trouvent les points d'entrée, et seulement ensuite agir. Claude Code peut faire la majeure partie de ce travail à votre place en une seule session.

Commencez par une reconnaissance générale. Demandez à Claude Code de décrire la structure du projet, de lister les principaux répertoires et d'identifier les points d'entrée (les fichiers où l'exécution démarre, comme index.js, main.py ou app.ts). Demandez-lui ensuite de repérer les fichiers de configuration clés : gestionnaires de paquets (package.json, pyproject.toml), modèles d'environnement (.env.example) et définitions CI (.github/workflows/).

Une fois que vous avez une carte mentale, la chose la plus utile que vous puissiez faire est d'écrire un fichier CLAUDE.md à la racine du projet. Ce fichier texte brut est automatiquement lu par Claude Code au début de chaque session. Il joue le rôle d'un briefing permanent : il indique à Claude Code comment construire le projet, quelles commandes éviter, quels répertoires sont importants et les conventions de l'équipe. Sans lui, chaque nouvelle session repart de zéro.

Un bon CLAUDE.md couvre quatre points :

• Commandes de build et d'exécution : comment installer les dépendances et démarrer l'application.
• Commande de tests : la commande unique qui lance la suite de tests complète.
• Notes d'architecture : quels dossiers couvrent quelle responsabilité (couche API, couche UI, couche base de données).
• Règles d'interdiction : les fichiers ou motifs que Claude Code ne doit jamais modifier sans permission explicite.

Recette : générer et maintenir la documentation

Une documentation qui diverge du code est pire que pas de documentation du tout : elle induit en erreur. La solution consiste à traiter les docs comme un artefact de build, généré et mis à jour par Claude Code chaque fois que le code change. L'idée centrale est le docs-as-code : votre README, la référence d'API et les changelogs vivent dans le repo et sont régénérés à la demande.

Claude Code peut lire toute votre base de code en une seule passe et produire une documentation précise et structurée. Les options clés sont --print (mode non interactif, redirige la sortie vers un fichier) et --allowedTools "Read,Write" (restreint Claude à la lecture des sources et à l'écriture des docs, rien d'autre). Cadrez toujours le prompt de manière précise : nommez les fichiers à lire et le fichier à écrire.

Pour une synchronisation continue, deux approches fonctionnent bien :

• Git hook : un hook pre-commit exécute claude --print et indexe automatiquement le fichier de documentation mis à jour, afin que les docs ne soient jamais commités avec du retard.
• Étape CI : une étape GitHub Actions ou un autre pipeline régénère la documentation à chaque fusion sur main, puis ouvre une pull request si quelque chose a changé.
• Mise à jour ciblée : après avoir modifié un module spécifique, exécutez Claude Code limité à ce seul fichier pour minimiser le coût et la latence.
• Génération de changelog : passez directement la sortie de git log --oneline dans le prompt et demandez à Claude de produire une section de changelog lisible par un humain.

L'identifiant de modèle pour les tâches de documentation courantes est claude-sonnet-4-6 : rapide et suffisamment précis pour une sortie structurée. Réservez claude-opus-4-8 pour la documentation de niveau architectural qui nécessite un raisonnement approfondi sur les décisions de conception.

Recette : automatiser une tâche répétitive

Une tâche répétitive est toute opération que vous effectuez plus de deux ou trois fois avec la même structure : renommer un lot de fichiers, convertir un rapport dans un autre format, récupérer des données depuis une API et les mettre en forme, nettoyer des journaux. Ce sont des candidats idéaux pour l'automatisation avec Claude Code.

La première étape consiste à repérer le schéma. Posez-vous la question : quelles entrées changent à chaque fois, et qu'est-ce qui reste fixe ? La partie fixe devient le script ; la partie variable devient un paramètre (une entrée variable que vous transmettez). Claude Code peut écrire, exécuter et affiner ce script en une seule conversation.

La deuxième étape est de capturer la recette pour ne plus jamais la retaper de zéro. Claude Code vous offre deux options :

• Un fichier script : un script Node, Python ou shell sauvegardé dans votre projet, que vous invoquez par une seule commande chaque fois que vous en avez besoin.
• Une slash-command (skill) : un court fichier markdown placé dans ~/.claude/skills/ qui devient une /votre-commande déclenchable dans n'importe quelle session future.

Une fois la recette en place, exécuter la tâche ne vous coûte plus qu'une seule commande. Claude Code lit le script, confirme les paramètres et exécute, en vous fournissant un journal que vous pouvez examiner avant que les fichiers ne soient modifiés.

Recette : écrire et exécuter un script jetable

Parfois, vous avez besoin d'un script jetable : un petit programme qui accomplit une tâche unique sur le moment et dont vous n'aurez plus jamais besoin. Exemples : renommer 200 fichiers, analyser un CSV, ou interroger une API pour récupérer des données. L'écrire à la main est lent. Claude Code peut l'écrire et l'exécuter pour vous en une seule opération.

La recette comporte trois étapes. Vous décrivez la tâche en langage courant, Claude Code génère le script (généralement un court fichier Node.js ou Python), puis il l'exécute immédiatement. Vous obtenez le résultat sans jamais ouvrir un éditeur de texte.

Éléments clés à inclure dans votre demande pour que Claude Code réussisse du premier coup :

• Entrée : quelles données ou quels fichiers le script doit-il lire ? Donnez un exemple réel si possible.
• Sortie : à quoi doit ressembler le résultat ? Une liste affichée, un nouveau fichier, un nombre ?
• Environnement : Node.js (CommonJS avec require) ou Python ? Si vous ne le précisez pas, Claude Code choisira selon ce qui est disponible.
• Suppression : dites "exécute-le et supprime-le" si vous ne souhaitez pas conserver le fichier.

Claude Code écrit le fichier dans un chemin temporaire, l'exécute, vous retransmet la sortie en direct, et peut supprimer le fichier automatiquement. Aucun fichier résiduel, aucun nettoyage manuel.

Recette : expliquer du code confus

Quand vous ouvrez un fichier inconnu et que la logique est opaque, Claude Code peut vous le parcourir ligne par ligne. L'essentiel est de fournir suffisamment de contexte : le fichier, la section précise, et ce que vous savez déjà (même si c'est "rien").

La voie la plus rapide est la syntaxe at-mention. Dans le panneau de chat de Claude Code, tapez @nomdefichier pour joindre un fichier directement à votre message. Claude l'explique alors avec une visibilité complète sur le code source réel, et non sur un extrait que vous auriez peut-être tronqué.

Pour une explication ciblée, réduisez la demande à une fonction, une classe, ou même une seule expression. Les demandes larges ("explique tout ce dépôt") produisent des réponses larges. Les demandes focalisées produisent des réponses exploitables.

• Mention @fichier : joindre le fichier source pour que Claude le lise directement
• Plage de lignes : demander les lignes 42-67 si le reste est clair
• Analogie : ajouter "explique avec une analogie du monde réel" pour la logique abstraite
• Mode glossaire : demander à Claude de définir chaque terme inconnu qu'il emploie dans l'explication