code-reviewer

Vue d’ensemble de la skill code-reviewer

Ce que fait la skill code-reviewer

La skill code-reviewer propose un workflow structuré de revue de PR et de diff pour les tâches de Code Review. Au lieu de s’appuyer sur un simple prompt du type « review this code », elle pousse l’agent à récupérer les fichiers modifiés, inspecter le diff, comprendre les conventions locales du projet, puis analyser les changements selon des catégories concrètes comme la correction, la sécurité, la performance, les tests et la maintenabilité.

Pour qui installer code-reviewer

Cette code-reviewer skill convient surtout aux développeurs, tech leads et reviewers assistés par IA qui veulent plus de régularité qu’un prompt générique n’en apporte habituellement. Elle est particulièrement utile si vous relisez des pull requests régulièrement, si vous voulez des constats classés par gravité, ou si vous avez besoin d’une checklist reproductible couvrant à la fois les problèmes logiques et les risques de sécurité plus élevés.

Le vrai besoin auquel elle répond

La plupart des utilisateurs ne veulent pas seulement du « feedback ». Ils veulent une revue capable de répondre à ces questions : qu’est-ce qui a changé, qu’est-ce qui est risqué, qu’est-ce qui doit bloquer le merge, qu’est-ce qui peut attendre, et sur quelles preuves s’appuie chaque point. Le workflow code-reviewer est conçu pour cela en séparant la collecte de contexte de l’analyse, ce qui limite les commentaires superficiels basés uniquement sur des extraits.

Ce qui distingue cette skill

Son principal différenciateur, c’est sa structure de revue. Le dépôt ne se contente pas d’une instruction large demandant d’inspecter du code. Il inclut :

• un processus de revue par phases
• un format de sortie orienté gravité
• des références ciblées pour la checklist, les patterns de code et la revue de sécurité
• un script utilitaire dans scripts/review_checklist.py pour générer une checklist de revue à partir des changements Git

Cela rend code-reviewer for Code Review plus actionnable qu’un simple prompt, et plus facile à adapter aux pratiques de revue d’une équipe.

Quand code-reviewer est particulièrement adapté

Utilisez code-reviewer lorsque vous avez :

• un diff de branche par rapport à main
• une PR avec plusieurs fichiers ou des changements transverses
• un besoin de distinguer les bloqueurs de merge des améliorations facultatives
• des changements sensibles côté sécurité, comme l’auth, la gestion des entrées ou l’accès aux données
• une codebase où les conventions existantes comptent autant que les bonnes pratiques abstraites

Quand il est moins adapté

Cette skill est moins utile lorsque :

• il n’y a ni diff ni ensemble de fichiers à inspecter
• vous cherchez uniquement des remarques de style
• la tâche relève de la conception d’architecture plutôt que de la revue de code
• le contexte du repo n’est pas accessible, donc aucune comparaison avec les patterns existants n’est possible
• la demande concerne en réalité du debugging, de la réécriture ou de la planification de fonctionnalité

Comment utiliser la skill code-reviewer

Contexte d’installation de la skill code-reviewer

Le fichier SKILL.md amont ne publie pas de commande d’installation directe, mais la skill se trouve dans zhaono1/agent-playbook, sous skills/code-reviewer. Si votre runtime de skills prend en charge l’installation de skills GitHub depuis un chemin de dépôt ou une collection, installez-la depuis ce dépôt et sélectionnez la skill code-reviewer.

Un schéma courant ressemble à ceci :

npx skills add https://github.com/zhaono1/agent-playbook --skill code-reviewer

Si votre environnement utilise un autre installeur, le point clé reste le slug de la skill : code-reviewer.

Commencez par lire ces fichiers avant de vous y fier

Pour l’évaluer rapidement, lisez :

1. skills/code-reviewer/SKILL.md
2. skills/code-reviewer/README.md
3. skills/code-reviewer/references/checklist.md
4. skills/code-reviewer/references/security.md
5. skills/code-reviewer/references/patterns.md
6. skills/code-reviewer/scripts/review_checklist.py

Cet ordre compte. SKILL.md explique comment le workflow s’active, les références montrent les standards appliqués, et le script révèle comment le workflow prévoit de collecter des preuves dans le repo.

Quels inputs fournir pour que code-reviewer fonctionne bien

L’usage de code-reviewer est le plus solide quand vous fournissez :

• la branche de base, généralement main
• l’objectif de la PR ou le ticket lié
• les fichiers modifiés ou le diff complet
• les zones de risque qui vous préoccupent le plus
• le contexte framework ou langage
• si vous voulez une passe rapide ou une revue bloquante avant merge

Sans cela, la revue peut quand même fonctionner, mais elle restera plus générique.

Comment la skill collecte le contexte de revue

Le dépôt explicite clairement le flux de revue attendu :

