Casos de falha com Codex: por que a IA quebra código e como validar mudanças

git diff --stat mostra de repente 18 arquivos, embora a tarefa que você deu ao Codex fosse só “corrigir o estado de um botão”. A CI está verde. Mas, ao abrir o diff, aparece outra história: coverageThreshold foi reduzido, um flaky test virou skip e um helper validateEmail() foi gerado mesmo já existindo emailSchema no repositório.

O Codex não quebrou o código de propósito. O limite da tarefa era amplo demais, e o processo de validação estava frouxo demais. Aqui não é uma discussão abstrata sobre a confiabilidade da IA. A ideia é montar uma tabela de padrões de falha, gates de validação, fluxo de rollback e checklist de review para tratar falha como lacuna de processo.

Tabela de padrões de falha: como a IA quebra código

Um estudo do arXiv sobre 33k agent-authored PRs no GitHub observou que PRs não mergeadas costumam ser maiores, tocar mais arquivos e falhar com mais frequência na validação de CI/CD do projeto. Isso não quer dizer que os AI agents simplesmente não sejam inteligentes. Decomposição de tarefas, critérios de aceitação e engajamento do reviewer também contam.

Estes são 9 padrões comuns, com sinal e primeira reação:

Padrão	Como aparece	Sinal	Primeira reação
Diff grande demais	O scope da mudança passa muito do pedido	git diff --stat mostra muito mais arquivos do que a tarefa descreve, como 10+ arquivos para um “fix de botão”	Olhar primeiro a file list. Separar mudanças esperadas de mudanças fora do scope; dividir ou reverter o extra
Testes falsamente verdes	Os testes passam, mas a lógica continua errada	O diff reduz coverageThreshold, coloca um flaky test em skip ou afrouxa assertions	Conferir se a configuração de testes mudou; exigir um teste de regressão que falhe antes da mudança
Diretório errado	CI config ou arquivos sem relação foram alterados	.github/workflows/, Makefile ou package.json scripts mudam sem a tarefa pedir	Verificar se AGENTS.md proíbe mudanças em CI/config; reverter e escrever a regra
Código duplicado	Um helper ou utilitário já existe	O diff adiciona um helper, mas o repo já tem a mesma função ou schema	Buscar implementação existente; se existir, reverter o duplicado e pedir ao Codex para usar o que já existe
PR grande demais	PR grande sem plan	O PR body só diz “fix issue”, sem implementation plan, comandos de verificação ou rollback	Pedir PRs menores, cada uma verificável, revisável e reversível
CI enfraquecida	A config de CI muda para fazer checks passarem	A CI falhou, mas o patch muda só test/CI config, não código de negócio	Tratar como blocker; reverter a mudança de CI e exigir fix no código de negócio
Bug de negócio escondido	A lógica parece correta, mas viola uma regra de negócio	O diff remove permission check ou validation que os testes não cobrem	Seguir um critical path, revisar efeitos colaterais e exigir approval explícito
Untrusted input	Entrada externa usada sem validação	Codex usa dados ou paths fornecidos pelo usuário sem sanitization ou validation	Conferir input validation; se faltar, exigir validation tests
Mudança grande sem plan	Implementação começou antes do plan	Codex editou código antes de listar arquivos a tocar, arquivos proibidos e comandos de verificação	Exigir /plan ou goal/context/constraints/done criteria explícitos antes de implementar

Esses padrões raramente aparecem isolados. Uma PR com diff grande demais pode misturar diretório errado, código duplicado e testes falsamente verdes. A checklist do GitHub para agent PR review também cita CI gaming, pontos cegos de reaproveitamento de código, problemas ocultos de correctness e PRs grandes sem plan como sinais de alerta.

A primeira reação é simples: não comece perguntando se a CI está verde. Comece pelo scope do diff e pela granularidade de rollback.

Fluxo de divisão de tarefas: trabalho grande não é proibido para Codex

As best practices da OpenAI recomendam planejar antes de implementar quando uma tarefa é complexa ou ambígua. O Codex tende a produzir melhor quando consegue verificar o trabalho, e tarefas pequenas e focadas são mais fáceis de testar e revisar.

Mas “dividir menor” não é um slogan vago. A granularidade certa é o ponto em que cada etapa pode ser validada e revertida separadamente.

Ciclo de sete etapas: de scope a update rules

Use este ciclo para mudanças do Codex:

scope -> plan -> patch -> verify -> review -> merge/rollback -> update rules

Cada etapa tem perguntas e uma condição de retorno.

1. scope

Perguntas:

