Cours Vibe coding avec Claude Code · Module 2: Un projet Next.js avec Claude Code

La mémoire du projet : AGENTS.md, CLAUDE.md et /init

10 min de lecture ·
Dans cette leçon12

Ohé ! La carte repose dans SPEC.md. Avant que l'équipage ne parte à la construction, tu vas accrocher dans la cabine le règlement du navire : un fichier de règles que Claude Code lira au début de chaque session, même dans un mois.

Problème : chaque session repart de zéro

Après /clear, ou demain matin, dans une nouvelle session, Claude ne se souvient pas de la conversation. Il ne sait pas que tu as désactivé Cache Components en connaissance de cause dans la leçon 1_2, que tu veux voir le résultat de npm run build après chaque changement, et que tu gardes le serveur de développement dans un terminal à part. Tu l'expliques de nouveau ou, pire, tu l'oublies. Alors Claude peut faire quelque chose de raisonnable de son point de vue, par exemple activer Cache Components, parce que l'assistant les propose dans les réglages recommandés. Le code, il le voit, mais ta décision, non.

Pour cela existe la mémoire du projet : des fichiers d'instructions que Claude Code charge au début de chaque conversation. Tu les écris en texte ordinaire, et tu les gardes dans le dépôt avec le code.

Ce que tu as déjà : AGENTS.md

L'assistant de la leçon 1_2 a laissé dans le projet un fichier AGENTS.md avec des instructions pour les agents de code. Ouvre-le dans Cursor. Tout son contenu tient entre deux marqueurs :

