Anatomía de una Garra: 84 Hooks como Capa de Orquestación

El primer hook tardó cuatro minutos en escribirse. Bloqueaba al modelo para que no sugiriera productos de OpenAI en un flujo de trabajo exclusivo de Anthropic. Dos meses después, ese único hook se convirtió en 84. Los 84 hooks se conectaron a 43 skills, 19 agentes especializados y 30 módulos de biblioteca. En algún momento, la colección dejó de ser un conjunto de scripts y se convirtió en una capa de orquestación.

No lo diseñé de esa manera. Nadie se sienta y dice “voy a construir 15.000 líneas de infraestructura de agentes.” Usted resuelve un problema. Luego otro. Luego resuelve el problema de los problemas interactuando entre sí. Para cuando nota la arquitectura, esta ya existe.

Andrej Karpathy también lo notó. En febrero de 2026, describió las “Claws” como una nueva capa computacional: orquestación, programación de tareas, gestión de contexto y enrutamiento de herramientas construidos sobre agentes LLM, de la misma manera en que los agentes se construyen sobre los LLMs.¹ El marco conceptual cristalizó algo que los profesionales habían estado construyendo sin nombrar. Este artículo es la anatomía de uno de esos sistemas: qué contiene, cómo creció, dónde funciona y dónde falla.

TL;DR

La capa “Claws” de Karpathy describe sistemas de orquestación construidos sobre CLIs de agentes. Construí uno de forma orgánica durante dos meses sobre Claude Code: 84 hooks en 15 tipos de eventos, 43 skills, 19 agentes y más de 30 módulos de biblioteca. El sistema se mapea claramente a cinco funciones de Claws (orquestación, programación de tareas, gestión de contexto, enrutamiento de herramientas, aplicación de calidad) con una brecha notable (definiciones declarativas de flujos de trabajo). Hallazgo clave: la separación entre planificación y ejecución emergió como una propiedad natural de la orquestación basada en hooks, no como un objetivo de diseño. La observación de Lattner de que “el juicio y la abstracción siguen siendo centrales mientras la IA automatiza la implementación” se mapea directamente a la arquitectura de hooks: los hooks de gobernanza ejercen juicio, los hooks de automatización ejecutan la implementación.

La Taxonomía de Claws

La descripción de Karpathy identifica cinco funciones que una capa de Claws realiza. Cada función tiene un análogo directo en el sistema de hooks que construí sobre Claude Code durante los últimos dos meses.¹

La taxonomía es útil porque separa responsabilidades que los profesionales tienden a construir de manera enredada. Mis primeros hooks mezclaban la gestión de contexto con la aplicación de calidad. El hook de seguimiento de costos tanto inyectaba contexto de presupuesto (gestión de contexto) como bloqueaba operaciones costosas (aplicación de calidad). Separarlos en hooks distintos mejoró la confiabilidad porque cada hook podía fallar de manera independiente sin romper la otra función.

El Sistema Completo

Los números a febrero de 2026:

La distribución de hooks entre tipos de eventos revela dónde se concentra la complejidad de la orquestación:

UserPromptSubmit lleva el mayor peso porque se dispara en cada mensaje del usuario. El despachador (prompt-dispatcher.sh) ejecuta nueve hooks secuencialmente en cada prompt: filtrado de seguridad, analítica, seguimiento de uso, monitoreo del sistema, inyección de objetivos, bloqueo de estimaciones de tiempo, inyección de contexto, inyección de temas de memoria y monitoreo de presión de contexto.²

Cada hook añade latencia. Nueve hooks secuenciales añaden un total medido de 200ms por prompt. El despachador los ejecuta secuencialmente (no en paralelo) porque las escrituras concurrentes de hooks a archivos JSON de estado compartidos causaron corrupción de datos en pruebas tempranas. Dos hooks escribiendo a jiro.state.json simultáneamente producían JSON truncado que rompía todos los hooks posteriores. La ejecución secuencial es más lenta pero segura. La sobrecarga de 200ms es invisible para los usuarios porque la velocidad de escritura humana es el cuello de botella, no la latencia de los hooks.

