Workflow Prompt‑to‑PR avec Claude Code : petites modifications

Pourquoi Prompt-to-PR est préférable aux gros prompts en une fois

Les gros prompts en une fois entraînent souvent de grosses modifications désordonnées : des dizaines de fichiers touchés, des refactors sans lien, et du code que vous n’avez pas eu le temps de comprendre. Même si le résultat est techniquement correct, la revue paraît risquée parce qu’il est difficile de savoir ce qui a changé et pourquoi.

Les petites modifications règlent ce problème. Quand chaque changement est limité et ciblé, vous pouvez le lire en quelques minutes, repérer tôt les erreurs et éviter de casser des éléments que vous ne vouliez pas toucher. Les réviseurs font davantage confiance aux petits PR, donc les merges se font plus vite et avec moins d’allers‑retours.

Prompt-to-PR est une boucle simple :

• Demandez une seule petite modification avec des limites claires.
• Vérifiez le diff et confirmez qu’il correspond à l’intention.
• Lancez vos vérifications habituelles (tests, lint, build).
• Si quelque chose échoue, re‑promptez avec l’erreur exacte et le contexte.
• Répétez jusqu’à obtenir un PR prêt à merger.

Ce rythme transforme les échecs en retours rapides au lieu d’une surprise à la fin. Si vous demandez à Claude Code d’ajuster une règle de validation, limitez‑vous à cette règle. Si un test échoue, collez la sortie de l’échec et demandez la plus petite correction qui fait passer le test, pas une réécriture entière du module.

Une chose ne change pas : vous êtes toujours responsable du code final. Traitez le modèle comme un pair local qui tape vite, pas comme un pilote automatique. Vous décidez de ce qui entre, de ce qui reste, et du moment où il est sûr d’ouvrir le PR.

Préparez votre repo et votre configuration de pairing local

Commencez à partir d’une base propre. Si votre branche est en retard ou que des tests échouent déjà, chaque suggestion devient une supposition. Pull des dernières modifications, rebasez ou mergez selon la préférence de votre équipe, et assurez‑vous que l’état actuel est sain avant de demander quoi que ce soit.

Une configuration de « pair programmer local » signifie que Claude Code modifie des fichiers dans votre repo pendant que vous gardez le contrôle sur l’objectif, les garde‑fous et chaque diff. Le modèle ne connaît pas votre codebase sauf si vous la lui montrez, soyez donc explicite sur les fichiers, contraintes et comportements attendus.

Avant la première invite, décidez où les vérifications seront exécutées. Si vous pouvez lancer les tests localement, vous aurez un retour en quelques minutes, ce qui maintient les itérations petites. Si certaines vérifications ne tournent qu’en CI (certaines règles de lint, suites longues, étapes de build), décidez quand vous allez vous fier à la CI pour ne pas attendre après chaque petite modification.

Une simple check‑list pré‑vol :

• Mettez à jour votre branche et confirmez que l’app se build ou démarre.
• Lancez les vérifications rapides localement (lint, tests unitaires, checks de types).
• Notez quelles vérifications sont uniquement CI et combien de temps elles prennent.
• Confirmez que vous pouvez reproduire l’incident ou voir clairement la fonctionnalité manquante.
• Assurez‑vous de pouvoir annuler les modifications facilement (état propre, petits commits).

Gardez un minuscule bloc‑notes ouvert pendant que vous travaillez. Notez les contraintes comme « pas de changements d’API », « comportement rétrocompatible », « toucher seulement le module X », ainsi que les décisions que vous prenez. Quand un test échoue, collez le message d’erreur exact là aussi. Ce bloc‑notes devient la meilleure entrée pour votre prochaine invite et empêche la session de dériver.

Rédigez des invites qui mènent naturellement à de petits diffs

Les petits diffs commencent par une invite volontairement étroite. La voie la plus rapide vers du code mergeable est un changement que vous pouvez relire en une minute, pas un refactor que vous devez comprendre pendant une heure.

