Quoi mettre dans ton CLAUDE.md (et surtout quoi NE PAS mettre)

Dans mon article sur comment je structure mes projets, je parle des 4 piliers : CLAUDE.md, Memory Bank, Rules, Commands.

Le CLAUDE.md, c'est le plus important. Et c'est celui qu'on remplit le plus mal.

Pourquoi ? Parce qu'on a tendance à y mettre TOUT. Et c'est exactement ce qu'il ne faut pas faire.

Pourquoi moins = plus

Le CLAUDE.md est lu à chaque message. Chaque ligne que tu y mets consomme du contexte. À chaque message.

Si ton CLAUDE.md fait 500 lignes, tu perds 500 lignes de contexte à chaque interaction. Sur un projet complexe, c'est catastrophique.

Les études montrent que les LLMs suivent bien environ 150-200 instructions. Au-delà, la qualité se dégrade. Et le system prompt de Claude Code utilise déjà ~50 instructions.

Ma règle : 50-80 lignes max.

Tout ce qui dépasse → ailleurs.

La structure WHAT / WHY / HOW

Un bon CLAUDE.md répond à 3 questions :

WHAT — C'est quoi ce projet ?

# mon-projet
Stack: Next.js 15, Supabase, Tailwind, shadcn/ui

WHY — Quel est le contexte ?

Bot Telegram multi-assistants pour gérer mon second cerveau Obsidian.

HOW — Comment on travaille dessus ?

Commandes: /start, /plan, /implement
Docs: docs/memory-bank/

C'est tout. Le reste va ailleurs.

Ce qui doit RESTER dans CLAUDE.md

Ce qui doit PARTIR ailleurs

NEVER > ALWAYS

Une liste de ce qu'il ne faut PAS faire est plus précieuse qu'une liste de ce qu'il faut faire.

Pourquoi ? Parce que Claude peut proposer des solutions "génériques" qui ne marchent pas dans ton contexte. Lui dire ce qu'il ne doit pas faire le stoppe avant qu'il parte dans la mauvaise direction.

## Ne jamais faire

- Ne pas utiliser `any` en TypeScript
- Ne pas créer de fichiers sans lire l'existant d'abord
- Ne pas commiter les secrets (.env)
- Ne pas modifier la DB sans migration Prisma
- Ne pas ajouter de dépendances sans demander

CLAUDE.md vs .claude/rules/

La confusion est fréquente. Voici la différence :

Les rules peuvent être path-scoped :

---
paths: "**/*.tsx"
---
# Règles React
- Utiliser les Server Components par défaut
- Client Components seulement si interactivité

Cette règle ne sera chargée QUE quand tu travailles sur des fichiers .tsx. Économie de contexte.

Exemple de CLAUDE.md minimal

# mon-saas

## Stack
Next.js 15 (App Router), Supabase, Tailwind, shadcn/ui

## Contexte
SaaS de facturation pour freelances. MVP en cours.

## Commandes
- /start : charger le contexte
- /plan : planifier une feature
- /implement : coder tâche par tâche

## Docs
- Architecture : docs/memory-bank/structure.md
- Conventions : .claude/rules/

## Ne jamais faire
- any en TypeScript
- Modifier la DB sans migration
- Commiter .env

32 lignes. C'est suffisant.

Red flags : ton CLAUDE.md est trop long si...

• ☐ Tu as des exemples de code dedans
• ☐ Tu expliques comment fonctionne chaque feature
• ☐ Tu as plus de 10 règles
• ☐ Tu répètes des infos qui sont déjà dans le code
• ☐ Tu as des workflows multi-étapes

Si tu coches une de ces cases, il est temps de refactorer.

Le prompt pour refactorer ton CLAUDE.md

Tu veux nettoyer ton CLAUDE.md mais tu sais pas par où commencer ?

J'ai créé un prompt qui :

1. Analyse ton CLAUDE.md actuel
2. Identifie ce qui doit partir ailleurs
3. Te propose une version refactorisée (50-80 lignes)
4. T'explique où déplacer le reste

[→ Télécharger le prompt gratuitement]

Living document : comment je le maintiens

Le CLAUDE.md n'est pas un fichier que tu écris une fois et que tu oublies. Il évolue avec ton projet.

Dans mon workflow, j'utilise 2 commandes :

• /pick-feature : Initialise le CLAUDE.md au début du projet
• /doc : Propose des nouvelles rules basées sur le code que je viens d'écrire

À chaque feature terminée, /doc analyse le code et me demande :

• "Ce pattern est utilisé 2+ fois, tu veux en faire une rule ?"
• "Cette convention n'est pas documentée, on l'ajoute ?"

C'est ce que j'appelle le living document. Le CLAUDE.md reste à jour sans effort manuel.

→ J'explique tout ce workflow dans Comment je structure mes projets

La suite

Le CLAUDE.md + les Rules, c'est la base. Ça configure ton environnement.

Mais pour vraiment exploiter Claude Code, il te faut aussi des outils actifs : des raccourcis (commandes), des superpouvoirs (MCP), et la capacité de déléguer (agents).

Dans le prochain article, je te présente les 3 boosters qui vont transformer ton workflow.

→ Lire : MCP, agents, commandes : les 3 boosters de ton IA

Et si tu as de la documentation lourde (500+ lignes d'API reference), j'explique comment la charger en lazy loading avec les Skills.

→ Lire : Les Skills : ce qu'ils apportent vraiment