Le CLAUDE.md de projet : ce que ton dépôt sait de lui-même

ByJean-Yves Hemlin

À la fin de cet article, ton dépôt (le dossier de ton projet, celui que Git suit et que tu peux envoyer à un collègue) contiendra un fichier qui explique une fois pour toutes ses outils, ses conventions et ses pièges. Ce fichier est partagé par Git avec quiconque ouvre le dépôt ensuite, toi dans six mois inclus.

Le CLAUDE.md général de l’article précédent s’applique partout, tout le temps, un peu comme des habitudes que tu gardes quel que soit le dossier sur lequel tu travailles. Celui d’aujourd’hui vit à l’inverse dans ton projet : il ne parle que de lui, comme une fiche collée sur un dossier précis.

Le CLAUDE.md général, resté sur la machine, et le CLAUDE.md de projet, partagé par Git à la racine du dépôt, sont chargés ensemble dans la session et s'additionnent.

Ce qu’il te faut

Un projet existant avec au moins quelques fichiers dedans. Si tu n’as encore aucun projet Claude Code, n’importe quel dossier de code que tu as sous la main fait l’affaire pour t’exercer.

Étape 1 — Générer un premier jet avec /init (3 minutes)

Ouvre un terminal à la racine de ton projet et lance :

claude

Puis, dans la session :

/init

Claude Code lit ton dépôt (la structure des dossiers, les fichiers qui listent les outils utilisés, un README existant s’il y en a un) et génère un CLAUDE.md de départ à la racine. C’est un point de départ, pas un travail fini : passe cinq minutes à le relire avant de continuer.

Et si /init ne trouve rien à dire ?

Sur un dossier vide, ou presque (un projet qui démarre, un simple README.md sans code), /init produit un fichier squelette qui ne t’apprend rien : il n’a rien à lire. C’est normal, ce n’est pas un échec de la commande. Il n’existe simplement pas encore de code dont déduire des habitudes de travail.

Dans ce cas, n’attends pas d’avoir du code à décrire : écris le fichier toi-même, à la main, comme une déclaration d’intention plutôt qu’une observation. La différence avec un projet mature, c’est que tu décris ce que le projet doit devenir plutôt que ce qu’il est déjà :

# Projet — API de facturation (nouveau projet)

## Stack prévue
- Python 3.12, FastAPI, PostgreSQL via SQLAlchemy
- Tests avec pytest dès la première fonction écrite

## Conventions à respecter dès le départ
- Type hints obligatoires sur toute nouvelle fonction
- Un module = une responsabilité ; pas de fichier `utils.py` fourre-tout

Ce fichier sans historique n’est pas moins utile : il évite à Claude Code d’improviser des outils ou une convention à ta place dès les premiers fichiers, et il t’évite à toi de retaper les mêmes précisions à chaque nouvelle session tant que le projet est encore petit. Une fois que du vrai code existe, relance /init : il complétera ce que tu as écrit à la main avec ce qu’il observe réellement, sans écraser tes intentions de départ si tu les as gardées au-dessus du résultat généré.

Tu ne sais pas quoi mettre dedans ? Ne reste pas devant une page blanche : demande directement à Claude Code de le rédiger avec toi.

Je démarre un projet d'API de facturation en Python. Pose-moi les questions
nécessaires (stack, conventions, ce que je veux éviter) et rédige-moi un
premier CLAUDE.md de projet à partir de mes réponses.

C’est une solution valable, souvent meilleure que d’écrire seul : au lieu de deviner toi-même la bonne structure, tu décris ton intention avec tes propres mots, et l’IA pose les questions qui manquent (langage cible, conventions d’équipe, contraintes de mise en ligne) avant de proposer un premier jet. Tu gardes la main pour trancher, mais tu ne pars plus d’une page blanche.

Étape 2 — Élaguer, pas empiler (5 minutes)

