Claude Code Hooks: automatiza tu flujo de desarrollo con comandos propios

El problema que nadie menciona de los asistentes de IA en el terminal

Llevas semanas usando Claude Code y funciona bien. Pero cada vez que termina una sesión, tienes que recordarle el contexto del proyecto, repetir las mismas instrucciones de estilo, ejecutar manualmente los linters, o copiar los cambios al repositorio correcto. Eso no es automatización: es delegar el trabajo manual a otra pantalla.

Los Claude Code Hooks resuelven exactamente este problema. Son scripts o comandos que se ejecutan automáticamente en momentos clave del ciclo de vida de Claude Code: antes de que procese tu petición, después de que genere código, cuando detecta un error, o cuando termina la sesión. Con ellos puedes personalizar el comportamiento del agente sin tocar su lógica interna.

Por qué importa tener hooks en tu flujo de IA

La mayoría de los desarrolladores usan Claude Code de forma reactiva: escriben un prompt, reciben código, lo revisan. Los hooks cambian el modelo a uno proactivo y reproducible. En lugar de que cada sesión empiece desde cero, defines una capa de automatización que garantiza consistencia entre ejecuciones.

Casos de uso reales que justifican el tiempo de configuración:

• Ejecutar eslint --fix automáticamente después de cada bloque de código generado.
• Enviar una notificación a Slack cuando Claude Code completa una tarea larga.
• Hacer commit automático con un mensaje estructurado al terminar cada sesión de trabajo.
• Inyectar el contexto del proyecto (arquitectura, convenciones, dependencias clave) al inicio de cada conversación.
• Registrar en un log local qué cambios hizo el agente y cuándo.

Cómo configurar Claude Code Hooks: guía paso a paso

1. Localiza o crea el archivo de configuración

Claude Code lee su configuración desde un archivo claude.json en la raíz del proyecto o en ~/.claude/claude.json para configuración global. Si no existe, créalo:

touch ~/.claude/claude.json

2. Estructura básica de un hook

Los hooks se definen bajo la clave hooks y se organizan por evento. La estructura mínima es:

{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix"
          }
        ]
      }
    ]
  }
}

En este ejemplo, cada vez que Claude Code usa las herramientas Write o Edit (es decir, escribe o modifica un archivo), ejecuta el linter automáticamente. El campo matcher acepta expresiones regulares, lo que te da control granular.

3. Los eventos disponibles

Los cuatro puntos de extensión principales son:

• preToolUse: se dispara antes de que Claude use cualquier herramienta. Útil para validaciones o para inyectar contexto.
• postToolUse: se dispara después de que la herramienta termina. El caso más común: formateo, linting, tests.
• notification: cuando Claude genera una notificación interna. Puedes redirigirla a Slack, email o cualquier webhook.
• stop: cuando la sesión termina. Ideal para commits automáticos o resúmenes de cambios.

4. Hook práctico: commit automático al terminar

Este hook hace un commit con todos los cambios staged al finalizar la sesión, usando la fecha y hora como mensaje por defecto:

{
  "hooks": {
    "stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "git add -A && git commit -m 'Claude Code session: '$(date '+%Y-%m-%d %H:%M') || true"
          }
        ]
      }
    ]
  }
}

El || true al final evita que un repositorio sin cambios rompa el hook con un error de salida.

5. Hook práctico: inyectar contexto al inicio

Si trabajas en un monorepo con convenciones específicas, puedes cargar un archivo de contexto antes de cada herramienta que Claude use por primera vez:

{
  "hooks": {
    "preToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          {
            "type": "command",
            "command": "cat .claude-context.md"
          }
        ]
      }
    ]
  }
}

El archivo .claude-context.md puede contener la arquitectura del proyecto, las dependencias críticas, las convenciones de naming, o cualquier información que no quieres repetir manualmente en cada sesión.

6. Depuración: cómo saber si tus hooks funcionan

Activa el modo verbose de Claude Code para ver qué hooks se disparan y qué salida producen:

claude --debug

También puedes añadir un hook de logging simple que registre cada ejecución en un archivo local:

"command": "echo $(date) - Hook ejecutado >> ~/.claude/hooks.log"

El siguiente paso: hooks como estándar de equipo

Si trabajas en equipo, el mayor valor de los hooks no está en tu configuración personal sino en el archivo claude.json dentro del repositorio. Cuando todo el equipo comparte los mismos hooks, garantizas que nadie suba código sin linting, que los commits sigan la misma convención, o que los tests se ejecuten después de cada modificación generada por IA.

Añade claude.json al repositorio, documenta cada hook con un comentario en el README, y convierte la consistencia en algo que no depende de que alguien lo recuerde. Eso sí es automatización.