Codex para revisão de código: como deixar a IA revisar PRs sem sair alterando tudo

Chega uma PR de 800 linhas com o título fix e uma descrição que diz só “corrigi algumas coisas”. Você olha para o diff, não sabe onde está o ponto crítico e também não quer ler cada arquivo alterado linha por linha. Alguém comenta na PR: @codex review for auth bypass and PII logging. Alguns minutos depois, aparece um inline comment apontando para logger.info(user.email).

Agora você precisa decidir: deixa o Codex fazer o fix, corrige você mesmo ou primeiro pergunta para a área de negócio se esse log está dentro da política? Este guia explica condições de disparo, escrita de Review guidelines, significado de P0/P1, fluxo de tratamento e fronteira de confirmação humana.

@codex review não é uma fórmula mágica

@codex review não é uma chave para a IA alterar código automaticamente. Ele só pede para o Codex ler o PR diff e publicar review comments conforme suas regras. Se vai disparar, o que será analisado e como tratar o resultado dependem da configuração prévia e do julgamento humano.

Disparos e configuração no GitHub Cloud

Para usar o Codex em code review, o repository precisa ter Codex Cloud configurado, e você precisa ter acesso aos code review settings. Há duas formas de disparo: escrever @codex review em um comentário da PR ou ativar Automatic reviews nos settings, para que o Codex publique uma review quando uma nova PR for opened for review.

Depois do disparo, o Codex lê o PR diff, segue a repository guidance, normalmente as Review guidelines escritas no AGENTS.md, e publica inline comments no formato padrão de GitHub code review. @codex review não é approval. Automatic reviews também não significa aprovação automática. Mudanças sensíveis, como auth, payment ou data migration, ainda exigem confirmação humana.

Você pode combinar disparadores de PR e workflows de CI com branch protection rules para garantir que a AI review seja apenas uma das checagens. Para configurar PR triggers, veja o artigo anterior sobre GitHub Actions PR triggers.

Focar em P0/P1, não em uma lista interminável

Por padrão, o Codex marca apenas problemas de prioridade P0/P1. P0 é um problema bloqueante: security regressions, auth bypass, data loss. P1 é um problema que deve ser corrigido: performance, concurrency, logging sensitive data.

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

Começar →Anúncio

Esse foco evita a explosão de review comments, mantém alto sinal e reduz ruído de baixo valor. Você pode sobrescrever a regra padrão na seção Review guidelines do AGENTS.md, por exemplo pedindo para olhar apenas auth bypass, PII logging e concurrency, sem comentar code style, que fica com Prettier, nem minor performance fora de hot paths. A próxima seção mostra a escrita concreta dessas Review guidelines.

Review guidelines ficam no AGENTS.md, não em todo comentário de PR

As Review guidelines definem o foco e a prioridade do Codex review. Elas devem ficar no arquivo AGENTS.md do repository, não serem repetidas em cada comentário de PR.

Leitura em camadas do AGENTS.md e escrita de Review guidelines

O Codex lê AGENTS.md antes de começar. A leitura vai do Git root até o diretório de trabalho atual, e instruções mais próximas são mais específicas. Por exemplo, um AGENTS.md dentro de auth/ pode sobrescrever regras do projeto e focar apenas em riscos relacionados a auth.

Uma seção típica de Review guidelines:

## Review guidelines

Focar apenas nos seguintes riscos:
1. Security regressions(auth bypass、path traversal)
2. PII logging(user.email、phone number)
3. Concurrency issues(race condition、deadlock)

Não focar em:
- Code style(automatizado com Prettier)
- Minor performance(fora de hot paths)

A vantagem: todas as PRs compartilham a mesma base de regras, você evita repetir comentários e o AGENTS.md mais perto dos changed files pode ser mais específico.

Vale lembrar que arquivos de instrução têm limite definido por project_doc_max_bytes, com padrão de 32 KiB. Arquivos longos demais podem ser truncados. A escrita completa de AGENTS.md, incluindo Project rules, Review guidelines e Coding style, fica para outros artigos da série prática de Codex. Aqui o foco é só a estrutura e a prioridade das Review guidelines.

Use o Codex app review pane para entender o diff antes de decidir

O review pane do Codex app não mostra apenas sugestões de alteração da IA. Ele reflete o estado completo do Git repository. Por padrão, foca em uncommitted changes, mas também permite alternar para all branch changes ou last turn changes.

Inline comments e PR context

Os inline comments no review pane ficam diretamente nas linhas do diff. Você pode usar esse feedback preciso para decidir o próximo passo: pedir para o Codex corrigir, corrigir você mesmo ou marcar como false positive. Depois de executar /review, o resultado aparece como inline comments no review pane.

Se o Codex tiver GitHub access e o projeto atual estiver em uma PR branch, o app pode mostrar PR context: reviewer feedback, changed files e PR description. Para isso, é preciso instalar e autenticar o GitHub CLI com gh auth login. Sem isso, os PR details podem não aparecer, e você verá apenas o diff local.

Controlar a granularidade: stage/revert por file ou hunk, não o commit inteiro

O review pane permite stage, unstage e revert no nível de entire diff, file ou hunk. Não é uma boa ideia reverter o commit inteiro assim que um finding aparece, principalmente em mudanças com vários files. Trabalhar por hunk permite manter mudanças seguras e desfazer apenas a parte arriscada.

Tratando review findings: depois de @codex fix, olhe diff, CI e testes

Ao encontrar P0/P1, não entregue tudo direto para @codex fix. Primeiro você precisa decidir se o finding é real, se a correção é razoável e se a mudança toca uma fronteira sensível que exige confirmação do time.

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

