Brochure de travail
Après avoir terminé un travail, l'utilisateur souhaite deux choses :
- Le récapitulatif normal dans le chat, exactement comme vous l'écririez de toute façon (ce qui a changé, où ça en est, ce qui n'est pas fait). Ce skill ne le remplace jamais et ne le raccourcit pas.
- Une brochure : une page HTML autonome qui parcourt visuellement le même travail, afin que l'utilisateur puisse l'ouvrir à côté du chat et comprendre le changement à l'aide de diagrammes, de captures d'écran et de code annoté, plutôt que de longs paragraphes.
La brochure doit être fidèle au code. Chaque affirmation, nombre, chemin de fichier et capture d'écran provient du diff réel, des commandes que vous avez exécutées et de l'application que vous avez observée. N'inventez jamais un test qui n'a pas été exécuté ni un résultat que vous n'avez pas vu.
Étapes
1. Rédigez d'abord le récapitulatif du chat
Terminez le travail comme d'habitude, y compris votre résumé textuel normal et wrap_up (si l'application en possède un). Construisez ensuite la brochure. Si l'utilisateur a seulement demandé la brochure d'un travail antérieur, passez directement à l'étape 2.
Après l'ouverture d'une PR (le hook PostToolUse du plugin, ou celui de vos paramètres, ajoute un rappel après gh pr create), construisez la brochure pour cette PR avec gather.sh --pr <N> dans le même tour, et placez le lien de la brochure dans votre message de clôture. Ne modifiez pas le corps de la PR pour l'ajouter sauf si l'utilisateur le demande. Ignorez uniquement si la PR est triviale (une ligne, faute de frappe, version bump).
2. Rassemblez les faits
Exécutez l'outil depuis la racine du dépôt (il imprime les commits, un diffstat par fichier regroupé par dossier, les modifications non commitées et les infos de PR) :
bash <skill-dir>/scripts/gather.sh # cette branche vs main + non commité
bash <skill-dir>/scripts/gather.sh A..B # n'importe quelle plage git (ex. travail déjà fusionné)
bash <skill-dir>/scripts/gather.sh --pr 51 # une PR GitHub
Lisez ensuite les parties du diff qui comptent (git diff <range> -- <path>), pas la totalité. Collectez également à partir de cette conversation :
- Pourquoi : le problème ou la demande dans les termes de l'utilisateur.
- Décisions : les options que vous avez pesées et pourquoi vous avez choisi celle-ci.
- Vérification : les commandes exécutées et leur sortie réelle, les captures d'écran prises, ce que vous avez vérifié dans le navigateur ou le simulateur, et ce que vous n'avez pas pu vérifier.
- Points en suspens : les suivis, les risques, tout ce qui reste à faire.
- Nécessite l'utilisateur : tout ce que seul l'utilisateur peut décider, vérifier visuellement ou approuver.
3. Capturez l'application réelle (lorsque le changement est visible)
Si le changement apparaît dans une interface utilisateur, la brochure doit montrer l'application réelle, pas une description.
- Après : capturez d'écran de l'application en cours d'exécution sur le(s) écran(s) modifié(s) avec les outils de prévisualisation (
preview_startavec le serveur launch.json du projet, naviguez,computer {action: "screenshot"}), ou le simulateur iOSscreenshot. Capturez les largeurs desktop et téléphone si la disposition a changé. - Avant : si la différence est le point important, extrayez la révision de base dans un worktree temporaire dans le scratchpad (
git worktree add <scratchpad>/before <base>), servez-le sur un port différent, capturez la même vue, puis supprimez le worktree (git worktree remove). Ignorez si le changement est purement additif ou si un "avant" n'apporte rien. - Enregistrez les captures d'écran sous forme de fichiers dans le scratchpad, réduisez-les (
sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg) et intégrez-les sous forme d'URIdata:. Gardez la page entière sous ~8 Mo. - Pour les changements vidéo/animations, intégrez quelques images fixes (
ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg) ou une bande d'images, ainsi que les mesures chiffrées. - Les changements non visuels (scripts, données, backend) reçoivent des diagrammes et des sorties réelles plutôt que des captures d'écran.
4. Planifiez l'histoire, puis choisissez les visuels
Ordonnez la page comme l'utilisateur voudrait que cela lui soit expliqué : le résultat d'abord, puis comment ça marche, puis les détails. Choisissez les visuels en fonction de ce qui a changé. Préférez une image chaque fois qu'elle explique plus vite que du texte ; gardez la prose pour de courtes légendes et des paragraphes d'une à trois phrases.
| Ce qui a changé | Visuel à utiliser |
|---|---|
| Logique, pipeline, règle de décision | Mermaid flowchart du nouveau flux ; mettez en surbrillance les nouveaux nœuds modifiés avec classDef changed |
| Requêtes entre parties (UI → API → stockage) | Mermaid sequenceDiagram |
| Structure (modules, fichiers, forme des données) | Arborescence de fichiers avec barres +/− ; Mermaid graph de la connexion des parties ; tableau des champs avant/après |
| UI | Paire de captures avant/après ; annotez avec des appels numérotés placés sur l'image |
| Nombres (temps, tailles, compteurs, performances) | Graphique à barres SVG en ligne à l'échelle, avant vs après |
| État ou cycle de vie | Mermaid stateDiagram-v2 |
| Séquence de travail (migration, modification en plusieurs étapes) | Étapes numérotées (uniquement si l'ordre est réel) |
| Code clé | Courts extraits de diff (5–25 lignes) avec les lignes importantes marquées, à l'intérieur de <details> pour qu'ils ne dominent pas |
Visez au moins trois visuels distincts pour un changement de taille fonctionnalité, et au moins un pour tout ce qui est plus petit. Les diagrammes doivent décrire le mécanisme réel (vrais noms de fonctions, vrais noms de fichiers, vraies valeurs), pas des boîtes génériques.
5. Construisez la page à partir du modèle
Copiez <skill-dir>/template.html et remplissez-le. Il contient déjà le look sketchpad (un thème clair volontairement : fond papier quadrillé, titres manuscrits, cartes crayonnées, diagrammes dessinés à la main), la mise en page et chaque composant listé ci-dessus. N'ajoutez pas de mode sombre et ne changez pas l'apparence sauf si l'utilisateur le demande. Règles :
- Conservez le bloc
<style>et le script de chargement Mermaid ; remplacez le contenu d'exemple. Supprimez les sections qui ne s'appliquent pas plutôt que de les laisser maigres (ex. pas de "Avant → après" pour un simple refactoring). <title>: le nom de la fonctionnalité, deux à quatre mots (ex. "Logique de relance du paiement"), pas "Résumé du travail : …".- Hero : une phrase sur le résultat, la ligne méta (branche, lien PR, date) et la bande de statistiques (fichiers, lignes +/−, commits, vérifications réussies). Calculez les chiffres à partir de gather.sh, n'estimez pas.
- Nécessite votre intervention (note autocollante sous le hero) : uniquement les vraies demandes qui attendent l'utilisateur, une ligne chacune, indiquant où regarder. Au maximum trois. Supprimez toute la note quand il n'y en a pas ; ne l'allongez jamais.
- Pourquoi ainsi (tableau des décisions) : deux à quatre options qui ont réellement été pesées pendant la session, une marquée Choisie, un compromis en une ligne chacune. N'inventez pas d'alternatives pour remplir ; si aucune décision réelle n'a été prise, supprimez la section.
- Gardez la page légère : ces deux sections plus celles qui s'appliquent. N'ajoutez pas de sections au-delà du modèle.
- Arborescence des fichiers : une ligne par fichier significatif (regroupez les fichiers générés/binaires en une seule ligne), largeurs des barres +/− en pourcentage du total du plus gros fichier, plus une ligne en français simple expliquant pourquoi il a changé.
- Extraits de diff : échappez
<,>,&. Marquez les lignes avecclass="add",class="del", ouclass="hl"(ligne importante non modifiée). - Mermaid va dans
<pre class="mermaid">, commençant directement après la balise avec le bloc de configuration du modèle (---/config:/look: handDrawn/theme: neutral/---) pour qu'il s'affiche dessiné à la main à la fois comme fichier local et sur claude.ai. Conservez la ligneclassDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2pxdu modèle. Échappez</>dans les étiquettes sous forme de</>, et utilisezclass <ids> changedpour ce que ce travail a ajouté ou modifié. Gardez chaque diagramme à environ 5–9 nœuds pour qu'il tienne sur un écran : fusionnez les étapes consécutives en un seul nœud avec une ligne de détail<br/>, et divisez un flux plus long en deux diagrammes. Utilisezflowchart LRpour les courtes chaînes,TDpour celles qui bifurquent. - Vérification : listez chaque vérification avec une pastille réussite / échec / non vérifié et sa preuve (extrait de sortie ou capture d'écran). Les éléments "non vérifiés" sont requis lorsqu'ils existent.
- Écrivez simplement : des phrases courtes, les termes de l'utilisateur, pas de remplissage.
Enregistrez-la sous <depot-racine>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html. Gardez ce dossier hors de git dans chaque dépôt sans toucher à son .gitignore, en l'ajoutant au fichier d'exclusion local une fois :
mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")
6. Vérifiez une fois, puis livrez
- Ouvrez-la une fois dans le panneau navigateur (
preview_startavecurl: file://<chemin>, ou le serveur statique du projet) et prenez une capture d'écran pour confirmer que les diagrammes se sont rendus et que rien ne déborde. Corrigez ce que ce seul affichage montre ; ne bouclez pas. - Affichez-la dans le panneau latéral :
SendUserFileavecdisplay: "render". - Publiez-la en tant qu'Artifact privé (
Artifactpublish avec le chemin du fichier,icon: "document", et une description d'une phrase) pour qu'elle survive après le nettoyage d'un worktree. C'est la copie persistante ; les artefacts commencent privés. Si aucun outil Artifact n'est disponible (ex. une session terminal simple), ignorez cette étape et donnez le chemin local. - Dans le chat, après votre récapitulatif normal, ajoutez une ligne avec le lien de la brochure et le chemin du fichier local.
Mise à jour : si l'utilisateur demande des modifications, modifiez le même fichier et republiez-le au même chemin pour que le lien reste valide.
À quoi ressemble une bonne brochure
- Une personne qui n'a pas participé à la session comprend ce qui a changé et pourquoi en moins de deux minutes de défilement.
- Le premier écran répond à "qu'est-ce qui est différent maintenant ?" sans avoir à défiler.
- Chaque diagramme, graphique et capture d'écran concerne ce changement.
- Le statut honnête est visible : ce qui a été vérifié, ce qui ne l'a pas été, ce qui reste à faire.