Une bonne invite nomme un objectif, une zone du code et un résultat attendu. Si vous ne pouvez pas indiquer où le changement doit se produire (fichier, dossier ou module), le modèle devinera et le diff s’étendra.

Une forme d’invite qui garde les changements contenus :

• Objectif : le seul comportement que vous voulez changer.
• Emplacement : le(s) fichier(s) ou composant(s) à toucher.
• Contraintes : ce qui ne doit pas changer.
• Acceptation : à quoi ressemble le « terminé ».
• Taille du diff : demandez explicitement la plus petite modification qui fonctionne.

Les limites sont l’arme secrète. Au lieu de « corriger le bug de connexion », indiquez ce qui doit rester inchangé : « Ne pas changer la forme de l’API », « Ne pas renommer les fonctions publiques », « Pas d’éditions de formatage seules », « Éviter les nouvelles dépendances ». Cela indique à votre pair où ne pas être ingénieux.

Quand le changement reste flou, demandez d’abord un plan avant le code. Un court plan force le travail en étapes et vous donne une chance d’approuver un petit premier pas.

Goal: Fix the null crash when rendering the profile header.
Location: src/components/ProfileHeader.tsx only.
Constraints: Do not change styling, props, or any exported types.
Expected outcome: If user.name is missing, show "Anonymous" and no crash.
Diff constraint: Minimal diff. No refactors. No unrelated formatting.
If unclear: First reply with a 3-step plan, then wait for approval.

Si vous travaillez en équipe, ajoutez aussi des contraintes de revue : « Gardez‑le sous ~30 lignes modifiées » ou « Un seul fichier sauf nécessité absolue. » Cela rend le diff plus facile à scanner et aiguise les prompts de suivi quand quelque chose échoue.

Choisissez la bonne unité de travail pour chaque itération

Gardez chaque boucle focalisée sur un petit changement testable. Si vous pouvez décrire l’objectif en une phrase et prédire quels fichiers vont changer, la taille est adéquate.

De bonnes unités de travail comprennent : corriger un bug sur un chemin précis (avec repro et garde‑fou), ajuster un seul test pour un comportement, faire un refactor préservant le comportement (renommer, extraire une fonction, supprimer une duplication), ou améliorer un message d’erreur ou une règle de validation.

Limitez le temps pour chaque boucle. Dix à vingt minutes suffisent généralement pour rédiger une invite claire, appliquer le diff et lancer une vérification rapide. Si vous explorez encore après 20 minutes, réduisez l’unité ou passez en mode investigation seulement (notes, logging, test échouant) et arrêtez‑vous là.

Définissez « terminé » avant de commencer :

• Le changement reste dans les fichiers et le comportement prévus.
• Une vérification prouve que ça marche (test, lint ou une simple étape d’exécution).
• Pas de nouveaux avertissements ou modifications de formatage bruyantes.
• Le diff est facile à expliquer en deux phrases.

Quand la portée commence à s’étendre, arrêtez‑vous tôt. Si vous vous surprenez à dire « tant qu’on y est », vous venez de trouver l’itération suivante. Capturez‑la comme suivi, committez le petit diff courant et continuez.

Relisez le diff avant de lancer les vérifications

Avant de lancer tests ou builds, lisez le diff comme le ferait un réviseur. C’est ici que le workflow reste propre ou dérive silencieusement vers « pourquoi ça a touché ce fichier ? ».

Commencez par demander à Claude Code un résumé en langage simple : fichiers touchés, changement de comportement, et ce qui n’a pas été modifié. S’il ne peut pas expliquer clairement, le diff fait probablement trop de choses.

Puis relisez vous‑même. Parcourez d’abord pour la portée, puis lisez pour l’intention. Vous recherchez la dérive : formatage non lié, refactors supplémentaires, symboles renommés ou modifications non demandées.

Un rapide pré‑contrôle :

