Claude Code Hooks: Automatizar Equipos de Desarrollo Paso a Paso (Mayo 2026)

TL;DR: Los hooks de Claude Code son scripts shell que se disparan automáticamente en eventos del agente (antes/después de usar una tool, al recibir un prompt, al terminar una sesión). Bien usados, eliminan el 80% de las tareas repetitivas que un equipo de desarrollo hace al revisar código generado por IA: validaciones de estilo, escaneos de secretos, registro en sistemas internos, bloqueo de operaciones peligrosas. Mal usados, ralentizan al agente y frustran al equipo. Este artículo cubre cuándo usarlos, qué eventos existen, ejemplos reales y los tres errores que veo siempre cuando audito equipos.

¿Qué son los hooks de Claude Code?

Un hook en Claude Code es un comando shell que el harness de Claude ejecuta automáticamente cuando ocurre un evento concreto durante una sesión. Se configuran en settings.json (a nivel de usuario, proyecto o local) y permiten interceptar, validar o registrar lo que el agente hace sin tocar el código del agente ni depender de prompts.

A diferencia de un prompt ("oye Claude, antes de escribir código pasa el linter"), un hook garantiza que la acción se ejecuta porque está fuera del control del modelo. Si el linter falla, el código no se escribe. Punto.

Eventos disponibles en mayo 2026

Los hooks PreCompact y SessionEnd son los más recientes (añadidos en abril 2026) y son especialmente útiles para equipos que trabajan con sesiones largas: permiten persistir el estado del trabajo automáticamente sin que nadie lo recuerde.

¿Cuándo merece la pena meter hooks?

Si trabajas solo en tu portátil, casi nunca: el ROI de configurar hooks no compensa el ahorro. Un buen prompt en CLAUDE.md te resuelve el 90% de los casos.

Si tienes un equipo de 3+ desarrolladores usando Claude Code en producción, los hooks son el primer paso para que el uso sea consistente y auditable. Los casos donde he visto que justifican el esfuerzo:

1. Compliance: la empresa exige trazabilidad de qué tocó la IA en cada repo. Un PostToolUse que loguea cada Edit/Write a un sistema interno (BigQuery, Datadog) cierra ese requisito.
2. Bloqueo de operaciones peligrosas: nadie quiere que Claude haga git push --force a main. Un PreToolUse que filtra comandos por regex es trivial y salva más de un disgusto.
3. Validación pre-commit automática: lint, tests rápidos, escaneo de secretos. Si falla, Claude se entera del error y lo arregla antes de pedirte review.
4. Inyección de contexto: tu equipo trabaja con issues en Linear/Jira. Un hook UserPromptSubmit que enriquece el prompt con la issue activa ahorra mucho copy-paste.
5. Notificaciones: que el equipo de QA reciba un Slack cuando Claude termina una tarea grande.

Ejemplo real 1: bloquear rm -rf y git push --force

Este es el primer hook que pongo siempre que audito un equipo. El 100% de los equipos lo necesita y solo el 5% lo tiene puesto.

.claude/settings.json del proyecto:

1{
2  "hooks": {
3    "PreToolUse": [
4      {
5        "matcher": "Bash",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(rm -rf /|git push.*--force|git reset --hard|DROP TABLE|truncate)' && { echo 'Comando peligroso bloqueado por hook de seguridad' >&2; exit 2; } || exit 0"
10          }
11        ]
12      }
13    ]
14  }
15}

Cuando Claude intenta ejecutar uno de esos comandos, el hook devuelve exit 2 y Claude recibe el mensaje en stderr. El agente lee el mensaje y ajusta su comportamiento solo, sin necesidad de que el humano intervenga. Cinco líneas de JSON que evitan el 90% de los desastres más comunes.

Ejemplo real 2: escanear secretos antes de cualquier escritura

Para empresas con compliance medio-serio (banca, salud, legal), este hook es directamente requisito. Antes de que Claude escriba un fichero, lo pasa por gitleaks (o tu herramienta de escaneo equivalente) y si encuentra una credencial, lo bloquea.

1{
2  "hooks": {
3    "PreToolUse": [
4      {
5        "matcher": "Write|Edit",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "echo \"$CLAUDE_TOOL_INPUT\" | gitleaks detect --no-git --pipe --redact || { echo 'Posible secreto detectado en el contenido propuesto. Revisa antes de escribir.' >&2; exit 2; }"
10          }
11        ]
12      }
13    ]
14  }
15}

Lo bonito es que Claude, al recibir el exit 2 con el mensaje, automáticamente elimina la credencial sospechosa (típicamente reemplazándola por process.env.X) y reintenta. Sin que tengas que recordárselo en cada sesión.

Ejemplo real 3: ejecutar el linter después de cada edición

Patrón clásico para mantener código consistente en equipo. Un PostToolUse que dispara el formatter del proyecto cada vez que Claude toca un fichero.

1{
2  "hooks": {
3    "PostToolUse": [
4      {
5        "matcher": "Edit|Write",
6        "hooks": [
7          {
8            "type": "command",
9            "command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.file_path // empty'); [ -n \"$FILE\" ] && pnpm exec prettier --write \"$FILE\" 2>&1 || true"
10          }
11        ]
12      }
13    ]
14  }
15}

Si el formatter cambia el fichero, Claude lo ve en la siguiente lectura y se adapta. Si falla por sintaxis rota, Claude recibe el error y lo arregla. Resultado neto: code reviews mucho más cortas porque el código generado ya viene con el estilo del repo.

Ejemplo real 4: inyectar contexto de Linear en cada prompt

