Relecture PR avec Claude Code : pré-vérifier les diffs plus vite et en toute sécurité

Pourquoi la relecture des PR prend tant de temps

Les revues de PR ne s'éternisent pas forcément parce que le code est « difficile ». Elles durent parce que le relecteur doit reconstituer l'intention, le risque et l'impact à partir d'un diff qui montre des changements, pas toute l'histoire.

Une petite modification peut toucher des dépendances cachées : renommer un champ et un rapport casse, changer une valeur par défaut et le comportement évolue, ajuster une condition et la gestion d'erreur change. Le temps de relecture augmente quand le relecteur doit cliquer partout pour avoir du contexte, lancer l'application en local et poser des questions de suivi juste pour comprendre ce que la PR est censée faire.

Il y a aussi un problème de comportements humains. Les gens parcourent les diffs de façon prévisible : on se concentre sur le changement « principal » et on manque les lignes ennuyeuses où se cachent des bugs (vérifications de bornes, gestion des nulls, logging, nettoyage). On a aussi tendance à lire ce qu'on s'attend à voir, donc les copier-coller ratés et les conditions inversées peuvent passer inaperçus.

Une bonne pré-relecture n'est pas un verdict. C'est une seconde paire d'yeux rapide et structurée qui indique où l'humain doit ralentir. Le meilleur rendu est :

• un résumé en langage clair de ce qui a changé
• des points de risque spécifiques (fichiers, fonctions, hypothèses)
• des remarques de lisibilité (noms, flux de contrôle confus)
• des inquiétudes de correction (logique, gestion d'erreur, cohérence des données)
• des cas limites qui méritent un test (entrées, timing, permissions, états vides)

Ce qu'elle ne doit pas faire : « approuver » la PR, inventer des exigences ou deviner le comportement d'exécution sans preuve. Si le diff n'inclut pas assez de contexte (entrées attendues, contraintes, contrats d'appelant), la pré-relecture doit le signaler et lister exactement ce qui manque.

L'aide par IA est la plus forte sur des PR de taille moyenne qui touchent la logique métier ou des refactorings où le sens peut se perdre. Elle est moins efficace quand la bonne réponse dépend d'une connaissance organisationnelle profonde (comportement legacy, particularités de performance en production, règles internes de sécurité).

Exemple : une PR qui « met à jour la pagination » cache souvent des décalages d'une page, des résultats vides et un tri décalé entre l'API et l'UI. Une pré-relecture doit faire émerger ces questions avant qu'un humain ne perde 30 minutes à les redécouvrir.

Que demander à Claude pour une pré-relecture

Traitez Claude comme une première passe rapide et pointilleuse, pas comme celui qui décide si la PR part en production. Le but est de faire remonter tôt : code confus, changements de comportement cachés, tests manquants et cas limites qu'on oublie quand on est proche du changement.

Donnez-lui ce dont un relecteur humain équitable aurait besoin :

