Claude Code CLI : configurer CLAUDE.md pour lab-claude

Vous avez déroulé un premier workflow sur lab-claude, mais vous retapez à chaque session les mêmes règles : “utilise uv run ruff check .”, “tests dans tests/”, “pas de dépendance nouvelle sans validation”. Ce guide vous montre comment poser ces règles une fois pour toutes dans un fichier CLAUDE.md court, que Claude Code lit automatiquement à l’ouverture d’une session dans le dépôt.

Ce que vous allez apprendre

Créer un CLAUDE.md court et utile pour lab-claude
Répartir les sections : stack, commandes, conventions, garde-fous
Distinguer les trois niveaux global, projet et sous-dossier
Utiliser les imports pour mutualiser des règles partagées
Vérifier que Claude Code lit bien le fichier au démarrage
Faire évoluer CLAUDE.md sans le transformer en fourre-tout
Éviter les CLAUDE.md gonflés qui noient l’information

Pourquoi un CLAUDE.md court vaut mieux qu’un long

Claude Code charge le contenu de CLAUDE.md dans le contexte de chaque session. Un fichier de 500 lignes consomme inutilement de la fenêtre de contexte, et l’agent survole l’essentiel. Un fichier de 30 à 80 lignes bien ciblées a un effet immédiat : moins de reprompting, plus de décisions cohérentes, moins de dérives de périmètre.

Le bon critère : si une règle vous a fait rerouter Claude plus d’une fois, elle mérite sa place. Sinon, elle reste dans votre tête ou dans une rule ciblée (couverte plus tard).

Prérequis

Projet fil rouge ~/Projets/lab-claude opérationnel (voir créer le projet fil rouge)
uv run ruff check . et uv run pytest -q verts sur votre machine
Session Claude Code CLI déjà testée

Les trois niveaux de CLAUDE.md

Claude Code lit plusieurs fichiers CLAUDE.md en cascade, du plus général au plus spécifique :

Niveau	Emplacement	Portée	Exemple d’usage
Global	`~/.claude/CLAUDE.md`	Tous vos projets	Préférences persistantes (style de résumés, langue, rappels génériques)
Projet	`<racine>/CLAUDE.md`	Le dépôt courant	Stack, commandes, conventions, garde-fous de `lab-claude`
Sous-dossier	`<racine>/app/CLAUDE.md`	Un sous-arbre	Règles spécifiques à un module (ex : `app/routes/` plus tard)

Règle pratique : mettez la règle au niveau le plus bas possible. Une convention qui ne s’applique qu’à app/routes/ n’a rien à faire dans le CLAUDE.md racine.

Les 4 sections minimales d’un bon CLAUDE.md

Pour un projet comme lab-claude, visez 4 sections brèves :

Stack et rôle : quelques lignes, pour situer le projet
Commandes utiles : lint, tests, serveur local
Conventions : ce qui doit être respecté sans le redire
Garde-fous : ce que Claude ne doit pas faire sans validation

Ce découpage suffit à 90 % des cas en phase débutant/intermédiaire.

Étape 1 : créer le fichier à la racine du dépôt

Placez-vous à la racine
Fenêtre de terminal
```
cd ~/Projets/lab-claude
```
Créez le fichier vide
Fenêtre de terminal
```
touch CLAUDE.md
```
Vérifiez qu’il est bien versionné (recommandé)
Fenêtre de terminal
```
git add CLAUDE.md
```

Étape 2 : renseigner les 4 sections

Collez ce modèle dans CLAUDE.md, puis ajustez à la marge.

# lab-claude — CLAUDE.md

## Stack et rôle
- Python 3.12+, FastAPI, uv, Ruff, pytest
- Projet pédagogique : rester petit, lisible, reproductible

## Commandes utiles
- Lint : `uv run ruff check .`
- Tests : `uv run pytest -q`
- Serveur local : `uv run uvicorn app.main:app --reload`

## Conventions
- Annotations de type obligatoires sur les fonctions publiques
- Tests via `fastapi.testclient.TestClient`
- Un endpoint = un fichier dans `app/routes/` quand le projet grossira
- Pas de dépendance ajoutée sans justification pédagogique

## Garde-fous
- Ne pas modifier `pyproject.toml` sans confirmation explicite
- Ne pas ajouter de nouveau dossier de premier niveau sans validation
- Toujours terminer par `uv run ruff check .` et `uv run pytest -q`
- Ne pas supprimer de tests existants sans raison explicite

Ce fichier tient en moins de 30 lignes actives, c’est le bon ordre de grandeur.

Étape 3 : vérifier que Claude le lit bien

Lancez une nouvelle session et testez avec un prompt qui force Claude à utiliser le fichier.

Démarrez Claude
Fenêtre de terminal
```
cd ~/Projets/lab-claude
claude
```

Posez cette question de contrôle

D'après CLAUDE.md, quelles sont les 2 commandes de validation à lancer
après chaque modification dans ce projet ?
Ne modifie aucun fichier.

Vérifiez la réponse

