Que fait review ?
Jugez une modification sur deux axes distincts, a-t-elle construit la bonne chose (spec) et est-elle bien construite (qualité), avec des yeux neufs, des conclusions étayées par des preuves, et une sévérité graduée en fonction de ce qu'un utilisateur réel rencontrerait. Agissez ensuite sur les constatations avec rigueur technique, sans déférence.
Principe fondamental : Approuvez une modification lorsqu'elle améliore définitivement la santé de la base de code et fait ce qui était demandé, même si ce n'est pas comme vous l'auriez écrite. N'approuvez jamais une modification que vous n'avez pas réellement lue et vérifiée.
Position dans le pipeline : spécifications → plan → construction (+ test) → revue → fusion.
Étape 1 : Délimiter le périmètre
- L'utilisateur nomme le périmètre (PR, branche, plage de commits, fichiers). Sinon : la branche courante par rapport à sa base de fusion avec la branche par défaut, plus les modifications non commitées.
- Résolvez le point fixe et confirmez que le périmètre n'est pas vide avant de faire quoi que ce soit d'autre :
git rev-parse <ref>,git log <ref>..HEAD --oneline,git diff <ref>...HEAD --statpour le travail commité, etgit diff --cached --stat(staged),git diff --stat(unstaged) etgit status --short(untracked) pour les modifications non commitées. Examinez l'union des deux, et lorsque des modifications non commitées sont dans le périmètre, informez-en chaque réviseur (l'invite de réviseur contient une ligne pour cela). Une référence erronée ou un périmètre vide sur les deux plans échoue ici. - Pour une PR, lisez sa description et les issues liées.
Étape 2 : Rassembler l'intention
Trouvez, dans l'ordre : la spécification et le plan que la modification implémente (specs/<slug>/, liens dans les commits/PR, un chemin donné par l'utilisateur), les lignes Ruling: du registre de construction, et l'issue qu'elle ferme. Reformulez l'intention en deux ou trois phrases. S'il n'y a pas de spécification, dites-le : l'axe de spécification juge alors par rapport à la description de la PR et aux attentes raisonnables d'un utilisateur.
Trouvez également les standards : CONTRIBUTING.md, CODING_STANDARDS.md, CLAUDE.md/AGENTS.md, configurations de lint, ADRs, le glossaire.
Vérification de la taille. Environ 100 lignes modifiées est idéal, environ 300 est acceptable pour un seul changement logique, environ 1000 est trop grand pour être bien revu : recommandez une scission (par pile, par groupe de fichiers, ou par tranches verticales) comme constatation. Le refactoring mélangé à du travail fonctionnel correspond à deux changements.
Étape 3 : Réviser avec un contexte frais
L'auteur est aveugle à ses propres hypothèses, tout comme la session qui a écrit le code. Lorsqu'un outil de sous-agent est disponible, dépêchez des réviseurs avec un contexte frais en utilisant reviewer-prompt.md : donnez-leur le diff (en tant que fichier ou commande exacte), les chemins des spécifications/plans, les fichiers de standards et les décisions du registre. Jamais votre historique de session. Les réviseurs sont en lecture seule et ne génèrent pas leurs propres réviseurs.
Exécutez en parallèle, afin qu'un axe ne puisse pas en masquer un autre :
- Réviseur de spécification : manquant, superflu, mal compris.
- Réviseur de qualité : exactitude, tests, conception, sécurité, performance.
- (Optionnel, pour les modifications risquées ou étendues) Réviseur de rayon d'impact : ce que cela casse là où grep ne le montrera pas.
Utilisez le modèle le plus performant disponible pour une revue complète de branche. Sans outil de sous-agent, effectuez vous-même chaque axe en un passage séparé, et étiquetez le résultat comme une auto-revue : plus faible qu'un réviseur frais, et l'utilisateur décide si cela suffit.
Revoir votre propre branche que vous venez de terminer en ligne n'est pas un substitut pour cette étape.
L'axe de spécification
Comparez le diff à ce qui a été demandé :
- Manquant : exigences ou critères de réussite ignorés, partiels, ou revendiqués mais non implémentés. Citez la ligne de la spécification.
- Superflu : comportement que personne n'a demandé, options spéculatives, hooks ou abstractions (dérapage de périmètre, YAGNI).
- Mal compris : bonne fonctionnalité construite de la mauvaise manière, ou mauvais problème résolu.
- Non vérifiable à partir du diff : exigences qui résident dans du code non modifié ou qui s'étendent sur plusieurs changements. Listez ce qu'il faut vérifier plutôt que de deviner.
La spécification est un document de vision, pas une liste exhaustive. Là où elle est silencieuse, l'attente raisonnable d'un utilisateur est l'exigence. Le silence sur une entrée n'est pas une permission pour qu'elle plante.
L'axe de qualité
Lisez d'abord les tests : ils révèlent l'intention et la couverture.
Tests
- Chaque nouveau comportement a-t-il un test qui échouerait si le comportement était cassé ? Répondez par l'expérience lorsque vous le pouvez : inversez une condition que la modification ajoute et exécutez la suite, dans un répertoire de travail ou une copie jetables afin que le checkout révisé ne change jamais. Une mutation qui reste verte est une constatation : nommez le test manquant.
- Comportement à travers des coutures publiques, pas des internes ; pas d'assertions sur des mocks ; pas de valeurs attendues calculées par le code testé ; mocks uniquement aux frontières du système.
- Les corrections de bogues ont un test de régression. Rien n'est ignoré ou désactivé. Sortie de test propre.
Exactitude
- Correspond à la spécification ; cas limites (null, vide, zéro, max, unicode, concurrent) ; chemins d'erreur, pas seulement le chemin heureux ; off-by-one, courses, état qui peut se désynchroniser.
Lisibilité et simplicité
- Les noms disent ce que les choses sont et font. Le flux de contrôle est simple. Cela pourrait-il être en moins de lignes ? Chaque abstraction mérite-t-elle sa place (ne généralisez pas avant la troisième utilisation) ?
- Code mort, variables sans effet, commentaires
// removed, shims de compatibilité dont personne n'a besoin. - Les commentaires expliquent pourquoi, pas quoi. Un commentaire qui raconte un contournement marque souvent une cause racine non corrigée.
Conception
- S'intègre dans les modèles existants ; un nouveau modèle nécessite une raison.
- Un refactoring réduit-il les concepts qu'un lecteur doit retenir, ou seulement les déplace-t-il ? Préférez la version où les branches, les modes ou les couches disparaissent.
- Logique fonctionnelle qui fuit dans un module partagé ; quasi-duplication d'un helper existant ; conditionnel ajouté à un flux non lié ; switchs répétés sur la même forme (modèle ou répartiteur manquant) ; un deuxième booléen qui doit rester synchronisé avec le premier (machine à états manquante).
- Wrappers à un seul appelant et couches de passage (intégrez-les). État mutable plus large que nécessaire.
- Validation aux frontières, confiance à l'intérieur. Pas de replis silencieux qui masquent un invariant flou ; pas de
any/casts gratuits. - Croissance des fichiers : une modification qui pousse un fichier bien au-delà d'une taille saine devrait d'abord décomposer.
Sécurité
- Entrée non fiable (HTTP, CLI, fichiers, env, sortie LLM, réponses tierces) validée à la frontière. Requêtes paramétrées. Sortie encodée. Authentification/autorisation vérifiée là où nécessaire. Secrets hors du code, des logs et du VCS. Nouvelles dépendances justifiées, maintenues, avec des licences compatibles ; diff du fichier de verrouillage examiné.
Performance
- Requêtes N+1, boucles ou fetches non bornés, pagination manquante, travail synchrone qui bloque, allocations importantes dans les chemins chauds, rendus inutiles. Quantifiez lorsque vous le pouvez (« ~50ms par ligne à 1k lignes »).
Baseline d'odeurs de code (jugements ; les standards documentés du dépôt prévalent) : Mysterious Name, Duplicated Code, Feature Envy, Data Clumps, Primitive Obsession, Repeated Switches, Shotgun Surgery, Divergent Change, Speculative Generality, Message Chains, Middle Man.
L'axe de rayon d'impact (modifications risquées ou étendues)
Lister les appelants n'est pas le travail ; grep fait cela en une seconde. Le travail est la casse que grep ne montrera pas :
- Trouvez le seul fait pour lequel la modification est sûre (« cet appel ne supprime que les entrées déjà mortes »). Prouvez-le en exécutant du code : un script qui importe la bibliothèque réelle à la version épinglée et appelle la fonction exacte en question.
- Regardez là où la recherche de symboles s'arrête : code source de la bibliothèque et correctifs locaux, timing d'exécution (ordre asynchrone, démontage), formats sérialisés (formes JSON, colonnes DB, protocoles filaires, autres langages lisant les mêmes octets), indicateurs de fonctionnalité, consommateurs à trois sauts de distance.
- Pour chaque risque : comment il casse,
file:line, probabilité, coût, et la vérification la moins chère. Listez les risques vérifiés et écartés séparément.
Étape 4 : Vérifier chaque constatation
Une constatation qui semble correcte n'est pas une constatation tant qu'elle n'est pas vérifiée.
- Vérifiez-la par rapport aux appelants, gardes et tests qui atteignent le code. Écartez-la s'ils la disqualifient.
- Prouvez les importantes : un test échouant, un script de reproduction, ou une sortie de commande montrant le mauvais comportement. Préférez les constatations prouvées par une exécution à celles plausibles.
- Étiquetez les défauts préexistants séparément des régressions introduites par cette modification.
- Fusionnez les constatations qui partagent une cause racine.
- Zéro constatation est un résultat valide. N'en inventez pas une pour avoir l'air minutieux.
Le seuil pour bloquer une fusion
Une constatation peut être Critique ou Importante, et donc bloquer la fusion, uniquement lorsqu'elle est établie par des preuves :
- une exécution (test, script ou commande) qui montre le mauvais comportement, ou
- une entrée concrète tracée pas à pas à travers le code jusqu'à une sortie erronée, avec
file:lineà chaque étape.
Une préoccupation plausible que vous n'avez pas pu établir de cette manière (« cela pourrait casser X », « les cas limites peuvent ne pas être gérés ») est classée Mineure et étiquetée non vérifiée. Elle ne bloque pas. Listez-la pour que l'auteur puisse la vérifier.
Étape 5 : Classer et rapporter
Classez par effet sur une personne raisonnable utilisant le logiciel s'il est livré, pas par le fait que la spécification mentionne le déclencheur.
| Sévérité | Signification | Action requise |
|---|---|---|
| Critique | Trou de sécurité, perte de données, fonctionnalité principale cassée | Bloque la fusion |
| Important | Comportement erroné ou fragile, exigence manquante, comportement non testé, erreurs avalées, duplication ou conception nuisible | Corriger avant fusion |
| Mineur | Polissage, petites simplifications, couverture plus large | À la discrétion de l'auteur ; enregistrer si reporté |
| Nit | Préférence de style | Optionnel |
| INFO | Contexte, aucune action | Aucune |
Menez par l'effet de levier : exactitude et sécurité d'abord, puis problèmes structurels et simplifications manquées, puis le reste. S'il y a un problème structurel et dix nits, le problème structurel est la revue. Proposez le mouvement, pas seulement le problème : « remplacez cette cascade de if par une recherche indexée par kind », « intégrez ce wrapper à un seul appelant », « réutilisez formatDate depuis utils/date.ts ».
Soyez honnête : pas de « LGTM » de complaisance, n'adoucissez pas un vrai bogue en « pourrait être une préoccupation mineure », n'enfléz pas les nits en Critique. Reconnaissez ce qui est bien fait, spécifiquement.
Utilisez le format dans reviewer-prompt.md : verdict de spécification, forces, problèmes par sévérité (chacun avec file:line, ce qui ne va pas, pourquoi c'est important, comment corriger, preuves), notes de rayon d'impact, décliné de juger (comportements considérés et écartés, avec pourquoi), et un verdict : Approuver, Approuver avec corrections, ou Demander des modifications. Gardez les sections de spécification et de qualité séparées ; ne re-classez pas entre elles.
Règle de verdict : demandez des modifications uniquement lorsqu'au moins une constatation Critique ou Importante satisfait au seuil de preuve ci-dessus. Une modification qui fait ce qui a été demandé et qui n'a que des préoccupations Mineures ou non vérifiées est approuvée, avec ces préoccupations listées. Rejeter une modification correcte coûte autant à l'auteur qu'approuver une modification cassée.
Étape 6 : Agir sur les constatations (lorsque vous êtes l'auteur)
Les retours de revue sont des entrées à évaluer, pas des ordres à exécuter.
- Lisez tout avant de réagir. Si un élément n'est pas clair, demandez à ce sujet avant d'implémenter quoi que ce soit : les éléments sont souvent liés.
- Reformulez chaque élément comme une exigence technique, et vérifiez-le par rapport au code. Est-il correct pour cette base de code ? Casse-t-il quelque chose ? Y avait-il une raison pour le code actuel ? Le réviseur a-t-il tout le contexte ?
- Répondez avec des preuves lorsqu'il a tort : un test, un
file:line, une mesure. Si une suggestion ajoute une fonctionnalité « appropriée » mais inutilisée, vérifiez l'utilisation ; YAGNI s'applique aussi aux réviseurs. Escaladez à l'utilisateur tout ce qui entre en conflit avec ses décisions antérieures. - Corrigez dans l'ordre : Critique/bloquant → simple → complexe. Chaque correction est précédée d'un test échouant qui reproduit la constatation (via
test), puis la correction, puis une suite complète au vert. Une passe de correction concentrée, pas une boucle infinie. - Les Mineures que vous ne corrigez pas vont dans une liste « Reporté » dans votre message final. Une constatation que vous décidez de ne pas corriger est une décision enregistrée avec une raison.
- Pas d'accord performatif. Pas de « Vous avez tout à fait raison ! », « Bien vu ! », ou de remerciements. Dites ce que vous avez changé (« Corrigé : les lignes vides émettent maintenant un CSV avec en-têtes seuls ; test
exports header for empty view») ou pourquoi le code reste. Si vous avez répondu et aviez tort, dites-le en une ligne et corrigez.
Sur GitHub, répondez dans le fil de commentaire en ligne, pas en tant que commentaire de niveau supérieur.
Avant fusion (Définition de fait)
- Chaque critère de succès de la spécification est atteint et vérifié dans le système en cours d'exécution
- Le nouveau comportement a des tests qui échouent sans la modification ; suite complète au vert, sortie propre
- Aucune constatation Critique ou Importante ouverte ; reports enregistrés avec raisons
- Pas de code mort, sortie de débogage, ou blocs commentés ; modifications limitées à la tâche
- Lint, vérification de type, construction passent
- Migrations, configuration et indicateurs pris en compte ; chemin de retour existe pour les modifications risquées
- Interfaces publiques et comportement visible par l'utilisateur documentés ; ADR pour les décisions difficiles à inverser
- Messages de commit et description de PR disent ce qui a changé et pourquoi, en termes autonomes
- L'humain a approuvé là où le projet l'exige
Rationalisations courantes
| Pensée | Réalité |
|---|---|
| « Les tests passent, donc c'est bon » | Les tests n'attrapent pas une mauvaise conception, les trous de sécurité ou une spécification mal lue. |
| « Je l'ai écrit, je sais que c'est correct » | Même auteur, mêmes angles morts. Obtenez des yeux neufs. |
| « Le code généré par IA est probablement correct » | Il est confiant et plausible lorsqu'il est erroné. Il nécessite plus de contrôle, pas moins. |
| « Le refactoring est plus propre » | Si le lecteur retient le même nombre de concepts, il a seulement déplacé. |
| « Nous nettoierons plus tard » | Plus tard vient rarement. Corrigez maintenant ou enregistrez explicitement. |
| « La spécification n'a pas mentionné cette entrée » | Le silence n'est pas une permission. Classez par ce que l'utilisateur obtient. |
| « Le réviseur a dit Mineur, donc c'est Mineur » | Re-classez par effet. |
| « La correction est évidente, pas besoin de test » | Le test échouant est la seule preuve que la constatation était réelle et est maintenant partie. |
| « Le réviseur a probablement raison » | Vérifiez par rapport au code d'abord. |
Drapeaux rouges
- « LGTM » sans preuve de lecture
- Constatations sans
file:line, ou affirmées sans vérifier les appelants et gardes - Constatations de spécification et de qualité fusionnées en une seule liste classée
- Nits enterrées au-dessus d'un bogue d'exactitude
- Un réviseur qui a reçu l'historique de session de l'auteur
- Correction de constatations de revue sans test échouant d'abord
- Implémentation de certains éléments de feedback pendant que d'autres sont encore...