Le problème : des sessions sans mémoire
Quand vous travaillez avec Claude Code, chaque session produit des décisions techniques, des patterns découverts, des erreurs corrigées. Mais une fois la session terminée, tout ça disparait. Vous recommencez à zéro la prochaine fois, et vous risquez de refaire les mêmes erreurs ou de re-découvrir les mêmes patterns.
Le CLAUDE.md résout une partie du problème - il donne des instructions à Claude. Mais il ne capture pas les leçons apprises en cours de route. C'est un document prescriptif ("fais ceci"), pas un journal descriptif ("voila ce qu'on a appris").
J'ai voulu un système ou Claude Code documente automatiquement ce qu'il apprend à chaque session, dans un format structureet consultable.
Le setup : deux mécanismes combines
Mon système repose sur deux éléments dans la configuration globale de Claude Code :
1. Le plugin "explanatory output style"
Claude Code dispose d'un système de plugins officiels qui modifient le comportement de l'agent. Pour voir et activer les plugins disponibles, tapez /plugins dans le terminal Claude Code. J'ai active le plugin explanatory-output-style, un plugin officiel maintenu par Anthropic :
{
"enabledPlugins": {
"explanatory-output-style@claude-plugins-official": true
}
}Ce plugin est aussi activable directement en éditant ~/.claude/settings.json. Il change le comportement de Claude Code : au lieu de simplement exécuter du code, il explique ses choix au fur et à mesure. Avant et après chaque bloc de code, il produit des "insights" - des points d'apprentissage encadres par des balises visuelles :
★ Insight ─────────────────────────────────────
[2-3 points educatifs sur le code ecrit]
─────────────────────────────────────────────────Ces insights ne sont pas du remplissage. Ils couvrent des décisions spécifiques au projet : pourquoi tel pattern plutôt qu'un autre, quel piège éviter avec telle API, quelle convention CSS adopter pour ce codebase précis.
2. L'instruction dans le CLAUDE.md global
Le plugin génère les insights dans la conversation, mais ils disparaissent avec la session. Pour les rendre persistants, j'ai ajoute cette instruction dans mon ~/.claude/CLAUDE.md (le fichier global, applique à tous les projets) :
## Fichier Insights
Pour chaque projet, maintenir un fichier `.claude/insights.md`
qui collecte les points d'apprentissage techniques generes
pendant les sessions de travail.
- A la premiere session d'un projet, creer le fichier
`.claude/insights.md`.
- A chaque session, ajouter les nouveaux insights
(balises ★ Insight) dans ce fichier, groupes par date.
- Chaque insight doit inclure : un tag de categorie
entre crochets, un titre court en gras, et une
explication claire.
- Format par session :
### [DATE] - [Contexte de la session]
- **[Categorie]** - **Titre de l'insight**
Description claire avec exemples de code si pertinent.C'est tout. Ces deux éléments combines font que Claude Code :
- Génère des insights pendant qu'il travaille (plugin)
- Les sauvegarde dans
.claude/insights.mdà chaque session (instruction CLAUDE.md)
À quoi ça ressemble en pratique
Voici un extrait réel du fichier .claude/insights.md de ce site (thisishumanmade.com), accumule sur plusieurs sessions :
### 2026-02-14 - Article tutoriel Claude Code cours complet
- **[Template HTML]** - **Structure des timestamps cliquables**
Les timestamps sont des <button class="timestamp-link"
data-time="SECONDS">. Le script JS modifie le src de
l'iframe YouTube avec ?start=X&autoplay=1. Le data-time
est en secondes, pas en MM:SS.
- **[SEO]** - **Schema JSON-LD VideoObject pour les articles tuto**
Les articles avec video doivent inclure un schema VideoObject
imbrique dans le schema Article. Le embedUrl utilise
youtube.com/embed/VIDEO_ID, pas watch?v=.
### 2026-02-12 - Firebase Realtime DB + App Mac menu bar
- **[Architecture]** - **Firebase Realtime DB vs Firestore**
Pour un cas 1-admin (status + messages), Realtime Database
est meilleur : pricing simple, SSE natif, latence plus faible.
- **[Swift]** - **SSE pour Firebase REST sans SDK**
Firebase supporte SSE nativement : un header Accept:
text/event-stream sur un GET garde la connexion ouverte.
URLSession.shared.bytes(from:) donne un async stream propre.
### 2026-02-05 - Workflow architecture complete
- **[Deploy]** - **Le script FTP differentiel est reutilisable**
Le pattern deploy.js (basic-ftp + timestamp .last-deploy +
exclusions) detecte les fichiers modifies via mtime. Tente
FTPS puis FTP en fallback. Reutilisable tel quel.Le fichier de ce seul projet fait déjà ~240 lignes et couvre 12 sessions de travail. Chaque session ajoute entre 2 et 8 insights, selon la complexité du travail.
Pourquoi c'est utile
1. La mémoire du projet survit aux sessions
Claude Code à une fenêtre de contexte limitée (~200K tokens). Quand une session se termine ou que le contexte est compacte, les détails fins disparaissent. Le fichier insights.md capture ces détails avant qu'ils soient perdus. À la session suivante, Claude peut relire ce fichier et retrouver le contexte technique du projet.
2. Les erreurs ne se répètent pas
Si un insight note "les sites Wix sont invisibles au scraping classique, utiliser des screenshots", la prochaine session ne perdra pas 10 minutes à essayer du scraping HTML sur un site Wix. C'est l'équivalent du CLAUDE.md, mais auto-génère et organique - il croit avec le projet.
3. C'est un journal de bord technique lisible par un humain
Le format [Categorie] - Titre - Description est conçu pour le scan rapide. Vous pouvez parcourir le fichier en 30 secondes et retrouver un pattern où une décision d'il y a deux semaines. Les catégories ([CSS], [Architecture], [Firebase], [SEO]...) permettent de filtrer mentalement.
4. Ça forme une base de connaissances réutilisable
Certains insights sont spécifiques au projet. D'autres sont universels ("le YouTube embed pese ~800KB, utiliser un placeholder"). Avec le temps, vos fichiers insights.md deviennent une bibliothèque de patterns que vous pouvez copier d'un projet à l'autre.
5. Ça documente le "pourquoi", pas juste le "quoi"
Le code dit ce qui a été fait. Les commits disent quand. Les insights disent pourquoi - pourquoi ce pattern, pourquoi pas l'alternative, quel piège ça évite. C'est la couche de documentation la plus difficile à maintenir manuellement, et ici elle est gratuite.
Comment mettre en place le même système
Étape 1 : activer le plugin explanatory
Ouvrez Claude Code dans votre terminal et tapez /plugins. Une liste de plugins officiels s'affiche - activez explanatory-output-style. C'est un plugin officiel maintenu par Anthropic, intégré dans Claude Code (rien à installer via npm ou pip).
Vous pouvez aussi l'activer manuellement en éditant ~/.claude/settings.json :
"enabledPlugins": {
"explanatory-output-style@claude-plugins-official": true
}Étape 2 : ajouter l'instruction dans votre CLAUDE.md global
Éditez ~/.claude/CLAUDE.md et ajoutez le bloc d'instructions suivant. Adaptez le format à vos préférences :
## Fichier Insights
Pour chaque projet, maintenir un fichier `.claude/insights.md`
qui collecte les points d'apprentissage techniques generes
pendant les sessions de travail.
- A la premiere session, creer `.claude/insights.md`.
- A chaque session, ajouter les nouveaux insights groupes
par date.
- Format : **[Categorie]** - **Titre** + Description.Étape 3 : laisser faire
C'est tout. À la prochaine session de travail sur n'importe quel projet, Claude Code va :
- Générer des insights pendant qu'il code (grâce au plugin)
- Les sauvegarder dans
.claude/insights.md(grâce à l'instruction globale)
Le fichier se remplit au fil des sessions, automatiquement.
Quelques conseils d'usage
- Ne le mettez pas dans le .gitignore - le fichier a de la valeur pour vos collègues aussi. Si vous travaillez en équipe, les insights d'un développeur profitent aux autres.
- Relisez-le de temps en temps - c'est un bon réflexe en début de session pour se remettre dans le contexte du projet.
- Élaguez si nécessaire - après quelques mois, certains insights deviennent obsolètes. Supprimez-les ou archivez-les.
- Utilisez les catégories pour retrouver vite - un
Ctrl+Fsur[CSS]ou[Firebase]filtre instantanément. - Combinez avec le CLAUDE.md - quand un insight revient souvent, promouvez-le en règle dans le CLAUDE.md du projet. L'insight est un brouillon, le CLAUDE.md est la règle.