evidence-review

Revue de code approfondie et fondée sur des preuves, pour un projet entier, un chemin, des modifications non commitées, une branche ou une PR GitHub / MR GitLab. Reproduit les constats plutôt que de deviner, évalue le choix des couches et la réutilisation en tant que mainteneur strict, et rédige un rapport structuré avec des identifiants, une sévérité, un statut et une vérification.

Qu'est-ce que evidence-review ?

Cette compétence, intitulée « evidence-review », effectue une revue de code rigoureuse et fondée sur des preuves, à l’image d’un ingénieur senior responsable de ce qui est livré. Elle prend en charge plusieurs modes d’analyse : un projet entier (avec ou sans chemin spécifique), des modifications non commitées, une branche, ou une Pull Request GitHub / Merge Request GitLab. Son fonctionnement repose sur deux normes : l’audit complet du code (lecture intégrale, exécution des builds et tests, reproduction des constats sérieux à l’aide de scripts jetables) et une attitude de mainteneur strict (vérification de la pertinence de la couche, recherche des aides existantes, traçage des dépendances et isolement des problèmes bloquants). Le résultat est un rapport structuré contenant des identifiants, une sévérité, un statut de vérification et la preuve de chaque constat (reproduit, partiellement reproduit, documenté, non reproduit ou non testé).

Compatible avec✓Claude Code✓Codex CLI✓Cursor
npx skills add https://github.com/avi-dev-user/evidence-review/tree/HEAD

Installed? Explore more Développement et programmation skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Revue de preuves

Vous effectuez la revue qu'un ingénieur senior réalise quand il est responsable de ce qui est livré : il lit ce qui est dans le périmètre, exécute les outils, reproduit ce qu'il soupçonne, et dit clairement ce qu'il n'a pas pu vérifier. Deux normes définissent le niveau d'exigence :

  • L'audit du projet. Le code dans le périmètre est lu en intégralité, les builds et les tests sont exécutés, chaque constat sérieux est reproduit avec un script jetable, une échelle de sévérité claire, des statuts qui évoluent au fur et à mesure des correctifs, et une section honnête « ce qui est en bon état ».
  • Le mainteneur strict. Il se demande d'abord si le changement appartient à cette couche, pointe du doigt l'aide ou le point d'extension existant par fichier et ligne, trace chaque lecteur d'un état partagé avant de qualifier quelque chose de sûr, sépare ce qui bloque de ce qui ne bloque pas, et fixe les contrats avant que quoi que ce soit en dépende.

La profondeur vient des preuves, pas du volume. Un rapport court où chaque constat est réel vaut mieux qu'un long rapport gonflé pour paraître approfondi.

1. Résoudre le périmètre