• récupérer les fichiers modifiés avec git diff main...HEAD --name-only
• inspecter l’historique des commits avec git log main...HEAD --oneline
• inspecter le diff réel avec git diff main...HEAD
• lire la documentation voisine et des fichiers similaires pour comprendre les conventions locales

C’est important, car beaucoup de revues IA faibles sautent la collecte de contexte et passent directement à des bonnes pratiques abstraites. Cette skill est plus utile lorsqu’elle s’ancre d’abord dans ce qui a réellement changé.

Un template de prompt code-reviewer vraiment pratique

Utilisez plutôt un prompt de ce type :

Review this branch with the code-reviewer skill.

Base branch: main
Goal: add password reset flow for users
Priority areas: security, correctness, test gaps
Constraints: keep current API shape, do not request large refactors
Please classify findings by severity: critical, high, medium, low.
For each finding, cite the file, explain the risk, and suggest the smallest safe fix.

C’est bien meilleur que « review my code », car vous donnez à la skill la branche cible, l’intention produit, les priorités de revue et le format de retour attendu.

Inputs faibles vs inputs solides

Input faible :

Review this PR

Input plus solide :

Use code-reviewer on the diff against main.
Focus on auth flows, input validation, and regression risk.
Check whether tests cover unhappy paths and whether any existing project patterns were broken.
Flag only issues that are actionable before merge unless clearly marked as low severity.

La version plus solide améliore concrètement la qualité de sortie, car elle resserre le périmètre de revue, nomme les zones de risque et indique à l’agent jusqu’où aller dans ses jugements.

Workflow conseillé pour une vraie revue de PR

Un code-reviewer guide pragmatique ressemble à ceci :

1. Récupérer les fichiers modifiés et le diff.
2. Lire la description de la PR ou le ticket.
3. Échantillonner des fichiers adjacents pour comprendre les conventions.
4. Lancer la revue par catégorie : correction, sécurité, performance, qualité de code, tests, documentation, maintenabilité.
5. Regrouper les constats par gravité.
6. Demander une seconde passe sur les fichiers les plus risqués si la première revue a remonté des problèmes sérieux.

Cette approche en deux passes fonctionne bien : la première identifie les risques larges, la seconde améliore la précision.

Appuyez-vous sur les références pour éviter les revues génériques

Les fichiers de support sont la principale raison de choisir cette skill plutôt qu’un prompt classique :

• references/checklist.md rend la revue plus systématique
• references/security.md ajoute des contrôles orientés OWASP
• references/patterns.md fournit des exemples concrets de bonnes et mauvaises implémentations

Si une revue vous paraît vague, demandez explicitement à l’agent d’appliquer une ou plusieurs de ces références pendant l’analyse du diff.

Utilisez le script utilitaire si vous voulez une trame de revue

Le dépôt inclut :

python scripts/review_checklist.py

C’est utile si vous voulez une checklist générée automatiquement à partir de l’état Git courant avant de demander à l’agent des constats rédigés. C’est un pont pratique entre l’inspection brute du diff et une revue écrite complète.

Le format de sortie le plus utile en pratique

Demandez à la skill de renvoyer :

• un court résumé de ce qui a changé
• les bloqueurs de merge en premier
• les constats groupés par gravité
• des références au niveau fichier
• une justification, pas seulement un verdict
• une évaluation finale « safe to merge? » avec réserves

Ce format colle au modèle de gravité du dépôt et rend la revue plus exploitable dans un vrai workflow d’équipe.

FAQ sur la skill code-reviewer

code-reviewer est-elle meilleure qu’un prompt de revue classique

En général oui, si vous avez un vrai contexte de repo. La valeur de code-reviewer ne vient pas d’une profondeur d’analyse « magique » à elle seule. Elle vient de la combinaison de signaux d’activation, d’un workflow par étapes, d’une couverture par checklist et de matériaux de référence qui poussent la revue vers plus d’exhaustivité et de cohérence.

code-reviewer est-elle accessible aux débutants

Oui, avec une réserve : les débutants doivent quand même fournir du contexte. La skill donne une structure forte, mais elle ne peut pas déduire à partir de rien les exigences, le comportement attendu ou les conventions d’équipe. Les nouveaux utilisateurs obtiendront de meilleurs résultats s’ils indiquent dès le départ l’objectif de la PR et la branche de base.

code-reviewer fonctionne-t-elle uniquement pour les pull requests

Non. L’usage de code-reviewer convient aussi à des diffs de branche locale, à un ensemble de fichiers modifiés, ou à une demande de revue ciblée sur un dossier comme « review the code in src/auth/ ». Elle est simplement plus performante lorsqu’il existe un diff clair par rapport à une branche de base connue.

Quels types de problèmes la skill code-reviewer recherche-t-elle

Les éléments du dépôt montrent une couverture de :

• la correction et les cas limites
• les problèmes de sécurité, y compris des points de vigilance de type OWASP
• les problèmes de performance comme des requêtes ou appels inutiles
• la qualité de code et la maintenabilité
• les lacunes de tests
• les lacunes de documentation

