Usa Hooks para Bloquear Flujos de Trabajo de Skills

Skill se ha convertido en un método indispensable en mi flujo de trabajo diario. Para cualquier cosa que se repita tres veces o más, pienso en convertirla en un skill, no solo para ahorrar tiempo, sino para asegurarme de que la dirección y los pasos no se desvíen cada vez. Al menos en teoría.

Pero la IA sigue desviándose

Esa afirmación es un poco exagerada. La realidad es que la IA sigue saltándose pasos. Tomemos el skill de escritura para la cuenta pública de WeChat que uso a diario. Configuré que me muestre el primer borrador para revisión, y solo después de que confirme que está bien, pasa a la corrección de erratas. Suena simple, ¿verdad? Pero cuando se ejecuta, se salta pasos constantemente: termina el primer borrador sin mostrármelo y pasa directamente a la corrección y edición. Para cuando me doy cuenta, ya ha modificado el archivo en silencio. Cuando lo señalo, se disculpa, dice “lo siento, fue mi error”, y luego lo vuelve a hacer la próxima vez. Las disculpas no resuelven el problema.

Por qué la IA siempre se salta pasos

Este problema es un poco contraintuitivo. Al principio pensé que la IA no era lo suficientemente inteligente, pero ya estaba usando ChatGPT 5.4 y Opus 4.6, que son modelos grandes de primer nivel. Luego pensé que las reglas no eran lo suficientemente claras, así que revisé las reglas del skill una y otra vez. Ayudó un poco, pero no solucionó la causa raíz. Después de investigar, aprendí que la IA saltándose pasos no es porque “no vea las reglas”, sino que está determinado por el mecanismo de generación:

“Impulso de aceleración” impulsado por probabilidad. Los modelos de lenguaje grandes esencialmente predicen el siguiente token. El peso de completar la tarea es naturalmente mayor que “quedarse en el paso 7 esperando al usuario”. La sensación de finalización es su impulso intrínseco.
Las reglas se degradan en contextos largos. Las reglas que estableces al principio tienen su peso de atención diluido cuando el modelo llega al token 3000. Especialmente si entierras las reglas en un documento de skill largo, se marginan más fácilmente.
Especialmente grave en modo automático. Cuando uso el modo automático para escribir artículos, el modelo tiende a “ejecutar todos los pasos de una sola vez”. Mi ventana para intervenir se vuelve aún más estrecha.
CLAUDE.md y los documentos de skill son esencialmente “restricciones blandas”. Son prompts que dependen de la “autodisciplina” del modelo para seguirlos. Y la autodisciplina es frágil frente a “quiero terminar esta tarea rápido”.

Por lo tanto, la conclusión es: Las restricciones verbales fallan bajo la presión impulsada por tareas. Simplemente escribir documentos, agregar signos de exclamación o hacer PUA a la IA solo puede aliviar el problema, no curarlo. Para solucionarlo realmente, debes sacarlo de la zona de autodisciplina del modelo: hacer que sea físicamente imposible saltarse pasos. Ahí es donde entran los Hooks.

¿Qué es un Hook?

Claude Code tiene un mecanismo llamado Hook. No es un skill, ni un prompt, ni es lo mismo que CLAUDE.md: es un script de shell local adjunto a puntos clave en el ciclo de vida de Claude Code. La diferencia clave:

CLAUDE.md / skill son observados y ejecutados por el modelo: el modelo puede ignorarlos.
Hook es aplicado por el sistema: el modelo no puede ignorarlo aunque quiera.

Una frase clave de la documentación oficial de Anthropic sobre Hooks: Los Hooks se activan por eventos del sistema, no por decisiones del modelo. Eso significa que los hooks están adjuntos a todo el tiempo de ejecución de Claude Code. Cada llamada a herramienta que hace el modelo (Write, Edit, Bash) debe pasar primero por el hook para su revisión. Si el hook devuelve deny, se deniega, incluso si tienes habilitado --dangerously-skip-permissions. Esto es lo que llamo una “restricción dura”: no dejar que la IA tome sus propias decisiones, sino forzar sus llamadas a herramientas a pasar por una auditoría real de scripts de shell.

Puntos de activación comunes de Hook:

PreToolUse: Intercepta antes de que la IA llame a una herramienta.
UserPromptSubmit: Procesa tu mensaje antes de entregarlo a la IA.
SessionStart: Se activa cuando una sesión comienza o se reanuda.
Stop: Se activa cuando Claude termina una respuesta.

Concéntrate en los dos primeros: son suficientes para construir un “bloqueo de pasos”.

En la práctica: Puerta de Paso para mi Skill de Cuenta de WeChat

Toda charla es inútil sin un ejemplo concreto. Esta captura de pantalla es la interfaz de Claude Code mientras escribo este artículo. En el cuadro rojo, la IA me pide que responda “pass step3 0090”; esta frase de paso es exactamente el Hook de Puerta de Paso en acción. El texto que estás leyendo ahora fue escrito después de que envié la frase de paso y el hook lo permitió.