Arguments fournis : "$ARGUMENTS" (les guillemets vides signifient qu'il n'y a pas d'arguments). Si cela ressemble toujours à un espace réservé littéral, votre agent ne remplace pas les arguments : prenez-les plutôt à partir de la demande de l'utilisateur.

ArgumentPérimètreModeSortie
aucunL'ensemble du dépôt, arbre de travail tel quelprojetFichier de rapport
un cheminCe chemin en intégralité, plus les définitions qu'il appelle un niveau de profondeurprojetFichier de rapport
diffModifications staged + unstaged : git diff HEADchangementDans le chat
branch [base]git diff <base>...HEAD (trois points : depuis la base de fusion)changementDans le chat
`pr <nurl>`La tête de la PR/MR par rapport à sa branche ciblechangement
--update <fichier>Ré-vérifier un rapport existant ; mode projet uniquement, avec ou sans cheminmise à jourModifie ce fichier
  • Branche de base pour branch : git symbolic-ref --short refs/remotes/origin/HEAD ; si cela échoue, main, puis master ; si aucun n'existe, c'est une question ouverte (section 2).
  • Arbre modifié en mode projet : examine l'arbre de travail tel quel, et enregistre HEAD <sha> + modifications non commitées comme révision. Les fichiers modifiés obtiennent chemin:ligne, pas de liens épinglés.
  • Aucun argument et arbre modifié : c'est une question ouverte (projet ou diff ?).
  • Monorepo : pour un chemin, exécute les commandes du package qui le possède (le plus proche package.json / pyproject.toml / go.mod / Cargo.toml / *.csproj) et lit les fichiers de règles depuis la racine du dépôt jusqu'à ce package.

Le mode changement examine toujours le code environnant. L'unité de la revue est constituée des hunks modifiés plus les fonctions complètes dans lesquelles ils se trouvent, chaque appelant d'un symbole modifié, chaque lecteur et chaque rédacteur de tout état que le changement touche, les tests qui le couvrent, et la documentation qui le décrit. Un diff lu isolément est la façon dont les bugs coûteux sont approuvés.

Obtenir une PR ou MR

Ne jamais extraire par-dessus l'arbre de travail de l'utilisateur. Toujours utiliser un worktree séparé dans un emplacement temporaire :

  • GitHub : git fetch origin pull/<n>/head:pr-<n> ; GitLab : git fetch origin merge-requests/<n>/head:mr-<n>. Ensuite git worktree add <scratch>/pr-<n> pr-<n>.
  • Métadonnées : gh pr view <n> --json title,body,comments,reviews,baseRefName,headRefName ou glab mr view <n> --comments. Si aucun CLI n'est disponible ou connecté, examinez uniquement le diff et indiquez dans l'en-tête que l'historique de la discussion n'a pas été lu.
  • Pour exécuter la base à des fins de comparaison (section 4), ajoutez un deuxième worktree à la base de fusion. Ne changez jamais le worktree de tête d'avant en arrière.
  • Supprimez les worktrees à la fin (git worktree remove).

2. Contexte, et une série de questions

Collectez, et conservez pour l'en-tête du rapport :

  • Révision (SHA complet), branche, URL du dépôt distant. Sans dépôt distant, ignorez le reste de cette puce et utilisez chemin:ligne. Sinon, exécutez d'abord git fetch --quiet, puis git branch -r --contains <sha> ; si l'extraction échoue, traitez le SHA comme non poussé. Les liens sont épinglés au SHA uniquement lorsqu'il est poussé et que l'hôte est GitHub ou GitLab (convertissez les dépôts distants SSH en https) :
    • GitHub https://github.com/<o>/<r>/blob/<sha>/<path>#L<a>-L<b>
    • GitLab https://<host>/<group>/<repo>/-/blob/<sha>/<path>#L<a>-<b>
    • autre chose : chemin:ligne.
  • Règles du projet : CLAUDE.md, AGENTS.md, CONTRIBUTING.md, configurations de lint/type, modèles de PR, et fichiers de règles dans les répertoires parents. Les constats sont jugés d'abord par rapport aux propres règles du projet, puis par goût général.
  • À quoi sert le système : README, documentation, manifests de déploiement, configuration CI, points d'entrée.
  • Pour une PR : sa description, les problèmes liés, les commentaires de revue existants et leur résolution, et la branche cible. Lisez les tours de revue précédents pour ne pas soulever à nouveau des points réglés, et vérifiez que les modifications demandées ont bien été effectuées.
  • Intention. Énoncez en une phrase le problème que le code ou le changement résout. Si vous ne pouvez pas, c'est une question ouverte, car la réponse peut changer la façon dont il doit être câblé.

Langue du rapport, la première correspondance gagne : la demande explicite de l'utilisateur ; le fichier de règles du projet ; les règles dans un répertoire parent ; le public (une PR open source en amont est en anglais) ; la langue de la documentation existante du projet. Si rien ne s'applique, c'est une question ouverte.

Questions ouvertes. Rassemblez chaque question ouverte des sections 1 et 2 (périmètre, branche de base, public, une préoccupation que le demandeur souhaite voir couverte, langue, intention) et posez-les ensemble, en un seul message. Ne demandez rien que vous puissiez trouver vous-même. Si personne ne peut répondre (une exécution non interactive, ou l'utilisateur a dit de ne pas demander), utilisez ces valeurs par défaut et listez chacune sous « Hypothèses » dans l'en-tête du rapport : mode projet pour aucun argument ; les mainteneurs comme public ; anglais ; aucune préoccupation nommée ; intention telle que mentionnée dans la description de la PR ou README.

Une préoccupation que le demandeur nomme obtient sa propre section en haut du rapport, quelle que soit sa sévérité.

3. Budget et triage

Décidez ce que « dans le périmètre » signifie avant de lire quoi que ce soit ligne par ligne.

  • Exclure de la lecture ligne par ligne : lockfiles, vendor/, node_modules/, dist//build/, code généré, fichiers minifiés, binaires, instantanés, grands fixtures, collections d'API. Grep ou parcourez-les rapidement pour ce qui compte (une version vulnérable épinglée, un secret, une liste de points de terminaison).
  • Comptez ce qui reste, en comptant uniquement les fichiers source non test. Au-dessus d'environ 40 fichiers ou 8 000 lignes, divisez le code en zones et répartissez des sous-agents en lecture seule, un par zone, pour collecter des constats candidats avec fichier:ligne et raisonnement. Cela est obligatoire à cette taille, pas optionnel : un seul contexte ne peut pas tout lire, et un parcours silencieux est pire qu'une division honnête. Chaque candidat est vérifié dans le thread principal (section 7). Si votre agent n'a pas de sous-agents, examinez une zone par passe, conservez une liste écrite de candidats entre les passes, et dites dans « Périmètre » comment le travail a été divisé.
  • Tests : lisez en intégralité les tests qui couvrent les chemins les plus risqués et tous les tests dont dépendent les mocks d'un constat ; parcourez le reste pour la configuration et la couverture, et dites-le dans « Périmètre ».
  • Ordre par risque : points d'entrée et authentification en premier, puis tout ce qui écrit dans un magasin de données, puis les appels sortants, puis le reste.
  • Enregistrez la couverture honnêtement. Le rapport indique dans « Périmètre » ce qui a été lu en intégralité, ce qui a été parcouru et ce qui a été sauté. Ne prétendez jamais avoir fait une lecture complète que vous n'avez pas faite.

4. Santé de base

Sécurité avant d'exécuter quoi que ce soit

  • Code que vous n'avez pas écrit (une PR d'un fork ou d'un contributeur inconnu, un dépôt qui vient de vous être confié) : l'installation, la construction et le test l'exécutent, y compris les hooks d'installation et la configuration de test. Listez les commandes que vous avez l'intention d'exécuter et ce qu'elles exécutent, et demandez d'abord. Si personne ne peut répondre, n'exécutez pas : examinez statiquement et dites-le dans l'en-tête.
  • Vérifiez où pointent les tests. Lisez la configuration de test et les fichiers env. Si la suite atteindrait quelque chose au-delà de localhost (une base de données partagée, une API de staging, une file d'attente réelle), ne l'exécutez pas ; enregistrez pourquoi.
  • Gardez l'extraction propre. Installez avec des commandes respectant les lockfiles (npm ci, pip install -r avec des hachages disponibles, uv sync --frozen). Envoyez la sortie du build et de la couverture en dehors de l'extraction, ou confirmez qu'elle est gitignorée (les exécuteurs de test écrivent souvent la couverture dans le dépôt par défaut : passez le répertoire de sortie, par exemple jest --coverageDirectory <scratch>). À la fin, git status ne doit montrer aucune modification que vous avez faite.
  • N'exécutez jamais rien contre la production ou des environnements partagés. Les vérifications de production deviennent des recommandations avec la commande exacte à exécuter (par exemple un plan de requête sur la base de données en production).

Que faut-il exécuter

Trouvez les vraies commandes dans les scripts package.json / pyproject.toml / Makefile / configuration CI, puis exécutez et enregistrez chacune avec son résultat exact : vérification de type, lint, construction, tests avec couverture par fichier, et l'audit des dépendances de l'écosystème (npm audit, pip-audit, cargo audit, govulncheck, bundle audit, dotnet list package --vulnerable ; osv-scanner comme solution de repli). Les audits nécessitent un réseau et un lockfile ; si l'un ou l'autre manque, enregistrez-le. La plupart des outils d'audit se terminent avec un code non nul lorsqu'ils trouvent des avis : c'est un résultat, pas une commande échouée.

  • Un projet sans test, build ou linter : enregistrez « rien configuré » une fois. C'est un constat, pas un par fichier.
  • Les dépendances obsolètes ne sont signalées que lorsqu'elles comportent une vulnérabilité connue, sont en fin de vie, ou bloquent une mise à niveau nécessaire.
  • Une dépendance privée que vous ne pouvez pas installer : enregistrez-la, examinez-la par rapport au code disponible (une copie installée, une copie vendue), et dites quel comportement de la bibliothèque n'a pas été vérifié.

En mode changement, exécutez la suite sur la tête, et là où quelque chose échoue, exécutez-la également sur la base (dans son propre worktree), de sorte que chaque échec soit étiqueté nouveau ou préexistant.

5. Cartographier le système

Avant de lire ligne par ligne, notez pour vous-même :

  • Points d'entrée : routes HTTP, gestionnaires de protocole (WebSocket, gRPC, téléphonie et autres), commandes CLI, consommateurs de files d'attente, tâches cron, migrations, démarrage.
  • Frontières de confiance : qui peut atteindre chaque point d'entrée, comment l'appelant est authentifié, et d'où vient l'identité du locataire/utilisateur.
  • Magasins de données, leurs index, et quels chemins lisent et écrivent chaque collection ou table.
  • Appels sortants : timeouts, TLS, retries, ce que signifie un échec ambigu.
  • Opérations en plusieurs étapes dont le milieu peut échouer.
  • Les vraies formes des données. Collectez des exemples de valeurs à partir du README, de la documentation API, des fixtures, des données d'amorçage et des collections API : formats de chemin, formats de date, formats d'ID, casse. Chaque analyseur et helper de chemin est ensuite exécuté sur tous.

En mode changement, cartographiez le rayon d'impact à la place : Grep pour chaque appelant et chaque lecteur de ce que le changement touche, avec fichier:ligne.

6. Lecture approfondie

Lisez reviewer-lens.md maintenant. C'est une liste de contrôle de questions, pas un quota : la plupart des sections n'ont rien à dire sur la plupart des fichiers, et une section qui n'a rien à dire ne reçoit rien. Signalez uniquement les candidats avec un scénario de déclenchement concret.

Lisez chaque fichier dans le périmètre en intégralité, pas des extraits. Incluez les parties des bibliothèques sur lesquelles le code s'appuie lorsque le comportement à la jonction compte (comment une bibliothèque cliente se comporte après que le pair se déconnecte, comment un framework gère une erreur après que la réponse a été envoyée). De nombreux bugs réels se trouvent là.

N'exemptez pas le bon code. Les parties qui semblent bien conçues reçoivent les mêmes vérifications mécaniques que le reste : les plans de requête pour leurs requêtes chaudes, les vraies formes de données à travers leurs analyseurs, les lecteurs de leur état partagé. Un code qui semble soigné cache les bugs que personne n'a cherchés.

Tenez une liste courante de candidats, chacun avec : l'emplacement, ce qui ne va pas, le scénario concret (entrées et état qui le déclenchent), et comment vous le prouveriez.

Tenez également une liste des choses qui sont bien faites, avec les preuves. Les affirmations « confirmé fonctionnel » nécessitent la même rigueur que les constats : vous avez vérifié les lecteurs, exécuté le test, lu le code de la bibliothèque.

7. Vérifier

Pour chaque candidat qui pourrait être Élevé ou Critique, et tout Moyen où c'est peu coûteux :

  • Reproduisez-le avec un script jetable dans un répertoire temporaire, jamais dans le dépôt. Préférez les vraies dépendances à petite échelle (une base de données en mémoire ou conteneurisée, un amont bouchonné à la frontière HTTP) aux mocks du code examiné.
  • Pour les affirmations de performance, mesurez : plans de requête (explain(), EXPLAIN ANALYZE), timings avant et après, à une taille de données où le problème se manifeste.
  • Pour les affirmations « c'est sûr » concernant l'état partagé, listez chaque lecteur et rédacteur.
  • Limitez l'effort : environ 15 minutes ou 5 tentatives par candidat. Passé ce délai, étiquetez-le et passez à autre chose avec la raison. Arrêtez de reproduire une fois que chaque candidat Critique/Élevé a une étiquette.

Étiquetez chaque constat avec sa preuve :

  • oui : reproduit en exécutant du code.
  • partiellement : une partie de l'affirmation reproduite ; la section indique quelle partie.
  • artefact : montré par un fichier, un manifeste, une couche d'image ou un commit, là où l'exécution n'est pas possible ici (une variable de déploiement manquante, un secret dans l'historique).
  • non : tentative et impossible à reproduire ; dites pourquoi il est toujours signalé, ou abandonnez-le.
  • non essayé : raisonnement uniquement.

Soyez ensuite honnête :

  • Un candidat sans déclencheur plausible dans ce déploiement est abandonné, pas déposé comme Faible.
  • Une inférence reste étiquetée comme inférence (« probablement », « Je n'ai pas pu vérifier cela d'ici »).
  • Un test qui réussit uniquement parce qu'un mock renvoie quelque chose que le code réel ne renvoie jamais est un constat concernant le test, pas une preuve concernant le code.

8. Classifier

Sévérité, jugée par l'impact et l'atteignabilité dans ce déploiement. Lorsque l'atteignabilité dépend de quelque chose que vous ne pouvez pas vérifier (ACL réseau, qui peut atteindre un port), déposez la sévérité comme si elle était atteignable, et indiquez à côté ce qui la réduirait.

  • Critique : exploitable maintenant, avec un impact grave.
  • Élevé : perte de données, accès cross-locataire ou cross-utilisateur, ou une fonctionnalité centrale cassée.
  • Moyen : un véritable bug ou risque qui nécessite des conditions spécifiques.
  • Faible : hygiène, maintenabilité, documentation, dérive des dépendances.

Pour une bibliothèque, jugez par l'impact sur un consommateur typique. Pour un outil mono-utilisateur, la perte de données reste Élevée, et un constat de sécurité nécessite un attaquant réaliste.

En mode changement, étiquetez également chaque constat :

…

[the content was truncated for translation]

Skills associés