Une skill Claude Code pour ranger sa mémoire auto

Le grenier

Vendredi soir. J'ouvre MEMORY.md parce qu'une recommandation de Claude Code m'avait paru à côté de la plaque. Je tombe sur ça :

# Memory

## Skills directory structure

- Skills are stored in `~/.claude/skills/`
- Each skill has a `SKILL.md` with frontmatter

## Existing skills

- `data-pipeline` — ETL orchestration
- `incident-response` — runbook structure
  [...11 lignes...]

## Skills rewrite (2026-03-10)

- Both `data-pipeline` and `release-checklist` rewritten to match standards
- Now use: checklist progression, parallel agents, ultrathink
- Key updates: runtime validation, deprecated schemas [...230 chars sur une ligne...]

## release-checklist architecture

- `SKILL.md` — Main orchestration
- `STAGES.md` — 8 deploy stages
  [...]

46 lignes. Six sections multi-paragraphes. Deux d'entre elles entièrement reproductibles avec un ls. Une qui ressemblait à un changelog de session. Une qui décrivait une skill que je pouvais lire directement dans son dossier.

C'est pas que le contenu était faux. C'est que tout ça était chargé à chaque conversation, sans valeur ajoutée. Le harness charge MEMORY.md automatiquement au démarrage. Tout ce qui dépasse 200 lignes est tronqué. Ce que vous y mettez vit dans le contexte de chaque thread. Point.

Très bien.

J'avais besoin de ranger. Mais ranger comment ? Aucune doc publique sur les best practices.

Le problème : des règles internes, non documentées

La mémoire auto est définie dans le system prompt interne de Claude Code, dans une section intitulée auto memory. Vous ne la voyez pas, mais elle vit dans chaque session. Elle décrit :

• 4 types stricts de mémoire : user, feedback, project, reference
• Un format de body obligatoire pour feedback et project (lignes **Why:** et **How to apply:**)
• Des règles strictes pour MEMORY.md (pas de frontmatter, lignes < 150 chars, pur index)
• Une liste de choses à ne jamais sauvegarder (catalogues dérivables, historique git, fixes de bugs, doublons CLAUDE.md)

J'ai cherché ces règles dans la doc publique d'Anthropic. Rien. Le concept de mémoire est mentionné dans la doc des managed agents, mais ni le format ni les règles internes du Claude Code CLI. Tout est dans le system prompt.

Bon. Encoder ces règles dans une skill qui audite et refactore.

Ce que ça donne

Une commande :

/memory-reorganize

Et 30 secondes plus tard :

- [x] Phase 1 : Inventaire (lister fichiers, lire MEMORY.md)
- [x] Phase 2 : Audit individuel de chaque fichier mémoire
- [x] Phase 3 : Audit de MEMORY.md (format index)
- [x] Phase 4 : Détection de duplicats et chevauchements
- [x] Phase 5 : Détection de contenu dérivable
- [x] Phase 6 : Vérification de fraîcheur
- [x] Phase 7 : Rapport des violations

## Audit de la mémoire — 2026-04-28

**État actuel** : 3 fichiers + MEMORY.md (46 lignes)

### Violations critiques
- MEMORY.md L3-6 "Skills directory structure" : entièrement dérivable de `ls`
- MEMORY.md L8-19 "Existing skills" : 12 lignes dérivables d'un `ls`
- MEMORY.md L21-27 "Skills rewrite" : 7 lignes inline (devrait être supprimé)
- MEMORY.md L26 fait ~280 caractères (>150)

### Violations moyennes
- release-checklist.md : champ `originSessionId` non standard
- data-pipeline.md : section "Architecture" dérivable de `ls`

### Contenu dérivable à supprimer
- 60% de release-checklist.md : catalogue de fichiers support

La skill propose ensuite un plan de refactor structuré et demande validation explicite avant de toucher à quoi que ce soit. Elle backup tout en *.backup-YYYY-MM-DD avant d'écrire la moindre ligne. Toujours. (Demandez à n'importe quel dev qui a effacé un dossier important une fois pourquoi je précise "toujours".)

