Orquestar hooks en Claude Code: del script suelto al bus de eventos
Una acentuación progresiva de reglas y telemetría para gestionar la escalabilidad de los hooks en agentes de IA.
La serie de artículos sobre Claude Code llega a su cuarta parte centrándose en cómo gestionar la complejidad de los hooks cuando el volumen de reglas crece. El problema de partida es claro: un único hook de tipo Stop que intenta validar todo el flujo de respuesta no escala, y gestionar una decena de scripts independientes resulta un mantenimiento insoportable. La solución propuesta es unificar el procesamiento a través de un bus de eventos centralizado que registre la telemetría antes de aplicar cualquier lógica.
Eventos y reglas
Claude Code ofrece varios puntos de inserción para ejecutar scripts personalizados, conocidos como hooks. El autor detalla cómo asignar cada regla al momento preciso de la interacción. Por ejemplo, las reglas sobre el trabajo a realizar (como incluir un paso de rollback en migraciones de bases de datos) deben ejecutarse en UserPromptSubmit, ya que su salida se inyecta antes de que el modelo comience a generar. Las restricciones sobre el uso de herramientas, como validar la escritura en carpetas de documentación, pertenecen a PreToolUse. Aquí, un hook puede incluso bloquear la llamada a la herramienta si no se cumplen los criterios. Finalmente, las verificaciones de longitud o formato de la respuesta final viven en Stop, donde el agente puede rechazar la respuesta y solicitar una nueva si excede los límites definidos por tipo de respuesta.
Telemetría primero
Antes de mover la lógica, el autor recomienda instrumentar el sistema. Un bus de eventos simple, implementado en un script de bash que utiliza jq, captura cada evento en un formato JSONL. Esto permite cuantificar el comportamiento del agente. En su propio caso, al analizar 13 días de logs en cuatro repositorios, detectó que 106 de 1.979 intentos de respuesta carecían del token de tipo inicial esperado, una frecuencia de 1 entre 19 que habría pasado desapercibida sin registros. Además, los chequeos de fin de respuesta reenviaron el 25% de las interacciones. Esta visibilidad es clave para ajustar las reglas con datos reales en lugar de suposiciones.
La arquitectura propuesta reduce la complejidad de settings.json a una única entrada por evento, apuntando al mismo script del bus. El bus lee el payload, determina qué reglas aplican y responde al harness. Aunque el artículo menciona plugins como hookify de Anthropic para gestionar reglas en archivos markdown, el enfoque de bus ofrece mayor control sobre la lógica de estado y la observabilidad. Para quien administre flujos de trabajo con agentes de IA, este patrón de logging centralizado y enrutamiento de eventos es una lección práctica sobre cómo mantener el control cuando la configuración deja de ser trivial.
