02 - CLAUDE.md : la memoire de ton projet#

Le fichier qui evite de re-expliquer ton projet a chaque nouvelle session.

Temps de lecture : 14 min | Niveau : Debutant

Ce que tu sauras faire apres#

• Expliquer ce qu'est CLAUDE.md et pourquoi il est charge a chaque session.
• Choisir le bon emplacement selon la portee voulue (toi, l'equipe, l'organisation).
• Trier ce qui merite d'etre dans le fichier et ce qui n'y a rien a faire.
• Decouper un gros fichier avec des imports @ et des regles .claude/rules/.
• Ecrire un CLAUDE.md complet pour un projet Python + dbt + BigQuery.

1. Le probleme que ca resout#

Chaque session Claude Code demarre avec une fenetre de contexte vide. Claude ne se souvient de rien de la session precedente.

Sans CLAUDE.md, tu recommences a chaque fois :

"On est sur BigQuery, pas Snowflake. Les tests se lancent avec make test, pas pytest. Ne touche jamais aux fichiers de models/legacy/."

Avec CLAUDE.md, tu l'ecris une fois, et Claude le lit au debut de chaque conversation.

Il existe deux mecanismes de memoire, complementaires :

Important. Claude traite ces fichiers comme du contexte, pas comme une configuration appliquee de force. Pour vraiment bloquer une action quoi qu'il arrive, il faut un hook PreToolUse (fichier 05) ou une regle de permission (fichier 03).

2. Ou mettre le fichier : la hierarchie#

Le tableau suit l'ordre de chargement, du plus large au plus precis. Une instruction projet arrive donc apres une instruction utilisateur dans le contexte de Claude.

Sur Windows, ~/.claude veut dire %USERPROFILE%\.claude.

Comment les fichiers se chargent#

Claude Code charge CLAUDE.md et CLAUDE.local.md depuis ton dossier courant et tous les dossiers au-dessus. Si tu lances Claude Code dans foo/bar/, il charge foo/CLAUDE.md puis foo/bar/CLAUDE.md.

Trois regles a retenir :

1. Les fichiers trouves sont concatenes, pas remplaces.
2. L'ordre va de la racine du disque vers ton dossier de travail. Les instructions les plus proches de toi sont lues en dernier.
3. Dans un meme dossier, CLAUDE.local.md est ajoute apres CLAUDE.md.

Les CLAUDE.md des sous-dossiers ne sont pas charges au demarrage : ils entrent en contexte quand Claude lit un fichier de ce sous-dossier.

Si ton depot a deja un AGENTS.md. Claude Code sait le lire. Par defaut, il lit AGENTS.md seulement si aucun CLAUDE.md ni CLAUDE.local.md n'existe dans ton dossier de travail ou au-dessus. Des que tu crees un CLAUDE.md, l'AGENTS.md n'est plus lu. Pour charger les deux, regle Project instructions sur claude-md-and-agents-md.

Verifier que ton fichier est bien charge#

/context

Regarde la liste sous Memory files. Si ton CLAUDE.md n'y est pas, Claude ne le voit pas. Pour ouvrir et editer les fichiers de memoire :

/memory

3. Quoi mettre, quoi ne pas mettre#

La regle mentale : "est-ce que supprimer cette ligne ferait faire une erreur a Claude ?" Si non, supprime-la.

Quand ajouter une ligne#

Ajoute une ligne quand :

• Claude fait la meme erreur pour la deuxieme fois.
• Une revue de code releve quelque chose que Claude aurait du savoir.
• Tu retapes la meme correction que la session precedente.
• Un nouveau collegue aurait besoin de la meme information.

La taille compte#

Vise moins de 200 lignes par fichier CLAUDE.md. Un fichier plus long consomme du contexte et fait baisser le respect des consignes. Un fichier trop long, c'est le piege classique : Claude ignore la moitie des regles parce que les importantes se perdent dans le bruit.

Si Claude ignore systematiquement une instruction, ajoute IMPORTANT sur cette ligne seulement. Si tu mets de l'emphase partout, plus rien ne ressort.

Etre specifique#

4. Decouper un gros fichier#

Les imports avec @#

Un CLAUDE.md peut importer d'autres fichiers avec la syntaxe @chemin/vers/fichier. Les fichiers importes sont charges au demarrage, en meme temps que le CLAUDE.md qui les reference.

