Comment configurer CLAUDE.md en 2026 : modèle et 6 règles

Des ressources sur le vibe coding : outils, études de cas, erreurs. Guides Ailoot.

Pourquoi avez-vous besoin de CLAUDE.md, et pourquoi Claude oublie-t-il le projet sans ce fichier ?#

Vous ouvrez Claude Code mardi et vous expliquez : « Je travaille sur ce projet, voici les outils, ne fais pas ça. » Ça fonctionne.

Jeudi, cette conversation est déjà terminée, alors vous répétez tout. Samedi, encore une fois ; lundi, une fois de plus.

Voilà à quoi ressemble le travail avec un agent sans CLAUDE.md : chaque nouvelle fenêtre est un stagiaire qui part de zéro et à qui vous devez répéter les mêmes choses encore et encore. Avant, je passais 5-10 minutes à taper ces consignes de démarrage à chaque session. Les prompts devenaient longs parce que je devais fournir tout le contexte manuellement. Et le résultat restait générique : l’agent ne connaissait ni mon public, ni mon modèle économique, ni mes principes.

Avec un CLAUDE.md vivant, la mise en route disparaît. Toutes les règles que vous répétiez dans chaque conversation se trouvent dans un seul fichier et apparaissent automatiquement au début de chaque session. Le prompt devient court : « fais X », au lieu de « je travaille sur le projet Y, les outils sont Z, ne fais pas A ni B et, au fait, souviens-toi aussi de C ».

Les erreurs répétées disparaissent alors.

Chaque erreur de l’agent est une raison d’ajouter une ligne à CLAUDE.md. Au bout d’un mois, vous avez une « constitution du projet » évolutive, et Claude cesse de tomber dans les mêmes pièges habituels.

Il y a aussi un troisième niveau : l’agent cesse d’écrire dans le vide. Grâce à CLAUDE.md, je dirige Claude vers des dossiers contenant du contexte : où trouver des informations sur le public, les tarifs et l’image de marque. Sans ce routage, l’agent rédige des « solutions de qualité » sans connaître mon modèle économique ; le résultat est donc abstrait, stéréotypé et « comme tous les autres ».

Qu’est-ce que CLAUDE.md, et dans quel ordre Claude le lit-il ?#

Anthropic décrit ainsi CLAUDE.md dans sa documentation officielle :

Les quatre emplacements où Claude Code recherche CLAUDE.md, par ordre croissant de priorité :

Les quatre fichiers sont chargés simultanément dans le contexte. Si les règles se contredisent, Anthropic indique directement dans sa documentation qu’on ne sait pas lequel prévaudra ; Claude peut en choisir un arbitrairement. Il est donc plus simple de conserver tout ce qui est essentiel dans le CLAUDE.md du projet et d’éviter les doublons.

Il existe un détail technique dont presque personne ne parle, mais qui explique bien des comportements étranges.

Autrement dit, CLAUDE.md n’est pas un « prompt système » au sens strict. C’est le premier message utilisateur que Claude voit. Ses règles sont donc de fortes recommandations, pas des lois. Pour imposer une règle, utilisez un hook testé sur l’événement couvert et des permissions ou une isolation pour les limites d’accès plus larges. Le lancement automatique d’un hook ne rend pas ses contrôles complets. J’expliquerai plus bas la limite entre les hooks et CLAUDE.md.

Comment rédiger un CLAUDE.md minimal en 5 minutes (modèle prêt à l’emploi) ?#

Voici un modèle que j’ai testé dans des dizaines de mes projets. Il maintient le fichier autour de 80-120 lignes, conformément au conseil d’Anthropic de viser moins de 200 lignes. Avec ce modèle, l’agent fournit les résultats les plus pertinents.

# [PROJECT NAME] - project navigation

This document is the project map. Read it at the start of every session
to understand where things are and how to work with them.

## What this project is

**[NAME]** - [one sentence: what it is and who it’s for].
[1-2 sentences: what problem it solves and how].

Details are in `business/INDEX.md`.

## Reading order at the start of every session

1. `about-me/INDEX.md` - who I am and how I think
2. `business/INDEX.md` - what we do (product, audience, economics)
3. `CLAUDE.md` (this file) - repo rules, tools, navigation
4. Task area: the relevant file from `business/`, `plans/<current plan>`,
   `mastery/<area>` or the feature folder in the code

Principle: layer 1 (about me) comes before layer 2 (business) for a reason.
First, **who** is thinking, then **about what**.

## Repository structure

[NAME]/
├── CLAUDE.md            ← this file, navigation
├── about-me/            ← digital projection of you (how you think, what you value)
│   └── INDEX.md
├── business/            ← the business’s second brain
│   ├── INDEX.md
│   ├── audience/        ← customer profile
│   ├── products/        ← products, prices
│   ├── goals/           ← goals, metrics
│   └── economics/       ← unit economics, revenue
├── plans/               ← technical plans (one plan = one feature)
├── retrospectives/      ← reflections after each session
└── (project code)

