requesting-code-review

Vue d’ensemble

Ce que fait cette compétence

La compétence requesting-code-review définit un flux de travail clair et reproductible pour demander à un sous-agent de revue de code IA d’inspecter vos changements avant qu’ils n’atterrissent. Elle est conçue pour les projets basés sur Git et vous aide à :

• Décider quand demander une revue (après les tâches, les fonctionnalités, et avant le merge)
• Regrouper un contexte précis pour le relecteur en utilisant des Git SHAs et des exigences
• Garder le relecteur concentré sur le diff du code, et non sur l’historique privé de votre session
• Classer les retours par sévérité pour savoir quoi corriger maintenant vs. plus tard

Au cœur, requesting-code-review repose sur le principe revoir tôt, revoir souvent afin de détecter les problèmes avant qu’ils ne se propagent dans votre base de code.

À qui cette compétence s’adresse

Cette compétence est bien adaptée si vous :

• Travaillez avec Git et créez régulièrement des branches de fonctionnalité ou des PR
• Souhaitez une manière structurée et reproductible de demander une revue de code assistée par IA
• Utilisez un développement piloté par sous-agents (par exemple, un agent dédié code-reviewer)
• Êtes attentif à la préparation à la production : exactitude, architecture, tests et alignement avec les spécifications

Elle est particulièrement utile pour :

• Les développeurs individuels qui veulent un filet de sécurité fiable
• Les petites équipes sans relecteur de code dédié
• Les projets où l’historique de commits et les diffs sont la principale source de vérité

Quand ce n’est pas le bon choix

requesting-code-review n’est peut‑être pas idéal si :

• Vous n’utilisez pas Git ou n’avez pas accès aux commit SHAs
• Vous cherchez de l’aide générale pour générer ou refactorer du code, et non une revue de changements spécifiques
• Vous ne pouvez pas fournir de plan, de spécification ou d’exigences claires pour les changements à relire

Dans ces cas, vous aurez sans doute intérêt à utiliser une compétence plus générale de codage ou de planification plutôt qu’un flux dédié à la revue.

Problèmes résolus

Sans processus de revue cohérent, les développeurs :

• Oublient souvent de demander une revue à des moments clés
• Partagent trop peu de contexte (ou au contraire beaucoup trop d’historique de session)
• Reçoivent des retours non structurés et difficiles à exploiter

La compétence requesting-code-review résout ces problèmes en :

• Définissant des points de passage obligatoires et optionnels pour la revue
• Standardisant les informations à fournir pour la revue (plage Git, exigences, résumé)
• S’appuyant sur un sous-agent code-reviewer dédié qui renvoie des retours classés par sévérité

Guide d’utilisation

Installation

Pour installer la compétence requesting-code-review depuis le dépôt obra/superpowers, utilisez la Skills CLI :

npx skills add https://github.com/obra/superpowers --skill requesting-code-review
``

Cela récupère la définition de la compétence ainsi que ses fichiers de support, y compris le modèle de sous-agent `code-reviewer`.

Après l’installation, ouvrez le répertoire de la compétence et commencez par parcourir ces fichiers :

- `SKILL.md` – description générale et étapes du flux de demande de revue de code
- `code-reviewer.md` – le prompt/modèle de l’agent qui réalise concrètement la revue

### Vue rapide du flux de travail principal
Le flux `requesting-code-review` comporte trois grandes phases :

1. **Décider quand lancer une revue**
   - Après chaque tâche dans un flux piloté par sous-agents
   - Après avoir terminé une fonctionnalité majeure
   - Avant de merger sur votre branche principale
2. **Préparer le contexte de revue**
   - Capturer la plage de commits Git avec `BASE_SHA` et `HEAD_SHA`
   - Résumer ce qui a été implémenté et ce que cela est censé faire
   - Renseigner les placeholders définis dans `code-reviewer.md`
3. **Lancer la revue et traiter les retours**
   - Déclencher le sous-agent `superpowers:code-reviewer`
   - Corriger immédiatement les problèmes Critical, corriger les Important avant de continuer, et consigner les Minor

### Étape 1 : Identifier le bon moment pour la revue
Selon `SKILL.md`, utilisez `requesting-code-review` :

**Points de passage obligatoires :**

- **Après chaque tâche** dans un développement piloté par sous-agents
- **Après avoir terminé une fonctionnalité majeure**
- **Avant de merger** sur votre branche principale (par exemple `main`, `master`)

**Points de passage optionnels mais précieux :**

