Anatomie d'une griffe : 84 hooks comme couche d'orchestration

Le premier hook a pris quatre minutes à écrire. Il empêchait le modèle de suggérer des produits OpenAI dans un workflow exclusivement Anthropic. Deux mois plus tard, ce seul hook en était devenu 84. Les 84 hooks étaient connectés à 43 skills, 19 agents spécialisés et 30 modules de bibliothèque. À un moment donné, la collection a cessé d’être un ensemble de scripts pour devenir une couche d’orchestration.

Je ne l’ai pas conçu ainsi. Personne ne s’assoit en disant « je vais construire 15 000 lignes d’infrastructure d’agents ». Vous résolvez un problème. Puis un autre. Puis vous résolvez le problème des interactions entre les problèmes. Au moment où vous remarquez l’architecture, elle existe déjà.

Andrej Karpathy l’a remarqué aussi. En février 2026, il a décrit les « Claws » comme une nouvelle couche computationnelle : orchestration, planification, gestion du contexte et routage des outils construits au-dessus des agents LLM, de la même manière que les agents sont construits au-dessus des LLMs.¹ Cette conceptualisation a cristallisé quelque chose que les praticiens construisaient sans le nommer. Cet article est l’anatomie d’un tel système : ce qu’il contient, comment il a grandi, là où il fonctionne, et là où il échoue.

TL;DR

La couche « Claws » de Karpathy décrit les systèmes d’orchestration construits au-dessus des CLI d’agents. J’en ai construit un de manière organique en deux mois sur Claude Code : 84 hooks répartis sur 15 types d’événements, 43 skills, 19 agents et plus de 30 modules de bibliothèque. Le système correspond précisément à cinq fonctions Claws (orchestration, planification, gestion du contexte, routage des outils, contrôle qualité) avec une lacune notable (les définitions de workflows déclaratifs). Constat principal : la séparation planification-exécution a émergé comme une propriété naturelle de l’orchestration par hooks, et non comme un objectif de conception. L’observation de Lattner selon laquelle « le jugement et l’abstraction restent au cœur tandis que l’IA automatise l’implémentation » se transpose directement sur l’architecture de hooks : les hooks de gouvernance exercent le jugement, les hooks d’automatisation exécutent l’implémentation.

La taxonomie des Claws

La description de Karpathy identifie cinq fonctions qu’une couche Claws remplit. Chaque fonction a un analogue direct dans le système de hooks que j’ai construit sur Claude Code au cours des deux derniers mois.¹

La taxonomie est utile parce qu’elle sépare des préoccupations que les praticiens ont tendance à construire de manière enchevêtrée. Mes premiers hooks mélangeaient gestion du contexte et contrôle qualité. Le hook de suivi des coûts à la fois injectait le contexte budgétaire (gestion du contexte) et bloquait les opérations coûteuses (contrôle qualité). Séparer ceux-ci en hooks distincts a amélioré la fiabilité, car chaque hook pouvait échouer indépendamment sans compromettre l’autre fonction.

Le système complet

Les chiffres en février 2026 :

La distribution des hooks par type d’événement révèle où la complexité de l’orchestration se concentre :

UserPromptSubmit porte le plus de poids car il se déclenche à chaque message utilisateur. Le répartiteur (prompt-dispatcher.sh) exécute neuf hooks séquentiellement à chaque prompt : filtrage de sécurité, analytique, suivi d’utilisation, surveillance système, injection d’objectifs, blocage des estimations de temps, injection de contexte, injection de sujets mémoire et surveillance de la pression contextuelle.²

Chaque hook ajoute de la latence. Neuf hooks séquentiels ajoutent un total mesuré de 200 ms par prompt. Le répartiteur les exécute séquentiellement (pas en parallèle) car les écritures concurrentes de hooks dans des fichiers d’état JSON partagés causaient une corruption de données lors des premiers tests. Deux hooks écrivant simultanément dans jiro.state.json produisaient du JSON tronqué qui cassait tous les hooks en aval. L’exécution séquentielle est plus lente mais sûre. La surcharge de 200 ms est invisible pour les utilisateurs car la vitesse de frappe humaine est le goulot d’étranglement, pas la latence des hooks.

Comment le système a grandi

