Configurer Claude Code : le guide du CLAUDE.md et des fichiers .claude

Chaque session de Claude Code commence avec une fenêtre de contexte vierge. Il ne sait pas comment lancer vos tests, quelle convention de nommage vous suivez, ni quel piège vous a coûté une après-midi la semaine dernière. Vous pouvez le lui réexpliquer à chaque fois, ou l'écrire une bonne fois dans quelques fichiers que Claude Code lit tout seul. C'est l'équivalent d'un document d'accueil pour un nouveau collègue, et c'est ce qui fait la différence entre un assistant générique et un assistant qui connaît votre projet.

Ce tutoriel suit l'ordre dans lequel on met ces fichiers en place. Tout ce qui suit est tiré de la documentation officielle de Claude Code, consultée en octobre 2026.

1. Le CLAUDE.md : le document d'accueil de votre projet

Le CLAUDE.md est un fichier Markdown que Claude Code lit au début de chaque session. Il en existe plusieurs, selon à qui la consigne s'adresse :

• Projet, partagé avec l'équipe : ./CLAUDE.md ou ./.claude/CLAUDE.md, à committer avec le code ;
• Personnel, tous projets : ~/.claude/CLAUDE.md, pour vos préférences (style, outils) ;
• Personnel, un seul projet : ./CLAUDE.local.md, à ajouter au .gitignore ;
• Organisation : un fichier géré par l'IT, par exemple /Library/Application Support/ClaudeCode/CLAUDE.md sur macOS, qui s'applique à tout le monde et ne peut pas être exclu.

Ces fichiers ne s'écrasent pas : ils s'additionnent. Lancé dans foo/bar/, Claude Code charge foo/CLAUDE.md puis foo/bar/CLAUDE.md. Les CLAUDE.md des sous-dossiers, eux, ne sont lus que lorsque Claude travaille sur un fichier de ce sous-dossier.

Pour démarrer, tapez /init dans une session : Claude analyse le projet et rédige un premier CLAUDE.md avec les commandes de build, de test et les conventions qu'il a repérées. S'il en existe déjà un, il propose des améliorations au lieu de l'écraser.

Que mettre dedans ? Ce qu'un nouveau développeur devrait savoir le premier jour, et que le code ne dit pas tout seul :

# Mon projet

## Commandes
- `npm run dev` : serveur local sur le port 3000
- `npm run test -- fichier.test.ts` : un seul fichier de test

## Conventions
- Les handlers d'API sont dans `src/api/handlers/`
- Indentation : 2 espaces

## Pièges
- Ne jamais modifier `src/generated/` : régénéré par `npm run codegen`

Deux règles comptent plus que les autres. Soyez précis : « Les handlers d'API sont dans src/api/handlers/ » est utile, « Garder le code organisé » ne l'est pas. Et restez court : Anthropic recommande de viser moins de 200 lignes par fichier, car un fichier long consomme du contexte et il est moins bien suivi. Si deux consignes se contredisent, Claude peut choisir l'une ou l'autre au hasard ; relisez vos fichiers de temps en temps.

2. Organiser : imports, règles ciblées, AGENTS.md

Quand le CLAUDE.md grossit, trois outils évitent d'en faire un pavé.

Les imports. Une ligne @chemin/vers/fichier insère un autre fichier dans le CLAUDE.md, par exemple @README.md ou @docs/architecture.md. Les chemins relatifs partent du fichier qui importe, et un fichier importé peut en importer d'autres, jusqu'à quatre niveaux. Attention : un import range le contenu, il ne le rend pas gratuit. Le fichier importé est chargé en entier au démarrage.

Les règles ciblées. Le dossier .claude/rules/ accueille des fichiers Markdown thématiques (tests.md, api.md…). Sans en-tête, une règle est chargée à chaque session. Avec un champ paths, elle ne l'est que lorsque Claude lit ou modifie un fichier correspondant :

---
paths:
  - "src/api/**/*.ts"
---

# Règles pour l'API
- Chaque endpoint valide ses entrées
- Utiliser le format d'erreur standard

C'est le bon endroit pour tout ce qui ne concerne qu'une partie du code : le CLAUDE.md reste léger, et la consigne arrive au moment où elle sert. Vos règles personnelles valables partout vont dans ~/.claude/rules/.

AGENTS.md. Si votre dépôt est déjà configuré pour d'autres agents de code avec un fichier AGENTS.md, les versions récentes de Claude Code le lisent quand aucun CLAUDE.md n'existe. Pour garder les deux, il suffit d'importer l'un dans l'autre : une ligne @AGENTS.md dans votre CLAUDE.md.

3. La mémoire automatique : ce que Claude retient seul

À côté de vos consignes, Claude Code tient ses propres notes. Quand vous le corrigez (« non, on déploie toujours avec ce script »), il peut l'enregistrer dans un dossier propre à chaque projet : ~/.claude/projects/<projet>/memory/. Un fichier MEMORY.md y sert d'index, une ligne par souvenir, avec un fichier détaillé par sujet.

Cette mémoire est rechargée à chaque session, mais seulement les 200 premières lignes ou 25 Ko de l'index : Claude la garde donc concise. La commande /memory permet de consulter ces fichiers et de couper la mémoire automatique si vous préférez tout écrire vous-même.

