Le probleme : des sessions sans memoire
Quand vous travaillez avec Claude Code, chaque session produit des decisions techniques, des patterns decouverts, des erreurs corrigees. Mais une fois la session terminee, tout ca disparait. Vous recommencez a zero la prochaine fois, et vous risquez de refaire les memes erreurs ou de re-decouvrir les memes patterns.
Le CLAUDE.md resout une partie du probleme — il donne des instructions a Claude. Mais il ne capture pas les lecons 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 systeme ou Claude Code documente automatiquement ce qu'il apprend a chaque session, dans un format structureet consultable.
Le setup : deux mecanismes combines
Mon systeme repose sur deux elements dans la configuration globale de Claude Code :
1. Le plugin "explanatory output style"
Claude Code dispose d'un systeme 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 editant ~/.claude/settings.json. Il change le comportement de Claude Code : au lieu de simplement executer du code, il explique ses choix au fur et a mesure. Avant et apres 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 decisions specifiques au projet : pourquoi tel pattern plutot qu'un autre, quel piege eviter avec telle API, quelle convention CSS adopter pour ce codebase precis.
2. L'instruction dans le CLAUDE.md global
Le plugin genere 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 a 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 elements combines font que Claude Code :
- Genere des insights pendant qu'il travaille (plugin)
- Les sauvegarde dans
.claude/insights.mda chaque session (instruction CLAUDE.md)
A quoi ca ressemble en pratique
Voici un extrait reel 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 deja ~240 lignes et couvre 12 sessions de travail. Chaque session ajoute entre 2 et 8 insights, selon la complexite du travail.
Pourquoi c'est utile
1. La memoire du projet survit aux sessions
Claude Code a une fenetre de contexte limitee (~200K tokens). Quand une session se termine ou que le contexte est compacte, les details fins disparaissent. Le fichier insights.md capture ces details avant qu'ils soient perdus. A la session suivante, Claude peut relire ce fichier et retrouver le contexte technique du projet.
2. Les erreurs ne se repetent pas
Si un insight note "les sites Wix sont invisibles au scraping classique, utiliser des screenshots", la prochaine session ne perdra pas 10 minutes a essayer du scraping HTML sur un site Wix. C'est l'equivalent du CLAUDE.md, mais auto-genere 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 concu pour le scan rapide. Vous pouvez parcourir le fichier en 30 secondes et retrouver un pattern ou une decision d'il y a deux semaines. Les categories ([CSS], [Architecture], [Firebase], [SEO]...) permettent de filtrer mentalement.
4. Ca forme une base de connaissances reutilisable
Certains insights sont specifiques au projet. D'autres sont universels ("le YouTube embed pese ~800KB, utiliser un placeholder"). Avec le temps, vos fichiers insights.md deviennent une bibliotheque de patterns que vous pouvez copier d'un projet a l'autre.
5. Ca documente le "pourquoi", pas juste le "quoi"
Le code dit ce qui a ete fait. Les commits disent quand. Les insights disent pourquoi — pourquoi ce pattern, pourquoi pas l'alternative, quel piege ca evite. C'est la couche de documentation la plus difficile a maintenir manuellement, et ici elle est gratuite.
Comment mettre en place le meme systeme
Etape 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, integre dans Claude Code (rien a installer via npm ou pip).
Vous pouvez aussi l'activer manuellement en editant ~/.claude/settings.json :
"enabledPlugins": {
"explanatory-output-style@claude-plugins-official": true
}Etape 2 : ajouter l'instruction dans votre CLAUDE.md global
Editez ~/.claude/CLAUDE.md et ajoutez le bloc d'instructions suivant. Adaptez le format a vos preferences :
## 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.Etape 3 : laisser faire
C'est tout. A la prochaine session de travail sur n'importe quel projet, Claude Code va :
- Generer des insights pendant qu'il code (grace au plugin)
- Les sauvegarder dans
.claude/insights.md(grace a 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 collegues aussi. Si vous travaillez en equipe, les insights d'un developpeur profitent aux autres.
- Relisez-le de temps en temps — c'est un bon reflexe en debut de session pour se remettre dans le contexte du projet.
- Elaguez si necessaire — apres quelques mois, certains insights deviennent obsoletes. Supprimez-les ou archivez-les.
- Utilisez les categories pour retrouver vite — un
Ctrl+Fsur[CSS]ou[Firebase]filtre instantanement. - Combinez avec le CLAUDE.md — quand un insight revient souvent, promouvez-le en regle dans le CLAUDE.md du projet. L'insight est un brouillon, le CLAUDE.md est la regle.