Claude Code : créer un second cerveau avec dossiers et Git

Documentation de référence Ailoot : ailoot.ai/docs/.

Pourquoi Claude Code a-t-il besoin d’un second cerveau, et que faut-il retenir ?#

Vous ouvrez Claude Code mardi. Vous expliquez : voici le projet, voici le public, ne faites pas ceci. Vous travaillez ensemble. Jeudi, c’est une nouvelle conversation, et vous devez tout réexpliquer.

Si vous avez un fichier CLAUDE.md, vous avez résolu la première source de frustration. Les règles de base et la description du projet se trouvent dans un seul fichier et sont chargées à chaque session. J’ai expliqué le fonctionnement de ce fichier dans mon guide de CLAUDE.md - vous pouvez le lire d’abord pour mettre en place les fondations.

Mais CLAUDE.md est un manuel d’instructions destiné à un nouvel employé. Comment s’habiller, quel ton adopter avec les clients, quelles commandes utiliser pour publier. Cela ne suffit pas pour prendre de bonnes décisions concernant le projet. Les décisions nécessitent des connaissances : quel est le produit, qui est le public, comment fonctionne l’économie, ce que vous avez essayé et ce qui n’a pas marché.

D’après l’expérience de l’auteur décrite ici, ces connaissances se trouvaient auparavant à quatre endroits : dans sa tête, dans les conversations Telegram, dans les documents Google et dans la tête des employés. Un mois après une décision, personne ne se souvenait pourquoi elle avait été prise. Une nouvelle personne passait une heure à poser des questions à l’équipe pour se mettre au courant. Claude ne faisait pas du tout partie de ce contexte.

Avant le second cerveau, dans l’expérience décrite par l’auteur, chaque session impliquait de réexpliquer qui était le client, comment l’offre était structurée et quel fournisseur gérait les paiements. Avec business/, j’ouvre une conversation et je dis : « mets à jour l’offre pour le nouveau tarif » - Claude va de lui-même dans business/company/legal.md, lit les exigences, puis ouvre business/products/pricing.md, repère le nouveau tarif et propose une modification en une seule fois. La mise en contexte initiale disparaît ; le contexte se charge automatiquement.

Anthropic appelle ce problème « context rot » dans son blog d’ingénierie :

Autrement dit, plus vous entassez d’informations dans la fenêtre, moins l’agent arrive à travailler précisément. La solution consiste à conserver une structure de fichiers externes que Claude peut consulter de lui-même en réponse à une demande précise. C’est cela, un second cerveau.

Qu’est-ce qu’un second cerveau, et comment appliquer ce concept à Claude ?#

Typiquement, un second cerveau est un outil de productivité : on crée un coffre Obsidian et on y ajoute des extraits de livres, des notes d’appels et des idées de projet.

Lorsque l’auteur a appliqué cette idée à son travail avec Claude Code, il ne s’agissait plus de productivité, mais d’architecture d’agent.

Dans l’approche classique, le second cerveau vous appartient et vous y accédez manuellement. Avec Claude Code, le second cerveau devient bidirectionnel : vous et l’agent y accédez tous les deux. Cela change les exigences concernant son format.

Puisque l’agent y accède de lui-même, les fichiers doivent être dans un format qu’il comprend sans intégration supplémentaire. Markdown est idéal : du texte, une hiérarchie de titres et des liens entre les fichiers. Notion et Google Docs ne conviennent pas. Vous pouvez les connecter par MCP, mais cela ajoute une couche supplémentaire, un jeton de plus par requête et un autre point de défaillance.

Comme les fichiers se trouvent dans le système de fichiers à côté du projet, ils sont automatiquement à la portée de Claude Code. Aucune configuration n’est nécessaire. Lancez l’agent dans le dossier du projet et il peut voir tous les fichiers qu’il contient. C’est gratuit et cela fonctionne immédiatement.

Quelle hiérarchie de mémoire Claude Code possède-t-il par défaut ?#

Avant d’ajouter quoi que ce soit, voyons ce dont Claude peut se souvenir sans votre aide. Anthropic décrit deux mécanismes dans sa documentation officielle : CLAUDE.md (les règles que vous écrivez) et la mémoire automatique (les leçons que Claude écrit lui-même). Les deux sont chargés au début de chaque session.