• l'objectif de la PR (1 à 3 phrases)
• ce qui ne doit pas casser (forme de l'API, compatibilité arrière, budget de performance, règles de sécurité)
• toutes contraintes ou compromis spéciaux (délais, déploiement progressif)
• les diff hunks pertinents, avec assez de code autour pour comprendre l'intention

Si la PR touche une zone à haut risque connue, dites-le d'emblée (auth, facturation, migrations, concurrence).

Puis demandez des sorties actionnables. Une bonne requête ressemble à :

• Résumez ce qui a changé en langage clair.
• Signalez les problèmes de lisibilité (noms, structure, surprises, motifs incohérents).
• Identifiez les risques de correction (gestion des nulls, chemins d'erreur, off-by-one, incompatibilités de forme de données).
• Listez les cas limites et modes de défaillance (timeouts, retries, entrées vides, mises à jour partielles).
• Suggérez des tests manquants et ce que chaque test prouve.
• Produisez une courte checklist pour le relecteur et 5 à 10 « questions à poser » avant le merge.

Gardez l'humain aux commandes en forçant la clarté sur l'incertitude. Demandez à Claude d'étiqueter les constats par « certain d'après le diff » vs « nécessite confirmation », et de citer les lignes exactes qui ont déclenché chaque inquiétude.

Préparez le diff et le contexte avant de lancer la requête

Claude n'est utile qu'à hauteur de ce qu'on lui montre. Si vous collez un diff géant sans objectif ni contraintes, vous obtiendrez des conseils génériques et manquerez les vrais risques.

Commencez par un objectif concret et des critères de succès. Par exemple : « Cette PR ajoute un rate limiting sur le endpoint de login pour réduire les abus. Elle ne doit pas changer la forme de la réponse. Elle doit maintenir une latence moyenne sous 50 ms. »

Ensuite, incluez seulement ce qui compte. Si 20 fichiers ont changé mais que seuls 3 contiennent la logique, concentrez-vous sur ces 3. Ajoutez du contexte quand un extrait serait trompeur, comme les signatures de fonctions, les types clés ou la config qui change le comportement.

Enfin, précisez les attentes de test. Si vous voulez des tests unitaires pour des cas limites, un test d'intégration pour un chemin critique ou une vérification manuelle UI, dites-le. Si les tests manquent volontairement, indiquez pourquoi.

Un « pack de contexte » simple qui marche bien :

• Objectif de la PR : quoi change, ce que voit l'utilisateur, ce qui doit s'améliorer
• Extraits de diff pertinents : fichiers clés uniquement, avec assez de contexte
• Contraintes strictes : budgets de performance, compatibilité, règles de sécurité/confidentialité
• Attentes de tests : ce qui doit être couvert, ce qui a été ajouté, comment l'exécuter
• Éléments « à ne pas changer » : contrats d'API publics, schéma de base de données, comportement UX, format de logs/audit

Étape par étape : un flux de pré-relecture reproductible

Une bonne relecture Claude Code fonctionne comme une boucle serrée : fournissez juste assez de contexte, obtenez des notes structurées, puis transformez-les en actions. Ça ne remplace pas les humains. Ça attrape les oublis faciles avant qu'un collègue passe beaucoup de temps à lire.

Le flux en 5 passes

Utilisez les mêmes passes à chaque fois pour que les résultats restent prévisibles :

1. Expliquez le changement en langage simple. Demandez à Claude de résumer ce que fait la PR, quels fichiers ont changé et la raison probable du changement. S'il ne peut pas l'expliquer simplement, la PR a probablement besoin d'une description plus claire ou d'un scope réduit.
2. Vérifiez la correction en premier. Cherchez les erreurs logiques, les hypothèses brisées et les changements de comportement silencieux (valeurs par défaut, gestion des erreurs, permissions, fuseaux horaires, off-by-one).
3. Parcourez les cas manquants. Pensez comme un utilisateur et comme la production : entrées vides, nulls, retries, échecs partiels, concurrence, compatibilité arrière.
4. Revoyez la lisibilité et la maintenabilité. Identifiez les noms confus, les fonctions longues, la logique dupliquée, les commentaires peu clairs et les petits refactors qui réduisent le temps de relecture futur.
5. Rédigez des commentaires de revue avec repères. Groupez les commentaires par fichier et incluez un nom de fonction ou un extrait cité pour que l'humain trouve rapidement l'endroit.

Après réception des notes, transformez-les en un court gate de merge :

Checklist de merge (restez concis) :

• Les tests couvrent le nouveau comportement et au moins un cas limite
• Les erreurs sont gérées de façon cohérente (et loggées si nécessaire)
• Aucun changement cassant sans plan de migration clair
• Le nommage et la structure correspondent au code voisin
• Les parties risquées ont un plan de rollback

Terminez en demandant 3 à 5 questions qui forcent la clarté, par exemple « Que se passe-t-il si l'API renvoie une liste vide ? » ou « Est-ce sûr en cas de requêtes concurrentes ? »

Utilisez un simple rubric (lisibilité, correction, cas limites)

Claude est le plus utile quand vous lui donnez une lentille fixe. Sans rubric, il commente souvent ce qui apparaît en premier (souvent des nits de style) et peut rater le cas limite risqué.

Un rubric pratique :

• Lisibilité : noms clairs, flux simple, fonctions courtes, commentaires qui expliquent le pourquoi, pas de code mort ni de log de debug laissé.
• Correction : invariants clés respectés, erreurs gérées de façon cohérente, valeurs nulles/vides sans risque, bornes correctes (off-by-one, arrondi).
• Cas limites : entrées vides/gigantes, champs optionnels manquants, fuseaux horaires et été/hiver, retries risquant des doublons, courses en concurrence.
• Sécurité et confidentialité : vérifs d'auth au bon endroit, pas de secrets dans le code/logs, logs qui ne fuient pas de tokens ou payloads sensibles.
• Compatibilité et sécurité de déploiement : anciens clients et données stockées ne doivent pas casser, migrations sûres, plan de rollback.

Quand vous demandez, exigez un paragraphe court par catégorie et demandez « problème le plus risqué en premier ». Cet ordre garde les humains concentrés.

Modèles de prompt qui produisent des notes utiles

Utilisez un prompt de base réutilisable pour homogénéiser les résultats. Collez la description de la PR, puis le diff. Si le comportement est visible par l'utilisateur, ajoutez le comportement attendu en 1 à 2 phrases.

You are doing a pre-review of a pull request.

Context
- Repo/service: <name>
- Goal of change: <1-2 sentences>
- Constraints: <perf, security, backward compatibility, etc>

Input
- PR description:
<...>
- Diff (unified diff):
<...>

Output format
1) Summary (max 4 bullets)
2) Readability notes (nits + suggested rewrites)
3) Correctness risks (what could break, and why)
4) Edge cases to test (specific scenarios)
5) Reviewer checklist (5-10 checkboxes)
6) Questions to ask the author before merge (3-7)

