Étendre Claude Code : CLAUDE.md, hooks, subagents, MCP

Dans les cinq chapitres précédents, vous avez installé Claude Code, donné des instructions, dénoué des blocages et conçu vos permissions. Ce chapitre parle de transformer l'outil lui-même. Retenir le nom des extensions ne sert à rien. Ce qui sert, c'est un tableau de correspondance : « lequel résout la gêne que j'ai en ce moment ? »

Une carte pour choisir : quatre questions décident

Il y a six extensions, mais seulement quatre choses à se demander. Une demande suffit-elle ? Voulez-vous que cela s'applique à coup sûr ? Voulez-vous séparer le contexte ? Voulez-vous vous relier à l'extérieur ? Posez-vous ces questions dans cet ordre, et la réponse est presque toujours unique.

Une demande suffit-elle ?

Si un oubli occasionnel n'est pas grave, des mots suffisent. → CLAUDE.md (les prémisses générales) ou Skills (la procédure d'un travail précis)

Voulez-vous que cela s'applique à coup sûr ?

Si un seul oubli pose problème, arrêtez-le par un dispositif. → hooks. Ils s’exécutent lorsque les réglages actifs correspondent à l’événement et aux conditions.

Voulez-vous séparer le contexte ?

Si vous ne voulez pas noyer le fil principal sous une sortie massive, faites travailler dehors et ne recevez que la conclusion. → subagents

Voulez-vous vous relier à l'extérieur ?

