Architecture d'agents : concevoir des harnais de développement propulsés par l'IA

TL;DR : Claude Code n’est pas une simple boîte de dialogue avec accès aux fichiers. C’est un runtime programmable doté de 22 événements de cycle de vie, chacun interceptable par des scripts shell que le modèle ne peut pas contourner. Empilez des hooks dans des dispatchers, des dispatchers dans des skills, des skills dans des agents, des agents dans des workflows, et vous obtenez un harness de développement autonome qui applique des contraintes, délègue le travail, persiste la mémoire entre les sessions et orchestre la délibération multi-agents. Ce guide couvre chaque couche de cette architecture : d’un simple hook à un système de consensus à 10 agents. Aucun framework requis. Uniquement du bash et du JSON.

Andrej Karpathy a forgé un terme pour désigner ce qui se développe autour d’un agent LLM : les griffes (claws). Les hooks, scripts et mécanismes d’orchestration qui permettent à l’agent de saisir le monde au-delà de sa fenêtre de contexte.¹ La plupart des développeurs traitent les agents de codage IA comme des assistants interactifs. Ils saisissent un prompt, observent l’agent modifier un fichier, puis passent à autre chose. Cette vision limite la productivité à ce que vous pouvez personnellement superviser.

Le modèle mental d’infrastructure est différent : un agent de codage IA est un runtime programmable avec un noyau LLM. Chaque action du modèle passe par des hooks que vous contrôlez. Vous définissez des politiques, pas des prompts. Le modèle opère au sein de votre infrastructure de la même manière qu’un serveur web opère sous les règles nginx. Vous ne vous asseyez pas devant nginx pour saisir des requêtes. Vous le configurez, le déployez et le surveillez.

Cette distinction est cruciale, car l’infrastructure produit des effets composés. Un hook qui bloque les identifiants dans les commandes bash protège chaque session, chaque agent, chaque exécution autonome. Un skill qui encode votre grille d’évaluation s’applique de manière cohérente, que vous l’invoquiez ou qu’un agent le fasse. Un agent qui audite le code en matière de sécurité exécute les mêmes vérifications, que vous soyez présent ou non.²

Points clés

• Les hooks garantissent l’exécution ; les prompts non. Utilisez les hooks pour le linting, le formatage, les vérifications de sécurité et tout ce qui doit s’exécuter à chaque fois, indépendamment du comportement du modèle. Le code de sortie 2 bloque les actions. Le code de sortie 1 émet uniquement un avertissement.³
• Les skills encodent une expertise métier qui s’active automatiquement. Le champ description détermine tout. Claude utilise le raisonnement LLM (et non la correspondance par mots-clés) pour décider quand appliquer un skill.⁴
• Les subagents évitent l’engorgement du contexte. Des fenêtres de contexte isolées pour l’exploration et l’analyse maintiennent la session principale légère. Jusqu’à 10 peuvent s’exécuter en parallèle.⁵
• La mémoire réside dans le système de fichiers. Les fichiers persistent au-delà des fenêtres de contexte. CLAUDE.md, MEMORY.md, les répertoires de rules et les documents de passation forment un système de mémoire externe structuré.⁶
• La délibération multi-agents détecte les angles morts. Un agent seul ne peut pas remettre en question ses propres hypothèses. Deux agents indépendants, avec des priorités d’évaluation différentes, détectent des défaillances structurelles que les quality gates ne peuvent pas couvrir.⁷
• Le harness pattern constitue le système. CLAUDE.md, hooks, skills, agents et mémoire ne sont pas des fonctionnalités indépendantes. Ils se composent en une couche déterministe entre vous et le modèle, qui s’adapte à l’automatisation.

Comment utiliser ce guide

Chaque section s’appuie sur la précédente. Le cadre de décision en fin de guide fournit une table de correspondance pour choisir le mécanisme adapté à chaque type de problème.

Parcours express en cinq minutes

Avant d’entrer dans le vif du sujet, voici le chemin le plus court pour passer de zéro à un harness fonctionnel. Un hook, un skill, un subagent, un résultat.

Étape 1 : Créer un hook de sécurité (2 minutes)

Créez .claude/hooks/block-secrets.sh :

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

Reliez-le dans .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

Résultat : Chaque commande bash exécutée par Claude est désormais analysée pour détecter toute fuite d’identifiants. Le modèle ne peut pas contourner cette vérification.

Étape 2 : Créer un skill de revue de code (1 minute)

Créez .claude/skills/reviewer/SKILL.md avec un frontmatter (name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob) et une checklist : injection SQL, XSS, secrets codés en dur, gestion d’erreurs manquante, fonctions de plus de 50 lignes.

Résultat : Claude active automatiquement cette expertise dès que vous mentionnez « review », « check » ou « audit ».

Étape 3 : Lancer un subagent (30 secondes)

Dans n’importe quelle session Claude Code, demandez à Claude d’examiner les 3 derniers commits pour détecter des problèmes de sécurité en utilisant un agent séparé. Claude lance un agent Explore qui lit le diff, applique votre skill de revue et renvoie un résumé. Votre contexte principal reste intact.

Ce que vous avez désormais

Un harness à trois couches : une porte de sécurité déterministe (hook), une expertise métier qui s’active automatiquement (skill) et une analyse isolée qui protège votre contexte (subagent). Chaque section ci-dessous approfondit l’une de ces trois couches.

Pourquoi l’architecture agent est essentielle

Simon Willison résume le moment actuel par une observation unique : écrire du code est devenu bon marché.⁸ C’est exact. Toutefois, le corollaire est que la vérification constitue désormais la partie coûteuse. Du code bon marché sans infrastructure de vérification produit des bugs à grande échelle. L’investissement rentable n’est pas un meilleur prompt, mais le système autour du modèle qui rattrape ce que le modèle laisse passer.

Trois forces rendent l’architecture agent indispensable :

Les fenêtres de contexte sont finies et sujettes aux pertes. Chaque lecture de fichier, sortie d’outil et tour de conversation consomme des tokens. Microsoft Research et Salesforce ont testé 15 LLM à travers plus de 200 000 conversations simulées et ont constaté une baisse de performance moyenne de 39 % entre l’interaction à un seul tour et l’interaction multi-tours.⁹ La dégradation commence dès deux tours et suit une courbe prévisible : des modifications multi-fichiers précises dans les 30 premières minutes se transforment en vision tunnel sur un seul fichier après 90 minutes. Des fenêtres de contexte plus larges ne résolvent pas le problème. La condition « Concat » de la même étude (la conversation complète en un seul prompt) a atteint 95,1 % de la performance mono-tour avec un contenu identique. La dégradation provient des frontières entre les tours, pas des limites de tokens.