• Les fichiers modifiés correspondent‑ils à ce que vous aviez demandé ?
• Y a‑t‑il des éditions « drive‑by » (churn d’espaces, refactors non liés) ?
• A‑t‑il introduit un nouveau comportement non demandé ?
• Y a‑t‑il une nouvelle dépendance ou un changement de config qui nécessite une vraie raison ?
• Un réviseur pourrait‑il comprendre cela sans lire cinq autres fichiers ?

Si le diff est plus gros que prévu, n’essayez pas de tester pour vous en sortir. Revertissez et re‑promptez pour un pas plus petit. Par exemple : « Ajoute seulement un test échouant qui reproduit le bug. Pas de refactors. » Les petits diffs rendent les échecs plus faciles à interpréter et le prompt suivant plus précis.

Lancez des vérifications après chaque petite modification

Les petits diffs ne payent que si vous les vérifiez immédiatement. L’objectif est une boucle serrée : changer un peu, vérifier un peu, attraper les erreurs tant que le contexte est frais.

Commencez par la vérification la plus rapide qui peut vous dire « c’est cassé ». Si vous avez changé du formatage ou des imports, lancez d’abord le lint ou le format. Si vous avez touché la logique métier, lancez les tests unitaires ciblés qui couvrent le fichier ou le paquet. Si vous avez modifié des types ou la config de build, lancez une compilation rapide.

Un ordre pratique :

• Lint ou format.
• Tests unitaires ciblés pour la zone modifiée.
• Build ou typecheck pour confirmer que tout tient.
• Suites plus lentes (intégration, end‑to‑end) après que le basique passe.

Quand quelque chose échoue, capturez deux choses avant de réparer quoi que ce soit : la commande exacte que vous avez lancée et la sortie d’erreur complète (copiez‑la telle quelle). Cet enregistrement rend la prochaine invite spécifique et évite les boucles « ça échoue toujours ».

Gardez la portée serrée. Si le lint échoue et que les tests échouent, corrigez d’abord le lint, relancez, puis traitez les tests. Ne mêlez pas « nettoyages rapides » et correction de crash dans la même passe.

Re‑promptez avec les échecs jusqu’à ce que les vérifications passent

Quand les vérifications échouent, traitez la sortie d’erreur comme votre prochaine invite. La boucle la plus rapide est : coller l’erreur, obtenir un diagnostic, appliquer une correction minimale, relancer.

Collez les échecs mot pour mot, y compris la commande et la stack trace complète. Demandez d’abord la cause la plus probable, pas un menu d’options. Claude Code travaille mieux lorsqu’il peut s’ancrer sur des numéros de ligne et des messages exacts plutôt que de deviner.

Ajoutez une phrase sur ce que vous avez déjà essayé pour éviter les retours en boucle. Répétez les contraintes importantes ("Ne pas changer les APIs publiques", "Conserver le comportement actuel, juste corriger le crash"). Puis demandez le patch le plus petit qui fait passer la vérification.

Une bonne invite d’échec inclut :

• La sortie d’échec exacte (verbatim).
• Le(s) fichier(s) et lignes impliqués.
• Ce que vous avez changé dans le dernier diff.
• Ce que vous avez déjà essayé.
• Une demande pour le plus petit patch qui fait passer la vérification.

Si le correctif proposé change le comportement, demandez un test qui prouve que le nouveau comportement est correct. Si un handler renvoie maintenant 400 au lieu de 500, demandez un test ciblé qui échoue sur l’ancien code et passe avec le correctif. Cela rend le travail honnête et le PR plus fiable.

Arrêtez‑vous une fois que les vérifications sont vertes et que le diff reste centré sur une idée. Si le modèle commence à améliorer du code sans lien, re‑promptez avec : « N’adressez que le test échouant. Pas de nettoyage. »

Rendez le PR facile à relire et à merger

Un PR se merge plus vite quand il est évident ce qui a changé, pourquoi et comment le vérifier. Avec ce workflow, le PR doit se lire comme une courte histoire : petites étapes, raisons claires.