Cette largeur de couverture la rend adaptée à une revue générale de PR, et pas seulement à une revue sécurité ou style.

Quand ne pas utiliser code-reviewer

Évitez code-reviewer lorsque la tâche consiste principalement à :

• générer du nouveau code
• déboguer une panne à l’exécution
• planifier une architecture à grande échelle
• faire uniquement du nettoyage de formatage ou de lint
• revoir du code sans accès au contexte des changements

Dans ces cas-là, une skill plus spécialisée ou un prompt directement centré sur la tâche sera un meilleur choix.

Imposera-t-elle un seul style de code

Non. Le dépôt encourage à vérifier les patterns existants dans des fichiers similaires avant de juger un changement. C’est un bon signal pour l’adoption, car cela réduit les conseils génériques qui entrent en conflit avec les conventions locales.

Comment améliorer la skill code-reviewer

Donnez à code-reviewer l’intention derrière le changement

Le plus gros levier de qualité, c’est d’expliquer ce que le code est censé faire. La qualité de revue chute vite lorsque l’agent ne voit que l’implémentation. Ajoutez le résumé du ticket, les critères d’acceptation ou une note d’intention d’un paragraphe afin que la skill puisse juger la correction, et pas seulement le style et la syntaxe.

Ciblez les zones de revue les plus risquées

Si vos priorités concernent surtout l’auth, la facturation, les migrations ou la concurrence, dites-le. La skill couvre déjà plusieurs catégories, mais des priorités ciblées augmentent la profondeur là où cela compte. C’est particulièrement important pour les grosses PR, où une revue trop large devient vite superficielle.

Fournissez assez de contexte repo pour comparer les patterns

Ce dépôt indique explicitement au reviewer de s’appuyer sur les conventions existantes. Aidez-le en nommant des fichiers ou modules comparables :

Compare the new handler to the existing patterns in src/api/users/ and src/api/sessions/.
Prefer consistency with those files unless there is a clear bug.

Cela réduit les faux positifs et rend les suggestions plus faciles à adopter.

Demandez uniquement des constats étayés par des preuves

Un mode d’échec fréquent dans les revues IA est la critique spéculative. Pour améliorer la sortie de code-reviewer, imposez une règle du type :

Only report an issue if you can point to a specific file change, missing case, or concrete risk. Avoid hypothetical style advice unless it affects maintainability or correctness.

Cela maintient la revue à un niveau de signal élevé.

Découpez les grosses revues en plusieurs passes

Pour les grosses PR, ne demandez pas tout d’un coup. Travaillez par étapes :

1. correction et sécurité
2. performance et maintenabilité
3. tests et documentation

Cela reflète la structure par catégories de la skill et produit généralement de meilleurs constats qu’une requête unique surchargée.

Demandez des recommandations de correction plus petites

Si la première sortie reste trop abstraite, demandez à la skill de reformuler les constats en corrections minimales et sûres :

Revise the review. For each high or critical issue, suggest the smallest code change or test addition that would reduce the risk before merge.

La revue devient alors plus actionnable pour des équipes déjà très sollicitées.

Surveillez les modes d’échec les plus courants

Les cas les plus fréquents où la sortie de la code-reviewer skill devient faible sont :

• aucune branche de base précisée
• aucun diff fourni
• aucune explication du comportement attendu
• des PR énormes sans priorités
• aucune référence aux patterns du projet
• une demande de « tout couvrir », qui renvoie en retour des conseils génériques

Dans la plupart des cas, le problème vient des inputs, pas de la skill.

Utilisez explicitement la checklist et les références sécurité

Si votre première revue est trop large, demandez une seconde passe en vous appuyant sur des références précises du repo :

• references/checklist.md pour l’exhaustivité
• references/security.md pour les changements sensibles
• references/patterns.md pour la cohérence et la détection d’anti-patterns

C’est l’un des moyens les plus simples d’améliorer le code-reviewer guide au quotidien.

Itérez après la première revue

Un bon deuxième prompt est :

Now re-review only the files with high-severity findings.
Assume the author wants merge-blocking issues only.
Double-check whether each finding is a real defect, a security exposure, or a missing test that hides regression risk.

Ce suivi élimine souvent les commentaires de faible valeur et affine la recommandation finale.

Adaptez code-reviewer au workflow de votre équipe

Si vous adoptez code-reviewer régulièrement, alignez-la sur votre culture de merge :

• définissez ce qui compte comme bloqueur vs suggestion
• précisez votre convention de branche de base
• indiquez vos attentes sur les tests
• ajoutez vos contrôles de sécurité spécifiques à l’équipe
• orientez la skill vers des fichiers représentatifs du style local

C’est ainsi qu’on transforme code-reviewer install en véritable amélioration de workflow, plutôt qu’en simple raccourci de prompt.