La croissance n’a pas été linéaire. Elle a suivi un schéma de cycles problème-solution-intégration.

Phase 1 : hooks à usage unique (Semaines 1-2). Chaque hook résolvait un seul problème. enforce-opus-model.sh bloquait les requêtes de modèles non-Opus. no-time-estimates.sh supprimait les estimations d’effort des réponses. filter-sensitive.sh interceptait les identifiants dans les appels d’outils. Ces hooks fonctionnaient indépendamment. Aucun hook ne connaissait l’existence d’un autre hook.

Phase 2 : problèmes de coordination (Semaines 3-4). Les hooks ont commencé à interférer les uns avec les autres. Le filtre d’identifiants bloquait des appels API légitimes. L’imposeur de modèle entrait en conflit avec le spawning de sous-agents. La solution : les répartiteurs. Un point d’entrée unique (prompt-dispatcher.sh) a remplacé sept hooks UserPromptSubmit individuels, contrôlant l’ordre d’exécution et partageant l’état via un pipe stdin mis en cache.

Phase 3 : capacités composées (Semaines 5-8). Les hooks individuels se sont composés en systèmes. La boucle qualité a connecté les hooks pre-tool (détection des problèmes avant qu’ils ne surviennent) avec les hooks post-tool (vérification des résultats après leur survenue) via un fichier d’état partagé (jiro.state.json). Le système de délibération utilisait des gardes de récursion, des budgets de spawn et des protocoles de consensus pour coordonner plusieurs agents sans boucles infinies. Ralph (la boucle de développement autonome) connectait les fichiers PRD au spawning de Claude, à la vérification des tests et à la revue de code dans un seul pipeline orchestré.

Phase 4 : conscience de soi (Semaine 9+). Le système est devenu suffisamment grand pour nécessiter des outils permettant de se comprendre lui-même. La recherche sémantique à travers le système de hooks (skill /find) permettait aux agents de découvrir les hooks par objectif plutôt que par nom de fichier. La surveillance des performances (skill /perf) suivait si la surcharge propre au système dégradait la machine. Un moniteur de pression contextuelle avertissait lorsque le contexte injecté par la couche d’orchestration consommait trop de la fenêtre de contexte du modèle.

La progression de hooks à usage unique vers une infrastructure auto-surveillée reflète un schéma que Chris Lattner a identifié dans sa revue du projet Claude C Compiler : « Un bon logiciel dépend du jugement, de la communication et d’une abstraction claire. L’IA a amplifié cela. »³ L’architecture du système de hooks révèle la même vérité. Les hooks les plus précieux ne sont pas ceux qui automatisent des tâches. Les hooks les plus précieux sont ceux qui encodent le jugement sur quand et comment les tâches doivent être automatisées.

Hooks de jugement vs. hooks d’automatisation

La revue du Claude C Compiler par Lattner distinguait entre ce que l’IA automatise bien (l’implémentation) et ce qui reste fondamentalement humain (le jugement et l’abstraction).³ Cette distinction se transpose directement sur le système de hooks.

Les hooks de jugement décident si quelque chose doit se produire. Ils encodent une politique, pas une procédure.

Les hooks d’automatisation exécutent des actions prédéterminées. Ils encodent une procédure, pas une politique.

Les hooks de jugement sont plus difficiles à écrire, plus difficiles à tester et plus précieux. quality-gate.sh a nécessité sept modes d’échec nommés, six critères de preuves et un détecteur de langage évasif. inject-context.sh a nécessité cinq lignes de bash. Mais les deux sont nécessaires. Les hooks d’automatisation fournissent les données que les hooks de jugement évaluent. sysmon-snapshot.sh (automatisation) alimente en données le moniteur de performances qui décide s’il faut recommander de réduire le nombre d’agents (jugement).

Le ratio compte. Dans une couche d’orchestration saine, les hooks de jugement devraient être plus nombreux que les hooks d’automatisation. Si la plupart des hooks ne font qu’injecter des données ou enregistrer des métriques, le système automatise bien mais gouverne mal. Un décompte vérifié du système actuel : 35 hooks de jugement, 44 hooks d’automatisation, soit environ 4:5. L’automatisation mène encore. Le ratio a commencé à environ 1:6 (presque exclusivement des hooks d’injection et de journalisation) et s’est déplacé vers le jugement sur deux mois, à mesure que des contraintes de gouvernance ont été ajoutées après avoir rencontré des échecs que la pure automatisation ne pouvait pas prévenir. Le ratio n’a pas encore atteint la parité, ce qui est en soi un signal utile : ce système gouverne encore moins qu’il n’automatise.

