Introduction

Chaque fois que vous ouvrez une nouvelle session Claude Code, l'agent démarre avec un état vierge — il n'a aucune mémoire des discussions de la veille, aucune connaissance du framework utilisé par votre projet, des conventions de nommage que vous suivez, ni des répertoires qui contiennent le code critique. Il s'agit d'une limitation inhérente aux modèles de langage, pas d'un bug.

Le fichier CLAUDE.md est le mécanisme officiel pour résoudre ce problème. Lorsque Claude Code démarre dans un répertoire, il lit automatiquement le fichier CLAUDE.md à la racine et utilise ce contenu comme contexte de fond pour toute la session. C'est ainsi que vous « enseignez » l'agent une fois et en bénéficiez indéfiniment.

Ce qu'est CLAUDE.md et comment il fonctionne

CLAUDE.md est un fichier markdown standard placé à la racine de votre projet (au même niveau que package.json, pyproject.toml, ou tout autre fichier de configuration que vous utilisez). Il n'y a aucune syntaxe spéciale, aucun schéma requis — vous écrivez en markdown libre.

Lorsque Claude Code exécute sa première commande dans une session, il lit ce fichier et charge son contenu dans la fenêtre de contexte dans le cadre d'un prompt système étendu. Cela signifie que tout ce que vous écrivez dans CLAUDE.md influence directement la façon dont l'agent interprète les requêtes, suggère du code et prend des décisions architecturales.

En plus du fichier racine, Claude Code lit également les fichiers CLAUDE.md dans les sous-répertoires lorsque vous travaillez dans ces répertoires. Cela est utile pour les monorepos — vous pouvez avoir un CLAUDE.md partagé à la racine et des fichiers CLAUDE.md séparés pour chaque package avec des instructions plus spécifiques.

Que faut-il écrire dans CLAUDE.md

Il n'y a pas de formule rigide, mais un CLAUDE.md efficace inclut généralement les groupes d'informations suivants.

Le premier groupe est une vue d'ensemble du projet : une brève description de ce que fait le projet, la stack technologique utilisée et les numéros de version importants. Le deuxième groupe est la structure des répertoires et les fichiers clés — pour que l'agent sache immédiatement où trouver la logique métier, la configuration et les tests. Le troisième groupe est celui des conventions et règles de code : conventions de nommage, style d'import, guides de style, et patterns à utiliser ou à éviter. Le quatrième groupe est celui des commandes couramment utilisées pour exécuter le serveur de développement, les tests, les builds et les déploiements.

Exemple de CLAUDE.md pour un vrai projet Next.js :

# Dự án: E-commerce Dashboard

## Stack
- Next.js 14 (App Router)
- TypeScript strict mode
- Prisma + PostgreSQL
- Tailwind CSS
- Zustand cho global state

## Cấu trúc thư mục
- `src/app/` — routes và layouts (App Router)
- `src/components/ui/` — primitive components (Button, Input...)
- `src/components/features/` — business components
- `src/lib/` — utilities và helpers
- `src/server/` — server actions và API logic
- `prisma/schema.prisma` — database schema

## Convention
- Component dùng named export, không dùng default export
- Server components là default, chỉ thêm "use client" khi cần
- Tên file component: PascalCase.tsx
- Tên file utility: camelCase.ts
- Không dùng `any` trong TypeScript

## Lệnh
- Dev: `npm run dev`
- Test: `npm run test`
- Type check: `npm run typecheck`
- Migration: `npx prisma migrate dev`

Cet exemple est concis mais suffisant pour que l'agent comprenne immédiatement l'architecture et évite de suggérer des choses inadaptées — comme utiliser des exports par défaut ou ajouter Redux à un projet qui utilise déjà Zustand.

Stratégie de maintenance de CLAUDE.md

Le fichier CLAUDE.md n'a de valeur que s'il reflète l'état réel du projet. Quelques habitudes aident à le maintenir à jour.

Premièrement, commit CLAUDE.md dans git dès le début et traitez-le comme faisant partie du codebase, pas comme un fichier personnel. Toute l'équipe en bénéficie lorsque l'agent comprend correctement le contexte du projet.

Deuxièmement, chaque fois que vous ajoutez une nouvelle technologie, modifiez l'architecture ou vous alignez sur une nouvelle convention d'équipe, mettez à jour CLAUDE.md dans la même pull request — ne remettez pas cela à plus tard. Une approche simple consiste à demander à Claude Code de le mettre à jour pour vous : après un changement majeur, demandez « Please update CLAUDE.md to reflect the changes just made » et vérifiez le résultat.

Troisièmement, gardez le fichier concis et bien structuré. Un fichier très long (plusieurs centaines de lignes) dilue le signal et peut amener l'agent à le « déprioriser » dans une fenêtre de contexte limitée. Concentrez-vous sur les informations que l'agent ne peut pas déduire lui-même en lisant le code.

Résumé

CLAUDE.md est le pont qui permet à Claude Code de conserver la mémoire du projet à travers des sessions indépendantes. Vous placez le fichier à la racine du projet, vous écrivez le contexte sur la stack, la structure, les conventions et les commandes courantes, puis vous le committez avec le codebase. L'agent lit ce fichier automatiquement à chaque session et opère de manière cohérente dès le départ sans que vous ayez à tout réexpliquer. C'est l'une des habitudes les plus simples qui apporte les gains de productivité les plus visibles lorsque vous travaillez avec Claude Code.