Architecture d'agents : construire des environnements de développement pilotés par l'IA

TL;DR : Claude Code n’est pas une 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, conserve la mémoire entre les sessions et orchestre une 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écrire 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 programmation IA comme des assistants interactifs. Ils saisissent un prompt, regardent 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 programmation 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 capitale, car l’infrastructure produit des effets cumulatifs. 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 pour la 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 systématiquement, 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 préviennent l’inflation 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 d’une fenêtre de contexte à l’autre. CLAUDE.md, MEMORY.md, les répertoires de rules et les documents de passation forment un système structuré de mémoire externe.⁶
• La délibération multi-agents détecte les angles morts. Un agent isolé 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 traiter.⁷
• 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 monte en puissance avec 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.

Pourquoi l’architecture agent est essentielle

Simon Willison résume le moment actuel par une observation centrale : écrire du code est désormais peu coûteux.⁸ C’est exact. Mais le corollaire, c’est que la vérification est devenue la partie onéreuse. Du code bon marché sans infrastructure de vérification produit des bugs à grande échelle. L’investissement réellement rentable 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 agent nécessaire :

Les fenêtres de contexte sont finies et sujettes à la perte d’information. 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 constaté une baisse de performance moyenne de 39 % entre l’interaction en 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 dégradent en vision tunnel mono-fichier au bout de 90 minutes. Des fenêtres de contexte plus larges ne résolvent pas ce problème. La condition « Concat » de la même étude (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 la modification est « trop mineure ». 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 unique 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 : rien à signaler. 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, pouvant déclencher un déni de service par amplification des requêtes en base de données.⁷ Le premier agent n’a jamais vérifié cet aspect, car rien dans son cadre d’évaluation ne traitait la complexité des requêtes comme une surface d’attaque. Cette lacune est structurelle. Aucune quantité de prompt engineering ne la corrige.

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 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 métier qui s’active automatiquement en fonction du contexte. Les hooks fournissent 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 spawn empêchent la récursion incontrôlée. La validation par consensus assure la qualité.

L’idée clé : la plupart des utilisateurs travaillent exclusivement dans la couche Core, observant le contexte gonfler et les 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 le harness ressemble sur le 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 à 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 représentent des connaissances que Claude a toujours à disposition. Les slash commands sont des 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

## Vérifications de sécurité
Lors de la revue de code, vérifiez :

### Validation des entrées
- Toutes les entrées utilisateur assainies avant les opérations en base de données
- Requêtes paramétrées (pas d'interpolation de chaînes dans le SQL)
- Encodage de sortie pour le contenu HTML rendu

### Authentification
- Jetons de session validés sur chaque endpoint protégé
- Vérifications des permissions avant les mutations de données
- Aucun identifiant codé en dur ni clé API dans le code source

Référence du frontmatter

Le champ Description est déterminant

Au démarrage de la session, Claude Code extrait les champs name et 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. Une analyse indépendante du code source de Claude Code confirme ce mécanisme : les descriptions des skills sont injectées dans une section available_skills du prompt système, et le modèle s’appuie sur 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 (revue de code pour des types de problèmes spécifiques), quand l’utiliser (examen de modifications, PRs, analyse de qualité), et des phrases 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 seuil de repli 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. Lancez /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é dans des 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 font un pull, ils récupèrent automatiquement le skill. Pas d’installation, pas de configuration. C’est la méthode la plus efficace pour 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 composent 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 philosophiques 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 en 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, voire git status) pollue le contexte dans 80 % des sessions. La solution consiste soit à resserrer la description, soit à ajouter disable-model-invocation: true et à exiger une invocation explicite via /skill-name.⁴

Trop de skills en concurrence pour le budget. Plus de skills signifie plus de descriptions en compétition pour le budget de contexte de 2 %. Si vous remarquez 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 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 22 événements de cycle de vie répartis en six catégories :¹³

Sémantique des codes de sortie

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

Crucial : 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 les équipes.¹⁴

Configuration des hooks

Les hooks résident dans les fichiers de paramètres. Au niveau du 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 permissions :

{
  "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. La sortie du modèle n’a aucune 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 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 é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 trois 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 à tour unique vers un modèle Claude rapide. Le modèle renvoie { "ok": true } pour autoriser ou { "ok": false, "reason": "..." } pour bloquer. À utiliser pour les évaluations nuancées 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
          }
        ]
      }
    ]
  }
}

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. N’utilisez jamais le mode asynchrone pour le formatage, la validation ou toute opération devant se terminer avant l’action suivante.

Dispatchers plutôt que hooks indépendants

Quand sept hooks se déclenchent tous sur le même événement, chacun lisant stdin indépendamment, des conditions de concurrence apparaissent. Deux hooks écrivant simultanément dans le même fichier d’état JSON vont tronquer 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 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. Envoyez un exemple de JSON via pipe : echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Utilisez stderr pour la sortie de débogage. Tout ce qui est écrit sur stderr apparaît dans le contexte de Claude.
3. Attention aux échecs de jq. Les chemins JSON incorrects renvoient null silencieusement. Testez les expressions jq avec de vraies entrées d’outils.
4. Vérifiez les codes de sortie. Un hook PreToolUse qui utilise exit 1 n’offre aucune protection 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 2 secondes, idéalement sous 500 ms.

