Guías prácticas para trabajar con agentes de IA
Una instrucción en CLAUDE.md es una petición que el agente casi siempre cumple. Un hook es una regla que se ejecuta fuera del modelo y bloquea la acción. Aquí ves la diferencia, cómo se configura y qué se le escapa.
6 min de lectura laboratorio: banco de pruebas publicado el 27 sept 2026
Un agente de programación ejecuta comandos en tu equipo: borra carpetas, lee ficheros, instala paquetes, sube cambios. Lo habitual es escribir en CLAUDE.md o AGENTS.md lo que no debe hacer: «no toques el fichero .env», «no hagas push a main».
Esas instrucciones funcionan casi siempre, pero son texto dentro del contexto del modelo: el agente las lee y decide. En sesiones largas compiten con todo lo demás que ha leído, y al resumir el historial para liberar espacio pueden perderse. Un preprint de junio de 2026 midió que, tras compactar, el incumplimiento de normas pasaba del 0 % al 30 % de media V, aunque es un estudio de un solo autor y sin revisión por pares.
Corregido el 7 de octubre de 2026. Esta guía decía sin condiciones que con el código 2 la acción se bloquea. Es cierto frente a las reglas de permiso —una decisión de un hook PreToolUse no se salta las reglas, y una regla deny que case bloquea la llamada pase lo que pase—. V Lo que faltaba es quién puede deshacer esa decisión después.
Un mod instalado puede aprobar después lo que el hook bloqueó. Un mod que atienda la comprobación de permisos responde cuando las reglas y los hooks ya han decidido, y su respuesta puede sustituir a la de ellos: puede aprobar una llamada que un hook PreToolUse bloqueó. V Hay dos casos en que no puede: si en la máquina hay configuración gestionada por tu organización, o si la sesión ha entrado con un /login de Team o Enterprise. En los dos, una llamada que el hook bloqueó sigue bloqueada, venga el hook del fichero de ajustes que venga, y una regla deny sigue mandando sobre el mod. V Lo que cuenta es con qué credencial corre la sesión, no qué plan tienes: una sesión que corre con una clave de API o con una credencial de larga duración (CLAUDE_CODE_OAUTH_TOKEN) no usa ese login, aunque lo tengas guardado. V En cualquier otro caso —que es el de quien trabaja con Pro o Max en su propio ordenador— el mod puede aprobar incluso lo que una regla deny rechaza. V
Corregido el 24 de octubre de 2026. Este párrafo decía que el bloqueo de un hook solo aguantaba frente a un mod si el hook estaba en la configuración gestionada, y que bastaba con tener plan Team o Enterprise para que las reglas deny mandaran. La referencia de permisos, leída hoy, dice lo que pone arriba: con configuración gestionada o con un /login de Team o Enterprise aguanta el bloqueo de cualquier hook, y lo que decide es la credencial de la sesión. V
Y hubo tres arreglos en que el hook no llegaba a cumplirse. Hasta la 2.1.288, del 2 de octubre, un hook PreToolUse se saltaba cuando fallaba la comparación con la herramienta o cuando sus datos no se podían serializar; ahora, en ese caso, la llamada se bloquea. V Y hasta la 2.1.292, del 6 de octubre, corregido como fallo de seguridad, la aprobación de un hook y el modo automático se saltaban la pregunta de permisos al leer ficheros de rutas de red de Windows, las que empiezan por dos barras. V Y hasta la 2.1.310, del 23 de octubre, en Windows, los hooks PreToolUse y PermissionRequest dejaban pasar la llamada cuando faltaba Git Bash y la orden del hook era solo texto entre comillas, como una ruta entrecomillada. V Lo añadimos el 24 de octubre.
Qué hacer. Actualiza a la 2.1.310 o posterior, y mira qué mods tienes instalados antes de dar por hecho que un hook te protege. Un hook es un freno fuerte, y deja de serlo si has instalado algo que puede soltarlo.
Un hook es un programa que el propio Claude Code ejecuta en momentos fijos de la sesión: antes de usar una herramienta, después, al terminar, al compactar. El que nos interesa es PreToolUse: se ejecuta antes de cada acción y puede impedirla.
Recibe por la entrada estándar un JSON con la herramienta que el agente quiere usar (tool_name: Bash, Read, Edit, Write…) y sus datos (tool_input: el comando o la ruta del fichero). Si el programa termina con el código de salida 2, la acción se bloquea y el motivo que escriba se muestra como razón del bloqueo.
La documentación de Claude Code lo resume así: a diferencia de las instrucciones de CLAUDE.md, que son orientativas, los hooks son deterministas V. Codex, Cursor y Copilot tienen mecanismos equivalentes.
.claude/hooks/proteger.py, que lea el JSON, compruebe la acción contra tus reglas y salga con código 2 si debe bloquearla..claude/settings.json (compartido con el equipo) o en .claude/settings.local.json (solo para ti), bajo hooks → PreToolUse, indicando a qué herramientas afecta:{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Read|Edit|Write|MultiEdit",
"hooks": [
{ "type": "command",
"command": "python3 \"${CLAUDE_PROJECT_DIR}/.claude/hooks/proteger.py\"" }
]
}
]
}
}
El laboratorio de abajo genera los dos ficheros con las reglas que elijas.
Añadido el 11 de octubre de 2026. Un hook que falla no frena nada: en la mayoría de los eventos, si el hook no arranca, agota su tiempo o sale con un código distinto de 0 y de 2, Claude Code ejecuta la acción igualmente. V Desde la versión 2.1.295 se arregla con una línea en su configuración, "onFailure": "block", que hace que un fallo bloquee en vez de dejar pasar. El valor por defecto es "continue". V
Conviene probarlo moviendo el script de sitio a propósito: si la acción se ejecuta, el freno que creías tener no estaba. I
El coste real no es técnico: es de mantenimiento y, sobre todo, de falsa seguridad. Un hook bloquea exactamente lo que describe su regla, ni más ni menos. El laboratorio te enseña lo fácil que es que un comando equivalente se escape.
Hasta dónde llega: un hook bloquea lo que describe su regla. No sustituye a los permisos, al entorno aislado ni a las credenciales de alcance mínimo, y no entiende intenciones.
Marca las que se cumplan en tu caso.
Usa el laboratorio de arriba con tu propio caso.
Las piezas que lo completan.
Si algo no encaja con tu caso, o si encuentras un error, escríbeme: se corrige y se anota.
Escríbeme