Le comportement du modèle est probabiliste, pas déterministe. Dire à Claude « lance toujours Prettier après avoir modifié des fichiers » fonctionne environ 80 % du temps.³ Le modèle peut oublier, privilégier la rapidité ou décider que le changement est « trop mineur ». Pour la conformité, la sécurité et les standards d’équipe, 80 % n’est pas acceptable. Les hooks garantissent l’exécution : chaque Edit ou Write déclenche votre formateur, à chaque fois, sans exception. Le déterministe l’emporte sur le probabiliste.

Une perspective unique ne suffit pas face aux problèmes multidimensionnels. Un seul agent examinant un endpoint API a vérifié l’authentification, validé l’assainissement des entrées et contrôlé les en-têtes CORS. Résultat : aucun problème détecté. Un second agent, sollicité séparément en tant que testeur d’intrusion, a découvert que l’endpoint acceptait des paramètres de requête sans limite, susceptibles de déclencher un déni de service par amplification des requêtes en base de données.⁷ Le premier agent n’avait jamais vérifié ce point car rien dans son cadre d’évaluation ne traitait la complexité des requêtes comme une surface d’attaque. Cette lacune est structurelle. Aucun prompt engineering ne peut la combler.

L’architecture agent répond à ces trois enjeux : les hooks imposent des contraintes déterministes, les subagents gèrent l’isolation du contexte et l’orchestration multi-agents fournit des perspectives indépendantes. Ensemble, ils forment le harness.

Le pattern Harness

Le harness n’est pas un framework. C’est un pattern : un ensemble composable de fichiers, scripts et conventions qui enveloppent un agent de développement IA dans une infrastructure déterministe. Les composants :

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

Couche d’instructions : Les fichiers CLAUDE.md et les répertoires de rules définissent ce que l’agent sait de votre projet. Ils se chargent automatiquement au démarrage de la session et après chaque compaction. C’est la mémoire architecturale à long terme de l’agent.

Couche d’extension : Les skills fournissent une expertise métier qui s’active automatiquement en fonction du contexte. Les hooks offrent des portes déterministes qui se déclenchent à chaque appel d’outil correspondant. Les fichiers de mémoire persistent l’état entre les sessions. Les agents personnalisés fournissent des configurations de subagents spécialisés.

Couche d’orchestration : Les patterns multi-agents coordonnent des agents indépendants pour la recherche, la revue et la délibération. Les budgets de lancement préviennent la récursion incontrôlée. La validation par consensus garantit la qualité.

L’enseignement clé : la plupart des utilisateurs travaillent exclusivement dans la couche Core, observant leur contexte gonfler et leurs coûts grimper. Les utilisateurs avancés configurent les couches Instruction et Extension, puis n’utilisent la couche Core que pour l’orchestration et les décisions finales.²

Ce à quoi ressemble le Harness sur disque

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

Chaque fichier de cette structure a une raison d’être. L’arborescence ~/.claude/ constitue l’infrastructure personnelle qui s’applique à tous les projets. L’arborescence .claude/ dans chaque dépôt est spécifique au projet et partagée via git. Ensemble, elles forment le harness complet.

Système de skills

Les skills sont des extensions invoquées par le modèle. Claude les découvre et les applique automatiquement en fonction du contexte, sans que vous ayez besoin de les appeler explicitement.⁴ Dès que vous vous surprenez à réexpliquer le même contexte d’une session à l’autre, c’est le moment de créer un skill.

Quand créer un skill

Les skills servent aux connaissances que Claude a toujours à disposition. Les slash commands servent aux actions que vous déclenchez explicitement. Si vous hésitez entre les deux, posez-vous la question : « Claude doit-il appliquer cela automatiquement, ou est-ce à moi de décider quand l’exécuter ? »

Créer un skill

Les skills peuvent résider dans quatre emplacements, du périmètre le plus large au plus restreint :⁴

Chaque skill nécessite un fichier SKILL.md avec un frontmatter YAML :

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Référence du frontmatter

Le champ description est déterminant

Au démarrage de la session, Claude Code extrait le name et la description de chaque skill et les injecte dans le contexte de Claude. Lorsque vous envoyez un message, Claude utilise le raisonnement du modèle de langage pour déterminer si un skill est pertinent. L’analyse indépendante du code source de Claude Code confirme le mécanisme : les descriptions de skills sont injectées dans une section available_skills du prompt système, et le modèle utilise sa compréhension linguistique standard pour sélectionner les skills pertinents.¹⁰

Mauvaise description :

description: Helps with code

Description efficace :

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

La description efficace inclut : ce qu’il fait (examiner le code pour des types de problèmes spécifiques), quand l’utiliser (examen de modifications, PRs, analyse de qualité), et des expressions déclencheuses (review, audit, check) que les utilisateurs tapent naturellement.

Budget de contexte

Toutes les descriptions de skills partagent un budget de contexte qui s’adapte dynamiquement à 2 % de la fenêtre de contexte, avec un minimum de 16 000 caractères.⁴ Si vous avez de nombreux skills, gardez chaque description concise. Vous pouvez ajuster le budget via la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ mais la meilleure solution reste des descriptions plus courtes et plus précises. Exécutez /context pendant une session pour vérifier si des skills sont exclus.

Fichiers complémentaires et organisation

Les skills peuvent référencer des fichiers supplémentaires dans le même répertoire :

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Référencez-les depuis SKILL.md avec des liens relatifs. Claude lit ces fichiers à la demande lorsque le skill s’active. Maintenez SKILL.md sous 500 lignes et déplacez le matériel de référence détaillé vers les fichiers complémentaires.¹²

Partager des skills via Git

Les skills de projet (.claude/skills/ à la racine du dépôt) se partagent via le contrôle de version :⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Lorsque vos coéquipiers tirent les modifications, ils obtiennent le skill automatiquement. Pas d’installation, pas de configuration. C’est le moyen le plus efficace de standardiser l’expertise au sein d’une équipe.

Les skills comme bibliothèque de prompts

Au-delà des skills à usage unique, la structure de répertoires fonctionne comme une bibliothèque de prompts organisée :

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Chaque skill encode une facette différente de votre expertise. Ensemble, ils forment une base de connaissances dans laquelle Claude puise automatiquement en fonction du contexte. Un développeur junior bénéficie de conseils de niveau senior sans avoir à les demander.

