GateGuard — Filtro previo a la acción que exige datos concretos

Un gancho de PreToolUse que obliga a Claude a investigar antes de editar. En lugar de una autoevaluación («¿estás seguro?»), exige hechos concretos. El acto de investigar genera una toma de conciencia que la autoevaluación nunca logró.

Cuándo activarlo

• Al trabajar en cualquier código fuente en el que las modificaciones de los archivos afecten a varios módulos
• Proyectos con archivos de datos que tienen esquemas o formatos de fecha específicos
• Equipos en los que el código generado por IA debe ajustarse a patrones existentes
• Cualquier flujo de trabajo en el que Claude tiende a adivinar en lugar de investigar

Concepto fundamental

La autoevaluación de los modelos de lenguaje grande (LLM) no funciona. Si se pregunta «¿has infringido alguna política?», la respuesta es siempre «no». Esto se ha comprobado experimentalmente.

Pero preguntar «enumera todos los archivos que importan este módulo» obliga al LLM a ejecutar Grep y Read. La propia investigación crea un contexto que modifica el resultado.

Barrera de tres etapas:

1. DENY  — block the first Edit/Write/Bash attempt
2. FORCE — tell the model exactly which facts to gather
3. ALLOW — permit retry after facts are presented

Ningún competidor cumple las tres. La mayoría se queda en la negación.

Pruebas

Dos pruebas A/B independientes, agentes idénticos, misma tarea:

Ambos agentes generan código que se ejecuta y supera las pruebas. La diferencia radica en la profundidad del diseño.

Tipos de compuertas

Compuerta de edición / MultiEdit (primera edición por archivo)

La puerta «MultiEdit» se gestiona de forma idéntica: cada archivo del lote se somete a la puerta de forma individual.

Before editing {file_path}, present these facts:

1. List ALL files that import/require this file (use Grep)
2. List the public functions/classes affected by this change
3. If this file reads/writes data files, show field names, structure,
   and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim

Compuerta de escritura (primera creación de un nuevo archivo)

Before creating {file_path}, present these facts:

1. Name the file(s) and line(s) that will call this new file
2. Confirm no existing file serves the same purpose (use Glob)
3. If this file reads/writes data files, show field names, structure,
   and date format (use redacted or synthetic values, not raw production data)
4. Quote the user's current instruction verbatim

Puerta de Bash destructiva (cada comando destructivo)

Se activa en: rm -rf, git reset --hard, git push --force, drop table, etc.

1. List all files/data this command will modify or delete
2. Write a one-line rollback procedure
3. Quote the user's current instruction verbatim

Puerta de Bash de rutina (una vez por sesión)

1. The current user request in one sentence
2. What this specific command verifies or produces

Inicio rápido

Opción A: Utiliza el hook ECC (sin instalación)

El hook que se encuentra en scripts/hooks/gateguard-fact-force.js está incluido en este complemento. Actívalo a través de hooks.json.

Si GateGuard bloquea las tareas de configuración o reparación, inicia la sesión con ECC_GATEGUARD=off. Para controlar a nivel de gancho, sigue utilizando ECC_DISABLED_HOOKS con el ID del gancho «GateGuard».

En sesiones largas, solo las primeras GATEGUARD_FACT_FORCE_FULL_DENIALS denegaciones de «fact-force» (por defecto, 3) emiten el bloque completo de cuatro hechos; las denegaciones posteriores se condensan en una sola línea que contiene el número ordinal de la denegación, de modo que los bloques casi idénticos no puedan acumularse en la ventana de contexto y amplificar los bucles de repetición del modelo (#2142). Volver a intentar el mismo archivo o comando tras presentar hechos nunca vuelve a activar la puerta.

Opción B: Paquete completo con configuración

pip install gateguard-ai
gateguard init

Esto añade .gateguard.yml para la configuración por proyecto (mensajes personalizados, rutas que se deben ignorar, activación/desactivación de la puerta).

Antipatrones

• No utilices la autoevaluación en su lugar. A la pregunta «¿Estás seguro?» siempre se responde «sí». Esto está verificado experimentalmente.
• No te saltes la comprobación del esquema de datos. Ambos agentes de pruebas A/B asumieron fechas según la norma ISO-8601 cuando se utilizaron datos reales %Y/%m/%d %H:%M. Comprobar la estructura de los datos (con valores ocultos) evita toda esta clase de errores.
• No controles cada comando de Bash individualmente. Los controles rutinarios de Bash se realizan una vez por sesión. Los controles destructivos de Bash se realizan en cada ocasión. Este equilibrio evita la ralentización al tiempo que detecta riesgos reales.

Buenas prácticas

• Deja que el filtro se active de forma natural. No intentes responder por adelantado a las preguntas del filtro: la propia investigación es lo que mejora la calidad.
• Personaliza los mensajes de los controles según tu ámbito. Si tu proyecto tiene convenciones específicas, añádelas a las indicaciones de los controles.
• Utiliza .gateguard.yml para ignorar rutas como .venv/, node_modules/, .git/.

Habilidades relacionadas

• safety-guard — Comprobaciones de seguridad en tiempo de ejecución (complementarias, sin solapamientos)
• code-reviewer — Revisión posterior a la edición (la «GateGuard» es una investigación previa a la edición)