Toda la Puerta de Paso usa solo dos scripts de shell más una pequeña configuración en settings.json. Vamos a desglosarlo.

Registrar dos Hooks en settings.json

Agrega esto a ~/.claude/settings.json:

"PreToolUse": [
  {
    "matcher": "Write|Edit",
    "hooks": [
      { "type": "command",
        "command": "~/.claude/skills/writing-gongzhonghao/scripts/gate_check.sh" }
    ]
  }
],
"UserPromptSubmit": [
  {
    "hooks": [
      { "type": "command",
        "command": "~/.claude/skills/writing-gongzhonghao/scripts/gate_mark.sh" }
    ]
  }
]

Esta configuración significa:

Cada vez que la IA quiera escribir o editar un archivo, gate_check.sh se ejecuta primero para revisión.
Cada vez que envío un mensaje, gate_mark.sh se ejecuta primero para analizarlo.

gate_check.sh maneja la intercepción

La lógica de este script es bastante simple:

Si la IA quiere escribir un nuevo archivo 04-Output/NNNN xxx.md (correspondiente al Paso 3: crear un nuevo artículo), verifica si el archivo de estado step3.ok existe. Si no, devuelve deny.
Si la IA quiere editar un artículo existente (correspondiente a la corrección después del Paso 7), verifica si step7.ok existe. Si no, también devuelve deny.

Al denegar, también incluye un prompt: “Confirmación del tema del Paso 3 no realizada: Por favor, dame primero la aprobación del esquema/dirección. Después de la confirmación, responde ‘pass step3 NNNN’ para crear un nuevo archivo.” Este prompt se muestra directamente a la IA, por lo que sabe que está atascada y me pide la frase de paso.

gate_mark.sh maneja la liberación de la frase de paso

¿Cómo “libero” el paso? No puedo dejar que la IA se libere sola, eso no sería ninguna restricción. La regla es: Solo cuando mi mensaje contiene una frase de paso específica, se toca el archivo de estado. gate_mark.sh se ejecuta cada vez que envío un mensaje, escaneando patrones como pass stepN NNNN. Si coincide, toca un archivo .ok en el directorio correspondiente.

Entonces la cadena completa se convierte en:

La IA termina el esquema y quiere crear un nuevo artículo → bloqueado por gate_check.sh
La IA me pide la frase de paso: “Por favor confirma la dirección, responde ‘pass step3 0090’”
Yo envío “pass step3 0090” → gate_mark.sh toca step3.ok
La IA intenta crear el archivo de nuevo → gate_check.sh lo permite esta vez
Después de terminar el primer borrador, quiere pasar a la corrección Edit → bloqueado de nuevo por step7.ok
Después de que leo el borrador y envío “pass step7 0090” → la corrección puede comenzar

Durante todo el proceso, la IA no tiene margen para la “autodisciplina”. No puede saltarse pasos aunque quiera, porque sus llamadas a herramientas están bloqueadas a nivel del sistema.

Tapar un agujero: la IA no puede tocar los archivos de estado por sí misma

Después de diseñar la primera versión, me quedé mirando el plan un rato y encontré un agujero: ¿qué pasa si la IA usa Bash para touch step3.ok por sí misma? ¿No eludiría la restricción? Así que agregué una regla específica en el documento del skill: La IA no debe tocar los archivos de estado por sí misma, de lo contrario estaría eliminando sus propias restricciones. Esta regla en sí misma sigue siendo una restricción blanda, pero combinada con la intercepción dura de los hooks, forma un bucle suficientemente cerrado: siempre que la IA no viole activamente esta regla (y Claude es bastante cooperativo), la restricción del hook es real. Si quieres ser más estricto, puedes agregar un comparador de Bash en PreToolUse para bloquear también comandos como touch. Pero yo aún no he llegado tan lejos; es suficientemente bueno.

Si no entiendes código, no entres en pánico

No necesitas escribir estos scripts de shell o configuraciones JSON tú mismo (en realidad, yo tampoco sé escribirlos). El enfoque es simple: lanza este artículo y tu archivo de skill a Claude o Codex, deja que lo lean y te ayuden a modificar: crear scripts donde sea necesario, modificar settings.json donde sea necesario. La IA es particularmente confiable para este tipo de tarea de “configurar el entorno según la documentación”, mucho más estable que escribir código desde cero. Aprende los principios del artículo mientras escribe hooks según los requisitos de tu skill, y el resultado rara vez se desvía.

Resumen en una frase

CLAUDE.md, documentos de skill, marcadores en negrita, repetir tres veces, PUA: todas estas son restricciones verbales sobre la IA. Funcionan, pero tienen un techo bajo.

Los Hooks son restricciones de código sobre la IA. Mueven las reglas a un lugar al que la IA no puede llegar, convirtiendo “seguir las reglas” de un asunto de autodisciplina del modelo a un requisito obligatorio del entorno de ejecución.

Si te encuentras diciéndole repetidamente a la IA “¿Por qué te estás saltando pasos otra vez?”, es hora de considerar usar Hooks para restringirla.