Claude Code : guide complet de configuration (CLAUDE.md, Hooks, MCP, Sub-Agents)

Claude ne se souvient de rien entre deux sessions. Il ne sait pas que tu lances npm run dev:local et pas npm start. Il ne sait pas que les commits sont en français, que src/components/ est intouchable, ou que tu es passé à Tailwind v4. À chaque nouvelle session, tu réexpliques. Il te repose les mêmes questions, relit les mêmes fichiers, propose des solutions qui contredisent les conventions que tu lui as données la veille. Tu ne codes plus : tu le formes.

Il y a une façon de changer ça. Claude Code embarque un cadre de travail complet : mémoire persistante, automatisations, agents. Ce guide couvre les sept blocs à configurer pour passer d’un LLM qu’on relance à un outil qui travaille avec toi.

Claude Code est un modèle agentique. Il ne génère pas juste du texte : il lit des fichiers, exécute des commandes, enchaine des décisions sans attendre une instruction à chaque étape. C’est ce qui le distingue d’un chatbot, même bien configuré.

La plupart des gens arrivent avec les habitudes acquises sur d’autres LLMs : prompt, réponse, recommencer. Le changement de paradigme vient du cadre de travail : mémoire persistante entre les sessions, automatisations déclenchées sans intervention, agents parallèles. Le gain de productivité vient de cette combinaison : un modèle qui agit, dans un cadre conçu pour le guider.

Sept blocs à connaitre, du plus simple au plus puissant. Tu n’as pas besoin de tous les mettre en place aujourd’hui : commence par les premiers, ajoute les suivants quand tu en ressens le besoin.

Cet article est mis à jour au fil des évolutions de Claude Code. Des imprécisions restent possibles, et la documentation officielle fait référence si tu veux aller à la source.

Le problème du contexte #

À chaque échange, Claude reçoit l’intégralité de la conversation depuis le début, sous forme de texte. C’est le contexte. Il s’alourdit à chaque message, chaque fichier lu, chaque résultat d’outil. Mesuré en tokens (environ 4 caractères chacun), il a une limite. Les modèles Claude récents supportent plus d’un million de tokens par session, ce qui parait immense jusqu’à ce qu’on voit comment ce volume se remplit.

La mécanique est simple : chaque nouvelle requête rejoue tout l’historique avant d’y ajouter sa part. Le volume envoyé grimpe donc à chaque échange, et finit par buter sur le plafond.

---
config:
  themeVariables:
    xyChart:
      plotColorPalette: "#60a5fa,#a78bfa,#f59e0b,#ef4444"
---
xychart
    title "Tokens traités par échange (cumul)"
    x-axis ["Échange 1", "Échange 2", "Échange 3", "Échange 4", "Échange 5"]
    y-axis "Tokens (k)" 0 --> 1000
    bar [13, 58, 177, 417, 847]
    bar [2, 2, 3, 3, 3]
    line [650, 650, 650, 650, 650]
    line [1000, 1000, 1000, 1000, 1000]

Les sept blocs qui suivent sont des réponses concrètes à cette contrainte. Certains évitent de réinjecter les mêmes informations à chaque session. D’autres réduisent les allers-retours de clarification. D’autres encore isolent les tâches lourdes dans des contextes séparés pour ne pas polluer la conversation principale. C’est ce qui fait de Claude Code un cadre de travail, pas juste un modèle qu’on relance.

Prérequis #

La façon la plus simple de démarrer : installer le plugin Claude Code pour VS Code directement depuis le marketplace.

Ouvre ton projet dans VS Code. Claude Code s’intègre dans l’éditeur, dans un panneau dédié. Il lit et modifie tes fichiers directement dans ton workspace, sans copier-coller, sans changer de fenêtre. Ton dossier de projet devient son espace de travail.

Disponible aussi en ligne de commande. Sur macOS, Linux ou WSL :

curl -fsSL https://claude.ai/install.sh | bash

Sur Windows (PowerShell) :

irm https://claude.ai/install.ps1 | iex

Ou via npm si tu préfères :

npm install -g @anthropic-ai/claude-code

Lance-le ensuite dans ton projet :

claude

Les exemples de configuration qui suivent (chemins, commandes shell) utilisent les conventions Linux et WSL2. Sur macOS, les chemins sont identiques.

Dans les deux cas, chaque lancement crée une nouvelle session : contexte vide, mémoire effacée. C’est précisément ce que les sept blocs viennent changer.

