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

TL;DR : Claude Code n’est pas une boîte de dialogue avec accès aux fichiers. C’est un environnement d’exécution programmable doté de 29 événements de cycle de vie documentés, chacun pouvant être intercepté par des scripts shell que le modèle ne peut 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, conserve la mémoire entre les sessions et orchestre la délibération multi-agents. Ce guide couvre chaque couche de cette pile : d’un simple hook à un système de consensus à 10 agents. Aucun framework requis. Uniquement du bash et JSON.

Andrej Karpathy a inventé un terme pour ce qui se développe autour d’un agent LLM : claws. Les hooks, scripts et l’orchestration qui permettent à l’agent de saisir le monde au-delà de sa fenêtre de contexte.¹ La plupart des développeurs considèrent les agents de codage IA comme des assistants interactifs. Ils saisissent un prompt, le regardent modifier un fichier, puis passent à autre chose. Cette approche plafonne la productivité à ce que vous pouvez personnellement superviser.

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

Cette distinction est importante car l’infrastructure se cumule. 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 vous-même ou qu’un agent le fasse. Un agent qui examine le code pour des questions de sécurité exécute les mêmes vérifications, que vous le surveilliez 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 toute opération 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 ne fait qu’avertir.³
• 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 de 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 permettent à la session principale de rester légère. Exécutez les subagents indépendants en parallèle et utilisez des équipes d’agents lorsque les workers ont besoin d’une coordination soutenue.⁵
• 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 règles 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 remettre en cause ses propres hypothèses. Deux agents indépendants aux priorités d’évaluation différentes détectent des défaillances structurelles que les contrôles qualité ne peuvent traiter.⁷
• Le pattern du harness est 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 passe à l’échelle avec l’automatisation.

Comment utiliser ce guide

Chaque section s’appuie sur la précédente. Le Decision Framework à la fin fournit une table de référence pour choisir le bon mécanisme selon le type de problème.

Chemin d’or en cinq minutes

Avant la plongée en profondeur, voici le chemin le plus court entre zéro et un harness opérationnel. 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

Branchez-le dans .claude/settings.json :

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

Résultat : chaque commande bash que Claude exécute est désormais passée au crible pour détecter les identifiants divulgués. 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 revue, vérification ou audit.

Étape 3 : Lancer un subagent (30 secondes)

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

Ce que vous avez maintenant

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 développe l’une de ces trois couches.

Pourquoi l’architecture d’agents est importante

Simon Willison cadre le moment présent autour d’une seule observation : écrire du code ne coûte plus rien aujourd’hui.⁸ Exact. Mais le corollaire, c’est que la vérification est désormais la partie coûteuse. Du code bon marché dépourvu d’infrastructure de vérification produit des bugs à grande échelle. L’investissement qui paie n’est pas un meilleur prompt. C’est le système autour du modèle qui rattrape ce que le modèle laisse passer.

Trois forces rendent l’architecture d’agents nécessaire :

Les fenêtres de contexte sont finies et lacunaires. Chaque lecture de fichier, sortie d’outil et tour de conversation consomme des tokens. Microsoft Research et Salesforce ont testé 15 LLMs sur plus de 200 000 conversations simulées et ont constaté une baisse de performance moyenne de 39 % entre les interactions à un seul tour et les interactions multi-tours.⁹ La dégradation commence dès deux tours et suit une courbe prévisible : des modifications précises multi-fichiers lors des 30 premières minutes dégénèrent en vision tunnel sur un seul fichier dès la 90ᵉ minute. Des fenêtres de contexte plus longues ne résolvent pas ce problème. La condition « Concat » de la même étude (conversation complète en tant que prompt unique) atteint 95,1 % des performances à un seul tour avec un contenu identique. La dégradation vient des frontières entre tours, pas des limites de tokens.

Le comportement du modèle est probabiliste, pas déterministe. Dire à Claude « exécute toujours Prettier après avoir édité des fichiers » fonctionne environ 80 % du temps.³ Le modèle peut oublier, privilégier la rapidité ou décider que le changement est « trop petit ». 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.

Les perspectives uniques passent à côté des problèmes multidimensionnels. Un agent seul chargé de passer en revue un endpoint API vérifiait l’authentification, validait l’assainissement des entrées et vérifiait les en-têtes CORS. Diagnostic clean. 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 non bornés pouvant déclencher un déni de service via amplification de requêtes en base de données.⁷ Le premier agent n’a jamais vérifié ce point parce que rien dans son cadre d’évaluation ne traitait la complexité des requêtes comme une surface de sécurité. Cette lacune est structurelle. Aucune quantité de prompt engineering ne la corrige.

L’architecture d’agents 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 codage 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’instruction : les fichiers CLAUDE.md et les répertoires de règles 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 de domaine qui s’active automatiquement selon le contexte. Les hooks fournissent des gates déterministes qui se déclenchent à chaque appel d’outil correspondant. Les fichiers de mémoire conservent l’état d’une session à l’autre. 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 spawn empêchent la récursion incontrôlée. La validation par consensus garantit la qualité.

L’idée clé : la plupart des utilisateurs travaillent entièrement dans la Core Layer, observant le contexte enfler et les coûts grimper. Les utilisateurs avancés configurent les couches d’instruction et d’extension, puis n’utilisent la Core Layer que pour l’orchestration et les décisions finales.²

Harness managés vs auto-hébergés (avril 2026)