Cómo Creció

El crecimiento no fue lineal. Siguió un patrón de ciclos de problema-solución-integración.

Fase 1: Hooks de propósito único (Semana 1-2). Cada hook resolvía un problema. enforce-opus-model.sh bloqueaba solicitudes de modelos que no fueran Opus. no-time-estimates.sh eliminaba estimaciones de esfuerzo de las respuestas. filter-sensitive.sh detectaba credenciales en llamadas de herramientas. Estos hooks operaban independientemente. Ningún hook sabía de la existencia de otro.

Fase 2: Problemas de coordinación (Semana 3-4). Los hooks comenzaron a interferir entre sí. El filtro de credenciales bloqueaba llamadas legítimas a APIs. El aplicador de modelo entraba en conflicto con la generación de subagentes. La solución: despachadores. Un único punto de entrada (prompt-dispatcher.sh) reemplazó siete hooks individuales de UserPromptSubmit, controlando el orden de ejecución y compartiendo estado a través de un pipe de stdin en caché.

Fase 3: Capacidades compuestas (Semana 5-8). Los hooks individuales se compusieron en sistemas. El bucle de calidad conectó hooks pre-herramienta (detectando problemas antes de que ocurran) con hooks post-herramienta (verificando resultados después de que ocurren) a través de un archivo de estado compartido (jiro.state.json). El sistema de deliberación usó guardias de recursión, presupuestos de instancias y protocolos de consenso para coordinar múltiples agentes sin bucles infinitos. Ralph (el bucle de desarrollo autónomo) conectó archivos PRD con la generación de instancias de Claude, verificación de pruebas y revisión de código en un único pipeline orquestado.

Fase 4: Autoconciencia (Semana 9+). El sistema se volvió lo suficientemente grande como para necesitar herramientas para entenderse a sí mismo. La búsqueda semántica a través del sistema de hooks (skill /find) permitió a los agentes descubrir hooks por propósito en lugar de por nombre de archivo. El monitoreo de rendimiento (skill /perf) rastreaba si la sobrecarga del propio sistema estaba degradando la máquina. Un monitor de presión de contexto advertía cuando el contexto inyectado por la capa de orquestación estaba consumiendo demasiado de la ventana de contexto del modelo.

La progresión de hooks de propósito único a infraestructura de automonitoreo refleja un patrón que Chris Lattner identificó en su revisión del proyecto Claude C Compiler: “El buen software depende del juicio, la comunicación y la abstracción clara. La IA ha amplificado esto.”³ La arquitectura del sistema de hooks revela la misma verdad. Los hooks valiosos no son los que automatizan tareas. Los hooks valiosos son los que codifican juicio sobre cuándo y cómo las tareas deben ser automatizadas.

Hooks de Juicio vs. Hooks de Automatización

La revisión de Lattner del Claude C Compiler distinguió entre lo que la IA automatiza bien (implementación) y lo que permanece fundamentalmente humano (juicio y abstracción).³ Esta distinción se mapea directamente al sistema de hooks.

Los hooks de juicio deciden si algo debe ocurrir. Codifican política, no procedimiento.

Los hooks de automatización ejecutan acciones predeterminadas. Codifican procedimiento, no política.

Los hooks de juicio son más difíciles de escribir, más difíciles de probar y más valiosos. quality-gate.sh requirió siete modos de fallo nombrados, seis criterios de evidencia y un detector de lenguaje evasivo. inject-context.sh requirió cinco líneas de bash. Pero ambos son necesarios. Los hooks de automatización proporcionan los datos que los hooks de juicio evalúan. sysmon-snapshot.sh (automatización) alimenta datos al monitor de rendimiento que decide si recomendar la reducción del número de agentes (juicio).

