Claude Code : maitriser CLAUDE.md et les rules

La difference entre un developpeur qui trouve Claude Code "moyen" et un qui le trouve "indispensable" tient souvent a un seul fichier : le CLAUDE.md. Sans lui, Claude Code genere du code generique. Avec un bon CLAUDE.md, il respecte vos conventions, connait votre architecture, et produit du code que vous n'avez presque pas besoin de retoucher.

Ce guide vous montre comment creer un CLAUDE.md efficace et utiliser le systeme de regles modulaires.

La hierarchie des fichiers de configuration

Claude Code lit les instructions a plusieurs niveaux, du plus global au plus specifique :

~/.claude/settings.json : configuration globale (serveurs MCP, preferences)
CLAUDE.md a la racine du projet : regles du projet, charge a chaque session
CLAUDE.md dans les sous-dossiers : regles specifiques a un module
*.claude/rules/.md : regles modulaires activees par chemin

Chaque niveau herite du precedent et peut le completer ou le surcharger.

Anatomie d'un bon CLAUDE.md

Un CLAUDE.md efficace couvre quatre domaines :

1. La stack technique

## Stack technique

Soyez precis sur les versions. Claude Code ajustera son code aux API disponibles dans votre version.

2. Les conventions de code

## Conventions

Plus vous etes explicite, moins vous aurez de retouches a faire.

3. L'architecture

## Architecture
Le projet suit une architecture en couches :
src/app/ : routes Next.js (App Router)
src/components/ : composants React reutilisables
src/lib/ : logique metier et services
src/db/ : schema Prisma et queries
src/types/ : types TypeScript partages

Regles d'architecture

4. Les patterns a suivre et a eviter

## Patterns
A suivre
Gestion d'erreurs : utiliser le pattern Result<T, E> pour les operations faillibles
Validation : Zod a l'entree de chaque endpoint
Logging : utiliser le logger structure (src/lib/logger.ts)

A eviter

Les regles modulaires (.claude/rules/)

Pour les projets complexes, un seul fichier CLAUDE.md peut devenir encombrant. Les regles modulaires resolvent ce probleme.

Structure

.claude/
rules/
api.md           # Regles pour tout fichier dans src/app/api/
components.md    # Regles pour les composants React
database.md      # Regles pour les fichiers Prisma/DB

Exemple : regles pour les composants

---

path: src/components/

# Regles composants React

Chaque composant a son propre dossier : ComponentName/index.tsx
Props definies dans une interface nommee ComponentNameProps
Pas de logique metier dans les composants
Tests obligatoires dans ComponentName/ComponentName.test.tsx
Storybook story dans ComponentName/ComponentName.stories.tsx

Le champ path dans le frontmatter indique quand la regle s'active. Claude Code la charge uniquement quand il travaille sur des fichiers qui matchent le pattern.

Exemple : regles pour les tests

---
path: */.test.ts, */.test.tsx, */.spec.ts

# Regles de tests

Exemples concrets par stack

CLAUDE.md pour un projet Spring Boot

# Projet API Spring Boot
Stack
Java 25 + Spring Boot 3.4
PostgreSQL 17 + Spring Data JPA
MapStruct pour le mapping DTO
Tests : JUnit 5 + Testcontainers + MockMvc

Conventions
Package par feature, pas par couche technique
  com.app.order/ (pas com.app.controller/, com.app.service/)
Records pour les DTOs
Optional<T> en retour de repository, jamais null
Validation par annotations Jakarta (@NotBlank, @Email)

Architecture

CLAUDE.md pour un projet Python FastAPI

# Projet FastAPI
Stack
Python 3.13 + FastAPI 0.115
SQLAlchemy 2.0 + Alembic
Pydantic v2 pour la validation
Tests : pytest + httpx

Conventions
Type hints obligatoires partout
Docstrings Google style pour les fonctions publiques
Async par defaut pour les endpoints
Pas de logique dans les routes (passer par des services)

Structure

Erreurs frequentes a eviter

Trop vague : "Ecris du bon code" n'aide pas Claude Code. Soyez precis et concret. Trop long : un CLAUDE.md de 500 lignes noie l'information. Visez 50-100 lignes pour le fichier principal et externalisez le reste dans des rules modulaires. Pas maintenu : un CLAUDE.md qui decrit une architecture d'il y a 6 mois est pire que pas de CLAUDE.md. Mettez-le a jour quand l'architecture evolue. Contradictoire : si le CLAUDE.md dit "pas de default export" mais que 80% de votre codebase en a, Claude Code sera confus. Alignez les regles avec la realite du projet.

Mesurer l'impact

Avant et apres l'ajout d'un bon CLAUDE.md, mesurez :

Le nombre de retouches manuelles apres generation
Le respect des conventions dans les code reviews
Le temps passe a reformuler vos demandes

En general, un CLAUDE.md bien configure reduit les retouches de 60 a 80% et divise par deux le nombre d'iterations necessaires pour obtenir du code correct.