### Where to find things

| What you need | Where to look |
|---|---|
| Why we’re building the project, and for whom | `business/INDEX.md` |
| Target customer, pains, desires | `business/audience/` |
| Product, plans, prices | `business/products/` |
| Goals and metrics | `business/goals/` |
| Economics | `business/economics/` |
| Technical plans | `plans/` |

## Tools

[INSERT TOOLS - for example: Next.js 14, TypeScript, Tailwind CSS, Prisma + PostgreSQL].

## Repo rules

1. Never hardcode dynamic data (prices, dates, figures) -
   get everything from files in `business/` and the LIVE marker.
2. Don’t publish without my explicit command.
3. Before `git push`, run `npm run build` and check that it
   builds without errors or warnings.
4. Add files by name with `git add`. Never use `git add .` or `git add -A`.
5. Don’t read `.env` in full. To check a variable, use
   `grep "^VAR=" .env`.

## Big features = a plan in `plans/`

Any task lasting more than an hour must be written up as a plan in the `plans/` folder:
1. Filename: `YYYY-MM-DD-feature-name.md`.
2. Divide the plan into phases. Mark each phase `[ ]` or `[x]`.
3. At the end of the plan, add a summary: whether it was fully implemented and what remains.

## End-of-feature cycle

After each feature is complete, go through these 5 steps:
1. Find errors → prove them with an example → fix them.
2. What was missed (edge cases, input validation, error handling).
3. Is this a real problem in our project? Check `business/` and `plans/`.
4. Take a fresh look: reread the diff as if you’re seeing it for the first time.
5. Security review. Especially: personal data and third-party materials.

## End-of-session reflection

In `retrospectives/YYYY-MM-DD_short-name.md`, record:
1. What the task was.
2. How it was solved.
3. Whether it was solved - yes / no / partially.
4. What could have been done better.
5. What was learned about the user or project.

## Language

Always respond in the user’s preferred language. Use hyphens only, not em dashes.

Pour que Claude complète automatiquement ce modèle pour votre projet, donnez-lui ce prompt. Il lira le contexte et remplira les champs entre crochets :

Create a CLAUDE.md file at the project root using this template:

[INSERT THE ENTIRE TEMPLATE FROM ABOVE]

Proceed as follows:

Read about-me/INDEX.md and business/INDEX.md to understand the project context and me as the author.

Fill in all the square-bracketed fields in the template based on what you find in those folders.

If some information is missing, ask me clarifying questions one at a time, with 3-4 answer options.

Vise moins de 200 lignes pour CLAUDE.md. Au-delà, examine les répétitions et déplace les procédures détaillées vers des fichiers liés. Préserve les règles essentielles de planification, réflexion et dépôt, puis teste-les sur des tâches représentatives.

Show me the final file and ask what should be revised.

Always respond in the user’s preferred language.

Si vous n’avez pas encore de dossiers about-me/ et business/, ce n’est pas grave. Claude vous posera des questions de clarification et préparera un CLAUDE.md minimal à partir des éléments disponibles. Vous pourrez créer les dossiers plus tard, une fois que vous saurez quoi y mettre.

Quelles 6 règles font de CLAUDE.md un document vivant ?#

Règle 1. Limitez-le à moins de 200 lignes

Anthropic le dit succinctement dans sa documentation officielle :

Un CLAUDE.md long se retourne contre lui-même de deux façons. D’abord, il consomme des tokens. Un fichier de 800 lignes d’instructions est chargé dans chaque fenêtre et utilise plusieurs milliers de tokens de votre budget à chaque session. Avec un abonnement Pro soumis à une limite quotidienne, cela réduit nettement le nombre de sessions disponibles. Ensuite, le modèle commence à ignorer les règles.

La documentation conseille de viser moins de 200 lignes pour réduire le contexte et améliorer le respect des consignes. Elle n’établit pas d’échec net à la ligne 201. Examinez pertinence, contradictions, volume chargé et résultats réels avant de déplacer des éléments.

Règle 2. Terminez chaque session par une réflexion

Écrivez dans CLAUDE.md : « À la fin de chaque session, note ce que tu as fait et appris dans retrospectives/YYYY-MM-DD_*.md. » Une fois cette ligne ajoutée, Claude termine de lui-même chaque session par une réflexion ; vous n’avez plus besoin de le lui demander.

Pourquoi réfléchir :

• Deux semaines plus tard, vous pouvez ouvrir une ancienne rétrospective et vous rappeler pourquoi vous avez choisi cette voie.
• Quand vous revenez au projet un mois plus tard, vous disposez d’une carte toute prête des décisions récentes.
• Si vous travaillez en équipe, un partenaire peut lire la rétrospective et comprendre l’état actuel en 2 minutes, sans appel.