Voir @README pour l'apercu du projet et @package.json pour les commandes npm.

# Instructions supplementaires
- workflow git @docs/git-instructions.md

Regles importantes :

• Les chemins relatifs sont resolus par rapport au fichier qui contient l'import, pas au dossier de travail.
• Un fichier importe peut lui-meme importer, jusqu'a 4 niveaux de profondeur.
• Les imports sont ignores dans les blocs de code et les code spans. Pour citer un chemin sans l'importer, entoure-le de backticks.
• Un import d'un fichier hors de ton dossier de travail declenche une boite de dialogue d'approbation la premiere fois. Si tu refuses, les imports restent desactives.

Les regles dans .claude/rules/#

Pour un gros projet, decoupe par sujet dans .claude/rules/. Chaque fichier .md couvre un theme, et la decouverte est recursive.

mon-projet/
├── .claude/
│   ├── CLAUDE.md           # Instructions principales
│   └── rules/
│       ├── style-python.md
│       ├── conventions-dbt.md
│       └── securite-donnees.md

Le gros avantage : une regle peut etre limitee a certains fichiers avec le champ paths en frontmatter YAML. Elle ne se charge que quand Claude travaille sur ces fichiers.

---
paths:
  - "models/**/*.sql"
  - "macros/**/*.sql"
---

# Regles SQL dbt

- Toujours utiliser `{{ ref('...') }}`, jamais un nom de table en dur.
- Les colonnes de date sont suffixees `_at` et stockees en TIMESTAMP UTC.
- Chaque modele `fct_` doit declarer un test `unique` et `not_null` sur sa cle primaire.

Deux precisions utiles :

• Une regle sans champ paths est chargee a chaque session, sans condition.
• Une regle avec paths se declenche quand Claude lit un fichier qui correspond au motif, pas a chaque appel d'outil. C'est ce qui fait economiser du contexte.

paths est le seul champ que Claude Code lit dans le frontmatter d'une regle. Tout autre champ est ignore sans erreur. Les regles personnelles vont dans ~/.claude/rules/ et s'appliquent a tous tes projets.

CLAUDE.md, regle ou skill ?#

5. La memoire automatique#

En plus de ce que tu ecris, Claude prend des notes tout seul. C'est actif par defaut.

Claude enregistre quatre types de notes, marques par un champ type :

• user : ton role, ton expertise, tes preferences de travail.
• feedback : les corrections que tu lui donnes, les approches que tu valides.
• project : le travail en cours, les echeances, les decisions non deductibles du code.
• reference : ou trouver l'information hors du projet (tracker, dashboard).

Claude ne note pas ce qu'il peut deduire du code, ni ce que ton CLAUDE.md dit deja.

Ou c'est stocke : ~/.claude/projects/<projet>/memory/, avec un index MEMORY.md et un fichier par sujet. Seules les 200 premieres lignes (ou 25 Ko) de MEMORY.md sont chargees au demarrage.

Pour inspecter ou desactiver :

/memory

Ou dans les reglages du projet :

{
  "autoMemoryEnabled": false
}

6. Exemple complet : projet Python + dbt + BigQuery#

Copie ce fichier a la racine de ton depot sous le nom CLAUDE.md, puis adapte les valeurs entre crochets.

# Projet : [NOM_DU_PROJET] - pipeline analytique

## Stack

- Python 3.11, gere avec `uv`
- dbt-bigquery 1.8
- Airflow 2.9 (DAGs dans `dags/`)
- Entrepot : BigQuery, projet GCP `[ID_PROJET_GCP]`

## Structure

- `dags/` : DAGs Airflow. Un fichier = un DAG.
- `dbt/models/staging/` : modeles `stg_`, un par table source, aucune jointure.
- `dbt/models/marts/` : modeles `dim_` et `fct_`, exposes au metier.
- `dbt/macros/` : une macro par fichier.
- `src/` : code Python d'extraction et de chargement.
- `tests/` : tests pytest. `tests/unit/` sans reseau, `tests/integration/` avec BigQuery.

## Commandes

- Installer : `uv sync`
- Tests unitaires : `make test-unit`
- Tests d'integration : `make test-integration` (necessite `GOOGLE_APPLICATION_CREDENTIALS`)
- Lint et format : `make lint` (ruff + sqlfluff)
- Compiler dbt : `cd dbt && dbt compile --target dev`
- Lancer un modele : `cd dbt && dbt build --select [NOM_MODELE] --target dev`

