CLAUDE.md : écrire les consignes de votre projet pour Claude Code

Où le placer

Claude Code lit le CLAUDE.md du dossier où vous le lancez et ceux de tous les dossiers au-dessus. Les fichiers s'additionnent, ils ne se remplacent pas. Ceux des sous-dossiers se chargent seulement quand Claude travaille sur un fichier de ce sous-dossier.

Le plus rapide : /init

Dans un projet sans CLAUDE.md, tapez /init : Claude Code analyse le code et rédige un premier fichier avec les commandes de build, les tests et les conventions qu'il repère. Si le fichier existe déjà, /init propose des améliorations au lieu de l'écraser. Relisez le résultat : il décrit ce qu'il voit dans le code, pas forcément ce que vous voulez.

Ce qu'on y met, ce qu'on n'y met pas

• Les faits utiles à chaque session : commandes de build et de test, conventions, organisation des dossiers, règles du type « toujours faire X ».
• Des consignes vérifiables : « indentation de 2 espaces » plutôt que « formater proprement ».
• Pas de procédure en plusieurs étapes, ni de règle qui ne concerne qu'une partie du code : elles vont dans un skill, ou dans une règle limitée à certains chemins (.claude/rules/).
• Pas d'obligation absolue : Claude traite CLAUDE.md comme du contexte, pas comme une configuration imposée. Ce qui doit se produire à coup sûr s'écrit sous forme de hook.

Un modèle de départ

# Projet : boutique en ligne (Next.js)

## Commandes
- Installer : npm install
- Lancer en local : npm run dev
- Tests : npm test (ils passent avant tout commit)

## Conventions
- TypeScript strict, indentation de 2 espaces
- Les textes affichés vivent dans messages/fr.json, jamais dans les composants
- Aucun prix écrit à la main : ils viennent de src/content/prix.ts

## Jamais
- Pousser sur main sans demande explicite
- Lire ou modifier .env et .env.local

## Pour aller plus loin
@docs/architecture.md

Ce qu'on a appris en s'en servant au quotidien

• Une règle tient mieux avec sa raison. « Jamais de prix tapé à la main : ils ont déjà divergé sur trois fichiers » est mieux suivi que « pas de prix en dur ».
• Le fichier global (~/.claude/CLAUDE.md) porte vos préférences : langue des réponses, style d'écriture, ce qui demande votre accord. Le fichier du projet porte ce que toute l'équipe doit respecter.
• Quand le fichier grossit, on déplace : une procédure devient un skill, une règle propre à un dossier va dans .claude/rules/. Selon Anthropic, un fichier long consomme plus de contexte et ses consignes sont moins bien suivies.
• Pour voir ce qui est chargé : /memory liste les fichiers de consignes et permet de les ouvrir.

Chez nous

Nos consignes tiennent sur trois niveaux : un fichier global, un fichier par espace de travail, un fichier par projet. Celui de ce site dit par exemple qu'aucun prix ne s'écrit dans une page. Et comme CLAUDE.md n'est que du contexte, des tests vérifient que la règle tient à chaque mise en ligne.