Claude Code e Codex no mesmo time: o que padronizar para o PR não virar bagunça?

Metade do time roda Claude Code, a outra metade roda Codex, e o PR chega com padrão de commit, tamanho e cobertura de teste diferentes na mesma semana

Se liga na cena: um dev pediu um ajuste pequeno e veio um diff de meio módulo, outro mandou commit com mensagem inventada, e o terceiro abriu PR sem um teste sequer

Aí bate a tentação da decisão mais preguiçosa do mundo: "todo mundo usa a mesma ferramenta e acabou"

Só que o conflito aqui não é de ferramenta, é de INSTRUÇÃO

Cada CLI lê um arquivo diferente: o Codex lê AGENTS.md, o Claude Code lê CLAUDE.md

O time até tem regra escrita, mas ela mora em dois lugares que ninguém sincroniza, e em uma semana os dois arquivos já divergiram

Então bora fazer o corte que importa: o que precisa ser IGUAL dentro do repositório, e o que pode continuar sendo gosto de cada dev na estação dele

Claude Code e Codex: o mapa de equivalências que o líder precisa ter na mão

Antes de padronizar qualquer coisa, você precisa reconhecer as mesmas peças dos dois lados

É tipo quando você troca de gerenciador de pacote: se você já conhece npm ou composer, o outro parece estranho por dez minutos e depois cai a ficha de que é o mesmo conceito com outro nome

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

A leitura da tabela é essa: os nomes mudam, o conceito é o mesmo

Tem arquivo de instrução, tem hook, tem review no PR e tem action de CI dos dois lados

O que significa que dá pra padronizar o resultado sem impor a ferramenta 🙂

O que você precisa antes de padronizar

Checklist curto, tudo verificável antes de sair editando arquivo:

• acesso de escrita no repositório (o padrão vive versionado, não em print de Slack)
• Claude Code e Codex instalados nas máquinas de quem vai usar cada um, e se você ainda está resolvendo quantos assentos o time precisa, fecha isso antes de padronizar processo
• o projeto marcado como confiável no Codex: sem isso, as camadas .codex/ do projeto não carregam e os hooks locais do projeto são ignorados
• pra review automático no PR: o Codex cloud configurado com "Code review" habilitado no repositório pelas configurações do Codex, e o GitHub App do Claude instalado via /install-github-app

Tome cuidado com o item do projeto confiável

É o clássico "configurei tudo e nada rodou", quando na verdade a camada do projeto nem foi lida

Passo a passo: padronizando o repositório para os dois lados

A ordem aqui importa: primeiro a fonte única, depois quem lê ela, e só no fim quem cobra

1. Gere a base com /init em cada ferramenta e escolha o AGENTS.md como fonte única do padrão do time

# dentro do Codex
/init

# dentro do Claude Code
/init

O erro comum deste passo: sair dali com dois arquivos vivos, cada um com metade das regras

Em uma semana eles divergem e ninguém sabe qual manda

2. Crie o CLAUDE.md da raiz importando o AGENTS.md, e coloque abaixo do import só o que é exclusivo do Claude

@AGENTS.md

## Específico do Claude Code

Regras que só fazem sentido aqui ficam abaixo do import

O Claude carrega o arquivo importado no início da sessão e depois anexa o restante do CLAUDE.md, então o padrão comum entra primeiro e o resto complementa

O erro comum deste passo: apostar em symlink

Ele funciona quando você não precisa adicionar conteúdo específico do Claude, mas no Windows criar symlink exige privilégio de Administrador ou Modo Desenvolvedor, e por isso a documentação de memória do Claude Code orienta usar o import @AGENTS.md

3. Escreva no AGENTS.md exatamente as regras que aparecem no PR: padrão de commit, comando de teste e escopo da mudança

## Padrão de commit

Use o padrão de commit adotado pelo time, com escopo no início da mensagem

## Testes

Rode o comando de teste do projeto antes de abrir o PR

## Escopo

Uma mudança por PR: nada de refatorar módulo vizinho no mesmo diff

O erro comum deste passo: transformar o arquivo em manifesto de 800 linhas

A documentação do Claude Code recomenda mirar em menos de 200 linhas por arquivo CLAUDE.md, porque arquivo longo consome mais contexto e derruba a aderência

E como o AGENTS.md entra expandido dentro do CLAUDE.md pelo import, o tamanho dele cai na mesma conta: a régua é do conjunto, não de um arquivo só

E tem a pegadinha: quebrar em imports ajuda a ORGANIZAR, mas não economiza contexto, já que os arquivos importados são expandidos e carregados no lançamento da sessão junto com o arquivo que referencia eles (com profundidade máxima de 5 saltos)

4. Adicione a seção de regras de review no AGENTS.md mais próximo do código

## Code Review Rules

Aponte PR sem teste para código novo

Aponte mudança fora do escopo descrito na descrição do PR

É dessa seção que o review do Codex no GitHub tira as regras, e ele usa o AGENTS.md mais próximo do código revisado