S'il faut des informations que l'IA ne peut pas connaître (la valeur actuelle en base, le contenu d'un suivi de tickets). → MCP

La cinquième question, c'est « est-ce que je le distribue à d'autres ? » : si oui, plugins. Ce qui se confond le plus facilement, ce sont Q1 et Q2, c'est-à-dire CLAUDE.md, Skills et hooks. Ils se ressemblent tous, mais ce qui les sépare, c'est quand ils sont lus et qui les exécute.

CLAUDE.md : distinguer chargement et respect des consignes

CLAUDE.md fournit le contexte du projet à chaque session lorsqu’il se trouve à un emplacement chargé. Utilisez ~/.claude/CLAUDE.md pour les consignes communes à tous vos projets. Il contient des instructions rédigées, pas des réglages qui imposent les permissions d’exécution.

Si l’agent dit avoir lu le fichier sans le respecter, regardez séparément ces trois questions.

A-t-il été chargé ? Regardez si CLAUDE.md et les règles figurent dans Memory files sous /context. Le répertoire de démarrage et les exclusions influencent les fichiers inclus. Un AGENTS.md chargé directement n’apparaît pas dans cette liste : son absence ne prouve donc pas qu’il n’a pas été lu
Est-il revenu après compression ? Le CLAUDE.md racine est relu sur le disque et réinjecté après /compact. Les CLAUDE.md des sous-répertoires et les règles liées aux chemins sont rechargés lors de la lecture des fichiers correspondants. Les décisions conservées uniquement dans la conversation suivent un traitement différent
A-t-il influencé l’action ? Même si le fichier est chargé, vérifiez à part les règles vagues et les consignes contradictoires. Ne supposez pas que la plus récente l’emporte toujours. Précisez la portée et les conditions d’exception

La recommandation officielle est moins de 200 lignes par fichier CLAUDE.md. Ce n’est ni un seuil de chargement ni une garantie de respect des consignes. Gardez les règles toujours nécessaires et séparez les détails avec leurs conditions de lecture. Tout importer par @path ne réduit pas le contexte initial. Utilisez les Skills pour les procédures occasionnelles et les règles liées aux chemins pour les consignes propres à certains fichiers.

Ces distinctions suivent la documentation officielle de la mémoire. Pour des exemples concrets de diagnostic et les différences entre outils, consultez comment diagnostiquer les règles ignorées par les agents IA.

« Je l’ai lu » ne prouve pas le respect des consignes. Vérifiez l’affichage du chargement séparément des diffs et des résultats de tests. Confiez les conditions vérifiables mécaniquement aux hooks ou à la CI, comme expliqué ensuite, et signalez les aspects non vérifiés.

hooks : exécuter des contrôles selon les conditions

Une consigne comme « ne réécris pas .env » ne garantit aucun taux de respect. Si vous devez vérifier une condition et bloquer une opération avant son exécution, envisagez les permissions et les hooks.

Cette section traite des hooks de type command, qui exécutent des commandes shell. Lorsque les réglages actifs correspondent à l’événement et aux conditions, Claude Code lui-même les lance. Le modèle n’a pas besoin de se rappeler de les exécuter. En revanche, un hook ne s’exécute pas s’il est désactivé dans les réglages ou si l’opération passe par un chemin qu’il ne couvre pas. Consultez Qu’est-ce que les hooks de Claude Code ? pour une vue d’ensemble. Voici neuf événements représentatifs, pas une liste exhaustive.

SessionStart        au démarrage ou à la reprise
UserPromptSubmit    juste après votre envoi                 [peut bloquer]
PreToolUse          juste avant un outil = portier          [peut bloquer]
PostToolUse         après le succès d’un outil = formatage  (ne peut pas annuler l’action terminée)
Notification        en attente de saisie ou d'accord
Stop                fin d'une réponse                       [peut bloquer]
SubagentStop        sous-agent terminé                      [peut bloquer]
SessionEnd          fin de session
PreCompact          avant la compression                    [peut bloquer]

Ce qui peut être bloqué dépend de l’événement. Bloquer un outil avant exécution diffère d’empêcher une réponse de se terminer pour poursuivre le travail. Refusez les opérations dangereuses à PreToolUse et formatez automatiquement à PostToolUse : ce sont deux points de départ courants. Placez la configuration sous la clé "hooks" de settings.json. L’emplacement définit la portée (~/.claude/ = utilisateur, .claude/ = partagé, settings.local.json = personnel).

Transformons maintenant en dispositif la consigne du début, « ne réécris pas .env ». Il s’agit de l’exemple « bloquer les modifications de fichiers protégés » du guide officiel, restreint à .env. Il faut deux éléments : un réglage et un script.

① .claude/settings.json : exécute le script juste avant tout appel à Edit ou Write.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

② .claude/hooks/protect-env.sh : bloque l’opération si le nom du fichier modifié commence par .env (y compris .env.local, etc.). Sous macOS et Linux, rendez le script exécutable avec chmod +x .claude/hooks/protect-env.sh.

#!/bin/bash
# .claude/hooks/protect-env.sh
command -v jq >/dev/null || { echo "jq introuvable, modification bloquée" >&2; exit 2; }

FILE_PATH=$(jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"   # Convertit les \ de Windows en /

if [[ "${FILE_PATH##*/}" == .env* ]]; then
  echo "Blocked: $FILE_PATH est un fichier .env, modification refusée" >&2
  exit 2
fi
exit 0

La structure est un nom d’événement, puis un tableau de motifs et de commandes. matcher désigne les outils ciblés : "Edit|Write" correspond à Edit ou à Write (sans ce champ, tous les outils correspondent). Le hook reçoit du JSON sur l’entrée standard ; pour Edit et Write, tool_input.file_path contient le chemin absolu du fichier modifié. Sous Windows, ce chemin utilise \ comme séparateur : le script le convertit donc en / avant la comparaison. Avec le code de sortie 2, le texte de la sortie d’erreur standard est transmis à Claude comme motif du refus, et Claude le lit pour chercher une autre approche. 1 est traité comme une erreur non bloquante et l’opération continue : pour bloquer, utilisez 2. 0 signifie aucune objection, et l’on passe aux contrôles habituels de permission.

Le script utilise bash et jq (l’exemple du guide officiel suppose lui aussi jq). Sous Windows, les hooks s’exécutent dans Git Bash, ou dans PowerShell si Git Bash est absent : cet exemple nécessite donc Git Bash. Pour qu’un jq manquant ne laisse pas tout passer en silence, la première instruction du script bloque l’opération dans ce cas.

Un hook peut resserrer les restrictions, jamais les desserrer. Même s'il renvoie une autorisation, il ne fait qu'éviter la demande, et les règles de refus restent toujours prioritaires. Comme un refus émis par PreToolUse agit même dans le mode qui saute toutes les validations, il peut servir de plancher à ce que vous avez relâché au chapitre 5.

Pour tester, procédez comme le guide officiel. Demandez à Claude « ajoute une ligne de commentaire à .env » : l’opération s’arrête avant la modification, et le texte Blocked: revient à Claude. Vérifiez aussi que les fichiers autres que .env se modifient toujours normalement. Si vous vous trompez dans le chemin du script, une simple notification Failed with non-blocking status code apparaît et la porte reste ouverte : surveillez donc aussi ce message. Notez que cet exemple ne bloque que les deux outils Edit et Write ; une réécriture par une commande Bash ou PowerShell suit un autre chemin. Élargissez la cible selon ce que vous voulez bloquer. Les formats de sortie et les différences entre événements sont décrits dans le guide officiel des Hooks.

Considérez le coût en amont : les hooks de type command exécutent automatiquement des commandes shell avec vos droits d’utilisateur et peuvent modifier ou supprimer tout fichier auquel votre compte a accès. La documentation officielle demande elle aussi de lire et de tester chaque commande avant de l’ajouter. Ne configurez que des commandes fiables et validez leurs entrées. Les modifications apportées directement aux fichiers de réglages sont normalement appliquées automatiquement. Vérifiez leur enregistrement avec /hooks. Si une modification reste sans effet, contrôlez le JSON et l’emplacement du fichier avant de redémarrer la session.

subagents : déléguer dans un contexte séparé

Les sorties complètes de tests et les journaux volumineux peuvent remplir le contexte de grandes quantités de texte que vous comptiez seulement parcourir, au détriment des prémisses importantes. Les sous-agents exécutent ce travail dans un contexte séparé et rendent un résumé de la conclusion. Ils disposent normalement de leur propre contexte, de leurs consignes et de leurs permissions d’outils : le parent doit leur transmettre explicitement les informations nécessaires. Une exécution qui duplique la conversation et hérite de l’historique du parent constitue une exception ; elle diffère du context: fork d’un skill. Puisque le compte rendu est un résumé, demandez aussi les preuves nécessaires et les questions non résolues.

Séparer paie — enquête large, contrôle produisant une sortie massive, tâche autonome dont seule la conclusion importe
Séparer coûte — traitement séquentiel, allers-retours fréquents, travaux parallèles qui touchent le même fichier, correction qui tient en un ou deux gestes

C'est une fonction native, utilisable sans configuration. Pour ajouter une définition, écrivez .claude/agents/<nom>.md (ou ~/.claude/agents/ pour tous les projets) avec name / description / tools / model dans l'en-tête YAML. La gestion passe par /agents, l'appel par @agent-<nom>. Commencez par ceux fournis d'origine : exploration, planification, usage général.

C'est la description qui est la clé de l'appel. L'agent principal la lit pour décider s'il délègue, donc une description vague rend la sélection automatique moins probable. Soyez concret sur ce que ça fait et quand l'utiliser : le même piège existe pour les Skills.

À ne pas confondre, les Agent Teams sont un dispositif où plusieurs sessions indépendantes se coordonnent par une liste de tâches partagée. C'est expérimental, sur adhésion, désactivé par défaut (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Comme d'autres instances tournent, la consommation de tokens est forte, et on ne peut pas les imbriquer. La comparaison est faite dans La différence entre subagents et Agent Teams. Dans le doute, une session unique ou des subagents.

Skills : transformer des procédures en capital

Face à un « à chaque fois, cette procédure », ce qui fait la supériorité des Skills, c'est qu'ils ne s'ouvrent qu'au moment utile. Concrètement, c'est un dossier organisé autour d'un SKILL.md. En tête, name et description ; en dessous, la procédure en Markdown ; et vous pouvez y joindre reference/ ou scripts/. Il suffit de le poser dans .claude/skills/ (le projet) ou ~/.claude/skills/ (tous les projets) pour qu'il soit reconnu.

Le principe central est la divulgation progressive. Une liste des noms et descriptions des skills entre normalement dans le contexte, tandis que le corps est chargé par sélection automatique ou invocation explicite avec /skill-name. Les documents annexes sont lus au besoin. La liste des descriptions consomme aussi du contexte ; si les skills sont nombreux, leurs descriptions peuvent être raccourcies ou omises pour respecter le budget. Rédigez une description précise et vérifiez séparément que le skill a été appelé et que sa procédure a produit le résultat attendu. Consultez Qu’est-ce que les Claude Agent Skills ? pour apprendre à les rédiger.

En une ligne : CLAUDE.md = prémisses chargées habituellement ; Skills = procédures ouvertes par sélection automatique ou invocation explicite ; hooks de type command = traitements déclenchés par les événements et conditions configurés.

MCP : tendre la main vers les systèmes extérieurs

MCP (Model Context Protocol) est un standard pour accéder à des données et opérations externes, comme les valeurs actuelles d’une base de données ou les tickets d’un outil de suivi. Voici deux modes de connexion courants. Diagnostiquez les problèmes en combinant le mode de connexion et les détails de l’erreur.

Local (stdio) : le serveur démarre comme processus enfant sur votre ordinateur. Le chemin de l’exécutable, les variables d’environnement nécessaires et la sortie d’erreur du serveur fournissent les indices
Distant (HTTP) : vous vous connectez à un serveur par URL. L’URL, le réseau, les erreurs du serveur et les identifiants fournissent les indices

Commencez par le statut et les détails dans /mcp. failed peut concerner un serveur local comme distant. Si Issue: dans claude mcp get <name> contient un code HTTP ou le corps de l’erreur, lisez-les aussi. needs authentication oriente vers l’authentification ; pending approval, vers la révision de l’approbation d’un serveur du projet. Si un en-tête fixe Authorization est rejeté avec 401/403 pendant la connexion, le statut est failed, même si le problème est lié à l’authentification. Les solutions sont regroupées dans Erreur de connexion MCP dans Claude Code : causes et solutions.

Placez le fichier partagé .mcp.json à la racine du projet. Utilisez le champ env de chaque serveur pour les variables transmises à un serveur stdio ; pour l’authentification HTTP, utilisez OAuth ou headers selon le service. N’inscrivez pas les vraies clés directement dans des fichiers partagés ; référencez plutôt une variable comme ${API_KEY}. Certains noms de variables, dont les identifiants de Claude Code lui-même, sont remplacés par des chaînes vides dans les URL et en-têtes distants ; les détails figurent dans les règles officielles d’expansion.

Les définitions d’outils sont chargées à la demande par défaut. Dans une configuration courante avec recherche d’outils activée, seuls les noms des outils et les descriptions des serveurs entrent initialement dans le contexte. Les définitions sont chargées d’emblée lorsque la recherche est désactivée, dans un environnement non compatible ou pour les serveurs utilisant alwaysLoad, entre autres cas. Les résultats consomment aussi du contexte : vérifiez l’usage réel avec /context et désactivez les serveurs inutilisés.

plugins : rassembler un ensemble et le distribuer

Les plugins permettent de regrouper skills, définitions de sous-agents, hooks et configuration MCP pour les distribuer. Si vous fournissez un manifeste pour un plugin, placez-le dans .claude-plugin/plugin.json. La structure standard place skills/, agents/, hooks/hooks.json et .mcp.json à la racine du plugin lui-même. Ne mettez pas ces éléments sous .claude-plugin/. Un plugin utilisant uniquement la structure standard peut se passer de manifeste.

/plugin marketplace add owner/repo   ← enregistrer un catalogue
/plugin install name@marketplace     ← en installer un depuis ce catalogue
/plugin list                         ← lister les plugins installés via des marketplaces

Voici les étapes de base pour installer via une marketplace. L’enregistrement d’un catalogue n’installe aucun plugin à lui seul. /plugin list recense les plugins installés par cette voie, pas tous ceux disponibles par d’autres moyens, comme les répertoires de skills ou la synchronisation. Les portées sont user (tous vos projets), project (configuration partagée) et local (vous seul dans ce projet). Même avec project, chaque membre doit installer les plugins de sources externes. La portée managed est administrée de façon centralisée et limite les modifications de configuration des utilisateurs. Pour créer les vôtres, consultez Plugins et Marketplace de Claude Code : utiliser, créer, publier.

Les plugins peuvent exécuter du code arbitraire avec vos privilèges, avertit la documentation officielle. Les éléments du catalogue communautaire passent par la validation automatique et l’examen de sécurité d’Anthropic, mais cela ne garantit pas qu’ils se comportent comme prévu. Vérifiez l’éditeur, le code inclus et les serveurs MCP. La conception des autorisations du chapitre 5 s’applique ici aussi au code écrit par d’autres.

Par quoi commencer : un mot sur l'ordre

Six extensions ont été alignées, mais il n'est pas nécessaire de tout installer. En installer avant d'avoir le problème n'ajoute que de la complexité de configuration. L'ordre part du symptôme.

Vous donnez toujours la même explication → CLAUDE.md. Si cela ne concerne qu'un travail précis, plutôt Skills
C’est écrit mais non respecté → contrôler le chargement, la portée et les conflits. Confier les conditions vérifiables mécaniquement aux hooks
Le contexte se remplit tout de suite → confier les recherches lourdes aux subagents, et désactiver les MCP inutiles
L'IA n'atteint pas l'information → MCP. Branchez un serveur à la fois, et passez au suivant une fois celui-ci fonctionnel
Vous voulez distribuer les mêmes réglages → plugins. Ne rassemblez que ce que vous utilisez déjà vous-même
Rien ne vous gêne particulièrement → n'installez rien. C'est le meilleur des états

La dernière ligne n'est pas une plaisanterie. Les extensions multiplient aussi les causes de blocage : le « Claude Code est bizarre » se révèle souvent être une couche que vous avez ajoutée vous-même. C'est pour cela que le diagnostic du chapitre 4 vient d'abord.

Résumé

Le critère de choix, ce sont quatre questions : une demande suffit-elle (CLAUDE.md, Skills), voulez-vous que cela s'applique à coup sûr (hooks), voulez-vous séparer le contexte (subagents), voulez-vous vous relier à l'extérieur (MCP). Pour distribuer, plugins
CLAUDE.md conserve des consignes persistantes. Le fichier racine est réinjecté après compression. Le raccourcir ne garantit pas le respect des règles : vérifiez séparément chargement et comportement
Les hooks de type command sont lancés par Claude Code lorsque les conditions configurées correspondent. Vérifiez les chemins d’exécution et le blocage ; un hook exécuté après coup ne peut pas annuler une opération terminée
Les subagents travaillent dans un autre contexte et ne rendent qu'un résumé. Ils ne conviennent ni au traitement séquentiel ni aux allers-retours fréquents
Les Skills utilisent la divulgation progressive : leur corps s’ouvre au besoin. Rédigez des descriptions précises pour la sélection automatique et vérifiez les résultats de la procédure même après une invocation explicite
MCP est un standard d’accès externe. Diagnostiquez les problèmes en combinant le statut de /mcp avec le mode de connexion et les détails de l’erreur
Les plugins sont la boîte de distribution. Du code écrit par d'autres tourne avec vos droits, alors vérifiez l'éditeur
L'ordre d'installation part du symptôme. Un élément à la fois, une fois la gêne apparue

La comparaison des outils eux-mêmes, pour choisir entre eux, se trouve dans le chapitre 6 « Étendre les capacités avec les extensions » du cours de programmation avec l'IA.

Plus vous étendez, plus la consommation augmente. Pour finir, nous traitons l'exploitation sur la durée. Passez au chapitre 7, « Coût et limites ».

L'étendre — CLAUDE.md, hooks, subagents et MCP