Mémoire et contexte

Chaque 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 faire 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-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 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é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, 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 l’enregistrez. Trois sessions plus tard, face à un cas limite similaire sur les entiers dans Python, l’entrée dans 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. L’auto memory charge les 200 premières lignes dans votre prompt système au démarrage de 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 terminé une sous-tâche distincte (fonctionnalité implémentée, bug corrigé) - Avant d’aborder une nouvelle zone du codebase - Quand 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 : 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 (continuer) ou lire le document de passation permet de passer directement à l’implémentation.¹⁵

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

Pour les sessions dépassant 60-90 minutes, lancez une instance Claude fraîche à chaque itération. L’état persiste via le système de fichiers, pas via la mémoire conversationnelle. Chaque itération dispose de l’intégralité du budget de contexte :¹⁶

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 contexte-vierge-par-itération échange 15-20 % de surcoût pour la phase d’orientation (lecture des fichiers d’état, analyse 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 vierge produit un résultat de meilleure qualité 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.¹⁵

Garder des 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. Un simple /compact après la correction libère ce poids mort.

Commencer 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 indépendante. Ils démarrent avec un contexte vierge (sans pollution provenant de la conversation principale), fonctionnent avec des outils spécifiés et renvoient les 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 fonctionner dans des git worktrees 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 base de code.

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

Le garde-fou 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-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 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 restent à « 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 véritable mode de défaillance (trop d’agents au total) plutôt qu’à une métrique indirecte (trop de niveaux d’imbrication).⁷

Agent Teams (aperçu de recherche)

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 uns et des autres :⁵

Activation : 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 à agent unique présentent 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 selon 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 patron 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 — Requiert-elle des connaissances spécialisées ?
3. Enjeux — La décision est-elle réversible ?
4. Dépendance au contexte — Nécessite-t-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’examen 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 en sécurité, ingénieur performance, entre autres). L’isolation du contexte garantit que les agents ne peuvent pas voir les découvertes des autres pendant la recherche.

DELIBERATION : Les agents consultent l’ensemble des résultats de recherche 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érentes étapes :⁷

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 session : 1. Méthodes diversifiées : plusieurs personas uniques représentés 2. Transparence des contradictions : les dissensions sont documentées avec leurs raisons 3. Gestion de la complexité : au moins 2 alternatives générées 4. Confiance du consensus : classifié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 graduelles (faible diversité, documentation des dissensions manquante).⁷

Pourquoi l’accord est dangereux

Charlan Nemeth a étudié la dissidence minoritaire de 1986 jusqu’à son ouvrage 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 véritablement 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 « Dégénérescence de la Pensée » : une fois qu’un LLM établit sa confiance dans une position, l’autoréflexion ne peut générer de contre-arguments originaux, 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 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 conformisme.⁷

Détecter les faux accords

Un module de détection de conformité traque les schémas suggérant que les agents s’accordent sans évaluation véritable :⁷

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 noté le risque de sécurité entre 7.1 et 7.4, une ré-exécution avec une isolation de contexte fraîche a dispersé les scores entre 5.8 et 8.9.

Dissidence stéréotypée : Des agents copiant le langage d’objection des autres plutôt que de générer des objections indépendantes.

Perspectives minoritaires absentes : Approbation unanime de personas aux priorités conflictuelles (un analyste en sécurité et un ingénieur performance 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 vite). 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

Tours de débat en forme 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 en d’autres mots. Le scoring par dimensions structurées 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 utilisait un seul 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 poursuivi 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 complétion de la tâche, une en fin de session) a permis de détecter 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 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, soit un coût amorti de 0,23 à 0,30 $ par session. La pertinence de cet investissement dépend de ce que coûte une mauvaise décision.

Quand délibérer

Conception de CLAUDE.md

CLAUDE.md constitue 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 commits conventionnels. Il doit connaître la commande exacte à exécuter et à 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 ne produisent de manière fiable aucun changement observable dans le comportement de l’agent :²¹

Paragraphes de prose sans commandes. « Nous valorisons un code propre et bien testé » relève de la documentation, pas des opérations. L’agent le lit puis écrit du code sans tests, faute d’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. Abandonnez si le chemin de rétrogradation est manquant. » en est une.

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 satisfaire ces quatre exigences simultanément et finit par sauter la vérification.²¹

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

Ce qui fonctionne

Instructions orientées commande :

## 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 :

## Définition de terminé
Une tâche est terminée lorsque TOUS les critères suivants sont validés :
1. `ruff check .` retourne 0
2. `pytest -v` retourne 0 sans échec
3. `mypy app/ --strict` retourne 0
4. Les fichiers modifiés ont été indexés 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 d'une mise en production
- Mettez à jour la version dans `pyproject.toml`
- Lancez 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 manque : 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é (évite les fausses complétion)
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. 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 dans 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é inter-outils des instructions