- Quand vous êtes **bloqué** et avez besoin d’un regard neuf
- **Avant un refactoring**, en tant qu’état de référence du comportement actuel
- Après la correction d’un **bug complexe**, pour vérifier l’absence de régressions ou de nouveaux problèmes

Ancrez l’habitude de déclencher cette compétence à ces moments, afin que les revues deviennent automatiques plutôt qu’un ajout de dernière minute.

### Étape 2 : Capturer la plage de commits Git
Le relecteur a besoin d’un diff propre et bien délimité. Utilisez les Git SHAs pour spécifier la plage :

```bash
BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

• BASE_SHA doit pointer vers le commit qui représente votre point de départ, par exemple le commit précédent ou la tête de origin/main.
• HEAD_SHA doit être le commit qui contient votre travail le plus récent.

Vous pouvez ajuster HEAD~1 ou choisir un autre point de base en fonction de votre stratégie de branches, du moment que la plage capture précisément les changements que vous voulez faire relire.

Étape 3 : Préparer le modèle de demande de revue

Le fichier code-reviewer.md définit comment dialoguer avec le Code Review Agent. Il utilise des placeholders que vous devez renseigner avant de déclencher le sous-agent.

Placeholders clés :

• {WHAT_WAS_IMPLEMENTED} – Une description concise de ce que vous venez de développer ou modifier
• {PLAN_OR_REQUIREMENTS} – La spécification, le ticket ou les exigences métier que l’implémentation doit respecter
• {BASE_SHA} – Le commit SHA de départ pour le diff
• {HEAD_SHA} – Le commit SHA de fin pour le diff
• {DESCRIPTION} – Un court résumé de l’ensemble de changements (par ex. "Add verification function and tests for user signups")
• {PLAN_REFERENCE} – Une référence vers votre document de plan ou d’exigences

Dans vos propres outils, remplissez ces placeholders avant de déclencher le sous-agent superpowers:code-reviewer avec l’outil Task.

Étape 4 : Déclencher le sous-agent code-reviewer

Une fois vos Git SHAs et le modèle complété :

1. Utilisez l’outil Task de votre environnement d’orchestration (tel que décrit dans le framework superpowers) avec le type superpowers:code-reviewer.

2. Passez le contenu rendu de code-reviewer.md, avec les placeholders remplacés par vos vraies valeurs.

3. Assurez-vous que l’agent peut accéder au diff Git pour la plage :

   git diff --stat {BASE_SHA}..{HEAD_SHA}
   git diff {BASE_SHA}..{HEAD_SHA}
   

   Le modèle indique ces commandes pour que le relecteur se concentre strictement sur les changements entre BASE_SHA et HEAD_SHA.

La conception de cette compétence garantit que l’agent de revue ne voit que le produit de votre travail (commits et diff), et non l’historique plus large de votre session ou du contexte sans lien.

Étape 5 : Interpréter et exploiter les retours

Le modèle code-reviewer.md demande à l’agent de :

• Évaluer la qualité du code (séparation des responsabilités, gestion des erreurs, DRY, cas limites)
• Évaluer l’architecture (conception, scalabilité, performance, sécurité)
• Vérifier les tests (couverture, points d’intégration, qualité des tests)
• Vérifier les exigences (alignement avec la spec, absence de dérapage de scope, changements cassants documentés)
• Juger la préparation à la production (migrations, rétrocompatibilité, documentation)

Les retours sont répartis en :

• Critical (Must Fix) – Bugs, failles de sécurité, risques de perte de données, fonctionnalité cassée
• Important (Should Fix) – Problèmes d’architecture, fonctionnalités manquantes, mauvaise gestion des erreurs, trous dans les tests
• Minor (Nice to Have) – Style, optimisations, améliorations de documentation

Le flux associé décrit dans SKILL.md est :

• Corriger les problèmes Critical immédiatement avant de continuer
• Corriger les problèmes Important avant de poursuivre le travail ou de merger
• Noter les problèmes Minor pour du nettoyage ultérieur ou des tâches de suivi
• Contester les retours, avec des arguments, si le relecteur se trompe ou manque de contexte

En suivant cette priorisation, vous transformez les retours de l’IA en une liste d’actions concrète plutôt qu’en un ensemble de suggestions vagues.

Exemple de schéma d’utilisation

Une utilisation typique de requesting-code-review peut ressembler à ceci :

1. Vous terminez "Task 2: Add verification function" sur votre branche de fonctionnalité.

2. Vous capturez les SHAs :

   BASE_SHA=$(git rev-parse origin/main)
   HEAD_SHA=$(git rev-parse HEAD)
   

3. Vous remplissez les placeholders de code-reviewer.md avec :

   • {WHAT_WAS_IMPLEMENTED} = "Verification function for user email flow"
   • {PLAN_OR_REQUIREMENTS} = Lien ou résumé du ticket/exigences
   • {BASE_SHA} et {HEAD_SHA} = Les valeurs issues de Git
   • {DESCRIPTION} = "Implement email verification and add tests for edge cases"

4. Vous déclenchez le sous-agent superpowers:code-reviewer à l’aide de votre outil Task.

5. Vous recevez des retours structurés regroupés en Critical, Important et Minor.

6. Vous traitez les problèmes Critical et Important, puis relancez éventuellement le processus avant de merger.

FAQ

Est-ce que requesting-code-review ne fonctionne que pour les dépôts GitHub ?

Non. La compétence requesting-code-review est basée sur Git, pas spécifique à GitHub. Elle repose sur les commit SHAs et les commandes git diff, donc elle fonctionne avec n’importe quel remote Git (GitHub, GitLab, Bitbucket ou auto‑hébergé) tant que vous pouvez fournir BASE_SHA et HEAD_SHA.

Dois-je partager tout l’historique de ma session de développement ?

Non. Un principe de conception clé de requesting-code-review est que le relecteur ne reçoit qu’un contexte strictement ciblé : ce qui a été implémenté, les exigences, et le diff Git. L’historique général de votre session et votre réflexion interne restent privés, tandis que le relecteur se concentre sur les changements de code réels.

Quand dois-je déclencher requesting-code-review dans mon flux de travail ?

Utilisez requesting-code-review :

• Après chaque tâche dans un développement piloté par sous-agents
• Après avoir terminé une fonctionnalité majeure
• Avant de merger sur votre branche principale

Vous pouvez aussi le déclencher lorsque vous êtes bloqué, avant de gros refactorings, ou après des corrections de bugs complexes, afin de détecter tôt les risques cachés.

Comment cela s’intègre-t-il avec mes revues de pull request existantes ?

requesting-code-review vient en complément, et non en remplacement, des revues de PR humaines. Vous pouvez :

• Lancer la compétence avant d’ouvrir une PR pour éliminer les problèmes évidents
• L’utiliser en parallèle des relecteurs humains pour améliorer la couverture et la cohérence
• Réutiliser ses catégories de retours structurés (Critical/Important/Minor) dans vos commentaires de PR

Comme la compétence est construite autour de plages Git, elle s’intègre naturellement dans les flux de travail basés sur les PR.

Puis-je personnaliser le comportement de l’agent code-reviewer ?

Oui. Le fichier code-reviewer.md est un modèle que vous pouvez adapter :

• Ajuster les checklists pour la qualité du code, l’architecture, les tests ou la sécurité
• Ajouter des préoccupations propres à votre projet (par ex. règles métier, budgets de performance)
• Affiner le format de sortie si vous souhaitez d’autres niveaux de sévérité ou des sections supplémentaires

Conservez simplement la structure de base (tâche claire, plage Git et catégories de sévérité) pour que la revue reste ciblée et exploitable.

Que faire si le relecteur propose quelque chose d’erroné ?

La compétence vous incite explicitement à répondre et argumenter lorsque le relecteur se trompe ou manque de contexte. Traitez la revue comme une recommandation forte, pas comme un verdict incontestable. Précisez les contraintes, expliquez les arbitrages effectués ou mettez à jour votre plan afin que les futures revues soient mieux alignées.

Est-ce que requesting-code-review génère des tests ou des changements de code pour moi ?

Non. Cette compétence concerne la revue, pas la génération. Elle vous aide à :

• Demander une revue ciblée de changements spécifiques
• Recevoir des retours structurés sur la qualité, l’architecture et les tests

Vous restez responsable de l’implémentation des corrections et de l’écriture des tests, même si vous pouvez combiner cette compétence avec d’autres compétences de codage ou de génération de tests dans votre toolchain.

Comment démarrer rapidement ?

1. Installez la compétence :

   npx skills add https://github.com/obra/superpowers --skill requesting-code-review
   

2. Lisez SKILL.md pour comprendre les points de passage de revue.

3. Passez en revue code-reviewer.md pour voir la checklist de l’agent et le format de sortie.

4. Exécutez votre prochaine tâche ou fonctionnalité, capturez BASE_SHA et HEAD_SHA, puis déclenchez le sous-agent superpowers:code-reviewer.

À partir de là, affinez le modèle et le flux de travail pour que requesting-code-review corresponde aux habitudes et au niveau d’exigence de votre équipe.