Ajouter du contexte

Votre projet contient des dizaines ou des centaines de fichiers, mais Claude n’a besoin que des bonnes informations pour vous aider. Le réflexe intuitif, « donnons-lui tout, il triera », est le mauvais : trop de contexte non pertinent dégrade ses réponses et coûte à chaque message. Savoir guider Claude vers ce qui compte est la compétence la plus rentable de ce cours. Claude Code vous donne pour cela quatre mécanismes : les fichiers CLAUDE.md que vous écrivez, les règles par chemin, la mémoire automatique que Claude entretient lui-même, et les mentions @ dans vos demandes.

Le fichier CLAUDE.md

Un CLAUDE.md est un fichier Markdown que Claude lit au début de chaque session. Il remplit deux rôles qu’il vaut mieux ne pas confondre. Le premier est descriptif : il guide Claude dans votre base de code en lui rappelant les commandes de build et de test, l’architecture, les conventions. Le second est prescriptif : il donne des directives, vos préférences et vos interdictions. « N’installe jamais de nouvelle dépendance sans demander » relève de la seconde catégorie.

Claude traite ce fichier comme du contexte, pas comme une configuration imposée. Il suit vos consignes de façon fiable quand elles sont concrètes, mais rien ne le garantit. Pour une règle qui doit tenir à chaque fois, sans exception, la documentation renvoie aux hooks (leçons 12 à 17).

Claude reconnaît quatre emplacements, chargés dans cet ordre, du plus large au plus précis :

Le choix de l’emplacement est une décision d’équipe autant que technique. Une convention d’architecture appartient au fichier de projet, où elle profitera aux nouveaux arrivants. Une URL de bac à sable ou un jeu de données de test préféré va dans CLAUDE.local.md. Votre langue de travail ou votre style de commit va dans le fichier utilisateur. Les fichiers situés dans les dossiers parents du répertoire de travail sont chargés au lancement ; ceux des sous-dossiers se chargent à la demande, quand Claude y travaille. Pour vérifier ce qui est chargé, lancez /context all et lisez la liste Memory files.

Si votre dépôt utilise un AGENTS.md pour d’autres agents de programmation, Claude Code le lit à la place quand il ne trouve aucun CLAUDE.md (version 2.1.277 et au-delà) ; le réglage Project instructions de /config permet de lire les deux.

Écrire des instructions efficaces

Trois règles résument la page officielle. Soyez concret et vérifiable : « indentation de 2 espaces » plutôt que « formate proprement », « lance npm test avant de commiter » plutôt que « teste tes changements », « les handlers d’API vivent dans src/api/handlers/ » plutôt que « garde les fichiers organisés ». Restez court : visez moins de 200 lignes par fichier ; au-delà, l’adhérence baisse et chaque ligne est payée à chaque message. Restez cohérent : si deux instructions se contredisent, Claude en choisit une au hasard.

Quand ajouter une ligne ? La documentation donne quatre déclencheurs : Claude refait la même erreur une seconde fois ; une revue de code relève quelque chose qu’il aurait dû savoir ; vous retapez une correction déjà donnée dans une session précédente ; un nouveau collègue aurait besoin de la même information. Si l’entrée est une procédure en plusieurs étapes ou ne concerne qu’une partie du projet, elle a sa place dans une skill (leçon 9) ou dans une règle par chemin plutôt que dans CLAUDE.md. Pour faire auditer vos fichiers d’instructions par Claude (contradictions, chemins qui n’existent plus, tournures écrites pour d’anciens modèles), lancez /doctor prompt-audit.

Importer des fichiers et scoper des règles

Un CLAUDE.md peut importer d’autres fichiers avec la syntaxe @chemin, relative au fichier qui importe, jusqu’à quatre niveaux :

Voir @README pour la vue d'ensemble et @package.json pour les commandes npm.
Le schéma de base de données est défini dans @prisma/schema.prisma.

Un fichier importé est chargé avec le CLAUDE.md qui l’importe : l’import aide à organiser, pas à économiser du contexte. Réservez-le aux fichiers réellement transverses. Pour mentionner un chemin sans l’importer, mettez-le entre accents graves.