Les skills se combinent avec les hooks

Les skills peuvent définir leurs propres hooks dans le frontmatter, qui ne s’activent que pendant l’exécution du skill. Cela crée un comportement spécifique au domaine qui ne pollue pas les autres sessions :²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

Les skills de philosophie s’activent automatiquement via des hooks SessionStart, injectant des contraintes de qualité dans chaque session sans invocation explicite. Le skill en lui-même est la connaissance. Le hook est l’application. Ensemble, ils forment une couche de politique.

Erreurs courantes avec les skills

Descriptions trop larges. Un skill git-rebase-helper qui s’active sur n’importe quel prompt lié à git (rebases, merges, cherry-picks, même git status) pollue le contexte dans 80 % des sessions. La solution consiste soit à resserrer la description, soit à ajouter disable-model-invocation: true et à exiger l’invocation explicite via /skill-name.⁴

Trop de skills en compétition pour le budget. Plus de skills signifie plus de descriptions en compétition pour le budget de contexte de 2 %. Si vous constatez que des skills ne s’activent pas, vérifiez avec /context lesquels sont exclus. Privilégiez un nombre réduit de skills bien décrits plutôt que de nombreux skills vagues.

Informations critiques enfouies dans les fichiers complémentaires. Claude lit SKILL.md immédiatement mais n’accède aux fichiers complémentaires qu’en cas de besoin. Si une information critique se trouve dans un fichier complémentaire, Claude risque de ne pas la trouver. Placez les informations essentielles directement dans SKILL.md.⁴

Architecture des hooks

Les hooks sont des commandes shell déclenchées par les événements du cycle de vie de Claude Code.³ Ils s’exécutent en dehors du LLM sous forme de scripts classiques, et non de prompts interprétés par le modèle. Le modèle veut exécuter rm -rf / ? Un script bash de 10 lignes vérifie la commande par rapport à une liste de blocage et la rejette avant même que le shell ne la voie. Le hook se déclenche que le modèle le veuille ou non.

Événements disponibles

Claude Code expose plus de 26 événements de cycle de vie répartis en sept catégories (la liste s’enrichit à chaque version — consultez l’aide-mémoire pour le tableau complet à jour) :¹³

Sémantique des codes de sortie

Les codes de sortie déterminent si les hooks bloquent les actions :³

Point critique : chaque hook de sécurité doit utiliser exit 2, et non exit 1. Exit 1 est un avertissement non bloquant. La commande dangereuse s’exécute quand même. C’est l’erreur de hook la plus fréquente d’une équipe à l’autre.¹⁴

Configuration des hooks

Les hooks résident dans les fichiers de paramètres. Au niveau projet (.claude/settings.json) pour les hooks partagés. Au niveau utilisateur (~/.claude/settings.json) pour les hooks personnels :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Le champ matcher est une expression régulière correspondant aux noms d’outils : Bash, Write, Edit, Read, Glob, Grep, Agent, ou * pour tous les outils. Utilisez "" (chaîne vide) pour les événements sans outil comme UserPromptSubmit.

Protocole d’entrée/sortie des hooks

Les hooks reçoivent du JSON sur stdin avec le contexte complet :

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

Pour un contrôle avancé, les hooks PreToolUse peuvent produire du JSON en sortie afin de modifier l’entrée de l’outil, injecter du contexte ou prendre des décisions de permission. Utilisez le wrapper hookSpecificOutput — l’ancien format decision/reason de niveau supérieur est déprécié pour PreToolUse :

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Trois types de garanties

Avant d’écrire un hook, posez-vous la question : quel type de garantie me faut-il ?¹⁴

Les garanties de formatage assurent la cohérence après coup. Les hooks PostToolUse sur Write/Edit exécutent votre formateur après chaque modification de fichier. Peu importe la sortie du modèle, le formateur normalise tout.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Les garanties de sécurité empêchent les actions dangereuses avant leur exécution. Les hooks PreToolUse sur Bash inspectent les commandes et bloquent les schémas destructeurs avec le code de sortie 2 :

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

Les garanties de qualité valident l’état aux points de décision. Les hooks PreToolUse sur les commandes git commit exécutent votre linter ou votre suite de tests et bloquent le commit si les vérifications de qualité échouent :

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

Types de hooks au-delà des commandes shell

Claude Code prend en charge quatre types de hooks :¹³

Les hooks de commande (type: "command") exécutent des scripts shell. Rapides, déterministes, sans coût en tokens.

Les hooks de prompt (type: "prompt") envoient un prompt en un seul tour à un modèle Claude rapide. Le modèle renvoie { "ok": true } pour autoriser ou { "ok": false, "reason": "..." } pour bloquer. À utiliser pour une évaluation nuancée que les expressions régulières ne peuvent exprimer.

Les hooks d’agent (type: "agent") lancent un subagent avec accès aux outils (Read, Grep, Glob) pour une vérification en plusieurs tours. À utiliser lorsque la vérification nécessite d’inspecter des fichiers réels ou des résultats de tests :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Les hooks HTTP (type: "http") envoient l’entrée JSON de l’événement sous forme de requête POST vers une URL et reçoivent du JSON en retour. À utiliser pour les webhooks, les services de notification externes ou la validation basée sur un API (v2.1.63+). Non pris en charge pour les événements SessionStart :

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Hooks asynchrones

Les hooks peuvent s’exécuter en arrière-plan sans bloquer l’exécution. Ajoutez async: true pour les opérations non critiques comme les notifications et la journalisation :¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

Utilisez le mode asynchrone pour les notifications, la télémétrie et les sauvegardes. Ne l’utilisez jamais pour le formatage, la validation ou toute opération devant se terminer avant l’action suivante.

Dispatchers plutôt que hooks indépendants

Sept hooks déclenchés simultanément sur le même événement, chacun lisant stdin de manière indépendante, créent des conditions de concurrence. Deux hooks écrivant dans le même fichier d’état JSON en parallèle tronqueront le JSON. Tous les hooks en aval qui analysent ce fichier échouent.²

La solution : un dispatcher unique par événement qui exécute les hooks séquentiellement à partir du stdin mis en cache :

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Débogage des hooks

Cinq techniques pour déboguer les hooks qui échouent silencieusement :¹⁴