Rules
- Cite evidence by quoting the relevant diff lines and naming file + function/class.
- If unsure, say what info you need.

Pour les changements à haut risque (auth, paiements, permissions, migrations), ajoutez une réflexion explicite sur les échecs et le rollback :

Extra focus for this review:
- Security/privacy risks, permission bypass, data leaks
- Money/credits/accounting correctness (double-charge, idempotency)
- Migration safety (locks, backfill, down path, runtime compatibility)
- Monitoring/alerts and rollback plan
Return a “stop-ship” section listing issues that should block merge.

Pour les refactors, faites de « pas de changement de comportement » une règle stricte :

This PR is a refactor. Assume behavior must be identical.
- Flag any behavior change, even if minor.
- List invariants that must remain true.
- Point to the exact diff hunks that could change behavior.
- Suggest a minimal test plan to confirm equivalence.

Si vous voulez un rapide survol, ajoutez une limite comme « Répondre en moins de 200 mots ». Si vous voulez de la profondeur, demandez « jusqu'à 10 constats avec raisonnement ».

Transformez la sortie en checklist pour le relecteur

Les notes de Claude deviennent utiles quand vous les convertissez en une checklist courte qu'un humain peut clore. Ne répétez pas le diff. Capturez les risques et décisions.

Séparez les items en deux catégories pour éviter que le fil ne tourne en débats de préférence :

À corriger (bloque le merge)

• Correction : l'issue attendue est écrite en une phrase et correspond au ticket
• Cas limites : entrées nulles/vides et chemins d'erreur sont gérés (ou rejetés) clairement
• Sécurité des données : écritures et migrations sûres pour les données existantes et l'ancien code
• Tests : au moins un test couvre le comportement principal et un autre couvre l'échec le plus risqué
• Observabilité : logs/métriques suffisants pour déboguer rapidement (request id, user id, job id)

Sympa à avoir (suivis)

• Lisibilité : renommer l'identifiant le plus confus ou ajouter un court commentaire « pourquoi »
• Cohérence : respecter les patterns existants pour erreurs, noms et layout des fichiers
• Performance : noter les changements sur les hot-paths et si ça compte à l'échelle actuelle
• Docs : mettre à jour la documentation inline si une nouvelle option/flag a été ajoutée

Capturez aussi la préparation au déploiement : ordre de déploiement le plus sûr, quoi surveiller après la mise en production et comment annuler le changement.

Questions à poser avant de merger

Une pré-relecture n'aide que si elle se termine par un petit ensemble de questions qui forcent la clarté.

Comportement et correction

• Quel changement visible pour l'utilisateur, et ce qui doit rester identique ?
• Si c'est « pas de changement de comportement », quelle preuve montre que les sorties sont identiques ?
• Quelle est la défaillance la plus probable en production, et où cela se verra-t-il (UI, API, données) ?
• Quelles hypothèses le code fait-il sur les entrées, l'ordre, le temps ou les appels réseau ?
• Des erreurs sont-elles silencieusement avalées ou converties en valeurs par défaut ?

Cas limites, tests et opérations

