Integração Git e GitHub: Deixe o Codex ser o revisor no seu PR

📚 Navegação da Série: O artigo anterior 25 · Isolamento Paralelo com Worktrees ensina você a usar git worktree para abrir várias "faixas paralelas" que não entram em conflito para o Codex, rodando várias tarefas simultaneamente de forma isolada. Este artigo move o campo de batalha do seu terminal local para o repositório GitHub: como colocar o Codex dentro do seu Pull Request para revisar o código automaticamente, apontar falhas de acordo com as regras que você definiu e enviar as alterações diretamente de volta para a branch. O próximo artigo 27 · Automação e CI/CD levará essa estrutura para a pipeline de CI, tornando-a "sem supervisão".

Primeiro, vamos falar de um cenário que acontece quase diariamente na colaboração em equipe. O tempo que leva desde a abertura de um PR até a sua integração (merge), em grande parte, não é gasto na revisão em si, mas sim "esperando que alguém revise" — a equipe é pequena, os revisores estão ocupados, e o seu PR fica lá parado, muitas vezes por um dia inteiro.

E quando a revisão finalmente acontece, o que as pessoas costumam apontar são coisas superficiais como "este nome de variável não está bom" ou "falta um espaço nesta linha"; enquanto os problemas realmente críticos — condições de corrida sob concorrência, middleware de autenticação ausente, gravação de dados privados do usuário nos logs — são cansativos, chatos de encontrar e fáceis de passar despercebidos após analisar apenas três arquivos, sendo justamente os mais propensos a serem ignorados.

A integração do Codex com o GitHub foi feita exatamente para isso: mencione-o com um @ no comentário do PR, e ele, como um colega de equipe que nunca se cansa, varrerá o diff e, seguindo as regras definidas no seu repositório, apontará os riscos de alta prioridade diretamente no PR. Você não precisa sair do GitHub, e ele também não tirará de você a decisão final de mesclar — ele atua como revisor, e você aprova. Essa linha é a mesma que viemos protegendo desde o artigo sobre permissões [15].

Ao terminar este artigo, você terá:

• Como um único @codex review aciona a revisão no PR, o que ele responde e quais níveis de problemas ele seleciona (P0/P1, diretriz oficial)
• Como ativar a "revisão automática" — toda vez que um novo PR é aberto, ele é revisado automaticamente, sem necessidade de menção manual com @
• Como usar as Review guidelines no AGENTS.md para personalizar as regras de revisão: não gravar logs, exigir autenticação em todas as rotas... fazendo-o apontar falhas segundo os seus critérios
• Como usar @codex fix após a revisão para que ele faça as alterações e as envie de volta para a branch, além dos limites de permissão por trás dessa ação
• O comando local /review: sem precisar do GitHub, faça uma autoinspeção no terminal antes de abrir o PR, sem alterar uma única linha de código
• Uma diretriz que percorre todo o artigo: o que você pode delegar com segurança e qual linha vermelha de "publicar alterações" você mesmo deve proteger

⚠️ A revisão acionada via GitHub (@codex review, revisão automática) explicada neste artigo depende do Codex cloud (requer um plano pago + autorização prévia do repositório); o comando local /review não precisa da cloud. Vou diferenciar claramente as duas abordagens para evitar confusões.

---

01 Primeiro, diferencie as duas abordagens: O Codex no GitHub e o Codex no seu terminal

Antes de começar, vamos esclarecer um ponto que costuma causar confusão: existem dois fluxos completamente diferentes para o Codex revisar seu código, executados em locais distintos.

Analogia: O mesmo professor que corrige o caderno de tarefas que você entregou também pode sentar ao seu lado enquanto você resolve os exercícios. Um é "você termina, envia e ele corrige depois"; o outro é "você ainda está escrevendo e ele observa na hora". Ambas as tarefas são feitas pelo mesmo professor, mas o cenário, as permissões e quem inicia a ação são totalmente diferentes.

No caso do Codex, essas duas abordagens são:

A primeira: Acionada via GitHub (cloud). Você escreve @codex review em um comentário do PR no GitHub, e o Codex inicia uma tarefa na nuvem, lê o diff desse PR e escreve uma revisão no PR como se fosse um revisor humano. Todo o processo acontece enquanto você está no GitHub, e o trabalho dele é executado nas máquinas de nuvem da OpenAI (conforme explicado em [10 Cloud]). Pré-requisito: O repositório deve estar conectado ao Codex cloud e a opção Code review deve estar ativada nas configurações do repositório.

A segunda: Comando local /review (CLI). Você digita /review no terminal durante uma sessão do Codex. Ele ativa um revisor dedicado na sua máquina local, analisa o diff selecionado por você (alterações não salvas, diferenças em relação a uma branch, um commit específico...) e exibe a lista de problemas para você. Ele funciona apenas no modo de leitura — não altera nenhuma linha de código no seu espaço de trabalho. Não requer conexão com o GitHub ou uso da cloud, sendo puramente local.

