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 --test ejecuta las pruebas del proyecto.
  • >&2 enví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 2 significa “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 Stop se 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 .env no 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.