Hooks: comprobaciones que se ejecutan solas
Comandos que se ejecutan automáticamente en momentos concretos del trabajo del agente, como antes de editar un archivo o al terminar, para que los pasos importantes no dependan de que el agente se acuerde.
Antes de empezar
- Verificación y evaluaciónTécnica
Cómo comprobar que el agente hizo bien el trabajo sin fiarte de su palabra: darle formas de verificarse a sí mismo, revisar el resultado y el proceso, y comparar configuraciones con honestidad.
Publicado
La idea clave: si algo tiene que pasar siempre, no lo dejes en una instrucción. Un hook es un comando que se ejecuta solo en un momento concreto —por ejemplo, cuando el agente termina—, tanto si el agente se acuerda como si no.
El problema
En Verificación y evaluación viste que el agente debe comprobar su trabajo con pruebas, tipos o linter. Lo normal es pedírselo en el AGENTS.md. El agente lo lee y casi siempre lo hace.
“Casi siempre” es el problema. Una instrucción es una petición: el modelo decide si la sigue. En una sesión larga, con mucho contexto, puede olvidarla o decidir que esta vez no hace falta. Y entonces te entrega un cambio con las pruebas rotas.
Cómo funciona
Piensa en el aviso del cinturón de un coche: no depende de que te acuerdes de ponértelo, salta solo. Un hook funciona igual. Le dices al programa que rodea al agente: “cuando pase esto, ejecuta este comando”.
Para empezar, bastan tres momentos. Los nombres son los de Claude Code:
| Momento | Nombre en Claude Code | Ejemplo de uso |
|---|---|---|
| Antes de usar una herramienta | PreToolUse |
Bloquear la edición de .env |
| Después de usar una herramienta | PostToolUse |
Formatear el archivo que acaba de editar |
| Cuando el agente va a terminar | Stop |
Pasar las pruebas antes de dar algo por hecho |
Al terminar, el hook responde con un número, su código de salida. Solo necesitas recordar dos:
- Código 0: no hay objeciones. Todo sigue como siempre.
- Código 2: “todavía no”. Si el hook es de antes de una herramienta, Claude Code la bloquea. Si es del final, el agente no puede terminar aún. En los dos casos, el agente recibe el mensaje de error del hook y puede corregir.
Otros agentes tienen mecanismos parecidos con otros nombres. Si el tuyo no los tiene, un hook de Git como pre-commit o la integración continua cumplen una función similar, aunque más tarde: cuando se guarda el cambio, no mientras el agente trabaja.
Ejemplo práctico
Sigue con la tarea de summarizeReading. Quieres que el agente no pueda darla por terminada si las pruebas fallan. En Claude Code, añade esto a .claude/settings.json, el mismo archivo donde se escriben los permisos:
{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "node --test >&2 || exit 2"
}
]
}
]
}
}
Qué hace cada parte:
"Stop"es el momento: el hook se ejecuta cada vez que el agente va a terminar su respuesta.node --testejecuta las pruebas del proyecto.>&2envía el resultado de las pruebas a la salida de errores. Es el texto que Claude Code le enseña al agente cuando algo falla, así sabe qué prueba falló.|| exit 2significa “si las pruebas fallan, termina con el código 2”. El agente no puede terminar todavía: recibe el error y sigue trabajando.
Si las pruebas pasan, no ocurre nada visible. Si fallan, el agente ve el error y lo corrige antes de entregarte el trabajo. La instrucción del AGENTS.md sigue siendo útil, porque explica cómo se prueba el proyecto, pero ya no es lo único que lo garantiza.
¿Instrucción, permiso o hook?
| Si quieres… | Usa |
|---|---|
| Que el agente sepa cómo se trabaja en el proyecto | AGENTS.md |
| Que el agente no pueda hacer una acción concreta | Permisos |
| Que un comando se ejecute siempre en un momento concreto | Un hook |
Se complementan: el AGENTS.md explica, los permisos impiden y los hooks automatizan.
Errores comunes
- Hooks lentos. El hook de
Stopse ejecuta cada vez que el agente termina de responder, también cuando solo contesta una pregunta. Usa comprobaciones rápidas y deja las lentas para la integración continua. - Un control imposible de cumplir. Si las pruebas fallan por algo que el agente no puede arreglar, lo obligas a seguir intentándolo. Claude Code corta después de varios intentos seguidos, pero es mejor que el control se pueda cumplir.
- Creer que un hook lo ve todo. Un hook que bloquea la edición de
.envno ve los cambios que el agente haga con un comando de terminal. Para impedir algo de verdad, combínalo con permisos y aislamiento, como explica Ejecución segura. - Copiar hooks sin leerlos. Un hook es un comando que se ejecuta en tu máquina con tus permisos. Revisa los hooks de un proyecto ajeno igual que revisarías cualquier script antes de ejecutarlo.
- Convertirlo todo en un hook. Si un paso solo hace falta en algunas tareas, encaja mejor en una Skill. Reserva los hooks para lo que tiene que pasar siempre.
Cuándo usarlo
Cuando ves que el agente olvida el mismo paso más de una vez, o cuando un paso no puede faltar nunca. Empieza por uno solo, como las pruebas al terminar, y añade otro cuando aparezca un olvido nuevo que se repita.
Siguiente paso
Con las comprobaciones automatizadas, puedes repartir el trabajo sin perder el control. Subagentes y delegación explica cuándo dividir una tarea entre varios agentes y cómo reunir sus resultados.
Fuentes
Consultadas el 2026-10-08.
- Automate actions with hooks, documentación de Claude Code.
- Hooks reference, documentación de Claude Code. Detalla qué significa cada código de salida en cada momento.
Contenido relacionado
- AGENTS.md: instrucciones persistentes para un proyectoTécnica
Un archivo Markdown en la raíz del repositorio que explica al agente cómo funciona tu proyecto: comandos, convenciones y cómo comprobar los cambios. Es una guía, no un mecanismo de control.
Publicado - Herramientas y permisosTécnica
Qué es una herramienta, cómo la usa un agente y cómo decidir qué puede hacer sin preguntar, qué necesita tu aprobación y qué queda prohibido.
Publicado