Delivery Gate — Portão Mecânico de Qualidade para Claude Code
Um hook de parada 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 de regex no texto do transcript. Sem inferência de IA.
Isso é diferente de portões 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 uma defesa em camadas:
- 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 portões de pipeline de CI — verificações automatizadas e determinísticas que validam 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 < 50 GB | shutil.disk_usage | Aviso |
| Espaço em disco < 15 GB | 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 raciocínio pode ter sido encurtado. Ela nunca bloqueia sozinha, porque heurísticas de 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 com >=3 edições).
Porquê
As verificações nativas do Claude Code cobrem qualidade de código (build → type → lint → test). Mas há um modo de falha diferente: o agente produz código funcional enquanto a higiene da sessão foi negligenciada — aprendizado não capturado, atalhos racionalizados, disco acabando silenciosamente.
Ao longo de muitas sessões de "entregar e esquecer", o humano não cresce. Este hook impõe o hábito: tarefa complexa → deve tocar as bibliotecas de aprendizado.
Instalação
cp quality-gate.py ~/.claude/scripts/
Adicione a ~/.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 diárias de aprendizado (diretório)
├── decisions/log.md # Registro de decisões
├── output-index.md # Índice das saídas da sessão
├── ratings-tracker.md # Avaliações de habilidades ao longo do tempo
└── 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 de regex para detecção de racionalização |
LIBS | 5 bibliotecas | Arquivos/diretórios para verificar atualizações de hoje |
COMPLEX_THRESHOLD | 3 | Chamadas de Editar/Escrever para classificar como complexo |
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 complexo) → exit 0
Tarefa complexa, aprendizado capturado — permitida:
edit_count=5 (complexo) → verifica LIBS → growth-log atualizado hoje → exit 0
Tarefa complexa, sem aprendizado — BLOQUEADA:
edit_count=4 (complexo) → verifica LIBS → todas as 5 desatualizadas → exit 2
stderr: "Bloqueado: tarefa complexa concluída mas nenhum aprendizado capturado hoje."
Espaço em disco baixo — BLOQUEADA:
disk_free=12GB < 15GB crítico → exit 2
stderr: "Bloqueado: espaço em disco em 12GB (limiar: 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 pulado, o hook passa (1 de 5 bibliotecas tocadas). Isso é proposital: portões 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— Portão de qualidade de raciocínio (completude/consistência/ancoragem/honestidade)verification-loop— Verificações de qualidade de código (build/type/lint/test)gateguard— Portão de segurança PreToolUse