Marre du code au hasard de Claude ? Un CLAUDE.md pour gagner 5-10 % de précision

Quand vous modifiez un projet existant avec Claude Code, il confond parfois le stack : du Vue dans un projet React, du JavaScript alors que la doc impose TypeScript. CLAUDE.md, à la racine du projet, corrige ce décalage de contexte.

Sur un backend Node, j’ai déjà eu la surprise : Claude a réécrit du middleware Koa en style Express — toute la chaîne était cassée. Dans les tests Anthropic, un CLAUDE.md bien rédigé améliore en général la précision du code de 5 à 10 %. Voici 7 façons d’écrire ce fichier, chacune avec des exemples copiables.

Qu’est-ce que CLAUDE.md

En clair : CLAUDE.md est un fichier Markdown à la racine qui aide Claude Code à comprendre votre projet — comme .editorconfig ou README.md, mais orienté IA.

Mécanisme : dans le projet, Claude Code lit ce fichier. La doc parle de chargement automatique ; en pratique, /init garantit que la config est bien « assimilée ». Le contenu entre dans le contexte et influence toutes les suggestions suivantes.

Claude Code supporte une configuration hiérarchique :

project-root/
├── CLAUDE.md              # global (tout le projet)
├── frontend/
│   └── .claude/
│       └── CLAUDE.md     # spécifique frontend
└── backend/
    └── .claude/
        └── CLAUDE.md     # spécifique backend

Règles communes à la racine, surcharge dans les sous-modules — React côté front, Node côté back.

Quatre principes fondamentaux

Avant d’écrire : ces quatre règles. Sans elles, j’ai déjà produit 300+ lignes d’« épopée » — Claude s’est dégradé.

1. Concision : la règle des 100 lignes

CLAUDE.md n’est pas un README. Les longs discours n’aident pas l’IA ici.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Pourquoi rester court ? Le fichier consomme des tokens. Plus il est long, moins il reste de place pour analyser le code. Arize AI recommande des configs sous 100 lignes.

❌ Mauvais (répétitif et verbeux) :

# Introduction
Projet frontend React. Nous utilisons React pour l'interface.
React est une bibliothèque JavaScript développée par Facebook… (200 lignes sur React)
# Stack
Notre stack comprend :
- React – framework UI, version 18.2…
- TypeScript – pour le typage…

✅ Bon (direct et actionnable) :

# Stack
- React 18.2 (Hooks en priorité, pas de class components)
- TypeScript (mode strict)
- TailwindCSS (utilities-first)
# Style
- Composants fonctionnels + hooks personnalisés
- Destructuration des props
- const de préférence, éviter let

Le second bloc dit plus en moins de lignes.

2. Spécificité : exécutable, pas vague

❌ Mauvais :

# Style
- Garder le code propre
- Suivre les bonnes pratiques
- Optimiser les performances

Impossible à vérifier.

✅ Bon :

# Style
- Fonctions max. 50 lignes, sinon découper
- Appels API avec gestion d'erreur et état loading
- Listes avec key, ID plutôt qu'index
- Pas de ternaires imbriqués — if/else ou early return

3. Itération : la config vit avec le projet

Écrire une fois puis oublier six mois — classique. Le projet passe à Vue 3, la config parle encore d’Options API.

Mise à jour rapide avec # : dans Claude Code, # ouvre CLAUDE.md. Comportement inattendu ? Ajoutez une ligne tout de suite.

Exemple : Claude générait axios, l’équipe utilisait fetch + wrapper. Une ligne :

# HTTP
- Utiliser uniquement `src/utils/request.ts` (wrapper fetch)
- Interdit : axios ou fetch brut

Plus d’erreur ensuite.

🔥 Ne perdez plus des mois sur des produits sans demande ! Validez vos promesses SaaS avec Adsterra à petit budget →

Tester l'MVP →Pub

4. Équipe : contrôle de version

