Fichier Claude.md : comment bien le structurer pour Claude Code

On va dire les choses : traiter son fichier CLAUDE.md comme un simple prompt pour Claude Code, c’est un peu comme vouloir construire une maison en commençant par choisir la couleur du canapé. Ce n’est pas absurde mais ce n’est clairement pas le plus important.

Si vous voulez que Claude Code se comporte comme un développeur qui comprend vraiment votre repo, il lui faut autre chose qu’une suite d’instructions balancées en vrac. Il lui faut une structure de projet qui explique le contexte, les zones sensibles, les règles du jeu et les façons de bosser. Dans cet article, on vous guide pour construire un fichier Claude.md qui fait tout ça !

Qu’est-ce que le fichier claude.md ?

Pourquoi CLAUDE.md n’est pas un simple prompt ?

En gros, Claude a besoin de quatre choses, en permanence :

• le pourquoi : à quoi sert le système ;
• la carte : où vivent les fichiers et les responsabilités ;
• les règles : ce qu’on peut faire ou non ;
• les workflows : comment le travail se déroule concrètement.

C’est ce qu’on peut appeler l’anatomie d’un projet Claude Code.

Le fichier CLAUDE.md ne doit pas être un pavé d’instructions. Il doit servir de mémoire centrale du dépôt : objectif du projet, carte rapide du repo, règles de base et commandes utiles. Plus il est court et précis, plus le modèle a de chances de récupérer le bon contexte au bon moment.

Le piège classique, c’est de faire un fichier qui veut tout contenir :

• l’architecture complète,
• tous les cas métiers,
• toutes les conventions,
• tous les pièges,
• tous les workflows.

Résultat : on transforme un repère en placard de cuisine. Et un placard, même bien rangé, ça reste moins pratique qu’un meuble avec des tiroirs étiquetés.

Que faut-il mettre dans un fichier CLAUDE.md ?

Selon la documentation de Claude Code, un bon fichier CLAUDE.md contient seulement le contexte vital. Il doit répondre rapidement à trois questions : pourquoi ce repo existe, comment il est organisé, et quelles sont les règles non négociables.

Vous pouvez y mettre par exemple :

• la mission du projet ;
• les grands dossiers du repo ;
• les conventions importantes ;
• les commandes utiles ;
• les interdits absolus.

Exemple de logique :

# CLAUDE.md## Purpose
Application interne qui gère les inscriptions, paiements et suivis pédagogiques.## Repo map
- src/app : logique métier
- src/ui : composants interface
- src/api : endpoints
- docs/ : architecture, ADR, runbooks
- .claude/skills : workflows réutilisables## Rules
- ne jamais modifier billing sans tests
- ne jamais toucher aux migrations sans validation
- toujours exécuter lint + tests sur les modules critiques## Commands
- npm run test
- npm run lint
- npm run build

Pas besoin d’écrire un roman. On cherche une boussole, pas une encyclopédie.

Pourquoi la structure du repo compte-t-elle autant pour Claude Code ?

Un modèle travaille mieux quand le projet est organisé en zones claires. La structure aide à comprendre le sens, les relations entre éléments et la hiérarchie de l’information. Un contenu bien segmenté est plus facile à retrouver, à interpréter et à réutiliser.

Dit autrement, si votre repo ressemble à un tiroir “divers”, Claude va bricoler. Si votre repo est aussi bien rangé qu’un atelier de passionné de mécanique, Claude va mieux raisonner.

Une bonne structure permet à l’IA de comprendre :

• où elle travaille ;
• ce qui est sensible ;
• où chercher la vérité ;
• comment ne pas casser la prod un vendredi à 17h42.

Oui, c’est précis. Oui, ça sent le vécu.

À quoi ressemble l’anatomie d’un projet Claude Code ?

Un projet Claude Code solide sépare la mémoire centrale, les workflows réutilisables, les garde-fous, la documentation de référence et les consignes locales. Cette séparation évite de surcharger le contexte et rend l’IA plus fiable dans la durée.

Voici la logique :

• CLAUDE.md : mémoire centrale du repo ;
• .claude/skills/ : modes experts réutilisables ;
• .claude/hooks/ : garde-fous automatiques ;
• docs/ : documentation progressive ;
• CLAUDE.md locaux : consignes proches des zones risquées.

On a fait un joli schéma pour y voir plus claire.

