Claude Code CLI : guide expert (hooks, sub-agents, MCP, slash commands)

Architecture de Claude Code (rappel rapide)

Claude Code est un agent CLI développé par Anthropic, écrit en Node.js et distribué via npm. Il expose le modèle Claude à un ensemble de tools intégrés qui lui permettent d'agir sur votre système de fichiers et votre terminal, sans que vous ayez à écrire de code d'orchestration.

Le runtime Node.js et le SDK Anthropic

Sous le capot, Claude Code utilise le SDK Anthropic (TypeScript) pour envoyer les messages au modèle et recevoir les appels de tools en streaming. Chaque tour de conversation correspond à un appel API avec la liste des tools disponibles dans le contexte. Le runtime gère le prompt caching automatiquement pour réduire la latence et les coûts sur les sessions longues.

Le système de tools intégrés

Claude Code embarque nativement sept catégories de tools :

• Read : lecture de fichiers avec pagination
• Write : écriture complète d'un fichier
• Edit : remplacement de sous-chaîne (plus économique que Write sur les gros fichiers)
• Bash : exécution de commandes shell avec timeout configurable
• Grep : recherche regex via ripgrep
• Glob : recherche de fichiers par pattern
• Agent (Task) : délégation à un sous-agent avec son propre contexte

Les tools MCP s'ajoutent à cette liste dès qu'un serveur est configuré. Voir la section flux agentiques Claude Code pour comprendre comment ces tools s'articulent dans une session.

settings.json et la hiérarchie

La configuration de Claude Code repose sur deux niveaux superposés :

• Niveau utilisateur : ~/.claude/settings.json (s'applique à tous vos projets)
• Niveau projet : .claude/settings.json à la racine du projet (s'applique au projet courant)

En cas de conflit, la règle projet prend la priorité sur la règle utilisateur. C'est l'inverse de ce qu'on pourrait attendre : les settings projet sont plus spécifiques et donc plus forts. Gardez les hooks globaux (sécurité, logging) au niveau utilisateur, et les hooks métier (sync de partials, validation SEO) au niveau projet.

Les hooks : intercepter chaque action

Les hooks sont la fonctionnalité la plus puissante pour automatiser les vérifications et les effets secondaires dans Claude Code. Un hook est une commande shell qui s'exécute automatiquement à un moment précis du cycle de vie de l'agent.

PreToolUse : valider avant exécution

PreToolUse se déclenche avant que le tool soit exécuté. Il reçoit en entrée (via stdin) un objet JSON décrivant l'appel de tool : nom du tool, paramètres, contexte de session. Si votre script retourne un code non-zéro, l'exécution du tool est bloquée et le message d'erreur est transmis au modèle.

Cas d'usage typique : refuser une commande rm -rf sur un répertoire de production. Votre script analyse le paramètre command du tool Bash, détecte la chaîne dangereuse et retourne un message d'erreur explicite. Le modèle reçoit ce message et peut proposer une alternative moins risquée.

PostToolUse : réagir après

PostToolUse se déclenche après chaque exécution de tool, qu'elle ait réussi ou échoué. C'est là que se configurent les effets secondaires déterministes : synchronisation, validation, notification.

Sur AzenFlow, ce hook synchronise automatiquement les partials header.html et footer.html vers toutes les pages du site dès qu'on modifie ces fichiers. Résultat : impossible d'oublier de propager une modification du bandeau de navigation.

SessionStart : charger du contexte personnalisé

SessionStart se déclenche une seule fois, au démarrage de chaque session Claude Code. Il sert à injecter du contexte dynamique que le fichier CLAUDE.md statique ne peut pas fournir : date du jour, état du dépôt git, variables d'environnement, résultat d'un appel API.

UserPromptSubmit : pré-traiter les prompts

UserPromptSubmit se déclenche à chaque fois que vous soumettez un message dans la session. Il permet d'enrichir ou de valider le prompt avant qu'il atteigne le modèle : ajouter un contexte automatique (numéro de ticket Jira, branche git active), ou bloquer des requêtes hors périmètre.

Voici un exemple complet de settings.json projet illustrant PostToolUse et SessionStart :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(jq -r '.tool_input.file_path'); case \"$FILE\" in *_partials/header.html) python _sync_header.py;; *_partials/footer.html) python _sync_footer.py;; esac"
          }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/audit/check-seo.js"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Cabinet de stratégie IA loaded'"
          },
          {
            "type": "command",
            "command": "git log -1 --format='Dernier commit : %s (%ar)'"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/security/check-dangerous-cmd.js"
          }
        ]
      }
    ]
  }
}

