Que Claude Code escriba «listo» no demuestra que haya ejecutado las pruebas ni creado el archivo esperado. Un Stop Hook puede ejecutar una comprobación local breve antes de cerrar el turno. No sustituye CI ni una estrategia de pruebas completa.

Configuración mínima

En .claude/settings.json, conecta el evento Stop con ./scripts/check-before-stop.sh y define un timeout corto. El script puede ejecutar una prueba enfocada y comprobar dist/app.js.

Devuelve 0 cuando todo pasa. Si falla, escribe una sola causa concreta en stderr y termina con 2. En Claude Code, el código 2 bloquea Stop y entrega la causa a Claude; 1 normalmente solo registra un error no bloqueante.


{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "./scripts/check-before-stop.sh",
        "timeout": 30
      }]
    }]
  }
}


chmod +x scripts/check-before-stop.sh

Stop Hook ejecuta la comprobación al final del turno. CLAUDE.md describe reglas, pero no ejecuta comandos. CI corre por separado y sigue siendo la barrera final.


npm test -- --runInBand >/dev/null 2>&1 || { echo "Stop bloqueado: npm test" >&2; exit 2; }
test -s dist/app.js || { echo "Stop bloqueado: falta dist/app.js" >&2; exit 2; }
exit 0

Validación de extremo a extremo

Cambia temporalmente la ruta por un archivo inexistente y confirma manualmente el código 2.
Ejecuta una tarea pequeña en Claude Code. El hook debe impedir el cierre y mostrar la causa breve.
Corrige la prueba o la ruta y repite. El código 0 debe permitir el cierre.
Si stop_hook_active ya es verdadero, evita reintentos ciegos: corrige la comprobación o detén la sesión y repara el hook.

No imprimas API Keys, .env ni logs completos. Para un flujo API separado, consulta la guía de BetterToken para Claude Code.

Stop Hook de Claude Code: verificar antes de «listo»

Configuración mínima

Validación de extremo a extremo

¿Quieres optimizar tu flujo de trabajo con LLM?