Structuré avec Claude

CLAUDE.md — bonnes pratiques

CLAUDE.md est le fichier que Claude lit automatiquement à chaque session. C’est ton levier principal pour calibrer son comportement sans répéter les mêmes instructions à chaque échange.

Où il vit

Il existe trois niveaux, lus de façon cumulative :

Fichier	Portée	Usage
`~/.claude/CLAUDE.md`	Global (tous projets)	Préférences personnelles, style de réponse, règles universelles
`CLAUDE.md` (racine projet)	Projet (versionné)	Stack, conventions, commandes, règles projet
`src/CLAUDE.md` (sous-dossier)	Sous-dossier spécifique	Instructions spécifiques à une partie du codebase

En pratique, le fichier à la racine du projet est celui qui compte le plus.

Les règles de base

Court et dense > long et verbeux. Claude lit tout le fichier à chaque session. Une instruction claire en une ligne vaut mieux qu’un paragraphe flou.

Écrire pour Claude, pas pour un humain. Pas besoin d’expliquer le “pourquoi” si ça n’aide pas Claude à mieux agir. Aller droit au but.

Mettre ce qui change le comportement, pas ce qui est évident. “Ne jamais utiliser var en JavaScript” est utile. “Écrire du bon code” ne l’est pas.

Mettre à jour au fil du projet. Un CLAUDE.md obsolète est pire qu’un CLAUDE.md inexistant — il induit Claude en erreur.

Structure recommandée

# Nom du projet

## Stack
- Langage, framework, version
- Base de données, ORM
- Outils de test

## Conventions
- Nommage, structure des fichiers
- Patterns à suivre
- Patterns à éviter

## Commandes utiles
commande1    # description
commande2    # description

## Règles absolues
- Ne jamais faire X
- Toujours faire Y avant Z
- Ne pas modifier [fichiers critiques]

## Contexte métier
[Si pertinent : domaine, terminologie spécifique, contraintes business]

Exemple : CLAUDE.md mal écrit

# Mon super projet

Bienvenue dans le projet ! Ce projet est une application web moderne construite
avec les meilleures pratiques du développement logiciel. Nous utilisons React
pour le frontend et Node.js pour le backend.

Il est important d'écrire du code propre et bien commenté. Les tests sont
importants. Essaie de suivre les bonnes pratiques généralement acceptées dans
l'industrie.

Pour démarrer le projet, tu peux utiliser npm run dev. Pour les tests, npm test.

Problèmes : trop de prose, rien d’actionnable, pas de conventions précises, aucune règle dure.

Exemple : CLAUDE.md bien écrit

# thealiasfmr hub

## Stack
- Astro 6 + Starlight (docs uniquement)
- MDX pour les pages de doc et blog
- Vanilla CSS — pas de Tailwind
- Variables CSS dans src/styles/global.css

## Conventions
- Pages FR : src/content/docs/ (racine)
- Pages EN : src/content/docs/en/ (même structure)
- Toute page .mdx doit avoir AuthorBadge en haut
- CSS : toujours var(--color-x), jamais valeurs hardcodées

## Commandes
npm run dev      # dev server localhost:4321
npm run build    # build production
npm run preview  # preview build

## Règles absolues
- Ne pas modifier astro.config.mjs sans validation explicite
- Ne jamais casser la config root locale Starlight
- Créer le placeholder EN quand on crée une page FR

Différence : court, précis, actionnable. Claude sait exactement quoi faire et quoi éviter.

Erreurs classiques

Tout mettre dedans. Plus CLAUDE.md est long, plus les instructions importantes se noient dans le bruit. Viser l’essentiel.

Instructions contradictoires. “Toujours écrire des tests” ET “Ne pas écrire de tests pour les utilitaires” sans précision → Claude choisit aléatoirement.

Ne pas le mettre à jour. Une stack change, des conventions évoluent. Un CLAUDE.md qui décrit l’ancien projet génère des erreurs silencieuses.

Oublier le niveau global. Le ~/.claude/CLAUDE.md global permet de factoriser les règles communes à tous tes projets (style de réponse, langue, préférences).

→ Voir aussi : Coûts & tokens — un CLAUDE.md concis réduit directement ta consommation.