harness-retro

Harness retro (Rétrospective du harness)

Trouvez ce qui a mal fonctionné dans les sessions passées et modifiez la configuration pour que cela ne se reproduise pas. Chaque constat doit s'appuyer sur une preuve dans une transcription. N'appliquez jamais de modification sans l'approbation de l'utilisateur.

1. Extraire les transcriptions

L'extracteur est un script sans dépendances externes situé à côté de ce fichier. Exécutez-le avec -I. Écrivez sa sortie dans le scratchpad de la session, ou dans un répertoire temporaire s'il n'y en a pas :

python3 -I <répertoire de base de cette compétence>/scripts/mine.py [CHEMIN] [--since 30d] --out <scratchpad>/retro.json

• Sans CHEMIN, il extrait les transcriptions du projet correspondant au répertoire de travail actuel. Pour extraire un autre projet, donnez le chemin de son répertoire de travail, ou utilisez --project=<clé> avec le nom du dossier sous ~/.claude/projects. Utilisez la forme avec =, car les clés commencent par -.
• Utilisez --since si l'utilisateur a précisé une fenêtre temporelle. Augmentez --max-bytes (40000 par défaut) uniquement si la sortie est tronquée et que vous avez besoin de plus de données.
• Si l'utilisateur demande une rétrospective sur tous les projets, exécutez le script une fois par dossier dans ~/.claude/projects et examinez les projets qui présentent le plus de frictions.

Le script affiche un résumé d'une ligne. S'il a analysé peu ou pas de sessions, informez-en l'utilisateur. Claude Code supprime les transcriptions après cleanupPeriodDays (30 par défaut), donc un historique plus ancien peut avoir disparu. Suggérez d'augmenter ce paramètre s'il souhaite des rétrospectives plus approfondies ultérieurement.

2. Lire les résultats

Le fichier JSON liste les sessions classées par score de friction. Chaque résultat comporte signal, score, ts, prior_prompt (ce que l'utilisateur a demandé), recent_actions (les derniers appels d'outils de Claude avant le résultat), et soit user_reaction soit detail.

Signaux, classés approximativement par ordre d'importance :

• user_correction : l'utilisateur a exprimé un désaccord. Un score de 5 ou plus indique une forte frustration ou une répétition ("encore", "j'ai dit", jurons).
• edit_revert et edit_churn : Claude a fait des allers-retours sur le même fichier.
• tool_error_streak : Claude a rencontré à plusieurs reprises la même erreur.
• interrupted : l'utilisateur a interrompu Claude en cours de réponse. Cela signifie généralement qu'il allait dans la mauvaise direction.
• permission_denied : Claude a tenté une action que l'utilisateur ou le classifieur a bloquée.
• self_retraction : Claude a reconnu une erreur. Ce signal est bruité, utilisez-le uniquement comme preuve complémentaire.

Les expressions régulières sont grossières. Éliminez les faux positifs, comme "ne pas" dans une instruction normale ou "réessayer" après une erreur réseau. En cas de doute sur un résultat, ouvrez la transcription autour du passage concerné. Le fichier est ~/.claude/projects/<clé>/<session>.jsonl ; cherchez l'horodatage et lisez quelques lignes de chaque côté. Ne lisez pas les transcriptions entières.

3. Regrouper en motifs

Regroupez les résultats réels en motifs récurrents. Un motif est une cause racine unique, formulée comme quelque chose que Claude fait de travers. Exemples : "Génère de nouvelles images au lieu d'utiliser la bibliothèque d'actifs approuvée", "Modifie la version actuelle au lieu d'en créer une nouvelle", "Affirme qu'une modification est visible sans avoir vérifié le résultat compilé". Pour chaque motif, enregistrez :

• Sa fréquence d'apparition et dans combien de sessions.
• Deux ou trois courtes citations de l'utilisateur, avec le titre de la session et la date.
• La cause racine. Choisissez parmi : connaissance manquante, règle existante mais ignorée, workflow par défaut inadapté, vérification absente, ou problème d'outil ou de permission.

Un incident isolé ne compte que si l'utilisateur était clairement en colère ou si le coût était élevé, par exemple un travail destructeur ou perdu.

4. Vérifier le harness actuel

Avant de proposer quoi que ce soit, lisez ce qui est déjà en place :

• ~/.claude/CLAUDE.md, ainsi que le CLAUDE.md du projet et les éventuels fichiers imbriqués.
• ~/.claude/settings.json, ainsi que .claude/settings.json et .claude/settings.local.json du projet (hooks, permissions).
• Le répertoire mémoire du projet ~/.claude/projects/<clé>/memory/ et son MEMORY.md.
• Les compétences dans ~/.claude/skills/ et .claude/skills/ du projet.

Si un motif est déjà couvert par une règle que Claude a ignorée, l'ajouter à nouveau ne servira à rien. Rendez la règle plus spécifique et placez-la là où elle sera vue, ou passez à un mécanisme plus fort.

5. Choisir la correction

Pour chaque motif, utilisez le mécanisme le plus léger qui fonctionnera réellement :

Cause racine	Correction
Un fait sur le projet que Claude ignorait	Un fichier mémoire dans le répertoire mémoire du projet, avec les métadonnées name, description, metadata.type en frontmatter, un corps contenant Pourquoi : et Comment appliquer :, et un pointeur d'une ligne dans MEMORY.md. Mettez à jour une mémoire existante plutôt que d'en dupliquer une.
Une règle permanente pour ce dépôt	CLAUDE.md du projet
Une règle pour tous les projets	~/.claude/CLAUDE.md
Une règle qui est régulièrement enfreinte et peut être vérifiée par un script (formatage, chaînes interdites, commande requise avant un commit)	Un hook dans settings.json. Utilisez la compétence update-config si elle est disponible.
Demandes ou refus de permission répétés pour des commandes sûres	Proposez des entrées dans la liste blanche, ou suggérez la compétence fewer-permission-prompts si elle est disponible. N'élargissez pas les permissions pour les commandes destructrices.
Un workflow en plusieurs étapes qui échoue systématiquement	Une compétence nouvelle ou modifiée (utilisez skill-creator si elle est disponible).
Un bug produit de Claude Code	Notez-le dans le rapport. Il n'y a pas de correction dans le harness.

Rédigez les règles sous forme d'instructions concrètes et vérifiables qui nomment l'élément spécifique, comme des fichiers, des chemins d'actifs, des commandes ou des noms de version. "Faire attention aux images" est trop vague pour être utile.

6. Rapporter et obtenir l'approbation

Présentez une section par motif, du plus coûteux au moins coûteux. Chaque section donne :

1. Le motif, en une ligne.
2. Les preuves : nombre d'occurrences, sessions et 2 ou 3 courtes citations avec date.
3. La cause racine.
4. La modification proposée : le fichier cible et le texte exact ou le diff.

Demandez ensuite quelles modifications appliquer. Une question multi-sélection AskUserQuestion avec une option par motif fonctionne bien. N'appliquez que les modifications approuvées, puis listez ce qui a été modifié et où.

Rédaction des règles

Tout ce qui est écrit dans CLAUDE.md, les mémoires ou les compétences doit respecter les règles d'écriture présentes dans les propres fichiers CLAUDE.md de l'utilisateur, comme le ton, les mots interdits ou les règles d'attribution. Restez court et précis. Les citations des transcriptions peuvent contenir des secrets que l'utilisateur a collés. L'extracteur masque les formats de clés courants, mais vérifiez avant de copier du texte dans un fichier.