GateGuard — Étape préalable à l'action imposant la vérification des faits

Un hook PreToolUse qui oblige Claude à mener une enquête avant toute modification. Au lieu d’une auto-évaluation (« Êtes-vous sûr ? »), il exige des faits concrets. Le fait de mener cette enquête crée une prise de conscience que l’auto-évaluation n’a jamais pu susciter.

Quand l’activer

• Lorsque vous travaillez sur une base de code où les modifications de fichiers affectent plusieurs modules
• Projets comportant des fichiers de données dotés de schémas ou de formats de date spécifiques
• Équipes où le code généré par l’IA doit respecter des modèles existants
• Tout workflow dans lequel Claude a tendance à deviner plutôt qu’à vérifier

Concept fondamental

L’auto-évaluation des LLM ne fonctionne pas. Si l’on demande « As-tu enfreint une quelconque politique ? », la réponse est toujours « non ». Cela a été vérifié expérimentalement.

Mais demander « liste tous les fichiers qui importent ce module » oblige le LLM à exécuter Grep et Read. L'analyse elle-même crée un contexte qui modifie le résultat.

Un processus en trois étapes :

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

Aucun concurrent ne les met toutes en œuvre. La plupart s’arrêtent à la dénégation.

Preuves

Deux tests A/B indépendants, des agents identiques, la même tâche :

Les deux agents produisent du code qui s'exécute et passe les tests. La différence réside dans la profondeur de conception.

Types de portes

Porte Edit / MultiEdit (première modification par fichier)

Le traitement « MultiEdit » est identique : chaque fichier du lot est soumis à une porte individuellement.

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

Porte d’écriture (première création d’un nouveau fichier)

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

Porte « Bash destructive » (chaque commande destructive)

Déclencheurs : 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

Barrière Bash de routine (une fois par session)

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

Démarrage rapide

Option A : Utiliser le hook ECC (sans installation)

Le hook situé à l'adresse scripts/hooks/gateguard-fact-force.js est inclus dans ce plugin. Activez-le via hooks.json.

Si GateGuard bloque la configuration ou la réparation, démarrez la session avec ECC_GATEGUARD=off. Pour un contrôle au niveau du hook, continuez à utiliser ECC_DISABLED_HOOKS avec l’ID du hook « GateGuard ».

Au cours de longues sessions, seuls les premiers GATEGUARD_FACT_FORCE_FULL_DENIALS refus de « fact-force » (3 par défaut) génèrent le bloc complet à quatre faits ; les refus suivants sont condensés en une seule ligne indiquant le numéro d'ordre du refus, afin que des blocs quasi-identiques ne puissent pas s'accumuler dans la fenêtre de contexte et amplifier les boucles de répétition du modèle (#2142). Une nouvelle tentative sur le même fichier ou la même commande après la présentation des faits ne redéclenche jamais la porte.

Option B : Package complet avec configuration

pip install gateguard-ai
gateguard init

Cela ajoute .gateguard.yml permettant une configuration par projet (messages personnalisés, chemins à ignorer, activation/désactivation de la barrière).

Anti-modèles

• N’utilisez pas l’auto-évaluation à la place. À la question « Êtes-vous sûr ? », la réponse est toujours « oui ». Cela a été vérifié expérimentalement.
• Ne négligez pas la vérification du schéma de données. Les deux agents de test A/B ont supposé que les dates étaient au format ISO-8601 alors que les données réelles utilisées %Y/%m/%d %H:%M. La vérification de la structure des données (avec des valeurs masquées) permet d’éviter toute cette catégorie de bogues.
• N’appliquez pas de contrôle d’accès à chaque commande Bash. Les commandes Bash de routine sont contrôlées une fois par session. Les commandes Bash destructrices sont contrôlées à chaque exécution. Cet équilibre évite les ralentissements tout en détectant les risques réels.

Bonnes pratiques

• Laissez le contrôle s’enclencher naturellement. N’essayez pas de répondre à l’avance aux questions du contrôle — c’est l’analyse elle-même qui améliore la qualité.
• Personnalisez les messages de contrôle en fonction de votre domaine. Si votre projet suit des conventions spécifiques, ajoutez-les aux invites de contrôle.
• Utilisez .gateguard.yml pour ignorer les chemins tels que .venv/, node_modules/, .git/.

Compétences associées

• safety-guard — Vérifications de sécurité à l’exécution (complémentaires, sans chevauchement)
• code-reviewer — Révision post-édition (la « GateGuard » correspond à une analyse pré-édition)