Guardrails en Claude Code: coste, rollback y Security beta

TL;DR: si dejas a Claude Code trabajar tareas largas sin guardrails, te arriesgas a tres cosas: gasto descontrolado de tokens, pérdida de trabajo cuando una sesión se rompe y comandos destructivos ejecutados antes de que reacciones. Este artículo cubre tres capas defensivas concretas: budget caps con variables de entorno, hooks en settings.json que cortan acciones de riesgo, y checkpoints automáticos para hacer rollback. Y miramos qué aporta Claude Security en beta pública.

El problema: agentes que ejecutan sin red de seguridad

La conversación en Reddit de las últimas semanas no es teórica. Hay reportes de gente que ha quemado decenas de euros en una sola sesión larga, otros que perdieron trabajo cuando el agente se equivocó al editar varios ficheros y un debate creciente sobre por qué no hay límites de uso por proyecto.

En mi flujo diario, el patrón es claro: cuanto más autónomo dejas al agente, más necesitas instrumentarlo. No es desconfianza, es ingeniería. Los guardrails son la diferencia entre un agente que te ahorra tiempo y un agente que te hace perder una tarde reconstruyendo trabajo.

Hay tres tipos de fallo que merece la pena prevenir explícitamente:

• Coste descontrolado: la sesión sigue iterando y consumiendo tokens en bucles que no aportan.
• Acciones destructivas: rm -rf, git reset --hard, force push a ramas compartidas.
• Pérdida de contexto y trabajo: la sesión se cae, se compacta mal o el agente sobrescribe ficheros sin checkpoint.

¿Qué es un guardrail en un agente de código?

Un guardrail es una restricción configurable que se aplica antes, durante o después de que el agente ejecute una acción. No es prompt engineering ni una buena práctica oral, es código declarativo que el harness ejecuta sí o sí.

En Claude Code, los guardrails viven en cuatro sitios: variables de entorno (presupuesto y modelo), settings.json (permisos y hooks), CLAUDE.md (reglas durables del proyecto) y herramientas externas como Claude Security.

Capa 1: presupuesto de tokens con variables de entorno

La forma más directa de evitar gasto descontrolado es topar la salida por turno. Claude Code respeta varias variables de entorno que actúan como techo duro.

# Limita tokens de salida por respuesta y fija modelo por defecto
export CLAUDE_CODE_MAX_OUTPUT_TOKENS=8000
export ANTHROPIC_MODEL=claude-sonnet-4-6
export DISABLE_AUTOUPDATER=1

Tres notas prácticas. Primera: bajar el cap de output reduce el riesgo de respuestas larguísimas que no aportan, sobre todo en tareas exploratorias. Segunda: fijar Sonnet por defecto y subir a Opus solo cuando lo decides explícitamente con /model recorta coste sin perder calidad en lo que ya es rutina. Tercera: si quieres ver el gasto en vivo, configura una statusline con tokens y coste por sesión.

Para presupuestos por proyecto, el patrón que me funciona es exportar estas variables en un .envrc con direnv y revisarlas al abrir cada repo. Si te interesa entender mejor cómo Claude Code organiza configuración, memoria y mapas de repo, ya cubrí ese flujo en setup de memoria, MCPs y mapa de repo.

Capa 2: hooks en settings.json para cortar comandos peligrosos

Los hooks ejecutan comandos del sistema en respuesta a eventos del agente: antes de un tool call, después, al terminar la sesión. Es la única forma de garantizar comportamiento, porque los ejecuta el harness, no el modelo.

Un ejemplo realista: bloquear cualquier intento de borrar ficheros con rm -rf antes de que se ejecute.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-destructive.sh"
          }
        ]
      }
    ]
  }
}

El script de hook recibe el comando por stdin, lo inspecciona y devuelve código de salida distinto de cero para abortar. Una versión mínima:

#!/usr/bin/env bash
# Bloquea patrones destructivos antes de ejecutarse
input=$(cat)
if echo "$input" | rg -q 'rm -rf|git reset --hard|force-push|--no-verify'; then
  echo "Comando bloqueado por hook de seguridad" >&2
  exit 2
fi
exit 0

El detalle importante: exit 2 hace que Claude Code aborte la ejecución y muestre el mensaje al modelo, así puede reintentar con otro enfoque. Con exit 1 el comportamiento es distinto según versión, conviene revisar la documentación oficial antes de desplegar a un equipo.

Capa 3: checkpoints y rollback de trabajo

Las sesiones largas se rompen. A veces el agente edita ocho ficheros antes de que veas que el segundo estaba mal. Sin checkpoints, recuperar es manual y doloroso.

Hay dos enfoques que se complementan:

Enfoque	Granularidad	Cuándo usarlo
/rewind integrado	Por turno de conversación	Deshacer un cambio reciente sin tocar git
Auto-commit con hook	Por tool call de edición	Sesiones largas, equipos, auditoría