Pour les projets de grande taille, le dossier .claude/rules/ accueille des fichiers d’instructions par thème. Un fichier dont l’en-tête YAML déclare des paths ne se charge que lorsque Claude travaille sur des fichiers qui correspondent :

---
paths:
  - "src/api/**/*.ts"
---
# Règles de l'API
- Toute route valide son entrée avec le schéma Zod du module

C’est le moyen officiel de garder un CLAUDE.md court sans perdre les règles spécifiques à un langage ou à un dossier.

La mémoire automatique

Le second système de mémoire ne vous demande rien : Claude l’écrit lui-même. Au fil des sessions, il note ce qui lui servira plus tard et le range dans ~/.claude/projects/<projet>/memory/, avec un index MEMORY.md dont les 200 premières lignes (ou 25 Ko) sont chargées à chaque démarrage, et un fichier par sujet lu à la demande. Il y consigne quatre types de notes : votre rôle et vos préférences (user), les corrections que vous lui donnez et les approches que vous validez (feedback), le travail en cours et les décisions qu’il ne peut pas déduire du code (project), et les références externes comme un tableau de bord ou un outil de tickets (reference). Il ne note pas ce qui se déduit du code ni ce que CLAUDE.md dit déjà.

Quand vous dites « retiens que les tests d’API ont besoin d’un Redis local » ou « utilise toujours pnpm, pas npm », Claude l’enregistre dans la mémoire automatique. Pour l’inscrire dans CLAUDE.md à la place, dites-le explicitement : « ajoute ça au CLAUDE.md ». Les anciennes versions proposaient un raccourci # pour écrire dans CLAUDE.md depuis le prompt ; il n’existe plus, et c’est /memory qui liste les fichiers CLAUDE.md, ouvre le dossier de mémoire automatique et permet de la désactiver. Tout est du Markdown en clair, que vous pouvez relire, corriger ou supprimer.

Mentionner des fichiers avec @

Quand vous voulez que Claude regarde un fichier précis, tapez @ suivi du chemin : l’autocomplétion propose les fichiers, et leur contenu est inclus dans votre demande, ce qui supprime l’étape de recherche et le risque qu’il ouvre le mauvais fichier.

Comment fonctionne le système d'authentification ? @src/auth/session.ts

Un dossier mentionné donne sa liste de fichiers, pas leur contenu. Le même geste sert pour une capture d’écran ou un document, et la leçon suivante y revient.

À vous de jouer

1. Ouvrez le CLAUDE.md généré à la leçon précédente et appliquez la règle « concret et vérifiable » à trois phrases vagues. Supprimez ce que Claude peut déduire du code (liste des dépendances, arborescence).
2. Créez .claude/rules/tests.md avec un en-tête paths ciblant vos fichiers de test et une règle sur le nommage ou la bibliothèque à utiliser. Demandez à Claude d’écrire un test et vérifiez qu’il la respecte.
3. Donnez une correction en conversation (« retiens que… »), quittez, relancez claude et vérifiez dans /memory qu’elle a été notée.
4. Lancez /doctor prompt-audit et lisez les propositions sans les appliquer toutes.

Sources officielles : How Claude remembers your project · Explore the .claude directory · Explore the context window · Extend Claude Code

Points clés à retenir

• CLAUDE.md existe à quatre niveaux (organisation, utilisateur, projet, local) ; il est lu à chaque session et compte comme contexte, pas comme règle imposée
• Instructions concrètes, moins de 200 lignes, pas de contradictions ; les procédures vont dans des skills, les règles locales dans .claude/rules/ avec paths
• @chemin importe un fichier dans CLAUDE.md et attache un fichier à une demande
• La mémoire automatique est écrite par Claude (~/.claude/projects/<projet>/memory/) ; « retiens que… » y va, « ajoute au CLAUDE.md » va dans le fichier
• /context all montre ce qui est chargé, /memory ouvre les fichiers, /doctor prompt-audit les audite