La réponse doit mentionner uv run ruff check . et uv run pytest -q. Si Claude hésite ou invente, relisez votre CLAUDE.md : il est probablement trop long ou mal structuré.

Étape 4 : tester l’effet sur un prompt réel

Un bon CLAUDE.md se voit quand vous n’avez plus besoin de redire les évidences.

Avant le fichier, votre prompt devait ressembler à :

Ajoute un endpoint /version qui renvoie la version FastAPI.
Utilise uv run ruff check . et uv run pytest -q pour valider.
Respecte les annotations de type et le style pytest du projet.
Ne modifie aucun autre fichier.

Après un bon CLAUDE.md, il suffit de :

Ajoute un endpoint /version qui renvoie la version FastAPI.
Ne modifie aucun autre fichier.

Claude reprend automatiquement les commandes et conventions du fichier.

Mutualiser avec des imports

Quand une règle est commune à plusieurs projets (par exemple votre style de commit, vos rappels de sécurité), CLAUDE.md peut importer un autre fichier Markdown avec la syntaxe @chemin/fichier.md.

Exemple dans ~/.claude/CLAUDE.md :

# Préférences globales

- Langue : répondre en français
- Résumés courts (5 points maximum)

@~/.claude/snippets/commits.md
@~/.claude/snippets/securite.md

Dans <racine>/CLAUDE.md, vous pouvez aussi importer un fichier local :

# lab-claude — CLAUDE.md

## Conventions partagées
@docs/conventions-python.md

## Garde-fous projet
- Ne pas modifier `pyproject.toml` sans confirmation

Bon réflexe : importer plutôt que copier. Un changement dans le fichier importé se propage partout, sans duplication.

Faire évoluer CLAUDE.md avec le projet

Un bon CLAUDE.md n’est pas figé : il grandit avec le projet, mais toujours de manière contrôlée.

Quand l’alimenter :

Après une session où vous avez dû recadrer deux fois la même règle
Quand une commande de validation change (ex : ajout de mypy)
Quand une nouvelle convention devient stable (ex : un dossier app/routes/)
Quand un garde-fou manquant a causé une dérive visible

Quand le nettoyer :

Quand un paragraphe n’a jamais servi depuis 2 semaines
Quand une règle est devenue évidente pour Claude (souvent grâce au code lui-même)
Quand vous dépassez ~80 lignes actives

Rythme recommandé : une relecture rapide toutes les 2 à 3 semaines, puis une coupe franche.

Anti-patterns à éviter

Les CLAUDE.md qui échouent se ressemblent tous. À éviter :

Le fichier encyclopédique : il raconte l’histoire du projet, les choix d’architecture passés, le contexte métier. Claude le survole.
Le fichier “doublon code” : il explique ce que le code dit déjà (ex : la liste exhaustive des endpoints). Gardez uniquement ce que le code ne peut pas dire.
Le fichier contradictoire : une règle projet qui s’oppose à la règle globale sans raison. Tranchez, puis supprimez l’autre.
Le fichier “tout est important” : aucune hiérarchie, aucun garde-fou clair. Forcez-vous à distinguer convention (préférence) et garde-fou (interdiction).
Le fichier figé : jamais relu après création. Planifiez une révision.

Comment savoir si votre CLAUDE.md est trop gros

Quelques signaux simples :

Il dépasse 120 lignes
Il contient des paragraphes qui expliquent le “pourquoi métier” plutôt que des règles actionnables
Vous n’êtes pas sûr de ce qu’il y a dedans sans le relire
Claude ignore plusieurs points lors d’une même session

Dans ces cas, coupez. Gardez les règles qui ont un effet visible.

Erreurs fréquentes

Symptôme	Cause probable	Correction
Claude ignore des conventions	Fichier trop long ou trop vague	Couper les paragraphes narratifs, ne garder que des règles
Les commandes sont réinventées	Syntaxe floue dans le fichier	Utiliser des listes à puces avec commandes exactes
Le fichier n’a aucun effet visible	Placé hors racine du dépôt	Déplacer à la racine, relancer une nouvelle session
Conflits entre CLAUDE.md projet et global	Règles contradictoires	Garder le projet comme référence et alléger le global

Checklist de fin de guide

CLAUDE.md présent à la racine de lab-claude
Moins de ~80 lignes actives
Stack, commandes, conventions, garde-fous clairement séparés
Test de contrôle passé (Claude cite les bonnes commandes)
Fichier commité dans Git

À retenir

Un CLAUDE.md utile est court et actionnable
Il sert à ne plus répéter ce qui est vrai tout le temps
Il ne remplace ni le plan, ni le diff, ni les tests
Une règle y entre seulement si elle vous a fait recadrer Claude au moins deux fois

Prochaines étapes

Mode plan, diff et validations disciplinées Installer un rituel : plan forcé, relecture diff, ruff + pytest systématique

Erreurs courantes et recadrage Reprendre le contrôle quand une session Claude Code dérive

Premier workflow réel CLI Revoir le workflow complet avant d'y appliquer CLAUDE.md