IMPORTANT : lance toujours `make lint` avant de proposer un commit.

## Conventions SQL

- CTE nommes en snake_case, un CTE par etape logique.
- Toujours `{{ ref('...') }}` ou `{{ source('...') }}`, jamais de table en dur.
- Colonnes de date : suffixe `_at`, type TIMESTAMP, toujours en UTC.
- Montants : suffixe `_ht` ou `_ttc`, jamais `montant` tout court.
- Chaque `fct_` declare `unique` et `not_null` sur sa cle primaire dans le `.yml`.

## Conventions Python

- Type hints obligatoires sur toute fonction publique.
- Pas de `print`, utiliser `logging` avec le logger du module.
- Les acces BigQuery passent par `src/clients/bigquery.py`, jamais de client instancie
  ailleurs.

## Donnees et securite

- Ne jamais ecrire de vraies valeurs de production dans un test ou un commentaire.
- `dbt/profiles.yml` et `.env` ne doivent jamais etre modifies.
- Le dataset `prod_analytics` est en lecture seule depuis cette machine.

## Git

- Branches : `feat/`, `fix/`, `chore/` suivi d'un tiret et d'un resume court.
- Messages de commit en francais, imperatif present.
- Ne jamais pousser directement sur `main`.

## Pieges connus

- `dbt run` sans `--target dev` vise la production. Toujours preciser `--target`.
- Les tests d'integration echouent si le dataset `dev_[TON_PRENOM]` n'existe pas.
- La source `raw.commandes` a un champ `montant` en STRING. Caster en NUMERIC dans staging.

Voir @docs/architecture.md pour le schema d'ensemble.

Ce fichier fait environ 60 lignes. C'est la bonne taille.

7. AVANT / APRES#

AVANT (un CLAUDE.md inutile)

# Mon projet

Ce projet est un pipeline de donnees. Il utilise Python, qui est un langage de
programmation tres populaire pour la data. Nous utilisons aussi dbt, un outil de
transformation. Merci d'ecrire du code propre et bien teste, en suivant les bonnes
pratiques du metier.

APRES (utile)

# Pipeline ventes

- Tests : `make test-unit` (pas `pytest` directement, le Makefile charge le .env)
- dbt : toujours `--target dev`, sinon tu vises la production
- La source `raw.commandes.montant` est en STRING : caster en NUMERIC dans staging
- Ne jamais modifier `dbt/profiles.yml`

Pourquoi c'est mieux ? La version APRES ne contient que des choses que Claude ne peut pas deviner en lisant le code. La version AVANT dit des evidences et gaspille du contexte.

Template pret a copier#

# [NOM_DU_PROJET]

## Commandes
- Installer : [COMMANDE_INSTALL]
- Tester : [COMMANDE_TEST]
- Lint : [COMMANDE_LINT]

## Conventions qui different du standard
- [REGLE_1]
- [REGLE_2]

## Interdits
- Ne jamais modifier [FICHIER_OU_DOSSIER]
- Ne jamais lancer [COMMANDE_DANGEREUSE]

## Pieges connus
- [PIEGE_1_ET_SA_PARADE]

A retenir#

• CLAUDE.md est charge au debut de chaque session : c'est du contexte, pas une contrainte.
• Quatre emplacements possibles : politique geree, utilisateur, projet, local.
• Vise moins de 200 lignes ; un fichier trop long fait ignorer les regles importantes.
• N'ecris que ce que Claude ne peut pas deduire du code.
• @chemin importe un autre fichier, jusqu'a 4 niveaux de profondeur.
• .claude/rules/ avec paths charge une regle seulement pour les fichiers concernes.
• /context verifie ce qui est charge, /memory ouvre et edite les fichiers.

Sources#

• Claude Code - How Claude remembers your project
• Claude Code - Best practices
• Claude Code - Settings files and precedence
• Claude Code - Commands
• Claude Code - Skills
• ChrisWiles/claude-code-showcase - un CLAUDE.md reel a la racine d'un projet entierement configure
• josix/awesome-claude-md - des CLAUDE.md de projets publics analyses un par un, ranges par type de projet dans scenarios/

Liens verifies le 26 septembre 2026.