Le filtrage par chemin se fait à l'intérieur du script du hook en parsant le JSON reçu sur stdin (typiquement avec jq sur le champ tool_input.file_path), pas via un champ de configuration. Claude Code n'expose pas de champ fileFilter : le matcher agit sur le nom du tool (Edit, Write, Bash), et toute granularité supplémentaire (par extension, par chemin) doit être implémentée dans le script. Sans ce filtrage interne, la commande de sync tournerait à chaque modification de n'importe quel fichier.

Une alternative documentée par Anthropic : utiliser le champ if avec la syntaxe permission rule du settings, par exemple "if": "Edit(*.ts)" pour ne déclencher le hook que sur les fichiers TypeScript. Choisissez le champ if quand le filtre tient sur un pattern simple, et le parsing stdin quand vous avez besoin de logique conditionnelle plus riche.

Sub-agents : paralléliser le travail

Le tool Agent (également appelé Task) permet à Claude Code de déléguer une sous-tâche à un agent fils qui s'exécute dans son propre contexte isolé. Le sous-agent ne voit pas l'historique de la session parente : il reçoit uniquement le prompt que l'orchestrateur lui transmet.

Le tool Agent (a.k.a. Task)

Lorsque vous demandez à Claude Code d'analyser 20 fichiers HTML en parallèle, l'agent orchestrateur peut lancer 20 appels Task simultanément. Chaque Task reçoit un prompt spécifique et retourne son résultat à l'orchestrateur qui agrège. Comparé à un traitement séquentiel, le gain de temps est proportionnel au nombre de tâches parallèles, limité par les quotas API Anthropic.

Sub-agents spécialisés via .claude/agents/

Claude Code supporte la définition de sub-agents spécialisés sous forme de fichiers Markdown dans le répertoire .claude/agents/. Chaque fichier définit le persona, le périmètre et les instructions d'un agent réutilisable. L'orchestrateur peut invoquer ces agents par leur nom.

Exemple de fichier .claude/agents/seo-analyst.md :

---
name: seo-analyst
description: Audit SEO technique d'une page HTML AzenFlow. Vérifie title, meta description, H1, Open Graph, Twitter Cards, schema JSON-LD, canonical, accents et typographie.
model: claude-haiku-4-5
---

# Rôle
Rôle : auditeur SEO technique spécialisé sur le site AzenFlow.

# Périmètre
Analyser uniquement les critères SEO techniques définis dans .claude/rules/html-seo.md.
Ne pas faire de recommandations éditoriales ni de suggestions de contenu.

# Format de sortie
Retourne un objet JSON avec les champs :
- score : entier de 0 à 17 (un point par critère)
- issues : tableau de strings décrivant les problèmes trouvés
- ok : tableau de strings listant les critères validés

Notez le champ model : vous pouvez assigner un modèle moins coûteux (Haiku) aux tâches simples et réserver Sonnet ou Opus pour l'orchestration et les tâches complexes. Sur un audit de 50 pages, l'économie est substantielle.

Pattern dispatching-parallel-agents

Le pattern consiste à confier à l'agent orchestrateur la décomposition de la tâche, le lancement parallèle des sous-agents, puis l'agrégation des résultats. Voir le guide sur les flux agentiques Claude Code pour une description détaillée de ce pattern.

Sur AzenFlow, cette approche est utilisée pour les audits d'accents sur les 200+ pages HTML : l'orchestrateur répartit les fichiers en 12 lots, chaque lot est traité par un sous-agent Haiku, et l'orchestrateur agrège les findings en un rapport unifié.

Quand un sub-agent est rentable, quand il ne l'est pas

Un sub-agent est rentable quand :

