Le fichier CLAUDE.md est la pierre angulaire de la configuration Claude Code en grand codebase. Mal structuré, il devient un fourre-tout illisible que Claude charge en entier à chaque session. Bien structuré, c'est l'équivalent d'une documentation d'onboarding senior qui rend Claude immédiatement productif.
Anthropic recommande dans son guide officiel 2026 une architecture en couches qu'on détaille ici.
Le CLAUDE.md à la racine du projet doit contenir uniquement le big picture. Trois sections suffisent. La nature du projet en deux lignes. La stack technique principale (langages, frameworks, bases de données). Les commandes universelles qui s'appliquent à tout le repo (npm run build à la racine, déploiement global).
Pas plus. Tout ce qui est spécifique à un sous-répertoire descend dans le CLAUDE.md du sous-répertoire.
Dans chaque sous-dossier important, créer un CLAUDE.md local. Il contient les conventions de ce sous-projet, les commandes de test propres à son scope, les patterns à respecter, les pièges à éviter.
Quand Claude est lancé dans ce dossier, il remonte l'arborescence et charge tous les CLAUDE.md des niveaux supérieurs, additivement. Pas de duplication. Le contexte est précisément calibré au scope du travail demandé.
Exemple concret. Un projet monorepo avec apps/web/, apps/api/, packages/shared/. Trois CLAUDE.md locaux plus un racine. Le développeur travaillant sur apps/api/ lance Claude dans ce dossier et reçoit automatiquement le contexte racine + api spécifique, sans contamination du contexte web ou shared.
Dans chaque CLAUDE.md local, déclarer les tests qui s'appliquent uniquement au scope. Plutôt que d'écrire à la racine "npm test" qui lance la suite complète de quinze minutes, écrire dans apps/api/CLAUDE.md "cd apps/api && npm test" qui prend trente secondes.
Claude utilisera la commande locale quand il travaille dans ce dossier, et il ne lancera la suite complète que si demandé explicitement. Gain de latence massif sur les itérations.
À côté de CLAUDE.md, le fichier .claude/settings.json contient les règles de permissions. Notamment permissions.deny qui exclut les fichiers générés, build artifacts, dependencies tierces (node_modules, vendor/, dist/, .next/).
Committer ce fichier dans git fait que chaque développeur reçoit la même configuration jour un, sans setup manuel. Standardisation immédiate.
Anthropic recommande d'utiliser des stop hooks qui s'exécutent à la fin de chaque session Claude Code. Ces hooks peuvent analyser ce qui s'est passé pendant la session (commandes lancées, erreurs rencontrées, patterns émergents) et proposer des mises à jour automatiques du CLAUDE.md pendant que l'information est encore fraîche.
C'est la mécanique d'auto-amélioration que nous enseignons à nos clients dans le parcours Claude Architect Prep. Au bout de trente sessions, le CLAUDE.md a été enrichi par Claude lui-même de patterns spécifiques au projet que personne n'aurait pensé à documenter manuellement.
Nous gérons un réseau de cent vingt-et-un sites WordPress et Pages Cloudflare avec Claude Code. Notre architecture CLAUDE.md a trois niveaux. Racine pour les conventions globales (URL canonique sans www, signature Franck PARIENTI, ton prose française sans bullets). Niveau scripts/ pour les conventions Apps Script et Cloudflare Workers. Niveau supabase/functions/ pour les conventions Edge Functions Deno.
Le résultat : nos sessions Claude Code sont prédictibles, les erreurs récurrentes sont éliminées par auto-amélioration hook, et tout nouveau développeur arrive avec le bon contexte immédiatement.
Notre parcours Claude Architect Prep couvre cette architecture en détail, avec exercices pratiques sur des codebases réels. Quinze heures, gratuit, certificat partageable sur LinkedIn, préparation à la certification officielle Claude Certified Architect Foundations d'Anthropic.
https://businessdigital.fr/academie/parcours/claude-architect-prep
Franck PARIENTI BusinessDigital.fr