# CLAUDE.md — Best Practices officielles (synthèse Anthropic) Synthèse de la documentation officielle Anthropic / Claude Code sur l'organisation des fichiers CLAUDE.md pour un projet de grande taille. **Sources officielles consultées** : `docs.claude.com/claude-code/memory`, `docs.anthropic.com/claude-code`, billet `claudelog.com`. --- ## 1. Hiérarchie de chargement Claude Code charge les CLAUDE.md dans cet ordre, à chaque démarrage de session : 1. **Managed** (settings d'org si MDM/enterprise) 2. **User** : `~/.claude/CLAUDE.md` (préférences perso, tous projets) 3. **Project** : `./CLAUDE.md` ou `./.claude/CLAUDE.md` (racine du repo) + tous les CLAUDE.md des dossiers **ancêtres** (walk up) 4. **Local** : `./CLAUDE.local.md` (gitignored, machine spécifique) 5. **Subdirectories** : les CLAUDE.md des **sous-dossiers** sont chargés **à la demande** quand Claude bosse dans ce sous-dossier — utile pour un monorepo. Un `CLAUDE.md` à la racine d'un sous-package ne pollue pas le contexte de la racine. --- ## 2. `@imports` — syntaxe officielle ```markdown @.claude/docs/brand-identity.md @~/.claude/RTK.md ``` - Syntaxe `@path` n'importe où dans un CLAUDE.md. - Profondeur max : **5 niveaux d'imports imbriqués**. - Les paths relatifs résolvent depuis le **fichier qui importe**, pas le cwd. - ⚠️ **Les imports se chargent au démarrage avec le CLAUDE.md parent** → ils coûtent du contexte. Ce n'est PAS un mécanisme de lazy-loading. **Règle pratique** : importer des invariants courts (conventions, raccourcis). Ne PAS importer des docs de référence longues (brand, SEO, business) — Claude les Read à la demande. --- ## 3. Chargement conditionnel via `.claude/rules/` **Feature officielle, pas un pattern communautaire.** Frontmatter YAML avec `paths:` (globs) : ```markdown --- paths: - "src/components/**" - "src/app/**/(page|layout).tsx" --- # Frontend UI Rules […] ``` Comportement : - **Rule sans `paths:`** → chargée au démarrage (comme CLAUDE.md). - **Rule avec `paths:`** → chargée **uniquement** quand Claude ouvre un fichier matchant le glob. **Zéro coût contexte tant que personne ne touche à ces fichiers.** C'est le vrai mécanisme pour scaler un projet sans saturer le contexte : on déplace les instructions spécifiques à une couche (UI, routing, CMS, SEO on-page…) dans des rules à chargement conditionnel. `~/.claude/rules/*.md` fonctionne aussi pour des préférences perso applicables à tous les projets. --- ## 4. Taille recommandée - **Cible : <200 lignes par CLAUDE.md**. Anthropic le précise dans la doc memory. - Plus long → Claude charge moins bien les instructions (dilution dans le contexte) ET coût de contexte plus élevé. - Si tu dépasses → splitter dans `.claude/rules/` (avec `paths:`) ou `.claude/docs/` (lecture à la demande). --- ## 5. Architecture "Router + Rules + Docs" Pattern recommandé pour les projets non triviaux : ``` mon-projet/ ├── CLAUDE.md # Router <200 lignes : invariants, pointeurs ├── .claude/ │ ├── rules/ # Règles conditionnelles │ │ ├── general.md # toujours chargé (workflow, conventions) │ │ ├── frontend-ui.md # paths: src/components/** │ │ ├── routing-metadata.md # paths: src/app/**/(page|layout).tsx │ │ └── ... │ └── docs/ # Référence à la demande (PAS importée) │ ├── brand-identity.md │ ├── business-model.md │ └── ... └── src/... ``` **Router CLAUDE.md type** : ```markdown # {{CLIENT_NAME}} — Next.js SEO ## Stack Next.js 16, App Router, Tailwind v4, TypeScript, {{CMS}}. ## Contexte business / design / SEO Lire à la demande : - `.claude/docs/brand-identity.md` (ton, personas, lexique) - `.claude/docs/design-system.md` (couleurs, typo, tokens) - `.claude/docs/seo-strategy.md` (mots-clés, cocon, concurrents) - `.claude/docs/content-strategy.md` (pages, copy direction) - `.claude/docs/business-model.md` (services, prix, USP) - `.claude/docs/target-audience.md` (personas détaillés) - `.claude/docs/platform-stack.md` (intégrations, env) - `.claude/docs/code-conduct.md` (invariants Elevaseo) ## Workflow Voir `.claude/rules/general.md` (toujours chargé). Règles spécifiques : auto-chargées via `paths:` quand tu touches src/. ``` Note : **on ne met PAS de `@import` vers les docs** — Claude les lit avec le tool Read quand il en a besoin. C'est ça qui rend le système scalable. --- ## 6. Slash commands vs CLAUDE.md vs Skills | Type | Quand l'utiliser | |---|---| | **CLAUDE.md** | Règles toujours actives (style, conventions, invariants). Chargé chaque session. | | **`.claude/rules/*.md` avec `paths:`** | Règles spécifiques à une couche/un sous-système. Chargées à la demande. | | **`.claude/docs/*.md`** | Référence consultable (branding, archi détaillée, runbooks). Lecture manuelle. | | **`.claude/commands/*.md`** (slash commands) | Workflow réutilisable déclenché à la main : `/deploy`, `/seo-audit`. | | **Skills (`.claude/skills/`)** | Workflow complexe avec heuristique de déclenchement automatique. Pattern Anthropic moderne. | Tendance 2026 : pour des workflows complexes, **préférer un skill** à un slash command — un skill peut s'auto-déclencher quand le contexte matche, le slash command demande une invocation manuelle. --- ## 7. Pièges fréquents | Piège | Solution | |---|---| | CLAUDE.md de 1000 lignes | Splitter dans `.claude/rules/` avec `paths:` ou `.claude/docs/` | | `@import` sur des docs lourdes | Ne pas importer, laisser Claude Read à la demande | | Monorepo : ancêtres CLAUDE.md polluent | Utiliser `claudeMdExcludes` dans `.claude/settings.local.json` | | Confusion rules vs docs | Rules = règles d'écriture/comportement. Docs = info de référence. | | Confusion rules vs skills | Rules = chargement conditionnel automatique sur glob. Skills = workflow nommé, plus riche, peut faire des actions. | --- ## 8. Décision pour Elevaseo Pour les sites Next.js clients : - **Router CLAUDE.md** : invariants Elevaseo + pointeurs vers `.claude/docs/`. Pas d'imports. - **`.claude/rules/`** : 5 fichiers (`general`, `frontend-ui`, `routing-metadata`, `seo-on-page`, `cms-integration`). Chargement conditionnel via `paths:` pour ne pas saturer le contexte sur les tâches qui ne touchent pas ces couches. - **`.claude/docs/`** : 8 fichiers générés depuis les templates client. Lus à la demande par Claude. C'est exactement la structure officielle, scalée pour un volume de 8-10 sites/an.