• Quelles sont les pires entrées réelles (vides, gigantesques, malformées, doublons), et que doit-il se passer ?
• Quel flux courant pourrait déclencher ceci deux fois (retries, double-clic, jobs en arrière-plan) et est-ce sûr ?
• Quel test prouve le comportement principal, et lequel couvre le cas limite le plus risqué ?
• Si un test manque, est-il difficile à écrire ou le code est-il difficile à tester ?
• De quoi ops a besoin : logs utiles, métriques, alertes, valeurs par défaut de config et étapes de rollback ?

Si vous ne pouvez pas répondre clairement, suspendez le merge et réduisez le scope ou ajoutez une preuve.

Pièges courants (et comment les éviter)

La plupart des échecs sont des problèmes de process, pas des problèmes de modèle.

• Coller des diffs énormes sans focalisation. Demandez une revue sur 1 à 3 zones risquées et collez seulement les hunks liés plus les signatures dont ils dépendent.
• Omettre l'intention et le comportement attendu. Sans objectif, la revue dérive. Ajoutez deux lignes : ce qui change et ce qui ne doit pas changer.
• Se fier aux hypothèses sûres. Exigez des citations du diff. S'il ne peut pas citer de preuves, traitez cela comme une hypothèse à tester.
• Laisser la discussion dévier sur des préférences de style. Demandez « À corriger » vs « Sympa à avoir » et limitez les notes de style.
• Ignorer les standards d'équipe. Si votre équipe a des conventions (retours précoces, types d'erreur, format de logs), incluez-les.

Si une PR ajoute un nouvel endpoint checkout, ne collez pas tout le service. Collez le handler, la validation, l'écriture DB et les changements de schéma. Puis dites : « Objectif : éviter les doubles facturations. Non-objectifs : refactorer le nommage. » Vous obtiendrez moins de commentaires et plus faciles à vérifier.

Exemple réaliste : pré-relecture d'une petite PR

Une petite PR réaliste : ajouter un champ « display name » à un écran de paramètres. Elle touche la validation (serveur) et le texte UI (client). C'est assez petit pour raisonner, mais contient encore des endroits où des bugs se cachent.

Voici les extraits de diff que vous colleriez (plus 2 à 3 phrases de contexte comme comportement attendu et tickets liés) :

- if len(name) == 0 { return error("name required") }
+ if len(displayName) < 3 { return error("display name too short") }
+ if len(displayName) > 30 { return error("display name too long") }

- <TextInput label="Name" value={name} />
+ <TextInput label="Display name" value={displayName} helperText="Shown on your profile" />

Exemples de constats que vous voudrez recevoir :

• Lisibilité : « displayName » vs « name » est mélangé entre fichiers. Choisissez un terme pour éviter la traduction mentale future.
• Correction : le serveur valide la longueur, mais le client ne le fait pas. Les utilisateurs peuvent taper 1 ou 2 caractères et ne voir l'erreur qu'après l'envoi.
• Cas limite : des chaînes composées d'espaces passent len(displayName) mais semblent vides. Trimmez avant validation.

Transformez cela en checklist :

• Le nommage est cohérent entre l'API, le champ en base et les libellés UI.
• Les vérifications côté client correspondent aux règles côté serveur (min/max, obligatoire).
• L'entrée est trimée (et le comportement Unicode/emoji est acceptable).
• Les messages d'erreur sont clairs et alignés entre serveur et UI.

Contrôles rapides, mesures et étapes suivantes

Une relecture Claude Code marche mieux si elle se termine par quelques vérifications rapides :

• Comportement : qu'est-ce qui change pour l'utilisateur et ce qui ne doit pas changer
• Tests : ce qui est couvert, ce qui manque, ce qui peut flak-er
• Logs et erreurs : les échecs sont clairs et les messages exploitables
• Performance : nouvelles boucles, requêtes N+1, payloads volumineux, appels réseau supplémentaires
• Sécurité : validation, checks d'auth, secrets, valeurs par défaut risquées

Pour mesurer l'impact, suivez deux métriques simples pendant 2 à 4 semaines : le temps de revue (ouvert -> premier review significatif, et ouvert -> merged) et le rework (commits de suivi après revue, ou nombre de commentaires nécessitant des changements de code).

La standardisation bat les prompts parfaits. Choisissez un template, exigez un petit bloc de contexte (quoi change, pourquoi, comment tester) et mettez-vous d'accord sur ce que « done » signifie.

Si votre équipe construit des features via du développement conversationnel, appliquez le même flux dans Koder.ai : générez les changements, exportez le code source, puis joignez la checklist de pré-relecture à la PR pour que la relecture humaine reste concentrée sur les parties les plus risquées.