CLAUDE.md est recherché à quatre endroits à la fois :

Les quatre fichiers sont chargés dans le contexte. Plus le niveau est spécifique, plus sa priorité est élevée. Le fichier local est lu en dernier ; ses règles remplacent donc toutes les autres.

Un fichier CLAUDE.md peut aussi se trouver dans n’importe quel dossier du projet. Lorsque Claude lit un fichier d’un sous-dossier, il charge à la demande le CLAUDE.md de ce sous-dossier. C’est utile dans un monorepo : les règles du frontend se trouvent dans frontend/CLAUDE.md, celles du backend dans backend/CLAUDE.md, et elles ne sont chargées que lorsque l’agent travaille sur la partie concernée.

La mémoire automatique est apparue dans Claude Code 2.1.59. Il s’agit de fichiers que Claude écrit à votre sujet :

~/.claude/projects/<project-name>/memory/
├── MEMORY.md          # Index, chargé à chaque session (200 lignes ou 25KB)
├── debugging.md       # Notes détaillées (chargées à la demande)
├── api-conventions.md
└── ...

Anthropic la décrit ainsi dans la documentation officielle :

La mémoire automatique s’active avec le drapeau autoMemoryEnabled dans ~/.claude/settings.json. Claude décide quoi y écrire. Vous pouvez lire MEMORY.md et le modifier à la main : c’est du Markdown ordinaire.

CLAUDE.md ou un second cerveau : où placer la limite ?#

Voici l’analogie que j’utilise dans mes conférences : imaginez que vous avez embauché un nouvel employé. Que lui donnez-vous le premier jour ?

Un manuel d’instructions : comment s’habiller, quand arriver, quel ton employer avec les clients et quel système utiliser pour publier. C’est un document court. Il n’explique pas ce que vous faites ni pourquoi. Il indique simplement comment se comporter.

Et, séparément, un accès au wiki de l’entreprise. Il explique ce qu’est le produit, à qui il s’adresse, qui est le public, quel est le prix et pourquoi, qui sont les concurrents et quelles erreurs vous avez commises. C’est une vaste archive. Personne ne la lit en entier : on la consulte pour une question précise.

CLAUDE.md = manuel d’instructions. Second cerveau = wiki. Il vous faut les deux.

La distinction est simple. Mettez dans CLAUDE.md tout ce qui est pertinent pour chaque tâche :

• Le rôle de l’agent dans ce projet (assistant, responsable, aide)
• La langue dans laquelle répondre
• La stack d’outils
• Les commandes de publication
• Les interdictions (ne pas utiliser de tirets cadratins, ne pas lancer git push --force)
• Les renvois : où trouver le contexte métier et où trouver les principes

Mettez dans le second cerveau tout ce qui est nécessaire à la demande :

• Le produit, le public, l’économie et les objectifs
• Les concurrents et le marché
• Les décisions passées et leurs raisons
• Les exemples et avis de clients
• Les principes et la méthodologie

Anthropic établit la même distinction dans sa documentation :

Les Skills sont une façon de stocker des connaissances épisodiques. Un dossier business/ à côté du projet en est une autre. J’utilise les deux et je les détaillerai plus bas.

De quoi se compose le cerveau d’un projet : 5 parties plus une machine à remonter le temps#

Exemple d’architecture tiré de l’expérience décrite par l’auteur :

Le point méthodologique essentiel est de séparer ai-clone/ et business/.

business/ répond à la question « que faisons-nous ? » Produit, public, prix, concurrents. Ce dossier concerne le projet. Si vous confiez le projet à un partenaire demain, ce dossier l’accompagnera.

ai-clone/ répond à la question « comment est-ce que je prends mes décisions ? » Mes principes, mon ton, mon savoir-faire et mes mots à éviter. Ce dossier me concerne. Si je commence un nouveau projet demain, il m’accompagnera.

Vous voulez non seulement créer un second dossier, mais aussi construire un système qui rend Claude cohérent ? Cela ne suffit pas à lui seul. Sans ai-clone/, l’agent répond pour tout le monde, pas pour vous. Sans Context Engineering, il parcourt tout le dossier et consomme des tokens. Il est utile de réunir les trois éléments : second cerveau + clone IA + Context Engineering. Ce sont les trois piliers sans lesquels l’IA hallucine.