Séparation planification-exécution

L’article de Boris Tane « How I use Claude Code » a attiré 936 points sur Hacker News en décrivant un schéma de workflow : séparer la planification de l’exécution.⁴ Planifier avec une session Claude (rechercher, esquisser, concevoir), puis exécuter avec une session fraîche qui reçoit le plan en entrée structurée. Le schéma a résonné parce qu’il résout un vrai problème : la planification et l’exécution rivalisent pour l’espace de la fenêtre de contexte.

Le système de hooks est arrivé à la même séparation par un chemin différent. Le système de délibération engendre des agents spécialisés pour rechercher et débattre des approches. Le résultat est un PRD structuré (Product Requirements Document) avec des stories, des critères d’acceptation et des types de vérification. La boucle Ralph lit le PRD et engendre des instances Claude fraîches pour implémenter chaque story. Les agents de planification n’implémentent jamais. Les agents d’implémentation ne planifient jamais.

Cette séparation n’était pas un objectif de conception. Elle a émergé de deux contraintes indépendantes :

1. Pression de la fenêtre de contexte. La planification nécessite de lire de nombreux fichiers et d’explorer des options. L’implémentation nécessite un contexte focalisé sur la tâche en cours. Mettre les deux dans la même fenêtre de contexte signifie qu’aucun des deux n’obtient assez d’espace. Des sessions séparées donnent à chaque phase un contexte complet.

2. Indépendance de la vérification qualité. Si le même agent planifie et implémente, il ne peut pas vérifier objectivement sa propre implémentation par rapport au plan. Un agent frais disposant uniquement du plan et du code fournit une vérification indépendante. La boucle Ralph impose cela : les agents d’implémentation exécutent les tests, mais trois agents de revue distincts (correction, sécurité, conventions) vérifient les résultats.

La convergence entre le workflow manuel de Tane et le système automatisé de hooks suggère que la séparation planification-exécution est une propriété naturelle des systèmes agentiques, et pas seulement une préférence de praticien. Tout système qui gère des fenêtres de contexte et vérifie des sorties finira par séparer la planification de l’exécution, car l’alternative (faire les deux dans un seul contexte) produit de moins bons résultats dans les deux phases.

Là où le système de hooks échoue

L’architecture présente trois faiblesses significatives qu’un framework d’orchestration dédié résoudrait.

Pas de définitions de workflows déclaratifs. Chaque workflow est encodé de manière impérative dans des scripts bash. La boucle Ralph fait 1 320 lignes de bash qui encodent une séquence spécifique : lire le PRD, sélectionner la story, rassembler le contexte, engendrer Claude, exécuter les tests, lancer les revues, gérer les échecs, mettre à jour l’état. Modifier le workflow signifie éditer du bash. Un système déclaratif définirait les workflows comme des données (YAML, JSON) qu’un interpréteur exécute. Les workflows déclaratifs sont plus faciles à modifier, composer et visualiser. Les scripts impératifs sont plus faciles à écrire initialement mais plus difficiles à maintenir à mesure qu’ils grandissent.

L’ordonnancement des hooks est fragile. Le répartiteur de prompts exécute les hooks dans une séquence codée en dur. Déplacer memory-capsule-inject.sh avant inject-context.sh casserait l’injection de capsule car elle dépend de l’ID de session que inject-context.sh résout. Ces dépendances sont implicites (encodées dans l’ordonnancement du répartiteur) plutôt qu’explicites (déclarées comme dépendances entre hooks). Un système dédié exprimerait les dépendances des hooks sous forme de DAG et trierait topologiquement l’ordre d’exécution.

Pas de visualisation des workflows. Avec 84 hooks, comprendre le chemin d’exécution complet de toute action utilisateur nécessite de lire le code du répartiteur et de tracer les chaînes de hooks manuellement. Il n’existe aucun outil qui montre « quand l’utilisateur tape un message, ces 9 hooks se déclenchent dans cet ordre, et le hook 3 appelle la fonction de bibliothèque X qui écrit dans le fichier d’état Y ». Le système est observable via les logs mais pas via la structure. Un framework d’orchestration dédié fournirait un graphe visuel des dépendances de hooks, des flux de données et des chemins d’exécution.