Résultat sur ma propre mémoire : 46 lignes de MEMORY.md ramenées à 5. Trois fichiers refactorés (en moyenne -50% de longueur, ajout des Why/How manquants). Aucune perte d'info de valeur.

Les règles, condensées

4 types stricts

Tout fichier qui ne rentre pas dans l'un de ces 4 types est suspect. Si vous écrivez "Memory : structure du projet", c'est ni user, ni feedback, ni project, ni reference. C'est dérivable du filesystem. Donc pas une mémoire. (Spoiler : c'est exactement ce que j'avais.)

Format Why / How to apply

Pour feedback et project, deux lignes obligatoires :

**Why:** [motivation, incident, contrainte]
**How to apply:** [quand/où cette règle s'applique]

Sans ces deux lignes, impossible de juger les cas limites plus tard. Une mémoire qui dit "ne pas commit le vendredi" sans Why deviendra ambiguë dans deux mois. No-deploy ou no-commit ? Toute la journée ou seulement après 16h ? Les vendredis fériés ? On reste là à fixer la règle nue, sans les invariants qui l'ont produite.

MEMORY.md = pur index

Règles strictes :

• Pas de frontmatter
• Une ligne par mémoire, format - [Title](file.md) — one-line hook
• Chaque ligne < 150 caractères
• Total < 200 lignes (au-delà = tronqué par le harness)
• Aucun contenu écrit directement, juste des pointeurs
• Sections sémantiques par sujet, pas chronologiques

Si votre MEMORY.md contient le mot "we", ou liste des choses, ou décrit une architecture : c'est cassé.

Ce qu'il NE FAUT PAS sauvegarder

Même si vous l'avez explicitement demandé :

• Patterns de code, architecture, chemins (dérivables)
• Historique git, qui-a-fait-quoi (git log est autoritaire)
• Recettes de debug ou fixes (le fix est dans le code)
• Tout ce qui est déjà dans CLAUDE.md
• État éphémère (tâches en cours, contexte de la conversation actuelle)
• Listes dérivables d'un ls

Le test mental : "où trouver cette info plus tard ?". Si la réponse est ls, git log, ou CLAUDE.md, ce n'est pas une mémoire.

Dates absolues

Toujours 2026-04-28. Jamais "récemment", "la semaine dernière", "il y a 2 jours". La mémoire vit pendant des mois. Les dates relatives, à 6 mois d'écart, c'est de la pure fiction.

Architecture de la skill

La skill vit dans ~/.claude/skills/memory-reorganize/ (voir sur GitHub) :

memory-reorganize/
├── SKILL.md              (orchestrateur, 171 lignes)
├── BEST_PRACTICES.md     (règles complètes, 86 lignes)
└── EXAMPLES.md           (avant/après concrets, 203 lignes)

Le pattern suit la recommandation officielle Anthropic de progressive disclosure. SKILL.md reste lean (orchestration des phases), les règles détaillées et les exemples ne sont chargés que quand la skill en a besoin. C'est pas cosmétique : ça se mesure en tokens économisés à chaque invocation. J'y reviens plus bas.

SKILL.md, orchestrateur en 10 phases

Le workflow :

Phase 1  : Inventaire (lister fichiers, lire MEMORY.md)
Phase 2  : Audit individuel vs BEST_PRACTICES.md
Phase 3  : Audit de MEMORY.md (format index)
Phase 4  : Détection duplicats / chevauchements
Phase 5  : Détection contenu dérivable
Phase 6  : Vérification de fraîcheur (refs cassées, dates relatives)
Phase 7  : Rapport des violations
Phase 8  : Plan de refactor (avec consultation EXAMPLES.md)
Phase 9  : Validation utilisateur (AskUserQuestion)
Phase 10 : Backup + application + vérif finale

Voir le fichier complet sur GitHub.

BEST_PRACTICES.md, règles encodées

Ce fichier capture les règles internes du system prompt sous forme de tableau et de checklist. C'est la source de vérité de l'audit (phase 2-6).

Pourquoi un fichier séparé ? Pour ne pas surcharger SKILL.md. La skill ne charge BEST_PRACTICES.md que pendant la phase d'audit. Le reste du temps, ces 86 lignes ne consomment aucun token. Multiplié par toutes les invocations futures, le calcul devient intéressant.

Voir sur GitHub.

EXAMPLES.md, calibrer le style du refactor

C'est le fichier qui m'a le plus surpris en termes d'impact. Sans exemples concrets, Claude refactorait correctement, mais le style variait d'un appel à l'autre. Avec 3 exemples avant/après bien choisis, le style devient déterministe. Comme un transfert de goût par démonstration : je montre ce que j'attends, Claude reproduit.

Trois cas couverts :

1. Mémoire project sans Why/How, la violation la plus fréquente
2. MEMORY.md = chaos vers index pur, la transformation la plus visible
3. Mémoire bien structurée mais trop bavarde, le cas subtil

Plus une table d'anti-patterns à la fin pour calibrer la détection.

Voir sur GitHub.

Un cas concret

Avant la skill, voilà à quoi ressemble une mémoire project typique du genre "bien intentionnée mais cassée" :

---
name: release-checklist skill architecture
description: Architecture of the release-checklist skill (refactored 2026-04-14)
type: project
originSessionId: 00000000-0000-0000-0000-000000000000
---

Pre-deploy validation skill for backend services.

Architecture (after 2026-04-14 refactor):

- `SKILL.md` (118 lines) — Lean orchestrator
- `STAGES.md` — 8 deploy stages with gating criteria
- `ROLLBACK.md` — 4 rollback procedures
- `KPIS.md` — measurable thresholds per stage

Key rules:

- No deploy on Friday after 16:00 (SRE policy)
- Mandatory canary 5% before full rollout
- Rollback within 15min if error rate > 1%
- Postmortem required for any P1/P2

Le diagnostic de la skill :

• Frontmatter avec originSessionId non standard
• Section "Architecture" entièrement dérivable d'un ls du dossier
• Pas de **Why:** ni de **How to apply:** (obligatoires pour type=project)
• "Key rules" : à garder absolument (règles SRE non dérivables)

Le résultat après refactor :

---
name: release-checklist skill
description: Pre-deploy validation skill for backend services. Blocks risky deploys and enforces mandatory SRE checks.
type: project
---

Pre-deploy skill for internal backend services.

**Why:** Reduce rollbacks (12% of deploys before introduction). Enforce canary, no-deploy-Friday, and automatic rollback <15min on >1% error rate, after the 3 P1 incidents in Q4 2025.

**How to apply:** Invoke for any release/deploy preparation. Architecture details in support files — do NOT duplicate here.

## Non-derivable operational rules

- **No deploy Friday > 16:00** (SRE policy)
- **Mandatory 5% canary** before full rollout
- **Rollback < 15min** if error rate > 1%
- **Postmortem required** for any P1/P2

26 lignes vers 16 lignes. Plus aucune duplication avec le filesystem. Le Why raconte enfin l'incident qui a motivé la règle. Le How to apply dit explicitement quand l'invoquer.

Et surtout : dans 3 mois, quand je tomberai sur l'edge case du genre "est-ce qu'on peut deploy un patch critique vendredi à 17h pour fixer une fuite de données ?", j'aurai la motivation pour décider. Pas juste la règle nue.

Garde-fous

La skill modifie des fichiers. Donc :

• Backup systématique : chaque fichier modifié est copié en *.backup-YYYY-MM-DD avant la moindre écriture
• Validation utilisateur explicite (Phase 9, via AskUserQuestion). La skill ne touche à rien sans votre OK.
• Pas de modif hors du dossier mémoire. Pas de CLAUDE.md, pas de settings.json, pas de skills.
• Préserve le contenu de valeur : si une mémoire viole les règles mais contient de l'info utile, elle est refactorée, pas supprimée
• Ne jamais inventer une mémoire : la skill réorganise ce qui est là, elle ne crée pas ex nihilo

Tester

Relancez Claude Code (les skills se chargent au démarrage), puis :

/memory-reorganize

Ou avec un focus spécifique :

/memory-reorganize duplicats
/memory-reorganize frontmatter
/memory-reorganize index

Comptez 30 secondes à 2 minutes selon la taille de votre mémoire. Sur 3 fichiers, c'est rapide. Sur 30 fichiers, la skill prend le temps de tout lire et croiser.

Ce que j'ai appris en faisant ça

Les règles internes de Claude Code ne sont pas documentées publiquement. Tout est dans le system prompt. C'est délibéré (les internes peuvent évoluer), mais ça veut dire que pour faire les choses correctement il faut soit lire son system prompt courant, soit demander à Claude lui-même les règles. La skill encode ces règles dans BEST_PRACTICES.md pour les rendre explicites. Au prix de devenir potentiellement obsolète si Anthropic change le système. C'est le deal.

Le Why change tout. J'ai testé deux versions de la skill : une qui demandait juste type + contenu, une qui exigeait Why + How to apply. La deuxième produit des mémoires utilisables à 6 mois. La première produit des mémoires que je suis incapable d'interpréter à 2 mois. Mes propres notes, deux mois plus tard, opaques. La motivation, c'est ce qui transforme une note en règle actionnable.

Le contenu dérivable est l'ennemi principal. Sur ma mémoire, c'était 60% du volume. Liste de skills (ls le donne), architecture des dossiers (tree le donne), changelogs de session (git log le donne). Ce contenu pollue chaque session sans rien apporter. Le test mental "où trouver cette info plus tard ?" devrait être systématique avant chaque sauvegarde. Je le fais maintenant. Ça a divisé par deux la taille de mes mémoires.

Progressive disclosure marche vraiment. En éclatant la skill en 3 fichiers, j'ai gagné ~30% sur la taille de SKILL.md. Les fichiers ne sont chargés que quand la skill en a besoin. Le pattern recommandé par Anthropic n'est pas un truc cosmétique. C'est mesurable en tokens économisés à chaque invocation.

La validation utilisateur n'est pas négociable. Une skill qui modifie des fichiers sans demander, c'est une skill qui finira par effacer un truc important. Un jour. AskUserQuestion ajoute 10 secondes à chaque exécution. C'est rien comparé au coût de récupérer un backup. Encore moins comparé au coût de récupérer un fichier sans backup.

Les limites

C'est un outil. Pas une autorité.

La skill applique des règles. Mais certaines de mes mémoires "violent" les règles tout en étant utiles. Par exemple une mémoire qui contient à la fois du project et du reference. La skill détecte l'ambiguïté et demande, plutôt que de trancher seule. Elle peut aussi se tromper sur le type qu'elle propose, surtout sur les mémoires courtes ou vraiment ambiguës.

Elle ne génère pas de mémoires. Si votre mémoire est vide, la skill ne va rien inventer. Elle réorganise ce qui existe, c'est tout. Pour enrichir la mémoire, c'est l'usage normal qui le fait : Claude Code sauvegarde au fil des conversations selon ses propres règles.

Et bien sûr, elle dépend de la stabilité du format de mémoire interne de Claude Code. Si Anthropic change le format demain, BEST_PRACTICES.md devient potentiellement faux. La skill est une photographie des règles à un moment donné. Il faudra la mettre à jour quand le système évoluera.

Mais pour le cas d'usage présent, un grenier qui dérape au fil des mois, c'est devenu mon outil de ménage trimestriel. 30 secondes pour auditer, 2 minutes pour valider. Et la mémoire repart propre pour 3 mois. Jusqu'à ce que je commence à y entasser à nouveau des trucs dérivables, parce qu'évidemment je le ferai.