• La tâche est indépendante (pas de dépendance à l'état de la session parente)
• Le volume justifie la parallélisation (10+ éléments à traiter)
• Un modèle moins cher peut faire le travail

Un sub-agent n'est pas rentable quand :

• La tâche nécessite le contexte complet de la session parente
• Il y a moins de 3 éléments à traiter (le overhead de lancement est supérieur au gain)
• La tâche est séquentielle par nature (chaque étape dépend de la précédente)

Serveurs MCP dans Claude Code

Le Model Context Protocol (MCP) est le standard ouvert d'Anthropic pour étendre les capacités d'un agent IA via des serveurs de tools externes. Dans Claude Code, chaque serveur MCP configuré ajoute ses tools à la liste disponible pour le modèle. Consultez le guide architecture MCP serveur pour les fondamentaux, et le comparatif technique MCP vs Claude Code CLI 2026 pour le positionnement des deux approches.

Configuration via settings.json

Les serveurs MCP se configurent dans le champ mcpServers du settings.json :

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/chemin/vers/projet"],
      "type": "stdio"
    },
    "n8n-workflows": {
      "command": "node",
      "args": ["./mcp-servers/n8n-adapter.js"],
      "type": "stdio",
      "env": {
        "N8N_API_KEY": "${N8N_API_KEY}",
        "N8N_BASE_URL": "https://votre-instance.n8n.cloud"
      }
    }
  }
}

Différence avec Claude Desktop

Claude Code supporte trois transports MCP : stdio (processus local lancé par Claude Code, idéal pour les outils sur la même machine), HTTP (recommandé par Anthropic pour les serveurs distants cloud), et SSE (Server-Sent Events, déprécié et conservé pour compatibilité). Pour ajouter un serveur distant, utilisez la commande claude mcp add --transport http <name> <url>, ou déclarez "type": "http" et "url": "..." dans .mcp.json. Claude Desktop partage la même architecture mais s'utilise depuis son interface graphique au lieu du terminal. Les variables d'environnement sont héritées de la session CLI ou définies dans le settings avec la syntaxe ${VAR}.

Cas pratique : un serveur MCP n8n pour exposer les workflows

L'intégration la plus utile pour AzenFlow : un serveur MCP local qui expose l'API n8n comme ensemble de tools. Claude Code peut alors : lister les workflows actifs, déclencher un workflow par son ID, récupérer les logs d'exécution, créer un nouveau workflow depuis un template. Cela transforme Claude Code en copilote de vos automatisations n8n, directement depuis votre terminal. Découvrez notre prestation n8n + IA pour intégrer ces architectures sur vos projets.

Slash commands et skills

Les slash commands sont le moyen le plus simple de créer des raccourcis pour vos tâches récurrentes. Vous les invoquez en tapant /nom-de-la-commande dans la session Claude Code.

Slash commands custom dans .claude/commands/

Un slash command est un fichier Markdown placé dans .claude/commands/. Le nom du fichier (sans extension) devient le nom de la commande. Le contenu du fichier est injecté comme prompt au moment de l'invocation. Vous pouvez utiliser des variables avec la syntaxe $ARGUMENTS pour passer des paramètres.

Crée un squelette d'article de blog AzenFlow pour le slug : $ARGUMENTS

Règles obligatoires :
- Exécute d'abord : python _build_blog_article.py "$ARGUMENTS"
- Ouvre le fichier généré dans blog/$ARGUMENTS.html
- Vérifie que data-blog-category et data-blog-tags sont présents
- Confirme que le H1 est accentué et en vouvoiement
- Retourne un résumé des champs à compléter manuellement

Skills : l'abstraction 2026

Un skill est une abstraction plus riche qu'un slash command : il peut inclure de la logique conditionnelle, des déclencheurs automatiques (via hooks), des références à des sub-agents spécialisés, et une documentation plus structurée. Les skills sont définis dans settings.json ou dans des fichiers dédiés dans .claude/skills/. La distinction pratique : un slash command est un prompt, un skill est un mini-workflow.

Exemple AzenFlow : /seo-geo-refresh

Le skill /seo-geo-refresh d'AzenFlow illustre la puissance de l'abstraction : il orchestre 6 phases d'audit successives (baseline, analyse, patches, vérification), lance des sub-agents spécialisés (seo-analyst, geo-strategist), et inclut 3 checkpoints de décision avec Matthias avant de commiter les changements. Impossible à représenter comme un simple slash command.

Mode headless et intégration n8n

Le mode headless permet d'appeler Claude Code de manière non-interactive, depuis un script, un pipeline CI, ou un noeud n8n. C'est la clé pour intégrer l'intelligence de Claude dans vos automatisations sans passer par l'API Anthropic directement.

claude --print / mode non-interactif

Le flag --print (alias -p) désactive l'interface interactive et retourne la réponse sur stdout. Claude Code auto-charge le CLAUDE.md du répertoire courant, donc pas besoin de flag dédié pour passer le contexte projet :