Par où commencer #

Si tu n’as pas encore de CLAUDE.md, la commande /init est le point de départ : lancée dans Claude Code, elle analyse ton projet et génère un fichier de départ depuis les commandes et conventions qu’elle détecte. C’est plus rapide qu’écrire à la main.

De là, le premier réflexe : passe en Plan mode (Shift+Tab). Tu verras exactement ce que Claude compte faire avant qu’il le fasse. Ça ne coûte rien à activer et ça donne confiance pour travailler sur du code qui compte.

Ensuite, un CLAUDE.md solide pour chaque projet, puis deux ou trois skills pour tes tâches les plus répétitives. C’est déjà 80% du gain, et ça prend une heure à mettre en place. La mémoire automatique, elle, travaille sans intervention de ta part dès le départ.

Les Hooks et MCP servers viennent naturellement quand tu identifies une friction spécifique : “je dois toujours penser à lancer le linter” ou “je dois toujours copier-coller des données depuis un outil externe”. Les Sub-Agents, c’est pour quand tu as des workflows suffisamment stables pour mériter d’être automatisés.

Ces blocs se combinent bien. Sur notre site exemple, ça donnerait :

CLAUDE.md              → stack, conventions et commandes toujours présentes
/review                → skill pour auditer un composant JS
npm run lint (hook)    → tourne automatiquement après chaque modification
@code-reviewer         → audit des 3 pages principales en parallèle

Chaque bloc a sa place. L’important c’est de les introduire progressivement, pas de tout configurer d’un coup.

La carte du territoire #

Si tu développes des projets au quotidien, tu as déjà une forme de configuration en place : un README, des scripts npm, des hooks git. Claude Code fonctionne de la même façon. Sept outils, chacun avec un rôle précis, regroupés ici par nature :

flowchart TB
    CM["CLAUDE.md<br>Mémoire permanente"]:::claudemd --> WHEN
    AM["Mémoire auto<br>Apprentissage entre sessions"]:::memoireAuto --> WHEN
    SK["Skills<br>Slash commands & expertise auto"]:::skills --> WHEN
    PM["Plan mode<br>Révision avant exécution"]:::planMode --> WHEN
    HK["Hooks<br>Automatisation"]:::hooks --> WHEN
    MCP["MCP Servers<br>Outils externes"]:::mcp --> WHEN
    SA["Sub-Agents<br>Travail en parallèle"]:::subAgents --> WHEN
    WHEN["Quelle approche<br>pour quelle tâche ?"]

    click CM href "#claudemd---la-mémoire-du-projet"
    click AM href "#mémoire-automatique---ce-que-claude-apprend-seul"
    click SK href "#skills---workflows-personnalisés-et-slash-commands"
    click PM href "#plan-mode---valider-avant-dagir"
    click HK href "#hooks---lautomatisation-en-arrière-plan"
    click MCP href "#mcp-servers---brancher-des-outils-externes"
    click SA href "#sub-agents---travailler-en-parallèle"

    classDef claudemd    fill:#1d4ed8,stroke:#1e40af,color:#fff
    classDef memoireAuto fill:#0e7490,stroke:#155e75,color:#fff
    classDef skills      fill:#15803d,stroke:#14532d,color:#fff
    classDef planMode    fill:#7e22ce,stroke:#6b21a8,color:#fff
    classDef hooks       fill:#b45309,stroke:#92400e,color:#fff
    classDef mcp         fill:#c2410c,stroke:#9a3412,color:#fff
    classDef subAgents   fill:#be123c,stroke:#9f1239,color:#fff

On va les voir dans cet ordre, du plus accessible au plus puissant.

Le dossier .claude/ #

Avant de rentrer dans le détail de chaque bloc, il faut connaitre l’endroit où tout ça vit : le dossier .claude/.

mon-projet/
├── .claude/
│   ├── skills/         ← tes slash commands et skills
│   ├── agents/         ← tes sub-agents
│   ├── rules/          ← règles modulaires scopées
│   └── settings.json   ← permissions et hooks
├── CLAUDE.md           ← instructions partagées (git)
├── CLAUDE.local.md     ← notes perso (gitignore)
└── .mcp.json           ← serveurs MCP du projet (racine)

Ce dossier peut exister à deux niveaux, et c’est important :

