Écrire un CLAUDE.md qui tient pour une équipe de développement

Un fichier CLAUDE.md est un fichier Markdown placé à la racine d'un projet, que Claude Code lit automatiquement au début de chaque session pour connaître le contexte du dépôt. Il contient les commandes de build et de test, les conventions de l'équipe, l'architecture en une phrase et les zones sensibles à ne pas toucher sans revue. Son rôle est précis : porter ce qui reste vrai d'une session à l'autre, pas ce qui se discute dans le prompt du jour.

Le symptôme qui amène la plupart des équipes à s'y intéresser est toujours le même. L'agent redemande les commandes de test à chaque session, propose un nommage de fichier qui ne correspond pas aux conventions internes, ou modifie un module que personne ne voulait voir toucher. Un fichier de contexte projet bien construit règle une bonne partie de ces frictions, sans complexité ajoutée.

Ce guide détaille ce qui mérite d'y figurer, ce qui n'y a pas sa place, le cas particulier du monorepo, et la manière de le faire vivre à plusieurs sans qu'il devienne un fourre-tout périmé.

1. Le rôle exact du fichier CLAUDE.md dans une session

Claude Code charge le contenu de CLAUDE.md avant de traiter la première demande de la session. Cette information reste disponible pendant toute la conversation, sans que l'utilisateur ait à la répéter. C'est la différence fondamentale avec un prompt : le prompt décrit une tâche ponctuelle, le fichier de contexte décrit un projet.

Cette distinction guide tout le reste. Une information qui vaut pour une tâche unique n'a rien à faire dans CLAUDE.md : elle encombre le contexte de l'agent pour toutes les sessions suivantes, y compris celles qui n'ont aucun rapport avec elle. À l'inverse, une convention stable répétée dans chaque prompt est un signal que le fichier de contexte mérite d'être complété.

Sur des équipes qui adoptent Claude Code, notamment lorsqu'il s'agit de déployer Claude Code en équipe, la question qui revient le plus en formation n'est pas « comment écrire le fichier » mais « quoi y mettre ». La réponse tient en un critère simple : une information mérite d'y figurer si elle reste vraie indépendamment de la tâche du jour.

2. Ce qui mérite de figurer dans le fichier

Un socle utile couvre un nombre restreint de catégories. Les détailler une à une évite le réflexe d'y verser toute la documentation du projet.

Commandes de build, de test et de lint

C'est l'information la plus consultée par l'agent, et celle dont l'absence coûte le plus de temps. Sans elle, l'agent devine une commande, se trompe, ou pose la question à chaque session.

## Commandes
- Installer les dépendances : pnpm install
- Lancer les tests : pnpm test
- Lancer un seul fichier de test : pnpm test -- chemin/du/fichier.test.ts
- Linter : pnpm lint
- Build de production : pnpm build

Architecture en une phrase

L'objectif n'est pas de documenter l'architecture, mais de donner à l'agent un repère immédiat pour situer un fichier avant de le modifier.

## Architecture
API FastAPI dans src/, pages Jinja2 dans frontend/, logique métier
partagée dans src/services/. Le frontend n'appelle jamais la base
de données directement, toujours via src/services/.

Conventions de nommage et de style d'équipe

Les conventions qui ne sont pas déjà imposées par un linter automatique valent d'être écrites. Un linter qui bloque une pull request suffit sans CLAUDE.md ; une convention qui repose sur la relecture humaine ne suffit pas.

• Nommage des fichiers, des composants, des branches git
• Langue du code (variables en anglais, commentaires en français, par exemple)
• Structure attendue d'un commit ou d'une pull request

Chemins sensibles et zones à ne pas toucher

C'est la catégorie la plus souvent oubliée, et celle qui évite le plus d'incidents. Un fichier de configuration de production, un script de migration déjà exécuté, ou un module legacy qu'une seule personne comprend encore méritent une ligne explicite.

## Zones sensibles
- Ne jamais modifier migrations/ sans validation d'un lead
- src/legacy_billing.py : code de facturation historique, ne pas
  refactorer sans ticket dédié, couverture de tests insuffisante
- .env.example à jour uniquement, jamais de secret réel dans le dépôt

3. Ce qui n'a pas sa place dans le fichier

Un CLAUDE.md efficace se définit autant par ce qu'il exclut que par ce qu'il contient.

• Le détail qui périme vite : la liste des tickets en cours, l'état d'avancement d'une fonctionnalité, un bug connu en cours de correction. Ces informations ont leur place dans un ticket ou une pull request, pas dans un fichier lu à chaque session pendant des mois.
• La documentation complète du projet : un README existant ou une documentation technique détaillée ne se recopient pas dans CLAUDE.md. Un lien vers ce document, avec une phrase de résumé, suffit.
• Les secrets et identifiants : clés d'API, mots de passe, tokens. Un fichier de contexte est lu par l'agent et, en pratique, il est aussi committé et parfois partagé. Aucun secret ne doit s'y trouver, au même titre que dans n'importe quel fichier versionné.

