annotate-merge-request

Annnote une demande de fusion / pull request avec des explications destinées aux relecteurs sur les changements générés par l'IA : intention, comportement avant/après et graphe de points d'entrée vérifié, le tout sous forme d'un commentaire global, d'un commentaire par fichier modifié et de commentaires en ligne sur les parties vraiment non évidentes, le tout maintenu à jour après chaque push.

Qu'est-ce que annotate-merge-request ?

Cette compétence automatisé la création d'annotations complètes pour les demandes de fusion (MR/PR) générées par l'IA, afin de les rendre facilement relisables sans allers-retours de questions-réponses. Elle produit trois couches de commentaires : un commentaire global résumant l'intention, le comportement avant/après et le graphe d'appel ; un commentaire par fichier modifié (sauf fichiers autogénérés) expliquant le rôle du changement ; et des commentaires en ligne uniquement sur les parties non évidentes, avec un budget maximum de 3 par fichier et 12 par MR. La compétence supporte GitLab, GitHub et Bitbucket, et fonctionne en deux modes : `annotate` pour une première exécution, et `sync` pour mettre à jour les annotations après chaque push. Elle utilise un système de marqueurs HTML invisibles pour identifier ses propres commentaires et les maintenir à jour, et vérifie le graphe d'appel par des recherches réelles dans le code pour éviter toute fabrication.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kirill-kolomin/self-descriptive-merge-requests/tree/main/skills/annotate-merge-request

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

Annoter une demande de fusion pour les relecteurs

Un relecteur qui lit un diff généré par l'IA passe la majeure partie de son temps à reconstruire trois choses que l'auteur connaissait déjà : pourquoi ce changement existe, quel comportement a changé, et qui appelle ce code. Cette compétence écrit ces trois choses, en langage naturel, au niveau de la demande de fusion - pas comme des commentaires dans le code source.

Les annotations se présentent en trois couches, avec des règles différentes :

CoucheCouverturePorte
Vue d'ensemble - un commentaire au niveau de la MRtoujoursla carte de l'ensemble du changement
Fichier - un commentaire par fichier modifiétoujours, sauf fichiers autogénérésce que signifie ce changement de fichier
En ligne - ancré à une ligne du diffuniquement les parties vraiment non évidentes, avec budgetpourquoi ce code particulier est comme ceci

La couverture par fichier est inconditionnelle : un relecteur ouvrant n'importe quel fichier du diff doit trouver une explication. Le jugement - ce qui mérite d'être expliqué et ce qui est évident - s'applique au sein d'un fichier, aux méthodes et aux blocs de diff individuels, jamais au fait que le fichier soit couvert ou non.

Modes de fonctionnement

ModeQuandCe qu'il fait
annotatePremière exécution sur une MRConstruit l'ensemble complet des annotations, les prévisualise, les publie après approbation
syncAprès chaque push sur la branche de la MRRevérifie les annotations existantes par rapport au nouveau diff ; met à jour, supprime ou ajoute uniquement ce qui a changé

Si des annotations de cette compétence existent déjà sur la MR (détectées par marqueur, voir §7), exécutez sync, pas annotate - réexécuter annotate duplique les commentaires.

1. Pré-vérification

Établir, avant d'écrire quoi que ce soit :

  1. Plateforme et identité de la MR. git remote -v → gitlab.com/GitLab auto-hébergé, github.com, ou Bitbucket. Ensuite, trouver la MR ouverte pour la branche actuelle (glab mr view, gh pr view). S'il n'y a pas encore de MR, arrêtez-vous et dites-le - cette compétence annote une MR existante ; elle n'en crée pas.
  2. Plage du diff. Toujours git merge-base HEAD origin/<branche-cible> → <base>..HEAD. Ne faites jamais de diff par rapport au sommet nu de la branche cible : des commits non liés arrivés sur la cible apparaîtraient comme des changements de cette MR.
  3. Langue. Écrivez les annotations dans la langue que les MR du projet utilisent déjà (vérifiez les descriptions et commentaires des MR/PR existantes). Par défaut, utilisez la langue dans laquelle l'utilisateur s'adresse à vous.
  4. Autorisation de publication. Publier sur une MR est visible par toute l'équipe et notifie les relecteurs. Par défaut, faites un aperçu à sec dans la conversation et publiez uniquement après approbation de l'utilisateur. Ignorez l'aperçu uniquement si l'utilisateur a déjà dit de publier sans demander.

