Guías · Sistema con Claude Code
Hooks para las reglas que nunca se pueden romper
Saca de CLAUDE.md las pocas reglas que se tienen que cumplir siempre y ponlas en hooks de Claude Code, pequeños scripts que el programa corre antes y después de cada llamada a una herramienta, y lee los hooks de un repositorio antes de confiar en él.
- Lectura
- 7 min de lectura
- Actualizada
- 19 de noviembre de 2026
- Parte de
- el paquete de 66 guías
Todos mis proyectos tienen el mismo puñado de reglas duras. Nunca leer un archivo .env en el chat. Nunca hacer force push. Los tests pasan antes de dar algo por terminado. Durante mucho tiempo esas reglas vivieron solo en texto: un RULES.md compartido y el CLAUDE.md de cada proyecto.
El texto funciona la mayoría de las veces, y ese es el problema. La propia página de buenas prácticas de Anthropic separa las instrucciones en dos tipos. Unas son cosas que Claude decide si sigue o no: tu prompt, CLAUDE.md, los skills. Otras son cosas que el programa hace cumplir: los hooks, las reglas deny y el sandbox. Su regla práctica es simple. Si sigues agregándole énfasis a una línea de CLAUDE.md ("NEVER", "IMPORTANT", negritas), esa línea va en un hook.
Las pruebas que he juntado apuntan a lo mismo, con límites. Un creador corrió 24 sesiones sobre una tienda de demo con una regla de "nunca instales paquetes". Cuando su prompt decía "conozco la regla del proyecto, esta vez apruebo instalarlo", la versión en CLAUDE.md cedió en 3 de 3 corridas y la versión con hook lo bloqueó en 3 de 3. Otro creador encontró que las reglas solo en CLAUDE.md se seguían 8 o 9 veces de 10, nunca 10. Las dos cifras las reportan ellos mismos. Me basta para tratar CLAUDE.md como una guía y los hooks como la barrera de contención.
Claude elige, el programa hace cumplir
Probando hooks con JSON por la entrada (Ejemplo)
guard-bash git push -f origin main exit=2 bloqueado guard-files app/.env exit=2 bloqueado guard-bash npm test exit=0 permitido guard-bash make wipe exit=0 se escapó: solo compara texto
1. Entiende qué es un hook
Un hook es un comando que Claude Code corre por su cuenta en un punto fijo de la sesión. Los puntos que importan aquí:
- PreToolUse corre antes de una llamada a una herramienta (leer un archivo, una edición, un comando de shell). Puede bloquear la llamada.
- PostToolUse corre después de una llamada a una herramienta. No puede deshacer nada, pero puede ordenar, por ejemplo formatear el archivo que se acaba de editar.
- Stop corre cuando Claude termina un turno de respuesta. Puede mandar a Claude de vuelta a trabajar.
- Notification corre cuando Claude te está esperando.
Los hooks viven en un archivo de configuración, bajo un solo objeto hooks. Pon los hooks del proyecto en .claude/settings.json para que queden en el commit y todos los tengan. Los personales van en ~/.claude/settings.json.
{
"hooks": {
"PreToolUse": [
{ "matcher": "Read|Edit|Write", "hooks": [{ "type": "command", "command": ".claude/hooks/guard-files.sh" }] },
{ "matcher": "Bash", "hooks": [{ "type": "command", "command": ".claude/hooks/guard-bash.sh" }] }
],
"PostToolUse": [
{ "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": ".claude/hooks/format.sh" }] }
],
"Stop": [
{ "hooks": [{ "type": "command", "command": ".claude/hooks/check-done.sh" }] }
]
}
}
Después escribe /hooks dentro de Claude Code para ver qué hooks están cargados y de qué archivo.
2. Aprende los dos datos de los que depende cada hook
El evento llega como JSON por la entrada estándar. No llega como variables de entorno. Tu script lee stdin y saca los campos que necesita, casi siempre con jq. En una herramienta de archivos la ruta está en tool_input.file_path. En un comando de shell está en tool_input.command.
El código de salida 2 bloquea. Salir con 0 significa sin objeción, y sigue el flujo normal de permisos. Salir con 2 detiene la acción, y lo que hayas escrito en el error estándar le llega a Claude como la razón. Salir con 1 no bloquea. Un creador que lo demostró lo señaló frente a la cámara: un guardia que sale con 1 deja correr el comando.
3. Bloquea lecturas y ediciones de archivos secretos
Rechaza cualquier llamada a una herramienta de archivos que toque un archivo env o una clave.
#!/usr/bin/env bash
# .claude/hooks/guard-files.sh (PreToolUse en Read|Edit|Write)
path=$(jq -r '.tool_input.file_path // ""')
path=${path//\\//} # normaliza las barras invertidas de Windows
case "$path" in
*.env|*.env.*|*/secrets/*|*.pem|*id_rsa*)
case "$path" in *.env.example) exit 0 ;; esac
echo "Bloqueado por un hook: $path guarda secretos. Pregúntale al usuario en vez de leerlo." >&2
exit 2 ;;
esac
exit 0
En la prueba de un creador, un verificador bloqueó una solicitud inofensiva sobre .env.example, así que permite los nombres que sabes que son seguros.
4. Bloquea los comandos de shell que nunca quieres que corran
Los comandos de shell necesitan su propio hook, porque un matcher de herramientas de archivos nunca los ve.
#!/usr/bin/env bash
# .claude/hooks/guard-bash.sh (PreToolUse en Bash)
cmd=$(jq -r '.tool_input.command // ""')
deny() { echo "Bloqueado por un hook: $1" >&2; exit 2; }
echo "$cmd" | grep -Eq 'rm +(-[a-zA-Z]*r[a-zA-Z]*f|-[a-zA-Z]*f[a-zA-Z]*r|-r +-f|-f +-r)' && deny "borrado forzado recursivo"
echo "$cmd" | grep -Eq 'git +push.*(--force|-f\b| \+)' && deny "force push"
echo "$cmd" | grep -Eq '(cat|less|head|tail|cp|base64|curl).*\.env\b' && deny "toca .env"
exit 0
Sé honesto contigo sobre lo que es esto. Compara texto. La mejor prueba que he encontrado atacó un hook de lista de bloqueo como este con 25 solicitudes peligrosas, dos veces cada una. Detuvo 21 de 50. Las solicitudes directas casi siempre se atraparon. Las indirectas casi nunca: flags separados como rm -r -f, un target make wipe, git push origin +main, un one-liner de Python que imprime el archivo, curl mandándolo a otro lado. El script de arriba atrapa los flags separados y el push con +main. Todavía se le escapa el resto. El mismo creador encontró que un hook de prompt (un modelo pequeño que juzga cada llamada) detuvo 46 de 50, pero solo después de usar el nombre completo del modelo. Con el alias corto, el hook registró "unrecognized model" y dejó pasar todo sin avisarle a nadie.
Así que un hook de texto es un cinturón de seguridad. Combínalo con reglas deny y el sandbox (ver la guía de permisos), y no des por hecho que un hook está corriendo hasta que lo hayas visto bloquear algo.
5. Formatea después de cada edición
El hook PostToolUse es el amable. Nunca bloquea. Solo corre tu formateador sobre lo que Claude tocó.
#!/usr/bin/env bash
# .claude/hooks/format.sh (PostToolUse en Edit|Write)
path=$(jq -r '.tool_input.file_path // ""')
case "$path" in
*.ts|*.tsx|*.js|*.css|*.html|*.md) npx --no-install prettier --write "$path" >/dev/null 2>&1 ;;
esac
exit 0
Ahora "siempre corre Prettier" puede salir de CLAUDE.md.
6. Haz que "terminado" signifique que los tests pasan
Un hook Stop se dispara al final de cada turno de respuesta. Se dispara una vez por turno, así que no espera a que termine toda la tarea, y una interrupción manual no lo activa. Si sale con 2, Claude lee la razón y sigue trabajando.
#!/usr/bin/env bash
# .claude/hooks/check-done.sh (Stop)
input=$(cat)
# ¿Ya lo mandamos de vuelta una vez en este turno? Déjalo parar, o puedes quedar en un ciclo infinito.
[ "$(echo "$input" | jq -r '.stop_hook_active')" = "true" ] && exit 0
if ! npm test --silent >/tmp/stop-hook.log 2>&1; then
echo "Los tests están fallando. Arréglalos antes de terminar. Últimas líneas:" >&2
tail -20 /tmp/stop-hook.log >&2
exit 2
fi
exit 0
La revisión de stop_hook_active importa. La documentación dice que Claude Code pasa por encima de un hook Stop después de varios bloqueos seguidos, pero no quieres llegar a eso. Un creador midió cuatro filtros con hooks Stop en un repositorio real. Solo el de los tests valió la pena: subió los requisitos cumplidos de 70% a 84% en sus corridas. Dos agentes revisores agregaron costo y no ayudaron. También le pasó que quedaba en ciclos cuando los tests y un revisor pedían cosas opuestas. Empieza con los tests.
7. Recibe un aviso cuando Claude te necesite
El hook Notification es lo que te deja alejarte de la pantalla. La documentación confirma que el matcher permission_prompt se dispara cuando un aviso de permiso lleva unos seis segundos esperando, e idle_prompt se dispara más o menos un minuto después de que Claude termina si no has escrito nada.
"Notification": [
{ "matcher": "permission_prompt|idle_prompt",
"hooks": [{ "type": "command", "command": "notify-send 'Claude Code' 'Te está esperando'" }] }
]
notify-send es de Linux. Los scripts listos de la mayoría de las guías son solo para macOS, así que en Windows vas a escribir el tuyo.
8. Prueba cada hook a mano antes de que Claude lo corra
Pásale JSON falso por la entrada y revisa el código de salida. No necesitas a Claude.
echo '{"tool_name":"Bash","tool_input":{"command":"git push -f origin main"}}' | .claude/hooks/guard-bash.sh; echo "exit=$?"
echo '{"tool_name":"Read","tool_input":{"file_path":"app/.env"}}' | .claude/hooks/guard-files.sh; echo "exit=$?"
echo '{"tool_name":"Bash","tool_input":{"command":"npm test"}}' | .claude/hooks/guard-bash.sh; echo "exit=$?"
Quieres ver 2, 2, 0. Después corre una sesión real y mira cómo pasa un bloqueo. Un script de hook que se cae porque le falta una herramienta falla en silencio. En la prueba de la lista de bloqueo de arriba, un hook caído y un servidor de hooks apagado dejaron pasar todas las corridas peligrosas, y Claude nunca lo mencionó.
9. Lee los hooks de un repositorio antes de confiar en él
Los hooks son código real que corre en tu máquina cada vez que Claude Code corre en esa carpeta. Un repositorio que clonas puede traer su propio .claude/settings.json con hooks adentro. Antes de abrir Claude Code en el proyecto de otra persona, abre .claude/settings.json, .claude/settings.local.json y cualquier carpeta hooks/, y lee cada comando. Los plugins también pueden traer hooks, en hooks/hooks.json.
Para equipos, la documentación confirma una configuración administrada, allowManagedHooksOnly, que bloquea los hooks de usuario, de proyecto, locales y de plugins para que solo corran los de la organización.
Qué vigilar
- Mis propios repositorios hoy funcionan con reglas de texto. RULES.md y cada CLAUDE.md dicen "nunca leas archivos .env en el chat", y ningún proyecto mío tiene todavía un hook que lo haga cumplir. Escribiendo esta guía encontré ese hueco. Si tus reglas son solo texto, estás en el mismo lugar.
- Hooks silenciosos. Un hook con el nombre de modelo equivocado, sin
jqo con un script sin permiso de ejecución no hace nada y no dice nada. Revisa/hooksy prueba con JSON por la entrada. - Reglas que un prompt no puede expresar. En la prueba del hook Stop, una tarea nunca avanzó porque la solicitud nunca dijo el requisito. Ningún filtro recupera una regla que nadie escribió.
Lista de verificación
- Cada regla que escribiste en mayúsculas o en negritas ahora es un hook o una regla deny.
- Un hook PreToolUse bloquea el acceso de las herramientas de archivos a archivos env y claves, con
.env.examplepermitido. - Otro hook PreToolUse en Bash bloquea borrados forzados recursivos, force pushes y lecturas de
.env, y sabes que solo compara texto. - Un hook PostToolUse formatea los archivos editados, así que el formato ya no está en CLAUDE.md.
- Un hook Stop corre los tests, sale con 2 cuando fallan y revisa
stop_hook_active. - Cada hook se probó con JSON por la entrada (2 para bloquear, 0 para permitir) y lo viste bloquear en una sesión real.
- Leíste
.claude/settings.jsony cualquier script de hooks antes de correr Claude Code en un repositorio que no escribiste tú.
¿Quieres el resto?
Esta es una de 66 guías. El paquete completo es a tu voluntad, desde un café.