Pendant tout le début de 2026, la voie « construisez votre propre harness » était la seule option réelle. En avril 2026, cela a changé. Anthropic a livré Claude Managed Agents en bêta publique (8 avril) : boucle du harness + exécution d’outils + conteneur sandbox + persistance d’état sous forme de REST API, facturé aux tokens standard plus 0,08 $ par heure-session. La mise à jour Agents SDK d’OpenAI (16 avril) a formalisé la même séparation — harness et compute en couches distinctes, avec des fournisseurs de sandbox natifs (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) et snapshot/réhydratation pour survivre à la perte de conteneur.²³²⁴

La surface SDK plus profonde côté OpenAI est arrivée dans openai-agents Python v0.14.0 (publié le 15 avril 2026 ; annoncé le 16 avril) : une sous-classe SandboxAgent d’Agent avec default_manifest, instructions de sandbox et capacités ; un Manifest décrivant le contrat de workspace neuf (fichiers, dossiers, fichiers locaux, repos Git, env, utilisateurs, mounts) ; un SandboxRunConfig pour le câblage par exécution du client sandbox, l’injection de session live, les overrides de manifest, les snapshots et les limites de concurrence de matérialisation. Les capacités intégrées couvrent l’accès shell, l’édition du système de fichiers, l’inspection d’images, les skills, la mémoire sandbox et la compaction. La mémoire sandbox conserve les leçons extraites d’une exécution à l’autre et les divulgue progressivement ; les workspaces prennent en charge les fichiers locaux, les entrées de repo Git et les mounts distants (S3, R2, GCS, Azure Blob, S3 Files) ; les snapshots sont portables entre fournisseurs. Backends : UnixLocalSandboxClient, DockerSandboxClient, et clients hébergés pour Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop et Vercel via des extras optionnels.²⁴

Pour les projets Python qui souhaitent embarquer le runtime Claude Code comme bibliothèque — entre « shell vers claude » et « REST API vers Managed Agents » — claude-agent-sdk-python est la troisième option. La série du 28-29 avril (v0.1.69 → v0.1.71) a fait passer le CLI embarqué à la v2.1.123, relevé le plancher de la dépendance mcp à >=1.19.0 (les versions plus anciennes laissaient silencieusement tomber les retours CallToolResult des outils MCP in-process, laissant le modèle avec un blob d’erreur de validation), et amené SandboxNetworkConfig à la parité de schéma avec l’SDK TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

La fourche architecturale est désormais réelle :

Quand choisir quoi : l’auto-hébergé reste pertinent pour les équipes qui disposent déjà d’une expertise infrastructure, qui veulent des skills/hooks qu’elles contrôlent, ou qui optimisent un workflow spécifique en profondeur. Le managé convient aux équipes sans ingénieurs plateforme dédiés, quand le time-to-value compte plus que la personnalisation, ou quand les exécutions d’agents doivent survivre de manière fiable aux fermetures de portable sans que vous ayez à construire cette couche de persistance. Les deux sont compatibles — vous pouvez exécuter un harness auto-hébergé qui délègue des tâches spécifiques à longue durée d’exécution à Managed Agents via son REST API.

À 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/ est une 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 à les appeler explicitement.⁴ Le moment où vous vous surprenez à réexpliquer le même contexte d’une session à l’autre est le moment où vous devriez 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, demandez-vous : « Claude doit-il appliquer cela automatiquement, ou est-ce à moi de décider quand l’exécuter ? »

Créer un Skill