Lisez references/platform-gitlab.md, references/platform-github.md, ou references/platform-bitbucket.md pour les commandes exactes - les API de commentaires diffèrent de manière significative (ancrage au niveau du fichier, résolvabilité, sémantique de mise à jour).

2. Construire l'inventaire des changements

Les deux scripts se trouvent à côté de ce fichier, dans scripts/. Invoquez-les par chemin absolu, construit à partir du répertoire de cette compétence - le répertoire de travail lors d'une exécution est le dépôt de l'utilisateur, pas la compétence, donc un chemin nu scripts/... échoue. Ci-dessous, $SKILL désigne le répertoire contenant ce SKILL.md (par exemple ~/.claude/skills/annotate-merge-request pour une installation au niveau de l'utilisateur, ou skills/annotate-merge-request du plugin lorsqu'il est chargé depuis un plugin).

python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json

Par fichier modifié, cela donne : type de changement (ajouté/modifié/supprimé/renommé), requires_file_comment (faux uniquement pour les fichiers autogénérés/vendus), une file_fingerprint, et les blocs du fichier avec les numéros de ligne du côté nouveau (ce à quoi les commentaires en ligne doivent s'ancrer), le symbole englobant le plus proche, et les signaux de trivialité. Pour les fichiers de spécifications et de tests, cela émet également test_cases - chaque cas dans le fichier avec son statut (unchanged / adapted / added / removed), calculé en comparant les corps des cas entre les deux révisions plutôt qu'en lisant le diff. C'est une carte heuristique pour votre lecture, pas un substitut - lisez le diff réel pour tout ce que vous allez décrire.

L'anchor de chaque bloc est une suggestion (sa première ligne ajoutée) ; added_lines liste toutes les lignes de ce bloc auxquelles vous pourriez vous ancrer à la place. Choisissez la ligne à propos de laquelle l'explication porte réellement.

Contrainte forte : un commentaire en ligne ne peut s'ancrer qu'à une ligne qui apparaît dans le diff. Ni GitLab ni GitHub ne permettent de commenter du code non touché loin d'un bloc. Tout ce que vous voulez dire sur du code que la MR n'a pas touché va dans le commentaire du fichier ou de la vue d'ensemble, jamais en ligne.

3. Couche 1 - couvrir chaque fichier modifié

Chaque fichier que l'inventaire marque requires_file_comment: true reçoit exactement un commentaire au niveau du fichier. Pas d'exceptions, pas de budget, pas de jugement sur le fait qu'il soit "assez intéressant".

La seule exemption concerne les fichiers de sortie autogénérés et vendus - lockfiles, dist/, snapshots, codegen, bundles minifiés, vendor/. L'inventaire les signale ; s'il en manque un que votre projet génère, exemptez-le aussi et dites à l'utilisateur quel motif ajouter.

Ce qui varie, c'est la forme et la longueur, pas l'existence :

  • Un fichier avec des changements de logique réels reçoit le modèle complet (references/annotation-format.md) : rôle, pourquoi il a changé, avant → après, appelé depuis.
  • Un fichier de spécifications ou de tests reçoit une liste de cas de test à la place - chaque cas qu'il contient maintenant, chacun avec un statut (unchanged / adapted / added / removed) et, pour ceux qui ont changé, une courte description. Le modèle standard est erroné pour les spécifications : rien ne les appelle, donc la section des points d'entrée est vide par construction. L'inventaire calcule les statuts pour vous (test_cases par fichier) ; les cas adapted sont ceux dont un relecteur a le plus besoin, donc ils viennent en premier et doivent dire si la forme de l'appel ou l'attente a changé. Règles complètes dans references/annotation-format.md.
  • Un fichier mécanique reçoit une ligne qui permet au relecteur de le passer en toute confiance : Uniquement les chemins d'importation - suite au renommage de PricingService ; aucun changement de comportement.
  • Un fichier supprimé reçoit une ligne sur pourquoi il a disparu et ce qui l'a remplacé - souvent l'annotation la plus utile dans une MR.

Ancrez-les comme des commentaires au niveau du fichier (subject_type=file sur GitHub, position_type=file sur GitLab), pas sur une ligne. Ils se fixent à l'en-tête du fichier, donc ils ne s'intercalent pas avec le code et le relecteur les rencontre en ouvrant chaque fichier. Lorsqu'une instance ne prend pas en charge l'ancrage au niveau du fichier, revenez à la première ligne modifiée du fichier - les références de la plateforme donnent le repli exact.

Bien écrire des lignes uniques est toute la compétence ici. Le volume évolue maintenant avec le nombre de fichiers, donc un fichier mécanique décrit en trois paragraphes est un défaut, pas une rigueur.

4. Couche 2 - le commentaire de vue d'ensemble

Un commentaire au niveau de la MR, point d'entrée pour toute la relecture, structuré exactement comme spécifié dans references/annotation-format.md :

  • Intention - quel problème cette MR résout, en deux ou trois phrases, en langage naturel. Ne reformulez pas le diff.
  • Comportement avant → après - ce qu'un observateur du système en cours d'exécution remarquerait. Pour un nouveau composant, dites "nouveau" plutôt que d'inventer un "avant".
  • Graphe des points d'entrée - comment un lecteur atteint le code modifié à partir d'un point d'entrée réel (route HTTP, commande CLI, gestionnaire d'événements, cron, API exportée). Limité à 3 niveaux ; une ligne par zone modifiée, pas par fichier.
  • Ordre de lecture - quel fichier ouvrir en premier, lesquels sont des suivis mécaniques.
  • Index des commentaires en ligne - liens vers chaque annotation en ligne.

