← mobang.fr

· Vibecoding

CLAUDE.md, mode d'emploi : transforme ton IA en équipier fiable

CLAUDE.md est un fichier texte que tu places à la racine de ton projet et que ton assistant IA lit automatiquement au début de chaque session. Il contient les règles du projet : la stack avec ses versions exactes, les commandes pour lancer et tester, les conventions de code, les pièges connus et ta définition de « fini ». Résultat : l'IA arrive briefée au lieu de repartir de zéro à chaque conversation.

C'est la réponse à un problème que tout le monde rencontre en codant avec l'IA : tu réexpliques ton projet à chaque session, et malgré ça l'assistant viole tes conventions, met à jour une lib que tu avais verrouillée ou touche à un dossier sensible. Le fichier de règles agit comme une mémoire de travail permanente.

La règle d'or tient en quatre mots : court et dense. Chaque ligne consomme du budget de contexte à chaque échange. Un fichier d'une page bien choisie bat dix pages exhaustives.

Ce guide te montre quoi mettre dedans, quoi laisser dehors, et te donne un exemple complet prêt à copier. CLAUDE.md, AGENTS.md, règles Cursor : les noms changent selon l'outil, les principes restent les mêmes.

Le problème : ton IA oublie tout entre deux sessions

Par défaut, un assistant IA ne garde aucun souvenir d'une conversation à l'autre. À chaque nouvelle session, il redécouvre ton projet comme un stagiaire qui arriverait chaque matin sans aucune mémoire de la veille.

Les symptômes, tu les connais sans doute déjà :

  • tu retapes la même explication de ta stack à chaque session ;
  • l'IA propose une bibliothèque que tu as écartée il y a trois semaines ;
  • elle écrit du code dans un style différent du reste du projet ;
  • elle « répare » des choses qui marchaient très bien.

Ce n'est pas un bug : le modèle ne voit que ce qui est dans son contexte. Le fichier de règles traite le problème à la source, en injectant ton brief au démarrage de chaque session, automatiquement.

Quoi mettre dedans : cinq blocs qui changent tout

Un bon fichier de règles couvre cinq sujets, et rien d'autre.

1. La stack et les versions exactes. Pas « du React », mais « Next.js 15, TypeScript strict, Tailwind 4 ». Sans version, l'IA pioche dans ses souvenirs d'entraînement et peut te sortir une syntaxe d'une version différente de la tienne.

2. Les commandes. Comment lancer le projet, lancer les tests, builder. L'IA peut alors vérifier son propre travail au lieu de te livrer du code non testé.

3. Les conventions du projet. Où vont les composants, comment tu nommes les fichiers, la langue des textes visibles. Tout ce qu'un nouveau développeur devrait savoir pour que son code ressemble au tien.

4. Les pièges connus. Les lignes les plus rentables du fichier : « ne touche jamais aux migrations à la main », « la lib Stripe est verrouillée en 14.x, ne pas mettre à jour ». Chaque piège documenté est une erreur que l'IA ne refera plus.

5. La définition de « fini ». Tests qui passent, lint OK, build qui compile. Sans ce bloc, l'IA considère qu'un code qui a l'air correct est terminé. Avec, elle sait ce qu'elle doit prouver avant de te rendre la main.

La règle d'or : court et dense

Ton fichier de règles est rechargé dans le contexte à chaque échange. Chaque ligne a donc un coût permanent : elle occupe de la place que le modèle ne peut plus consacrer à ton code. C'est le même mécanisme que celui décrit dans pourquoi l'IA perd le fil : plus le contexte se remplit, plus l'attention du modèle se dilue.

Concrètement :

  • vise une page maximum — quinze à vingt lignes, c'est déjà très bien ;
  • pas de documentation générale, pas d'historique du projet, pas de tutoriels ;
  • une règle par ligne, formulée comme un ordre : « fais X », « ne touche jamais à Y » ;
  • si une ligne n'a jamais évité une erreur, supprime-la.

En 2026, ce pattern est devenu un standard de fait de l'industrie. La communauté des développeurs qui codent avec l'IA le résume par la formule « structured skills > heroic prompting » : des règles structurées et permanentes battent les prompts héroïques réécrits à chaque session.

Exemple complet : un CLAUDE.md minimal pour un projet web

Voici un fichier complet pour un projet web type. Copie-le, adapte chaque ligne à ton projet, supprime ce qui ne s'applique pas.

# Boutique en ligne — règles projet

## Stack
- Next.js 15 (App Router), TypeScript strict
- Tailwind CSS 4, Prisma + PostgreSQL

## Commandes
- Dev : `npm run dev`
- Tests : `npm test` (Vitest)
- Build : `npm run build`

## Conventions
- Composants dans `src/components/`, un fichier par composant
- Interdit : `any` — utilise un type explicite ou `unknown`
- Textes visibles en français, centralisés dans `src/locales/fr.json`

## Pièges connus
- Ne modifie jamais `prisma/migrations/` à la main
- `stripe` est verrouillé en 14.x : ne pas mettre à jour

## Définition de « fini »
- `npm test` et `npm run lint` passent, le build compile

Une vingtaine de lignes utiles. Chacune évite une catégorie d'erreurs précise. C'est exactement la densité qu'on vise.

CLAUDE.md, AGENTS.md, règles Cursor : même famille

Le nom du fichier dépend de ton outil, pas le principe :

  • CLAUDE.md : lu par Claude Code à la racine du projet ;
  • AGENTS.md : le même rôle, adopté par plusieurs autres outils ;
  • règles Cursor : le même contenu, dans le format de règles de Cursor.

La bonne nouvelle : le contenu est portable. Rédige tes règles une fois, en markdown simple, et décline-les selon l'outil. Si tu changes d'assistant demain, ton investissement te suit. Certains gardent même un seul fichier source et créent les autres comme de simples copies ou liens.

Dernier point : commite ce fichier dans git. Il fait partie du projet au même titre que le README, et toute personne — humaine ou IA — qui rejoint le projet en profite.

Par où commencer aujourd'hui

Trente minutes suffisent pour une première version.

  1. Crée le fichier à la racine de ton projet (CLAUDE.md ou l'équivalent de ton outil).
  2. Remplis les cinq blocs : stack et versions, commandes, conventions, pièges connus, définition de « fini ». Quinze à vingt lignes, pas plus.
  3. Pars de tes irritants réels : les trois dernières fois où l'IA t'a agacé, quelle règle l'aurait évité ? Écris-la.
  4. Teste immédiatement : ouvre une nouvelle session et donne une petite tâche. Si l'IA respecte tes conventions sans que tu les rappelles, c'est gagné.
  5. Entretiens le fichier : chaque nouvelle erreur récurrente devient une ligne ; chaque ligne devenue inutile saute. Une relecture par mois suffit.

Le fichier parfait n'existe pas, et ce n'est pas le but. Un fichier imparfait d'une page, maintenu vivant, transforme déjà ton assistant en équipier qui connaît le projet. Tout ce que tu réexpliquais à la main jusqu'ici — écrit une fois, pour de bon.