Que mettre dans business/, et que ne pas y mettre ?#

Structure de premier niveau de business/ dans le projet décrit par l’auteur :

business/
├── INDEX.md              ← plan du dossier, à lire en premier
├── company/              ← mission, entité juridique, valeurs, politiques juridiques
├── products/             ← produits, programmes, prix
├── audience/             ← profil client, segments, objections
├── goals/                ← objectifs annuels, trimestriels et mensuels, indicateurs
├── economics/            ← économie unitaire, revenus, dépenses, prévisions
├── marketing/             ← canaux, entonnoir, supports, concurrents
├── execution/            ← planification hebdomadaire, backlog
└── assets/               ← système de conception, avis, banque de textes

C’est un exemple tiré du projet décrit par l’auteur, pas un dogme. Je crée des dossiers selon les besoins. J’ai commencé par trois (products/, audience/, goals/) ; les autres ont été ajoutés après 2-3 mois, quand il est devenu difficile de savoir où ranger les nouveaux éléments.

Le fichier principal du dossier est INDEX.md. C’est une carte. Il contient un tableau « question → fichier » que Claude utilise pour savoir où aller. Sans lui, l’agent gaspille des tokens à lire tous les fichiers dans l’ordre.

Extrait d’exemple de INDEX.md :

### Où trouver les informations

| Besoin | Où chercher |
|---|---|
| Qui est notre client et quels sont ses points de douleur | `business/audience/avatar.md` |
| Produits, offres et prix | `business/products/` |
| Objectifs et indicateurs | `business/goals/` |
| Économie (revenus, dépenses, économie unitaire) | `business/economics/` |
| Canaux et supports de promotion | `business/marketing/` |

Une seule ligne dans CLAUDE.md suffit alors : « Pour les questions métier, lis business/INDEX.md et suis le plan. » L’agent ne charge pas tout le dossier dans le contexte. Il charge le plan, choisit le bon fichier et ne lit que celui-là.

Liste de contrôle des éléments à ne pas mettre dans business/ :

• Les conversations brutes sans traitement. S’il y a un enseignement à en tirer, synthétisez-le et consignez-le. Sinon, laissez-les de côté.
• Les informations déjà présentes dans le code. « Les paiements passent par CloudPayments » est inutile ; l’agent peut le voir dans le code.
• Les captures d’écran et images. Elles augmentent la taille du dossier et ne sont pas analysées par un modèle textuel sans étape supplémentaire.
• Les chiffres dynamiques. « Aujourd’hui, il y a 423 paiements pour le produit » sera périmé dans une semaine. Utilisez le marqueur LIVE et un lien vers une requête de base de données.
• Les informations sensibles ou discutables. Si le dépôt était publié demain sur YouTube devant 100 mille inconnus, ne gardez que ce que vous accepteriez de montrer. Les employés, les agents et parfois des prestataires externes lisent ce dossier.

Pourquoi avoir un dossier ai-clone séparé, et pourquoi ne pas le mélanger à business ?#

L’idée est simple : l’entreprise sait ce que nous faisons. Le clone sait comment je prends mes décisions.

Structure de ai-clone/ dans le projet décrit par l’auteur :

ai-clone/
├── INDEX.md           ← plan du dossier
├── role.md            ← qui je suis, mon parcours, ce qui compte
├── identity/          ← valeurs, vision, mission
├── thinking/          ← modèles mentaux tirés de conférences
├── voice/             ← ton, vocabulaire, style
├── principles/        ← convictions sur le produit, le code, l’entreprise
├── feedback/          ← règles tirées des erreurs ← dossier principal
├── style/             ← mots à éviter, format Telegram
└── reference/         ← outils, environnement

Le dossier le plus utile est feedback/. Il contient des règles précises que j’ai apprises à la suite d’erreurs de l’agent. Chaque règle est placée dans un fichier distinct selon ce format :

---
name: short-name
description: une ligne - ce que contient le fichier et quand appliquer la règle
type: feedback
---

