Usar Codex para escrever código é a parte mais visível. O ganho mais consistente aparece quando ele também reproduz o problema, cria um teste, revisa o diff e mostra evidência de que a correção funciona.
Isso muda a conversa de “parece resolvido” para “o erro falhava neste cenário, o teste protege o comportamento e a suíte continua passando”.
Em uma frase: peça ao Codex para provar o bug antes de corrigi-lo e provar a correção antes de entregar.
Três usos diferentes
Diagnóstico de bug
O objetivo é localizar causa, não editar rápido. O Codex inspeciona fluxo, logs, testes e histórico relevante, reproduz a falha e apresenta hipóteses com evidência.
Criação de testes
O objetivo é transformar comportamento esperado em verificação repetível. O teste deve falhar pelo motivo correto antes da correção.
Code review
O objetivo é analisar uma mudança já feita: regressões, contratos, segurança, casos de borda, clareza e falta de testes.
Misturar os três em um pedido vago pode fazer o agente corrigir antes de entender e escrever um teste que apenas confirma a própria implementação.
Como dar um bug para o Codex
Inclua:
- comportamento esperado;
- comportamento observado;
- passos para reproduzir;
- ambiente e versão;
- mensagem de erro completa;
- frequência;
- último momento conhecido em que funcionava;
- arquivos, logs ou testes relevantes;
- restrições da correção.
Exemplo:
Ao salvar um cliente com e-mail em maiúsculas, a API retorna conflito,
embora o cadastro existente esteja em minúsculas.
Reproduza com um teste. Localize a causa e proponha a menor correção.
Não altere o schema nem faça migração. Só implemente depois de explicar o plano.
O artigo Briefing e AGENTS.md para Codex traz um modelo completo para transformar relatos em critérios de aceite.
Diagnóstico em quatro etapas
1. Reproduzir
Se não existe reprodução, a correção pode atuar no sintoma errado. Peça comando, entrada e saída observada.
2. Traçar o fluxo
Identifique onde o dado entra, é transformado, persistido e devolvido. Bugs aparecem muitas vezes na fronteira entre módulos.
3. Formular hipóteses
Uma hipótese útil aponta arquivo, condição e evidência. “Pode ser cache” sem observação não ajuda.
4. Isolar a causa
Faça o menor experimento capaz de diferenciar hipóteses. Depois escreva o teste de regressão.
O guia oficial de uso do Codex e os casos de uso do Codex mostram fluxos de análise, engenharia e qualidade com execução verificável.
Teste de regressão: a prova mínima
Um teste de regressão precisa:
- representar o cenário real;
- falhar no código anterior;
- passar depois da correção;
- não depender de detalhe irrelevante;
- ter nome que explique o comportamento.
Peça ao Codex para mostrar o resultado antes e depois. Se o teste já passava antes da mudança, ele não prova o bug.
Que testes pedir
Unitário
Para lógica isolada, transformação e validação.
Integração
Para banco, fila, API e interação entre módulos.
Contrato
Para preservar schema, status, eventos e integrações externas.
End-to-end
Para fluxo crítico do ponto de vista do usuário.
Visual
Para layout, responsividade e estados da interface.
Não transforme todo bug em teste end-to-end. Escolha a camada mais próxima da causa e acrescente uma verificação de fluxo quando o risco justificar.
Prompt para criar testes
Mapeie o comportamento e os testes existentes.
Proponha casos: feliz, erro, borda e regressão.
Implemente primeiro o teste que reproduz o bug.
Execute e confirme que falha pelo motivo esperado.
Depois faça a menor correção e execute testes do módulo e suíte relacionada.
Na entrega, mostre comandos e resultados.
Como pedir code review
Defina o objeto: diff local, branch, pull request ou conjunto de arquivos. Depois informe prioridades.
Revise este diff procurando bugs funcionais, quebra de contrato, segurança,
concorrência, dados e falta de teste. Ignore preferência de estilo já coberta pelo lint.
Para cada finding, informe severidade, arquivo e linha, cenário reproduzível,
impacto e correção mínima. Não aplique alterações.
O guia oficial de code review descreve o Codex como apoio ao fluxo de revisão. A saída deve ser tratada como findings a verificar, não como sentença automática.
Como classificar findings
Crítico
Perda de dados, acesso indevido, indisponibilidade ampla ou falha de segurança explorável no contexto real.
Alto
Quebra de fluxo importante, contrato público ou cálculo relevante.
Médio
Caso de borda plausível, manutenção que aumenta risco ou degradação localizada.
Baixo
Melhoria pequena sem impacto funcional imediato.
Severidade depende do contexto. Uma validação ausente pode ser baixa em ferramenta interna isolada e crítica em endpoint público financeiro.
Como confirmar um finding
Exija quatro elementos:
- trecho exato;
- caminho de execução;
- entrada que ativa o problema;
- resultado observado ou teste.
Se o agente não consegue demonstrar, marque como hipótese. Leia o arquivo e execute a reprodução antes de mudar o código.
Review não é “corrija tudo”
Depois de confirmar findings:
- agrupe por causa;
- remova duplicados;
- priorize impacto e probabilidade;
- selecione a menor mudança segura;
- faça um finding por etapa quando possível;
- execute testes após cada grupo;
- revise o diff final.
Aplicar todas as sugestões de uma vez aumenta regressão e dificulta descobrir qual mudança causou o problema.
QA para interface
Testes automatizados não substituem abrir a página. Para mudança visual:
- execute o projeto;
- confira largura desktop e mobile;
- teste estados vazio, carregando, erro e sucesso;
- navegue por teclado quando aplicável;
- verifique console e rede;
- faça screenshot dos pontos críticos;
- compare com referência aprovada.
O Codex pode executar parte desse fluxo, mas uma pessoa responsável deve avaliar se a interface comunica o resultado correto.
QA para API e automação
Confirme:
- autenticação e autorização;
- validação de entrada;
- idempotência;
- timeout e repetição;
- tratamento de erro;
- logs sem segredo;
- contratos com dependências;
- comportamento com dados duplicados;
- rollback ou reversão.
Para um webhook, teste evento válido, assinatura inválida, repetição do mesmo evento e indisponibilidade temporária do destino.
Erros comuns
- pedir correção sem reprodução;
- aceitar teste que nunca falhou;
- revisar o repositório inteiro sem escopo;
- classificar tudo como crítico;
- aplicar findings sem ler o código;
- confundir lint com revisão funcional;
- ignorar teste visual;
- declarar sucesso sem mostrar comando e resultado;
- testar apenas o caminho feliz.
Fluxo recomendado
RELATO
→ REPRODUÇÃO
→ TESTE QUE FALHA
→ CAUSA CONFIRMADA
→ CORREÇÃO MÍNIMA
→ TESTE QUE PASSA
→ SUÍTE RELACIONADA
→ REVIEW DO DIFF
→ QA HUMANO
Esse fluxo serve tanto para bug pontual quanto para uma mudança maior. O que varia é a profundidade da verificação.
Relação com governança
Ambientes, permissões e comandos disponíveis determinam o que o Codex pode testar. Consulte Segurança e governança no Codex antes de liberar rede, produção ou credenciais.
Se você está começando, leia OpenAI Codex para iniciantes. Para automatizar a rotina, transforme apenas procedimentos já validados em skills, conforme Skills, plugins e MCP no Codex.
Checklist de entrega
- O problema foi reproduzido?
- Existe teste que falhava antes?
- A causa foi confirmada?
- A correção é proporcional ao escopo?
- Teste novo e suíte relacionada passaram?
- Findings foram verificados?
- Diff contém apenas mudanças necessárias?
- Segurança, contrato e dados foram revisados?
- QA visual ou operacional foi feito?
- Evidências e riscos restantes estão registrados?
O Codex aumenta a capacidade de investigar e verificar. A equipe mantém a responsabilidade de decidir o que é defeito, qual risco aceita e quando a evidência é suficiente para entregar.
Como revisar uma correção gerada pelo Codex
Leia o diff em três passagens.
Passagem funcional
A mudança resolve exatamente o cenário? Entradas e saídas preservam contratos? Casos de erro continuam coerentes?
Passagem de risco
Procure acesso, dados, concorrência, timeout, repetição, transações, logs e dependências. Uma linha pequena em autenticação pode ter impacto maior que cem linhas de interface.
Passagem de manutenção
O código segue os padrões do módulo? Existe duplicação, comentário enganoso ou teste acoplado à implementação?
Depois das três passagens, execute testes de novo. A leitura pode levar a um pequeno ajuste que invalida o resultado anterior.
Como lidar com bug intermitente
Não aumente tentativas indefinidamente. Registre timestamp, entrada, identificador, ambiente e correlação. Peça instrumentação mínima para diferenciar condições.
Adicione logs estruturados sem dados sensíveis nos pontos A, B e C.
Inclua request_id, estado e duração. Não altere o comportamento.
Execute o cenário controlado e compare uma ocorrência boa e uma ruim.
Quando a causa for confirmada, remova logs temporários ou ajuste o nível. Observabilidade de diagnóstico não deve virar ruído permanente.
Testes que parecem bons, mas não protegem
- teste que simula tudo e nunca chama a lógica real;
- snapshot grande que muda sem explicar o comportamento;
- asserção apenas de status, ignorando conteúdo;
- teste dependente da ordem de execução;
- caso feliz sem erro ou borda;
- teste que repete a implementação;
- teste flakey aceito porque “passa na segunda”.
Peça ao Codex para explicar qual regressão cada teste detecta. Se não houver resposta concreta, revise a estratégia.
Critério de encerrar a investigação
Uma tarefa pode terminar com correção, mitigação ou diagnóstico documentado. Se a causa depende de sistema externo, registre evidência, impacto, workaround e próximo responsável.
Não force uma mudança especulativa só para fechar o ticket. Uma conclusão honesta e reproduzível é melhor que uma correção que desloca o erro.
Como usar histórico sem ancorar na solução antiga
Issues, commits e incidentes anteriores ajudam a entender decisões. Peça ao Codex para separar contexto de evidência atual. Um comentário antigo pode estar errado ou desatualizado.
Use o histórico para responder:
- quando o comportamento mudou;
- que restrição motivou a implementação;
- quais alternativas já foram tentadas;
- que áreas costumam regredir;
- quem conhece o domínio.
Depois confirme no código e nos testes atuais. Não reverta uma decisão arquitetural apenas porque uma versão anterior parecia mais simples.
Relatório curto de investigação
Sintoma: [o que foi observado]
Reprodução: [comando ou passos]
Causa: [arquivo, condição e evidência]
Correção: [mudança mínima]
Teste: [falha antes, passa depois]
Regressões: [suíte e QA]
Risco restante: [limitação]
Esse formato permite revisar sem reler toda a conversa. Anexe logs sanitizados e screenshots quando ajudam.
Quando pedir uma segunda revisão
Faça uma nova passagem quando a mudança toca autenticação, pagamentos, dados, concorrência, migração, endpoint público ou muitas áreas. A segunda revisão deve receber o diff final e o contexto de risco.
Mesmo assim, cada finding precisa ser confirmado. Duas respostas de agente iguais não substituem um teste que demonstra o problema.
Perguntas frequentes
O Codex consegue encontrar bugs sozinho? +
Ele pode inspecionar código, reproduzir falhas e levantar hipóteses, mas precisa de contexto, ambiente e critérios. Findings devem ser confirmados com evidência.
Posso pedir ao Codex para escrever testes? +
Sim. Informe o comportamento esperado, framework, comandos e casos de borda. Revise se o teste realmente falha antes da correção e passa depois dela.
Code review do Codex substitui revisão humana? +
Não. Ele amplia cobertura e velocidade, enquanto a responsabilidade por arquitetura, risco de negócio e aprovação continua humana.
Como reduzir falsos positivos no review? +
Peça arquivo e linha, cenário reproduzível, impacto concreto e teste que demonstre o problema. Descarte findings que não resistem à verificação.
O Codex deve corrigir tudo que encontrar? +
Não. Primeiro classifique severidade, escopo e regressão possível. Aplique mudanças pequenas, execute testes e revise o diff antes de aceitar.
Artigos Relacionados