Dimensão	Acionada via GitHub @codex review	Local /review
Onde é acionado	Nos comentários do PR no GitHub	Na sessão do Codex no terminal
Onde é executado	Codex cloud (nuvem)	Na sua máquina local
Objeto de revisão	O diff do PR	O diff selecionado (não commitado / comparado com branch / commit específico)
Onde o resultado é salvo	Como comentário de revisão no PR	Listado no painel de revisão do terminal
Pré-requisito	Conexão com a cloud + chave Code review ativada	Nenhum, pronto para uso local
Altera o código?	Não (a menos que você use @codex fix)	De forma alguma, puramente leitura

💡 Resumo em uma frase: Existem dois fluxos para o Codex revisar código — no GitHub, @codex review roda na nuvem e publica a revisão no PR (requer cloud e ativação da chave); no terminal, /review roda localmente e apenas lê sem alterar código (não requer nada). Este artigo foca no primeiro fluxo, enquanto o segundo serve como uma autoinspeção antes de abrir o PR.

---

02 Um único @codex review: Deixando-o apontar falhas no PR

O uso principal é extremamente simples: digite @codex review na caixa de comentários do PR e aperte Enter.

Por que vale a pena delegar isso a ele? Porque "revisar um PR com atenção" é a típica tarefa cansativa e propensa a adiamentos — quando as pessoas estão ocupadas, seu PR fica na fila esperando revisão até o fim do dia; e quando finalmente começam a olhar, a atenção começa a se dispersar após ler apenas dois arquivos. Esse tipo de tarefa "importante, mas exaustiva" é exatamente o que um colega de equipe incansável deve analisar primeiro.

Analogia: O editor encarregado de "encontrar falhas graves" antes de publicar um texto. Quando você termina de escrever um texto, pode lê-lo três vezes e não encontrar erros — porque foi você quem escreveu, e seu cérebro preenche automaticamente o que "você queria expressar". Nesse momento, você o entrega a um editor especializado em encontrar falhas graves: ele não se importa com a beleza da sua escrita, mas foca em "aqui a lógica quebrou" ou "estes dados não batem". O Codex no PR atua exatamente como esse editor: ele não elogia a elegância do seu código, mas aponta diretamente onde as coisas podem dar errado.

Na prática, acesse o GitHub e digite no campo de comentários do PR:

@codex review

O que acontece depois de enviar? O fluxo segue este ritmo:

1. O Codex adiciona uma reação 👀 ao seu comentário — indicando "recebido, comecei a analisar" (a documentação oficial deixa claro: ele primeiro reage com 👀 antes de publicar a revisão).
2. Ele inicia a tarefa na nuvem, lê o diff do PR e o compara com as regras de revisão do seu repositório (explicado na próxima seção).
3. Após a análise, ele publica uma revisão de código no PR como um colega de equipe, anexando os problemas linha por linha nos trechos correspondentes.

Existe uma definição crítica oficial que você precisa conhecer, caso contrário, pode achar que ele "deixou passar um monte de coisas":

No GitHub, o Codex apenas sinaliza problemas de nível P0 e P1, mantendo os comentários de revisão focados em riscos de alta prioridade.

Em termos simples: ele deliberadamente evita encher o seu PR com detalhes insignificantes. P0 e P1 são as prioridades dos problemas (P0 sendo a mais grave, P1 importante). Ele foca apenas nessas duas categorias — observações irrelevantes como "este nome de variável poderia ser melhor" ou "falta um espaço aqui" não são geradas por padrão. Esse design tem sido extremamente prático para mim: no ano passado, ao usar algumas ferramentas de revisão por IA, o que mais me irritava era um pequeno PR receber quarenta "sugestões", fazendo com que os bugs reais ficassem perdidos no meio do ruído. A moderação do Codex ao relatar apenas P0/P1 garante que cada comentário seja realmente relevante.

Um caso real em que o utilizei: no mês passado, o PR de um colega alterou a lógica de callback de pagamento. Durante minha própria revisão, foquei apenas em verificar se o cálculo do valor estava correto. Após rodar @codex review, ele apontou um problema P1: o endpoint de callback não possuía validação de idempotência, o que faria com que callbacks duplicados adicionassem saldo repetidamente. Eu realmente não tinha percebido isso.

💡 Resumo em uma frase: Escreva @codex review nos comentários do PR: ele adiciona uma reação 👀, lê o diff e publica a revisão como um colega de equipe; ele filtra apenas problemas de alta prioridade P0/P1, evitando poluir o PR com detalhes menores, tornando cada comentário digno de atenção.

---

03 Revisão automática: Atuando automaticamente a cada novo PR aberto

O comando @codex review é um acionamento manual. No entanto, é comum esquecer — especialmente em PRs abertos por outros membros da equipe. A ferramenta oferece uma configuração definitiva: as revisões automáticas (Automatic reviews).