Une règle courte en une phrase.

**Pourquoi :** pourquoi cette règle existe. Contexte, incident, observation.

**Comment l’appliquer :** déclencheurs précis indiquant quand la règle s’applique.

Sans « Pourquoi », la règle est morte : l’agent ne la transposera pas à une situation similaire. Sans « Comment l’appliquer », il ne saura pas quand utiliser la règle.

Un exemple tiré de mon dossier : la règle « trait d’union, pas de tiret cadratin ». Elle vient du fait que le tiret cadratin — est un marqueur visuel important des textes générés. Elle s’applique à tout texte destiné au public. Le fichier se trouve dans ai-clone/feedback/no-em-dashes.md.

Je procède un peu différemment : j’écris les règles dans ai-clone/feedback/, pas dans CLAUDE.md. CLAUDE.md est un fichier du projet, mais les règles de ton et de style sont personnelles. Elles me suivent dans le projet suivant. CLAUDE.md reste avec le projet.

Que sont les Live Metrics, et pourquoi ne pas inscrire des chiffres en dur dans les fichiers ?#

L’un des principaux pièges au démarrage d’un second cerveau consiste à le remplir de chiffres périmés. Vous écrivez « nous avons 320 clients », et deux semaines plus tard, ils sont déjà 410. Vous écrivez « le chiffre d’affaires mensuel est de 4.7 millions », et un mois plus tard le chiffre a perdu son contexte : s’agit-il d’un objectif, d’un résultat réel ou d’une prévision ?

Dans l’exemple de l’auteur, le fonctionnement est le suivant. Dans le fichier business/products/practicum.md, un marqueur remplace le chiffre :

## Cohortes

> **LIVE** - exécutez les requêtes de `live-metrics.md`, section « Ventes »
> pour consulter les paiements actuels par cohorte.

| Cohorte | Dates | Payants |
|-------|------|------------|
| 1 | 10-12 mars 2026 | LIVE |
| 2 | 24-26 mars 2026 | LIVE |

Un fichier distinct live-metrics.md contient des requêtes SQL prêtes à exécuter et la description de leurs résultats :

## Ventes (paiements par cohorte)

```sql
SELECT c.name, COUNT(p.id) AS paid, SUM(p.amount) AS revenue
FROM purchases p
JOIN cohorts c ON c.id = p.cohort_id
WHERE p.status = 'paid'
GROUP BY c.name
ORDER BY c.starts_at DESC;
```

Quand je demande à l’agent « combien de paiements avons-nous pour la deuxième cohorte ? », il :

1. Lit business/products/practicum.md
2. Repère le marqueur LIVE à côté du chiffre
3. Ouvre live-metrics.md
4. Trouve la section « Ventes »
5. Exécute la requête sur la base de données de production
6. Répond avec des données actualisées

Cela résout deux problèmes à la fois. Les chiffres ne deviennent pas périmés. Et les décisions sont prises à partir de la situation actuelle, pas de celle de l’année dernière.

Comment l’IA navigue-t-elle dans le second cerveau pour une seule requête ?#

Une demande précise, par exemple : « rédige un e-mail aux participants au sujet de la nouvelle cohorte ».

1. Claude commence avec une fenêtre vide. Il charge CLAUDE.md (règles, stack, chemins d’accès).
2. Grâce aux renvois dans CLAUDE.md, il voit : « ai-clone/INDEX.md - à lire au début de chaque session ». Il ouvre le fichier et apprend qui je suis, quel est mon ton et quels mots à éviter j’emploie.
3. Il voit dans les renvois : « modèles d’e-mails - src/lib/email/layout.ts ». Il ouvre le fichier et comprend le format.
4. Il voit : « contexte produit - business/products/practicum.md ». Il ouvre le fichier et prend connaissance du produit.
5. Il voit le marqueur LIVE dans le fichier et un renvoi vers live-metrics.md. Il ouvre le fichier et trouve le SQL prêt à exécuter. S’il lui faut un chiffre actuel, il lance la requête. Sinon, il indique « récupérer ce chiffre au moment de l’envoi ».
6. Il consulte les règles de ton dans ai-clone/style/telegram-format.md, l’interdiction des tirets cadratins dans ai-clone/feedback/no-em-dashes.md et les taux de conversion du funnel dans business/marketing/funnel.md.

