Bonnes pratiques CLAUDE.md : un modèle fiable pour Claude Code

Une pull request revient pour la troisième fois avec le même commentaire. Claude Code a modifié la bonne fonctionnalité, mais a oublié la commande de test du dépôt, touché une migration hors périmètre ou omis le contrôle mobile. Répéter un prompt plus long au début de chaque session ne corrige pas ce problème d’organisation.

Un CLAUDE.md utile donne à Claude Code quelques décisions durables avant le début du travail. Il n’a pas besoin de raconter toute l’entreprise ni de recopier le README. Ce guide explique ce qui doit figurer dans le fichier, ce qui doit être imposé ailleurs et comment vérifier le résultat avec un script Node.js réellement exécutable.

La réponse courte

Le fichier CLAUDE.md doit contenir les commandes, les limites de modification et les critères de revue qui s’appliquent à la plupart des tâches de son périmètre. Gardez ces cinq règles en tête :

CLAUDE.md fournit des instructions persistantes à Claude Code ; ce n’est pas un système de contrôle d’accès.
Placez les règles partagées à la racine du dépôt, les notes personnelles dans CLAUDE.local.md et les règles liées à un chemin dans .claude/rules/.
Visez moins de 200 lignes environ. Les chemins, les commandes et les conditions de réussite sont plus utiles qu’un long contexte historique.
Imposez les restrictions de sécurité avec les permissions et les hooks au lieu de compter sur une interdiction écrite.
Testez une nouvelle instruction sur une petite tâche réelle avant d’en faire une règle d’équipe.

Ne cherchez pas à produire le fichier parfait dès le premier jour. Relevez les commentaires apparus dans les trois dernières revues, puis ne conservez que les décisions qui seront encore utiles lors de la prochaine tâche.

Ce que Claude Code peut faire et ce qu’une personne doit décider

Un fichier d’instructions et une limite de permissions ne répondent pas au même besoin. Claude Code peut examiner le code existant, effectuer une modification ciblée, lancer des contrôles nommés et résumer le diff. Une personne reste responsable de la politique produit, de l’autorisation de mise en production et des décisions qui concernent les clients, l’argent, la vie privée ou le droit.

Décision	Déléguer à Claude Code	Conserver sous contrôle humain
Investigation	Trouver les fichiers, les motifs existants et les tests liés	Décider si des données client ou contractuelles peuvent être consultées
Implémentation	Modifier le code et les tests dans le périmètre indiqué	Approuver les changements de prix, d’autorisation, de règle juridique ou de politique client
Vérification	Exécuter lint, contrôle de types, tests et build	Décider si les critères d’acceptation sont remplis et autoriser la publication
Maintenance	Signaler les fichiers modifiés et les risques non résolus	Ajouter ou retirer des règles permanentes du dépôt

CLAUDE.md signifie en pratique : « vérifie ces éléments dans cet ordre ». Il ne garantit pas qu’une commande destructrice ne sera jamais exécutée. Si git push --force, l’accès à la base de production ou la lecture de fichiers contenant des secrets doivent être bloqués physiquement, utilisez des règles de refus dans les permissions ou un hook PreToolUse. Le guide des permissions de Claude Code présente séparément cette couche d’application.

Choisir le bon périmètre avant d’écrire

L’emplacement du fichier détermine où les instructions s’appliquent. Un CLAUDE.md à la racine convient aux règles partagées du projet. ~/.claude/CLAUDE.md s’applique aux projets de l’utilisateur. CLAUDE.local.md sert aux notes privées propres à une machine et doit être ignoré par Git. Les fichiers imbriqués et les règles limitées à certains chemins empêchent un grand dépôt de charger des instructions sans rapport avec la tâche.

Une organisation simple suffit : repo/CLAUDE.md pour les règles communes, repo/CLAUDE.local.md pour les notes personnelles, repo/.claude/rules/api.md pour les fichiers d’API et repo/packages/admin/CLAUDE.md pour le paquet d’administration.

Au démarrage, Claude Code lit les fichiers applicables dans le répertoire courant et ses parents. Un CLAUDE.md imbriqué est chargé lorsque Claude lit des fichiers de ce sous-arbre. C’est pourquoi les règles propres à un paquet doivent rester près de ce paquet au lieu de toutes s’accumuler à la racine.