Ces faiblesses partagent une cause commune : le système a grandi de manière organique en résolvant des problèmes individuels plutôt que d’être conçu comme une couche d’orchestration cohérente. La croissance organique produit des systèmes qui fonctionnent (les 84 hooks fonctionnent correctement en production) mais qui sont difficiles à appréhender dans leur ensemble. Le compromis est réel : concevoir la couche d’orchestration en amont aurait produit une meilleure structure mais de moins bonnes capacités, car de nombreuses capacités (capsules mémoire, listes blanches de sorties, budgets de spawn) ont été inventées en réponse à des échecs qui n’auraient pas pu être prédits avant qu’ils ne se produisent.

Ce que les praticiens devraient retenir

Si vous construisez une couche d’orchestration au-dessus d’un CLI d’agent, trois schémas de ce système sont directement transposables.

Commencez par les répartiteurs, pas par les hooks individuels. L’amélioration architecturale la plus significative a été de remplacer sept hooks UserPromptSubmit individuels par un seul répartiteur qui les exécute séquentiellement. Si vous anticipez plus de trois hooks sur un type d’événement donné, construisez d’abord le répartiteur. Les 30 minutes passées à écrire un répartiteur économisent des heures de débogage de bugs d’interaction entre hooks par la suite. Le schéma minimal :

#!/bin/bash
# dispatcher.sh — sequential hook execution with shared stdin
HANDLERS=("inject-context.sh" "track-usage.sh" "quality-gate.sh")
HOOK_DIR="$(dirname "$0")/handlers"
INPUT=$(cat)  # Cache stdin once (each handler gets the same input)

for handler in "${HANDLERS[@]}"; do
    [ -x "$HOOK_DIR/$handler" ] && echo "$INPUT" | "$HOOK_DIR/$handler"
done

Enregistrez ce répartiteur unique comme point d’entrée de vos hooks. Ajoutez les gestionnaires au tableau à mesure que vous les construisez. Chaque gestionnaire lit le même stdin mis en cache (la charge utile de l’événement hook) et écrit sur stdout indépendamment.

Séparez le jugement de l’automatisation dès le début. Lorsque vous écrivez un nouveau hook, demandez-vous : « Ce hook décide-t-il si quelque chose doit se produire, ou exécute-t-il une action prédéterminée ? » Les hooks de jugement nécessitent plus de tests, plus de gestion de cas limites et plus d’itérations. Les hooks d’automatisation nécessitent fiabilité et performance. Les traiter de la même manière conduit à des hooks de jugement sous-testés et des hooks d’automatisation sur-ingéniérés.

Laissez la séparation planification-exécution émerger. Ne forcez pas la séparation dès le premier jour. Construisez la chose la plus simple qui fonctionne. Quand vous remarquez que la fenêtre de contexte de votre agent est trop pleine pour la planification et l’implémentation à la fois, séparez-les. Quand vous remarquez que votre agent ne peut pas vérifier objectivement son propre travail, ajoutez des agents de revue indépendants. La séparation semblera évidente quand les contraintes l’exigeront.

L’approche par hooks a un avantage par rapport aux frameworks d’orchestration dédiés : zéro engagement. Chaque hook est indépendant. Vous pouvez adopter un hook, dix hooks ou quatre-vingt-quatre hooks. Vous pouvez supprimer n’importe quel hook sans casser les autres (à condition de maintenir le répartiteur). Il n’y a pas de framework à apprendre, pas de dépendance à gérer, pas de runtime à opérer. La couche d’orchestration n’est que des fichiers.

Karpathy a appelé cela une nouvelle couche computationnelle. L’implémentation est plus ancienne que le nom. Les praticiens construisent des Claws depuis la première fois qu’ils ont écrit un script shell pour encapsuler un appel CLI d’agent. La différence entre un script shell et une couche d’orchestration n’est pas une différence de nature. C’est une différence dans le nombre de problèmes que vous avez résolus, et dans le nombre de ces solutions qui ont dû se résoudre les unes les autres.

Sources