Alignez les commits sur vos itérations. Si vous avez demandé un changement de comportement, faites‑en un commit. Si vous avez ensuite corrigé un test qui échouait, faites‑en le commit suivant. Les réviseurs peuvent suivre le cheminement et faire confiance au fait que vous n’avez pas glissé d’autres changements.

Rédigez des messages de commit pour l’intention, pas pour les noms de fichiers. « Corrige la redirection de connexion quand la session expire » vaut mieux que « Mise à jour du middleware auth. » Quand le message nomme l’effet côté utilisateur, les réviseurs passent moins de temps à deviner.

Évitez de mélanger refactors et changements de comportement dans le même commit. Si vous voulez renommer des variables ou déplacer des helpers, faites‑le séparément (ou laissez‑le pour plus tard). Le bruit ralentit la revue.

Dans la description du PR, restez court et concret :

• Ce qui a changé (1–2 phrases).
• Pourquoi cela a changé (le bug ou l’exigence).
• Comment tester (étapes exactes, y compris flags ou données nécessaires).
• Ce que vous n’avez pas changé (pour fixer les attentes).
• Tout risque ou note de rollback.

Exemple : une page de facturation qui plantait à cause d’un enregistrement client null. Commit 1 ajoute une garde et un état d’erreur clair. Commit 2 ajoute un test pour le cas null. La description du PR dit : « Ouvrir Billing, charger un client sans profil, confirmer que la page affiche le nouvel état vide. » C’est le type de PR que les réviseurs peuvent approuver rapidement.

Pièges courants qui vous ralentissent

Ce rythme se casse quand la portée s’étend silencieusement. Une invite qui commence par « corriger ce test échouant » devient « améliorer la gestion d’erreur sur tout le module », et tout à coup vous révisez un gros diff avec une intention floue. Gardez‑le serré : un objectif, un ensemble de modifications, un ensemble de vérifications.

Un autre ralentissement est d’accepter des refactors « plus jolis » juste parce qu’ils ont l’air bien. Renommages, déplacements de fichiers et changements de style créent du bruit dans la revue et rendent plus difficile d’identifier le vrai changement comportemental.

Pièges courants :

• Laisser le modèle toucher des fichiers non liés « tant qu’il y est ».
• Traiter les symptômes (checks null supplémentaires) plutôt que la cause racine indiquée par le test.
• Coller seulement les dernières lignes des logs et cacher l’erreur initiale.
• Sauter un scan rapide du diff avant de lancer les vérifications.
• Re‑prompter avec « ça échoue toujours » sans la commande et la sortie exactes.

Un exemple concret : un test échoue avec « expected 400, got 500. » Si vous ne collez que la fin de la stack trace, vous obtenez souvent des suggestions génériques try/catch. Si vous collez la sortie complète du test, vous pouvez voir le vrai problème : une branche de validation manquante. Cela mène à un diff petit et ciblé.

Avant de commit, lisez le diff comme un réviseur. Demandez‑vous : chaque ligne sert‑elle la demande, et puis‑je l’expliquer en une phrase ? Sinon, revertissez les changements en trop et re‑promptez avec une demande plus étroite.

Exemple : correction de bug jusqu’à PR mergeable en quelques boucles

Un utilisateur rapporte : « La page de paramètres revient parfois aux valeurs par défaut après enregistrement. » Vous pull main, lancez les tests et voyez une erreur. Ou il n’y a pas de tests, juste un repro clair.

Traitez‑le comme une boucle : une petite demande, un petit diff, puis des vérifications.

D’abord, donnez à Claude Code le plus petit contexte utile : sortie du test échouant (ou étapes de repro), le chemin de fichier suspecté et l’objectif ("conserver le comportement sauf corriger le reset"). Demandez un diagnostic et un patch minimal, pas un refactor.

Ensuite, travaillez en boucles courtes :

1. Boucle 1 (patch minimal) : Appliquez le plus petit changement plausible pour corriger le bug. Restez précis : une condition de garde, une check null manquante, une valeur par défaut erronée ou une liste de dépendances incorrecte.