Para auto-commit, un PostToolUse que dispare un git add -A && git commit -m "checkpoint: $(date +%s)" en una rama efímera te da un historial linear de cada paso. Si el agente la lía, git reflog y vuelves al checkpoint anterior. No es elegante, pero funciona.

Una advertencia honesta: hacer commit por cada edición ensucia el historial y solo tiene sentido en una rama de trabajo desechable. La rama final pasa por un squash antes de merge.

Claude Security en beta pública: qué aporta y qué no

Anthropic anunció Claude Security en beta pública. Lo que hace, según su descripción oficial, es escanear tu código, validar sus propios hallazgos y proponer fixes. Suena a SAST con LLM por encima.

Mi lectura, desde un setup de developer individual: es interesante para encontrar vulnerabilidades antes de un release, no sustituye a los guardrails operativos. Detecta SQLi, secrets en el repo o dependencias con CVEs, pero no te impide que el agente haga git push --force a main mientras tú estás comiendo.

La mezcla útil es: Security para el código que el agente escribe, hooks para los comandos que el agente ejecuta, budget caps para el coste del agente. Tres capas, tres preocupaciones distintas.

En Producción

Cuando llevas guardrails a un proyecto compartido, hay diferencias respecto al setup local que conviene anticipar.

Versionado de hooks: los scripts de hook viven fuera del repo si están en ~/.claude/. Para un equipo, mete las reglas en .claude/settings.json dentro del repo y usa settings.local.json para las personales. Así todos heredan las mismas restricciones.

Coste real de los hooks: cada PreToolUse añade latencia. Un hook que tarda 200 ms en ejecutarse, multiplicado por 50 tool calls en una sesión, son 10 segundos perdidos. Mantén los hooks rápidos y delega validaciones pesadas a CI.

Permisos en settings: en lugar de bloquear con hook, considera la lista de permisos. Es más simple y deterministic. Para esto, el principio de separación de responsabilidades aplica igual que en arquitectura: lo que se puede expresar declarativamente, no lo metas en un script.

Coste en euros: con Sonnet por defecto y un cap de 8.000 tokens de output, una sesión de 2 horas trabajando en una feature media ronda los 1-3 €. Sin caps, he visto reports de 15-25 € por sesión cuando el agente entra en bucles. La diferencia es real.

Errores Comunes y Depuración

• Error: el hook nunca se ejecuta. Causa: el matcher no coincide con el nombre exacto de la tool (Bash, no bash). Solución: revisa con claude --debug qué tool se invoca y ajusta el matcher.
• Error: el agente rompe la sesión cuando un hook devuelve exit 2. Causa: stderr del hook no es informativo. Solución: imprime un mensaje claro a stderr explicando el bloqueo, así el modelo puede reintentar con otro enfoque.
• Error: los checkpoints automáticos llenan el repo de commits basura. Causa: el hook hace commit en la rama principal. Solución: detecta la rama actual y solo haz checkpoint si empieza por wip/ o similar.
• Error: CLAUDE_CODE_MAX_OUTPUT_TOKENS no parece aplicarse. Causa: la variable se define en una shell distinta a la que lanza Claude Code. Solución: expórtala en .envrc, .zshrc o el equivalente que cargue tu launcher.

Preguntas Frecuentes

¿Los guardrails ralentizan al agente?

Un poco. Cada hook añade latencia mínima, normalmente bajo 100 ms si el script es eficiente. La diferencia es despreciable comparada con el tiempo que ahorras evitando rollbacks manuales o sesiones a 20 € que no aportan.

¿Hace falta Claude Security si ya tengo SonarQube o Snyk?

No de entrada. Si ya tienes un SAST en CI, Claude Security solapa funcionalidad. Tiene sentido evaluarlo si no tienes nada o si quieres validación dentro del flujo del agente, pero no lo añadas solo porque está en beta.

¿Puedo limitar el gasto por proyecto en lugar de por sesión?

Hoy no de forma nativa. Lo que sí puedes hacer es exportar variables distintas por repo con direnv o un wrapper de shell, y revisar el coste acumulado con la statusline. Para topes duros por proyecto, los modos /effort y Auto Mode ayudan a controlar coste de otra manera.

Cierre

Operar a un agente como Claude Code en serio requiere tratarlo como un servicio en producción: con presupuesto, con monitor y con red de seguridad. Las tres capas que cubrimos no son alternativas, se combinan. Los budget caps protegen tu factura, los hooks protegen tu sistema y los checkpoints protegen tu trabajo. Claude Security añade una cuarta dimensión sobre el código que el agente produce, pero llega después de las tres anteriores.

Si configuras esto una vez y lo versionas en el repo, dejas de pensarlo. Y eso es exactamente lo que quieres: que la seguridad operativa sea aburrida y automática, no algo que recuerdas cuando ya has perdido trabajo.

¿Has tenido un susto con coste o trabajo perdido en Claude Code? Cuéntame qué guardrail añadiste después en @sergiomarquezp_. Próximo tema relacionado: cómo medir el ROI real de un agente de código en un proyecto pequeño.