CommunityImagegithub.com

pr-diagram

Génère un diagramme Mermaid (.mmd) de ce que modifie une pull request, afin que les relecteurs visualisent le flux avant de lire le diff.

Qu'est-ce que pr-diagram ?

Cette compétence permet de créer un diagramme Mermaid qui résume visuellement les changements apportés par une pull request (PR), en mettant en évidence le flux fonctionnel et l'impact de chaque modification. L'utilisateur peut invoquer la compétence via des commandes comme "pr diagram", "diagram this PR", ou utiliser l'argument `/pr-diagram` avec un numéro ou une URL de PR, ou bien pour la branche courante. La compétence analyse le diff de la PR pour identifier les relations entre les étapes, en s'appuyant sur une lecture du code (en lecture seule). Elle détermine le type de diagramme le plus adapté (flowchart, diagramme de séquence, diagramme d'état, etc.), code les nœuds en fonction de leur statut (nouveau, modifié, inchangé), et respecte des règles strictes pour ne jamais modifier le code, approuver ou fusionner la PR, ni publier de commentaires. Une fois le diagramme généré, la compétence affiche la nouvelle description complète de la PR et demande une approbation avant de la publier via `gh pr edit --body-file`. Cette compétence est conçue pour fonctionner avec Claude Code (et des agents similaires) qui interagissent avec GitHub CLI. Elle est idéale pour les relecteurs qui veulent comprendre rapidement le flux d'une PR sans lire en détail chaque ligne de code.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/amihali1/claude-skills/tree/HEAD/plugins/pr-diagram/skills/pr-diagram

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · 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

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)

  1. 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 .mmd va dans un répertoire temporaire ou de travail, jamais dans le dépôt.
  2. Ne jamais approuver, demander des modifications, ni fusionner. N'exécutez pas gh pr review, gh pr merge ou gh pr close, et ne publiez pas de commentaires sur la PR. La seule écriture que cette compétence effectue est gh pr edit --body-file sur la description.
  3. 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.
  4. 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-diagram utilise la PR de la branche courante, ou le diff de la branche locale si aucune PR n'existe.
  • /pr-diagram 123 ou une URL de PR cible cette PR (fonctionne pour d'autres dépôts via l'URL).
  • type=td|lr|sequence|state|er force 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écisionflowchart TD (haut en bas)
des composants ou services interconnectés, ou un pipelineflowchart LR (gauche à droite)
une requête ou un message passant entre 3+ participants au fil du tempssequenceDiagram
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, pas CardValidator.validateExpiry(). Lorsque le nom aide, utilisez une forme courte : PaymentReconciliationService devient Réconciliateur de paiements.
  • Raccourcissez les URL au chemin : api.example.com/v2/orders/{id}/refunds devient POST /orders/:id/refunds.
  • Nœuds rectangulaires A["..."] : 35 caractères maximum par ligne.
  • Nœuds stadium A(["..."]) et arrondis A("...") : 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), cylindre A[("...")] = magasin de données.
  • Maximum 15 nœuds. Utilisez subgraph pour 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, et opt, ainsi que le texte des Note, 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), car A---oB est analysé comme une arête circulaire.
  • subgraph Id["Label"] … end. Chaque subgraph a besoin de son propre end.
  • Participants de séquence : participant API as API de commandes (l'ID n'a pas d'espaces).
  • Les types d'attributs dans erDiagram doivent être des mots uniques (varchar, pas varchar(255)).
  • Pas de blocs de thème %%{init}%%. Les couleurs classDef gè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 :

  1. Récupérez le corps actuel dans un fichier temporaire : gh pr view <N> --json body -q .body > <tmp>/body-old.md

  2. 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.
    
  3. Vérifiez que le nouveau corps commence par le corps d'origine complet. Il doit être conservé octet pour octet.

  4. 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)

  1. gh pr edit <N> --body-file <tmp>/body-new.md. N'utilisez jamais --body avec du texte en ligne, car les guillemets du shell altèrent les backticks et $.
  2. Vérifiez avec gh pr view <N> --json body -q .body qu'il correspond à body-new.md, puis donnez l'URL de la PR. Ignorez les espaces de fin lors de la comparaison, car -q ajoute 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.

Skills associés