1. Testez les scripts de manière indépendante. Transmettez un échantillon JSON via pipe : echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Utilisez stderr pour la sortie de débogage. La sortie d’erreur du code de sortie 2 est retransmise au Claude comme message d’erreur. La sortie d’erreur non bloquante (exit 1, 3, etc.) n’apparaît qu’en mode verbeux (Ctrl+O).
3. Surveillez les échecs de jq. Des chemins JSON incorrects renvoient null silencieusement. Testez vos expressions jq contre de vraies entrées d’outils.
4. Vérifiez les codes de sortie. Un hook PreToolUse utilisant exit 1 n’applique aucune contrainte tout en donnant l’impression de fonctionner.
5. Gardez les hooks rapides. Les hooks s’exécutent de manière synchrone. Maintenez tous les hooks sous les 2 secondes, idéalement sous les 500 ms.

Mémoire et contexte

Toute conversation avec une IA s’inscrit dans une fenêtre de contexte finie. À mesure que la conversation s’allonge, le système compresse les échanges précédents pour laisser place au nouveau contenu. Cette compression est avec perte. Des décisions architecturales documentées au tour 3 peuvent ne pas survivre jusqu’au tour 15.⁹

Les trois mécanismes d’effondrement multi-tour

L’étude MSR/Salesforce a identifié trois mécanismes indépendants, chacun nécessitant une intervention différente :⁹

Stratégie 1 : le système de fichiers comme mémoire

La mémoire la plus fiable entre les frontières de contexte réside dans le système de fichiers. Claude Code lit CLAUDE.md et les fichiers mémoire au démarrage de chaque session et après chaque compaction.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

Le fichier MEMORY.md capture les erreurs, décisions et patterns d’une session à l’autre. Lorsque vous découvrez que ((VAR++)) échoue avec set -e en bash quand VAR vaut 0, vous le consignez. Trois sessions plus tard, face à un cas limite similaire sur les entiers dans Python, l’entrée MEMORY.md fait remonter le pattern.¹⁵

Auto Memory (v2.1.32+) : Claude Code enregistre et rappelle automatiquement le contexte du projet. Au fil de votre travail, Claude inscrit ses observations dans ~/.claude/projects/{project-path}/memory/MEMORY.md. L’auto memory charge les 200 premières lignes dans votre prompt système au démarrage de la session. Restez concis et créez des liens vers des fichiers thématiques séparés pour les notes détaillées.⁶

Stratégie 2 : compaction proactive

La commande /compact de Claude Code résume la conversation et libère de l’espace de contexte tout en préservant les décisions clés, le contenu des fichiers et l’état des tâches.¹⁵

Quand compacter : - Après avoir achevé une sous-tâche distincte (fonctionnalité implémentée, bug corrigé) - Avant d’aborder une nouvelle zone du codebase - Lorsque Claude commence à se répéter ou à oublier le contexte antérieur - Environ toutes les 25 à 30 minutes lors des sessions intensives

Instructions de compaction personnalisées dans CLAUDE.md :

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

Stratégie 3 : documents de passation de session

Pour les tâches s’étendant sur plusieurs sessions, créez des documents de passation qui capturent l’état complet :

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

La structure Status/Files/Decision/Blocked/Next fournit à la session suivante un contexte complet pour un coût minimal en tokens. Démarrer une nouvelle session avec claude -c (continue) ou lire le document de passation permet de passer directement à l’implémentation.¹⁵

Stratégie 4 : itération en contexte neuf (la boucle Ralph)

Pour les sessions dépassant 60 à 90 minutes, lancez une instance Claude neuve à chaque itération. L’état persiste via le système de fichiers, non par la mémoire conversationnelle. Chaque itération dispose du budget de contexte complet :¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

Comparaison avec une session longue unique :

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

L’approche par itération en contexte neuf échange 15 à 20 % de surcoût pour la phase d’orientation (lecture des fichiers d’état, parcours de l’historique git) contre des ressources cognitives complètes à chaque itération.¹⁶ Le calcul coût-bénéfice : pour les sessions de moins de 60 minutes, une conversation unique est plus efficace. Au-delà de 90 minutes, le contexte neuf produit une qualité supérieure malgré le surcoût.

Les anti-patterns

Lire des fichiers entiers quand vous n’avez besoin que de 10 lignes. La lecture d’un seul fichier de 2 000 lignes consomme 15 000 à 20 000 tokens. Utilisez les décalages de lignes : Read file.py offset=100 limit=20 économise la grande majorité de ce coût.¹⁵

Conserver les sorties d’erreur verbeuses dans le contexte. Après avoir débogué un bug, votre contexte contient plus de 40 traces de pile issues des itérations échouées. Un simple /compact après la correction libère ce poids mort.

Démarrer chaque session en lisant tous les fichiers. Laissez les outils glob et grep de Claude Code trouver les fichiers pertinents à la demande, économisant plus de 100 000 tokens de préchargement inutile.¹⁵

Modèles de subagents

Les subagents sont des instances spécialisées de Claude qui gèrent des tâches complexes de manière autonome. Ils démarrent avec un contexte vierge (sans pollution provenant de la conversation principale), opèrent avec des outils spécifiques et renvoient leurs résultats sous forme de résumés. Les résultats d’exploration n’alourdissent pas votre conversation principale ; seules les conclusions y sont renvoyées.⁵

Types de subagents intégrés

Créer des subagents personnalisés

Définissez vos subagents dans .claude/agents/ (projet) ou ~/.claude/agents/ (personnel) :

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Champs de configuration des subagents

Isolation par worktree

Les subagents peuvent opérer dans des git worktrees temporaires, offrant une copie isolée complète du dépôt :⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

L’isolation par worktree est indispensable pour les travaux expérimentaux susceptibles de casser le codebase.

Subagents parallèles

Claude Code prend en charge jusqu’à 10 subagents en parallèle.⁵ Utilisez l’exécution parallèle pour des tâches de recherche indépendantes :

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Chaque agent s’exécute dans sa propre fenêtre de contexte, identifie le code pertinent et renvoie un résumé. Le contexte principal reste propre.

La garde de récursion

Sans limites de lancement, les agents délèguent à des agents qui délèguent à d’autres agents, chacun perdant du contexte et consommant des tokens. Le modèle de garde de récursion impose des budgets :¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Leçon essentielle : utilisez des budgets de lancement, pas uniquement des limites de profondeur. Les limites basées sur la profondeur suivent les chaînes parent-enfant (bloquées à la profondeur 3), mais ignorent la largeur : 23 agents à la profondeur 1, c’est toujours « profondeur 1 ». Un budget de lancement comptabilise le nombre total d’enfants actifs par parent, plafonné à un maximum configurable. Ce modèle de budget correspond au mode de défaillance réel (trop d’agents au total) plutôt qu’à une métrique indirecte (trop de niveaux d’imbrication).⁷

