CommunityRédaction et éditiongithub.com

explorateur-de-pr

Expliquer une pull request, un correctif ou une modification locale à un collègue junior, sous forme d'une page HTML autonome (par défaut) ou d'un document Markdown de passation (--md). Couvre une fonctionnalité (pourquoi, architecture, flux, code clé, vérification) ou un correctif (symptôme, cause racine, correction, preuve).

Qu'est-ce que explorateur-de-pr ?

L'explorateur-de-pr est une compétence d'agent AI conçue pour générer une explication autonome et détaillée d'une pull request, d'un correctif de bogue ou d'une modification locale, destinée à un collègue débutant. Elle produit soit une page HTML riche (par défaut) avec mise en évidence de code, diagrammes Mermaid et support des modes clair/sombre, soit un document Markdown de type HANDOVER.md (via l'option --md). L'agent prend en charge deux modes principaux : l'explication d'une fonctionnalité (problème, architecture, flux, code, vérification) ou d'un correctif de bogue (symptôme, cause racine, correction, preuve de régression). Il utilise l'interface de ligne de commande `gh` pour récupérer automatiquement les détails de la PR, ou analyse le diff local pour les modifications non validées. Les options incluent --concise pour une version synthétique, --local pour forcer l'utilisation du checkout local, et --md pour la sortie Markdown. Cette compétence est utile pour les développeurs qui doivent expliquer une modification complexe, rédiger un document de passation, créer un guide de revue de code, ou simplement assurer la continuité du travail au sein d'une équipe. Elle fonctionne sur tout environnement avec git, gh (optionnel) et un interpréteur de commandes.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more Rédaction et édition skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · 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

Explorateur de PR

Produire un document qui enseigne à un collègue une modification : ce qui n'allait pas ou manquait, comment le système fonctionne autour, ce que fait le changement, et comment nous savons qu'il fonctionne.

Arguments

  • Cible : un numéro ou une URL de PR, ou rien.
    • Avec une PR et l'interface gh disponible, récupérez les détails avec gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files et le diff avec gh pr diff <url>. Lisez le code environnant au commit de tête de la PR (git show <headRefOid>:<path>), pas HEAD local.
    • Sans PR, ou sans gh : expliquez le changement local. Utilisez git diff <base>...HEAD pour les commits et git diff plus git status pour le travail non commité, où <base> est la branche par défaut ou le premier commit.
  • --local : utilisez le checkout local même lorsqu'une PR existe (travail non poussé). Notez sur la page qu'elle reflète les modifications locales.
  • --concise : une version courte qui se lit en deux minutes environ. Au maximum un visuel, 3 extraits de code, pas de table des matières, 1 à 3 phrases par section.
  • --md : écrivez en Markdown au lieu de HTML (fichier par défaut HANDOVER.md à la racine du dépôt, sauf si l'utilisateur en nomme un). Utilisez ceci pour les passations et lorsqu'un navigateur n'est pas pratique.

Public et voix

  • Le lecteur est un ingénieur junior de l'équipe. Utilisez des phrases courtes, des verbes simples, une idée par paragraphe.
  • Ne définissez pas les bases (REST, SQL, JWT, hooks React) et n'utilisez pas d'analogies non techniques. Restez technique, avec de vrais noms de modules, fonctions, routes et champs, et de vrais nombres.
  • Simplifiez la rédaction, pas le contenu. Expliquez un appel de bibliothèque ou un motif inhabituel là où il apparaît.
  • Rédigez comme une version finale. Décrivez directement l'état actuel. Pas de journal des modifications ni de formulation « nous pensions plus tôt ».
  • Soyez honnête sur la certitude. Étiquetez les affirmations non prouvées « probable, pas encore confirmé ».

Portée : expliquer le changement, pas le diff

  • Choisissez les fichiers qui racontent l'histoire, et à l'intérieur seulement les lignes qui comptent.
  • Utilisez 1 à 3 extraits par fichier, chacun de moins de ~25 lignes, avec ... pour les parties élidées. Donnez à chacun le chemin du fichier et 2 à 4 phrases sur ce qu'il fait et pourquoi.
  • Pour un correctif, montrez le code qui a causé le bogue et le diff du correctif.
  • Ordonnez le code selon le flux d'exécution, pas l'ordre du diff.
  • Sautez les changements de plomberie, les renommages et le formatage. Mentionnez-les en une ligne si un relecteur les verra dans le diff.

1. Comprendre le changement

  • Lisez le diff et le code environnant. Décidez du mode :
    • Fonctionnalité : nouveau comportement ou refactorisation importante.
    • Correctif de bogue : un symptôme, une cause racine et un correctif.
  • Trouvez la dernière exécution de vérification : commande de test et résultats, et idéalement la preuve qu'un nouveau test de régression échoue sans le correctif et passe avec. Si cette preuve n'existe pas et qu'il est peu coûteux de la produire, faites-le : git stash push -- <fichiers sources>, exécutez le test, puis git stash pop. Cherchez également une vérification manuelle ou de bout en bout (sortie CLI, requête, capture d'écran). Montrez uniquement la dernière exécution de chaque.
  • Utilisez les résultats de la conversation (analyse de cause racine, rapport QA, ticket) lorsqu'ils existent.

