GateGuard — Investigación Obligatoria Antes de Editar

Flujo de tres fases

🚫

1. Deny

El primer intento de Edit / Write / Bash destructivo es bloqueado automáticamente antes de ejecutarse.

→

🔍

2. Force

El agente recibe una lista exacta de hechos que debe investigar y presentar: importadores, esquema, instrucción.

→

✅

3. Allow

Una vez presentados los hechos concretos, el retry es permitido. La investigación ya mejoró el output.

Ejemplo real — Ficha de hechos antes de editar analytics/events.py

📋 GATEGUARD FACT SHEET — analytics/events.py Generado por el agente · 2026-06-18 09:41

1

Archivos que importan este módulo (grep result)

analytics/aggregator.py:12 analytics/pipeline/ingest.py:8 analytics/pipeline/transform.py:5 api/routes/events.py:3 api/routes/reports.py:9 workers/celery_tasks.py:17 workers/scheduler.py:22 tests/unit/test_events.py:2 tests/integration/test_pipeline.py:4 scripts/backfill_events.py:1 scripts/export_csv.py:6 ⚠ 11 archivos afectados

2

Funciones/clases públicas afectadas por el cambio

EventRecord (dataclass) parse_event_timestamp(raw_ts) normalize_event_type(event) batch_insert_events(events: list) ⚠ parse_event_timestamp usada en 8 de los 11 importadores

3

Esquema real de los datos (valores sintéticos)


{

  "event_id": "evt_8f4a2c",

  "timestamp": "2026/01/15 09:32",  ← formato %Y/%m/%d %H:%M (NO ISO-8601!)

  "store_id": "shop_001",

  "event_type": "page_view",

  "session_id": "sess_x9k2",

  "value_eur": 0.00

}

⚠ Agente sin gate asumía ISO-8601 → 3 bugs/sprint por esta razón

4

Instrucción exacta del usuario (verbatim)

"Refactoriza parse_event_timestamp para que también acepte timestamps en milisegundos Unix (int), además del formato actual. No rompas compatibilidad con los loaders existentes."

A/B Test — mismo agente, misma tarea, distinto resultado

Tarea	Con GateGuard	Sin GateGuard	Mejora
Módulo de analítica Refactor parse_event_timestamp	8.0	6.5	+1.5 ↑
Validador de webhooks Nuevo endpoint + tests	10.0	7.0	+3.0 ↑
Media	9.0	6.75	+2.25 ↑

Ambos agentes producen código que corre y pasa tests. La diferencia es profundidad de diseño y respeto de convenciones existentes.

Sin gate vs Con gate — comportamiento del agente

❌ Sin GateGuard

Edita events.py directamente sin investigar quién lo importa

Asume formato ISO-8601 por defecto → rompe ingest.py y aggregator.py

Crea archivo nuevo sin verificar si ya existe una función equivalente

Ejecuta git reset --hard sin listar archivos afectados

La autoevaluación "¿estás seguro?" siempre responde "sí" — efecto nulo

3 bugs de formato de fecha por sprint en AnalyticsPro

✅ Con GateGuard

Primer Edit bloqueado → agente investiga con Grep + Read

Descubre los 11 importadores antes de tocar una línea de código

Lee el esquema real: formato %Y/%m/%d %H:%M → lo respeta

Antes de crear archivo verifica con Glob que no existe uno igual

Comando destructivo requiere lista de afectados + rollback de una línea

0 bugs de formato de fecha desde la activación del gate

Tipos de gate configurados

Edit / MultiEdit Gate

Se activa en: primera edición por archivo

Lista TODOS los archivos que importan/requieren este archivo
Lista las funciones/clases públicas afectadas
Si lee/escribe datos, muestra estructura y formato de fechas
Cita la instrucción del usuario textualmente

Write Gate

Se activa en: creación de archivo nuevo

Nombra qué archivo y línea llamará a este nuevo archivo
Confirma que no existe uno con el mismo propósito (Glob)
Si maneja datos, muestra estructura y formato
Cita la instrucción del usuario textualmente

Destructive Bash Gate

Se activa en: rm -rf, git reset --hard, drop table…

Lista archivos/datos que este comando modificará o borrará
Escribe un rollback de una sola línea
Cita la instrucción del usuario textualmente

Routine Bash Gate

Se activa en: primera vez por sesión (sin destrucción)

La petición actual del usuario en una frase
Qué verifica o produce este comando específico

Configuración — hooks.json

        .claude/hooks.json
        JSON
      

// GateGuard PreToolUse hook — investigación obligatoria antes de editar
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node scripts/hooks/gateguard-fact-force.js"
          }
        ]
      }
    ]
  }
}
      

        .gateguard.yml
        YAML
      

# AnalyticsPro — configuración de GateGuard
max_full_denials: 3          # luego condensado para evitar loops de contexto
ignore_paths:
  - .venv/
  - node_modules/
  - .git/
  - *.lock
gates:
  edit: true
  write: true
  bash_destructive: true
  bash_routine: true
disable_env_var: "ECC_GATEGUARD"  # ECC_GATEGUARD=off para bypass de sesión
      