Ganhar 15% off →Anúncio

Tabela de triagem de review findings

Fluxo executável para tratar findings

Confirmar se o finding é real: veja a linha do diff apontada pelo inline comment e confirme se o problema existe mesmo.

Definir a fronteira do fix: auth, payment e data migration são mudanças sensíveis e precisam de confirmação humana. style e minor perf podem ser ignorados ou deixados para a toolchain.

Escolher o tratamento:

• Deixar o Codex corrigir: escreva @codex fix the P1 issue no comentário da PR; o Codex inicia uma cloud task com base no PR context
• Corrigir você mesmo: edite o código manualmente, rode testes locais e depois faça push
• Pedir testes: abra uma follow-up issue ou explique no comentário
• Marcar false positive: explique o motivo no comentário para evitar repetição

Olhar diff e CI: mesmo que @codex fix tenha permissão para fazer push na PR branch, você ainda precisa olhar o diff, o resultado da CI e a cobertura de testes. Um fix do Codex não é merge automático, não equivale a CI passando e não substitui approval de reviewer humano.

Confirmar mudanças sensíveis com humanos: auth bypass, payment flow e data migration tocam fronteiras de segurança. Um reviewer do time precisa confirmar. Não pule essa etapa.

O que não fazer

• Não faça push/merge automático: @codex fix só pede para a IA alterar código; não é permissão de merge
• Não pule a CI: mesmo que o Codex corrija o problema, a CI precisa rodar para garantir que outros testes não quebraram
• Não ignore opiniões de reviewers humanos: AI review é uma segunda checagem, não substitui o reviewer do time
• Não dê permissões grandes demais ao Codex: main branch push, force push e write access a diretórios sensíveis devem ser limitados

Fronteiras de segurança e controle de permissões para mudanças sensíveis serão aprofundados em artigos posteriores da série prática de Codex sobre permissões e Secrets. Para boas práticas de CI, veja o guia anterior de pipeline CI com GitHub Actions.

Commit message e PR description: deixe a IA redigir, mas não invente o padrão

@codex generate commit message ou @codex generate PR description pode fazer o Codex gerar texto a partir do diff e do PR context. Revise o resultado, não use direto. O commit message deve seguir Conventional Commits, não um formato inventado na hora.

Conventional Commits e modelo de commit message

O formato de Conventional Commits é <type>[optional scope]: <description>. Tipos comuns: fix corresponde a uma versão PATCH, feat a uma versão MINOR, e um footer BREAKING CHANGE ou ! indica mudança incompatível.

Exemplo:

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

fix(auth): prevent bypass in login flow

- Add session validation before auth redirect
- Reject expired tokens within 5 minutes

Refs: #123

Usar Conventional Commits faz sentido porque é um padrão amplamente adotado. Toolchains como semantic-release, auto-changelog e commitlint dependem desse formato para gerar changelogs e decidir versões. Inventar uma regra própria quebra essas automações e aumenta o custo de colaboração do time.

Modelo de PR description

Uma PR description deve ter pelo menos cinco partes:

1. Contexto: por que a mudança existe (feedback de usuário, problema de desempenho, risco de segurança)
2. Escopo da mudança: quais módulos são afetados (auth, payment, logging)
3. Testes: cenários verificados (testes locais, cobertura de CI, verificação manual)
4. Riscos: condições de borda conhecidas (concorrência, comportamento sob alto tráfego)
5. Rollback: como voltar atrás rapidamente (revert commit, feature flag, config toggle)

Depois que o Codex gerar o texto, confira se as cinco partes estão completas, se a descrição está correta e se riscos ou rollback ficaram de fora. Não faça commit direto do texto gerado, principalmente em mudanças sensíveis.

Para orientar a geração de commit message e PR description, escreva uma instrução específica no comentário da PR, como @codex generate commit message following Conventional Commits, para que a IA siga o formato padrão.

Resumo

Codex review é uma segunda checagem de alto sinal, não permissão de merge. @codex review só pede para a IA ler o diff e publicar inline comments; Automatic reviews automatiza apenas o disparo, não approval nem merge.

Fluxo central:

1. Nas Review guidelines do AGENTS.md, foque em 1 ou 2 riscos, como auth bypass, PII logging ou concurrency. Não tente cobrir tudo
2. P0/P1 é o foco padrão para evitar explosão de review comments. P0 deve ser corrigido; P1 exige decisão de tratamento
3. Quando surgir um finding, olhe a linha do diff apontada pelo inline comment e confirme se o problema é real. Mudanças sensíveis como auth, payment ou data migration exigem confirmação humana
4. Depois de @codex fix, ainda revise diff, resultado de CI, cobertura de testes e julgamento humano. Não faça push/merge automático, não pule CI e não ignore reviewers do time
5. Use Conventional Commits para commit messages. Não invente formato; a toolchain depende do padrão para gerar changelog e decidir versões

Ações práticas:

• Adicione AGENTS.md ao repository e escreva uma seção curta de Review guidelines focada em 1 ou 2 riscos
• Teste @codex review na próxima PR e veja se os inline comments seguem suas regras
• Em mudanças sensíveis, leia os próximos artigos da série prática de Codex sobre permissões, secrets e revisão de falhas antes de decidir usar @codex fix

Artigos relacionados

• GitHub Actions PR triggers: configurar PR triggers e branch protection rules
• Boas práticas de pipeline CI com GitHub Actions: checagens de CI e responsabilidades de reviewers humanos
• Comparativo de assistentes de programação com IA: Claude Code vs Cursor vs Copilot: escolher ferramentas de AI coding