Règle 3. Faites un commit après chaque tâche terminée

Dans mon CLAUDE.md, il est écrit : « Après chaque tâche terminée, crée un commit git avec un message explicite. » Claude commence alors de lui-même à diviser le travail en commits atomiques.

Cela vous apporte deux choses. D’abord, si quelque chose casse, vous pouvez annuler une opération, et non « tout ce que j’ai fait aujourd’hui ». Ensuite, l’historique des commits devient un journal de travail qui montre ce qui a changé et dans quel ordre.

Règle 4. Consultez toujours le dossier business/

Pour toute tâche liée aux clients, aux produits ou aux textes, l’agent doit d’abord ouvrir business/INDEX.md et le fichier pertinent indiqué dans cet index. Mon CLAUDE.md précise explicitement : « Pour travailler sur l’interface ou les textes, consulte d’abord business/audience/avatar.md et business/assets/brand-guidelines.md. »

Sans cette règle, Claude rédige des textes dans « le style général d’un site de qualité ». Avec elle, les textes correspondent à votre style et à votre clientèle, sans employer vos mots interdits.

Règle 5. Ajoutez une règle après chaque erreur de l’agent

C’est la règle principale qui garde CLAUDE.md vivant.

Voici des exemples tirés de mon CLAUDE.md, ajoutés après des erreurs précises :

• « Ne commite jamais le travail en cours de quelqu’un d’autre avec git add . : indexe les fichiers par leur nom. »
• « Avant d’envoyer vers main, vérifie git log origin/main..main --oneline : si la sortie n’est pas vide, n’envoie rien. »
• « N’invente pas de valeurs : récupère-les dans .env ou dans le code. En particulier, les URL, les noms d’utilisateur et les tokens. »

Chacune de ces lignes est la trace d’un incident précis. Un jour, un agent a commité la branche inachevée d’un partenaire. Une autre fois, j’ai inclus les commits non poussés de quelqu’un d’autre. Une fois encore, un agent a inventé une URL qui n’existe pas. Chaque erreur devient une règle, et la même blessure qu’on s’inflige soi-même ne se reproduit pas.

Règle 6. Placez la sécurité dans .claude/settings.json, pas dans CLAUDE.md

Dans CLAUDE.md, vous pouvez écrire « ne touche pas à .env », mais cela reste une demande ; Claude peut la violer, puisque CLAUDE.md est chargé comme un message utilisateur, et non comme une loi. Pour une sécurité critique, utilisez .claude/settings.json, où vous pouvez bloquer strictement certaines commandes.

La liste de blocage que j’ajoute à chaque nouveau projet :

• rm -rf (suppression récursive de fichiers quelconques).
• Lecture intégrale de .env (Read .env).
• export et curl dans une même commande (un schéma de fuite de secrets vers l’extérieur).
• git push --force sans approbation explicite.

Retrouvez d’autres guides sur Ailoot.

Quelle est la structure de CLAUDE.md dans une entreprise active (anatomie d’un fichier de 280 lignes) ?#

La plupart des exemples de CLAUDE.md en ligne sont des modèles techniques destinés aux développeurs : « Utilise TypeScript », « N’écris pas de tests de plus de 50 lignes ». Pour un entrepreneur, ce type de CLAUDE.md est inutile : il ne couvre pas l’activité commerciale.

Voici la structure de mon CLAUDE.md de travail. J’ai retiré les règles et chemins précis, car ils reflètent mes opérations internes. Mais la structure et la logique des sections peuvent s’appliquer à n’importe quel projet : adaptez-les à votre situation et vous obtiendrez un fichier opérationnel.

1. Brève description du projet (15 lignes). Ce que nous faisons, à qui nous nous adressons et quels produits nous proposons. Pas un résumé du site marketing, mais une synthèse destinée à l’agent pour qu’il comprenne « où nous allons ».

2. À propos de moi (10 lignes). Un renvoi au dossier about-me/ - une projection numérique de ma façon de penser. Ton, valeurs, principes, mots interdits. Quand Claude rédige un texte « en mon nom », il consulte d’abord ce dossier pour que la voix corresponde.

3. Structure du dépôt (20 lignes). Une arborescence commentée : emplacement du code, du contexte métier, des plans et des rétrospectives. Sans cette carte, Claude cherche les fichiers à l’aveugle à chaque fois.

4. Tableau « où trouver les éléments » (25 lignes). Routage de la « question → fichier ». Par exemple, pour une agence immobilière, on pourrait indiquer : « besoin des conditions de prêt immobilier → business/products/mortgage.md » ou « besoin du ton des publications → business/assets/voice.md ». Remplacez ces exemples par vos propres fichiers. Ce tableau est le cœur de CLAUDE.md. Sans lui, l’agent devine quel fichier contient la réponse. Avec lui, il va directement à la source.