La proporción importa. En una capa de orquestación saludable, los hooks de juicio deberían superar en número a los hooks de automatización. Si la mayoría de los hooks simplemente inyectan datos o registran métricas, el sistema automatiza bien pero gobierna pobremente. Un conteo verificado del sistema actual: 35 hooks de juicio, 44 hooks de automatización, aproximadamente 4:5. La automatización aún lidera. La proporción comenzó en aproximadamente 1:6 (casi todos eran hooks de inyección y registro) y se desplazó hacia el juicio durante dos meses a medida que se añadieron restricciones de gobernanza tras encontrar fallos que la automatización pura no podía prevenir. La proporción aún no ha alcanzado la paridad, lo cual es en sí mismo una señal útil: este sistema aún gobierna menos de lo que automatiza.

Separación entre Planificación y Ejecución

El artículo de Boris Tane “How I use Claude Code” atrajo 936 puntos en Hacker News al describir un patrón de flujo de trabajo: separar la planificación de la ejecución.⁴ Planificar con una sesión de Claude (investigando, delineando, diseñando), luego ejecutar con una sesión nueva que recibe el plan como entrada estructurada. El patrón resonó porque resuelve un problema real: la planificación y la ejecución compiten por espacio en la ventana de contexto.

El sistema de hooks llegó a la misma separación por un camino diferente. El sistema de deliberación genera agentes especializados para investigar y debatir enfoques. La salida es un PRD (Documento de Requisitos de Producto) estructurado con historias, criterios de aceptación y tipos de verificación. El bucle Ralph lee el PRD y genera instancias frescas de Claude para implementar cada historia. Los agentes de planificación nunca implementan. Los agentes de implementación nunca planifican.

Esta separación no fue un objetivo de diseño. Emergió de dos restricciones independientes:

1. Presión de la ventana de contexto. La planificación requiere leer muchos archivos y explorar opciones. La implementación requiere un contexto enfocado en la tarea actual. Poner ambos en la misma ventana de contexto significa que ninguno obtiene suficiente espacio. Las sesiones separadas dan a cada fase contexto completo.

2. Independencia de la verificación de calidad. Si el mismo agente planifica e implementa, no puede verificar objetivamente su propia implementación contra el plan. Un agente nuevo con solo el plan y el código proporciona verificación independiente. El bucle Ralph aplica esto: los agentes de implementación ejecutan pruebas, pero tres agentes de revisión separados (corrección, seguridad, convenciones) verifican los resultados.

La convergencia entre el flujo de trabajo manual de Tane y el sistema automatizado de hooks sugiere que la separación planificación-ejecución es una propiedad natural de los sistemas agénticos, no solo una preferencia de los profesionales. Cualquier sistema que gestione ventanas de contexto y verifique salidas eventualmente separará la planificación de la ejecución porque la alternativa (hacer ambas en un solo contexto) produce peores resultados en ambas fases.

Dónde Falla el Sistema de Hooks

La arquitectura tiene tres debilidades significativas que un marco de orquestación diseñado a propósito abordaría.

Sin definiciones declarativas de flujos de trabajo. Cada flujo de trabajo está codificado imperativamente en scripts de bash. El bucle Ralph tiene 1.320 líneas de bash que codifican una secuencia específica: leer PRD, seleccionar historia, recopilar contexto, generar Claude, ejecutar pruebas, ejecutar revisiones, manejar fallos, actualizar estado. Cambiar el flujo de trabajo implica editar bash. Un sistema declarativo definiría flujos de trabajo como datos (YAML, JSON) que un intérprete ejecuta. Los flujos de trabajo declarativos son más fáciles de modificar, componer y visualizar. Los scripts imperativos son más fáciles de escribir inicialmente pero más difíciles de mantener a medida que crecen.

El orden de los hooks es frágil. El despachador de prompts ejecuta hooks en una secuencia codificada. Mover memory-capsule-inject.sh antes de inject-context.sh rompería la inyección de cápsulas porque depende del ID de sesión que inject-context.sh resuelve. Estas dependencias son implícitas (codificadas en el orden del despachador) en lugar de explícitas (declaradas como dependencias entre hooks). Un sistema diseñado a propósito expresaría las dependencias de hooks como un DAG y ordenaría topológicamente el orden de ejecución.