Les skills se trouvent dans quatre emplacements possibles, du 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 tout

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écider si un skill est pertinent. Une 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 de l’invite système, et le modèle utilise la compréhension standard du langage 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’elle fait (réviser le code pour des types de problèmes spécifiques), quand l’utiliser (examen de changements, PR, analyse de qualité), et les expressions déclencheurs (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 à 1 % de la fenêtre de contexte, avec une valeur de repli de 8 000 caractères.⁴ Si vous avez de nombreux skills, gardez chaque description concise et placez le cas d’usage clé en premier. Vous pouvez remplacer le budget via la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ mais la meilleure solution consiste à rédiger des descriptions plus courtes et plus précises. Exécutez /context pendant une session pour vérifier si certains skills sont exclus.

Fichiers de support 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 à l’aide de liens relatifs. Claude lit ces fichiers à la demande lorsque le skill s’active. Maintenez SKILL.md sous les 500 lignes et déplacez les documents de référence détaillés vers des fichiers de support.¹²

Partager des Skills via Git

Les skills de projet (.claude/skills/ à la racine du dépôt) sont partagés 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 font un pull, ils récupèrent le skill automatiquement. Aucune installation, aucune configuration. C’est la manière la plus efficace de standardiser l’expertise au sein d’une équipe.

Les Skills comme bibliothèque d’invites

Au-delà des skills à usage unique, la structure des répertoires fonctionne comme une bibliothèque d’invites 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 composent avec les Hooks

Les skills peuvent définir leurs propres hooks dans le frontmatter qui ne s’activent que lorsque le skill est en cours d’exécution. 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 les hooks SessionStart, injectant des contraintes de qualité dans chaque session sans invocation explicite. Le skill lui-même est de la connaissance. Le hook est de 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 toute invite liée à git (rebases, merges, cherry-picks, et même git status) pollue le contexte de 80 % des sessions. La solution consiste soit à resserrer la description, soit à ajouter disable-model-invocation: true et à exiger une invocation explicite /skill-name.⁴

Trop de skills se disputant le budget. Plus il y a de skills, plus de descriptions se disputent le budget de contexte de 1 %. Si vous remarquez que des skills ne s’activent pas, vérifiez /context pour repérer ceux qui sont exclus. Privilégiez moins de skills bien décrits plutôt que de nombreux skills vagues.

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

Surface des Skills du SDK (8 mai 2026)

Les harnesses auto-hébergés sur claude-agent-sdk-python v0.1.77+ doivent utiliser l’option skills sur ClaudeAgentOptions pour déclarer les skills disponibles, et non la valeur héritée "Skill" dans allowed_tools.³⁷ Le raccourci "Skill" est déprécié et l’option dédiée donne à Claude Code des informations plus structurées sur les skills disponibles. Le CLI fourni dans v0.1.77 est v2.1.133.

Architecture des hooks

Les hooks sont des commandes shell déclenchées par les événements de cycle de vie de Claude Code.³ Ils s’exécutent en dehors du LLM en tant que scripts simples, et non comme des 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 29 événements de cycle de vie documentés répartis en huit catégories au moment de cette mise à jour du guide. La liste des événements s’étoffe au fil des versions, donc considérez la documentation de référence comme la source de vérité et consultez la fiche de référence pour le tableau complet à jour avant de câbler des hooks en production :¹³

Sémantique des codes de sortie

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

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 courante dans toutes les équipes.¹⁴

Configuration des hooks

Les hooks vivent dans des fichiers de paramètres. Au niveau du projet (.claude/settings.json) pour les hooks partagés. Au niveau de l’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 filtre une valeur spécifique à l’événement. Pour les événements d’outil, il correspond aux valeurs tool_name telles que Bash, Edit, Write, Read, Glob, Grep, aux noms d’outils MCP comme mcp__server__tool, ou * pour tous les outils. Les noms simples et les listes séparées par | sont des correspondances exactes ; les valeurs comportant d’autres caractères sont des expressions régulières JavaScript. Certains événements ne prennent pas en charge les matchers et se déclenchent toujours lorsqu’ils sont configurés.¹³

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 émettre du JSON pour 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 au niveau supérieur est obsolète 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, demandez-vous : de quel type de garantie ai-je besoin ?¹⁴

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. La sortie du modèle n’a pas d’importance car 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 motifs 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 contrôles 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 cinq types de hooks :¹³

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

Les hooks d’outil MCP (type: "mcp_tool") appellent un outil sur un serveur MCP déjà connecté. Utilisez-les lorsque la logique de validation vit déjà derrière une frontière MCP et n’a pas besoin d’un script shell séparé.

Les hooks de prompt (type: "prompt") envoient un prompt à 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 regex ne peuvent pas exprimer.

Les hooks d’agent (type: "agent") lancent un subagent avec accès aux outils (Read, Grep, Glob) pour une vérification multi-tours. Ils sont expérimentaux ; préférez les hooks de commande pour les portes de production et réservez les hooks d’agent aux contrôles qui nécessitent réellement d’inspecter des fichiers réels ou la sortie 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 comme requête POST à une URL et reçoivent du JSON en retour. À utiliser pour les webhooks, les services de notification externes ou la validation basée sur 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 async pour les notifications, la télémétrie et les sauvegardes. N’utilisez jamais async pour le formatage, la validation, ou tout ce qui doit s’achever avant l’action suivante.

Dispatchers plutôt que hooks indépendants

Faire tourner sept hooks qui se déclenchent tous sur le même événement, chacun lisant stdin indépendamment, crée des conditions de course. Deux hooks écrivant simultanément dans le même fichier d’état JSON tronqueront le JSON. Chaque hook en aval qui analyse ce fichier se brise.²

Le correctif : un dispatcher par événement qui exécute les hooks séquentiellement à partir d’un 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 indépendamment. Pipez un échantillon de JSON : echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Utilisez stderr pour la sortie de débogage. Le stderr du code de sortie 2 est renvoyé à Claude comme message d’erreur. Le stderr non bloquant (exit 1, 3, etc.) n’apparaît qu’en mode verbeux (Ctrl+O).
3. Surveillez les échecs de jq. Des chemins JSON erronés renvoient null silencieusement. Testez les expressions jq sur de vraies entrées d’outil.
4. Vérifiez les codes de sortie. Un hook PreToolUse qui utilise exit 1 ne fournit aucune application tout en semblant 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 500 ms.

Streaming d’événements de hook côté SDK

Les harnesses auto-hébergés construits sur claude-agent-sdk-python (v0.1.74+, 6 mai 2026) peuvent s’abonner aux événements de hook directement depuis le flux de messages plutôt que de passer par des callbacks de scripts shell.³⁶ Définissez include_hook_events=True sur ClaudeAgentOptions et les objets HookEventMessage (PreToolUse, PostToolUse, Stop, et autres) sont émis depuis le même itérateur que les messages d’assistant et les résultats d’outils. Cela reflète l’option includeHookEvents du SDK TypeScript ; le CLI groupé est passé à v2.1.129 dans la même version.

Le motif de flux d’événements convient lorsque votre harness vit déjà en Python et que vous voulez les signaux de hook dans le même flux de contrôle que la sortie du modèle. Le contrat de hook par script shell (codes de sortie, JSON stdin, dispatchers) reste la bonne réponse pour les harnesses qui composent plusieurs outils, partagent des hooks entre Claude Code et Codex, ou ont besoin d’une sémantique de code de sortie pour le blocage.

Provenance d’effort et de session (7-8 mai 2026)

Deux ajouts dans Claude Code v2.1.132 et v2.1.133 donnent aux hooks et aux sous-processus un meilleur signal sur leur contexte d’exécution :³⁸³⁹

• effort.level dans l’entrée du hook. Les hooks reçoivent désormais un champ JSON effort.level sur la même entrée qui transporte tool_input et session_id. La même valeur est exportée comme variable d’environnement $CLAUDE_EFFORT, afin que les commandes Bash puissent la lire sans analyser le JSON. Utilisez-la pour faire varier le coût des hooks selon le palier d’effort : sautez la validation coûteuse en low, exécutez la porte de sécurité complète en xhigh ou max.
• Variable d’environnement CLAUDE_CODE_SESSION_ID sur les sous-processus Bash. Les sous-processus de l’outil Bash voient désormais la même valeur session_id que les hooks, exposée comme CLAUDE_CODE_SESSION_ID. Cela comble le fossé de provenance pour les outils qui journalisent l’état par session et qui étaient auparavant incapables de corréler les événements de sous-processus avec les événements de hook.

Les deux signaux sont disponibles sans changement de code ; les hooks existants qui ignorent les nouveaux champs continuent de fonctionner.

Mémoire et contexte

Chaque conversation IA opère dans une fenêtre de contexte finie. À mesure que la conversation s’étend, le système compresse les tours antérieurs pour faire place au nouveau contenu. Cette compression entraîne des pertes. Les décisions architecturales documentées au tour 3 peuvent ne pas survivre jusqu’au tour 15.⁹

Les trois mécanismes de l’effondrement multi-tours

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 au-delà des frontières de contexte réside dans le système de fichiers. Claude Code lit CLAUDE.md et les fichiers de mémoire au début 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, les décisions et les patterns à travers les sessions. Lorsque vous découvrez que ((VAR++)) échoue avec set -e en bash quand VAR vaut 0, vous le consignez. Trois sessions plus tard, lorsque vous rencontrez un cas limite similaire avec un entier 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 écrit ses observations dans ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory charge les 200 premières lignes dans votre prompt système au démarrage de session. Gardez-le 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 terminé une sous-tâche distincte (fonctionnalité implémentée, bug corrigé) - Avant de démarrer un nouveau secteur de la base de code - Lorsque Claude commence à se répéter ou à oublier le contexte antérieur - Environ toutes les 25 à 30 minutes lors de 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 : passages de relais entre sessions

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 le contexte complet à un coût minimal en tokens. Démarrer une nouvelle session avec claude -c (continue) ou lire le document de passation mène directement à l’implémentation.¹⁵

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

Pour les sessions dépassant 60 à 90 minutes, lancez une nouvelle instance de Claude par itération. L’état persiste à travers le système de fichiers, non par la mémoire conversationnelle. Chaque itération bénéficie 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

À comparer avec une session unique de longue durée :

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 contexte-frais-par-itération échange une surcharge de 15 à 20 % pour l’étape d’orientation (lecture des fichiers d’état, balayage 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 frais produit une sortie de meilleure qualité malgré la surcharge.

Stratégie 5 : curation de mémoire managée (Dreaming)

Les Managed Agents Claude d’Anthropic ont ajouté Dreaming en tant que Research Preview le 6 mai 2026.³⁵ Selon Anthropic : « Dreaming est un processus planifié qui examine vos sessions d’agent et vos magasins de mémoire, extrait les patterns et organise les souvenirs afin que vos agents s’améliorent au fil du temps. »³⁵

Dreaming s’exécute en arrière-plan entre les sessions, hors du chemin critique. Il complète plutôt qu’il ne remplace le pattern système-de-fichiers-comme-mémoire : votre fichier MEMORY.md demeure la surface porteuse ; Dreaming écrit des entrées de mémoire organisées dans le magasin de mémoire des Managed Agents, que l’agent lit au démarrage de session. Les deux patterns coexistent pour les harnais qui mêlent l’état système de fichiers auto-hébergé à la curation côté managé.

Dreaming est en Research Preview, son comportement peut donc évoluer. Les patterns de passation de session et de CLAUDE.md documentés ci-dessus restent le mécanisme de mémoire faisant autorité pour les harnais auto-hébergés.

Les anti-patterns

Lire des fichiers entiers alors que vous n’avez besoin que de 10 lignes. La lecture d’un seul fichier de 2 000 lignes consomme entre 15 000 et 20 000 tokens. Utilisez les décalages de ligne : 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 d’itérations échouées. Une seule commande /compact après la correction du bug 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, ce qui économise 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 indépendante. Ils démarrent avec un contexte propre (sans pollution provenant de la conversation principale), opèrent avec des outils spécifiés et renvoient les résultats sous forme de résumés. Les résultats d’exploration n’encombrent pas votre conversation principale ; seules les conclusions sont retournées.⁵

Types de subagents intégrés

Création de subagents personnalisés

Définissez les 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 worktrees git temporaires, fournissant 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 essentielle pour les travaux expérimentaux susceptibles de casser la codebase.

Subagents parallèles

Utilisez des subagents parallèles pour des tâches de recherche indépendantes qui n’ont pas besoin de se coordonner entre elles :⁵

> 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, trouve le code pertinent et renvoie un résumé. Le contexte principal reste propre.

Le garde-fou de récursion

Sans limites de création, les agents délèguent à des agents qui délèguent à des agents, chacun perdant du contexte et consommant des tokens. Le modèle de garde-fou 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 critique : utilisez des budgets de création, pas seulement des limites de profondeur. Les limites basées sur la profondeur suivent les chaînes parent-enfant (bloquées à la profondeur 3) mais ratent la largeur : 23 agents à la profondeur 1 restent à « profondeur 1 ». Un budget de création suit le total des enfants actifs par parent, plafonné à un maximum configurable. Le modèle de budget correspond au mode de défaillance réel (trop d’agents au total) plutôt qu’à une métrique de substitution (trop de niveaux d’imbrication).⁷

Agent Teams (aperçu de recherche)

Agent Teams coordonne 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 mutuellement leurs conclusions :⁵

Activez avec : export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Quand utiliser les agent teams plutôt que les subagents :

Orchestration multi-agents

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

Orchestration inter-outils (avril 2026) : Google a publié Scion en open source le 7 avril — un hyperviseur multi-agents qui exécute Claude Code, Gemini CLI et d’autres « deep agents » comme processus concurrents, chacun avec un conteneur, un git worktree et des identifiants isolés. S’exécute en local, sur hub ou Kubernetes. Philosophie explicite : « isolation over constraints » — les agents fonctionnent avec une grande autonomie à l’intérieur de limites imposées au niveau de l’infrastructure, pas dans le prompt.²⁵ Cela étend directement l’argument de l’isolation des subagents à différents fournisseurs d’outils. Si votre flux de travail couvre Claude et les modèles OpenAI, Scion est la première véritable implémentation de référence pour des subagents inter-outils avec isolation worktree + identifiants par agent.

Le débat n’est pas une solution miracle : Le cluster de recherche M3MAD-Bench (début 2026) a constaté que le débat multi-agents plafonne et peut être subverti par un consensus trompeur — des arguments valides perdent lorsque d’autres agents affirment avec assurance la mauvaise réponse.²⁶ Tool-MAD améliore cela en donnant à chaque agent un accès hétérogène aux outils et en utilisant des scores de Faithfulness/Relevance dans la phase de jugement. Si vous construisez une orchestration de type débat, investissez dans (a) l’hétérogénéité des outils par agent et (b) un score quantitatif du juge plutôt que de supposer que plus d’agents = meilleures réponses.

Orchestration multi-agents managée et Outcomes (Public Beta)

Si vous ne voulez pas construire l’infrastructure de délibération décrite ci-dessous, Multiagent Orchestration est entré en Public Beta dans Claude Managed Agents le 6 mai 2026.³⁵ Selon Anthropic : « Lorsqu’il y a trop de travail pour qu’un seul agent le fasse bien, l’orchestration multi-agents permet à un agent principal de découper le travail en morceaux et de déléguer chacun à un spécialiste avec son propre modèle, prompt et outils. »³⁵ Les spécialistes « travaillent en parallèle sur un système de fichiers partagé et contribuent au contexte global de l’agent principal. »³⁵

Le tracing est inclus d’origine. Selon Anthropic : « vous pouvez également tracer chaque étape dans la Claude Console : quel agent a fait quoi, dans quel ordre et pourquoi, vous donnant une visibilité complète sur la manière dont votre tâche a été déléguée et exécutée. »³⁵

La fonctionnalité Public Beta complémentaire est Outcomes. Selon Anthropic : « vous écrivez une rubrique décrivant à quoi ressemble le succès et l’agent travaille à l’atteindre. Un évaluateur séparé évalue la sortie par rapport à vos critères dans sa propre fenêtre de contexte, de sorte qu’il n’est pas influencé par le raisonnement de l’agent. »³⁵ Il s’agit de la version managée du modèle de validation à deux portes documenté plus loin dans cette section : la rubrique remplace la porte écrite à la main, l’évaluateur séparé remplace le validateur de consensus.

La délibération auto-hébergée reste la bonne réponse lorsque la validation doit s’intégrer à votre propre surface de hooks (blocage PreToolUse, sémantique des codes de sortie, dispatchers personnalisés) ou lorsque le harness doit fonctionner sans dépendances externes. Multiagent managé est la bonne réponse lorsque la délégation standard plus l’évaluation par rubrique est le contrat dont vous avez réellement besoin.

Délibération minimum 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 modèle couvre 80 % de la valeur. Tout le reste apporte une amélioration incrémentale.

Le déclencheur de confiance

Toutes les tâches n’ont pas besoin de délibération. Un module de notation de confiance évalue quatre dimensions :¹⁷

1. Ambiguïté - La requête a-t-elle plusieurs interprétations valides ?
2. Complexité du domaine - Nécessite-t-elle des connaissances spécialisées ?
3. Enjeux - La décision est-elle réversible ?
4. Dépendance au contexte - Nécessite-t-elle de comprendre le système au sens large ?

Le score correspond à trois niveaux :

Le seuil s’adapte selon le type de tâche. Les décisions de sécurité requièrent un consensus de 0,85. Les modifications de documentation n’en requièrent que 0,50. Cela évite la sur-ingénierie des tâches simples tout en garantissant que les décisions à risque sont scrutées.⁷

La machine à états

Sept phases, chacune contrôlée par la précédente :⁷

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

RESEARCH : Des agents indépendants examinent le sujet. Chaque agent reçoit un persona différent (Technical Architect, Security Analyst, Performance Engineer, et d’autres). L’isolation du contexte garantit que les agents ne peuvent pas voir les conclusions des autres pendant la recherche.

DELIBERATION : Les agents voient toutes les conclusions de recherche et génèrent des alternatives. L’agent Debate identifie les conflits. L’agent Synthesis combine les conclusions non contradictoires.

RANKING : Chaque agent évalue toutes les approches proposées selon 5 dimensions pondérées :

L’architecture de validation à deux portes

Deux portes de validation détectent les problèmes à différentes étapes :⁷

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

Porte 2 : Pride Check (hook Stop). S’exécute avant que la session puisse se fermer : 1. Méthodes diversifiées : plusieurs personas uniques représentés 2. Transparence des contradictions : les désaccords ont des raisons documentées 3. Gestion de la complexité : au moins 2 alternatives générées 4. Confiance du consensus : classée comme forte (au-dessus de 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 points du cycle de vie correspondent à la manière dont les défaillances surviennent réellement : certaines sont instantanées (mauvais score) et d’autres sont graduelles (faible diversité, documentation des désaccords 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 les groupes qui parviennent rapidement à un accord. Le dissident n’a pas besoin d’avoir raison. L’acte de désaccord force la majorité à examiner les hypothèses qu’elle aurait autrement passées sous silence.¹⁸

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 qui semble la plus assurée, indépendamment de son exactitude.¹⁹ Liang et al. ont identifié la cause profonde comme la « Degeneration-of-Thought » : une fois qu’un LLM établit sa confiance dans une position, l’auto-réflexion ne peut pas générer de nouveaux contre-arguments, rendant l’évaluation multi-agents 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 conclusions 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 est le coût du suivisme.⁷

Détecter le faux accord

Un module de détection de la conformité suit les schémas suggérant que les agents sont d’accord sans véritable évaluation :⁷

Regroupement des scores : Tous les agents notant à 0,3 points près sur une échelle de 10 points signalent une contamination du contexte partagé plutôt qu’une évaluation indépendante. Lorsque cinq agents évaluant un refactoring d’authentification ont tous noté le risque de sécurité entre 7,1 et 7,4, une nouvelle exécution avec une isolation de contexte fraîche a étalé les scores entre 5,8 et 8,9.

Désaccords standardisés : Des agents copient le langage de préoccupation des autres plutôt que de générer des objections indépendantes.

Perspectives minoritaires absentes : Approbation unanime de personas aux priorités contradictoires (un Security Analyst et un Performance Engineer sont rarement d’accord sur tout).

Le détecteur de conformité attrape 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é dans la délibération

Tours de débat libre. Trois tours d’allers-retours textuels pour une discussion sur l’indexation de base de données ont produit 7 500 tokens de débat. Tour 1 : véritable désaccord. Tour 2 : positions reformulées. Tour 3 : arguments identiques formulés différemment. 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.⁷

Porte de validation unique. La première implémentation exécutait un seul hook de validation à la fin de la session. Un agent a terminé une délibération avec un score de consensus de 0,52 (en dessous du 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. Le découpage en deux portes (une à la fin de la tâche, une à la fin de la session) a détecté les mêmes problèmes à différents points 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 conclusions. 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.⁷

Aux tarifs Opus actuels, une délibération à 3 agents coûte environ 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, donc le coût amorti sur l’ensemble des décisions est de 0,23 à 0,30 $ par session. Que cela en vaille la peine dépend de ce que coûte 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 pour 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 à quoi ressemble « terminé ».

La hiérarchie de précédence

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

Ce qui est ignoré

Ces schémas produisent invariablement aucun changement observable dans le comportement de l’agent :²¹

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

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. Avortez si le chemin de downgrade est manquant. » l’est.

Priorités contradictoires. « Avancez vite et livrez rapidement » plus « Assurez une couverture de tests exhaustive » plus « Maintenez le runtime sous 5 minutes » plus « Exécutez 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 par défaut.²¹

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

Ce qui fonctionne

Instructions axées sur les 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`

Définitions de clôture :

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Sections organisées par tâche :

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

Règles d’escalade :

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip 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 contournements destructeurs)
4. Sections organisées par tâche (réduit l’analyse d’instructions non pertinentes)
5. Périmètre par répertoire (monorepos : isole les instructions par service)

Sautez les préférences de style tant que les quatre premières ne sont pas en place.

Imports de fichiers

Référencez d’autres fichiers depuis 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 : relative (@docs/file.md), absolue (@/absolute/path.md) ou répertoire personnel (@~/.claude/file.md). Profondeur maximale : 5 niveaux d’imports.⁶

Compatibilité d’instructions inter-outils

AGENTS.md est un standard ouvert reconnu par tous les grands outils de codage IA.²¹ Si votre équipe utilise plusieurs outils, rédigez AGENTS.md comme source canonique et reflétez les sections pertinentes dans les fichiers spécifiques aux outils :

Les schémas dans AGENTS.md (axés commandes, à clôture définie, organisés par tâche) fonctionnent dans n’importe quel fichier d’instructions, quel que soit l’outil. Ne maintenez pas des jeux d’instructions parallèles qui dérivent l’un de l’autre. Rédigez une source faisant autorité et reflétez-la.

Notes de parité Codex

Codex dispose désormais d’équivalents de premier ordre pour les principales couches du harness, mais la migration est une traduction de schémas, pas une copie de fichiers. Codex lit AGENTS.md avant de commencer le travail, en superposant la guidance globale de ~/.codex avec les instructions du projet et des dépôts imbriqués.³¹ Les skills Codex utilisent le même modèle mental SKILL.md avec divulgation progressive : Codex commence par le nom du skill, sa description et son chemin de fichier, puis charge le skill complet uniquement lorsqu’il décide de l’utiliser.³² Codex prend également en charge nativement les hooks, les hooks empaquetés en plugin, les hooks managés, MCP, et des workflows explicites de subagents.³³³⁴

La correspondance pratique :

La différence importante : les subagents Claude peuvent être sélectionnés automatiquement à partir des descriptions, tandis que Codex documente actuellement les workflows de subagents comme explicites. Cela fait des skills et des hooks le bon choix par défaut pour le comportement permanent du harness dans Codex ; les subagents sont réservés au travail parallèle délibéré, à la revue et à l’exploration.

Tester vos instructions

Vérifiez que l’agent lit et suit réellement 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, c’est que les instructions sont soit trop verbeuses (contenu poussé hors du contexte), soit trop vagues (l’agent ne peut pas extraire d’instructions actionnables), soit non découvertes. L’analyse de 2 500 dépôts par GitHub a révélé que le flou est à l’origine de la plupart des échecs.²¹

Modèles de production

Modèles à long horizon d’Opus 4.7 (avril 2026)

Claude Opus 4.7 (16 avril 2026) est livré avec des capacités spécifiques qui modifient ce contre quoi un harness doit se défendre :²⁹

• Résilience aux défaillances d’outils : Opus 4.7 poursuit son exécution malgré les défaillances d’outils qui interrompaient les sessions d’Opus 4.6. Vous pouvez réduire — sans toutefois éliminer — les wrappers défensifs de réessai dans le code des subagents. Conservez les protections au niveau des hooks ; élaguez l’échafaudage en prompt du type « si l’outil échoue, réessaye trois fois ».
• Niveau d’effort xhigh (Opus-4.7 uniquement) : Se situe entre high et max. Valeur par défaut recommandée pour les charges de travail de codage et agentiques. Sur les subagents de longue durée, xhigh surpasse significativement high avec un coût en tokens sous-proportionnel. max reste le bon choix pour le raisonnement difficile en un seul coup ; xhigh est meilleur pour les tâches soutenues.
• Plafond de budget de tokens : Configurable par exécution d’agent via output_config.task_budget (en-tête bêta task-budgets-2026-03-13). Le modèle voit un compte à rebours en cours et adapte gracieusement son travail au budget plutôt que de tomber à court de manière inattendue. À utiliser pour les boucles agentiques où vous souhaitez une dépense en tokens prévisible sans sacrifier la qualité sur les prompts courts.
• Conscience des besoins implicites : Premier modèle Claude à passer les tests de « besoin implicite » — reconnaître quand la requête littérale de l’utilisateur sous-spécifie ce dont il a réellement besoin. Cela rend la section « règles de clarification » de CLAUDE.md moins nécessaire. Si votre CLAUDE.md compte 200 lignes de garde-fous du type « considérez aussi X quand l’utilisateur demande Y », élaguez ceux qui sont désormais couverts nativement.

Base des worktrees, chemins du sandbox et paramètres administrateur (7 mai 2026)

Claude Code v2.1.133 ajoute quatre paramètres de niveau administrateur qu’il vaut la peine de connaître pour les harness de production :³⁹

Le retour en arrière de worktree.baseRef est celui à signaler aux utilisateurs : les agents qui s’appuyaient sur le comportement v2.1.128-v2.1.132 (worktrees branchant depuis le HEAD local) perdent l’accès au travail non poussé dans les nouveaux worktrees, sauf à réactiver explicitement cette option.

La boucle qualité

Un processus de revue obligatoire pour toutes les modifications non triviales :

1. Implémenter - Écrire le code
2. Réviser - Relire chaque ligne. Repérer les fautes de frappe, les erreurs de logique, les sections peu claires
3. Évaluer - Faire passer l’evidence gate. Vérifier les patterns, les cas limites, la couverture des 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 à la recherche de régressions
6. Recommencer - Si un critère de l’evidence gate échoue, retournez à l’étape 4
7. Rapporter - Lister ce qui a changé, comment cela a été vérifié, citer des preuves spécifiques

L’evidence gate

« Je crois » et « cela devrait » ne sont pas des preuves. Citez des chemins de fichiers, des sorties de tests ou du code spécifique.

Si vous ne pouvez pas produire de preuves pour une ligne, retournez à Affiner.²²

Patterns de gestion des erreurs

Écritures de fichiers atomiques. Plusieurs agents écrivant simultanément dans le même fichier d’état corrompt JSON. Écrivez dans des fichiers .tmp, puis effectuez un mv 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 en cas de corruption d’état. Si l’état devient corrompu, 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 bash de ((VAR++)). ((VAR++)) retourne le code de sortie 1 lorsque VAR vaut 0, car 0++ s’évalue à 0, ce que bash traite comme faux. Avec set -e activé, cela tue le script. Utilisez plutôt VAR=$((VAR + 1)).¹⁶

Classification du rayon d’impact

Classez chaque action d’agent par rayon d’impact et appliquez les contrôles en conséquence :²

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

Spécification de tâche pour les exécutions autonomes

Les tâches autonomes efficaces incluent trois éléments : objectif, critères d’achèvement et 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 machine : succès/échec des tests, sortie du linter, codes de statut HTTP, vérifications d’existence de fichiers. Une tâche initiale qui demandait à l’agent d’« écrire des tests qui passent » a produit assert True et assert 1 == 1. Techniquement correct. Pratiquement sans valeur.¹⁶

Modes d’échec à surveiller

Une trace de session concrète

Une trace de session d’une exécution autonome traitant un PRD comportant 5 stories :²

1. SessionStart se déclenche. Le dispatcher injecte : date courante, détection de projet, contraintes philosophiques, 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 de projet actif, baseline de dérive de session.

3. L’agent appelle Bash pour exécuter les tests. PreToolUse:Bash se déclenche. Vérification des credentials, validation du sandbox, détection de 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 de la portée du fichier. PostToolUse:Write se déclenche : vérification du linter, suivi des commits.

5. L’agent termine la story. Stop se déclenche. Le contrôle qualité vérifie : l’agent a-t-il cité des preuves ? Langage atténué ? Commentaires TODO dans le diff ? Si une vérification échoue, exit 2 et l’agent continue.

6. Vérification indépendante : Un agent neuf exécute la suite de tests sans faire confiance à l’auto-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 l’un des relecteurs signale CRITICAL, la story retourne dans la file.

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

Total des hooks déclenchés sur 5 stories : ~340. Temps total dans les hooks : ~12 secondes. Cette surcharge a empêché trois fuites de credentials, une commande destructrice et deux implémentations incomplètes en 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, contrôles qualité, revue multi-agent).

Les deux fuites de credentials 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 était de 2,4 secondes de bash par story. Le taux de fausse complétion est passé de 35 % à 4 % parce que le hook Stop exécutait indépendamment les tests avant d’autoriser l’agent à se déclarer terminé.

Considérations de sécurité

Les cinq principes des agents dignes de confiance (Anthropic, avril 2026)

Anthropic a publié un cadre formel pour la fiabilité des agents le 9 avril 2026.²⁷ Les cinq principes rejoignent — et étendent — la réflexion sur l’Evidence Gate présentée dans ce guide :

Anthropic a également fait don de MCP à l’Agentic AI Foundation de la Linux Foundation, rejoignant AGENTS.md (désormais cogéré avec OpenAI, Google, Cursor, Factory, Sourcegraph). Les standards d’interopérabilité des agents sont désormais indépendants des fournisseurs.²⁷

Outil de sandbox pour skills : Pour les équipes qui considèrent les skills comme une surface d’attaque, SandyClaw de Permiso (lancé le 2 avril 2026) exécute les skills dans un sandbox dédié et fournit des verdicts étayés par des preuves issues de la détection Sigma/YARA/Nova/Snort. Premier produit dans la catégorie sandbox de skills.²⁸

Le sandbox

Claude Code prend en charge un mode sandbox 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 sandbox empêche le modèle d’effectuer des requêtes réseau arbitraires ou d’accéder à des fichiers en dehors du dossier du projet. Sans sandboxing, Claude Code utilise un modèle basé sur les permissions où vous approuvez ou refusez chaque appel d’outil individuellement.¹³

Les frontières 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 fournissent 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, indépendamment de 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’action. Un subagent avec permissionMode: plan ne peut effectuer aucun changement, 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 afin d’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 humain-agent

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

Le schéma : les humains détiennent les décisions qui requièrent un contexte organisationnel, un jugement éthique ou une orientation stratégique. Les agents détiennent les décisions qui requièrent une recherche computationnelle dans de vastes espaces de possibilités. Les hooks font respecter cette frontière.

Application récursive des hooks

Les hooks se déclenchent également pour les actions des subagents.¹³ Si Claude engendre un subagent via le 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 garde-fous de sécurité. L’événement SubagentStop vous permet d’exécuter du nettoyage ou de la validation à la fin d’un subagent.

Ce n’est pas optionnel. Un agent qui engendre un subagent sans vos hooks de sécurité est un agent capable de force-pusher sur main, de lire des fichiers de credentials ou d’exécuter des commandes destructrices pendant que vos garde-fous surveillent la conversation principale sans rien faire.

Le coût comme architecture

Le coût est une décision architecturale, pas une réflexion opérationnelle a posteriori.² Trois niveaux :

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

Niveau agent. Spawns frais plutôt que conversations longues. Chaque story dans une exécution autonome obtient un nouvel agent avec un contexte propre. Le contexte ne gonfle jamais parce que chaque agent démarre à neuf. Un briefing plutôt qu’une mémoire : les modèles exécutent mieux un briefing clair qu’ils ne naviguent à travers 30 étapes de contexte accumulé.

Niveau architecture. CLI-first plutôt que 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 a du sens 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 ?

La contrainte porte sur les performances, pas sur le nombre. Chaque hook s’exécute de façon synchrone, donc le temps total d’exécution des hooks s’ajoute à chaque appel d’outil correspondant. 95 hooks répartis entre les paramètres au niveau utilisateur et au niveau projet s’exécutent sans latence perceptible lorsque chacun se termine 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 sortant avec le code 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 suggère une alternative plus sûre. Le code de sortie 1 est un avertissement non bloquant où l’action se poursuit malgré tout.³

Où dois-je placer les fichiers de configuration des hooks ?

Les configurations de hooks vont dans .claude/settings.json pour les hooks au niveau projet (commités dans votre dépôt, partagés avec votre équipe) ou dans ~/.claude/settings.json pour les hooks au niveau utilisateur (personnels, appliqués à chaque projet). Les hooks au niveau projet prennent la priorité lorsque les deux existent. Utilisez des chemins absolus pour les fichiers de scripts afin d’éviter les problèmes liés au 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 dont le score global de confiance est 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 de routine contournent entièrement la délibération. L’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 du désaccord ?

Testez à la fois les chemins de réussite et les chemins d’échec. Réussite : les agents sont en désaccord de manière productive et parviennent à un consensus. Échec : les agents convergent trop vite, 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’agent déterministes, vérifiant que les deux portes de validation détectent chaque mode de défaillance documenté. Un système de délibération en production exécute 141 tests 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 en latence de la délibération ?

Une délibération à 3 agents ajoute 30 à 60 secondes de temps réel (les agents s’exécutent séquentiellement via l’outil Agent). 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, pas la surcharge d’orchestration.⁷

Quelle doit être la longueur d’un fichier CLAUDE.md ?

Gardez chaque section en dessous de 50 lignes et le fichier total en dessous de 150 lignes. Les fichiers longs sont tronqués par les fenêtres de contexte, donc placez en tête les instructions les plus critiques : les commandes et les définitions de clôture avant les préférences de style.²¹

Cela peut-il fonctionner avec d’autres outils que Claude Code ?

Les principes architecturaux (les hooks comme portes déterministes, les skills comme expertise de domaine, les subagents comme contextes isolés, le 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, les motifs de matcher et l’outil Agent de Claude Code. AGENTS.md transpose les mêmes motifs vers Codex, Cursor, Copilot, Amp et Windsurf.²¹ Le pattern du harness est indépendant de l’outil même si les détails d’implémentation sont spécifiques à l’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 de skill

---
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 clés

Emplacements de fichiers

Journal des modifications

Références