5. Principes clés du projet (40 lignes, 10-15 éléments). Cette section se constitue lentement et demande le plus d’efforts. Chaque élément est la trace d’une erreur précise. Pour une boutique en ligne, par exemple, les règles pourraient être : « ne code jamais en dur les prix et délais de livraison », « ne publie pas de produit sans instruction explicite » et « vérifie le style par rapport au glossaire de la marque avant de publier une fiche produit ». Cette section est la « constitution du projet ».

6. Planification opérationnelle (20 lignes). Un tableau de déclencheurs reliant « expression de l’utilisateur → action ». Par exemple : « Quand je dis “planifier la semaine”, ouvre ops/monthly.md et crée le fichier de la semaine. » Claude devient ainsi un assistant opérationnel qui comprend le contexte des commandes.

7. Outils (5 lignes). Technologies utilisées. Bref, sans remplissage.

8. Publication (15 lignes). Une procédure étape par étape pour publier des modifications en production : quelles commandes exécuter, dans quel ordre et quels éléments vérifier. Avant, je l’expliquais à chaque fois. Maintenant, Claude le sait.

9-12. Sécurité (35 lignes). Quatre sous-sections distinctes : règles d’utilisation de .env, accès à la base de données de production, commandes sûres pour les démonstrations (enregistrements d’écran, diffusions, captures d’écran, afin d’éviter d’exposer accidentellement des tokens) et règles de rotation des secrets.

13. Dossier plans/ (10 lignes). La norme pour les plans : nom de fichier, structure des phases et contenu du bloc récapitulatif.

14. Dossier retrospectives/ (5 lignes). La norme pour les rétrospectives : modèle, nom de fichier et contenu attendu.

15. Données de la base en direct (15 lignes). Une règle pour signaler les « données récentes » : lorsqu’un fichier précise que les chiffres doivent être à jour, l’agent les récupère à la source au lieu d’utiliser d’anciennes valeurs. Cela évite que Claude utilise les chiffres d’hier.

16. Langue (3 lignes). « Réponds toujours dans la langue préférée de l’utilisateur. Utilise uniquement des traits d’union, pas de tirets cadratins. »

Environ 280 lignes au total : cela dépasse la cible de concision sans invalider le fichier. Il restait utile dans cet exemple ; le conserver doit dépendre du contexte mesuré et de tests représentatifs. Les tableaux ne coûtent pas automatiquement moins de tokens que la prose.

À quoi sert la commande /init, et pourquoi ne suffit-elle pas ?#

Anthropic décrit ainsi la commande dans sa documentation :

Ce que /init fait bien :

• Il identifie les outils à partir de package.json, Cargo.toml et pyproject.toml.
• Il répertorie les commandes de compilation et de test.
• Il repère les conventions dans les fichiers existants (.eslintrc, .prettierrc).
• Il repère les règles Cursor existantes (.cursorrules, .cursor/rules/) et celles de Copilot, puis en intègre les éléments pertinents. Il récupère AGENTS.md en mode CLAUDE_CODE_NEW_INIT=1.

Ce que /init ne fera pas :

• Il ne saura pas qui sont vos clients.
• Il n’inclura pas vos mots interdits pour les textes.
• Il n’ajoutera pas de règles concernant les erreurs des agents (car il n’y en a pas encore eu).
• Il ne créera pas de tableau « où trouver les éléments » pour la structure de votre entreprise.

Le bon processus est donc le suivant :

1. Exécutez /init dans Claude Code

   Vous obtiendrez un CLAUDE.md de départ de 30-50 lignes avec les outils et les commandes. C’est le socle technique.

2. Ajoutez le modèle de cet article par-dessus

   Utilisez la section « CLAUDE.md minimal en 5 minutes ». Ajoutez les sections sur la navigation, le routage et les principes.

3. Remplissez les champs entre crochets

   Demandez à Claude : « lis mon projet et complète le modèle ». Si les dossiers business/ et about-me/ n’existent pas encore, Claude posera des questions de clarification.

4. Faites un test de résistance

   Dites à Claude : « Lis mon CLAUDE.md et trouve 10 ambiguïtés susceptibles de t’induire en erreur en tant qu’agent. » Vous obtiendrez une liste de corrections.

5. Ensuite, vivez avec le fichier

   Ajoutez une ligne après chaque erreur de l’agent. En un mois, vous aurez un CLAUDE.md évolutif, adapté à votre entreprise.

Prompt pour l’étape quatre :

I have a CLAUDE.md. Tomorrow I’ll be building a feature based on it.

Your task is to stress-test it. Find 10 reasons we could potentially fail:

where CLAUDE.md is ambiguous and you, as an agent, might misunderstand it

where there are gaps that would force you to make things up

where rules contradict one another

where I overestimate how much can be done in one day

where I underestimate things (this is even worse)

Don’t hold back. Criticize it harshly. I want to find these issues now, not in production.
At the end, give me a list of specific changes: what to change and how, so these problems don’t happen.