2. Structure

Chaque document commence par une ligne d'en-tête (dépôt · PR #n · ticket, ou dépôt · modifications locales), un titre en langage clair et un chapô de 1 à 2 phrases.

Correctif de bogue

  1. Ce qui n'a pas fonctionné : le symptôme, où il a été vu, ce qui a été écarté.
  2. Cause racine : l'endroit exact où les données ou le flux se brisent (fichier:ligne), avec un visuel si cela aide.
  3. Le code qui l'a causé : un ou deux extraits.
  4. Le correctif : un extrait de diff et pourquoi il fonctionne. Nommez les effets secondaires qu'il corrige également.
  5. Comment nous le savons : un test de régression qui échoue avant et passe après, les résultats de la suite complète, une vérification manuelle.
  6. Enseignements : 2 à 4 leçons qu'un junior peut réutiliser ailleurs.

Fonctionnalité

  1. Pourquoi : le problème ou l'objectif, avec des preuves.
  2. Où cela se situe : contexte d'architecture ou de module (diagramme), plus ce qui est intentionnellement inchangé.
  3. Comment cela fonctionne : étapes ou organigramme lié aux cartes de code.
  4. Visite guidée du code : une carte par fichier important, dans l'ordre du flux.
  5. Comportement à connaître : cas limites, états, modes de défaillance (un tableau s'il y en a plus de 3).
  6. Vérification : seulement la dernière exécution.
  7. Enseignement pour le relecteur : le modèle mental en 2 à 3 lignes, et où regarder le plus attentivement dans le diff.

Ajouts pour la passation (toujours inclus avec --md ; facultatif en HTML) :

  • Comment exécuter / tester : commandes exactes.
  • Hypothèses faites : décisions prises là où le cahier des charges était silencieux, et pourquoi.
  • Questions ouvertes pour le métier : classées par impact.
  • Risques et retour arrière : ce qui pourrait mal tourner en production et comment revenir en arrière.
  • Prochaines étapes : ce que vous feriez avec plus de temps.

Concise : seulement Ce qui n'a pas fonctionné / Quoi et pourquoi, Cause racine / Comment cela fonctionne, Le correctif / Code clé, et Comment nous le savons.

3. Visuels : seulement lorsqu'ils expliquent quelque chose que le texte ne peut pas

ContenuUtilisation
Architecture de module ou de service, qui appelle qui, séquence de requêtesflowchart / sequenceDiagram Mermaid (≤ ~12 nœuds)
Une branche qui se comporte différemment avant et aprèsTableau avant/après ou petit SVG statique
Données passant par des étapes, valeurs éliminées par un filtreUn tableau d'exemples d'entrées → sorties, avant vs après
États, commandes, risques, contratsTableaux

En Markdown, utilisez des blocs ```mermaid (GitHub les rend). N'ajoutez des animations que si l'utilisateur le demande.

4. Construction

  • HTML : partez de references/page-template.html (autonome, mode clair et sombre, Mermaid et highlight.js depuis un CDN). Sauvegardez dans .pr-review/<nom>.html, nommé d'après le ticket ou la PR, ou local-<description-courte>. Gardez-le hors de git : si git check-ignore -q .pr-review/ échoue, ajoutez .pr-review/ à .git/info/exclude. Ne modifiez pas .gitignore sauf demande explicite.
    • Extraits de code : <pre><code class="language-<lang>">…</code></pre>, échappés en HTML. Pour un diff de correctif, utilisez language-diff avec les lignes -/+.
    • Mermaid : <pre class="mermaid">…</pre>. Ne codez jamais les couleurs en dur.
  • Markdown (--md) : Markdown standard de type GitHub, même structure, pas de HTML.

5. Vérifier une fois

  • HTML : si un outil de navigation est disponible, ouvrez la page une fois en largeur de bureau et une fois à ~400px. Vérifiez que Mermaid s'affiche et que le code est mis en évidence, corrigez ce que vous avez vu en un passage, et ne bouclez pas. Sinon, dites qu'elle n'a pas été prévisualisée et donnez la commande pour l'ouvrir (open sur macOS, start sur Windows, xdg-open sur Linux).
  • Relisez chaque fichier:ligne, nombre et commande sur la page par rapport au code. Les faits doivent être exacts.

6. Rapporter

Répondez avec :

  • le chemin du fichier
  • le mode, et les sections couvertes
  • les visuels utilisés et ce que chacun explique
  • quelle exécution de vérification le document montre
  • tout ce qui est étiqueté « pas encore confirmé »

Ne modifiez jamais le corps d'une PR, ne postez pas de commentaire et ne poussez rien sans demander au préalable.

Skills associés