/init a tendance à être généreux. Le réflexe à corriger tout de suite : ce fichier n’est pas de la documentation générale de ton projet, c’est un mode d’emploi pour une IA qui va exécuter des commandes dedans. Retire tout ce qui appartiendrait plutôt à un README.md classique, c’est-à-dire une présentation du projet pour un humain qui découvre, et garde ce qui change concrètement le comportement de Claude Code :

# Projet — API de facturation

## Stack
- Python 3.12, FastAPI, PostgreSQL via SQLAlchemy
- Tests avec pytest, lancés par `make test` (pas directement `pytest`,
  le Makefile configure la base de test)

## Conventions
- Type hints obligatoires sur toute nouvelle fonction
- Pas de print() pour le debug : utiliser le logger déjà configuré
  dans `app/logging.py`

## Pièges connus
- Le dossier `legacy/` n'est plus maintenu, ne jamais s'en inspirer
  pour du nouveau code
- Les migrations de base de données passent par `alembic`, jamais
  de modification manuelle du schéma

Trois sections suffisent pour démarrer : la stack, c’est-à-dire ce que le projet utilise réellement, pas ce qu’il pourrait utiliser ; les conventions, ce que tu corriges à répétition en relisant le travail d’un collègue ; et les pièges, ce qui a déjà fait perdre du temps à quelqu’un.

Étape 3 — Vérifier avec /memory (1 minute)

Comme pour le fichier général, /memory te montre où Claude Code cherche chaque fichier :

/memory

Deux lignes correspondent à tes fichiers si tu as suivi la série depuis le début : « User instructions » (Saved in ~/.claude/CLAUDE.md, ton fichier général) et « Project instructions » (Checked in at ./CLAUDE.md, celui de la racine du dépôt). Sélectionne la seconde avec Entrée : le fichier du projet s’ouvre dans ton éditeur, avec les sections que tu viens d’élaguer. Échap ferme la liste sans rien ouvrir. Les deux fichiers s’additionnent, ils ne s’effacent pas l’un l’autre : le général reste actif, le projet ajoute ses propres règles par-dessus.

Étape 4 — Le partager par Git (30 secondes)

Contrairement au fichier général qui reste sur ta machine, celui-ci vit dans le dépôt. Ajoute-le au suivi de version comme n’importe quel fichier :

git add CLAUDE.md
git commit -m "Ajoute le CLAUDE.md du projet"

Toute personne qui clone le dépôt et ouvre Claude Code dedans hérite immédiatement des mêmes règles, sans configuration de son côté.

Le piège à éviter : la contradiction silencieuse

Comme les deux fichiers s’additionnent, une règle du projet qui contredit une règle générale crée un flou que Claude Code doit trancher lui-même, en silence. Par exemple, ton fichier général dit « type hints toujours », mais un vieux projet n’en utilise nulle part. Si tu sens une hésitation dans les réponses, /memory te mène droit aux deux fichiers en cause ; la solution est presque toujours de rendre la règle de projet explicitement prioritaire (« Ce projet n’utilise pas de type hints, contrairement à la règle générale, pour rester cohérent avec le code existant »).

Ce qui vient de se passer

Un CLAUDE.md de projet, généré par /init puis élagué à l’essentiel, suivi par Git, additionné au fichier général sans l’effacer. Le dépôt sait maintenant se décrire lui-même à quiconque l’ouvre avec Claude Code.

En résumé

  • /init à la racine du projet génère un premier jet à partir du contenu réel du dépôt.
  • Élague ce qui relève de la documentation générale ; garde la stack, les conventions, les pièges connus.
  • /memory liste le fichier général et le fichier de projet, que Claude Code lit ensemble.
  • Suis-le avec Git : c’est ce qui le rend partagé, contrairement au fichier général.
  • En cas de contradiction entre les deux niveaux, rends la règle de projet explicitement prioritaire.

Prochaine étape : le troisième et dernier niveau, pour les projets qui contiennent eux-mêmes des sous-projets avec leurs propres règles.

Cette mise en pratique poursuit la série sur l’installation et la configuration de Claude Code, de zéro jusqu’à un premier programme fonctionnel. La vidéo est ici.

Abonne-toi au blog pour suivre la suite de la série.

Similar Posts