CLAUDE.md, AGENTS.md et MEMORY.md : qui lit quoi en 2026 ?#

La question qui trouble surtout les nouveaux utilisateurs est : Claude Code lit-il AGENTS.md ? Avant septembre 2026, la réponse était « non » : la documentation d’Anthropic recommandait de créer un CLAUDE.md qui importe AGENTS.md. Depuis la version 2.1.277 (sortie le 18 septembre 2026), Claude Code lit AGENTS.md lui-même, mais seulement s’il n’y a aucun CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md dans le dossier de travail ou dans un dossier parent.

Si le projet a un CLAUDE.md, Claude Code ne lit que celui-ci par défaut et ignore AGENTS.md. Vous pouvez changer ce comportement dans /config, sous Project instructions : par exemple, le paramètre claude-md-and-agents-md lui fait lire les deux fichiers. Une autre méthode fonctionne dans toutes les versions : ajouter un import dans CLAUDE.md :

@AGENTS.md

## Claude Code

Additional rules for Claude Code that other agents don’t need.

La syntaxe @filename importe un autre fichier. Claude le lit et le charge dans le contexte avec CLAUDE.md. L’import ne provoque pas une seconde lecture du fichier, même si Claude Code peut lire AGENTS.md de lui-même.

Quand avez-vous besoin de AGENTS.md ? Si vous travaillez en parallèle avec Claude Code et Codex CLI, Cursor ou Copilot, créez un AGENTS.md comme source unique de vérité, placez @AGENTS.md dans CLAUDE.md et ajoutez les règles propres à Claude par-dessus. Si vous n’avez aucune règle de ce type, vous n’avez pas besoin de créer CLAUDE.md : depuis la version 2.1.277, Claude Code lira AGENTS.md lui-même. Si vous travaillez uniquement dans Claude Code, vous n’avez pas besoin d’AGENTS.md ; utilisez un seul CLAUDE.md. Pour toutes les options étape par étape, consultez le guide d’utilisation conjointe de AGENTS.md et CLAUDE.md dans un projet.

Qu’est-ce que MEMORY.md ? Depuis une mise à jour récente, Claude Code conserve automatiquement des notes à votre sujet dans ~/.claude/projects/<project-name>/memory/MEMORY.md. Elles portent notamment sur vos habitudes de conversation (« l’utilisateur préfère les réponses courtes »), des expressions récurrentes (« a interdit les emoji dans le code ») et des observations comportementales (« travaille sur macOS, utilise zsh »).

C’est un système de mémoire distinct, pas CLAUDE.md. Vous ne le rédigez pas à la main ; Claude le fait à partir de vos conversations. Si MEMORY.md contient quelque chose qui devrait devenir une règle, déplacez-le dans CLAUDE.md. S’il contient quelque chose d’inutile ou d’inexact, vous pouvez le supprimer manuellement : c’est un fichier texte.

Quelle taille utile pour CLAUDE.md, et comment revoir un fichier long ?#

Dans chaque fenêtre Claude Code, plusieurs couches sont chargées dans le contexte : le prompt système d’Anthropic (estimé à des dizaines de milliers de tokens), votre CLAUDE.md, les fichiers importés avec @, MEMORY.md, l’historique de la conversation en cours et le contenu des fichiers ouverts par Claude. Tout cela doit tenir dans le contexte du modèle (200K tokens pour Sonnet, 1M pour Opus).

Plus CLAUDE.md grossit, moins il reste de place pour le travail en cours. Un fichier de 1 000 lignes représente environ 8 000 tokens, répétés à chaque session. Avec un abonnement Pro (selon mon expérience, environ 10-12 prompts « lourds » par jour), cela réduit votre capacité d’un quart.

Le coût n’est qu’un sujet. Les consignes longues, sans pertinence ou contradictoires peuvent moins bien être suivies ; aucun nombre universel de règles fiables n’existe. Testez des tâches représentatives sollicitant les règles critiques, relevez les échecs et comparez après une modification ciblée.

Voici donc une règle pratique pour la taille :

• 80-120 lignes : départ commode pour une carte concise, sans score de respect garanti.
• 150-200 lignes : invitation à revoir la pertinence et déplacer les procédures détaillées vers des fichiers liés.
• 200-300 lignes : inspectez tokens, répétitions et résultats ; l’exemple métier de 280 lignes peut encore convenir.
• 400+ lignes : forte raison de revoir le fichier, sans preuve d’inutilisabilité. Gardez les contraintes essentielles et ne déplacez le détail qu’après vérification des liens et règles.

Le nombre de lignes seul ne prouve ni succès ni échec. Après modification, répétez les mêmes tâches représentatives et vérifiez les règles importantes plutôt qu’inventer un pourcentage de conformité.

Anthropic propose un test direct dans sa documentation :