• A tarefa é concreta o suficiente para virar goal + context + constraints + done criteria?
• Ela cruza vários subsistemas, como auth, payment e notification?
• Ela pode afetar configuração de CI, schema de banco de dados ou dependências externas?

Retorno: se cruzar vários subsistemas ou afetar CI/config, divida primeiro em tarefas separadas.

2. plan

Perguntas:

• O Codex listou primeiro os arquivos esperados, arquivos ou diretórios que não vai tocar e comandos de verificação?
• O plan inclui riscos e condições de saída?
• O plan descreve o caminho de rollback?

Retorno: se não houver plan ou esses pontos estiverem faltando, peça um novo /plan.

3. patch

Perguntas:

• git diff --stat bate com o scope de arquivos do plan?
• O Codex mudou arquivos fora do scope, como CI/config ou arquivos sem relação?
• Ele gerou código duplicado, como um helper já existente?

Retorno: se o diff não bater com o plan ou tocar um sinal de alerta, volte ao passo 2.

4. verify

Perguntas:

• Foram adicionados testes para o core path?
• O teste falharia antes da mudança?
• Os CI status checks são required e não skipped?
• lint ou pre-commit passaram?

Retorno: se nenhum teste relevante foi adicionado ou se a mudança só fez os testes passarem enfraquecendo configuração, volte ao passo 3.

5. review

Perguntas:

• O scope do diff bate com a tarefa?
• Alguém seguiu um critical path?
• Um reviewer humano approved explicitamente, em vez de confiar só no autorrelato da IA?
• A branch protection exige required reviews, required status checks e conversation resolution?

Retorno: se o reviewer pedir mudanças ou encontrar alerta, volte ao passo 3.

6. merge/rollback

Perguntas:

• A mudança cumpre a checklist de evidências da próxima seção?
• Ela pode ser revertida de forma independente no nível de hunk ou arquivo?
• O trabalho ficou isolado em um worktree, para descartar uma tentativa falha e levar uma tentativa bem-sucedida a PR?

Retorno: se faltarem evidências ou a mudança não for reversível de forma independente, rollback e volta ao passo 1.

7. update rules

Perguntas:

• A falha veio de uma regra faltante em AGENTS.md, como “não mexer na CI config” ou “dividir tarefas com mais de cinco arquivos”?
• Área proibida, critério de aceitação ou rollback deveriam ser escritos em AGENTS.md?

Ação: se a falha veio de uma regra faltante, escreva em AGENTS.md.

Tarefas grandes continuam possíveis com Codex

Refatorações grandes não são proibidas. Elas só precisam ser divididas até que cada etapa possa sofrer rollback sozinha. A experiência de refatoração com IA em 10.000 linhas mostra a mesma coisa: passos pequenos e rede de segurança com testes importam.

Verifique a granularidade assim:

• Cada patch pode ser revertido de forma independente no nível de hunk ou arquivo?
• Cada verify consegue provar que o comportamento antes da mudança falharia?
• Cada merge tem reviewer approve explícito e status checks?

Se a resposta for não, a tarefa ainda está grande demais.

Codex review pane na prática: validar não é só testar

Ao revisar uma mudança do Codex, a primeira coisa não é o resultado dos testes. É o scope do diff e a granularidade de rollback. O review pane do app Codex oferece três views e operações no nível de hunk/arquivo.

Três views de diff

O review pane reflete o estado Git do repositório, não só as edições do Codex. Ele pode mostrar mudanças do Codex, do usuário e outras uncommitted changes.

View	O que mostra	Quando usar
uncommitted changes	Todas as mudanças sem commit, por padrão	Revisar o scope da tarefa Codex atual
all branch changes	Todas as mudanças da branch atual contra a base branch	Revisar a cadeia inteira de tarefas, incluindo vários turns
last turn changes	As mudanças do último turn do Codex	Isolar o que Codex acabou de fazer e detectar rápido mudanças fora do scope

Comece com uncommitted changes para confirmar o scope. Depois veja all branch changes para achar sobras de trabalhos anteriores. Por fim use last turn changes para verificar se o Codex seguiu o plan.

Inline comments e operações hunk/arquivo

O review pane aceita inline comments em linhas específicas do diff. Esses comentários podem virar contexto para uma correção posterior do Codex.

Níveis de operação:

• entire diff: stage/unstage/revert do diff inteiro
• file: stage/unstage/revert de um arquivo
• hunk: stage/unstage/revert de um bloco de código, a menor unidade útil

Se você encontrar uma mudança fora do scope, como remoção de config de CI, reverta primeiro aquele hunk ou arquivo, não o diff inteiro.

Carregamento de PR context