• Dans ton projet (monprojet/.claude/) : la config n’est disponible que pour ce projet
• Dans ton home (~/.claude/) : la config est disponible dans tous tes projets

En pratique, tu mettras dans ~/.claude/ les choses universelles (ta préférence pour le français, ton agent de code review générique) et dans .claude/ du projet les choses spécifiques (les conventions du projet, l’agent qui connait ta base de données).

Documentation →

CLAUDE.md - La mémoire du projet #

C’est le point de départ, et de loin le plus simple à mettre en place. CLAUDE.md est un fichier texte que Claude lit automatiquement à chaque session. C’est sa mémoire sur ton projet.

Sans lui, Claude ne sait pas que tu utilises du JS vanilla, que le dossier src/ contient les composants, ou que les commits doivent être en français. Tu dois le répéter à chaque session. Avec lui, tu ne le dis qu’une fois.

Ce qu’il doit contenir :

# Mon Site

## Stack

- HTML / CSS / JavaScript vanilla · pas de framework
- npm pour les scripts

## Architecture

src/ → composants et modules JS public/ → fichiers générés, ne pas modifier
directement

## Commandes

- `npm run dev` → serveur local avec hot reload
- `npm run lint` → vérification du code

## Conventions

- Commits en français
- Toujours lancer `npm run lint` avant de committer

Pense à CLAUDE.md comme un brief d’agence : concis, actionnable, et centré sur ce qui change réellement le comportement.

CLAUDE.md peut exister à plusieurs niveaux, tous chargés simultanément :

CLAUDE.local.md est le fichier pour tes notes personnelles sur un projet partagé : une convention que tu préfères mais qui n’est pas une règle d’équipe, un rappel sur un bug en cours, une configuration locale.

Règles modulaires avec .claude/rules/ #

Sur les projets plus larges, tu peux découper les instructions en fichiers thématiques dans .claude/rules/. Chaque fichier peut être scopé à des chemins précis via un frontmatter YAML :

---
paths:
  - "src/api/**/*.ts"
---
# Règles API
- Tous les endpoints doivent inclure une validation d'input

Claude charge ce fichier automatiquement quand il lit un fichier dont le chemin correspond au pattern. Sur un projet de taille raisonnable, un seul CLAUDE.md suffit. Les rules/ ont leur sens quand les instructions deviennent longues au point de se marcher dessus.

Documentation →

Mémoire automatique - Ce que Claude apprend seul #

Sans rien configurer, Claude Code construit de la mémoire entre tes sessions. Quand il découvre quelque chose d’utile dans ton projet, il l’écrit dans un fichier qui persiste : une commande de build non documentée, un pattern récurrent dans ton code, une erreur qu’il a déjà résolue. La prochaine session, il relit cette mémoire et reprend là où il en était.

Concrètement : tu n’as pas à répéter deux fois “lance d’abord docker compose up avant de tester”. Claude le note et s’en souvient.

Cette mémoire est activée par défaut. Pour la désactiver si tu veux un comportement strictement déterministe :

{
  "autoMemoryEnabled": false
}

La différence avec CLAUDE.md : CLAUDE.md contient ce que tu décides que Claude doit savoir, rédigé par toi. La mémoire automatique contient ce que Claude a appris en travaillant sur ton projet. Les deux se complètent : le premier cadre le comportement, le second accumule l’expérience au fil du temps.

La mémoire est stockée dans ~/.claude/projects/<project>/memory/. Le fichier MEMORY.md est chargé à chaque démarrage de session (200 lignes ou 25 Ko maximum). Les fichiers thématiques ne le sont pas : Claude les lit à la demande. Tous les worktrees d’un même dépôt git partagent ce dossier.

~/.claude/projects/<project>/memory/
├── MEMORY.md          ← index chargé au démarrage
├── debugging.md       ← lu à la demande
└── api-conventions.md ← lu à la demande

La commande /memory liste tous les fichiers chargés en session, permet de basculer la mémoire auto et ouvre directement ce dossier.

Documentation →

Skills - Workflows personnalisés et slash commands #

Dans Claude Code, les skills sont le système unique pour créer tes propres workflows. Si tu as croisé le terme “slash commands” ailleurs, c’est la même chose : les custom slash commands ont été fusionnés dans les skills, et c’est désormais le seul système recommandé.

Un skill, c’est un dossier dans .claude/skills/ :