<!-- BEGIN:nextjs-agent-rules -->
## This is NOT the Next.js you know
(avertissement et indication de l'endroit où chercher la documentation)
<!-- END:nextjs-agent-rules -->

<!-- et --> ouvrent et ferment un commentaire qu'on ne voit pas quand le fichier est affiché, et ces deux marqueurs désignent le fragment qui appartient à Next.js. À l'intérieur se trouve l'avertissement que cette version de Next.js peut différer de ce que le modèle a appris auparavant, et la consigne de lire, avant d'écrire du code, le guide du dossier node_modules/next/dist/docs/. La documentation de Next.js explique que ce dossier contient la documentation adaptée à la version installée, et que next dev recrée le bloc en ne changeant que le texte entre les marqueurs, en laissant le reste du fichier tranquille.

Claude Code lit AGENTS.md comme instructions du projet quand il n'y a pas de fichier CLAUDE.md ni CLAUDE.local.md dans le dossier de travail et dans les dossiers au-dessus. Au début de la session, tu verras alors une ligne semblable à celle-ci :

no CLAUDE.md found; AGENTS.md loaded: .../krakens-call/AGENTS.md

C'est la preuve que l'avertissement de Next.js arrive dans chaque conversation. Il y a aussi un piège : dès qu'un CLAUDE.md apparaît dans le projet, Claude cesse de lire AGENTS.md de lui-même.

Import : une ligne avec @

La solution, c'est l'import. Une ligne avec @ et un chemin dans le fichier CLAUDE.md charge le fichier indiqué avec lui, et un fichier importé peut en importer d'autres, jusqu'à quatre niveaux de profondeur. Ici, une seule ligne suffit :

@AGENTS.md

Place-la tout en haut de CLAUDE.md. Claude lira alors d'abord le fichier importé, puis tes règles, et il n'y a rien à copier. AGENTS.md lui-même ne change pas, donc Next.js peut continuer à rafraîchir son bloc.

/init : un premier brouillon

La commande /init génère un CLAUDE.md de départ : Claude analyse le projet et écrit les commandes de build, de tests et les conventions qu'il a trouvées. Quand CLAUDE.md existe déjà, /init ne l'écrase pas, il propose seulement des corrections. Tape dans la session, dans le dossier krakens-call :

/init

Claude demandera l'accord pour écrire CLAUDE.md. Les bonnes pratiques de Claude Code disent clairement que la suite du travail consiste surtout à supprimer des lignes. Lis le fichier dans Cursor et marque mentalement tout ce que Claude trouverait seul dans le dépôt : la liste des dossiers, la description de l'App Router, les versions des paquets de package.json.

Demande : garde ce qu'on ne voit pas dans le code

Tu raccourciras le brouillon avec une seule demande. Dis-y ce qui doit rester, ce qui doit partir et ce que Claude ne trouvera dans aucun fichier :

Demande pour Claude Code :

Raccourcis @CLAUDE.md en trois parties : commandes de vérification,
pièges et décisions. Tout en haut, ajoute la ligne d'import
@AGENTS.md. Supprime la description des dossiers et de
l'architecture, car tu la liras dans le dépôt. Écris des phrases
ordinaires, sans mots en majuscules. Dans les pièges, ajoute que
Cache Components est désactivé volontairement, et dans les
décisions, que le serveur npm run dev, je le lance moi-même dans un
terminal à part.

La demande dit ce qui reste, ce qui part et pourquoi. Les deux dernières informations sont un savoir qui n'est pas dans le code : l'absence de la ligne cacheComponents dans next.config.ts ne dit pas que c'est une décision et non un oubli.

Ce que Claude a écrit : un CLAUDE.md court

Ouvre CLAUDE.md dans Cursor. Le tien aura d'autres mots, mais une forme semblable. En haut se trouvent l'import et les commandes :

@AGENTS.md

# Commandes de vérification
- Types : npx tsc --noEmit
- Lint : npm run lint
- Build : npm run build, après chaque étape du plan

Ce ne sont que des commandes, sans phrases du genre « vérifie toujours les types ». La documentation explique que Claude a besoin de commandes pour vérifier lui-même son travail en cours de route. Cette partie n'impose rien : elle donne les outils, et la preuve, tu continues de la demander dans la demande.

Sous les commandes se trouvent les pièges et les décisions, c'est-à-dire un savoir que Claude ne lira pas dans les fichiers du projet :

# Pièges
- Cache Components est désactivé volontairement (il n'y a pas de cacheComponents dans next.config.ts). Ne l'active pas.
- Tailwind 4 : la configuration est dans app/globals.css, sans fichier tailwind.config.js.
- Corrige les erreurs de types à la source, sans any ni @ts-ignore.

# Décisions
- Le serveur npm run dev, je le lance moi-même dans un terminal à part, tu ne le lances pas.
- Le plan de la page d'accueil est dans le fichier SPEC.md.

Chaque ligne est quelque chose qu'on ne voit pas dans le code, ou quelque chose que tu as déjà corrigé dans ce lieu : la syntaxe de Tailwind 3 de la leçon 1_3 et le silence imposé aux types de la leçon 1_4. SPEC.md apparaît ici sans @, donc c'est une mention et non un import : le plan n'est pas chargé dans chaque conversation, et Claude l'ouvrira quand il en aura besoin.

Ce qu'il ne faut pas y mettre

Les bonnes pratiques de Claude Code citent des choses qui, aujourd'hui, ne font que gêner :

  • la description de l'architecture et de la disposition des fichiers : Claude lit le dépôt lui-même ;
  • les MAJUSCULES et le mot IMPORTANT : les modèles actuels exécutent une phrase ordinaire, et un excès d'insistance fait appliquer la règle avec exagération ; si une ligne se perd, le fichier est trop long ;
  • tout « au cas où » : chaque ligne retire un peu d'attention à Claude à chaque tâche, qu'elle soit utile ou non.

La documentation de la mémoire recommande aussi une longueur : moins de 200 lignes par fichier. Conseil du capitaine : aucun mot de passe ni aucune clé, car CLAUDE.md part dans le dépôt avec le code.

Une prière, pas une loi

CLAUDE.md est lu par le modèle, qui décide lui-même de ce qu'il en fait. La documentation appelle ces instructions du contexte, et non une configuration imposée : Claude les suit presque toujours, mais sans garantie. Une règle qui ne doit souffrir aucune exception est appliquée par le programme Claude Code lui-même, par exemple avec un hook, c'est-à-dire un script lancé automatiquement à un événement choisi. Tu découvriras les hooks dans les lieux suivants. Pour l'instant, retiens le partage : CLAUDE.md pour les indications, un hook pour la loi sans exception.

Des notes rien que pour toi

Les remarques que tu ne veux pas dans le dépôt, par exemple « explique-moi chaque commande Git avant de la lancer », écris-les dans le fichier CLAUDE.local.md à la racine du projet. Claude le lit juste après CLAUDE.md. Ce fichier ne doit pas arriver dans Git, et le .gitignore de l'assistant ne le connaît pas, donc demande à Claude d'y ajouter une ligne :

CLAUDE.local.md

Dès lors, Git ignore tes notes, et tu ne verras pas ce fichier dans Source Control. Attention : CLAUDE.local.md désactive lui aussi la lecture autonome de AGENTS.md, mais chez nous l'import en haut de CLAUDE.md règle cela.

Deux outils pour finir. Quand tu dis « souviens-toi que... », Claude l'écrit dans l'auto memory, c'est-à-dire dans ses propres notes sur ton ordinateur, en dehors du projet. Pour que quelque chose arrive dans CLAUDE.md, dis-le explicitement : « ajoute cela à CLAUDE.md ». La commande /memory montre la liste des fichiers de mémoire, ouvre celui que tu choisis dans l'éditeur et active ou désactive l'auto memory.

Vérification : une nouvelle session

La mémoire se vérifie dans une conversation qui n'a pas entendu la précédente. Quitte la session avec la commande /exit et relance claude, car les fichiers de mémoire se chargent au début de la session. Puis demande :

Avec quelles commandes vérifieras-tu ce projet après un changement,
et que n'as-tu pas le droit de modifier dans next.config.ts ?

Une bonne réponse cite les trois commandes de CLAUDE.md et Cache Components. Si Claude devine, lance /context all et regarde la liste Memory files : CLAUDE.md doit y figurer. L'absence du fichier dans la liste signifie que Claude ne le voit pas.

La revue du capitaine

Avant de faire un commit, vérifie dans Source Control :

  1. L'import : la première ligne de CLAUDE.md est @AGENTS.md.
  2. La longueur : une quinzaine de lignes, loin de 200.
  3. Le test du code : pour chaque ligne, tu te demandes si Claude la trouverait dans le dépôt ; si oui, la ligne part.
  4. Secrets et lest : dans le diff, il n'y a ni clés ni CLAUDE.local.md, et .gitignore a une nouvelle ligne.

Erreur typique de l'agent dans cette tâche : en raccourcissant, il garde la description des dossiers « pour l'ordre » ou ajoute des règles en majuscules. Tu l'attraperas dans le diff, avant d'approuver le changement.

Étape suivante

Demande un commit de CLAUDE.md et de .gitignore avec une description du genre « CLAUDE.md : commandes de vérification et pièges du projet ». Le fichier grandira lentement : la documentation conseille d'ajouter une ligne quand Claude commet pour la deuxième fois la même erreur. Dans la leçon suivante, tu construiras la landing page d'après le plan, et dans l'éditeur ci-dessous tu verras un exemple de CLAUDE.md, de CLAUDE.local.md et un extrait de .gitignore.

Retiens : CLAUDE.md est le règlement du navire, que chaque nouvel équipage lit avant d'appareiller.

Code de cette leçon : CLAUDE.md
@AGENTS.md

# Commandes de vérification
- Types : npx tsc --noEmit
- Lint : npm run lint
- Build : npm run build, après chaque étape du plan

# Pièges
- Cache Components est désactivé volontairement (il n'y a pas de cacheComponents dans next.config.ts). Ne l'active pas.
- Tailwind 4 : la configuration est dans app/globals.css, sans fichier tailwind.config.js.
- Corrige les erreurs de types à la source, sans any ni @ts-ignore.

# Décisions
- Le serveur npm run dev, je le lance moi-même dans un terminal à part, tu ne le lances pas.
- Le plan de la page d'accueil est dans le fichier SPEC.md.

Tu as repéré une erreur dans cette leçon ?

Teste tes connaissances

Réponds aux questions de cette leçon. Choisis une réponse pour voir tout de suite si elle est correcte.

  1. 1. Le projet contient AGENTS.md de l'assistant, mais ni CLAUDE.md ni CLAUDE.local.md. Que chargera Claude Code au début de la session ?

  2. 2. Que vaut-il le plus la peine de mettre dans le CLAUDE.md du projet Kraken's Call ?

  3. 3. Où écris-tu tes propres instructions pour le projet, que tu ne veux pas envoyer dans le dépôt ?

Tâches pratiques dans le jeu

  • Tri vertical

    Ordonne les étapes de la mise en place de la mémoire du projet dans Kraken's Call :

  1. QuestionQuiz : AGENTS.md sans CLAUDE.md
  2. QuestionQuiz : que mettre dans CLAUDE.md
  3. Remets dans l'ordreOrdre : la mémoire du projet pas à pas
  4. QuestionQuiz : des notes hors du dépôt

Articles utiles