BatchCodes/commentaires-en-regles

Commentaires en règles

Cette compétence transforme l'historique des commentaires de revue de code de PR d'un dépôt en fichiers de règles de style de codage par langage. Elle ajoute des règles déduites du code source local. Elle propose ensuite d'exécuter une revue basée sur le résultat.

Exécutez cette compétence sur un dépôt cible : le répertoire dans lequel l'utilisateur travaille actuellement, ou un chemin ou un dépôt distant qu'il nomme. Cette compétence réside dans un dépôt séparé. Vous l'exécutez une fois, à la demande. Elle ne s'installe pas dans le dépôt cible.

Quand utiliser cette compétence

• L'utilisateur demande de générer, construire ou mettre à jour des règles de style à partir de l'historique des revues de PR.
• L'utilisateur souhaite remplir .claude/rules/ à partir des retours de revue de code passés plutôt que de les écrire à la main.
• L'utilisateur demande quelles conventions ses réviseurs appliquent réellement et veut les transformer en quelque chose qu'un agent peut suivre.

N'utilisez pas cette compétence pour revoir une PR ou un diff spécifique — utilisez code-review pour cela. Ne l'utilisez pas pour de la documentation générale de dépôt — utilisez init pour cela.

Prérequis

Vérifiez ces éléments avant de commencer. Si une vérification échoue, arrêtez-vous et donnez un message clair.

• gh est installé et authentifié (gh auth status).
• jq est installé.
• Le répertoire cible est un dépôt git avec un dépôt distant GitHub (gh repo view réussit ici).

Si gh auth status échoue, n'exécutez pas gh auth login ou gh auth refresh vous-même. Dites à l'utilisateur de les exécuter, puis arrêtez-vous. Ces commandes peuvent ouvrir un flux de navigateur interactif ou une invite de code d'appareil — seul l'utilisateur doit les lancer.

Procédure

Étape 1 — Récupérer les commentaires de revue des PR fusionnées