CLAUDE.md va dans Git — au même titre que .gitignore.

C’est le consensus d’équipe. Des versions locales différentes → des styles IA différents par développeur.

# Ne pas ignorer CLAUDE.md dans .gitignore
# ❌ faux
*.md
# ✅ correct
*.md
!CLAUDE.md
!README.md

Revoyez les changements de CLAUDE.md en code review.

"Config courte et concrète — idéalement sous 100 lignes. Chaque règle doit être exécutable et vérifiable."

Cinq modules indispensables

Sans ces blocs, CLAUDE.md apporte peu.

1. Déclaration du stack

Frameworks, bibliothèques, versions — obligatoire.

# Stack
**Frontend**
- Next.js 14 (App Router)
- React 18 (Server Components en priorité)
- TypeScript 5.2
- Tailwind CSS 3.4
**Backend**
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15

Sans version, Claude risque des API obsolètes (Next.js 13 vs 14).

2. Structure du projet

# Structure
src/
├── app/              # routes Next.js
├── components/
│   ├── ui/          # base (Button, Input)
│   └── features/    # métier (UserCard, OrderList)
├── lib/
├── services/        # couche API
└── types/
# Nommage
- Composants : PascalCase (UserProfile.tsx)
- Utilitaires : camelCase (formatDate.ts)
- Constantes : UPPER_SNAKE_CASE (API_BASE_URL)

3. Commandes courantes

# Commandes dev
npm run dev          # serveur dev (localhost:3000)
npm run build
npm run test
npm run lint
npm run type-check
# Base de données
npx prisma studio
npx prisma migrate dev

4. Style de code

# Règles de code
## React
- Composants fonctionnels + Hooks, pas de class components
- Types des props en interface au-dessus du composant
- Ordre : props → composant → export
## État
- local : useState/useReducer
- serveur : TanStack Query
- global : Zustand (éviter Context)
## Erreurs
- API : try-catch
- utilisateur : toast
- dev : console.error, prod : Sentry

5. Workflow et limites

# Workflow
- Feature : types → composant → tests
- Bug : test de repro → correctif → tests verts
# Limites
- ❌ ne pas modifier `/prisma/schema.prisma` (revue équipe)
- ❌ pas de nouvelles dépendances sans accord
- ❌ ne pas toucher `/lib/auth/*`
- ✅ libre sur `/components` et `/app` (code métier)

Sept astuces à fort impact

Astuce 1 : SHOULD/MUST pour la priorité

# Priorités
**MUST**
- MUST TypeScript strict
- MUST gestion d'erreur sur les API
**SHOULD**
- SHOULD composants < 200 lignes
- SHOULD logique répétée en hook custom
**COULD**
- COULD commentaires JSDoc

Astuce 2 : utiliser /init

Après modification de la config, lancez /init — comme un rafraîchissement du contexte.

Vous : /init
Claude : Config projet chargée, stack : React 18 + TypeScript…

Astuce 3 : l’exemple vaut mieux que le discours

❌ Texte seul : « API avec types, erreurs, loading »

✅ Avec modèle :