Appliquez ce test à chaque ligne. Si la réponse est « il s’en sortirait quand même », supprimez-la. CLAUDE.md n’est pas destiné à la documentation, à l’historique des décisions ni à la philosophie. Il ne sert qu’à consigner les règles dont l’agent a besoin pour éviter les erreurs.

Quelles 7 erreurs rendent CLAUDE.md inutile ?#

Erreur 1. « Sois un bon ingénieur »

C’est l’erreur la plus courante. Les gens écrivent des souhaits généraux dans CLAUDE.md : « écris du code propre », « applique les bonnes pratiques », « pense comme un ingénieur senior ».

Ces mots ne veulent rien dire. Claude écrit déjà du « code propre » au sens général. Ces lignes occupent du contexte sans influencer aucune décision.

Remplacez « écris du code propre » par « utilise une indentation de 2 espaces », « n’utilise pas any en TypeScript » ou « les fonctions ne doivent pas dépasser 30 lignes ». C’est précis et vérifiable.

Erreur 2. Répéter ce que Claude sait déjà

Des descriptions de conventions linguistiques standard (« en JavaScript, les fonctions sont des objets de première classe », « TypeScript dispose d’un typage statique »). Des explications sur le fonctionnement de npm, git ou docker.

Claude a appris tout cela pendant son entraînement. Le répéter dans CLAUDE.md n’apporte rien ; cela réduit seulement le contexte disponible.

Erreur 3. Instructions détaillées, étape par étape, dans CLAUDE.md

De longues instructions sur « comment déployer le projet », « comment rédiger une migration de base de données » ou « comment créer un nouveau composant ». Des dizaines de lignes étape par étape.

Ce n’est pas l’endroit pour de longues instructions étape par étape. CLAUDE.md sert à énoncer des règles en une ligne. Placez les instructions longues dans skills/ (un mécanisme distinct de Claude Code, chargé à la demande) ou dans docs/. Dans CLAUDE.md, ajoutez un renvoi d’une ligne : « Pour créer une migration, ouvre docs/migrations.md. »

Erreur 4. Règles déjà vérifiées par un analyseur de code automatique

« Utilise des points-virgules », « ne laisse pas d’imports inutilisés », « n’utilise pas var ». ESLint, Prettier et Biome détectent tout cela : ce sont des linters (outils automatiques de vérification du code).

Un linter est déterministe : il s’exécute, détecte une erreur et la corrige. Une règle de CLAUDE.md est probabiliste ; l’agent peut l’oublier. Il n’est pas nécessaire de la répéter : il est plus simple de configurer le linter.

Erreur 5. Des secrets dans CLAUDE.md

J’ai vu des mots de passe de comptes de test, des tokens d’API de bac à sable et des liens vers des panneaux d’administration authentifiés. Tout cela se trouvait dans un fichier commité dans git et chargé dans le contexte du modèle d’Anthropic.

Jamais. Les secrets doivent se trouver dans .env, qui est dans .gitignore. Tout au plus, CLAUDE.md peut indiquer : « Ne lis pas .env en entier ; utilise grep pour une variable précise. »

Erreur 6. Un fourre-tout de plus de 500 lignes, jamais nettoyé depuis six mois

CLAUDE.md a grossi, répète la moitié de docs/, se contredit à plusieurs endroits et plus personne ne se souvient de son contenu. L’agent commence à en ignorer la plupart. L’équipe se plaint que « Claude ne suit pas les instructions » et ajoute encore des règles, ce qui empire les choses.

Signes qu’un CLAUDE.md est laissé à l’abandon : plus de 300 lignes, règles répétées dans différentes sections, liens obsolètes vers des fichiers qui n’existent plus et notes « historiques » comme « en 2024, nous avons décidé de procéder ainsi, puis nous avons changé d’avis ».

La solution : toutes les deux semaines, demandez à Claude de le passer en revue à l’aide du test d’Anthropic : « Si cette ligne était supprimée, l’agent ferait-il une erreur ? » Supprimez tout ce qui reçoit la réponse « non ».

Erreur 7. Créer CLAUDE.md puis l’oublier

C’est l’inverse de l’erreur précédente. Le fichier a été préparé une fois, il y a deux mois, et n’a pas été retouché depuis. Entre-temps, les outils ont changé, de nouveaux dossiers ont été ajoutés et de nouvelles erreurs d’agents sont apparues. CLAUDE.md n’en sait rien, car personne ne l’a mis à jour.

Un signe révélateur : vous répétez la même instruction à chaque session. « Ne fais pas X », « ne touche pas à Y », « souviens-toi de Z ». Si vous l’avez répétée plus de deux fois, cette règle appartient à CLAUDE.md, pas à votre mémoire.

Comment rendre CLAUDE.md capable d’apprendre, grâce à une règle de mise à jour en fin de session ?#

Mon CLAUDE.md comporte une courte section :

## Self-learning