Exécutez scripts/fetch_comments.sh sur le dépôt cible. Il exécute un pipeline de scripts autonomes sous scripts/lib/ : lister les PR, récupérer les commentaires, filtrer, formater et regrouper, puis écrire le résultat. Exécutez ce script avec --help pour ses options (état de PR, limite de nombre de PR, concurrence, délai d'attente). Spécification complète : references/fetch-plan.md.

• Le script écrit un fichier de commentaires en Markdown dans ~/.cache/comments-to-rules/{propriétaire}-{dépôt}/ par défaut.
• Utilisez --output pour choisir un emplacement différent. Donnez-lui un répertoire pour obtenir un fichier par langage. Donnez-lui tout autre chemin pour obtenir un fichier combiné.
• En mode répertoire, le script groupe déjà les commentaires par langage : <langage>/comments-NNN.md, 250 commentaires par morceau. Cela maintient chaque appel Read de l'Étape 2 peu coûteux.
• Le script ignore un commentaire de moins de 10 caractères avant que vous ne le voyiez (--min-length pour changer cela). Il mesure cela sur la prose uniquement, avec tout bloc ```suggestion exclu du décompte. C'est un filtre mécanique pour le bruit pur — lgtm, nit, +1, et similaires. Il ne remplace pas le filtrage basé sur le jugement de l'Étape 2.
• Un commentaire avec un bloc ```suggestion ignore entièrement ce filtre de longueur, quelle que soit la longueur de sa prose. La suggestion est un signal en soi, même sans prose à côté — voir Étape 2. Ce commentaire gagne également un bloc Code original: au-dessus : le code environnant que GitHub a attaché au commentaire, montrant ce que la suggestion a remplacé.
• Le script signale sa propre progression : le dépôt qu'il a détecté, l'emplacement de sortie, chaque lot de récupération et chaque fichier qu'il écrit. Montrez cette progression à l'utilisateur. N'exécutez pas le script silencieusement.
• La limite de PR par défaut est 1000, les plus récentes d'abord. Passez --all pour aucune limite. Si le nombre de PR dépasse la limite par défaut, le script se termine avec le statut 2 et un message NEEDS_INPUT. Demandez à l'utilisateur s'il souhaite utiliser les 1000 PR les plus récentes ou toutes, puis réexécutez avec ce choix.
• Si l'utilisateur interrompt le script (Ctrl-C) pendant une récupération importante, le script s'arrête après le lot en cours. Il écrit ce qu'il a récupéré jusqu'à présent et imprime la plage de PR qu'il n'a pas atteinte. Dites-le à l'utilisateur et proposez de reprendre plus tard pour cette plage.
• Si gh est manquant ou non authentifié, ou si jq ou timeout est manquant, arrêtez-vous et dites à l'utilisateur comment le corriger. N'exécutez pas gh auth login ou gh auth refresh vous-même — voir Prérequis.
• Si le dépôt n'a pas de PR fusionnées, dites-le à l'utilisateur, puis passez à l'Étape 3 (le passage local seul).

Étape 2 — Filtrer et regrouper les commentaires en règles

Les commentaires sont déjà regroupés par langage : un sous-répertoire ou une section par langage, de l'Étape 1. Ils sont déjà filtrés par longueur. Lisez les commentaires de chaque langage vous-même — ne scriptez pas cette partie.

• Supprimez le bruit que le filtre de longueur a manqué : les approbations avec des mots supplémentaires ("LGTM" plus un commentaire), les commentaires de robots et les discussions sans instruction exploitable. Cette étape nécessite du jugement. Le filtre de longueur non.
• Conservez un commentaire qui énonce ou implique une convention de codage — par exemple, "utilisez const pas let ici", "gérez toujours cette erreur", ou "préférez un retour précoce".
• Lorsque deux commentaires ou plus énoncent la même règle, fusionnez-les en une seule règle.
• Un commentaire avec un bloc ```suggestion, et un bloc Code original: au-dessus, contient une vraie paire avant/après de l'historique de ce dépôt. Lisez le diff, pas seulement la prose à côté — le diff peut énoncer une règle par lui-même, même là où la prose dit peu ou rien. Une suggestion qui transforme un if/else en clause de garde et un retour énonce "préférez un retour précoce" par elle-même, avec ou sans commentaire qui le dit. Lorsque vous conservez une règle de cette manière, traitez le diff comme la source, pas seulement comme un exemple pour une règle énoncée séparément.
• Là où une règle mérite un exemple de code, consultez rule-template.md pour savoir quand il vaut la peine d'en ajouter un. Préférez une vraie paire Code original: et suggestion à une paire fabriquée — c'est déjà une vraie paire pasCommeÇa/plutôtCommeÇa.
• Énoncez la règle, puis montrez la paire comme code. Ne racontez pas d'où elle vient — pas de "un réviseur a suggéré cela sur la PR #531", pas de "la suggestion réelle d'un réviseur a changé". La règle et le code sont le contenu. Le numéro de PR et le réviseur ne le sont pas.

Une langue peut avoir trop peu de commentaires exploitables pour soutenir une règle avec confiance. Comme guide approximatif, traitez moins de trois règles survivantes comme trop peu. Cela peut arriver avec un historique de PR mince, un dépôt petit ou nouveau, ou une langue que les réviseurs touchent rarement. Dans ce cas, ne forcez pas un fichier de règles à partir de ce qui existe peu. Notez quelles langues sont minces. Conservez les quelques règles qui ont survécu. Laissez l'Étape 3 écrire le reste du fichier de cette langue. Cela inclut le cas extrême : une langue avec zéro commentaire survivant reçoit toujours un fichier, écrit entièrement par l'Étape 3.

Avant d'écrire le fichier de règles d'une langue, vérifiez le répertoire .claude/rules/ du dépôt cible pour tout fichier existant qui couvre déjà cette langue. Ne vérifiez pas seulement un nom exact code-style-{langue}.md — lisez la métadonnée paths: de chaque fichier existant et comparez-la avec les extensions de fichier de cette langue.

• Si un fichier existant a paths: qui couvre déjà cette langue, demandez à l'utilisateur (avec AskUserQuestion) : mettre à jour ce fichier ou créer un nouveau code-style-{langue}.md à côté ? Posez cette question une fois par langue avec une correspondance, pas une fois par fichier.
• Si vous mettez à jour un fichier existant, lisez-le d'abord. Fusionnez vos nouvelles découvertes. Conservez les règles existantes qui tiennent toujours. Si une nouvelle découverte contredit une règle existante, arrêtez-vous et demandez à l'utilisateur laquelle conserver — ne jamais écraser silencieusement.
• Si aucun fichier existant ne couvre cette langue, créez .claude/rules/code-style-{langue}.md.

Dans les deux cas, suivez la structure de references/rule-template.md : une métadonnée paths: glob, une note de contexte optionnelle et des puces de règles. Énoncez une règle en prose et arrêtez-vous par défaut — ajoutez un exemple bon/mauvais en bloc de code seulement lorsque la règle resterait peu claire sans. Là où un commentaire de PR réel donne un exemple propre qu'une règle nécessite vraiment, citez-le textuellement plutôt que de le paraphraser. Écrivez chaque fichier de règles en prose conforme à ASD-STE100. Invoquez la compétence asd-ste100 pour ce passage, si elle est installée. Si elle n'est pas installée, notez dans le fichier que vous avez sauté cette vérification.

Étape 3 — Passage des fichiers locaux

Scannez les fichiers du dépôt cible, en respectant .gitignore, regroupés par langage. Scannez chaque langage présent dans la base de code, pas seulement ceux que l'Étape 2 a déjà couverts. Déduisez les conventions du code lui-même : style de nommage, ordre des imports, formatage, structure des tests, gestion des erreurs et modèles similaires.

• Pour une langue que l'Étape 2 a bien couverte, ajoutez ces découvertes sous un titre "Déduit Localement". Gardez cette section visuellement séparée des règles basées sur les commentaires de PR au-dessus, afin que la source de chaque règle reste claire.
• Pour une langue que l'Étape 2 a marquée comme mince ou ignorée, ce passage est la source principale de la langue — pas un bonus. Cela couvre une langue sans commentaires de PR et un dépôt sans PR fusionnées du tout (voir Étape 1). Écrivez le fichier à partir de l'inférence locale seule. Énoncez cela clairement dans la note de contexte du fichier — voir rule-template.md — par exemple : "Ces règles proviennent de conventions de code locales. L'historique des revues de PR pour cette langue était trop mince pour en tirer des règles." N'étiquetez pas ces règles comme dérivées de PR. Ne présentez pas une découverte locale comme si un réviseur l'avait dite.
• Là où le code local ne suit aucune convention cohérente, n'inventez pas une règle. Ajoutez la question à une section "Questions Ouvertes" à la place — voir rule-template.md — et demandez à l'utilisateur quelle convention adopter.
• N'écrivez pas de fichier de règles pour une langue sans règle exploitable à énoncer — ni de l'Étape 2, ni de cette étape. Un fichier de règles dont le seul contenu expliquerait pourquoi il n'a rien à dire n'est pas un fichier de règles. Cela se produit le plus souvent pour une langue qu'un formateur contrôle entièrement, sans historique de PR ni convention manuscrite à déduire — par exemple, les fichiers JSON qui ne sont que des fichiers de configuration ou de verrouillage, formatés uniquement par Prettier. Dans ce cas, sautez le fichier et listez la langue, avec une raison d'une ligne, dans le résumé de l'Étape 4 à la place.

Si l'Étape 1 n'a trouvé aucune PR fusionnée, le fichier de règles de chaque langue provient de cette étape seule. Traitez cela comme le chemin normal pour un dépôt nouveau ou peu revu, pas comme un repli.

Déléguer le travail des Étape 2 et Étape 3 d'une langue à un sous-agent est un choix raisonnable sur un dépôt avec plusieurs langages. Chaque langage obtient alors son propre contexte séparé pour lire les commentaires et scanner les fichiers. Si vous faites cela, dites au sous-agent ce que son rapport final doit inclure :

• La langue et le chemin du fichier qu'il a écrit ou mis à jour.
• Le nombre total de règles.
• Combien de commentaires il a utilisés pour créer des règles — un décompte cumulé, mis à jour chaque fois qu'il conserve ou supprime un commentaire. Ne lui faites pas reconstruire ce décompte après coup en relisant le fichier.

L'Étape 4 construit son résumé à partir de ces seuls nombres rapportés. Ne relisez pas un fichier de règles terminé pour compter ses règles ou confirmer son contenu. Le sous-agent qui a écrit le fichier connaît déjà les deux nombres.

Gardez cette délégation plate — un seul niveau, jamais imbriquée. Dispensez au plus un sous-agent par langage, directement depuis la session principale. Ne faites pas en sorte qu'un sous-agent linguistique génère ses propres agents enfants pour diviser un volume de commentaires important, et ne le lui demandez pas. Un audit de transcription a trouvé un arbre imbriqué — session principale, puis agents linguistiques, puis lecteurs de morceaux enfants, environ 20 agents de profondeur. Sa gestion a coûté 16% du coût réel en jetons de cette exécution en pure coordination seule : interroger le statut des agents, envoyer des réveils de pulsation, suivre les retardataires un par un. Ce nombre ne compte même pas la narration de la session principale entre les vérifications. Un langage avec plus de commentaires que le contexte d'un sous-agent ne peut confortablement contenir n'est pas une raison pour ajouter un niveau d'arbre. C'est une raison pour que ce seul sous-agent lise ses fichiers de morceaux séquentiellement, dans son propre contexte. Ce contexte peut contenir bien plus que ce que la session principale a jamais besoin de suivre à la fois.

Étape 4 — Confirmer que les fichiers de règles sont complets

Avant de proposer quoi que ce soit de plus, dites clairement à l'utilisateur que l'écriture des fichiers de règles est terminée. C'est un événement séparé de l'offre de revue de l'Étape 5, pas une introduction. Énoncez-le comme son propre message, avec un résumé qui couvre :

• Fichiers. Chaque .claude/rules/code-style-{langue}.md que vous avez écrit ou mis à jour cette exécution.
• Langues couvertes. Les langues distinctes dans ces fichiers.
• PR récupérées. Le nombre de PR depuis la sortie imprimée de l'Étape 1. Lisez ce nombre — ne le recomptez pas vous-même.
• Commentaires récupérés. Le nombre total de commentaires depuis la sortie imprimée de l'Étape 1 — le nombre après le filtre de longueur, avant le filtre sémantique. Lisez la ligne "a écrit N commentaire(s) dans M groupe(s) de langues" du script. Ne le dérivez pas en lisant les commentaires.
• Commentaires utilisés. Combien de commentaires ont survécu au filtre sémantique de l'Étape 2 et ont façonné une règle. Ce nombre est plus petit que "commentaires récupérés" — la plupart des commentaires récupérés s'avèrent être du bruit, une discussion ou un doublon d'une règle déjà capturée. Obtenez-le depuis le décompte cumulé que vous avez tenu par langue pendant le filtrage — voir la note de l'Étape 3 sur la délégation à un sous-agent. Ne l'obtenez pas en relisant un fichier de règles terminé et en comptant.
• Règles créées. Le nombre total de règles dans chaque fichier que vous avez écrit cette exécution, dérivées de PR et localement déduites combinées. Faites la somme de votre propre décompte suivi par langue ou du nombre rapporté par chaque sous-agent. Appliquez la même règle que "Commentaires utilisés" : comptez pendant que vous travaillez et ne recomptez jamais en relisant le fichier.
• Jetons utilisés. Énoncez cela comme une estimation et dites-le. Vous n'avez aucun moyen fiable de lire votre propre utilisation exacte de jetons en milieu de session. Basez l'estimation sur un proxy approximatif : divisez le nombre de caractères que vous avez lus dans les commentaires et les fichiers locaux, plus le nombre de caractères que vous avez écrits dans les fichiers de règles, par environ 4. Dites à l'utilisateur que c'est une estimation approximative, pas un chiffre facturé, et dirigez-les vers /cost pour un nombre exact.
• Langues ignorées. Toute langue que l'Étape 3 a choisi de ne pas écrire de fichier pour — aucune règle exploitable d'aucune étape, ou trop peu de fichiers dans le dépôt pour mériter un fichier dédié — avec une raison d'une ligne chacune.

Exemple :

Fichiers de règles terminés.

• Écrit .claude/rules/code-style-python.md, mis à jour .claude/rules/code-style-shell.md (2 fichiers)
• Langues : python, shell
• 342 PR fusionnées récupérées, 118 commentaires ont survécu au filtrage, 23 de ceux-ci utilisés pour créer des règles
• 19 règles créées au total
• ~28K jetons utilisés cette exécution (estimation approximative — exécutez /cost pour un chiffre exact)
• Ignoré json — seulement config

…