Voyez, le repo commence à ressembler à un environnement de travail, et plus à la conversation du groupe familiale sur Whatsapp.

Pourquoi créer des skills dans .claude/skills/ ?

Les skills servent à transformer des tâches récurrentes en workflows réutilisables. Au lieu de répéter les mêmes consignes à chaque session, on encapsule une méthode stable pour le code review, le refactoring, le release management ou le debug.

En clair, vous allez arrêter de réécrire vingt fois “tu es un top développeur, analyse ce code, vérifie la sécurité, regarde les edge cases, propose une version plus simple” et mettre tout ça dans une skill.

Quels workflows valent le coup d’être transformés en skills ?

Les meilleurs candidats sont les tâches répétitives, sensibles ou structurées. Une skill est utile quand vous voulez la même qualité d’exécution à chaque fois, quel que soit le moment ou la personne qui l’utilise.

Exemples très utiles :

• code-review/ : checklist qualité, sécurité, lisibilité ;
• refactor/ : simplification, découpage, dette technique ;
• release/ : vérifications avant mise en production ;
• debugging/ : hypothèses, reproduction, instrumentation, correctif.

Le bénéfice est simple :

• plus de cohérence ;
• moins d’oublis ;
• moins de “ça dépend” ;
• plus de capitalisation d’équipe.

Bref, vous industrialisez l’intelligence au lieu de la rejouer à la main.

À quoi servent les hooks dans .claude/hooks/ ?

Les hooks servent à rendre automatiques les vérifications qui ne doivent jamais dépendre de la mémoire du modèle. Une IA peut oublier une consigne ; un hook, non. C’est la différence entre “normalement ça passe” et “on a mis une ceinture de sécurité”.

Les hooks sont parfaits pour :

• lancer un formateur après modification ;
• exécuter les tests sur des zones critiques ;
• empêcher l’accès à certains dossiers ;
• vérifier qu’un changement respecte les règles du repo.

Pourquoi les hooks sont-ils plus fiables que les prompts ?

Parce qu’un hook est déterministe. Là où le prompt influence un comportement probable, le hook impose une action ou un blocage réel. C’est essentiel pour les modules sensibles, comme l’authentification, la facturation ou les migrations.

Exemples de zones à protéger :

• src/auth/
• src/billing/
• database/migrations/

En gros, si une erreur peut coûter cher, la confiance dans le prompt ne suffit pas.

Pourquoi mettre la doc dans docs/ au lieu de tout mettre dans CLAUDE.md ?

Parce que toute l’information n’a pas besoin d’être présente en permanence dans le contexte principal. Une bonne doc vit dans des espaces dédiés : vue d’architecture, décisions techniques et runbooks opérationnels. Cette logique de “source de vérité” évite de gonfler inutilement le contexte.

C’est une bonne pratique valable pour tout projet de code :

• on n’entasse pas tout ;
• on structure l’info ;
• on crée des blocs clairs ;
• on aide le système à trouver ce dont il a besoin au bon moment.

Que mettre dans docs/ ?

Le dossier docs/ doit contenir le contexte durable, détaillé et référentiel. On y place ce qui doit exister dans le projet, mais pas forcément dans la tête de Claude à chaque seconde.

Typiquement :

• architecture.md : vision d’ensemble ;
• decisions/ : ADR, choix techniques, arbitrages ;
• runbooks/ : procédures incident, déploiement, récupération.

C’est la différence entre :

• mémoire active dans CLAUDE.md,
• mémoire profonde dans docs/.

Pourquoi ajouter des CLAUDE.md locaux dans certains modules ?

Les fichiers CLAUDE.md locaux permettent de rapprocher les consignes des zones sensibles. Quand Claude intervient dans un module risqué, il voit immédiatement les pièges, conventions et contraintes propres à cet endroit.

C’est particulièrement utile pour :

• src/auth/CLAUDE.md
• src/persistence/CLAUDE.md
• infra/CLAUDE.md

Quels types d’informations mettre dans un CLAUDE.md local ?

Un CLAUDE.md local doit contenir les gotchas du module. On y met les pièges fréquents, les dépendances délicates, les invariants métier et les tests à exécuter avant toute modification.

Exemple pour src/auth/CLAUDE.md :

# CLAUDE.md## Module purpose
Gestion de l’authentification, des sessions et des permissions.## Rules
- ne jamais contourner la validation de session
- ne jamais modifier les scopes sans revue humaine
- toute modification doit conserver la compatibilité avec le middleware d’audit## Required checks
- tests auth
- tests permissions
- tests e2e login/logout

