Hooks: el patrón que sustituye 80% de validaciones manuales

La diferencia entre pedirle al modelo y forzar al harness

Llevas tres semanas escribiendo "no hagas commits directos a main" en CLAUDE.md y el modelo lo respeta el 95% del tiempo. El otro 5% es el que rompe producción. La solución no es escribirlo más fuerte; es mover la validación fuera del modelo. Los hooks de Claude Code se ejecutan en el harness, no en el LLM: no se "olvidan", no se distraen, no negocian. Si el matcher dispara, el hook corre. Punto.

¿Por qué deberías implementar hooks en lugar de confiar en instrucciones de sistema?

Porque los modelos de lenguaje operan bajo probabilidades estadísticas y tienden a degradar el seguimiento de reglas conforme la ventana de contexto se satura. Un hook traslada el cumplimiento normativo a un proceso determinista del sistema operativo, garantizando una tasa de cumplimiento absoluta e inquebrantable frente a políticas críticas de infraestructura y seguridad de código.

PreToolUse y PostToolUse: dónde vive la lógica

• PreToolUse: corre antes de que la herramienta se ejecute. Si retornas exit code distinto de cero, la llamada se cancela. Aquí van validaciones bloqueantes: comandos peligrosos, edits a archivos protegidos, commits a ramas críticas.
• PostToolUse: corre después de éxito. Aquí van efectos secundarios: formatear código tras un Edit, regenerar tipos tras tocar el schema, correr tests, notificar a Slack.
• Stop, SessionStart, UserPromptSubmit: más nichos, pero útiles para auditoría e inicialización.

Configuración real

Esto vive en .claude/settings.json (proyecto) o ~/.claude/settings.json (global). El matcher filtra por nombre de herramienta:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{
          "type": "command",
          "command": "node ~/.claude/hooks/block-dangerous-bash.js"
        }]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "node ~/.claude/hooks/block-protected-files.js"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "node ~/.claude/hooks/prettier-format.js"
        }]
      }
    ]
  }
}

El hook que bloquea commits a main

// ~/.claude/hooks/block-dangerous-bash.js
const input = JSON.parse(require("fs").readFileSync(0, "utf-8"));
const cmd = input.tool_input?.command ?? "";

const dangerous = [
  /git\s+push\s+.*\s(main|master)\b/,
  /git\s+reset\s+--hard/,
  /rm\s+-rf\s+\//,
  /DROP\s+TABLE/i,
];

for (const re of dangerous) {
  if (re.test(cmd)) {
    console.error(`Blocked: command matches ${re}. If intentional, run in shell directly.`);
    process.exit(2); // exit code 2 = block + show stderr to model
  }
}
process.exit(0);

El exit code 2 es la convención: bloquea la herramienta y pasa el stderr al modelo para que entienda por qué falló. El modelo entonces busca otra forma de cumplir la tarea, no se queda peleando con el harness.

Comparativa de mecanismos de control en agentes IA

Para elegir el nivel de control adecuado dentro de tus flujos de desarrollo, es fundamental entender las diferencias operativas entre las herramientas disponibles:

Mecanismo	Punto de ejecución	Determinismo	Latencia agregada	Caso de uso principal
Instrucción de Prompt (CLAUDE.md)	Inferencia del LLM	Probabilístico (85-95%)	0 ms (costo en tokens)	Guías de estilo y convenciones semánticas
Skills personalizadas	Herramienta orquestada	Condicional al modelo	Media (tiempo de API)	Flujos de trabajo complejos multi-paso
Slash Commands	Entrada directa del usuario	Determinado por invocación	Baja (inmediato)	Disparadores manuales de rutinas repetitivas
Hooks del Harness	Entorno local del sistema	100% determinista	Sub-segundo (en scripts locales)	Políticas de seguridad y linters automáticos

Hook vs skill vs slash command

• Hook: validación o efecto automático que debe correr SIEMPRE. No negociable. No requiere contexto del usuario.
• Skill: procedimiento con lógica condicional que el modelo invoca cuando el contexto lo activa. Negociable, contextual.
• Slash command: shortcut explícito que el usuario invoca a mano. Cero ambigüedad, cero contexto.

Si te encuentras escribiendo "siempre debes hacer X antes de Y" en un skill, eso es un hook disfrazado. Muévelo.

Casos donde el ROI es brutal

• Formateo automático: prettier/eslint en PostToolUse tras cada Edit. Ahorra revisiones de diffs ruidosos.
• Bloqueo de secrets: PreToolUse en Write/Edit que rechaza si detecta patrones tipo sk-, AKIA, ghp_. De acuerdo con el reporte anual de seguridad de GitGuardian (2024), la mayor parte de las credenciales expuestas se filtran durante confirmaciones de código en etapas tempranas de desarrollo; interceptarlas en el editor mitiga este riesgo de raíz.
• Tests incrementales: PostToolUse que corre vitest related solo sobre archivos tocados.
• Auditoría: log de toda llamada Bash a Loki para forense post-incident.

El anti-patrón: hooks lentos

Si tu hook tarda 4 segundos, lo pagas en cada Edit. Multiplica por 80 edits en una sesión y son 5 minutos perdidos. Los hooks deben ser sub-segundo: validación pura, sin red, sin builds. Si necesitas algo pesado, dispáralo en background y deja que falle async (Slack, métricas), no bloquees la conversación.

El impacto de los hooks en equipos de desarrollo en LATAM

En empresas tecnológicas y agencias de nearshoring en México y América Latina, la integración acelerada de desarrolladores junior y contractors representa un desafío constante de estandarización. Cuando los equipos delegan la supervisión de arquitectura exclusivamente a revisiones de código entre pares, el costo operativo en horas hombre se dispara. Configurar hooks a nivel de repositorio repositorio centraliza las políticas de gobernanza técnica sin fricción cultural ni curvas de aprendizaje prolongadas.

Asimismo, los contratos de desarrollo nearshore con corporativos en Estados Unidos imponen cláusulas estrictas de cumplimiento como SOC 2 o ISO 27001. Un hook que bloquee la escritura de credenciales o la ejecución de scripts no autorizados en terminal sirve como evidencia auditable frente a clientes exigentes, transformando un archivo de configuración local en un control de seguridad corporativo comprobable.

Qué puede salir mal y cómo evitarlo

El error más frecuente al diseñar hooks radica en crear dependencias circulares. Si un hook de PostToolUse ejecuta un script que a su vez invoca una herramienta editada por el harness, puedes provocar un bucle infinito que congele la terminal del desarrollador. Mantén los hooks desacoplados de llamadas anidadas al agente.

Otro problema habitual ocurre cuando las expresiones regulares de validación son excesivamente rígidas. Si una validación bloquea comandos inocuos debido a un regex mal estructurado, los desarrolladores desactivarán el archivo de configuración global. Asegúrate de registrar mensajes de error descriptivos mediante el canal estándar de salida de error (stderr) para que tanto el modelo como el programador entiendan con exactitud qué regla se activó y cómo proceder sin deshabilitar la protección.

Cuenta tus hooks. Si tienes menos de tres, probablemente le estás pidiendo al modelo cosas que el harness debería hacer solo. ¿Cuál validación repites en cada CLAUDE.md y nunca codificaste?