CLAUDE.md : le fichier que tout développeur devrait avoir dans ses projets

Il y a une raison pour laquelle Claude Code écrit du bon code dans certains projets et du boilerplate générique dans d'autres.

Ce n'est pas le modèle. C'est CLAUDE.md. C'est aussi la première raison pour laquelle je code environ 3x plus vite avec Claude Code — le fichier de conventions est ce qui supprime les allers-retours.

Ce que c'est

CLAUDE.md est un fichier markdown que Claude Code lit au début de chaque session. Pense-y comme le doc d'onboarding que tu donnerais à un prestataire senior le premier jour : stack, conventions, règles, contexte.

Sans ça, Claude infère les patterns depuis ce qu'il voit dans le codebase. Parfois il infère correctement. Souvent non — surtout pour les conventions implicites que ton équipe "sait juste".

Avec un bon CLAUDE.md, Claude produit du code qui suit tes règles sans avoir besoin de le répéter à chaque fois.

Quoi y mettre

1. Stack et versions

## Stack
- Next.js 16 (App Router), React 19
- TypeScript strict
- Tailwind 4 + Shadcn/ui
- next-safe-action pour les server actions

Simple mais important. Claude utilisera les bonnes APIs, les bons imports, et n'atteindra pas des patterns d'anciennes versions.

2. Vue d'ensemble de l'architecture

## Architecture
src/
├── app/          # Routes (App Router)
├── components/   # Primitives UI + layout
├── domain/       # Entités domaine + erreurs
├── lib/          # Utilitaires partagés
└── actions/      # Server actions next-safe-action

Ça dit à Claude où les choses vivent et où mettre les nouvelles.

3. Conventions fortes

Les règles qui ne sont pas évidentes à la lecture du code :

## Conventions
 
### Imports — bloc unique, pas de lignes vides entre imports
### Actions — toujours next-safe-action, jamais de fonctions async brutes
### Erreurs — les services throw DomainError, les actions ne retournent jamais { success: false }
### Logging — format ligne unique : log.info(`Message | key=${value}`)

Ce sont exactement les règles qu'un nouveau contributeur (humain ou IA) rate en premier. Mets-les ici.

4. Ce qu'on ne fait jamais

C'est la section la plus sous-estimée :

## Ne jamais faire
- Pas de console.log (utiliser logger)
- Pas de try/catch dans les actions
- Pas de retour { success: false, error } dans les actions ou services
- Pas de lignes vides entre les imports

Les prohibitions explicites sont plus efficaces que les conventions implicites. Claude les suit.

5. Exemples de code

Pour les patterns difficiles à décrire, montre-les :

## Pattern action (toujours utiliser celui-ci)
 
\`\`\`ts
export const myAction = authenticatedAction
  .schema(MySchema)
  .action(async ({ parsedInput, ctx }) => {
    return await myService.doThing(ctx.userId, parsedInput);
  });
\`\`\`

Les exemples surpassent les règles. Si tu as une façon canonique d'écrire quelque chose, montre-la.

Où le mettre

• /CLAUDE.md — racine du projet, commité dans git
• ~/.claude/CLAUDE.md — global, s'applique à tous les projets (pour tes standards cross-projet personnels)

Tu peux aussi utiliser @path/to/file.md dans CLAUDE.md pour inclure d'autres fichiers. Pratique pour séparer de gros ensembles de règles.

Reste honnête

Le pire CLAUDE.md est celui qui décrit comment le codebase devrait être, pas comment il est. Claude suivra les instructions et générera du code incohérent avec les patterns existants.

Écris-le en lisant le vrai code, pas ton état idéal. Mets-le à jour quand les conventions changent.

Le retour sur investissement cumulé

Le premier CLAUDE.md prend une heure à écrire. Après ça, chaque session IA assistée dans ce projet coûte moins d'overhead de contexte. Tu arrêtes de ré-expliquer les choses. La revue de code va plus vite parce que le code généré suit déjà tes règles.

C'est le fichier à plus fort levier que tu peux ajouter à un projet en ce moment.

Le CLAUDE.md Starter Kit te donne un template prêt à l'emploi pour les projets Next.js + TypeScript. Adapte-le à ta stack en 10 minutes.