AGENTS.md est un standard ouvert adopté par plus de 60 000 projets et 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 reproduisez les sections pertinentes dans les fichiers spécifiques à chaque outil :

Les patterns d’AGENTS.md (commandes en premier, délimitation par fermeture, organisation par tâche) fonctionnent dans tout 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 reproduisez-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 directives 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 principale cause d’échec.²¹

Patterns de production

La quality loop

Un processus de revue obligatoire pour tout changement non trivial :

1. Implémenter — Écrire le code
2. Relire — Relire 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 de fichiers atomiques. Plusieurs agents écrivant simultanément dans le même fichier d’état corrompent le JSON. Écrivez dans des fichiers .tmp, puis déplacez-les avec 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. Si l’état est corrompu, le pattern de récupération recrée à partir de valeurs par défaut sûres au lieu 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++)) retourne le code de sortie 1 lorsque VAR vaut 0 car 0++ s’évalue à 0, que bash interprète comme faux. Avec set -e activé, cela tue le script. Utilisez VAR=$((VAR + 1)) à la place.¹⁶

Classification du rayon d’impact

Classifiez chaque action de l’agent par rayon d’impact et appliquez les contrôles correspondants :²

Remote Control (connexion à Claude Code local depuis n’importe quel navigateur ou application mobile) transforme le contrôle « Externe » d’une attente bloquante en une 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âches pour les exécutions autonomes

Les tâches autonomes efficaces comportent trois éléments : objectif, critères de complétion 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 : réussite/échec des tests, sortie du linter, codes HTTP, vérifications 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 d’échec à surveiller

Trace concrète d’une session

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

1. SessionStart se déclenche. Le dispatcher injecte : date courante, détection du 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 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 sandbox, 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 de fichier. PostToolUse:Write se déclenche : vérification du lint, suivi des commits.

5. L’agent termine la story. Stop se déclenche. Contrôles qualité : l’agent a-t-il cité des preuves ? Langage évasif ? Commentaires TODO dans le diff ? Si un contrôle échoue, code de sortie 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 se lancent en parallèle. Chacun examine le diff indépendamment. Si un réviseur 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 : environ 340. Temps total passé dans les hooks : environ 12 secondes. Cette surcharge a empêché trois fuites d’identifiants, une commande destructrice et deux implémentations incomplètes lors d’une seule exécution nocturne.

Considérations de sécurité

Le bac à sable

Claude Code s’exécute dans un bac à sable qui restreint l’accès réseau et les opérations sur le système de fichiers. Ce 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.¹³

Périmètres 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, quel que soit le contenu du prompt :

# 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 par subagent 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 allowedEnvVars explicite 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 humain-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 prennent les décisions qui nécessitent un contexte organisationnel, un jugement éthique ou une orientation stratégique. Les agents prennent les décisions qui requièrent une exploration computationnelle d’espaces de possibilités vastes. Les hooks matérialisent cette frontière.

Application récursive des hooks

Les hooks se déclenchent aussi 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 garde-fous de sécurité. L’événement SubagentStop permet d’exécuter un nettoyage ou une validation à la fin d’un subagent.

Ce n’est pas facultatif. 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 garde-fous surveillent la conversation principale sans rien faire.

Le coût comme architecture

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

Au niveau des tokens. Compression du prompt système. Supprimez les exemples de code tutoriels (le modèle connaît déjà les API), fusionnez les règles dupliquées entre fichiers, et remplacez les explications par des contraintes. « Rejeter 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 identifiants ne doivent pas être lus.

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

Au niveau de l’architecture. Privilégier CLI 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 est pertinent quand 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 qui compte, pas le nombre. Chaque hook s’exécute de manière synchrone ; le temps d’exécution total s’ajoute donc à chaque appel d’outil correspondant. 95 hooks répartis entre les paramètres utilisateur et projet s’exécutent sans latence perceptible tant que chaque hook 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 poussive. 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 propose une alternative plus sûre. Le code de sortie 1 est un avertissement non bloquant : 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 (committé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 à tous les projets). Les hooks de projet ont 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 de confiance global est inférieur à 0,70 déclenchent une délibération, soit environ 10 % des décisions totales. Les corrections de documentation, les renommages de variables et les modifications de routine passent directement. 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 du désaccord ?

Testez à la fois les chemins de succès et les chemins d’échec. Succès : 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’agents déterministes, vérifiant que les 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 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 l’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 du LLM par agent, pas la surcharge d’orchestration.⁷

Quelle longueur pour un fichier CLAUDE.md ?

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

Cela fonctionne-t-il avec d’autres outils que Claude Code ?

Les principes architecturaux (hooks comme portes déterministes, skills comme expertise métier, 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, les patterns de matcher et l’Agent tool de Claude Code. AGENTS.md transporte ces mêmes patterns vers Codex, Cursor, Copilot, Amp et Windsurf.²¹ Le pattern du harness est agnostique vis-à-vis de l’outil, même si les détails d’implémentation sont spécifiques.

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 d’un 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