Repository navigation
Hook tdd guard
Esta página explica o hook tdd_guard.py de forma didática. Se algum termo for novo, consulte o Glossário.
Um hook (gancho automático) é um pequeno programa que dispara sozinho em um momento específico, sem você pedir. Ele aplica regras de qualidade automaticamente. O bigtech traz 6 hooks; este é um deles.
O tdd-guard é um guarda de TDD. Ele impede que você escreva código de produção sem antes ter um teste que falha. Em outras palavras, ele faz cumprir a disciplina do TDD (desenvolvimento guiado por testes; veja o ciclo red, green, refactor no Glossário).
A ideia: em TDD, primeiro você escreve um teste para algo que ainda não existe (ele falha, fica "vermelho"), e só depois escreve o código que faz o teste passar (fica "verde"). O tdd-guard garante essa ordem.
Ele dispara no evento PreToolUse, ou seja, antes de o assistente salvar ou editar um arquivo (ferramentas Write, Edit, MultiEdit). Ele intercepta a escrita antes de ela acontecer e decide se permite ou bloqueia.
Sem disciplina, é comum escrever o código primeiro e os testes depois (ou nunca). Isso deixa passar erros e dificulta a manutenção. O tdd-guard torna a boa prática automática: você só consegue avançar no código de produção se já existir um teste cobrindo o que você vai fazer. O resultado é código mais confiável desde o início.
Quando o assistente tenta salvar um arquivo, o guarda pensa assim, em ordem:
- Se o controle de TDD foi desligado na sessão (variável
TDD_GUARD=off), ele libera sem verificar. - Se o projeto não tem o arquivo de configuração
.claude/tdd-guard.json, ele libera (fica inerte). Sem esse arquivo, o hook não atua em projeto nenhum. - Ele olha o tipo do arquivo. Se for um arquivo de teste, libera sempre: escrever teste nunca é bloqueado.
- Se você avisou que está apenas reorganizando o código (variável
TDD_PHASE=refactor), ele libera. - Para um arquivo de produção, ele consulta o último resultado de testes:
- Se nunca rodou teste, bloqueia e pede para você escrever um teste que falhe primeiro.
- Se há um teste vermelho (falhando), libera: é a hora de escrever o código que faz ele passar.
- Se está tudo verde (nenhum teste falhando), bloqueia e pede um novo teste que falhe, ou o modo refatoração.
Este hook é opt-in (adesão voluntária). Ele só funciona em projetos que têm o arquivo de configuração .claude/tdd-guard.json na raiz. Sem esse arquivo, ele fica completamente parado e nenhum projeto é afetado. Você ativa criando esse arquivo, que diz qual é o comando de teste do projeto.
Caso precise, você pode contornar o guarda:
- Desligar na sessão atual: no terminal, defina
TDD_GUARD=off. O hook fica inerte até o fim da sessão. - Modo refatoração: defina
TDD_PHASE=refactorpara reorganizar código com os testes já verdes, sem precisar de um teste novo. - Isentar arquivos: no arquivo de configuração, liste padrões em
exclude_globs(por exemplo, pastas de protótipos ou scripts) que nunca serão bloqueados.
O guarda foi feito para errar do lado seguro. Se o resultado dos testes não puder ser lido por algum defeito (por exemplo, o programa de teste não está instalado, ou demorou demais), ele libera com aviso em vez de bloquear. Esse comportamento se chama fail-open (veja o Glossário). Assim, um defeito do plugin nunca deixa você preso.
O tdd-guard decide se libera olhando o último resultado de testes. Quem roda os testes e grava esse resultado é o hook companheiro tdd-runner. Os dois trabalham juntos: o runner roda e anota; o guard lê a anotação e decide.
Detalhe técnico: os dois hooks de TDD compartilham um arquivo auxiliar interno chamado
tdd_common.py, que guarda a lógica comum (presets de tecnologia, classificação de arquivos, leitura e escrita do estado). Você não precisa mexer nele.
Veja também o tdd-runner e o agente de qualidade qa-engineer. Voltar para a Home.