GateGuard — Gate de Pré-Ação para Forçar Fatos

Um hook PreToolUse que força o Claude a investigar antes de editar. Em vez de autoavaliação ("tem certeza?"), ele exige fatos concretos. O ato de investigar cria uma consciência que a autoavaliação nunca proporcionou.

Quando Ativar

• Trabalhando em qualquer base de código onde edições de arquivos afetam múltiplos módulos
• Projetos com arquivos de dados que possuem esquemas ou formatos de data específicos
• Equipes onde o código gerado por IA deve corresponder a padrões existentes
• Qualquer fluxo de trabalho onde o Claude tende a adivinhar em vez de investigar

Conceito Central

A autoavaliação de LLMs não funciona. Pergunte "você violou alguma política?" e a resposta é sempre "não". Isso é verificado experimentalmente.

Mas perguntar "liste todos os arquivos que importam este módulo" força o LLM a executar Grep e Read. A própria investigação cria um contexto que altera a saída.

Gate de três estágios:

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

Nenhum concorrente faz os três. A maioria para na negação.

Evidências

Dois testes A/B independentes, agentes idênticos, mesma tarefa:

Ambos os agentes produzem código que executa e passa nos testes. A diferença é a profundidade do design.

Tipos de Gate

Gate de Edição / MultiEdição (primeira edição por arquivo)

MultiEdição é tratada de forma idêntica — cada arquivo no lote é "gated" individualmente; entradas sem seu próprio file_path são "gated" como a file_path da chamada. NotebookEdit é "gated" como uma Edição de seu notebook_path: mesma classe, regras de chave, crédito e limite verificadas, as perguntas completas (a alteração da célula não é lida), e nunca uma aprovação apenas de comentário.

As perguntas dependem da classe do alvo (veja Perguntas por classe de alvo). Para alvos de código, o gate de Edição pergunta:

Before editing {file_path}, present these facts:

1. List ALL files that import/require this file (search the tree — Glob/Grep, or find/grep via Bash)
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

Esses quatro são o conjunto completo, perguntados sempre que a alteração não pode ser lida com confiança. Quando pode (veja Perguntas se encaixam na alteração), uma edição que não toca em nenhuma declaração pública pede em vez disso os pontos de chamada no arquivo ou seu módulo que dependem do comportamento alterado, e o item 3 é descartado quando a alteração não lida com nenhum dado.

Gate de Escrita (primeira criação de novo arquivo)

Para alvos de código, o gate de Escrita pergunta:

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 (search the tree — Glob/Grep, or find/grep via Bash)
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

O item 3 é descartado quando o novo conteúdo não lida com nenhum dado.

Perguntas se encaixam na alteração

Para alvos de código, o gate lê a alteração que está prestes a permitir (Edição old_string/new_string, cada entrada de MultiEdição para o arquivo, Escrita content) e decide três coisas:

• Superfície pública: uma linha em um dos lados declara ou expõe um nome público. JS/TS: export, exports, public, declare (arquivos .d.ts sempre); Python: def/class que não começam com _, dunders, __all__, uma atribuição pública em nível de módulo como BASE_URL = ... (__init__.py sempre); Go: nomes func/type/var/const capitalizados, package, linhas começando com maiúscula; Rust: pub, impl, trait, extern, #[macro_export], #[derive], #[repr], #[no_mangle]; shell: definições de função, export, declare -x; PowerShell: function, filter, param, Export-ModuleMember, [CmdletBinding. Um membro de um contêiner exportado também conta, julgado a partir do arquivo: linhas dentro de uma interface exportada, enum, tipo, objeto ou lista de exportação, declarações de membros de uma classe exportada, entradas __all__, atributos de classe pública e campos de dataclass, e membros

…