# Appel simple (CLAUDE.md du cwd est auto-charge)
cd mon-projet/ && claude -p "Analyse le fichier index.html et retourne les 3 principaux problèmes SEO en JSON"

# Injecter un contexte additionnel via stdin
cat brief-edito.md | claude -p "Génère un plan d'article SEO conforme à ce brief"

# Ajouter des règles ponctuelles au prompt système
claude -p --append-system-prompt-file ./style-rules.txt "Audit SEO de blog/nouveau-article.html"

# Sortie JSON structurée
claude -p --output-format json "Audit SEO de blog/nouveau-article.html"

Pour les pipelines CI où la rapidité prime sur le contexte projet, le flag --bare (mode minimal) skippe l'auto-discovery du CLAUDE.md, des hooks, skills, plugins et serveurs MCP. Le démarrage est sensiblement plus rapide, et Claude conserve l'accès aux tools Bash, Read et Edit. Utile quand vous n'avez besoin que d'une réponse ponctuelle sans charger toute la configuration du projet.

# Mode minimal : pas de CLAUDE.md, pas de hooks, pas de MCP
claude --bare -p "Reformule ce paragraphe en vouvoiement"

Wrapper webhook n8n pour appeler Claude Code en CI

Dans un workflow n8n, le noeud Execute Command peut appeler Claude Code en mode headless et récupérer la sortie pour la traiter dans les noeuds suivants. Voici le pattern recommandé :

1. Un webhook n8n reçoit l'événement déclencheur (nouveau commit, formulaire soumis, cron)
2. Un noeud Set construit le prompt en interpolant les données de l'événement
3. Un noeud Execute Command appelle claude --print "{{ $json.prompt }}"
4. Un noeud JSON Parse extrait le résultat structuré
5. Les noeuds suivants utilisent le résultat (notification Slack, mise à jour base de données, etc.)

Pour les pipelines d'intégration n8n plus complexes, notre équipe peut vous accompagner : consultez la page audit technique.

Coût et latence comparés à l'API directe

Le coût par appel headless est identique à l'API Anthropic directe : vous payez les tokens consommés au même tarif. La latence est légèrement supérieure : 200 à 400 ms de surcoût lié au démarrage du process Node.js et à l'initialisation du runtime Claude Code. Pour les appels fréquents (plusieurs par minute), préférez l'API directe ou maintenez un process Claude Code en mode daemon. Pour les appels peu fréquents (toutes les heures ou moins), le mode headless est parfaitement adapté et offre l'avantage de réutiliser la configuration du projet (settings.json, CLAUDE.md, hooks).

Pièges connus et debugging

Boucles de hooks (PostToolUse qui re-déclenche un Edit)

Le piège classique : un hook PostToolUse sur le matcher Edit qui lui-même modifie un fichier via un script Python. Si ce script utilise la même API que Claude Code pour écrire le fichier, il peut déclencher à nouveau le hook, créant une boucle infinie. La solution : filtrer dans le script du hook lui-même (jq sur tool_input.file_path reçu sur stdin) et exclure explicitement les fichiers cibles du sync pour éviter la boucle. Comme Claude Code n'expose pas de champ fileFilter, ce verrouillage doit toujours être codé côté script.

Sub-agents qui explosent le budget tokens

Chaque sub-agent consomme son contexte complet : le prompt transmis par l'orchestrateur, plus les tools disponibles, plus sa propre chaîne de raisonnement. Sur un dispatching de 50 agents simultanés sur un problème complexe, la consommation peut dépasser 2M de tokens en quelques minutes. Stratégies de maîtrise : limiter le nombre d'agents parallèles (10 à 15 maximum par vague), utiliser Haiku pour les tâches simples, transmettre le minimum d'informations nécessaires dans le prompt du sous-agent.

Contexte projet trop volumineux (CLAUDE.md > 50 KB)

Un CLAUDE.md trop volumineux est chargé dans chaque tour de conversation, réduisant la fenêtre de contexte disponible pour le travail réel et augmentant les coûts. Maintenez le fichier principal sous 30 KB. Pour les règles sectorielles ou techniques détaillées, utilisez des fichiers séparés dans .claude/rules/ et référencez-les dans CLAUDE.md avec un commentaire explicatif. Claude Code ne charge les fichiers de règles que lorsqu'ils sont explicitement mentionnés ou inclus.