Delivery Gate — Portão de Qualidade Mecânico para Claude Code
Um Stop hook que verifica três coisas antes que Claude possa finalizar uma sessão, usando apenas verificações determinísticas — timestamps de modificação de arquivos, uso de disco e padrões regex no texto do transcript. Sem inferência de IA.
Isto é diferente de gates de raciocínio (como self-audit): delivery-gate verifica fatos verificáveis por máquina; self-audit verifica a qualidade da saída em quatro dimensões de raciocínio. Juntos, formam defesa em profundidade:
- delivery-gate: "A biblioteca de aprendizado foi tocada hoje? O espaço em disco está seguro?"
- self-audit: "O conteúdo do arquivo está correto, completo e honesto?"
Este é o mesmo padrão de gates de pipeline de CI — verificações automatizadas e determinísticas que confirmam fatos legíveis por máquina, em vez de confiar em status auto-relatados.
O Que Ele Verifica
| Verificação | Mecanismo | Ao Acionar |
|---|---|---|
| Padrões de racionalização | Regex na cauda do transcript | Apenas aviso (nunca bloqueia) |
| Bibliotecas de aprendizado desatualizadas | mtime em 5 caminhos configuráveis | Aviso se algumas desatualizadas; Bloqueio se >=3 desatualizadas OU growth-log desatualizado + tarefa complexa |
| Espaço em disco < 50GB | shutil.disk_usage | Aviso |
| Espaço em disco < 15GB | shutil.disk_usage | Bloqueio (exit 2) |
A detecção de racionalização alerta sobre padrões como "pular testes por enquanto" e "bug pré-existente" — sinais superficiais de que o pensamento pode ter sido interrompido. Ela nunca bloqueia sozinha, pois heurísticas regex podem gerar falsos positivos. As condições de bloqueio são: disco crítico, >=3 bibliotecas de aprendizado desatualizadas, OU growth-log especificamente desatualizado (ambos exigem tarefa complexa >=3 edições).
Por Quê
As verificações embutidas do Claude Code cobrem qualidade de código (build → tipo → lint → teste). Mas existe um modo de falha diferente: o agente produz código funcional enquanto a higiene da sessão foi negligenciada — aprendizado não registrado, atalhos racionalizados, disco ficando sem espaço silenciosamente.
Ao longo de muitas sessões de "entrega e esquece", o humano não cresceu. Este hook impõe o hábito: tarefa complexa → deve tocar as bibliotecas de aprendizado.
Instalação
cp quality-gate.py ~/.claude/scripts/
Adicione em ~/.claude/settings.json:
{
"hooks": {
"Stop": [{
"hooks": [{
"type": "command",
"command": "python3 ~/.claude/scripts/quality-gate.py",
"timeout": 5000
}]
}]
}
}
Bibliotecas de Aprendizado
Crie estes arquivos no diretório de memória do seu projeto. O hook verifica se pelo menos um foi atualizado hoje:
memory/
├── growth-log/ # Entradas de aprendizado diárias (diretório)
├── decisions/log.md # Registro de decisões
├── output-index.md # Índice de saídas da sessão
├── ratings-tracker.md # Acompanhamento de avaliações de habilidades
└── tooling_capabilities.md # Inventário de ferramentas conhecidas
Personalize o dicionário LIBS para corresponder à sua própria estrutura de arquivos.
Configuração
Edite quality-gate.py:
| Variável | Padrão | Propósito |
|---|---|---|
RATIONALIZE | 4 padrões | Padrões regex para detecção de racionalização |
LIBS | 5 bibliotecas | Arquivos/diretórios para verificar atualizações de hoje |
COMPLEX_THRESHOLD | 3 | Chamadas Editar/Escrever para classificar como complexa |
DISK_WARN_GB | 50 | Avisar abaixo disto |
DISK_CRIT_GB | 15 | Bloquear abaixo disto |
Exemplos
Sessão simples — permitida:
edit_count=1 (< 3, não complexa) → exit 0
Tarefa complexa, aprendizado registrado — permitida:
edit_count=5 (complexa) → verifica LIBS → growth-log atualizado hoje → exit 0
Tarefa complexa, sem aprendizado — BLOQUEADA:
edit_count=4 (complexa) → verifica LIBS → todas as 5 desatualizadas → exit 2
stderr: "Blocked: tarefa complexa concluída mas nenhum aprendizado foi registrado hoje."
Espaço em disco baixo — BLOQUEADO:
disk_free=12GB < 15GB crítico → exit 2
stderr: "Blocked: espaço em disco em 12GB (limite: 15GB)."
Limitações
O hook impõe o hábito de tocar as bibliotecas de aprendizado, não a qualidade do que foi registrado. Se output-index.md for atualizado mas growth-log for ignorado, o hook passa (1 de 5 bibliotecas tocadas). Isso é proposital: gates mecânicos verificam fatos verificáveis por máquina. Para verificação de qualidade de conteúdo, combine com self-audit.
Compatibilidade
- Python 3.8+ (usa
from __future__ import annotations) - Multiplataforma: Windows, macOS, Linux
- Zero dependências além da stdlib
Qualidade
Este código passou por 4 rodadas de revisão automatizada de código (CodeRabbit + Greptile) com 9 bugs reais encontrados e corrigidos.
Veja Também
self-audit— Gate de qualidade de raciocínio (completude/consistência/fundamentação/honestidade)verification-loop— Verificações de qualidade de código (build/type/lint/test)gateguard— Gate de segurança PreToolUse