TDD com Codex: faça a IA escrever o teste primeiro e depois chegar ao verde

Você vê o Codex escrever “todos os testes passaram” no terminal. Mas, olhando com calma, ele só colou a conclusão. Não mostrou o comando, nem disse quais testes rodou. Você abre o diff e percebe que o arquivo de teste também mudou: a assertion saiu de toEqual(42) para toBeTruthy(). O problema não é desconfiar do Codex. O problema é confiar em um “verde” sem evidência. Este guia traz um modelo operacional reutilizável, uma checklist de validação e guardrails contra falsos verdes para trocar “confiar na IA” por “verificar evidência reproduzível”.

Por que test-first importa mais com Codex

Test-first não é só “escrever teste antes do código”. Com Codex, os testes viram critérios de aceitação executáveis pela máquina. O Codex consegue rodar comandos, ler saídas e editar arquivos, mas o critério de “pronto” precisa estar claro antes.

A documentação oficial do OpenAI Codex diz que o Codex tende a produzir melhor quando consegue verificar o trabalho. Isso significa que, se você disser como validar, qual comando rodar e que resultado espera, a chance de ele fazer a mudança correta aumenta. Tarefas vagas tendem a receber respostas vagas. Tarefas menores são mais fáceis de testar e revisar.

O ciclo red-green-refactor tem três fases:

Essas três etapas não devem ser puladas. Se você pula o red, não sabe se o teste realmente valida o novo comportamento. Se pula o refactor, é fácil deixar código remendado. Para o básico de Codex, veja o guia completo para começar com Codex.

Red Phase: fazer o Codex escrever um teste que possa falhar

A Red phase gira em torno de uma restrição: modificar apenas arquivos de teste, sem escrever implementação. Faça o Codex listar os casos primeiro, gerar um por vez e, no fim, rodar os testes para confirmar o vermelho.

Modelo de prompt

Modifique apenas arquivos de teste. Não modifique o código de implementação.
Escreva testes para [nome da funcionalidade] cobrindo:
1. [comportamento mínimo]
2. [caso de borda]
3. [caminho de erro]
Ao terminar, rode `npm test` e cole o nome do teste que falhou e a assertion.

Esse prompt precisa incluir “Não modifique o código de implementação”. Sem essa frase, o Codex pode escrever o teste e implementar o comportamento ao mesmo tempo, quebrando a verificação vermelha.

Confirmar o vermelho

Quando o Codex terminar, peça a saída completa dos testes. O vermelho precisa falhar na assertion esperada, não em erro de compilação ou importação. Se você vir isto:

FAIL src/utils/calculator.test.ts > add > should handle negative numbers
AssertionError: expected -1 to be 42

o teste está verificando o comportamento com números negativos e falhando no lugar certo. Se aparecer apenas TypeError: Cannot find module 'calculator', isso é erro de compilação, não uma falha útil de teste.

Ordenar a lista de testes

Não peça ao Codex para gerar dezenas de testes de uma vez. Comece pelo comportamento mínimo, casos de borda, bugs de regressão e caminhos de erro. Avance caso por caso. A lista pode ficar em AGENTS.md ou em um documento separado, para o Codex seguir em ordem.

🔥 Não perca meses em produtos sem demanda! Valide as propostas do seu SaaS com a Adsterra e pouco orçamento →

Testar agora →Anúncio

Para fundamentos de teste unitário, veja Vitest, testes unitários e TDD e o guia prático de Vitest.

Green Phase: menor implementação até chegar ao verde

O guardrail duro da Green phase é simples: arquivos de teste não são tocados. Se o teste falhar, o Codex só pode mudar a implementação. Ele não pode adaptar o teste ao código existente.

Modelo de prompt

Modifique apenas arquivos de implementação. Não modifique arquivos de teste.
Faça a menor mudança necessária para os testes passarem.
Ao terminar, rode `npm test` e cole o resumo dos testes aprovados.

Esse prompt precisa incluir “Não modifique arquivos de teste”. Sem essa frase, o Codex pode alterar assertions, apagar testes ou pular casos para fazer o resultado parecer verde.

Verificar o resumo e o diff

Depois do trabalho do Codex, peça quantidade de testes, testes aprovados e duração:

PASS src/utils/calculator.test.ts (1.2s)
  add
    ✓ should add two numbers (5ms)
    ✓ should handle negative numbers (3ms)
  2 tests passed

Depois revise o diff. Se um arquivo de teste aparecer na lista de mudanças, rejeite essa Green phase.

Guardrails contra falsos verdes

Falso verde é o maior risco do TDD. Fique atento a estes seis sinais:

O Codex não aplica esses guardrails por você. Eles precisam ser verificados na review. Equipes mais automatizadas podem mover parte disso para CI ou para um pre-commit hook.

Refactor Phase: limpar só depois do verde

A Refactor phase só começa depois do verde. Se os testes não passam, não refatore. Depois do refactor, os testes devem rodar novamente; não confie apenas no diff.

Modelo de prompt

Todos os testes estão passando. Agora faça apenas refatoração:
- Renomear variáveis para deixar a intenção mais clara
- Remover código duplicado
- Extrair funções
Não modifique arquivos de teste. Depois rode `npm test` de novo.

Nesta fase, o Codex muda estrutura, não comportamento. Se o refactor introduzir lógica nova, não é mais refactor: é uma nova Green phase para um novo comportamento.

Rodar testes novamente

Depois do refactor, o Codex precisa executar o mesmo conjunto de testes outra vez. Se eles continuarem verdes, o refactor não quebrou o comportamento existente. Se algum teste falhar, o refactor alterou comportamento e precisa ser revertido ou corrigido.

Revise também o diff: arquivos de teste não devem aparecer na lista de mudanças. Se aparecerem, o refactor passou do limite.

Para um exemplo de refatoração, veja Refatoração com IA e rede de segurança de testes.

Pacote de evidências: fazer o Codex entregar provas revisáveis

Antes de encerrar cada fase, o Codex precisa entregar estas evidências:

Checklist de aceitação antes de concluir

• Comando de teste e exit code
• Resumo de falha ou aprovação
• Lista de arquivos modificados
• Se arquivos de teste foram modificados
• CI status checks, se existirem

Modelo de resposta final

Peça ao Codex para responder neste formato:

### Resultado dos testes
- Comando: `npm test`
- Exit code: 0
- Aprovados: 42 testes
- Falhas: 0
- Duração: 1.2s

### Arquivos modificados
- src/utils/calculator.ts
- (arquivos de teste não foram modificados)

### Risco restante
- Caso de borda não coberto: entrada negativa

Esse formato deixa a evidência legível, comparável e fácil de arquivar. Se o Codex só responder “os testes passaram”, você não sabe se ele realmente executou os testes, se alterou arquivos de teste ou se deixou um caso de borda de fora.

KiloClaw - OpenClaw gerenciado para empresas: orquestração de agentes IA e roteamento inteligente

Começar →Anúncio

Escolha da camada de teste e exemplos de comando

Cada camada de teste verifica um tipo de risco. Não comece sempre por E2E completo, e não dependa apenas de snapshot tests.

Tabela de decisão de camadas de teste

Esses comandos são exemplos: substitua pelos comandos reais do seu projeto. Cada stack pode usar Jest, Vitest, Pytest, Playwright ou GitHub Actions. Para mais contexto, veja o guia de testes Jest com Next.js.

Testes unitários costumam ser a primeira camada de verificação para Codex. Eles rodam rápido, mostram falhas claras e são fáceis de documentar em AGENTS.md. Testes de integração e E2E funcionam melhor para interações entre módulos e fluxos de usuário, mas são mais difíceis de diagnosticar. Typecheck e lint complementam a validação, capturando erros de compilação e estilo. CI é o último gate da equipe: mesmo que tudo passe em local, os CI status checks precisam passar antes do merge.

Fixar regras em AGENTS.md e prompts

Escreva as regras de TDD em AGENTS.md para que o Codex leia antes de cada tarefa. Assim você não repete o mesmo prompt toda vez.

Pequeno exemplo de AGENTS.md

Coloque algo assim na raiz do projeto ou em um diretório local:

## Test commands
- Run tests: `npm test`
- Run unit tests: `npm run test:unit`
- Run typecheck: `npm run typecheck`

## TDD rules
- Red phase: only modify test files
- Green phase: only modify implementation files
- Refactor phase: must re-run tests after cleanup

