Tutoriel

insights.md - a technical journal auto-generated by Claude Code

During every work session, Claude Code generates "insights" - technical learning points. I configured my setup so it saves them automatically to a persistent file, project by project. Here's how and why.

The problem: sessions with no memory

When you work with Claude Code, every session produces technical decisions, discovered patterns, and fixed bugs. But once the session ends, all of that disappears. You start from scratch next time, and risk repeating the same mistakes or rediscovering the same patterns.

The CLAUDE.md solves part of the problem - it gives instructions to Claude. But it doesn't capture the lessons learned along the way. It's a prescriptive document ("do this"), not a descriptive log ("here's what we learned").

I wanted a system where Claude Code automatically documents what it learns in each session, in a structured, searchable format.

The setup: two combined mechanisms

My system relies on two elements in Claude Code's global configuration:

1. The "explanatory output style" plugin

Claude Code has a system of official plugins that change the agent's behavior. To see and enable the available plugins, type /plugins in the Claude Code terminal. I enabled the plugin explanatory-output-style, an official plugin maintained by Anthropic:

{
  "enabledPlugins": {
    "explanatory-output-style@claude-plugins-official": true
  }
}

This plugin can also be enabled directly by editing ~/.claude/settings.json. It changes Claude Code's behavior: instead of simply executing code, it explains its choices as it goes. Before and after each code block, it produces "insights" - learning points framed by visual tags:

★ Insight ─────────────────────────────────────
[2-3 points educatifs sur le code ecrit]
─────────────────────────────────────────────────

These insights aren't filler. They cover project-specific decisions: why this pattern rather than another, what pitfall to avoid with a given API, which CSS convention to adopt for this specific codebase.

2. The instruction in the global CLAUDE.md

The plugin generates insights within the conversation, but they disappear with the session. To make them persistent, I added this instruction to my ~/.claude/CLAUDE.md (the global file, applied to all projects):

## 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.

That's it. These two elements combined mean Claude Code:

  1. Generates insights while it works (plugin)
  2. Saves them to .claude/insights.md at each session (CLAUDE.md instruction)

What it looks like in practice

Here's a real excerpt from the .claude/insights.md file for this site (thisishumanmade.com), accumulated over several 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.

This single project's file is already ~240 lines long and covers 12 work sessions. Each session adds between 2 and 8 insights, depending on the complexity of the work.

Why it matters

1. Project memory survives sessions

Claude Code has a limited context window (~200K tokens). When a session ends or the context is compacted, fine-grained details disappear. The insights.md file captures these details before they're lost. In the next session, Claude can re-read this file and recover the project's technical context.

2. Mistakes don't repeat

If an insight notes "Wix sites are invisible to classic scraping, use screenshots", the next session won't waste 10 minutes trying HTML scraping on a Wix site. It's the equivalent of a CLAUDE.md, but auto-generated and organic - it grows with the project.

3. It's a technical logbook readable by a human

The format [Category] - Title - Description is designed for quick scanning. You can skim the file in 30 seconds and find a pattern or a decision from two weeks ago. The categories ([CSS], [Architecture], [Firebase], [SEO]...) let you filter mentally.

4. It forms a reusable knowledge base

Some insights are project-specific. Others are universal ("the YouTube embed weighs ~800KB, use a placeholder"). Over time, your insights.md files become a library of patterns you can copy from one project to another.

5. It documents the "why", not just the "what"

The code says what was done. Commits say when. Insights say why - why this pattern, why not the alternative, what pitfall it avoids. It's the hardest layer of documentation to maintain manually, and here it's free.

How to set up the same system

Step 1: enable the explanatory plugin

Open Claude Code in your terminal and type /plugins. A list of official plugins appears - enable explanatory-output-style. It's an official plugin maintained by Anthropic, built into Claude Code (nothing to install via npm or pip).

You can also enable it manually by editing ~/.claude/settings.json :

"enabledPlugins": {
  "explanatory-output-style@claude-plugins-official": true
}

Step 2: add the instruction to your global CLAUDE.md

Edit ~/.claude/CLAUDE.md and add the following instruction block. Adapt the format to your 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.

Step 3: let it run

That's it. At the next work session on any project, Claude Code will:

  1. Generate insights while it codes (thanks to the plugin)
  2. Save them to .claude/insights.md (thanks to the global instruction)

The file fills up over sessions, automatically.

A few usage tips

  • Don't put it in .gitignore - the file has value for your colleagues too. If you work as a team, one developer's insights benefit the others.
  • Reread it from time to time - it's a good habit at the start of a session to get back into the project's context.
  • Prune it if needed - after a few months, some insights become outdated. Delete or archive them.
  • Use categories to find things fast - a Ctrl+F on [CSS] or [Firebase] filters instantly.
  • Combine it with CLAUDE.md - when an insight keeps coming up, promote it to a rule in the project's CLAUDE.md. The insight is a draft, the CLAUDE.md is the rule.