At the end of every session, check:
- Have I learned anything new about the user or how to work with them?
- Did I break any rule that should now be recorded?

If so, create or update a file in `about-me/feedback/` in this format:
Rule (one-line rule) → Why (why it was added)
→ How to apply (when it applies).

I don’t write the rules by hand - I say, “not like that, because this is how,”
and you put it into a file.

Une fois cette section ajoutée à CLAUDE.md, Claude a commencé à demander à la fin de chaque session : « Y avait-il quelque chose de nouveau qui méritait d’être consigné ? » Si c’était le cas, il proposait un brouillon de règle, je le précisais et un fichier était créé.

Après deux mois de travail de cette manière, j’ai plus de deux douzaines de fichiers dans about-me/feedback/ - des règles tirées d’erreurs précises. Chaque fichier est une page au format Règle → Pourquoi → Comment. Le dossier est devenu une « seconde mémoire » qui consigne mes préférences et mes interdits personnels.

Chaque erreur n’est pas répétée, car elle devient une règle, et les règles s’accumulent et se renforcent mutuellement. Au bout de six mois, Claude connaît mieux mon projet que je ne m’en souviens après une pause d’un mois.

Comment ajouter à CLAUDE.md des règles juridiques, marketing et opérationnelles ?#

Pour la plupart des équipes, CLAUDE.md est un document purement technique : outils, commandes de compilation, conventions de code. C’est utile, mais cela ne représente qu’un tiers de sa valeur.

Quand un entrepreneur tient à jour CLAUDE.md, il est judicieux d’y ajouter des sections métier. Trois sont particulièrement importantes :

Règles juridiques (pour les marchés réglementés)

Si vous publiez des textes dans un secteur réglementé (finance, médecine, publicité pour des médicaments, produits pour enfants), les mots interdits ont une portée juridique et doivent figurer explicitement dans CLAUDE.md. Pas dans la tête de quelqu’un, ni sur une capture d’écran de l’éditeur : dans un fichier que l’agent voit à chaque session.

Exemple pour un projet fintech sans licence bancaire :

Note éditoriale : ce qui suit montre le format d’une règle interne pour un projet précis. Cela ne constitue pas une autorisation générale d’utiliser les termes indiqués : la recevabilité d’une déclaration dépend du droit applicable et du statut de l’entreprise.

🚨 CRITIQUE - les formulations financières sont interdites. Dans les contenus destinés aux clients, n’utilisez pas : « dépôt », « rendement garanti » ou « produit d’investissement ». Utilisez : « compte d’épargne », « rendement prévu » et « produit à taux variable ». La raison tient aux exigences légales applicables à la publicité des services financiers pour ce projet.

Ce bloc dans CLAUDE.md fait une chose simple : chaque fois que vous demandez à Claude de rédiger un texte destiné aux clients, l’agent le vérifie au regard de ces interdictions. Sans cette règle, les mots interdits réapparaissent dans une campagne sur trois. Avec elle, vous n’avez plus à vous en soucier.

La même approche fonctionne pour :

• Les projets médicaux (aucune affirmation selon laquelle un produit « traite » ou « guérit »).
• La publicité pour des médicaments (pas d’affirmations du type « le plus efficace » ; avertissements obligatoires).
• Tout secteur réglementé soumis à ses propres règles publicitaires.

Style marketing et format des textes

Si vous publiez régulièrement des textes (réseaux sociaux, lettres d’information, sites web), il est utile d’en documenter le format dans un paragraphe de CLAUDE.md. Voici un exemple de ce qu’une personnalité des réseaux sociaux ou une agence qui gère une messagerie pourrait écrire :

Pour rédiger des publications sur le canal, consulte style/posts.md. Utilise les marqueurs de mise en forme autorisés par le canal et évite les caractères spéciaux « dangereux ». Termine par un CTA comportant une balise UTM selon cette convention : utm_source=<channel>&utm_medium=<type>&utm_campaign=<slug>.

Claude rédigeait auparavant des publications dans « le style général d’un site marketing ». Maintenant, il suit votre format, utilise vos UTM et ne laisse pas deviner que le texte a été écrit par une IA.

Habitudes opérationnelles

Des tableaux de déclencheurs. Lorsque vous prononcez une expression précise, l’agent sait quels fichiers ouvrir et quelles actions effectuer. Voici un exemple pour une équipe qui planifie à la semaine :

« Planifier la semaine » → ouvrir ops/monthly.md, créer YYYY-WNN.md dans le même dossier et déplacer les tâches de ops/backlog.md sous les jours correspondants. « Que contient le backlog ? » → lire ops/backlog.md et l’afficher sous forme de liste. « Clore la semaine » → remplir la section « Résumé de la semaine » du fichier de la semaine en cours.