Un import comme @docs/project-map.md peut mieux organiser l’information, mais il ne réduit pas le contexte : le contenu importé est lui aussi chargé au démarrage. Conservez dans CLAUDE.md la décision toujours nécessaire et indiquez où lire les détails à la demande. Sous Windows, Claude Code lit CLAUDE.md et non AGENTS.md ; un import explicite @AGENTS.md est donc plus fiable qu’un lien symbolique si les deux fichiers doivent partager leurs consignes.

Un premier modèle CLAUDE.md prêt à adapter

Les commandes et les règles de modification doivent tenir sur un écran. Le modèle ci-dessous évite les conseils vagues comme « écrire du code propre ». Il nomme les chemins, les contrôles, les exclusions et le rapport final attendu de l’agent.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- Database schema: prisma/schema.prisma
- Tests: Vitest for units, Playwright for checkout

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Follow nearby code before adding a new abstraction.
- Do not change auth, billing, or migrations unless the task names them.
- When an API handler changes, update validation and tests together.
- Never place secrets in code, fixtures, logs, or screenshots.

## Review checklist
- Run the checks related to the changed files.
- Test an error path as well as the happy path.
- Report changed files, commands run, and skipped checks.

Le fichier peut être rédigé dans la langue de l’équipe. La précision compte davantage que la langue. Remplacez « tester correctement » par npm test. Remplacez « respecter l’architecture » par une règle concrète comme « les réponses API utilisent src/lib/api-response.ts ». Une personne chargée de la revue doit pouvoir dire si la consigne a été suivie sans en deviner le sens.

Trois cas d’usage concrets

Ces scénarios distinguent clairement les entrées, les sorties et la revue humaine. Avant de rendre une leçon permanente, appliquez-la à une petite tâche et vérifiez si elle modifie un résultat observable.

Cas d’usage 1 : réduire les retours répétés dans une agence

Une agence web peut appliquer des conventions CSS, des dimensions d’image et des navigateurs cibles différents dans chaque dépôt client. Copier tout le manuel de l’agence dans chaque projet rend les règles utiles difficiles à trouver. Conservez plutôt les trois à cinq contrôles propres à ce client et à ce code.

Entrée : Les trois derniers fils de revue, les fichiers inclus dans le périmètre ainsi que les commandes lint et build existantes.

Sortie : Un rapport de diff qui nomme les composants réutilisés, les pages modifiées, les commandes exécutées et les conditions de navigateur restant à vérifier.

Revue humaine : L’intention graphique, les droits sur les images, le texte de l’appel à l’action et le rendu mobile final. Comparez le nombre de retours en revue sur dix tâches avant et après la règle ; cet indicateur est plus parlant que la longueur brute de CLAUDE.md.

Cas d’usage 2 : modifier un formulaire SaaS sans angle mort

Un formulaire peut sembler correct alors que la validation serveur, l’e-mail de notification ou la gestion des erreurs ne fonctionne plus. Les consignes du projet doivent nommer les fichiers et les tests qui évoluent ensemble à chaque modification du formulaire.

Entrée : Le composant du formulaire, le schéma de validation, le handler d’API, le modèle d’e-mail et les tests existants.

Sortie : Des tests pour le parcours nominal et les entrées invalides, des erreurs compréhensibles pour l’utilisateur et la liste des réglages modifiés. Le rapport final doit aussi confirmer qu’aucune donnée personnelle n’a été écrite dans les logs.

Revue humaine : Les champs collectés, la durée de conservation, les destinataires des notifications et l’autorisation de production. Suivez les soumissions en échec et le temps de support, pas seulement le taux de conversion.

Cas d’usage 3 : empêcher une publication de contenu incomplète

Une page MDX peut contenir un texte juste tout en étant publiée sans description, lien interne, image principale ou bloc de code lisible sur mobile. Une courte liste de publication donne à l’agent une ligne d’arrivée observable.

Entrée : Le fichier MDX, le schéma du frontmatter, les cibles des liens internes, la commande de build et l’URL de production.