La vue d'ensemble a ses propres limites de volume (max 7 entrées d'ordre de lecture, max 5 lignes de comportement, pas d'énumération par fichier - les commentaires de fichier font ça). Elles sont dans references/annotation-format.md ; respectez-les, ou la vue d'ensemble devient le mur de texte que les commentaires de fichier étaient censés empêcher.

Vérifier le graphe des points d'entrée

Ne devinez jamais un graphe d'appel. Une liste d'appelants fabriquée est pire qu'aucune annotation : elle est faussement confiante et le relecteur lui fera confiance. Pour chaque arête revendiquée, trouvez l'appelant avec une recherche réelle (rg -n 'NomDuSymbole' dans tout le dépôt, y compris les tests et la configuration), et remontez jusqu'à atteindre un point d'entrée ou 3 niveaux, selon ce qui vient en premier. Si les appelants d'un symbole ne peuvent pas être résolus - dispatch dynamique, conteneur DI, réflexion, registre à clé de chaîne - écrivez point d'entrée non résolu (<raison>) plutôt qu'une chaîne plausible.

5. Couche 3 - commentaires en ligne, uniquement là où le code n'est pas évident

C'est la seule couche qui fait appel à un jugement. Exécutez le test de signification de references/significance-test.md sur chaque méthode et chaque bloc. La version courte :

Annotez quand le lecteur pourrait raisonnablement demander "pourquoi c'est comme ça ?" - une intention non évidente, un changement de comportement qui n'est pas visible dans le diff, une conséquence non locale, un compromis délibéré, un algorithme inhabituel, un contournement, une contrainte extérieure au fichier, ou une interaction avec un autre changement de cette même MR.

Ignorez quand le code s'explique de lui-même pour un lecteur compétent de cette base de code : une aide de 5 à 10 lignes qui met en majuscule les titres d'une chaîne, une constante DEBOUNCE_MS = 300, une vérification nulle évidente, une mise à jour mécanique de test. Le commentaire du fichier couvre déjà le fichier ; un commentaire en ligne ici le répéterait avec moins de valeur.

La taille du code n'est pas le test - sa distance inférentielle l'est. Une aide de 6 lignes dans un système d'encodage personnalisé a besoin d'un commentaire ; un fichier de snapshot généré de 200 lignes n'en a pas.