## Done when
- All tests pass
- Test files are not modified in green/refactor phase
- Diff contains only expected changes

Esse arquivo diz ao Codex quais comandos de teste existem, o que cada fase pode alterar e o que conta como concluído. Para mais detalhes sobre AGENTS.md, veja o artigo da série sobre regras de projeto para Codex.

Diretórios locais podem ter regras mais específicas. Por exemplo, src/utils/AGENTS.md pode listar cenários de teste, casos de borda e bugs conhecidos de src/utils/.

Não coloque secrets, tokens ou configuração sensível em AGENTS.md. O Codex lê esse arquivo, mas não filtra automaticamente informações sensíveis.

Do local para a equipe: gates de CI

Testes verdes em local não significam que a mudança pode ser mergeada. Em equipe existe gate de CI: required status checks precisam passar, e a PR review precisa estar concluída.

Checklist do fluxo

1. Testes locais verdes: Codex conclui as três fases e entrega o pacote de evidências
2. Revisão do diff no review pane: verificar se arquivos de teste foram modificados
3. Criar PR: fazer push para uma feature branch
4. Required status checks precisam passar: CI roda test completo, typecheck e lint
5. Review humana: revisar diff, pacote de evidências e riscos restantes

Testes verdes não significam merge automático

GitHub Docs explica que required status checks precisam passar antes de fazer merge em uma protected branch. Mas há um risco: um job skipped reporta success e não bloqueia o merge do PR, mesmo sendo required check. Ou seja, um PR pode parecer mergeável mesmo que alguns checks não tenham rodado de verdade.

Para evitar falsos verdes por workflows pulados, abra a página GitHub Checks e confirme que todos os required checks realmente executaram, em vez de aparecerem como skipped.

Usar o review pane

O review pane da Codex app permite ver se o diff inclui mudanças em arquivos de teste. Você pode stage, unstage ou revert por arquivo ou hunk. Se um arquivo de teste foi alterado, reverta essa mudança e mantenha apenas a mudança de implementação.

Para mais contexto de CI, veja GitHub Actions CI e fundamentos de workflows no GitHub Actions. O fluxo de PR review aparece no artigo de code review com Codex AI desta série.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Limites para correção automática de falhas de CI

codex exec e Codex GitHub Action podem ajudar com testes de CI falhando, mas precisam de limites de segurança.

Fluxo de correção automática de falhas

Segundo a documentação de Codex non-interactive, um fluxo de correção de falha de CI se parece com isto:

1. Primeiro rodar o teste para reproduzir a falha
2. Pedir ao Codex a menor correção
3. Gerar um patch artifact
4. Abrir um PR separando o fix do job original

Com npm test 2>&1 | codex exec "resuma a causa da falha e sugira a menor correção", você passa a saída do teste para o Codex resumir a falha e sugerir um reparo mínimo.

Princípios de segurança

Não dê ao Codex acesso de escrita ao repositório e acesso a secrets no mesmo job. Use o sandbox com menor privilégio possível: read-only por padrão, workspace-write apenas para o diretório de trabalho, e danger-full-access só em ambientes controlados.

Separe a geração do patch artifact da criação do PR para não expor API keys a código não confiável.

Não vale expandir aqui um YAML completo de GitHub Actions. O princípio é simples: menor privilégio, patch separado e merge humano. A automação com codex exec é tratada em outro artigo desta série.

Resumo

O desenvolvimento orientado a testes com Codex se resume a um modelo de três fases: Red escreve apenas testes, Green mexe apenas na implementação, e Refactor limpa depois de rodar os testes de novo. Cada fase precisa entregar evidência revisável: comando, resumo de falha ou sucesso e lista de arquivos modificados.

Os guardrails contra falsos verdes são a parte mais importante: revisar se arquivos de teste foram alterados, se assertions foram enfraquecidas, se testes foram pulados, se fixtures mudaram, se só unit tests rodaram quando integração importava, ou se o workflow de CI foi skipped.

Em equipe, verde local não basta. CI status checks, PR review e regras de protected branch decidem se a mudança pode ser mergeada.

Na próxima vez que pedir ao Codex para mudar código, faça ele escrever o teste primeiro, confirme o vermelho e então revise a evidência. Não pare nas palavras “os testes passaram”.