Agent Teams (aperçu expérimental)

Les Agent Teams coordonnent plusieurs instances de Claude Code qui travaillent indépendamment, communiquent via une boîte aux lettres et une liste de tâches partagées, et peuvent contester les conclusions des autres :⁵

Activer avec : export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Quand utiliser les Agent Teams plutôt que les subagents :

Orchestration multi-agent

Les systèmes d’IA à agent unique présentent un angle mort structurel : ils ne peuvent pas remettre en question leurs propres hypothèses.⁷ La délibération multi-agent impose une évaluation indépendante depuis plusieurs perspectives avant qu’une décision ne soit verrouillée.

Délibération minimale viable

Commencez avec 2 agents et 1 règle : les agents doivent évaluer indépendamment avant de voir le travail de l’autre.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

Ce schéma couvre 80 % de la valeur. Tout le reste apporte des améliorations incrémentales.

Le déclencheur de confiance

Toutes les tâches ne nécessitent pas de délibération. Un module de scoring de confiance évalue quatre dimensions :¹⁷

1. Ambiguïté – La requête admet-elle plusieurs interprétations valides ?
2. Complexité du domaine – Exige-t-elle des connaissances spécialisées ?
3. Enjeux – La décision est-elle réversible ?
4. Dépendance au contexte – Requiert-elle une compréhension du système global ?

Le score se répartit en trois niveaux :

Le seuil s’adapte selon le type de tâche. Les décisions de sécurité exigent un consensus de 0,85. Les modifications de documentation n’ont besoin que de 0,50. Cela évite de sur-ingénierer les tâches simples tout en garantissant que les décisions risquées reçoivent l’attention nécessaire.⁷

La machine à états

Sept phases, chacune conditionnée par la précédente :⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH : Des agents indépendants étudient le sujet. Chaque agent reçoit un persona différent (architecte technique, analyste sécurité, ingénieur performance, entre autres). L’isolation du contexte garantit que les agents ne voient pas les découvertes des autres pendant la recherche.

DELIBERATION : Les agents consultent toutes les découvertes et génèrent des alternatives. L’agent Debate identifie les conflits. L’agent Synthesis combine les résultats non contradictoires.

RANKING : Chaque agent note chaque approche proposée selon 5 dimensions pondérées :

L’architecture de validation à deux portes

Deux portes de validation détectent les problèmes à différents stades :⁷

Porte 1 : Validation du consensus (hook PostToolUse). S’exécute immédiatement après chaque agent de délibération : 1. La phase doit avoir atteint au minimum RANKING 2. Au moins 2 agents terminés (configurable) 3. Le score de consensus atteint le seuil adaptatif 4. Si un agent a émis une objection, les préoccupations doivent être documentées

Porte 2 : Pride Check (hook Stop). S’exécute avant la clôture de la session : 1. Diversité des méthodes : plusieurs personas uniques représentés 2. Transparence des contradictions : les dissidences sont documentées avec leurs raisons 3. Gestion de la complexité : au moins 2 alternatives générées 4. Confiance du consensus : classée comme forte (supérieure à 0,85) ou modérée (0,70-0,84) 5. Preuve d’amélioration : la confiance finale dépasse la confiance initiale

Deux hooks à différents moments du cycle de vie correspondent à la façon dont les défaillances surviennent réellement : certaines sont instantanées (mauvais score) et d’autres graduelles (faible diversité, documentation des dissidences manquante).⁷

Pourquoi l’accord est dangereux

Charlan Nemeth a étudié la dissidence minoritaire de 1986 jusqu’à son livre de 2018 In Defense of Troublemakers. Les groupes avec des dissidents prennent de meilleures décisions que ceux qui parviennent rapidement à un accord. Le dissident n’a pas besoin d’avoir raison. L’acte même de désaccord force la majorité à examiner des hypothèses qu’elle aurait autrement ignorées.¹⁸

Wu et al. ont testé si les agents LLM peuvent réellement débattre et ont constaté que sans incitations structurelles au désaccord, les agents convergent vers la réponse initiale la plus assurée, indépendamment de sa justesse.¹⁹ Liang et al. ont identifié la cause profonde comme la « Degeneration-of-Thought » : une fois qu’un LLM établit une confiance dans une position, l’autoréflexion ne peut pas générer de contre-arguments inédits, rendant l’évaluation multi-agent structurellement nécessaire.²⁰

L’indépendance est la contrainte de conception critique. Deux agents évaluant la même stratégie de déploiement avec visibilité sur les résultats de l’autre ont produit des scores de 0,45 et 0,48. Les mêmes agents sans visibilité : 0,45 et 0,72. L’écart entre 0,48 et 0,72 représente le coût du mimétisme.⁷

Détecter le faux accord

Un module de détection de conformité suit les schémas suggérant que les agents s’accordent sans évaluation réelle :⁷

Regroupement des scores : Tous les agents notant dans un intervalle de 0,3 points sur une échelle de 10 signale une contamination de contexte partagé plutôt qu’une évaluation indépendante. Lorsque cinq agents évaluant un refactoring d’authentification ont tous attribué un score de risque sécurité entre 7,1 et 7,4, une ré-exécution avec isolation de contexte a étalé les scores de 5,8 à 8,9.

Dissidence générique : Des agents copiant le langage de préoccupation des autres plutôt que de formuler des objections indépendantes.

Absence de perspectives minoritaires : Une approbation unanime de personas aux priorités contradictoires (un analyste sécurité et un ingénieur performance sont rarement d’accord sur tout).

Le détecteur de conformité repère les cas évidents (environ 10 à 15 % des délibérations où les agents convergent trop rapidement). Pour les 85 à 90 % restants, les portes de consensus et de pride check fournissent une validation suffisante.

Ce qui n’a pas fonctionné en délibération

Les tours de débat libre. Trois tours d’échanges textuels pour une discussion sur l’indexation de base de données ont produit 7 500 tokens de débat. Tour 1 : désaccord authentique. Tour 2 : positions reformulées. Tour 3 : arguments identiques dans des mots différents. Le scoring structuré par dimension a remplacé le débat libre, réduisant le coût de 60 % tout en améliorant la qualité du classement.⁷