Budgets (valeurs par défaut ; l'utilisateur peut les augmenter explicitement) :

  • Au maximum 3 commentaires en ligne par fichier, au maximum 12 par MR.
  • Ce sont des plafonds, pas des quotas. Un fichier dont l'histoire est entièrement racontée par son commentaire de fichier reçoit zéro commentaire en ligne, et c'est le cas normal.
  • Dépassez un budget est un signal, pas une permission : si plus de 12 endroits dans une MR sont vraiment non évidents, la MR est trop grande, ou l'explication appartient à la vue d'ensemble où elle peut être racontée comme une seule histoire. Dites-le à l'utilisateur.

Chaque annotation en ligne utilise les mêmes sections que le commentaire de fichier, limitées à ce bloc, et reste courte - 3 à 6 lignes, lues dans une vue de diff exiguë.

6. Références croisées au sein de la MR

Lorsqu'un changement n'a de sens qu'avec un autre changement de la même MR, liez-les. Les références croisées appartiennent généralement au graphe des points d'entrée, mais apparaissent aussi dans l'intention ("nécessaire parce que passe maintenant X") et dans l'avant/après ("l'ancien chemin existe toujours, voir "). Les commentaires de fichier sont l'endroit le plus naturel pour elles : Ce nouveau contrat du fichier est consommé par [[ref:order-controller]].

Une URL de commentaire n'existe pas tant que le commentaire n'est pas publié, donc les références croisées nécessitent deux phases :

  1. Publiez chaque commentaire avec un jeton d'espace réservé ([[ref:<slug>]]) là où un lien vers une autre annotation doit aller.
  2. Collectez les identifiants/URL des commentaires créés, puis modifiez chaque corps, en remplaçant les jetons par de vrais liens.

Planifiez les slugs avant de publier - chaque jeton [[ref:...]] doit être résolu en phase 2, et un jeton résiduel dans un commentaire publié est un défaut visible. La phase 2 n'est pas facultative.

7. Publier, avec un marqueur d'identité

Chaque commentaire créé par cette compétence se termine par une ligne de marqueur invisible dans le rendu markdown :

<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<fichier> ffp=<empreinte-fichier> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<fichier>@<nouvelle-ligne> fp=<empreinte-bloc> -->

Utilisez la file_fingerprint de l'inventaire pour ffp= et l'fingerprint du bloc pour fp=. Le marqueur est ce qui rend possible sync : il identifie les propres commentaires de la compétence, à quoi chacun était attaché, et l'empreinte du code qu'il décrivait. Ne publiez jamais une annotation sans un ; ne modifiez jamais le commentaire d'un humain.

Laissez les annotations non résolues. Un fil résolu s'affiche réduit, donc le relecteur devrait développer chaque annotation une par une - ce qui cache exactement ce que l'annotation existe pour montrer. Publiez-les ouvertes et laissez le relecteur résoudre chacune en la lisant ; ce clic est leur propre marqueur "lu".

Le coût de ce choix : là où le projet exige que tous les fils soient résolus avant la fusion (Tous les fils doivent être résolus de GitLab, Exiger la résolution de la conversation de GitHub), les annotations doivent être résolues avant que le bouton de fusion ne soit débloqué. Avec un commentaire de fichier par fichier, cela représente un nombre réel de clics, donc dites à l'utilisateur lorsque vous détectez un tel paramètre, et proposez de tout résoudre en masse à la fin. Les commandes pour les deux sont dans les fichiers de référence de la plateforme.

8. Synchronisation après chaque push

De nouveaux commits invalident silencieusement les annotations : le code qu'un commentaire décrit peut avoir bougé, changé de sens, ou disparu - et de nouveaux fichiers arrivent sans aucune couverture. Réexécutez cette compétence en mode sync après chaque push sur la branche de la MR.

python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json

--comments est répétable et prend le JSON brut de la plateforme tel quel - sur GitHub, cela nécessite deux appels (commentaires de révision et commentaires de problème), donc passez les deux fichiers.

Il classe chaque annotation existante comme ok (ancre et empreinte inchangées - laissez-la tranquille), moved (même code, nouvelle ligne - ré-ancrez), stale (le code qu'elle décrivait a changé - relisez et réécrivez), ou orphaned (le fichier ou le bloc a disparu - supprimez). Il rapporte également file coverage - quels fichiers modifiés n'ont toujours pas de commentaire au niveau du fichier, lesquels sont exemptés - et les blocs uncovered qui sont maintenant candidats pour un commentaire en ligne.

Ensuite : corrigez uniquement ce qui a été signalé, réécrivez toujours le commentaire de vue d'ensemble sur place (il résume toute la MR, donc tout push peut l'invalider), et réexécutez la phase 2 du §6 pour que les liens de références croisées pointent encore vers des commentaires vivants. Une ligne MISSING dans la couverture des fichiers n'est pas un travail facultatif - un nouveau fichier sans commentaire est la seule lacune que cette compétence existe pour empêcher. Suivez references/sync-after-push.md pour le cas du force-push, la gestion des commentaires supprimés par plateforme, et comment éviter de churner les commentaires qui n'ont pas réellement changé.

Mentionnez à l'utilisateur, une fois, que cela doit être exécuté après chaque push, et que references/sync-after-push.md a un hook pre-push facultatif.

Skills associés