Guías prácticas para trabajar con agentes de IA, con un laboratorio al final de cada una
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.
5 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ó, salvo que ese hook esté en la configuración gestionada. V Con configuración gestionada, o con plan Team o Enterprise, las reglas deny sí mandan sobre el mod. En cualquier otro sitio —que es el caso de quien trabaja con Pro o Max en su propio ordenador— el mod puede aprobar incluso lo que una regla deny rechaza. V
Y hubo dos versiones 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
Qué hacer. Actualiza a la 2.1.292 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