Lancez les vérifications après revue du diff.

2. Boucle 2 (retour avec l’échec exact) : Si des tests échouent, copiez la sortie d’erreur exacte dans Claude Code. Incluez le nom de fichier, le numéro de ligne et le message d’assertion. Demandez : « Quel est le plus petit changement pour corriger cet échec sans élargir la portée ? »

Si les vérifications passent mais que vous craignez des régressions, ajoutez de la couverture.

3. Boucle 3 (ajustement ou nouveau test) : Ajoutez un test qui échoue sans le patch et passe avec lui. Concentrez‑le sur le bug. Relancez les vérifications.

Terminez avec une petite description de PR : quel était le bug, pourquoi il se produisait et ce qui a changé. Ajoutez une note pour le réviseur comme « touche seulement le fichier X » ou « ajoute un test pour le cas reset » afin que la revue soit rassurante.

Checklist rapide avant d’ouvrir le PR

Juste avant d’ouvrir la pull request, faites une dernière passe pour vous assurer que le travail est facile à relire et sûr à merger.

• Le diff correspond à l’objectif initial et est assez petit pour être compris en quelques minutes.
• Vous avez lancé les vérifications pertinentes (tests, lint, typecheck, build) et elles passent. Si votre équipe utilise la CI, confirmez que le même ensemble s’y exécutera.
• Le changement a un filet de sécurité approprié : un test pour le bug ou la fonctionnalité quand c’est raisonnable, ou une raison claire pour laquelle aucun test n’est nécessaire.
• La description du PR est spécifique : ce qui a changé, pourquoi, et les étapes exactes pour vérifier.
• Il n’y a pas d’éditions parasites : formatage non lié, renommages stylistiques ou refactors non requis.

Un exemple rapide : si vous avez corrigé un bug de connexion mais aussi reformaté 20 fichiers, annulez le commit de formatage. Votre réviseur doit se concentrer sur la correction de connexion, pas se demander ce qui a bougé d’autre.

Si un point échoue, faites encore une petite boucle : un tiny diff, relancez les vérifications et mettez à jour les notes du PR. Cette dernière boucle sauve souvent des heures d’allers‑retours.

Prochaines étapes : faites de ce rythme une habitude

La constance transforme une bonne session en un workflow fiable. Choisissez une boucle par défaut et appliquez‑la de la même façon à chaque fois. Après une semaine, vos invites seront plus courtes et vos diffs plus simples à relire.

Une routine simple :

• Choisissez un tout petit résultat (un bug, un cas limite, une fonction).
• Demandez un petit diff et une brève explication de ce qui a changé.
• Lisez le diff comme un réviseur, puis lancez les vérifications localement.
• Re‑promptez avec la sortie d’erreur exacte et les noms de fichiers.
• Arrêtez dès que les vérifications sont vertes et que le changement est clair.

Un template personnel d’invite vous aide à rester discipliné : « Change seulement ce qui est nécessaire. Toucher au plus 2 fichiers. Conserver le comportement public sauf indication contraire. Dites‑moi la commande à lancer et ce à quoi ressemble le succès. »

Si vous construisez dans Koder.ai, vous pouvez appliquer la même boucle dans son interface chat. Le mode planning est utile pour cadrer la plus petite tranche mergeable (entrées, sorties et critères d’acceptation), et les instantanés et rollback vous aident à récupérer vite quand une expérience dérape.

Une fois le changement stable, exportez le code source pour lancer vos outils locaux habituels, la CI et la revue des coéquipiers dans votre repo habituel. Déployez quand vous avez besoin d’une validation en conditions réelles, par exemple pour vérifier un flux de bout en bout.

Faites de la boucle votre valeur par défaut. Petites invites, petits diffs, vérifications fréquentes et corrections rapides aboutissent à des PRs qui paraissent ennuyeux, dans le bon sens du terme.