.claude/skills/
└── review/
    ├── SKILL.md        ← instructions et prompt
    ├── examples/       ← fichiers d'accompagnement optionnels
    └── scripts/
        └── helper.py   ← script dont seul l'output entre dans le contexte

Le fichier SKILL.md commence par un frontmatter qui définit son comportement :

---
description: >
  Analyse un fichier pour la qualité, la sécurité et les performances. Use when
  asked to review or audit code.
---

Tu es un expert en code review. Analyse le fichier $ARGUMENTS en vérifiant :

- Sécurité (injections, XSS, CSRF)
- Performance (requêtes N+1, index manquants)
- Lisibilité et conventions du projet

Retourne un rapport structuré avec priorités.

Ce skill peut être déclenché de deux façons :

Manuellement, en tapant /review src/components/header.js dans le terminal. La variable $ARGUMENTS récupère ce qui suit la commande. Tu peux cibler des arguments précis avec $1, $2, etc.

Automatiquement, quand Claude juge que le contexte correspond à la description du skill. Si tu lui demandes “peux-tu auditer ce fichier ?”, il va charger le skill review tout seul, sans que tu tapes la commande.

C’est la vraie différence avec un simple prompt : un skill avec une bonne description devient un outil que Claude utilise de sa propre initiative. L’intérêt des scripts dans un skill est aussi notable : ils sont exécutés, pas lus. Si tu as un script Python qui vérifie l’état du serveur, seul son output entre dans le contexte, pas ses 200 lignes de code.

Documentation →

Plan mode - Valider avant d’agir #

Plan mode change la façon dont Claude interagit avec ton projet : au lieu d’appliquer les modifications directement, il te présente d’abord exactement ce qu’il compte faire. Tu valides, puis il agit.

Pour activer Plan mode au démarrage :

claude --permission-mode plan

Ou en cours de session, avec Shift+Tab jusqu’à voir “plan” apparaitre dans l’interface.

Claude liste les fichiers qu’il va toucher, les modifications qu’il compte apporter, et attend ton accord. C’est particulièrement utile quand tu travailles sur du code partagé, quand tu explores une codebase inconnue, ou quand la portée d’une refactorisation n’est pas encore claire.

L’inverse existe aussi : le mode auto, qui permet à Claude d’exécuter les actions sûres sans demander à chaque fois. Il se configure dans ton settings.json global, soit ~/.claude/settings.json. Depuis la version 2.1.142, auto est ignoré quand il est défini au niveau d’un projet :

{
  "permissions": {
    "defaultMode": "auto"
  }
}

Plan mode pour travailler en confiance sur du code qui compte. Mode auto pour les tâches répétitives où tu sais ce que tu veux. Entre les deux, le comportement par défaut demande confirmation pour les actions potentiellement risquées.

Documentation →

Hooks - L’automatisation en arrière-plan #

Un hook, c’est une commande shell qui se lance automatiquement quand Claude utilise un outil. Tu définis “après chaque écriture de fichier, lance le linter” : ça arrive à chaque fois, sans que tu aies à y penser.

Voici les événements les plus utiles (la liste complète est bien plus longue) :

La configuration se fait dans settings.json :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/lint.sh"
          }
        ]
      }
    ]
  }
}

Le hook reçoit les informations sur l’événement via stdin, au format JSON. Pour récupérer le fichier modifié dans le script, on utilise jq :

#!/bin/bash
file=$(jq -r '.tool_input.file_path' < /dev/stdin)
npm run lint -- "$file"

Ici, chaque fois que Claude écrit ou modifie un fichier, le linter tourne automatiquement. Si le linter remonte une erreur, Claude la voit et peut la corriger immédiatement.

PermissionRequest ouvre une possibilité différente : au lieu d’agir sur le résultat d’un outil, ce hook intercepte les demandes de permission de Claude. Tu peux l’utiliser pour auto-approuver certaines classes d’actions sans passer en mode auto complet :

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

PreCompact se déclenche juste avant que Claude compresse son contexte avec /compact. Tu peux lui passer des instructions sur ce qu’il doit absolument conserver dans le résumé, plutôt que de le laisser choisir seul.

D’autres usages courants : formater le code avec Prettier après chaque modification, lancer les tests unitaires sur les fichiers touchés, afficher une notification desktop quand une longue tâche se termine, ou loguer les actions de Claude pour les auditer plus tard. La variable $CLAUDE_PROJECT_DIR est disponible dans les scripts pour connaitre la racine du projet.

