Tutoriel

insights.md - un journal technique auto-génÚre par Claude Code

À chaque session de travail, Claude Code gĂ©nĂšre des "insights" - des points d'apprentissage techniques. J'ai configurĂ© mon setup pour qu'il les sauvegarde automatiquement dans un fichier persistant, projet par projet. Voici comment et pourquoi.

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 :

  1. GĂ©nĂšre des insights pendant qu'il travaille (plugin)
  2. 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 :

  1. Générer des insights pendant qu'il code (grùce au plugin)
  2. 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+F sur [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.