Écrire un prompt de revue de code : six règles et un template

Pourquoi la plupart des prompts de revue font du bruit

La plupart des prompts de revue de code sont une liste de sujets : « Examiner ce code ; regarder les bugs, les failles de sécurité, les performances et la lisibilité. » Le modèle prend la liste au pied de la lettre et écrit quelque chose sous chaque rubrique. Le résultat est un commentaire long, poli et en grande partie inutile. L’auteur de la pull request le lit en entier pour en jeter la plus grande partie, ou ne le lit pas du tout.

Ce qui change vraiment la sortie, c’est l’exigence de preuve : le modèle écrit ce qu’il peut montrer, et se tait sur ce qu’il ne peut pas montrer. Chez diffox, quand nous répartissons une pull request entre 17 agents spécialisés, les instructions de chaque agent commencent par la même exigence (son fonctionnement fait l’objet d’un article à part). Les six règles ci-dessous viennent de cette expérience et de la documentation des outils eux-mêmes.

Les six règles

1. Exigez une preuve. Chaque constat doit s’appuyer sur une entrée ou une situation concrète qui produit le mauvais résultat : « Si la liste est vide, le calcul de la moyenne divise par zéro. » Un modèle qui ne peut pas construire un tel scénario doit se taire. Cette seule phrase élimine la plupart des commentaires du genre « on pourrait aussi faire attention à ceci ».
2. Demandez une citation exacte, pas un numéro de ligne. Les modèles ne comptent pas les lignes de façon fiable ; une citation, elle, se cherche et se retrouve dans le fichier. La documentation d’Anthropic recommande la même technique : si le modèle ne trouve pas de citation qui appuie son affirmation, il doit la retirer (source).
3. Limitez le périmètre à ce changement. La review porte sur les problèmes que causent les lignes ajoutées ou modifiées par la pull request. Si vous reprochez à l’auteur d’aujourd’hui chaque défaut de l’ancien code, plus personne ne lit le commentaire.
4. Laissez de côté les questions de goût et ce que vos outils vérifient déjà. La mise en forme, une préférence de nommage, un commentaire manquant ne sont pas des constats de review ; ne faites pas réécrire au modèle ce que le linter et le vérificateur de types signalent déjà. La documentation de Codex dit la même chose : laissez les vérifications de format et de lint à la CI.
5. Définissez la gravité. Écrivez vous-même ce que veulent dire « bloquant » et « mineur » : un résultat faux, une perte de données, une faille de sécurité sont bloquants ; ce qui n’apparaît que sur un chemin rare ou se réduit à un nom trompeur est mineur. Sans définition, chaque constat ressort comme « important ».
6. Fixez le format de la sortie. Chaque constat comporte les mêmes champs : fichier, citation, scénario, résultat faux, gravité, correction en une ligne. S’il n’y a aucun constat, le modèle le dit en une ligne et s’arrête, au lieu de meubler une review vide.

Les six règles ont un point commun : chacune décrit une vérification que le modèle peut faire. « Être prudent » ne se vérifie pas ; « la citation est-elle dans le fichier ? » se vérifie.

Copiez ce template et adaptez-le à votre dépôt

Le prompt ci-dessous réunit les six règles en un seul texte. Il est écrit en anglais, car les quatre outils suivent sans peine des instructions en anglais ; c’est la dernière ligne qui fixe la langue des commentaires. Il y a deux endroits à modifier : la définition de la gravité et la liste « Do not report ».

You are reviewing a pull request. Report only defects that this
change introduces or exposes.

A finding is valid only if you can state all three:
1. the code, quoted word for word from the changed lines;
2. a concrete input or state that reaches that code;
3. the wrong result that follows, and what the right one would be.
If you cannot state all three, do not report it.

Do not report: style, formatting, naming taste, missing comments,
anything a linter or a type checker already reports, or code this
change did not touch.

Severity:
- blocking: wrong result, data loss, security hole, or a crash on
  an ordinary path
- minor: wrong only on a rare path, or a name, comment or test that
  says something the code does not do

For each finding give: file, the quoted code, the scenario, the
wrong result, severity, and a one-line fix.
If you find nothing, write "No findings" and stop.
Write the findings in French.

Le template est volontairement court. La documentation de Claude Code dit que la longueur a un prix : un long fichier d’instructions dilue les règles qui comptent le plus. Quand vous ajoutez vos propres règles, vérifiez que chaque nouvelle ligne change bien un constat.