Documentation →

MCP Servers - Brancher des outils externes #

Par défaut, Claude Code peut lire et écrire des fichiers, exécuter des commandes bash, et faire des recherches. C’est déjà pas mal. Mais si tu veux qu’il puisse aussi interroger ta base de données, créer des issues GitHub, ou scraper une page web, il faut lui brancher un serveur MCP.

MCP (Model Context Protocol) est le protocole standard pour étendre les capacités de Claude avec des outils tiers. Il existe des serveurs pour à peu près tout :

• Bases de données : Postgres, MySQL, SQLite
• Outils de dev : GitHub, Linear, Jira
• Automatisation web : Playwright, Puppeteer
• Cloud : AWS, Vercel, Cloudflare
• Recherche : Brave Search, Tavily

La façon recommandée d’en ajouter un, c’est la commande claude mcp add, qui écrit la configuration à ta place. Beaucoup de services proposent désormais un serveur hébergé en HTTP, sans rien à installer. Pour brancher GitHub avec un jeton d’accès personnel :

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer YOUR_GITHUB_PAT"

Pour une base Postgres en local, via un serveur stdio :

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://localhost/mydb"

Chaque serveur a un scope. --scope local (le défaut) le réserve à toi sur ce projet, --scope project le partage avec l’équipe via un .mcp.json versionné, --scope user le rend disponible dans tous tes projets. Pratique pour les bases dont l’URL change d’un environnement à l’autre.

Tu peux aussi écrire .mcp.json à la main, à la racine du projet. Une règle : jamais de secret en clair, ce fichier est versionné. On pointe vers une variable d’environnement à la place :

{
  "mcpServers": {
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
    }
  }
}

Une fois configuré, Claude peut directement faire SELECT * FROM users ou créer une pull request sans que tu aies à copier-coller quoi que ce soit.

Documentation →

Sub-Agents - Travailler en parallèle #

C’est le bloc le plus avancé, et aussi le plus puissant. Un sub-agent est une instance séparée de Claude qui travaille de son côté, dans sa propre fenêtre de contexte, et te retourne uniquement son résultat final.

Comme vu plus haut, le contexte se remplit à mesure qu’une session avance. Les sub-agents règlent ce problème en isolant chaque tâche : l’agent fait son travail, retourne le résultat, et son contexte disparaît. La conversation principale ne garde que la synthèse.

À noter : les sub-agents ne réduisent pas ta consommation de requêtes. Chaque agent est une instance Claude à part entière qui fait ses propres appels. Ils règlent la qualité des réponses sur les sessions longues, pas les limites de quota.

Le parallélisme #

L’autre avantage : plusieurs agents peuvent tourner simultanément sur des tâches indépendantes. Au lieu d’auditer tes 3 pages l’une après l’autre dans la même conversation, tu lances 3 agents en parallèle.

flowchart TD
    T["Auditer le site complet"] --> A & B & C
    A["Agent A<br>Page accueil"] --> S
    B["Agent B<br>Page contact"] --> S
    C["Agent C<br>Page portfolio"] --> S
    S["Synthèse dans<br>la conversation principale"]

Un agent se configure avec un fichier .md dans .claude/agents/ :

---
name: code-reviewer
description: >
  Reviews code for quality, security, and best practices.
  Use when asked to review, audit, or check code quality.
tools: Read, Bash
model: claude-sonnet-4-6
memory: user
---

Tu es un expert en code review.
Focus sur : sécurité, performance, lisibilité.
Note les patterns récurrents que tu observes dans ta mémoire.

Le paramètre memory: user mérite une explication. Avec cette option, l’agent maintient son propre fichier MEMORY.md qui persiste entre les sessions. Il peut noter les patterns qu’il observe, les conventions du projet, les erreurs récurrentes, et s’en souvenir la prochaine fois qu’il est invoqué. C’est un agent qui s’améliore avec le temps.

Pour l’invoquer, tu mentionnes simplement son nom dans la conversation :

@code-reviewer regarde src/components/header.js

Ou il peut être appelé depuis un skill, ou déclenché par Claude lui-même quand il juge qu’une tâche mérite d’être isolée.

Documentation →

Quand utiliser quoi #

Sources et références #

• Documentation Claude Code
• MCP Servers - dépôt officiel