Analogia: Mudar de "ir ao médico fazer exames apenas quando lembrar" para "a empresa agendar exames periódicos para todos os funcionários". A revisão manual depende de você lembrar de solicitar — o que frequentemente cai no esquecimento; a revisão automática integra isso ao fluxo de trabalho, sendo acionada automaticamente no momento certo, sem depender da sua iniciativa. Trata-se de confiar tarefas fáceis de esquecer a um mecanismo estruturado, em vez de depender da memória.

Como ativar? A documentação oficial explica claramente:

Se você deseja que o Codex revise automaticamente cada PR, ative as Automatic reviews nas configurações do Codex. Dessa forma, sempre que um novo PR for aberto para revisão, o Codex enviará uma revisão, sem a necessidade de um comentário @codex review.

O caminho para configuração envolve apenas duas etapas (a página de configurações fica no Codex em chatgpt.com, não no GitHub):

1. Acesse a página de configurações do Codex em chatgpt.com (endereço oficial: https://chatgpt.com/codex/settings/code-review; caso o link mude, procure por Code review em chatgpt.com → Codex → Settings).
2. Ative a opção Automatic reviews.

Após a ativação, assim que um novo PR for aberto, o Codex iniciará a análise automaticamente, sem que você ou seus colegas precisem lembrar de mencioná-lo.

Quando usar a revisão manual e quando usar a automática? A divisão que adotei no meu dia a dia é:

• Repositórios principais da equipe com alta colaboração → Ativar a revisão automática. Ele funciona como uma "primeira barreira" constante, revisando cada PR assim que é criado.
• Projetos pessoais menores ou alterações pontuais → Usar apenas o comando manual @codex review, sem necessidade de acioná-lo a cada pequeno commit.
• Grandes alterações ou foco em aspectos específicos → Mesmo com a revisão automática activa, você pode enviar um comentário manual com foco específico (como @codex review for security regressions, detalhado na próxima seção) para que ele realize outra análise sob uma perspectiva diferente.

Comparativo	Manual @codex review	Revisão Automática
Método de acionamento	Menção manual com @ em cada comentário	Acionamento automático ao abrir o PR
Risco de esquecimento	Depende da memória, fácil de esquecer	Garantido pelo fluxo, impossível de esquecer
Cenários indicados	Projetos pessoais, alterações pequenas ou pontuais	Repositórios da equipe, onde todo PR exige revisão
Nível de controle	Analisa apenas sob demanda, permitindo focar em pontos específicos	Cobertura total, sem esforço manual

💡 Resumo em uma frase: Revisão automática significa ativar Automatic reviews nas configurações do Codex; ela é acionada assim que um novo PR é aberto, sem depender da sua memória para fazer a menção @; recomendo ativá-la nos repositórios principais da equipe e usar o comando manual em projetos menores.

---

04 Personalizando as regras de revisão: Escrevendo suas diretrizes no AGENTS.md

A esta altura, você deve estar se perguntando: quem define os "critérios" de revisão? Por padrão, ele adota padrões gerais de qualidade de código; no entanto, você pode usar o AGENTS.md para especificar os pontos críticos do seu repositório.

Conforme explicado no artigo [11 AGENTS.md], o arquivo AGENTS.md é a "lista de diretrizes do projeto" que o Codex lê sempre que começa a trabalhar. As regras de revisão ficam em uma seção dedicada, usando o cabeçalho padronizado Review guidelines.

Analogia: Entregar a um inspetor de qualidade uma lista com os itens específicos que a fábrica exige. Padrões gerais de qualidade são fáceis de seguir (verificar se os parafusos estão firmes ou se a estrutura tem rachaduras), mas sua linha de produção pode ter requisitos específicos — como "este lote será exportado para a União Europeia, então a certificação ambiental é obrigatória". Ao listar esses pontos em um quadro na parede, o inspetor passará a dar atenção especial a eles. O bloco Review guidelines no AGENTS.md atua exatamente como essa "lista de verificação do repositório".

Exemplo oficial para adicionar no arquivo AGENTS.md na raiz do repositório:

## Review guidelines

- Don't log PII.
- Verify that authentication middleware wraps every route.

Essas duas regras significam: "Não registre dados de identificação pessoal (PII) nos logs" e "Verifique se o middleware de autenticação envolve todas as rotas". Uma vez configuradas, o Codex prestará atenção extra a esses pontos em cada revisão.

Existe um mecanismo inteligente e alinhado com o princípio de proximidade detalhado no artigo [11] — conforme a documentação oficial:

O Codex aplica as diretrizes do arquivo AGENTS.md mais próximo de cada arquivo alterado. Você pode incluir instruções mais específicas em diretórios mais profundos da estrutura de pastas quando determinados pacotes exigirem um controle mais rígido.

Isso significa que você não precisa acumular todas as regras no arquivo da raiz. Se o módulo de pagamentos exige validações rigorosas, basta criar um arquivo em src/payment/AGENTS.md. Ao alterar o código dessa pasta, a regra específica será aplicada automaticamente. Essa abordagem segue o mesmo princípio de "sobreposição por proximidade" visto no artigo [11], e funciona perfeitamente para revisões de código.

Exemplo de configuração que costumo adotar em src/payment/AGENTS.md:

## Review guidelines

- 校验金额必须用 Decimal，禁止用 float 做钱的运算。
- 每一笔扣款都要有幂等键，防重复回调。

Dessa forma, quando o Codex revisar alterações relacionadas a pagamentos, ele focará especificamente nessas duas regras — se a falha de "ausência de validação de idempotência" mencionada na seção anterior estivesse documentada ali, ele a teria identificado de maneira muito mais ativa.

Há também uma alternativa mais direta: definir um foco temporário de revisão. Se você não quiser modificar o AGENTS.md e precisar apenas que um PR específico seja analisado sob uma perspectiva diferente, basta informar diretamente no comentário:

@codex review for security regressions

Let's double check if there are other rules. Yes, "Trate erros de digitação em docs como P1" (Treat typos in docs as P1.)

Isso instrui: "Desta vez, foque especificamente em regressões de segurança". A documentação oficial traz outro exemplo: se quiser que ele identifique erros de digitação na documentação, você pode adicionar a regra "Trate erros de digitação em docs como P1" (Treat typos in docs as P1.) no seu AGENTS.md — se você definir que é P1, ele reportará como P1.

💡 Resumo em uma frase: As regras de revisão são salvas na seção Review guidelines do arquivo AGENTS.md (como não gravar logs, exigir autenticação de rotas...); o princípio de proximidade permite definir regras mais rígidas para módulos sensíveis como pagamentos; para mudar o foco temporariamente, basta comentar @codex review for xxx.

---

05 Corrigindo diretamente: @codex fix e até onde ele pode atuar

O Codex terminou a revisão e marcou um problema P1 no PR. O que fazer a seguir? Você pode enviar outro comentário solicitando que ele corrija o problema diretamente — e a alteração será enviada de volta para a branch do PR.

Analogia: O editor que não apenas marca os erros graves, mas também reescreve o texto e o insere de volta no rascunho. Geralmente, um editor apenas assinala e escreve uma observação para você mesmo corrigir; o Codex pode ir além — se você disser "corrija isso para mim", ele fará a alteração e atualizará o arquivo. No entanto, observe que para ele alterar o código, você precisa conceder a permissão necessária.

Exemplo de uso oficial, adicionando um novo comentário no PR:

@codex fix the P1 issue

A documentação oficial descreve o comportamento da seguinte forma:

O Codex usa este PR como contexto para iniciar uma tarefa na nuvem e, quando tiver permissão, pode enviar as correções de volta para a branch.

Ao analisar esta frase, identificamos dois pontos cruciais, ambos alinhados com as diretrizes de segurança que seguimos:

Primeiro, o comando @codex fix inicia uma tarefa na nuvem. Ele não realiza a alteração diretamente no comentário; em vez disso, ele inicia uma tarefa do Codex cloud (explicada no artigo [10]), usando o PR como contexto e seguindo o ciclo de desenvolvimento (planejar -> executar -> validar) para alterar e testar o código.

Segundo, "quando tiver permissão" é a parte mais importante. A capacidade de enviar as alterações para a sua branch depende do nível de acesso concedido ao Codex. Como enfatizado nos artigos [15 Permissões] e [16 Segurança]: a capacidade de alterar código é determinada pelas autorizações que você define, e não pela iniciativa da IA. Se você não conceder permissão de escrita, ele apenas apresentará as alterações sugeridas, sem conseguir enviá-las para a branch.

Aproveitando, um detalhe importante para não confundir: o comportamento muda de acordo com o que é escrito após @codex:

• @codex review → Executa o fluxo específico de revisão de código (apenas analisa, sem alterar arquivos).
• @codex + qualquer instrução exceto review (por exemplo, @codex fix the CI failures ou @codex adicione testes para esta rota) → Inicia uma tarefa geral na nuvem, usando o PR como contexto para executar a ação solicitada.

A documentação oficial explica claramente:

Se você comentar @codex seguido de qualquer conteúdo diferente de review, o Codex iniciará uma tarefa na nuvem usando seu PR como contexto.

Portanto, review funciona como uma palavra reservada para o fluxo de análise, enquanto as demais seguem para tarefas gerais de nuvem. Compreender essa diferença evita questionamentos sobre o motivo de @codex fix alterar arquivos em vez de apenas sugerir revisões.

Aqui preciso reforçar uma diretriz crucial alinhada ao nosso foco de segurança: usar @codex fix permite que a IA faça alterações diretas no repositório remoto — isso é muito prático, mas a decisão de conceder essa permissão e de aprovar a mesclagem das alterações sugeridas continua sob sua responsabilidade. Minha prática pessoal é: permitir que ele faça a correção e envie para uma branch temporária é aceitável, mas o processo de mesclagem com a branch principal (merge) deve ser sempre manual — seguindo o mesmo princípio de "ele executa na pista ao lado, você decide quando integrar" apresentado na seção sobre worktrees [25].

💡 Resumo em uma frase: Após a revisão, ao comentar @codex fix the P1 issue, ele inicia uma tarefa na nuvem para ajustar o código e envia a correção para a branch do PR se a permissão de escrita estiver ativa; lembre-se de que @codex review executa o fluxo de análise e @codex + outros termos inicia uma tarefa geral; por fim, a etapa final de merge deve ser sempre realizada por você.

Neste ponto, o fluxo de revisão integrado ao GitHub está completo, conforme ilustrado no diagrama a seguir:

Este diagrama conecta as seções 02 a 05 em um fluxo contínuo: assim que um PR é criado ou atualizado, ele pode ser acionado por um comentário @codex review ou disparado automaticamente pela revisão ativa; o Codex analisa o diff na nuvem com base no arquivo AGENTS.md mais próximo; em seguida, ele adiciona as observações nas lines correspondentes (focando apenas em P0/P1 no GitHub); ao solicitar @codex fix, o Codex realiza os ajustes e o ciclo reinicia com uma nova revisão.

---

06 Comando local /review: Autoinspeção no terminal antes de abrir o PR

As primeiras cinco seções focaram no GitHub. No entanto, existe uma etapa anterior muito prática: quando o código ainda não foi enviado e o PR não foi aberto, e você deseja fazer uma revisão prévia — é aqui que entra o /review local, sem a necessidade de acessar o GitHub.

Analogia: Corrigir os erros do rascunho com uma borracha antes de entregar o trabalho, em vez de esperar o professor rasurar a folha com caneta vermelha. Em vez de subir commits com falhas simples e acumular dezenas de observações de revisão (sejam humanas ou do @codex review), é melhor fazer uma autoinspeção local antes de abrir o PR e corrigir os problemas mais evidentes. Isso reduz drasticamente o retrabalho.

Para executar, basta rodar o comando abaixo durante uma sessão do Codex no terminal:

/review

De acordo com a documentação oficial, ao executar o comando, serão apresentadas algumas opções de revisão. O Codex ativará um revisor dedicado que analisará o diff selecionado e listará os problemas ordenados por prioridade — garantindo a integridade do seu espaço de trabalho, pois opera estritamente em modo de leitura. As opções disponíveis são:

• Review against a base branch (Comparar com uma branch base): Selecione uma branch local para que o Codex identifique o ponto de mesclagem, analise o diff correspondente e aponte os principais riscos antes de você abrir o PR.
• Review uncommitted changes (Revisar alterações não commitadas): Analisa arquivos em staging, fora do staging e não rastreados, permitindo corrigir inconsistências antes do commit.
• Review a commit (Revisar um commit específico): Apresenta os commits mais recentes para que o Codex avalie as alterações do SHA selecionado.
• Custom review instructions (Instruções personalizadas de revisão): Permite definir um comando específico (como "focar em regressões de acessibilidade") para direcionar o revisor.

Existe uma pequena configuração oficial importante: por padrão, o comando /review utiliza o modelo ativo na sessão atual; para usar um modelo mais avançado dedicado a revisões, você deve configurar o parâmetro review_model no arquivo config.toml. Geralmente uso um modelo mais rápido no dia a dia, mas para análises detalhadas como a revisão de código, vale a pena configurar um modelo dedicado com maior capacidade no review_model.

Adotei o /review local como uma etapa fixa antes de enviar alterações:

1. Após finalizar o código, rodo /review no terminal e escolho Review uncommitted changes para analisar as modificações locais.
2. Corrijo os pontos reportados diretamente na minha máquina local.
3. Após realizar os ajustes, faço o commit, push e abro o PR — dessa forma, quando o @codex review (ou a revisão automática) rodar no repositório, os apontamentos serão pontuais e realmente relevantes.

Uma autoinspeção local garante uma revisão muito mais limpa no repositório remoto. Utilizo esse fluxo e percebi que os apontamentos nos PRs foram reduzidos pela metade.

💡 Resumo em uma frase: O comando local /review serve como uma etapa de autoinspeção antes do PR — escolha uma das opções no terminal (alterações locais, comparar com branch, commit específico ou customizado) e receba a lista de problemas ordenada por prioridade em modo leitura; ajustar esses pontos localmente reduz as observações remotas; você pode definir um modelo dedicado para essa tarefa com o parâmetro review_model.

---

07 Configurando o gh: Permitindo que o Codex Desktop analise o contexto completo do PR

Caso você utilize o aplicativo Codex Desktop apresentado no artigo [07] (ou a extensão para IDE descrita no [09]), recomendo fortemente a instalação da ferramenta de linha de comando oficial do GitHub: o gh.

Analogia: Conceder ao seu assistente um crachá de acesso ao arquivo central. Sem isso, ele sabe que "existe um PR", mas não consegue consultar o histórico de discussões ou as notas de revisão (contexto do PR e comentários de revisores); ao fornecer a credencial (autenticação do gh), ele pode acessar e listar todo o histórico para você de forma imediata.

A documentação oficial explica claramente:

Instale a GitHub CLI (gh) e autentique-se usando gh auth login para que o Codex possa carregar o contexto do PR, os comentários de revisão e os arquivos modificados. Se o gh não estiver instalado ou autenticado, os detalhes do PR podem não ser exibidos na barra lateral ou no painel de revisão.

Em resumo: com o gh instalado e autenticado, a barra lateral do Codex Desktop exibirá o contexto do PR, os comentários dos revisores e os arquivos modificados, permitindo responder a eles na mesma interface; sem o gh, essas informações podem não aparecer.

Como instalar e se autenticar (detalhes por plataforma):

# macOS(Homebrew)
brew install gh

# Windows(winget)
winget install --id GitHub.cli

# 装完,任意平台都跑这句登录
gh auth login

ℹ️ O método de instalação no Linux varia de acordo com a distribuição (apt / dnf / pacman, etc.); consulte a documentação oficial da GitHub CLI para obter os comandos exatos. Após a instalação, execute gh auth login da mesma forma.

Após a autenticação, o fluxo recomendado oficial para realizar um ciclo completo de correção na mesma interface é:

1. Abra o painel de revisão na branch do PR.
2. Analise o contexto do PR, os comentários e os arquivos alterados.
3. Solicite ao Codex que trate os comentários selecionados.
4. Valide o diff gerado no painel de revisão.
5. Assim que estiver pronto, adicione ao stage, faça o commit e o push de volta para a branch do PR.

Observe a etapa 5: "Assim que estiver pronto, faça o push". Novamente, mantemos o controle. A IA auxilia na leitura e nas alterações, mas a ação final de enviar as modificações de volta permanece em suas mãos conforme o fluxo oficial.

Deixamos aqui um alerta de segurança, alinhado com o conceito de injeção de prompt discutido no artigo [16]: comentários de PR, observações de revisores e issues vinculadas são "conteúdos externos" que, em tese, podem conter instruções maliciosas direcionadas à IA. Portanto, embora seja útil permitir que ela analise e responda aos comentários, evite instruí-la a "aplicar tudo de forma totalmente automatizada e enviar diretamente" — especialmente se surgirem comentários solicitando a execução de comandos ou acessos a URLs que fujam de uma revisão de código padrão. Nesses casos, faça uma validação manual.

💡 Resumo em uma frase: Para gerenciar PRs via app Desktop ou IDE, instale o gh e execute gh auth login — ele funciona como a credencial de acesso do Codex para ler o contexto do PR, comentários e arquivos modificados; a ação final de push também permanece sob seu controle direto; mantenha-se atento a possíveis injeções de prompt em comentários externos.

---

08 Protegendo a linha vermelha: Jamais permita que uma IA realize "merge" ou "force-push" por você

Até aqui apresentamos diversos fluxos que podem ser delegados com segurança; esta seção foca especificamente na linha que você deve proteger — um conceito discutido nos artigos [15 Permissões] e [16 Segurança] que deve ser seguido à risca no Git.

Analogia: O assistente pode revisar o contrato e propor ajustes até que esteja satisfatório, mas a assinatura final deve ser feita pelo representante legal. O trabalho de redação, alinhamentos e organização pode ser delegado; contudo, a assinatura torna o documento válido e irreversível — exigindo uma pessoa responsável pelas consequências. No Git, o ato equivalente a assinar o contrato é o merge com a branch principal e o envio forçado (force-push) para o repositório remoto.

Por que especificamente esses dois comandos? A tabela abaixo explica a diferença:

Operação	É reversível em caso de erro?	Quem deve executar
@codex review / /review local	— (Modo leitura, sem alterações)	✅ Delegar com segurança
@codex fix enviado para a branch do PR	✅ Sim (a branch pode ser ajustada ou excluída)	✅ Delegar após autorização, sob sua validação
Mesclar o PR na branch principal (merge)	⚠️ Impacta toda a equipe, difícil de reverter	⚠️ Execução manual obrigatória
git push --force / Sobrescrever histórico remoto	❌ Risco de apagar commits de outros membros	❌ Linha vermelha, execução estritamente manual

Existem duas regras indispensáveis que sigo rigorosamente:

Primeira: O merge final deve ser manual. O Codex pode revisar, propor correções e enviar alterações para a branch do PR — ações que podem ser desfeitas facilmente (caso não esteja satisfatório, basta excluir a branch e reiniciar). Contudo, realizar o merge na branch principal significa integrar o código ao fluxo de produção de toda a equipe, exigindo que você avalie a necessidade e o momento correto de integração.

Segunda: O force-push jamais deve ser delegado a uma IA. O comando git push --force reescreve o histórico do repositório e pode apagar commits de outros desenvolvedores, sendo uma ação crítica. Esse comando deve ser executado exclusivamente por você, validando sempre a branch de destino. Presenciei uma situação crítica no ano passado onde um script de automação executou um force-push incorreto e removeu todo o trabalho de uma manhã de um colega. Evite dar margem para que esse tipo de situação ocorra por automação.

Lembra-se do que discutimos no artigo [15]? O comando codex exec é executado por padrão em um sandbox read-only (somente leitura) — isso não se deve a limitações técnicas, mas ao princípio de manter a área de atuação da IA o mais restrita possível, exigindo o parâmetro explícito --sandbox workspace-write para liberações de escrita. Essa filosofia de design, que restringe permissões por padrão e exige liberações conscientes, segue a mesma premissa de manter o merge e o force-push estritamente manuais: quanto mais crítica e difícil de reverter for uma ação, mais necessária é a intervenção humana consciente.

💡 Resumo em uma frase: Fluxos reversíveis como review, fix e push para a branch do PR podem ser delegados; contudo, a mesclagem final (merge) e ações de force-push devem ser manuais (verificando sempre a branch correspondente) — ações irreversíveis exigem confirmação humana direta, alinhando-se ao princípio de restrição padrão do codex exec.

---

09 Mapa mental: O Codex como revisor, você como aprovador

Conectando os conceitos anteriores, o fluxo de trabalho pode ser resumido no seguinte mapa mental — o Codex atua como revisor e assistente de correção no fluxo do GitHub, enquanto você gerencia a aprovação final (merge).

Essa imagem representa a linha de colaboração de um PR: autoinspeção local com o comando /review (modo de leitura, em verde) -> execução em nuvem com @codex review sinalizando problemas P0/P1 no PR (com ciclos de ajuste e revisão) -> a etapa final e crítica de mesclagem na branch principal (merge e force-push, em vermelho) permanece estritamente sob seu controle.

Seguir esse modelo mental ajuda a manter o equilíbrio: evita que você faça todas as revisões manuais por receio de falhas (desperdiçando o ganho de produtividade da ferramenta), e impede que delegue merges e force-pushes de forma automatizada (o que traria problemas graves a longo prazo). O revisor analisa o código, e o responsável valida a aprovação.

💡 Resumo em uma frase: Enxergue o Codex como seu revisor e assistente de desenvolvimento no GitHub — ele gerencia o /review local, as análises de @codex review e correções com @codex fix; cabe a você proteger a etapa final de merge e force-push. Evite sobrecarregar-se fazendo tudo sozinho, mas não delegue decisões críticas.

---

10 Atividade prática: Executando uma autoinspeção com /review local

A revisão acionada via GitHub depende de acesso à cloud e autorização do repositório, o que dificulta demonstrações em ambientes isolados. No entanto, o comando /review local não possui dependências adicionais, sendo ideal para validar o fluxo de autoinspeção. O exemplo a seguir roda exclusivamente em sua máquina local de forma segura (somente leitura).

Etapa 1: Criar um repositório git temporário (no terminal padrão, fora da sessão do Codex)

mkdir review-demo && cd review-demo
git init
printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n' > app.py
git add app.py && git commit -m "feat: 初始 get_user"

Resultado esperado: O comando git init inicializa o repositório e o commit retorna uma linha semelhante a [main (root-commit) xxxxxxx] feat: 初始 get_user, seguida de 1 file changed, ... (a formatação exata depende da versão do git instalada). Observe que introduzimos intencionalmente uma injeção de SQL (concatenação direta de string na query) em app.py — avaliaremos se o Codex consegue identificá-la.

Etapa 2: Simular uma nova alteração (mantendo-a sem commit para a análise)

printf 'def get_user(uid):\n    return db.query("SELECT * FROM users WHERE id=" + uid)\n\ndef delete_user(uid):\n    db.execute("DELETE FROM users WHERE id=" + uid)\n' > app.py

Resultado esperado: Execução sem erros. O espaço de trabalho agora possui uma modificação ("inclusão da função delete_user"), não adicionada ao staging e sem commit, ideal para testar a revisão de alterações não commitadas.

Etapa 3: Iniciar a sessão do Codex e executar o /review

codex

Após acessar, execute:

/review

Resultado esperado: O menu de opções de revisão será exibido; use as setas para selecionar Review uncommitted changes (Revisar alterações não commitadas) e pressione Enter.

Etapa 4: Analisar os retornos exibidos

Resultado esperado: O Codex ativa o revisor, analisa o diff atual e apresenta os apontamentos no painel ordenados por prioridade. Ele deve identificar o risco de SQL Injection no método delete_user (gerado pela concatenação de uid), sinalizando como alta prioridade e recomendando o uso de consultas parametrizadas. A correta identificação do problema confirma que o Codex interpretou o código alterado com precisão. Note também que o arquivo app.py não foi modificado — o comando /review opera em modo somente leitura.

ℹ️ A quantidade exata de retornos, a redação e a sinalização da primeira linha de injeção dependem da análise do modelo no momento da execução; o ponto principal a ser validado é que ele aponte a falha de SQL Injection sem modificar seus arquivos locais.

Etapa 5: Limpeza (Opcional)

cd .. && rm -rf review-demo

Ao concluir essas etapas, você executou o fluxo prático de autoinspeção local com o comando /review antes de abrir um PR. Posteriormente, em cenários reais integrados ao Codex cloud, você poderá ajustar os pontos reportados localmente antes de realizar o push e acionar o @codex review — a combinação de autoinspeção local com revisão remota forma o fluxo de trabalho ideal discutido neste artigo.

💡 Resumo em uma frase: O roteiro prático consiste em 5 etapas — inicializar o repositório local (com falha de SQL Injection) -> gerar alterações locais -> rodar /review selecionando alterações não salvas -> verificar a injeção reportada sem alterações físicas de arquivos -> limpar os arquivos; um fluxo local e em modo de leitura para validar a autoinspeção.

---

11 Resumo

Este artigo detalhou a integração do Codex com fluxos Git e GitHub — a premissa central não reside na quantidade de linhas analisadas, mas na clara separação entre as duas abordagens de revisão e no respeito às ações críticas (linhas vermelhas).

Recapitulando os pontos centrais:

Objetivo	Como acionar no Codex	Ponto crítico
Revisar um PR	Adicione o comentário @codex review no PR	Processado na nuvem, foca em P0/P1, adiciona observações como revisor
Automatizar a revisão de PRs	Ative as Automatic reviews nas configurações	Fluxo garantido por sistema, recomendado em repositórios da equipe
Personalizar diretrizes	Adicione no bloco Review guidelines do AGENTS.md	Princípio de proximidade, permitindo regras específicas por diretório
Corrigir direto no PR	Comente @codex fix the P1 issue	Inicia uma tarefa na nuvem e envia o push se houver permissão de escrita
Autoinspeção local	Execute /review e escolha a opção correspondente	Modo leitura, otimiza o código localmente antes do push remoto
Exibir contexto no Desktop	Instale o gh e execute gh auth login	Sem isso, dados e comentários do PR podem não ser listados
Proteger ações críticas	Faça merges e force-pushes manualmente	Ações irreversíveis exigem validação manual, seguindo o padrão read-only

Agora você deve ser capaz de:

• Diferenciar os dois fluxos: revisão integrada via GitHub @codex review (processamento em nuvem, publicado no PR, exige conexão cloud e ativação da chave) e inspeção local com /review (executado em sua máquina, somente leitura, pronto para uso).
• No GitHub: realizar menção manual com @codex review, configurar Automatic reviews para automatizar o fluxo, definir regras no bloco Review guidelines do AGENTS.md e solicitar correções com @codex fix; autenticar com gh para exibir dados de PR no Desktop.
• Localmente: rodar o comando /review no repositório temporário seguindo as etapas práticas para validar o fluxo de autoinspeção.
• Proteger a etapa de homologação: manter o merge final e force-push estritamente manuais — aproveitando a produtividade da automação sem perder a governança do código.

Retornando ao cenário inicial — a fila de espera por revisões manuais costuma atrasar entregas, e a avaliação humana está sujeita a cansaço e falhas em riscos complexos. Delegar essa validação inicial ao Codex garante avaliações focadas em alta prioridade seguindo suas regras, otimizando o tempo de entrega; alimm do que, manter as decisões críticas sob sua validação traz segurança ao processo. Essa divisão de responsabilidades desenha a colaboração mais eficiente entre humanos e IA no Git.

---

O próximo artigo 27 · Automação e CI/CD levará essa integração para o próximo nível. Enquanto as revisões aqui dependem de acionamento manual ou eventos de PR no GitHub, o próximo passo apresentará o conceito "sem supervisão": usar codex exec para integrar o Codex diretamente em pipelines do GitHub Actions, permitindo que ele trate falhas de CI de forma autônoma, suba correções e abra PRs sem intervenção humana. Imagine ter falhas de build corrigidas de forma preventiva durante a noite, deixando apenas a revisão e o merge pendentes para o seu início de expediente. Isso representa um novo nível de produtividade colaborativa.

---

Leituras recomendadas

• Agent Skills: Empacotando rotinas de trabalho para ensinar o Codex a executar tarefas de forma autônoma
• Prática integrada: Adicionando recursos e realizando commits em uma ferramenta de TODO do zero
• Extensões de IDE (VS Code, etc.)