La répartition est simple : le CLAUDE.md, c'est ce que vous voulez qu'il sache ; la mémoire, c'est ce qu'il a appris en travaillant avec vous.

4. settings.json : les autorisations et les réglages

Les consignes du CLAUDE.md orientent Claude ; les fichiers settings.json fixent ce qu'il a le droit de faire. Ils existent à plusieurs niveaux, du plus prioritaire au moins prioritaire :

1. les réglages gérés par votre organisation ;
2. les options passées en ligne de commande pour une session ;
3. .claude/settings.local.json : vous, sur ce projet (hors git) ;
4. .claude/settings.json : toute l'équipe, sur ce projet (committé) ;
5. ~/.claude/settings.json : vous, sur tous vos projets.

Le réglage le plus utile au quotidien, ce sont les permissions. Plutôt que de valider la même commande vingt fois par jour, autorisez-la ; et interdisez ce qui ne doit jamais être lu :

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

La ligne $schema donne l'autocomplétion dans votre éditeur. Le fichier est du JSON strict : pas de commentaire, pas de virgule finale. Quand vous répondez « Oui, ne plus demander » à une demande d'autorisation, Claude Code enregistre la règle dans settings.local.json pour vous. La commande /config règle les préférences personnelles sans ouvrir de fichier.

5. Les skills : vos procédures, en une commande

Une skill est un dossier contenant un fichier SKILL.md : une procédure que Claude applique quand elle est pertinente, ou que vous lancez vous-même en tapant /nom-de-la-skill. Contrairement au CLAUDE.md, son contenu n'est chargé que lorsqu'elle sert. On les range dans .claude/skills/<nom>/SKILL.md pour le projet, ou ~/.claude/skills/<nom>/SKILL.md pour vous.

---
name: resume-modifs
description: Résume les modifications non committées et signale les risques. À utiliser quand on demande ce qui a changé ou un message de commit.
---

Résume les modifications en deux ou trois puces, puis liste les risques :
gestion d'erreurs manquante, valeurs en dur, tests à mettre à jour.

La description est décisive : c'est sur elle que Claude s'appuie pour décider de charger la skill de lui-même. Pour une action à effet de bord, comme un déploiement ou un envoi de message, ajoutez disable-model-invocation: true dans l'en-tête : seule une commande tapée par vous pourra la lancer.

Si vous utilisiez les anciennes commandes personnalisées (.claude/commands/deploy.md), elles fonctionnent toujours : elles ont été fusionnées dans les skills, qui ajoutent les fichiers annexes et le déclenchement automatique.

6. Les hooks : ce qui doit arriver à coup sûr

C'est la nuance la plus importante du tutoriel. Un CLAUDE.md conseille : Claude le suit, mais il le traite comme du contexte, pas comme une règle inviolable. Quand une action doit se produire à chaque fois, ou ne jamais se produire, on passe par un hook : une commande que Claude Code exécute lui-même à un moment précis, déclarée dans un settings.json.

Formater automatiquement chaque fichier modifié :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Bloquer toute modification d'un fichier sensible : un hook PreToolUse lance un petit script avant chaque écriture, qui vérifie le chemin et répond par le code de sortie 2 pour refuser l'action. Claude reçoit alors la raison du refus et adapte son approche. La commande /hooks liste les hooks actifs. Un hook exécute des commandes sur votre machine : relisez-les comme du code avant de les ajouter, surtout dans un projet partagé.

L'arborescence, en résumé

~/.claude/
├── CLAUDE.md            vos préférences, tous projets
├── settings.json        vos réglages et permissions
├── rules/               vos règles personnelles
└── skills/              vos skills personnelles

mon-projet/
├── CLAUDE.md            le document d'accueil (committé)
├── CLAUDE.local.md      vos notes sur ce projet (hors git)
└── .claude/
    ├── settings.json        permissions et hooks de l'équipe
    ├── settings.local.json  vos exceptions (hors git)
    ├── rules/               règles ciblées par dossier
    └── skills/              procédures du projet

Ce qu'on en fait chez nous

Nous construisons nos sites dans un atelier commun, et cette organisation y tourne au quotidien. Un CLAUDE.md d'atelier décrit ce qui ne change jamais : le CMS, l'hébergement, la procédure de déploiement. Chaque site a ensuite son propre CLAUDE.md, qui ne contient que ses spécificités, et surtout ses pièges : la règle CSS qui casse l'en-tête fixe, le fichier de vérification Google à ne jamais supprimer. La mémoire automatique garde le reste : les décisions prises, les erreurs déjà commises et comment elles ont été corrigées.

Le gain ne se voit pas le premier jour. Il se voit le jour où une session repart sur un projet laissé en plan trois semaines plus tôt, et où l'erreur d'il y a un mois n'est pas commise une deuxième fois.

Un agent de code sans configuration repart de zéro à chaque session. Avec quelques fichiers bien tenus, il reprend là où l'équipe s'est arrêtée.

Pour aller plus loin sur ce que ces outils changent dans un projet, lisez notre point sur Claude Code à l'été 2026. Et si vous voulez mettre l'IA au travail sur vos propres projets sans perdre la main, parlons-en.