pr-diagram : diagrammer une pull request
Objectif : un diagramme qui indique à un relecteur ce que fait le changement et comment il s'enchaîne, en 10 secondes. Ce n'est pas une cartographie de l'ensemble du code.
Règles de sécurité (absolues)
- Ne jamais modifier le code. Ne modifiez, créez ou supprimez pas de fichiers dans le dépôt, et ne commitez, poussez ou changez pas de branche. Le fichier
.mmdva dans un répertoire temporaire ou de travail, jamais dans le dépôt. - Ne jamais approuver, demander des modifications, ni fusionner. N'exécutez pas
gh pr review,gh pr mergeough pr close, et ne publiez pas de commentaires sur la PR. La seule écriture que cette compétence effectue estgh pr edit --body-filesur la description. - Une seule étape d'approbation : afficher la nouvelle description complète et demander de la publier dans le même message. Ne demandez pas "vous voulez que je publie ?" puis montrez la description ensuite. Cela fait deux tours d'approbation. Affichez le corps complet, pas seulement la section ajoutée, et terminez le message par la question. "Ça me va", "publie" ou "oui" à ce message compte comme approbation. Le silence, une question ou une demande de modification non. Après une modification, affichez à nouveau le corps complet et la question ensemble.
- Signez tout ce que vous ajoutez avec cette ligne exacte comme dernière ligne du bloc ajouté :
- Généré par Claude Code
Arguments
/pr-diagramutilise la PR de la branche courante, ou le diff de la branche locale si aucune PR n'existe./pr-diagram 123ou une URL de PR cible cette PR (fonctionne pour d'autres dépôts via l'URL).type=td|lr|sequence|state|erforce un type de diagramme.
Étape 1 : rassembler le diff
Avec une PR (tout en lecture seule) :
gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>
Sans PR : trouver la base (gh repo view --json defaultBranchRef -q .defaultBranchRef.name), puis
git diff --stat $(git merge-base origin/<base> HEAD) et git diff $(git merge-base origin/<base> HEAD).
Gros diffs (>1500 lignes modifiées ou >30 fichiers) : lisez d'abord --stat et le corps de la PR, puis lisez
uniquement les fichiers qui portent la logique. Ignorez les fichiers de verrouillage, le code généré, les instantanés et les renommages purs.
Étape 2 : identifier le flux
Un diff montre des lignes, pas des relations. Lisez la version actuelle de chaque fichier touché (en lecture seule) et déterminez :
- Le flux : ce qui le déclenche (requête, tâche, événement, action utilisateur), ce qui s'exécute dans quel ordre, et où il se termine (réponse, écriture en base, message, appel externe).
- Le statut de chaque étape : nouveau (ajouté par cette PR), modifié (existant, changé) ou inchangé (contexte dont le relecteur a besoin pour placer le changement).
- Le résumé en une phrase dont un relecteur a besoin ("ajoute une étape de réessai avant l'appel de paiement").
Utilisez le titre et le corps de la PR comme intention, mais faites confiance au code en cas de désaccord. Chaque nœud et arête doit être rattaché à du code que vous avez lu. N'inventez jamais une étape pour rendre l'image plus propre. Si quelque chose est incertain, laissez-le de côté et dites-le.
Code supprimé : si une étape supprimée est importante pour les relecteurs, affichez-la comme un nœud gris étiqueté "(supprimé)" avec une arête en pointillés. Sinon, laissez-la de côté.
Étape 3 : choisir le type de diagramme
La sortie est toujours un diagramme Mermaid dans un fichier .mmd. Choisissez le type qui correspond au flux :
| Le changement porte principalement sur... | Diagramme |
|---|---|
| un processus étape par étape ou une logique de décision | flowchart TD (haut en bas) |
| des composants ou services interconnectés, ou un pipeline | flowchart LR (gauche à droite) |
| une requête ou un message passant entre 3+ participants au fil du temps | sequenceDiagram |
| un changement d'état ou de cycle de vie (en attente → approuvé → …) | stateDiagram-v2 |
| des tables, colonnes ou relations (migrations) | erDiagram |
Utilisez un seul diagramme. N'en utilisez deux que si la PR modifie clairement à la fois la structure et le flux d'exécution. Si la PR est trop petite pour nécessiter une image (1 à 2 fichiers, aucun nouveau flux), dites-le et arrêtez-vous.
Étape 4 : construire le diagramme
Étiquettes : en français simple, courtes.
- Décrivez ce que fait une étape, pas les identifiants du code :
Vérifier que la carte n'est pas expirée, pasCardValidator.validateExpiry(). Lorsque le nom aide, utilisez une forme courte :PaymentReconciliationServicedevientRéconciliateur de paiements. - Raccourcissez les URL au chemin :
api.example.com/v2/orders/{id}/refundsdevientPOST /orders/:id/refunds. - Nœuds rectangulaires
A["..."]: 35 caractères maximum par ligne. - Nœuds stadium
A(["..."])et arrondisA("..."): 25 caractères maximum par ligne. - Si un nœud a besoin de plus de détails, divisez-le en lignes avec
<br/>(chaque ligne dans sa limite). Utilisez 3 lignes au maximum. - Signification des formes : rectangle = étape ou composant, stadium = début ou fin (déclencheur, réponse),
arrondi = système externe, losange
A{"..."}= décision (25 caractères maximum), cylindreA[("...")]= magasin de données. - Maximum 15 nœuds. Utilisez
subgraphpour regrouper par service ou domaine lorsqu'il y a plus d'environ 8 nœuds. - Étiquetez brièvement les arêtes en français simple (
envoie,en cas d'échec,sauvegarde), 20 caractères maximum. - Diagrammes de séquence : les noms de participants et d'acteurs 25 caractères maximum. Les messages, les étiquettes
loop,alt, etopt, ainsi que le texte desNote, 35 caractères maximum par ligne (divisez avec<br/>, 3 lignes au maximum). N'utilisez pas;ou#dans le texte des messages, car ils cassent l'analyse.
Couleurs (lisibles en mode clair et sombre de GitHub). Utilisez des remplissages clairs avec du texte foncé et une bordure forte :
classDef new fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#0b3d17
classDef changed fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#4a2b00
classDef unchanged fill:#e9ecef,stroke:#868e96,stroke-width:1px,color:#343a40
class StepA,StepB new
class StepC changed
class StepD unchanged
Chaque nœud reçoit exactement une classe. Dans stateDiagram-v2, utilisez classDef plus class StateName new.
Diagrammes de séquence : les classes ne s'appliquent pas. Un rect définit uniquement l'arrière-plan, et la couleur du texte
provient du thème de GitHub (gris clair en mode sombre). Un remplissage opaque clair rend le texte illisible en mode sombre,
donc utilisez toujours des teintes translucides :
- nouveau :
rect rgba(46,160,67,0.18) - modifié :
rect rgba(210,153,34,0.22) - inchangé : pas de
rect
N'utilisez jamais rect rgb(...) opaque. Ajoutez Note over pour le changement clé.
PR entièrement nouvelles (rien de modifié ou d'inchangé) : gardez la teinte verte, et dites aussi "Tout ce diagramme est du nouveau code" dans le résumé, car il n'y a rien pour contraster.
Pièges de syntaxe (ils cassent le rendu GitHub). Vérifiez chacun :
- Les identifiants de nœuds doivent être alphanumériques simples (
ChkCard). Les étiquettes doivent toujours être entre guillemets :ChkCard["Vérifier carte"]. - Utilisez
#quot;pour un"littéral dans une étiquette.<br/>est le seul HTML autorisé dans les étiquettes. - N'utilisez jamais
end(en minuscules) comme identifiant. Mettez toujours des espaces autour des flèches (A --> B), carA---oBest analysé comme une arête circulaire. subgraph Id["Label"]…end. Chaque subgraph a besoin de son propreend.- Participants de séquence :
participant API as API de commandes(l'ID n'a pas d'espaces). - Les types d'attributs dans
erDiagramdoivent être des mots uniques (varchar, pasvarchar(255)). - Pas de blocs de thème
%%{init}%%. Les couleursclassDefgèrent les deux modes.
Enregistrez le diagramme sous pr-<N>-diagram.mmd (ou branche-<nom>-diagram.mmd) dans un répertoire temporaire
ou de travail. Donnez le chemin complet.
Étape 5 : auto-vérification avant présentation
- Comptez les caractères sur chaque ligne d'étiquette par rapport à sa limite (35 pour les rectangles, 25 pour les nœuds stadium, arrondis et losanges, 20 pour les étiquettes d'arêtes ; dans les diagrammes de séquence, 25 pour les participants et 35 pour les messages, blocs et notes). Corrigez ceux qui dépassent.
- Assurez-vous qu'aucune étiquette ne contient d'identifiant de code brut (camelCase,
Foo.bar(), snake_case) là où le français simple fonctionne. - Vérifiez la couleur de chaque nœud : est-il vraiment nouveau, modifié ou inchangé dans le diff ?
- Vérification de rendu facultative :
npx -y @mermaid-js/mermaid-cli -i <fichier>.mmd -o <fichier>.svg. La première exécution télécharge Chromium (~150 Mo), alors demandez avant de l'exécuter.
Étape 6 : présentation
Utilisez ce format dans le chat :
**<résumé en une phrase de ce que fait la PR>**
<2–3 phrases : le flux en mots, où se situe le changement, ce qui est omis ou incertain>
```mermaid
...
```
**Légende :** vert = nouveau code · jaune = code modifié · gris (ou pas de teinte) = contexte inchangé
Enregistré : <chemin complet vers le .mmd>
Étape 7 : afficher la description complète et demander de publier (même message que l'étape 6)
Faites ceci avant de répondre, afin que le diagramme, la nouvelle description complète et la question soient envoyés tous ensemble :
-
Récupérez le corps actuel dans un fichier temporaire :
gh pr view <N> --json body -q .body > <tmp>/body-old.md -
Construisez le nouveau corps dans
<tmp>/body-new.md. Placez le bloc entre des marqueurs afin que les réexécutions le remplacent au lieu de l'empiler :<!-- pr-diagram:start --> ## Diagramme des modifications <phrase de résumé> ```mermaid ...Légende : vert = nouveau · jaune = modifié · gris (ou pas de teinte) = inchangé (Utilisez des mots, pas des émojis de couleur. Les émojis s'affichent avec des couleurs différentes sur chaque OS, par ex. ⬜ s'affiche en lavande sur Windows.)
- Généré par Claude Code
Si les marqueurs existent déjà, remplacez uniquement le texte entre eux. Sinon, ajoutez le bloc après une ligne vide. Conservez tous les autres octets du corps d'origine inchangés. -
Vérifiez que le nouveau corps commence par le corps d'origine complet. Il doit être conservé octet pour octet.
-
Terminez le message par la nouvelle description complète dans un bloc de code, l'URL de la PR, et la question : "Publier ceci sur ?" Arrêtez-vous et attendez (règle de sécurité 3).
Étape 8 : publier (uniquement après un oui au message de l'étape 7)
gh pr edit <N> --body-file <tmp>/body-new.md. N'utilisez jamais--bodyavec du texte en ligne, car les guillemets du shell altèrent les backticks et$.- Vérifiez avec
gh pr view <N> --json body -q .bodyqu'il correspond àbody-new.md, puis donnez l'URL de la PR. Ignorez les espaces de fin lors de la comparaison, car-qajoute une nouvelle ligne. Par exemple, comparez.rstrip()des deux en Python.
Pas encore de PR (branche locale uniquement) ? Proposez le bloc à coller lorsque l'utilisateur ouvrira la PR. Ne créez pas la PR.
À ne pas faire
- Ne diagrammez pas chaque fichier. Un diagramme de tout ne montre rien.
- Ne mettez pas de secrets, de noms d'hôtes internes, d'URL complètes avec des jetons ou des chaînes de requête, ni de données client dans les étiquettes.