Il rédige l’e-mail avec mon ton, des chiffres à jour et sans tirets cadratins ni marqueurs d’IA.

Anthropic appelle cette approche le contexte « juste à temps » dans son blog d’ingénierie :

Autrement dit, Claude transporte des pointeurs vers les données, et non les données elles-mêmes. C’est beaucoup plus efficace en tokens et beaucoup plus précis, car seules les informations pertinentes entrent dans le contexte. La fenêtre reste dégagée pour le raisonnement.

5 anti-patterns du second cerveau : que faut-il éviter ?#

Anti-pattern 1. Un CLAUDE.md trop volumineux. 500 lignes d’instructions « au lieu de tout mettre au même endroit ». Anthropic est direct :

La longueur cible est de 80-120 lignes. Placez tout le reste dans des fichiers séparés et indiquez leur chemin.

Anti-pattern 2. Un dossier fourre-tout. Vous mettez tout dans le second cerveau : conversations brutes, captures d’écran inutiles, rapports que personne ne lira. Un mois plus tard, le dossier a gonflé, l’agent gaspille des tokens à lire des choses inutiles et vous ne savez plus où se trouve quoi. La règle : chaque fichier du second cerveau doit répondre à une question précise. Si personne ne l’a ouvert depuis six mois, supprimez-le ou déplacez-le dans les archives.

Anti-pattern 3. Les doublons. « Les paiements passent par CloudPayments, dans src/lib/payment/cloudpayments.ts ; le fournisseur est configuré dans .env. » L’agent peut voir tout cela dans le code. Ne le dupliquez pas dans business/. Les doublons deviennent obsolètes : le code change, business/ n’est pas mis à jour, et l’agent travaille à partir d’informations périmées.

Anti-pattern 4. Les chiffres inscrits en dur. « Nous avons 1,247 clients, avec un taux de conversion de 6.3 % » - imaginez qu’il s’agisse de chiffres provenant d’une start-up fintech abstraite. Tous ces chiffres seront périmés dans une semaine. Utilisez le marqueur LIVE et live-metrics.md. La section consacrée à ce sujet se trouve plus haut.

Anti-pattern 5. Un contexte sans chemin accessible. Si le second cerveau est ailleurs sans permission ni lien pour l’agent, démarrer dans le code ne suffit pas. Les notes partagées non sensibles peuvent rester dans business/ et ai-clone/ avec le code. Gardez le contexte privé dans un emplacement aux accès contrôlés, avec permissions et routage explicites. La commodité des dossiers ne prime pas sur la confidentialité.

Comment créer un second cerveau en une heure : guide étape par étape#

1. Créez deux dossiers racine

   À la racine du projet, à côté de src/ :

   mkdir -p business/{products,audience,goals,economics,marketing}
   mkdir -p ai-clone/{identity,voice,principles,feedback,style}
   

2. Créez un INDEX.md comme plan du dossier

   business/INDEX.md est un tableau « question → fichier ». Commencez par au moins 5 lignes et ajoutez-en au fur et à mesure. Faites de même dans ai-clone/INDEX.md.

3. Ajoutez de courtes descriptions du produit et du client

   business/products/main.md - ce qu’est le produit, à qui il s’adresse, son prix et ce qui le différencie. 30-50 lignes. business/audience/avatar.md - qui est le client, quels sont ses points de douleur et ce qu’il achète. 30-50 lignes. Ne décrivez pas un client idéal ; décrivez un client réel. Si vous ne savez pas quelque chose, marquez-le « à clarifier » et continuez.

4. Décrivez-vous dans ai-clone/role.md

   Qui vous êtes, ce que vous faites et ce qui compte pour vous. 20-30 lignes. C’est suffisant pour commencer. Ajoutez le ton, les principes et les mots à éviter lorsque vous remarquez que l’agent écrit dans un style qui ne vous ressemble pas.