Avec de tels tableaux, Claude passe d’un « assistant qui écrit du code » à un « opérateur » qui connaît la routine de votre entreprise. Chaque lundi, je dis « planifions la semaine », et Claude ouvre les bons fichiers, lit les objectifs mensuels et propose comment les répartir.

Comment vérifier votre CLAUDE.md à l’aide d’une liste de contrôle en 12 points en 5 minutes ?#

1. Taille. Est-il concis, avec environ 200 lignes comme cible de revue plutôt que seuil de validation ?
2. Nom. S’appelle-t-il exactement CLAUDE.md, avec des majuscules, et non claude.md ?
3. Emplacement. Se trouve-t-il à la racine du projet ou dans ./.claude/CLAUDE.md ?
4. Description du projet. Les 5 premières lignes expliquent-elles clairement ce qu’est le projet et à qui il s’adresse ?
5. Outils. Les technologies sont-elles énumérées explicitement et sans remplissage ?
6. Structure. Y a-t-il un schéma du dépôt accompagné d’explications ?
7. Routage. Y a-t-il un tableau « question → fichier » indiquant où trouver les réponses ?
8. Principes. Y a-t-il une section contenant des règles qui commencent par « jamais » et « toujours » ?
9. Précision. Chaque règle est-elle vérifiable ? (« Utilise 2 espaces », et non « écris avec élégance ».)
10. Mise à jour automatique. Y a-t-il une règle demandant de « vérifier en fin de session ce qu’il faut ajouter » ?
11. Rétrospective. Y a-t-il une règle demandant de « noter le résumé de la session dans retrospectives/ » ?
12. Sécurité. Les interdictions critiques (.env, rm -rf) figurent-elles également dans .claude/settings.json ?

Si vous avez plus de cinq réponses « non », ouvrez Claude et donnez-lui ce prompt :

Read my CLAUDE.md and compare it with the checklist below. For each item, say: yes / no / partly, and what specifically to fix.

Checklist:

Assez compact pour la tâche ; revoir vers 200 lignes sans plafond strict

Project description in the first 5 lines

Tools listed explicitly

Repository structure diagram included

“Question → file” table included

Principles section with rules included

Every rule is specific and verifiable

“Update at the end of the session” rule included

“Reflect at the end of the session” rule included

Critical prohibitions included in .claude/settings.json

No duplicates of the same rule in different sections

No dangling links to files that no longer exist

After the audit, give me a list of specific changes that will make the file living.

Que faut-il utiliser après CLAUDE.md : Plan Mode, Skills ou sous-agents ?#

CLAUDE.md est le fondement. Une fois qu’il fonctionne, vous pouvez ajouter trois mécanismes de Claude Code qui se renforcent mutuellement.

Plan Mode. Un mode dans lequel Claude commence par créer un plan de modifications, attend votre approbation et ne commence à travailler qu’ensuite. Activez-le avec Shift+Tab ou la commande /plan. Il répond au principal point de friction du vibe coding : « J’ai demandé à Claude de corriger une chose, et il a réécrit la moitié du projet. » Cela ne se produira pas en Plan Mode : vous voyez le plan avant que l’agent ne touche à des fichiers.

Skills. Des fichiers .md séparés dans le dossier .claude/skills/, qui contiennent des connaissances propres à un type de tâche. Par exemple, une skill « rédiger une migration de base de données » contient une procédure précise, un modèle et des exemples. Ces connaissances ne figurent pas dans CLAUDE.md parce qu’elles sont trop détaillées. Mais quand Claude rencontre une tâche comme « rédiger une migration », il charge la skill correspondante et la suit.

Sous-agents. Quand une tâche nécessite beaucoup de contexte (par exemple, l’examen d’une grande fonctionnalité), Claude peut lancer un sous-agent distinct dans un contexte vierge qui lui est propre. Le sous-agent effectue le travail et renvoie le résultat sans encombrer le contexte de votre conversation principale.

Ces trois mécanismes utilisent CLAUDE.md comme point d’entrée : ils le lisent au début de leur travail pour comprendre le contexte du projet. C’est pourquoi ces fonctionnalités fonctionnent aussi mal sans un CLAUDE.md évolutif. D’abord le fondement, puis les couches supplémentaires.

Prochaine étape. Créez un fichier CLAUDE.md à la racine du projet, copiez le modèle au début de cet article et remplissez les champs entre crochets à l’aide du prompt d’assistance. Puis vivez avec ce fichier : transformez chaque erreur de l’agent en une nouvelle ligne. Au bout de deux ou trois semaines, CLAUDE.md cessera d’être « un document écrit puis oublié » et deviendra un fichier que Claude consulte réellement à chaque session.

Si vous voulez créer un cadre complet autour de CLAUDE.md - un dossier business/ pour un Second Brain, un dossier about-me/ pour une projection numérique de vous-même, des skills de base et un Plan Mode configuré - suivez les étapes et les exemples de cet article. Guides Ailoot.

Continuer avec Ailoot.