5. Isole exceção de time por subdiretório com AGENTS.override.md

services/payments/AGENTS.override.md

Quando um time precisa de regra diferente da raiz, é ali que ela vive

O erro comum deste passo: enfiar a exceção de um time no arquivo da raiz e transformar o padrão global em colcha de retalhos

6. Alinhe a atribuição do commit pela configuração attribution do Claude Code

É nela que você define os textos de commit e de pr e o sessionUrl

Por padrão os commits usam git trailers como Co-Authored-By, que dá pra personalizar ou desativar

O erro comum deste passo: mexer só no includeCoAuthoredBy e ficar sem entender por que o trailer continua aparecendo

O attribution tem precedência, e o includeCoAuthoredBy está depreciado

7. Feche o loop de qualidade com hook, pra regra ser cobrada na hora da edição e não só na revisão

No Claude Code, o evento PostToolUse com matcher Write|Edit em .claude/settings.json roda um comando (uso típico: o linter), o resultado volta como texto que o Claude lê, e o $CLAUDE_PROJECT_DIR aponta pra raiz do projeto

No Codex, o equivalente vem pelo arquivo hooks.json ou por tabelas de hooks inline no config.toml, com a mesma estrutura de eventos

O erro comum deste passo: esperar que o PostToolUse desfaça a ação

Ele não desfaz, porque a ferramenta já executou: o que ele faz é devolver o problema pro agente resolver

8. Leve a mesma régua pro CI e pro PR

- uses: openai/codex-action@v1
  with:
    prompt-file: .github/codex/prompts/review.md
    sandbox: read-only

A action instala o Codex CLI e roda codex exec com as permissões definidas, aceita prompt ou prompt-file (um dos dois), além de model, effort e sandbox, e a documentação sugere guardar os prompts em .github/codex/prompts/

No PR, você chama @claude no comentário pelo lado do Claude Code (a action oficial é anthropics/claude-code-action) e @codex review pelo lado do Codex, ou liga o Automatic reviews pra todo PR novo

Onde a padronização aperta e onde ela pode soltar

Padronizar tudo mata a produtividade, padronizar nada gera o PR bagunçado

Então vamos aos três cenários que todo líder reconhece

Monorepo com times de regras diferentes:

O time de pagamentos não escreve código igual ao time do front, e forçar isso na raiz é receita de arquivo gigante que ninguém segue

A saída é o escopo por diretório: AGENTS.md dentro do subdiretório vale só ali, e o AGENTS.override.md (exemplo: services/payments/) sobrescreve quando a regra do time é realmente outra

A raiz continua magra, do jeito que a régua de menos de 200 linhas pede

PR que chega grande demais ou sem teste:

Aqui a regra escrita no AGENTS.md faz metade do trabalho, e o review automático faz a outra metade

Um detalhe que ajuda a acalmar o time: no GitHub, o Codex sinaliza apenas problemas P0 e P1, pra manter os comentários focados em risco alto

Ou seja, gosto pessoal de nomenclatura nem vira comentário no PR, e isso já mata metade das brigas de revisão 😀

O dev que quer manter o próprio setup:

Esse é o ponto onde você SOLTA

No Codex, o dev configura o sandbox_mode (read-only, workspace-write ou danger-full-access) e a approval_policy (untrusted, on-request ou never) nos padrões pessoais dele em ~/.codex/config.toml, checa a sessão com /status e ajusta o que a ferramenta pode fazer com /permissions

O corte é esse, e vale escrever no canal do time: o que o revisor VÊ NO DIFF é do repositório, o que é da estação fica com o dev

Quem prefere aprovar cada passo e quem prefere deixar rodar solto podem conviver, desde que o commit, o teste e o escopo cheguem iguais

Conclusão

O padrão do time não vive no decreto do líder, vive no AGENTS.md

Ele chega no Claude Code pelo import @AGENTS.md dentro do CLAUDE.md da raiz, e é cobrado por hook na hora da edição e por review no PR

E tem um argumento a mais pra apostar nesse formato: o AGENTS.md é um dos projetos fundadores da Agentic AI Foundation, fundo dirigido sob a Linux Foundation, ao lado do Model Context Protocol e do goose

Mais de 60.000 projetos open source e frameworks de agentes já adotaram o formato desde o lançamento, incluindo Amp, Codex, Cursor, Devin, Factory, Gemini CLI, GitHub Copilot, Jules e VS Code

A fundação chegou a 190 organizações membro em maio de 2026, depois da entrada de 43 novos membros

Traduzindo pro seu caso: padronizar nesse arquivo não amarra o time a uma ferramenta só, e é justamente isso que você queria

Próximo passo, e dá pra fazer hoje: roda o /init, move as regras pra um AGENTS.md enxuto e abre um PR de teste com um dev de cada lado, só pra ver o que ainda diverge

O que sobrar de divergência é exatamente o que faltava escrever…

até o próximo post!