5. Ajoutez les renvois dans CLAUDE.md

   Ouvrez CLAUDE.md et ajoutez une section :

   ## Plan du projet
   
   - Contexte métier → `business/INDEX.md`
   - Contexte à mon sujet → `ai-clone/INDEX.md`
   - Plans techniques → `plans/YYYY-MM-DD-*.md`
   - Bilans des sessions précédentes → `retrospectives/`
   
   Lisez toujours `ai-clone/INDEX.md` et `business/INDEX.md` au début d’une session.
   

6. Lancez Claude Code et vérifiez

   Ouvrez l’agent. Demandez-lui : « parle-moi de mon produit et de mon public ». S’il répond à partir du contexte des dossiers, cela fonctionne. S’il invente des choses, vérifiez que les dossiers sont à côté du projet, que les fichiers portent les bons noms et que les renvois dans CLAUDE.md sont formulés avec précision.

Ensuite, le second cerveau se développe selon deux principes.

Premièrement : chaque fois que l’agent fait une erreur, ajoutez une règle. Au bout de 3-4 semaines, ai-clone/feedback/ contiendra 15-20 fichiers de règles, et l’agent cessera de faire les erreurs les plus courantes.

Deuxièmement : chaque fois que vous prenez une décision métier, consignez-la dans business/. Si vous augmentez un prix, ajoutez une note à business/products/pricing.md avec la date et la raison. Si vous changez de positionnement, ajoutez une note à business/company/about.md. Six mois plus tard, vous aurez une archive qui se souvient du « pourquoi ».

Nous avons accompli ensemble une quantité importante de travail cette semaine.

Analyse toutes les modifications de code de cette semaine, tous les commits que nous avons faits.
Quelles informations utiles devraient figurer dans business/ ? Écris-les dans les fichiers appropriés
avec des liens wiki vers les fichiers voisins afin que le contexte ne se perde pas.

Si le code contient des décisions que je n’ai pas expliquées, demande-moi pourquoi
et consigne la raison dans le fichier approprié, en indiquant la date.

Ne duplique pas ce qui est déjà évident dans le code. N’inclus que ce que l’agent
ne saurait pas lors de la prochaine session sans business/.

Et ensuite : Skills, Subagents et Context Engineering#

Une fois le second cerveau en place, il existe trois autres outils qu’Anthropic décrit comme trois niveaux différents d’optimisation du contexte.

Les Skills sont des connaissances procédurales. Si vous répétez un flux de travail (rédiger un guide pédagogique, préparer une publication Telegram, auditer un site Web), vous pouvez le coder dans un fichier SKILL.md avec une description de tâche. Au début d’une session, Claude parcourt les noms et les descriptions des Skills et ne charge que ceux qui correspondent à la tâche en cours. Cela économise des tokens et maintient le cap.

Les Subagents sont des instances isolées de Claude, avec leurs propres fenêtres de contexte. Lancez un Subagent pour une tâche exigeante (lire 30 fichiers et préparer un résumé) ; il travaille dans sa propre fenêtre et ne renvoie que le résultat. Votre fenêtre principale reste dégagée. Anthropic écrit :

Le Context Engineering consiste à gérer ce qui entre dans la fenêtre. Anthropic l’a qualifié de compétence fondamentale pour travailler avec des agents en 2025, un niveau au-dessus du prompt engineering. Le prompt engineering consiste à choisir la formulation. Le Context Engineering consiste à choisir les fichiers, les chemins, les Skills et les Subagents.

Un second cerveau est la première brique du Context Engineering. Sans lui, les Skills lisent un espace vide, les Subagents n’ont nulle part où aller et la fenêtre de l’agent se remplit d’informations aléatoires. Avec lui, les trois outils se mettent à fonctionner.

Prochaine étape. Créez deux dossiers à côté du projet : business/ et ai-clone/. Ajoutez dans chacun un INDEX.md de 5 lignes qui sert de plan. Ajoutez quatre lignes de renvoi à CLAUDE.md. En une heure, vous aurez un cadre opérationnel pour votre second cerveau. Développez-le ensuite selon la règle « après chaque erreur de l’agent, ajoutez une ligne à ai-clone/feedback/ ». J’explique le modèle complet de CLAUDE.md qui permet de renvoyer au second cerveau dans le guide Comment bien configurer CLAUDE.md.

Continuez à découvrir Ailoot sur ailoot.ai.