Que fait Code Change Review ?
Examinez une modification comme le ferait un ingénieur senior compétent : trouvez les défauts qui comptent, prouvez-les et signalez-les pour que l'auteur puisse agir rapidement. Une revue courte avec trois vrais bugs vaut mieux qu'une longue avec trente peut-être, car chaque faux positif apprend au lecteur à survoler.
Workflow
1. Délimiter l'ensemble des modifications
Déterminez exactement ce qui est sous revue avant de lire le moindre code. Si l'utilisateur ne l'a pas précisé, par défaut, tout ce qui n'est pas encore sur la branche de base.
| Cible | Comment l'obtenir |
|---|---|
| Travail non indexé | git diff HEAD (plus git status pour les fichiers non suivis, puis lisez-les) |
| Uniquement indexé | git diff --cached |
| Branche courante | git diff $(git merge-base HEAD <base>) où <base> est généralement main/master |
| Plage de commits | git diff A..B |
| Pull request (numéro ou URL) | gh pr view <n-ou-url> pour la description, la base et la tête ; gh pr diff <n-ou-url> pour le diff ; gh pr diff <n-ou-url> --name-only pour la liste des fichiers |
| Fichiers spécifiques | Lisez-les ; demandez ce qui a changé par rapport à quoi si c'est important |
Pull requests. « Review PR 123 » ou « review PR #123 » signifie la PR 123 dans le dépôt courant. Une URL (https://github.com/<propriétaire>/<dépôt>/pull/<n>) peut être passée à gh telle quelle, et fonctionne depuis n'importe quel répertoire, même pour un autre dépôt. Pour une merge request GitLab, utilisez glab mr view / glab mr diff. Le diff seul ne suffit pas comme contexte (étape 3), alors lisez aussi les versions des fichiers de la PR :
-
Si la PR provient du dépôt courant, récupérez-la ainsi que sa base sans changer de branche, dans une ref dédiée qui est mise à jour par force, de sorte qu'une PR rebasée remplace toute copie d'une revue précédente. Récupérez depuis le remote qui pointe vers le dépôt de base de la PR (vérifiez avec
git remote -v) ; dans un fork, il s'agit généralement deupstream, pasorigin:git fetch <remote> <base> +refs/pull/<n>/head:refs/review/pr-<n> git rev-parse refs/review/pr-<n> # doit être égal à : gh pr view <n> --json headRefOid --jq .headRefOidSi la récupération échoue ou que le commit ne correspond pas à
headRefOid, arrêtez-vous et dites-le plutôt que de passer en revue une copie erronée ou obsolète. Ensuite, lisez les fichiers avecgit show refs/review/pr-<n>:<path>et comparez avec$(git merge-base refs/review/pr-<n> <remote>/<base>). Utilisezgh pr checkout <n>seulement si l'utilisateur est d'accord pour que son arbre de travail change. -
Pour un autre dépôt, lisez les fichiers à la tête de la PR via
gh api "repos/<owner>/<repo>/contents/<path>?ref=<head-sha>"(entre guillemets, car?est un caractère glob dans zsh), ou clonez-le dans un répertoire temporaire si la revue a besoin de beaucoup de contexte. -
Lisez les retours existants pour ne pas répéter ce qui a été soulevé, répondu ou résolu.
gh pr view <n> --commentsn'affiche que les commentaires de premier niveau ; les fils de discussion de revue en ligne, leurs réponses et l'état de résolution viennent de GraphQL :gh api graphql --paginate -F owner=<owner> -F repo=<repo> -F n=<n> -f query='query($owner:String!,$repo:String!,$n:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){totalCount nodes{author{login} body}}}}}}}'--paginatesuit les fils au-delà des 100 premiers. Un fil dontcomments.totalCountdépasse 100 a plus de réponses ; récupérez-les avecnode(id:<thread id>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}}avant de vous y fier.
Obtenez également l'intention : la description de la PR, les messages de commit, le ticket lié, ou demandez à l'utilisateur en une ligne si rien n'existe. Vous ne pouvez pas juger si le code est correct sans savoir ce qu'il est censé faire.
Pour les très grandes modifications (plus d'environ 1 500 lignes modifiées), faites d'abord un tri. Classez les fichiers par risque (authentification, paiements, migrations de données, concurrence, API publiques, et tout ce qui est supprimé passe avant la documentation, le code généré et les lockfiles) et indiquez quels fichiers ont reçu un examen plus léger.
2. Charger les références linguistiques pour les langages touchés par la modification
Chargez uniquement les fichiers de référence pour les langages et types de fichiers présents dans l'ensemble modifié, jamais tous. Chaque fichier ajoute du contexte qui prend de la place par rapport au code que vous examinez.
Exécutez le détecteur si Python est disponible (python ou python3) :
python <rép-du-skill>/scripts/detect_languages.py --git <base> # branche vs base
python <rép-du-skill>/scripts/detect_languages.py --git HEAD # travail non indexé
python <rép-du-skill>/scripts/detect_languages.py --git <remote>/<base> --head refs/review/pr-<n> # PR récupérée
git diff --name-only ... | python <rép-du-skill>/scripts/detect_languages.py # toute liste de fichiers
Pour une pull request, utilisez --head avec la ref récupérée à l'étape 1. Le détecteur lit alors les shebangs du commit de la PR, pas de votre arbre de travail, qui peut manquer les nouveaux scripts de la PR ou contenir des versions différentes. Pour une PR dans un autre dépôt, gh pr diff <url> --name-only | python <rép-du-skill>/scripts/detect_languages.py donne la liste des fichiers, mais ne peut pas voir le contenu des fichiers. Vérifiez la première ligne de chaque fichier sans extension de la liste, qu'il soit mappé ou non (un script Python sous migrations/ est déjà mappé à sql.md mais nécessite aussi python.md) : lisez-le à la tête de la PR, ou à la base si la PR le supprime, et acheminez-le avec le tableau de shebangs ci-dessous.
Cela imprime les fichiers de référence à lire et quels fichiers modifiés ont déclenché chacun. Sans Python, utilisez ce tableau, qui correspond exactement au détecteur. Les noms de fichiers sont comparés sans tenir compte de la casse.
| Fichiers modifiés | Fichier à lire |
|---|---|
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lock | references/languages/python.md |
.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .vue, .svelte, .astro, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, tsconfig.json | references/languages/javascript-typescript.md |
.go, go.mod, go.sum, go.work | references/languages/go.md |
.rs, Cargo.toml, Cargo.lock | references/languages/rust.md |
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.properties | references/languages/java-kotlin.md |
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.json | references/languages/csharp-dotnet.md |
.c, .h, .cc, .cpp, .cxx, .c++, .hpp, .hh, .hxx, .inl, .ipp, .m, .mm, CMakeLists.txt, Makefile, meson.build, conanfile.txt, vcpkg.json | references/languages/c-cpp.md |
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.ru | references/languages/ruby.md |
.php, .phtml, composer.json, composer.lock | references/languages/php.md |
.swift, .pbxproj, Package.swift, Package.resolved, Podfile | references/languages/swift.md |
.sql, .psql, .pgsql, .ddl, et tout fichier sous migration/, migrations/, migrate/, alembic/versions/, flyway/, liquibase/ | references/languages/sql.md |
.sh, .bash, .zsh, .ksh, .fish, .ps1, .psm1, .psd1, .bat, .cmd | references/languages/shell.md |
.tf, .tfvars, .hcl, .dockerfile, Dockerfile, Dockerfile*, Containerfile, .dockerignore, compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml, Chart.yaml, values.yaml, kustomization.yaml, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile, tout fichier sous .circleci/, et YAML sous .github/workflows/, .github/actions/, k8s/, kubernetes/, helm/, charts/, manifests/, deploy/, deployment/, kustomize/, argocd/ | references/languages/infrastructure.md |
Un fichier sans extension est acheminé par l'interpréteur de sa ligne shebang (#!/usr/bin/env deno, #!/usr/bin/python3). Les suffixes de version sont ignorés.
| Interpréteur shebang | Fichier à lire |
|---|---|
python | references/languages/python.md |
node, deno, bun, ts-node, tsx | references/languages/javascript-typescript.md |
ruby | references/languages/ruby.md |
php | references/languages/php.md |
sh, bash, zsh, ksh, dash, fish, pwsh | references/languages/shell.md |
Un fichier peut nécessiter deux références. Une migration Rails ou Alembic a besoin de son fichier de langage et de sql.md, et le détecteur signale les deux. Un langage sans fichier de référence reçoit quand même une revue complète. Les angles généraux ci-dessous couvrent cela, et vous devez appliquer ce que vous savez des pièges courants de ce langage. Les langages embarqués comptent aussi : les chaînes SQL en Python, ou les commandes shell construites en Go, sont une raison de charger sql.md ou shell.md.
3. Construire le contexte au-delà du diff
Le diff montre ce qui a changé, pas ce que cela affecte. Avant de juger quoi que ce soit :
- Lisez le code environnant de chaque hunk, pas seulement les lignes modifiées. Beaucoup de bugs vivent dans l'interaction des nouvelles lignes avec les anciennes.
- Trouvez les appelants et les dépendants de chaque fonction, type, schéma, clé de configuration ou endpoint modifié (grep, LSP find-references). Le rayon d'impact est invisible depuis le diff.
- Apprenez les conventions du projet : configurations du linter et du formateur,
CLAUDE.md/CONTRIBUTING.md, et comment le code voisin gère les erreurs, la journalisation et les tests. Jugez la cohérence par rapport à cette base de code, pas par rapport au goût général. - Cherchez des aides existantes avant d'accepter un nouveau code utilitaire. Réimplémenter quelque chose que le dépôt possède déjà ne se voit que lorsque vous regardez en dehors du diff.
4. Examiner par angle, par ordre de priorité
Travaillez du haut de cette liste vers le bas. Un bug de niveau 1 est plus important que n'importe quel nombre de remarques de niveau 3. references/review-angles.md contient la liste de contrôle complète pour chaque angle ; lisez-le pour toute revue non triviale.
- Est-ce correct ? Correction et cas limites, fidélité à l'intention (fait-il ce qu'il prétend, complètement ?), gestion des erreurs et modes de défaillance, concurrence et état partagé, rayon d'impact sur les appelants.
- Est-ce sûr à déployer ? Sécurité, compatibilité API/schéma/wire, intégrité des données et migrations, opérabilité (déploiement, rollback, observabilité), nouvelles dépendances, vie privée.
- Est-ce du bon code ? Performance et efficacité, abstraction (altitude) (la correction est-elle au bon niveau ?), duplication et réutilisation, simplicité vs. sur-ingénierie, cohérence avec les conventions, lisibilité.
- Est-ce vérifié ? Tests qui échoueraient réellement sans la modification, documentation et commentaires maintenus synchronisés.
Appliquez les vérifications du fichier de langage chargé dans ces angles. Ce sont les formes spécifiques que ces problèmes prennent dans ce langage.
5. Vérifier chaque constat avant de le signaler
Pour chaque constat potentiel :
- Écrivez le scénario de défaillance : entrée ou état concret, puis le résultat erroné. Si vous ne pouvez pas, ce n'est probablement pas un bug.
- Relisez le code pour vérifier que le problème n'est pas déjà traité : une garde en amont, un validateur, un type qui l'exclut, un test qui le couvre.
- Exécutez-le lorsque c'est peu coûteux et sûr (un test unitaire, un extrait REPL, le vérificateur de types ou le linter) et que le constat est incertain.
- Évaluez la confiance : Confirmé (tracé ou reproduit) ou Plausible (chemin crédible que vous n'avez pas pu prouver complètement). Abandonnez tout ce qui est plus faible. Si quelque chose n'est pas clair mais inoffensif à soulever, posez-le sous forme de question plutôt que d'affirmer un bug.
6. Rapporter
Utilisez references/reporting.md pour les balises de sévérité, le format de commentaire et le modèle de sortie. En bref :
- Commencez par un verdict en une ligne : est-ce sûr à merger, et le problème le plus important s'il y en a.
- Chaque constat commence par sa balise de sévérité :
[CRITICAL],[MAJOR],[MINOR]ou[NIT], puis une affirmation en une ligne et sonfile:line. Le corps explique, dans cet ordre, quel est le problème, pourquoi c'est un problème (le scénario de défaillance concret), et une correction ou amélioration suggérée lorsque vous pouvez en proposer une. - Listez les constats du plus sévère au moins sévère. Plafond par défaut d'environ 10. Mentionnez combien d'éléments de moindre sévérité vous avez omis, et listez-les si l'utilisateur le demande.
- Gardez les
[NIT]en réserve sauf s'il n'y a aucun défaut réel, ou si l'utilisateur a demandé un passage approfondi. - Terminez par ce que vous n'avez pas couvert (fichiers survolés, choses que vous n'avez pas pu exécuter). Une note de périmètre honnête fait partie de la revue.
Utilisez le même format balise-en-premier pour les commentaires postés sur une pull request, afin qu'un constat se lise de la même manière dans le rapport et sur la PR. Ne postez sur la PR que lorsque l'utilisateur vous le demande ; references/reporting.md montre comment les poster en une seule revue avec des commentaires en ligne.
Si l'hôte fournit un outil de constats structurés, rapportez via celui-ci dans le même ordre au lieu d'imprimer la liste, et commencez toujours le résumé de chaque constat par sa balise.
Principes
- Preuve plutôt qu'opinion. Chaque constat cite du code. « Envisagez X » sans raison est du bruit.
- Examinez la modification, pas la base de code. Signalez les problèmes préexistants seulement lorsque la modification les aggrave ou en dépend, et étiquetez-les comme préexistants.
- Respectez les choix de l'auteur. Une approche différente mais tout aussi valide n'est pas un constat. N'êtes en désaccord que lorsque vous pouvez nommer un coût concret.
- Ne corrigez pas pendant la revue sauf si on vous le demande. Suggérez des corrections ; laissez l'utilisateur décider de les appliquer.