Sin visualización de flujos de trabajo. Con 84 hooks, entender la ruta completa de ejecución de cualquier acción del usuario requiere leer el código del despachador y rastrear cadenas de hooks manualmente. No existe una herramienta que muestre “cuando el usuario escribe un mensaje, estos 9 hooks se disparan en este orden, y el hook 3 llama a la función de biblioteca X que escribe en el archivo de estado Y.” El sistema es observable a través de logs pero no a través de estructura. Un marco de orquestación diseñado a propósito proporcionaría un gráfico visual de dependencias de hooks, flujos de datos y rutas de ejecución.

Estas debilidades comparten una causa común: el sistema creció orgánicamente a partir de la resolución de problemas individuales en lugar de ser diseñado como una capa de orquestación coherente. El crecimiento orgánico produce sistemas que funcionan (los 84 hooks funcionan correctamente en producción) pero son difíciles de razonar como un todo. La compensación es real: diseñar la capa de orquestación por adelantado habría producido mejor estructura pero peores capacidades, porque muchas capacidades (cápsulas de memoria, listas blancas de salida, presupuestos de instancias) fueron inventadas en respuesta a fallos que no podrían haberse predicho antes de que ocurrieran.

Lo que los Profesionales Deberían Llevarse

Si usted está construyendo una capa de orquestación sobre un CLI de agentes, tres patrones de este sistema se transfieren directamente.

Comience con despachadores, no con hooks individuales. La mejora arquitectónica más grande fue reemplazar siete hooks individuales de UserPromptSubmit con un único despachador que los ejecuta secuencialmente. Si anticipa más de tres hooks en cualquier tipo de evento, construya el despachador primero. Los 30 minutos dedicados a escribir un despachador ahorran horas de depuración de errores de interacción entre hooks después. El patrón mínimo:

#!/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

Registre este único despachador como su punto de entrada de hooks. Añada manejadores al arreglo a medida que los construya. Cada manejador lee el mismo stdin en caché (la carga útil del evento de hook) y escribe a stdout de manera independiente.

Separe el juicio de la automatización desde temprano. Cuando escriba un nuevo hook, pregúntese: “¿Este hook decide si algo debe ocurrir, o ejecuta una acción predeterminada?” Los hooks de juicio necesitan más pruebas, más manejo de casos límite y más iteración. Los hooks de automatización necesitan confiabilidad y rendimiento. Tratarlos de la misma manera conduce a hooks de juicio poco probados y hooks de automatización sobreelaborados.

Permita que la separación planificación-ejecución emerja. No fuerce la separación desde el primer día. Construya lo más simple que funcione. Cuando note que la ventana de contexto de su agente está demasiado llena para la planificación y la implementación simultáneamente, sepárelas. Cuando note que su agente no puede verificar objetivamente su propio trabajo, añada agentes de revisión independientes. La separación se sentirá obvia cuando las restricciones lo exijan.

El enfoque basado en hooks tiene una ventaja sobre los marcos de orquestación diseñados a propósito: cero compromiso. Cada hook es independiente. Puede adoptar un hook, diez hooks u ochenta y cuatro hooks. Puede eliminar cualquier hook sin romper otros (asumiendo que mantiene el despachador). No hay un marco que aprender, ninguna dependencia que gestionar, ningún runtime que operar. La capa de orquestación son solo archivos.

Karpathy lo llamó una nueva capa computacional. La implementación es más antigua que el nombre. Los profesionales han estado construyendo Claws desde la primera vez que escribieron un script de shell para envolver una llamada a un CLI de agentes. La diferencia entre un script de shell y una capa de orquestación no es una diferencia de tipo. Es una diferencia en cuántos problemas ha resuelto, y cuántas de esas soluciones tuvieron que resolverse entre sí.

Fuentes