Quel fichier chaque outil lit-il ?

L’endroit où écrire le prompt dépend de l’outil. Le tableau ci-dessous vient de la documentation de chacun des quatre outils, lue le 15 octobre 2026.

Source : la documentation de chaque outil, 15 octobre 2026.

Deux détails passent souvent inaperçus. Dans Claude Code, seule la Code Review sur GitHub lit REVIEW.md ; la commande /code-review du terminal ne le lit pas. Copilot, lui, lit les instructions sur la branche head de la pull request, celle qui porte les changements : une pull request qui modifie le fichier d’instructions change aussi les règles de sa propre review.

Pour faire de votre propre prompt une commande dans Claude Code, écrivez un skill : placez le template dans .claude/skills/revue/SKILL.md et ajoutez en tête la ligne !`git diff main...HEAD`. Cette ligne exécute la commande et insère sa sortie dans le prompt ; quand vous tapez /revue, le modèle trouve le diff déjà prêt (documentation des skills).

Écrire les règles propres à votre dépôt

Le template couvre la partie générale ; la vraie valeur est dans les règles de votre dépôt. Ce sont les choses que vous répétez à chaque review : quelle donnée ne doit pas franchir quelle couche, quel effet de bord est dangereux, quel contrat ne doit pas être rompu.

Une bonne règle a trois parties, et la documentation de Codex les énumère toutes : le comportement à signaler, pourquoi il compte, et la voie sûre ou l’exception. La troisième est la plus souvent oubliée : si vous ne dites pas au modèle quelle est la bonne voie, il signale aussi le comportement attendu comme une erreur.

• Trop vague : « Faire attention aux requêtes à la base de données. »
• Solide : « Chaque requête doit être limitée au tenant de l’appelant. Voie sûre : la fonction utilitaire scoped(). Exception : les rapports d’administration. »

Vous pouvez aussi poser l’exigence de preuve au niveau du dépôt. L’exemple de la documentation de Claude Code : une affirmation sur un comportement doit montrer un fichier et une ligne dans le code source, et non une déduction tirée d’un nom. Cette seule règle réduit les fausses alertes qui font perdre un aller-retour à l’auteur.

Quand un seul prompt ne suffit pas

Si vous demandez à un seul prompt de couvrir à la fois la sécurité, la concurrence, les tests et le respect des règles, le modèle disperse son attention et trouve un peu de chaque. Sur les gros changements, ce qui marche, c’est de découper le travail : chaque prompt cherche une seule chose et respecte la même exigence de preuve.

Deuxième étape : contrôler ce que dit le modèle. Un modèle peut paraître convaincant et se tromper quand même : il cite une ligne qui n’est pas dans le fichier, ou conteste du code que le changement n’a pas touché. Comme vous demandez une citation, un programme peut le vérifier : la citation est-elle vraiment dans ce fichier, appartient-elle aux lignes modifiées ? La documentation de la Code Review de Claude Code décrit le même schéma : chaque agent cherche une classe de problèmes différente, puis une étape de vérification écarte les fausses alertes.

diffox fait lui-même ces deux étapes : chacun de ses 17 agents spécialisés cherche une seule chose et montre ce qu’il a trouvé par une citation exacte du code ; la citation est vérifiée par du code, pas par un modèle. Les phrases qui expriment une obligation dans le fichier de règles à la racine de votre dépôt (AGENTS.md ou CLAUDE.md) sont aussi transmises aux agents comme règles de review.

Testez la règle sur une vraie pull request

On ne sait pas si un prompt est bon en le lisant. Le conseil de la documentation de Codex est le plus pratique : ouvrez une pull request représentative, demandez une review, corrigez les règles d’après les constats reçus, et resserrez ou supprimez l’instruction qui produit du bruit.

• Testez la règle sur un changement qui contient une violation qu’elle doit détecter : la détecte-t-elle ?
• Testez-la sur un changement qui suit la voie sûre : se tait-elle ?
• Testez-la sur un changement sans rapport avec le sujet : se tait-elle encore ?

Si vous faites examiner deux fois la même pull request, vous pouvez obtenir deux résultats différents ; ne prenez pas un seul essai pour un résultat. Comparez les résultats avant et après l’ajout d’une règle, sur quelques pull requests, toujours les mêmes.