Em uma PR branch, se GitHub access ou gh auth login estiver disponível, o review pane pode carregar PR context, review comments e changed files. Isso muda a revisão de “ver diff local” para “ver PR diff mais comentários de reviewer”.

Lembrete sobre fatos voláteis: detalhes de UI e slash command podem mudar. Reabra a página oficial antes de publicar se esse comportamento exato importar.

Princípio central da review

Validar não é só olhar testes:

1. Primeiro confira se o scope do diff bate com o plan
2. Depois confira se a granularidade de rollback é pequena o suficiente, como hunk ou arquivo
3. Por fim confira se testes foram adicionados e cobrem o critical path

Se os dois primeiros pontos falharem, testes passando não provam que o código está correto.

Checklist de evidências: testes passando não bastam

GitHub Docs explica que required status checks precisam estar successful, skipped ou neutral antes de merge em uma protected branch. No GitHub Actions, um check skipped pode ser tratado como success e não bloquear o merge.

Por isso “CI verde” não significa “código bom”. Você precisa de um conjunto de evidências, não de um único sinal.

Use esta checklist.

Evidências no nível de código

• O scope do diff bate com a tarefa, sem mudanças fora do scope
• Nenhum código duplicado foi adicionado; o projeto foi pesquisado por equivalentes existentes
• CI/config não foi alterada, salvo se a tarefa permitia explicitamente

Evidências no nível de testes

• Testes foram adicionados para o core path
• Os testes falhariam antes da mudança, não apenas passam depois
• A configuração de testes não foi enfraquecida: sem coverage threshold reduzido, sem skip, sem assertion mais fraca

Evidências no nível de CI

• lint e pre-commit passaram
• CI status checks são required e não skipped
• A configuração de CI não mudou só para fazer o check passar

Evidências no nível de PR

• O PR body inclui implementation plan, comandos de verificação e notas de rollback
• Um reviewer humano approved explicitamente, em vez de confiar no autorrelato da IA
• A branch protection cobre required reviews, required status checks e conversation resolution

Evidências no nível de rollback

• Cada patch pode ser revertido de forma independente no nível de hunk ou arquivo
• A tarefa ficou isolada em um worktree, para descartar uma tentativa falha e levar uma bem-sucedida a PR

Branch protection e status checks

Protected branches do GitHub podem exigir:

• required reviews: número definido de approvals antes do merge
• required status checks: checks precisam passar, ficar skipped ou neutral antes de entrar na protected branch
• conversation resolution: todas as conversas precisam estar resolved antes do merge

Esses são merge gates fora da IA. Eles não são substituídos pelo fato de a IA dizer que terminou.

Ordem de review

Use esta ordem:

1. Revisar primeiro o scope do diff, incluindo file list e tamanho do diff
2. Revisar se CI ou configuração de testes mudou
3. Revisar se testes foram adicionados e cobrem o core path
4. Revisar se um reviewer approved explicitamente

Não inverta a ordem. Começar pelos testes facilita perder mudanças fora do scope e CI enfraquecida.

Rollback e retrospectiva: o que fazer depois de uma mudança ruim

Quando a review encontra mudança fora do scope ou teste falsamente verde, o primeiro movimento é rollback, não pedir ao Codex para continuar corrigindo o mesmo diff confuso.

Granularidade de rollback: de hunk a branch

Escolha o nível de rollback conforme o escopo e a causa da falha:

Granularidade	Quando usar	Operação
Revert no nível de hunk	Um bloco de código contém mudança fora do scope, como remoção de CI	Selecionar aquele hunk no review pane -> revert
Revert no nível de arquivo	Um arquivo inteiro contém código duplicado ou mudanças fora do scope	Selecionar aquele file no review pane -> revert
Descartar branch	A direção da tarefa está errada e vários arquivos precisam ir embora	git checkout main -> excluir a branch

Prefira a menor granularidade útil. Só descarte uma branch quando vários hunks ou arquivos estiverem errados.

Isolamento com worktree: tentativas falhas podem ser descartadas

O artigo Codex Worktree desta série usa worktrees para isolar tarefas paralelas. Uma tentativa falha pode ser descartada; uma bem-sucedida pode ir para PR.

Se uma tarefa quebra código dentro do worktree, exclua aquele worktree e mantenha o workspace principal limpo. Isso é mais seguro do que reverter várias vezes na mesma branch.

Depois do rollback: escrever em AGENTS.md

Depois do rollback, decida se a falha veio de uma regra faltante. Se veio, escreva em AGENTS.md.

Faça estas perguntas:

• Faltava uma convenção de projeto, como “não mexer na CI config” ou “dividir tarefas acima de cinco arquivos”?
• Faltavam critérios de aceitação, como “testes precisam provar a falha antes da mudança”?
• Faltava regra de rollback, como “cada patch precisa ser revertível separadamente”?

Se sim, escreva a regra no lugar certo de AGENTS.md, como descrito na próxima seção.

Depois da retrospectiva: transformar fluxos repetidos em skills

Decida se uma falha deve virar skill com estas perguntas:

• A falha veio de uma fronteira de capacidade do Codex, como entender mal uma restrição de negócio?
• Veio de um workflow complexo em várias etapas, como coordenação multi-agent?
• Veio de um fluxo de review que você repete com frequência, como checar scope do diff, CI config e testes adicionados toda vez?

Se sim, transforme isso em skill, como no artigo Codex Skills/plugins desta série.

Onde colocar regras em AGENTS.md

Antes de cada run ou session, o Codex monta uma instruction chain e lê arquivos AGENTS.md globais e de projeto. No nível de projeto, ele lê do Git root até o diretório atual. O arquivo mais próximo é mais específico.

Isso significa que AGENTS.md pode ficar na raiz do repositório, em um submódulo ou em um diretório de funcionalidade. O Codex deve preferir a regra mais específica quando os paths se sobrepõem.

Locais e conteúdos comuns de AGENTS.md

O guia inicial do Codex nesta série cobre um template típico de AGENTS.md:

Local	Conteúdo típico	Exemplo
repo root	repo layout, build/test/lint commands, engineering conventions	Project structure: src/frontend, src/backend, src/shared; build: npm run build; test: npm test; lint: npm run lint
src/frontend	frontend-specific conventions e PR expectations	frontend usa apenas React hooks, não class components; PRs precisam incluir Storybook stories
src/backend	backend-specific conventions e do-not rules	backend não acessa banco de dados diretamente; use ORM; não escreva SQL em controllers
src/shared	shared utility conventions	shared contém apenas pure functions, sem side effects

Onde escrever lições de falha

Depois de uma falha, coloque a regra conforme a causa:

Causa da falha	Onde escrever	Exemplo
Config de CI removida por engano	repo root -> PR expectations -> do-not rules	Não modificar .github/workflows/, Makefile ou package.json scripts sem aprovação explícita
Mais de cinco arquivos alterados	repo root -> PR expectations -> do-not rules	Mudanças que tocam mais de cinco arquivos devem ser divididas; cada tarefa deve tocar no máximo três arquivos
Testes falsamente verdes	repo root -> what done means	Testes precisam cobrir o core path e provar que o comportamento antes da mudança falha, não apenas que o novo passa
Código duplicado	repo root -> engineering conventions	Antes de adicionar helper em src/lib, buscar equivalente existente; se existir, usar o existente
Mudança grande sem plan	repo root -> PR expectations	Mudanças que tocam mais de três arquivos exigem /plan primeiro, com arquivos a editar, arquivos proibidos e comandos de verificação
Untrusted input	src/backend -> engineering conventions	Toda entrada de usuário deve ser validada; não use dados ou paths fornecidos pelo usuário diretamente
Bug de negócio escondido	src/backend -> engineering conventions	Depois de mudar permission checks ou validation, seguir um critical path e revisar efeitos colaterais

Descoberta de regras: o arquivo mais próximo vence

A documentação de AGENTS.md da OpenAI descreve instruções de projeto como uma cadeia do Git root até o diretório atual, onde arquivos mais próximos são mais específicos.

Na prática:

• AGENTS.md no repo root guarda regras gerais, como build/test/lint commands e “não mexer na CI”
• AGENTS.md em submódulo guarda regras específicas, como só usar hooks no frontend ou proibir SQL no backend
• AGENTS.md em diretório de funcionalidade guarda as regras mais específicas, como restrições de negócio de uma API

Ao escrever uma lição:

• Convenções globais como “não mexer na CI” vão para o repo root
• Convenções de submódulo como regras de frontend vão em src/frontend
• Restrições de funcionalidade como uma regra de API vão em src/backend/api/xxx

O limite de AGENTS.md

AGENTS.md reduz mudanças fora do scope e erros acidentais, mas não prova correção. O Codex pode seguir AGENTS.md e ainda produzir lógica errada.

O último gate continua sendo approval explícito de um reviewer humano, não a simples existência de um arquivo de regras.

Checklist de review humana para PRs de IA

A recomendação do GitHub para revisar agent-generated PRs começa por file list e tamanho do diff, depois confere se CI/test config mudou, busca helpers duplicados, segue um critical path e pede um teste que prove a falha antes da mudança.