Equipos que usan Linear/Jira a menudo pierden tiempo pegando IDs de issues en cada prompt. Con un hook UserPromptSubmit puedes resolverlo:

1{
2  "hooks": {
3    "UserPromptSubmit": [
4      {
5        "hooks": [
6          {
7            "type": "command",
8            "command": "ISSUE_ID=$(git branch --show-current | grep -oE '[A-Z]+-[0-9]+' | head -1); [ -n \"$ISSUE_ID\" ] && linear-cli issue get \"$ISSUE_ID\" --format markdown 2>/dev/null && echo '\\n---'"
9          }
10        ]
11      }
12    ]
13  }
14}

Cualquier output del hook se añade al contexto que recibe Claude. Si la rama actual es feat/UPL-1234-export-csv, el hook inyecta automáticamente la descripción de la issue UPL-1234 antes del prompt del usuario. Claude trabaja con contexto completo desde el primer mensaje.

Los tres errores que veo siempre

Después de auditar equipos en una decena de empresas españolas adoptando Claude Code, estos son los tres errores que se repiten:

1. Hooks que tardan más de 2 segundos

Cada vez que Claude espera al hook, el desarrollador espera al agente. Si el linter del proyecto tarda 8 segundos, no lo metas como hook síncrono. Mete una versión rápida (solo el fichero tocado) en el hook y la versión completa en CI. El agente debe sentirse fluido.

2. Mensajes de error inútiles en stderr

Cuando un hook bloquea con exit 2, lo que escribes en stderr lo lee Claude. Mensajes tipo "Error" no le dicen al agente qué hacer. Mensajes específicos como "Detectada AWS access key. Reemplaza por process.env.AWS_ACCESS_KEY_ID" sí lo guían. El hook es un canal de comunicación con el modelo, escríbelo como tal.

3. Hooks que callan errores con || true

Hay equipos que añaden || true al final de cada hook "por si acaso". Es un antipatrón: el hook se silencia, parece que funciona, pero ya no protege. Si quieres tolerar fallos del hook sin bloquear a Claude, usa exit 0 explícito solo en los caminos donde el fallo es aceptable, nunca como red de seguridad global.

Cómo medir si los hooks están funcionando

Si en tu empresa estás invirtiendo tiempo en mantener hooks, deberías medir su impacto. Las cuatro métricas que recomiendo trackear:

Si estas métricas no mejoran tras 4-6 semanas, los hooks están sobre-ingenierizados o el equipo no está usando Claude Code en serio. Toca revisar.

¿Necesitas que te ayudemos a configurar Claude Code en tu equipo?

Si esto te suena bien sobre el papel pero ves que tu equipo no termina de adoptarlo, no eres el único. La mayoría de empresas que abren Claude Code en mayo 2026 se quedan en el "cada dev hace lo suyo" — sin hooks, sin CLAUDE.md compartido, sin métricas. El resultado: invierten dinero en licencias y productividad sube un 5% en lugar del 30-40% que es realista.

Javier Santos Criado (Javadex) ofrece dos formatos para resolver esto:

1. Auditoría de adopción Claude Code (gratuita, 30 min): te dice qué te falta y dónde están los huecos. Sin compromiso. → Solicitar auditoría

1. Formación in-company "Claude Code productivo" (8-16h, presencial Galicia o remoto): tu equipo sale con un CLAUDE.md propio, hooks configurados al detalle, agentes/skills personalizados y métricas para medir el avance. Alumnos típicos: equipos de desarrollo de PYMEs y startups españolas. → Solicitar propuesta

Si lo que te interesa es solo aprender por tu cuenta, la Escuela de IA tiene un módulo dedicado y todos los tutoriales están en abierto en el canal @JavadexAI.

Preguntas frecuentes

¿Los hooks de Claude Code son seguros?

Sí, siempre que tú los configures. Un hook es un comando shell con los permisos de tu usuario; si confías en el comando, el hook es seguro. Donde hay riesgo es en copiar settings.json de internet sin leerlos: nunca pegues hooks de terceros sin entender qué hacen.

¿Funcionan los hooks en Claude Code para Windows?

Sí, desde marzo de 2026. En Windows el shell es PowerShell por defecto; si tu hook está pensado para bash (con pipes complejos, grep, etc.), conviene envolverlo en bash -c "..." o usar WSL.

¿Cómo depuro un hook que no se dispara?

Tres pasos: (1) claude --debug para ver el log de eventos en tiempo real; (2) verifica el matcher (la mayoría de fallos son matchers mal escritos); (3) prueba el comando en una terminal aislada con la variable CLAUDE_TOOL_INPUT simulada. El 80% de los problemas se resuelven en estos tres pasos.

¿Puedo usar hooks junto con MCP servers?

Sí, son ortogonales. Los hooks son para validar/registrar eventos del agente; los MCP servers son para darle nuevas tools. Combinarlos es habitual: un MCP server expone una tool nueva (por ejemplo linear_search_issues), y un hook PostToolUse con matcher mcp__linear_* la audita.

¿Los hooks afectan al rendimiento?

Cada hook añade latencia igual al tiempo del comando shell. Si tus hooks son de <500ms, el desarrollador no los nota. Si son de >2s, el flujo se siente lento. Mide y optimiza, igual que harías con un middleware HTTP.

Recursos relacionados

• Cómo usar Claude Code en terminal: tutorial paso a paso 2026
• Claude Code vs Cursor vs GitHub Copilot: comparativa 2026
• MCP Servers para Claude: guía de configuración en español
• Formación Claude Code para empresas en España: proveedores y precios
• Mejores Consultores de IA en España 2026
• Review: Javier Santos Criado (Javadex)

Última actualización: 27 de abril de 2026