Une seule porte de validation. La première implémentation utilisait un unique hook de validation en fin de session. Un agent a terminé la délibération avec un score de consensus de 0,52 (sous le seuil), puis a continué sur des tâches sans rapport pendant 20 minutes avant que le hook de fin de session ne signale l’échec. La séparation en deux portes (une à la fin de la tâche, une à la fin de la session) a permis de détecter les mêmes problèmes à différents moments du cycle de vie.⁷

Coût de la délibération

Chaque agent de recherche traite environ 5 000 tokens de contexte et génère 2 000 à 3 000 tokens de résultats. Avec 3 agents, cela représente 15 000 à 24 000 tokens supplémentaires par décision. Avec 10 agents, environ 50 000 à 80 000 tokens.⁷

Au tarif actuel d’Opus, une délibération à 3 agents coûte approximativement 0,68 à 0,90 $. Une délibération à 10 agents coûte 2,25 à 3,00 $. Le système déclenche la délibération sur environ 10 % des décisions, ce qui porte le coût amorti sur l’ensemble des décisions à 0,23-0,30 $ par session. La pertinence de cet investissement dépend du coût d’une mauvaise décision.

Quand délibérer

Conception de CLAUDE.md

CLAUDE.md est une politique opérationnelle pour un agent IA, pas un README destiné aux humains.²¹ L’agent n’a pas besoin de comprendre pourquoi vous utilisez les conventional commits. Il a besoin de connaître la commande exacte à exécuter et ce que signifie « terminé ».

La hiérarchie de précédence

Les fichiers de règles se chargent automatiquement et fournissent du contexte structuré sans encombrer CLAUDE.md.⁶

Ce qui est ignoré

Ces schémas ne produisent de manière fiable aucun changement observable dans le comportement de l’agent :²¹

Les paragraphes de prose sans commandes. « Nous valorisons un code propre et bien testé » est de la documentation, pas de l’opérationnel. L’agent le lit puis écrit du code sans tests parce qu’il n’y a aucune instruction actionnable.

Les directives ambiguës. « Soyez prudent avec les migrations de base de données » n’est pas une contrainte. « Exécutez alembic check avant d’appliquer les migrations. Annulez si le chemin de downgrade est absent. » en est une.

Les priorités contradictoires. « Avancez vite et livrez rapidement » plus « Assurez une couverture de tests complète » plus « Maintenez le temps d’exécution sous 5 minutes » plus « Lancez les tests d’intégration complets avant chaque commit. » L’agent ne peut pas satisfaire les quatre simultanément et finit par sauter la vérification.²¹

Les guides de style sans mécanisme d’application. « Suivez le Google Python Style Guide » sans ruff check --select D ne donne à l’agent aucun moyen de vérifier la conformité.

Ce qui fonctionne

Des instructions orientées commandes :

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Des définitions de complétion :

## Définition de terminé
Une tâche est complète lorsque TOUS les critères suivants sont satisfaits :
1. `ruff check .` se termine avec le code 0
2. `pytest -v` se termine avec le code 0 sans aucun échec
3. `mypy app/ --strict` se termine avec le code 0
4. Les fichiers modifiés ont été ajoutés à l'index et commités
5. Le message de commit suit le format conventionnel : `type(scope): description`

Sections organisées par tâche :

## Lors de l'écriture de code
- Exécutez `ruff check .` après chaque modification de fichier
- Ajoutez des annotations de type à toutes les nouvelles fonctions

## Lors de la revue de code
- Vérifiez les problèmes de sécurité : `bandit -r app/`
- Contrôlez la couverture de tests : `pytest --cov=app --cov-fail-under=80`

## Lors de la mise en production
- Mettez à jour la version dans `pyproject.toml`
- Exécutez la suite complète : `pytest -v && ruff check . && mypy app/`

Règles d’escalade :

## En cas de blocage
- Si les tests échouent après 3 tentatives : arrêtez et signalez le test en échec avec la sortie complète
- Si une dépendance est manquante : vérifiez d'abord `requirements.txt`, puis demandez
- Jamais : supprimer des fichiers pour résoudre des erreurs, forcer un push, ou ignorer les tests

Ordre de rédaction

Si vous partez de zéro, ajoutez les sections dans cet ordre de priorité :²¹

1. Commandes de build et de test (l’agent en a besoin avant de pouvoir faire quoi que ce soit d’utile)
2. Définition de terminé (empêche les faux achèvements)
3. Règles d’escalade (empêche les solutions de contournement destructrices)
4. Sections organisées par tâche (réduit l’analyse d’instructions non pertinentes)
5. Cadrage par répertoire (monorepos : isole les instructions par service)

Ignorez les préférences de style tant que les quatre premiers points ne fonctionnent pas.

Imports de fichiers

Référencez d’autres fichiers au sein de CLAUDE.md :

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Syntaxe d’import : relatif (@docs/file.md), absolu (@/absolute/path.md), ou répertoire personnel (@~/.claude/file.md). Profondeur maximale : 5 niveaux d’imports.⁶

Compatibilité des instructions entre outils

AGENTS.md est un standard ouvert reconnu par tous les principaux outils de développement assisté par IA.²¹ Si votre équipe utilise plusieurs outils, rédigez AGENTS.md comme source canonique et répliquez les sections pertinentes dans les fichiers spécifiques à chaque outil :

Les patterns d’AGENTS.md (commandes en premier, définis par clôture, organisés par tâche) fonctionnent dans n’importe quel fichier d’instructions, quel que soit l’outil. Ne maintenez pas de jeux d’instructions parallèles qui divergent. Rédigez une source unique faisant autorité et répliquez-la.

Tester vos instructions

Vérifiez que l’agent lit et suit effectivement vos instructions :

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

Le test décisif : demandez à l’agent d’expliquer vos commandes de build. S’il ne peut pas les reproduire mot pour mot, les instructions sont soit trop verbeuses (le contenu est repoussé hors du contexte), soit trop vagues (l’agent ne parvient pas à en extraire des instructions exploitables), soit non découvertes. L’analyse de 2 500 dépôts par GitHub a révélé que le manque de précision est la cause principale des échecs.²¹

Patterns de production

Le quality loop

Un processus de revue obligatoire pour toute modification non triviale :

1. Implémenter — Écrire le code
2. Relire — Reprendre chaque ligne. Repérer les coquilles, erreurs de logique, passages obscurs
3. Évaluer — Exécuter l’evidence gate. Vérifier les patterns, cas limites, couverture de tests
4. Affiner — Corriger chaque problème. Ne jamais reporter à « plus tard »
5. Prendre du recul — Vérifier les points d’intégration, les imports, le code adjacent pour détecter les régressions
6. Répéter — Si un critère de l’evidence gate échoue, revenir à l’étape 4
7. Rapporter — Lister ce qui a changé, comment cela a été vérifié, citer des preuves concrètes