Use esta checklist de sinais vermelhos.

Sinais vermelhos no nível de código

• A file list e o tamanho do diff são muito maiores que a descrição da tarefa
• CI/test config mudou, como .github/workflows/, Makefile ou package.json scripts
• Um novo helper duplica um helper existente
• O PR body só diz “fix issue”, sem implementation plan, comandos de verificação ou rollback
• A PR é grande demais, como mais de 10 arquivos

Sinais vermelhos no nível de testes

• Nenhum teste novo foi adicionado
• O teste verifica só comportamento post-change e não prova que o comportamento antigo falhava
• A configuração de testes foi enfraquecida: coverage threshold menor, flaky test em skip ou assertion mais fraca

Sinais vermelhos no nível de CI

• A CI falhou, mas o patch só mudou tests ou CI config em vez de código de negócio
• CI status checks estão skipped ou neutral, não passing
• A configuração de CI mudou para fazer o check passar

Sinais vermelhos no nível de PR

• PR body vazio
• Sem implementation plan
• Sem reviewer approval, só relatório da IA
• Conversations unresolved

Blockers vs sinais de divisão

Tipo	Sinal vermelho	Resposta
Blocker	A CI falhou, mas só test/CI config mudou	Request changes, reverter a mudança de CI e exigir fix no código de negócio
Blocker	Testes falsamente verdes, como coverageThreshold reduzido ou skip	Request changes, reverter a configuração de teste e exigir novo teste
Blocker	Untrusted input sem validation	Request changes e exigir validation tests
Sinal de divisão	PR grande, como mais de 10 arquivos	Request changes e dividir em PRs menores
Sinal de divisão	PR body vazio sem implementation plan	Request changes e adicionar plan, comandos de verificação e rollback

Princípio central do reviewer

O reviewer não está julgando se a IA é confiável em abstrato. Ele verifica:

1. se o scope do diff bate com a descrição da tarefa
2. se CI/test config mudou
3. se testes foram adicionados e cobrem o core path
4. se efeitos colaterais escondidos foram checados seguindo um critical path

Não inverta a ordem. Começar pelos testes facilita perder CI enfraquecida e mudanças fora do scope.

Conclusão

Quando o Codex quebra código, a causa geralmente não é ele ser “não confiável” em abstrato. O limite da tarefa era amplo demais, e o processo de aceitação estava frouxo. A checklist prática é:

• Tabela de padrões de falha: reconhecer formas comuns de mudanças do Codex darem errado
• Ciclo de sete etapas: de scope a update rules como fluxo completo de aceitação
• Review pane na prática: não parar nos testes; revisar primeiro scope do diff e granularidade de rollback
• Checklist de evidências: testes passando não bastam; revisar também scope do diff, testes adicionados, status da CI, review humana e branch protection
• Rollback e retrospectiva: revert no nível de hunk/arquivo, isolamento com worktree e escrita em AGENTS.md ou skill
• Locais de AGENTS.md: colocar regras em repo root, submódulo ou diretório de funcionalidade conforme o scope
• Sinais vermelhos de review humana: começar por file list e diff size, depois CI/test config, testes adicionados e reviewer approval

Transforme essa lista em uma ferramenta real de review. A cada mudança do Codex, percorra os itens. Se o mesmo fluxo de review se repetir, considere transformá-lo em skill, como no artigo Codex Skills/plugins.

Falha não é surpresa. É lacuna de processo.

Próximos passos e leituras recomendadas

Artigos publicados

• Refatoração com IA de 10.000 linhas: retrospectiva real e rede de segurança com testes — lições práticas sobre passos pequenos e rede de testes
• Guia de refatoração com Cursor — princípios de review que também servem para outras ferramentas de coding com IA
• GitHub Actions CI workflow — fundamentos de status checks
• GitHub Actions workflow — fundamentos de PR workflow
• Fluxo de agente no Codex Cloud — execução remota, aceitação de PR e ciclos de tarefas longas

Mesma série: guia prático de Codex

• Guia completo para começar com Codex — CLI, IDE, Cloud e desktop
• Segurança e permissões do Codex — sandbox e approval reduzem risco
• Revisão de código com Codex — review como gate de aceitação
• Tarefas de automação com Codex — patches gerados por exec ainda precisam de review humana
• Codex Worktree na prática — isolar tarefas paralelas
• Codex Skills/plugins — transformar workflows de review em skills
• Desenvolvimento guiado por testes com Codex — TDD + Codex
• Otimização de custos do Codex
• Codex em fluxos empresariais