Sortie : La longueur de la description, le résultat du contrôle des liens, l’état des blocs de code et du build, ainsi que les URL inspectées dans un navigateur.

Revue humaine : L’exactitude des faits, l’intention de recherche, la place des annonces, la lisibilité et l’autorisation de publication. Analysez chaque semaine les clics issus de la recherche, la lecture engagée et les clics sur l’appel à l’action plutôt que les seules pages vues.

Exécuter ce contrôle de CLAUDE.md

Le script Node.js suivant vérifie le nombre de lignes, trois titres obligatoires et quelques motifs de secrets à signal fort. Enregistrez-le sous check-claude-md.mjs et exécutez-le avec Node.js 20 ou une version plus récente.

import { readFile } from "node:fs/promises";

const filePath = process.argv[2] ?? "CLAUDE.md";
const text = await readFile(filePath, "utf8");
const lines = text.split(/\r?\n/);
const lineCount = text.endsWith("\n") ? lines.length - 1 : lines.length;

// Pass localized H2 names as the third argument, separated by "|".
const requiredHeadings = (
  process.argv[3] ?? "Commands|Change rules|Review checklist"
)
  .split("|")
  .map((heading) => heading.trim())
  .filter(Boolean);
const h2Headings = new Set();
let fenceMarker = null;