L’evidence gate

« Je pense que » et « ça devrait » ne constituent pas des preuves. Citez des chemins de fichiers, des sorties de tests ou du code spécifique.

Si vous ne pouvez pas fournir de preuve pour une ligne, revenez à l’étape Affiner.²²

Patterns de gestion des erreurs

Écritures atomiques de fichiers. Plusieurs agents écrivant simultanément dans le même fichier d’état corrompent JSON. Écrivez dans des fichiers .tmp, puis utilisez mv de manière atomique. Le système d’exploitation garantit que mv est atomique sur le même système de fichiers.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Récupération après corruption d’état. En cas de corruption de l’état, le pattern de récupération recrée à partir de valeurs par défaut sûres plutôt que de planter :¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

Le piège ((VAR++)) en bash. ((VAR++)) renvoie le code de sortie 1 quand VAR vaut 0, car 0++ s’évalue à 0, ce que bash interprète comme faux. Avec set -e activé, cela tue le script. Utilisez VAR=$((VAR + 1)) à la place.¹⁶

Classification du blast radius

Classifiez chaque action d’agent par blast radius et appliquez la validation appropriée :²

Remote Control (connexion au Claude Code local depuis n’importe quel navigateur ou application mobile) transforme la validation « Externe » d’une attente bloquante en notification asynchrone. L’agent continue à travailler sur la tâche suivante pendant que vous examinez la précédente depuis votre téléphone.²

Spécification des tâches pour les exécutions autonomes

Une tâche autonome efficace comporte trois éléments : l’objectif, les critères de complétion et les pointeurs de contexte :¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Les critères doivent être vérifiables par la machine : réussite/échec des tests, sortie du linter, codes HTTP, vérification d’existence de fichiers. Une tâche initiale demandant à l’agent d’« écrire des tests qui passent » a produit assert True et assert 1 == 1. Techniquement correct. Pratiquement inutile.¹⁶

Modes de défaillance à surveiller

Trace concrète d’une session

Trace d’une session autonome traitant un PRD avec 5 stories :²

1. SessionStart se déclenche. Le dispatcher injecte : date courante, détection du projet, contraintes de philosophie, initialisation du suivi des coûts. Cinq hooks, 180 ms au total.

2. L’agent lit le PRD, planifie la première story. UserPromptSubmit se déclenche. Le dispatcher injecte : contexte du projet actif, référence de dérive de session.

3. L’agent appelle Bash pour exécuter les tests. PreToolUse:Bash se déclenche. Vérification des identifiants, validation du bac à sable, détection du projet. 90 ms. Les tests s’exécutent. PostToolUse:Bash se déclenche : heartbeat d’activité enregistré, vérification de dérive.

4. L’agent appelle Write pour créer un fichier. PreToolUse:Write se déclenche : vérification du périmètre du fichier. PostToolUse:Write se déclenche : vérification du lint, suivi des commits.

5. L’agent termine la story. Stop se déclenche. Vérifications de la quality gate : l’agent a-t-il cité des preuves ? Langage hésitant ? Commentaires TODO dans le diff ? Si une vérification échoue, exit 2 et l’agent continue.

6. Vérification indépendante : un agent distinct exécute la suite de tests sans se fier au rapport de l’agent précédent.

7. Trois agents de revue de code sont lancés en parallèle. Chacun examine le diff indépendamment. Si un relecteur signale un problème CRITICAL, la story retourne dans la file d’attente.

8. La story est validée. La story suivante se charge. Le cycle se répète pour les 5 stories.

Total de hooks déclenchés sur 5 stories : ~340. Temps total passé dans les hooks : ~12 secondes. Cette surcharge a empêché trois fuites d’identifiants, une commande destructrice et deux implémentations incomplètes au cours d’une seule exécution nocturne.

Étude de cas : traitement nocturne de PRD

Un harness de production a traité 12 PRD (47 stories) sur 8 sessions nocturnes. Les métriques comparent les 4 premiers PRD (harness minimal : CLAUDE.md uniquement) aux 8 derniers (harness complet : hooks, skills, quality gates, revue multi-agent).

Les deux fuites d’identifiants ont nécessité la rotation des clés API et l’audit des services en aval : environ 4 heures de réponse à incident. La surcharge du harness qui a empêché l’équivalent représentait 2,4 secondes de bash par story. Le taux de faux achèvement est passé de 35 % à 4 % grâce au hook Stop qui exécutait les tests indépendamment avant d’autoriser l’agent à signaler la complétion.

Considérations de sécurité

Le bac à sable

Claude Code prend en charge un mode bac à sable optionnel (activé via settings.json ou la commande /sandbox) qui restreint l’accès réseau et les opérations sur le système de fichiers grâce à une isolation au niveau du système d’exploitation (seatbelt sur macOS, bubblewrap sur Linux). Lorsqu’il est activé, le bac à sable empêche le modèle d’effectuer des requêtes réseau arbitraires ou d’accéder à des fichiers en dehors du répertoire du projet. Sans bac à sable, Claude Code utilise un modèle basé sur les permissions où vous approuvez ou refusez chaque appel d’outil individuellement.¹³

Limites de permissions

Le système de permissions contrôle les opérations à plusieurs niveaux :

Défense contre l’injection de prompt

Les skills et les hooks offrent une défense en profondeur contre l’injection de prompt :

Les skills avec restrictions d’outils empêchent un prompt compromis d’obtenir un accès en écriture :

allowed-tools: Read, Grep, Glob

Les hooks PreToolUse valident chaque appel d’outil, quelle que soit la manière dont le modèle a été sollicité :

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

L’isolation des subagents limite le rayon d’impact. Un subagent avec permissionMode: plan ne peut effectuer aucune modification même si son prompt est compromis.

Sécurité des hooks

Les hooks HTTP qui interpolent des variables d’environnement dans les en-têtes nécessitent une liste explicite allowedEnvVars pour empêcher l’exfiltration arbitraire de variables d’environnement :¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

La répartition des responsabilités entre humain et agent

La sécurité dans les architectures d’agents exige une répartition claire entre les responsabilités humaines et celles de l’agent :¹⁷