L’intérêt est énorme ! Claude n’a pas besoin de deviner les angles morts. Ils sont juste là, sous son nez.

En quoi cette approche change-t-elle vraiment le comportement de Claude ?

Un repo structuré fait passer Claude d’un mode “assistant qui improvise” à un mode “ingénieur qui opère dans un cadre”. Plus le projet donne des repères clairs, plus les réponses deviennent cohérentes, contextuelles et sûres.

Sans structure :

• Claude répond à la demande immédiate ;
• oublie des contraintes ;
• réinvente les consignes ;
• applique des règles inconsistantes.

Avec structure :

• Claude retrouve le contexte plus vite ;
• respecte mieux les limites ;
• suit des workflows réutilisables ;
• agit de manière plus stable d’une session à l’autre.

En gros, vous remplacez la magie par du design. Et dans un projet logiciel, c’est généralement une excellente idée.

Comment mettre en place cette structure sans tout refaire d’un coup ?

Il ne faut pas refondre tout le repo en une journée. Le plus efficace est d’avancer par couches : d’abord le fichier central, puis les skills récurrentes, ensuite les hooks, puis la documentation détaillée et enfin les consignes locales sur les zones critiques.

Plan simple :

1. Commencer par le minimum vital

Créez un CLAUDE.md court avec :

• la mission ;
• la carte du repo ;
• 5 à 10 règles ;
• les commandes essentielles.

2. Identifier 3 workflows répétitifs

Transformez-les en skills :

• review,
• debug,
• refactor.

3. Poser 2 ou 3 hooks de sécurité

Par exemple :

• format automatique ;
• tests sur modules critiques ;
• blocage de dossiers sensibles.

4. Ranger la vérité dans docs/

Créez :

• un overview d’architecture ;
• quelques ADR ;
• un ou deux runbooks utiles.

5. Ajouter des CLAUDE.md locaux là où ça pique

Auth. Persistence. Infra. Billing. Migrations.
Les endroits où “petit changement” peut vouloir dire “grosse galère”.

Quelle structure type peut-on adopter ?

Une structure simple et modulaire suffit souvent à transformer l’expérience. Le but n’est pas la perfection théorique, mais la lisibilité opérationnelle.

Exemple :

mon-projet/
├── CLAUDE.md
├── README.md
├── docs/
│   ├── architecture.md
│   ├── decisions/
│   └── runbooks/
├── .claude/
│   ├── settings.json
│   ├── hooks/
│   └── skills/
│       ├── code-review/
│       │   └── SKILL.md
│       ├── refactor/
│       │   └── SKILL.md
│       └── release/
│           └── SKILL.md
├── src/
│   ├── api/
│   │   └── CLAUDE.md
│   ├── auth/
│   │   └── CLAUDE.md
│   └── persistence/
│       └── CLAUDE.md
└── tools/
    ├── scripts/
    └── prompts/

C’est propre. C’est lisible. Et surtout, ça donne à Claude des repères stables.

Alors, faut-il mieux prompter ou mieux structurer ?

Le prompting reste utile, mais la structure a plus d’impact à long terme. Un bon prompt peut améliorer une tâche ponctuelle ; une bonne architecture d’information améliore toutes les sessions.

Autrement dit : prompting is temporary, structure is permanent. Oui, la formule est bonne. Parce qu’elle est vraie.

Conclusion : comment faire de Claude un ingénieur “natif” de votre projet ?

Claude devient vraiment utile quand le repo lui donne du contexte durable, localisable et exploitable. Un bon projet Claude Code ne repose pas sur un prompt géant, mais sur une architecture d’information claire, modulaire et maintenable.

Retenez l’essentiel :

• CLAUDE.md = mémoire centrale, courte ;
• .claude/skills/ = workflows réutilisables ;
• .claude/hooks/ = garde-fous déterministes ;
• docs/ = vérité détaillée ;
• CLAUDE.md locaux = consignes proches des zones à risque.

Quand votre repo est organisé comme ça, Claude arrête peu à peu de se comporter comme une IA à qui il faut tout répéter. Et commence à agir comme quelqu’un qui travaille vraiment dans le projet. Pas mal pour un collègue qui ne demande ni week-end prolongé ou clavier mécanique à 300 euros.