for (const line of lines) {
  const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
  if (fenceMatch) {
    const marker = fenceMatch[1];
    if (fenceMarker === null) fenceMarker = marker;
    else if (marker[0] === fenceMarker[0] && marker.length >= fenceMarker.length) fenceMarker = null;
    continue;
  }
  if (fenceMarker !== null) continue;

  const heading = line.match(/^##\s+(.+?)\s*$/)?.[1];
  if (heading) h2Headings.add(heading);
}

const secretPatterns = [
  ["AWS access key", /AKIA[0-9A-Z]{16}/],
  ["GitHub token", /gh[pousr]_[A-Za-z0-9]{20,}/],
  ["assigned secret", /\b(api[_-]?key|password|token)\s*[:=]\s*["'][^"'\n]{8,}["']/i],
];

const failures = [];
if (lineCount > 200) failures.push(`too many lines: ${lineCount} (max 200)`);
if (requiredHeadings.length === 0) failures.push("required heading list is empty");

for (const heading of requiredHeadings) {
  if (!h2Headings.has(heading)) failures.push(`missing h2: ${heading}`);
}

for (const [label, pattern] of secretPatterns) {
  if (pattern.test(text)) failures.push(`possible secret: ${label}`);
}

if (failures.length > 0) {
  console.table(failures.map((problem) => ({ problem })));
  process.exitCode = 1;
} else {
  console.log(`CLAUDE.md check passed: ${lineCount} lines`);
}

La commande reste volontairement simple pour fonctionner en local comme en CI : node check-claude-md.mjs CLAUDE.md. Avec des titres H2 traduits, passez-les en troisième argument : node check-claude-md.mjs CLAUDE.md "Commandes|Règles de modification|Liste de contrôle". Si elle renvoie le code 1, corrigez chaque ligne du tableau puis relancez-la avant d’accepter la modification.

Ce contrôle ne remplace pas un scanner complet de secrets. Associez-le au secret scanning de GitHub ou à un outil spécialisé. Lorsqu’un identifiant est détecté, révoquez-le et retirez-le de l’historique si nécessaire ; supprimer uniquement la ligne visible ne suffit pas.

Pièges : causes et corrections concrètes

Piège 1 : le fichier grandit après chaque revue. La cause consiste à transformer tout commentaire en règle permanente sans vérifier s’il se répétera. N’ajoutez que les décisions récurrentes, supprimez d’abord les commandes obsolètes et rapprochez les détails propres à un paquet de ce paquet.

Piège 2 : les instructions sont invérifiables. « Maintenir la qualité » ou « suivre le design existant » ne définit aucun critère de réussite. Remplacez ces phrases par un chemin cible, une commande, un code de sortie attendu, une largeur de navigateur ou un test nommé. Une nouvelle personne dans l’équipe doit parvenir à la même conclusion que l’auteur de la règle.

Piège 3 : la sécurité repose sur du texte. Écrire « ne jamais toucher à la production » ne crée pas de barrière. Ajoutez les motifs de commandes dangereuses aux règles de refus et utilisez un hook PreToolUse lorsqu’une opération doit être arrêtée de manière déterministe. CLAUDE.md peut expliquer la raison et l’alternative approuvée.

Piège 4 : les imports deviennent une réserve documentaire cachée. La cause est de croire que les fichiers importés ne coûtent aucun contexte. Ils sont chargés au démarrage. Gardez une règle de décision courte dans le fichier racine et fournissez un chemin ou une URL pour les détails que Claude ne doit lire que lorsque la tâche l’exige.

Éviter la dérive de la documentation

Traitez une modification de CLAUDE.md comme une modification de code. Ouvrez le diff, lancez le contrôle et testez une tâche représentative. Supprimez une règle lorsque la commande, le chemin ou l’architecture qu’elle décrit n’existe plus.

Une revue mensuelle légère peut répondre à quatre questions :

Quel commentaire de revue est apparu plusieurs fois ?
Quelle instruction a été ignorée ou comprise de deux manières différentes ?
Quelle commande ou quel chemin n’est plus à jour ?
Quel avertissement devrait être imposé par une permission ou un hook ?

Le bon indicateur n’est ni le nombre de tokens ni la taille du document. Suivez le nombre de retours en revue, les échecs détectés avant l’intégration et les minutes consacrées à réexpliquer les bases du dépôt. Si ces chiffres ne s’améliorent pas, reformulez ou retirez la règle.

Questions fréquentes

Quelle longueur viser pour CLAUDE.md ?

Il n’existe pas de limite stricte de contenu, mais la recommandation officielle est de viser moins de 200 lignes. Un départ proche de 100 lignes laisse de la place pour la carte du projet, les commandes, les limites et les contrôles de revue. Déplacez ce qui ne concerne qu’un paquet vers un fichier imbriqué ou .claude/rules/.

Le fichier reste-t-il disponible après /compact ?

Le CLAUDE.md racine est réinjecté dans le contexte après la compaction. Les instructions imbriquées et limitées à un chemin sont rechargées lorsque Claude lit les fichiers correspondants. Placez les décisions durables dans des fichiers au lieu de dépendre d’une conversation susceptible d’être compactée.

Quelle différence avec Auto memory ?

CLAUDE.md contient les instructions écrites et maintenues par des personnes. Auto memory conserve les notes locales que Claude tire de son expérience, par exemple des découvertes de débogage ou des préférences. Les commandes et les limites partagées appartiennent à CLAUDE.md ; une découverte locale reste dans Auto memory tant qu’une personne ne la transforme pas en règle d’équipe.

Que doit contenir la première version ?

Commencez par les commandes d’installation, de test et de build, une liste des zones protégées et les éléments obligatoires du rapport final. Exécutez une vraie tâche, puis ajoutez seulement la décision manquante qui a provoqué une reprise de travail observable.

Transformer ces principes en modèle de projet

Rédiger CLAUDE.md ne constitue qu’une partie d’un processus fiable. Permissions, tests, transmission du contexte et revue doivent exprimer les mêmes limites. Le catalogue de ressources ClaudeCodeLab rassemble des listes de contrôle et des exercices réutilisables pour transformer ces éléments en modèle adapté à votre projet.

Résultats du test réel

Le 22 juillet 2026, le code check-claude-md.mjs présenté dans cet article a été exécuté sur deux fichiers temporaires. Un exemple valide de 10 lignes a terminé avec le code 0 et affiché le message de réussite. L’exemple négatif, contenant un titre manquant et un jeton de test, a terminé avec le code 1 et signalé trois problèmes : le titre absent et deux motifs de secrets correspondants.

La revue de l’article a également contrôlé la syntaxe JavaScript, les URL officielles, les liens internes, le frontmatter, cette section finale et la présence d’un seul appel à l’action commercial. Le comportement décrit a été comparé à la documentation officielle de Claude Code sur la mémoire, la fenêtre de contexte, les réglages et les hooks. Lancez maintenant le contrôle sur votre propre CLAUDE.md, puis corrigez le premier problème indiqué.