# Modèle API
Référence :
\`\`\`typescript
// src/services/user.ts
export async function getUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('getUser error:', error);
    throw error;
  }
}
\`\`\`
Toutes les fonctions API : retour typé, try-catch, log

Astuce 4 : couches en Monorepo

monorepo-root/
├── CLAUDE.md
├── apps/
│   ├── web/.claude/CLAUDE.md
│   └── mobile/.claude/CLAUDE.md
└── packages/shared/.claude/CLAUDE.md

Racine : pnpm, tsconfig, Conventional Commits. apps/web : Next.js + Tailwind + Zustand.

KiloClaw - OpenClaw managé pour l’entreprise : orchestration d’agents IA et routage intelligent

Commencer →Pub

Astuce 5 : comparer ❌ et ✅

# Mises à jour d'état
❌ mutation directe du state
✅ immuable : setUser(prev => ({...prev, age: 31}))

Astuce 6 : documenter les erreurs fréquentes

# ⚠️ Erreurs courantes
## 1. useEffect sans cleanup
❌ :
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
}, []);
\`\`\`
✅ :
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  return () => clearInterval(timer);
}, []);
\`\`\`
## 2. dépendances manquantes
Ne pas désactiver aveuglément ESLint — ajouter les deps ou useCallback/useMemo

Astuce 7 : liens vers la doc détaillée

# Documentation détaillée
- [Guide API](./docs/api-guidelines.md)
- [Guide composants](./docs/component-guide.md)
- [Tests](./docs/testing.md)

Cinq pièges fréquents

1. Trop long — README + doc API dans le même fichier → perte de tokens. Solution : 100 lignes, uniquement l’utile au codage.
2. Jamais mis à jour — Solution : revoir après chaque refonte majeure.
3. Pas versionné — Solution : Git, ne pas ignorer.
4. Règles vagues — « bonnes pratiques » ne s’exécute pas. Solution : phrases vérifiables.
5. Secrets — pas de clés dans CLAUDE.md.

❌ faux
DATABASE_URL=postgresql://admin:password123@localhost:5432/mydb
✅ correct
- DATABASE_URL : depuis .env.local, format dans .env.example
- API_KEY : variable d'environnement, clé de test auprès de l'équipe

Trois cas réels

Cas 1 : frontend React (e-commerce)

# Frontend e-commerce
## Stack
- Next.js 14.0 (App Router)
- React 18.2, TypeScript 5.2, Tailwind 3.4
- Zustand, TanStack Query
## Structure
src/app, src/components/ui|features, lib, services
## Règles
- Composants fonctionnels + Hooks
- API : try-catch
## Commandes
npm run dev | build | lint
## Limites
- ne pas modifier /lib/auth/*
- pas de nouveaux paquets sans l'équipe

Effet : structure des composants proche du code manuel.

Cas 2 : API Node.js

# API gestion des commandes
## Stack
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15
- Zod (validation)
## Structure
src/routes, controllers, services, middleware, utils
## Règles
- Chaque API : validation Zod + erreurs + logs
- DB uniquement dans services
- Controllers : requête/réponse seulement
- async/await, pas de callbacks
## Exemple API
\`\`\`typescript
export async function createOrder(req: Request, res: Response) {
  try {
    const data = orderSchema.parse(req.body);
    const order = await orderService.create(data);
    logger.info('Order created', { orderId: order.id });
    res.json({ success: true, data: order });
  } catch (error) {
    logger.error('Create order failed', error);
    res.status(500).json({ success: false, error: 'Internal error' });
  }
}
\`\`\`
## Commandes
npm run dev | build | test
npx prisma studio

Effet : nouveaux endpoints avec validation Zod et gestion d’erreur.

Cas 3 : Monorepo

Racine CLAUDE.md :

# Monorepo full-stack
## Architecture
- pnpm workspaces
- apps/ : applications
- packages/ : paquets partagés
## Règles communes
- TypeScript strict
- ESLint + Prettier
- Commits : Conventional Commits
## Commandes
pnpm install
pnpm run dev
pnpm run lint
pnpm --filter web dev

apps/web/.claude/CLAUDE.md : Next.js 14 + React, port 3000.

apps/api/.claude/CLAUDE.md : Express + Prisma, port 4000.

Effet : Claude adapte React ou Express selon le répertoire courant.

Conclusion

Trois rappels : court (≤100 lignes), concret (vérifiable), à jour (évolue avec le projet).

Un bon CLAUDE.md peut sensiblement booster la productivité IA — commencez par le stack, ajoutez une ligne à chaque erreur récurrente. Après chaque grosse évolution technique, mettez le fichier à jour : ce n’est pas un one-shot, c’est l’ADN du projet pour l’IA.