Le principe : les humains sont responsables des décisions nécessitant un contexte organisationnel, un jugement éthique ou une orientation stratégique. Les agents sont responsables des décisions nécessitant une recherche computationnelle dans de vastes espaces de possibilités. Les hooks assurent le respect de cette frontière.

Application récursive des hooks

Les hooks se déclenchent également pour les actions des subagents.¹³ Si Claude lance un subagent via l’Agent tool, vos hooks PreToolUse et PostToolUse s’exécutent pour chaque outil utilisé par le subagent. Sans application récursive des hooks, un subagent pourrait contourner vos barrières de sécurité. L’événement SubagentStop vous permet d’exécuter un nettoyage ou une validation à la fin d’un subagent.

Ce n’est pas optionnel. Un agent qui lance un subagent sans vos hooks de sécurité est un agent capable de faire un force-push sur main, de lire des fichiers d’identifiants ou d’exécuter des commandes destructrices pendant que vos barrières observent la conversation principale sans rien faire.

Le coût comme élément d’architecture

Le coût est une décision architecturale, pas une considération opérationnelle secondaire.² Trois niveaux :

Au niveau des tokens. Compression du system prompt. Supprimez les exemples de code tutoriels (le modèle connaît les APIs), fusionnez les règles dupliquées entre fichiers, et remplacez les explications par des contraintes. « Rejeter les appels d’outils correspondant à des chemins sensibles » accomplit le même travail qu’une explication de 15 lignes sur les raisons pour lesquelles les identifiants ne doivent pas être lus.

Au niveau de l’agent. Des instances fraîches plutôt que de longues conversations. Chaque story dans une exécution autonome reçoit un nouvel agent avec un contexte vierge. Le contexte ne gonfle jamais car chaque agent démarre à zéro. Un briefing plutôt qu’une mémoire : les modèles exécutent mieux un briefing clair qu’ils ne naviguent dans 30 étapes de contexte accumulé.

Au niveau de l’architecture. Privilégier CLI à MCP lorsque l’opération est sans état. Un appel claude --print pour une évaluation ponctuelle coûte moins cher et n’ajoute aucune surcharge de connexion. MCP est pertinent lorsque l’outil nécessite un état persistant ou du streaming.

Cadre de décision

Quand utiliser chaque mécanisme :

Skills vs Hooks vs Subagents

FAQ

Combien de hooks est-ce trop ?

C’est la performance, et non le nombre, qui constitue la contrainte. Chaque hook s’exécute de manière synchrone, donc le temps d’exécution total des hooks s’ajoute à chaque appel d’outil correspondant. 95 hooks répartis entre les paramètres utilisateur et projet fonctionnent sans latence perceptible lorsque chaque hook s’exécute en moins de 200 ms. Le seuil à surveiller : si un hook PostToolUse ajoute plus de 500 ms à chaque modification de fichier, la session devient lente. Profilez vos hooks avec time avant de les déployer.¹⁴

Les hooks peuvent-ils empêcher Claude Code d’exécuter une commande ?

Oui. Les hooks PreToolUse bloquent toute action d’outil en terminant avec le code de sortie 2. Claude Code annule l’action en attente et affiche la sortie stderr du hook au modèle. Claude voit la raison du rejet et propose une alternative plus sûre. Le code de sortie 1 est un avertissement non bloquant où l’action se poursuit malgré tout.³

Où placer les fichiers de configuration des hooks ?

Les configurations de hooks vont dans .claude/settings.json pour les hooks au niveau du projet (commités dans votre dépôt, partagés avec votre équipe) ou ~/.claude/settings.json pour les hooks au niveau utilisateur (personnels, appliqués à tous les projets). Les hooks de projet ont la priorité lorsque les deux existent. Utilisez des chemins absolus pour les fichiers de script afin d’éviter les problèmes de répertoire de travail.¹⁴

Chaque décision nécessite-t-elle une délibération ?

Non. Le module de confiance évalue les décisions selon quatre dimensions (ambiguïté, complexité, enjeux, dépendance au contexte). Seules les décisions obtenant un score de confiance global inférieur à 0,70 déclenchent une délibération, soit environ 10 % du total des décisions. Les corrections de documentation, les renommages de variables et les modifications courantes ignorent entièrement la délibération. Les décisions d’architecture de sécurité, les modifications de schéma de base de données et les déploiements irréversibles la déclenchent systématiquement.⁷

Comment tester un système conçu pour produire des désaccords ?

Testez à la fois les chemins de succès et les chemins d’échec. Succès : les agents expriment un désaccord productif et parviennent à un consensus. Échec : les agents convergent trop rapidement, ne convergent jamais, ou dépassent les budgets de spawn. Les tests de bout en bout simulent chaque scénario avec des réponses d’agents déterministes, vérifiant que les portes de validation détectent chaque mode d’échec documenté. Un système de délibération en production exécute 141 tests répartis sur trois couches : 48 tests d’intégration bash, 81 tests unitaires Python, et 12 simulations de pipeline de bout en bout.⁷

Quel est l’impact de la délibération sur la latence ?

Une délibération à 3 agents ajoute 30 à 60 secondes de temps réel (les agents s’exécutent séquentiellement via le Agent tool). Une délibération à 10 agents ajoute 2 à 4 minutes. Les hooks de consensus et de pride check s’exécutent chacun en moins de 200 ms. Le principal goulot d’étranglement est le temps d’inférence LLM par agent, et non la surcharge d’orchestration.⁷

Quelle longueur devrait avoir un fichier CLAUDE.md ?

Limitez chaque section à moins de 50 lignes et le fichier total à moins de 150 lignes. Les fichiers longs sont tronqués par les fenêtres de contexte ; placez donc en priorité les instructions les plus critiques : commandes et définitions de closures avant les préférences de style.²¹

Ce système peut-il fonctionner avec d’autres outils que Claude Code ?

Les principes architecturaux (hooks comme portes déterministes, skills comme expertise de domaine, subagents comme contextes isolés, système de fichiers comme mémoire) s’appliquent conceptuellement à tout système agentique. L’implémentation spécifique utilise les événements de cycle de vie de Claude Code, les patterns de correspondance et le Agent tool. AGENTS.md transpose ces mêmes patterns vers Codex, Cursor, Copilot, Amp et Windsurf.²¹ Le pattern de harness est agnostique vis-à-vis de l’outil, même si les détails d’implémentation sont spécifiques à chaque outil.

Carte de référence rapide

Configuration des hooks

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Frontmatter des skills

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Définition de subagent

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

Codes de sortie

Commandes principales

Emplacements des fichiers

Journal des modifications

Références