Un fichier qui mélange ces catégories avec le socle utile perd vite en lisibilité. L'agent traite tout le contenu de la même façon : une information périmée noyée au milieu de commandes valides pèse autant, dans le contexte, qu'une information à jour.

4. Le cas du monorepo

Un monorepo regroupe plusieurs paquets ou applications dans un seul dépôt. La question qui se pose systématiquement en formation sur ce sujet est de savoir s'il faut un fichier unique ou un fichier par paquet. La réponse dépend de ce qui varie réellement entre les paquets.

Un fichier racine pour ce qui vaut partout

Le fichier à la racine du dépôt porte ce qui reste vrai pour tout le monorepo : gestionnaire de paquets utilisé, convention de commit, structure générale des dossiers, politique de revue de code.

Un fichier par paquet pour ce qui varie

Chaque paquet ou application ajoute son propre fichier CLAUDE.md dans son sous-dossier, avec ses commandes spécifiques (un paquet backend en Python n'a pas les mêmes commandes de test qu'un paquet frontend en TypeScript) et ses particularités d'architecture interne.

Ce qui s'hérite entre les deux niveaux

Claude Code lit le fichier du dossier de travail courant et remonte vers la racine pour compléter le contexte. En pratique, cela signifie qu'une session ouverte dans un paquet précis dispose des deux niveaux d'information, sans duplication nécessaire. Une convention de commit définie une seule fois à la racine n'a pas besoin d'être répétée dans chaque paquet.

5. Versionner et faire vivre le fichier à plusieurs

Un fichier CLAUDE.md non versionné dérive rapidement de la réalité du code. Le committer avec le reste du projet est la règle, sauf cas particulier où l'équipe préfère un fichier local non partagé pour des préférences strictement individuelles.

La revue de code comme garde fou

Une modification de CLAUDE.md mérite le même traitement qu'une modification de configuration partagée : elle passe par une pull request, relue par au moins une autre personne. Cela évite qu'une convention change silencieusement pour un seul contributeur pendant que le reste de l'équipe continue sur l'ancienne règle. Cette relecture suit les mêmes principes que ceux détaillés pour relire du code généré par IA : vérifier les décisions non explicites, pas seulement la syntaxe.

Ce qui déclenche une reprise du fichier

Plusieurs signaux indiquent qu'une mise à jour est nécessaire, plutôt que d'attendre une révision périodique arbitraire :

• Changement d'outil de build, de gestionnaire de paquets ou de framework de test
• Nouvelle convention adoptée en équipe après une rétrospective
• Ajout d'un nouveau module ou service dont l'architecture mérite une phrase de repère
• Correction répétée du même écart par l'agent, signe qu'une règle manque ou est mal formulée

6. Le piège du fichier trop long

Un fichier CLAUDE.md consomme de la fenêtre de contexte à chaque session, sur chaque tâche, même la plus simple. Un fichier qui accumule des règles obsolètes, des explications redondantes ou des sections copiées d'une documentation externe n'apporte rien en échange de cette consommation.

Le signal le plus fiable qu'un fichier est devenu trop long n'est pas sa longueur en elle-même, mais son effet observé : l'agent commence à ignorer certaines instructions, à mélanger des règles issues de contextes différents, ou à traiter une information ancienne comme encore valide. Un fichier utile tient, dans la grande majorité des projets, sur une à deux pages.

La correction est presque toujours la même : déplacer le détail vers la documentation classique du projet, et ne garder dans CLAUDE.md que ce qui sert réellement à chaque session, quelle que soit la tâche. Ce principe rejoint celui qui structure les dynamic workflows dans Claude Code : un contexte ciblé produit de meilleurs résultats qu'un contexte exhaustif.

Pour une équipe qui connecte aussi Claude Code à des outils externes via le Model Context Protocol, la même discipline s'applique : le fichier de contexte décrit le projet, les connecteurs exposent les données à la demande, les deux ne se substituent pas l'un à l'autre.

En pratique, un fichier CLAUDE.md ne se termine jamais vraiment. Il évolue avec le projet, se corrige après chaque friction observée avec l'agent, et se discute en équipe comme n'importe quelle convention partagée. Le socle proposé ici (commandes, architecture en une phrase, conventions, zones sensibles) suffit pour démarrer sur la grande majorité des projets, monorepo compris.

Pour aller plus loin

• formation Claude Code : accompagnement d'équipe pour adopter Claude Code sur un dépôt réel, conventions comprises.
• MCP, le Model Context Protocol en entreprise : connecter Claude Code à vos outils internes au delà du fichier de contexte.
• Dynamic workflows Claude Code : orchestrer plusieurs agents en parallèle sur des tâches à grande échelle.
• Formation vibecoding avec Claude Code : apprendre à coder avec un agent pour un public non spécialiste.
• Coding agents ou développement sur mesure pour PME : quand un agent de code suffit, quand un développement sur mesure reste nécessaire.