Claude Code e Codex no Mesmo Repositório: Minha Configuração Real

Claude Code e Codex no Mesmo Repositório: Minha Configuração Real

Eu costumava ser um fiel seguidor do Claude Code. Não de forma tribal — mais no sentido de "este é o agente em que confio, este é o que ajustei, a memória muscular já está construída". A Anthropic lançava uma atualização, eu instalava. A Anthropic tinha uma queda, eu esperava. A ideia de rodar um segundo CLI em paralelo parecia como trair uma ferramenta que tinha conquistado meu fluxo de trabalho.

Então, no mês passado, numa quarta-feira à tarde, a página de status da API do Claude ficou laranja. Depois vermelha. Aria — minha agente de conteúdo — estava na metade de um lote de quatro publicações. Fiquei sentado lá por 47 minutos vendo o spinner girar. Quando a API voltou, eu tinha perdido a manhã e a paciência para continuar sendo um engenheiro de CLI único.

Então fiz o que vinha evitando. Abri um segundo painel de terminal, executei codex no mesmo repositório, e comecei a me ensinar como realmente viver em ambos os ecossistemas ao mesmo tempo. Não a versão de marketing onde você "compara" as duas ferramentas e escolhe um vencedor. A versão chata e granular onde você roda ambas, na mesma base de código, com o mesmo contexto de projeto, com skills que funcionam na maioria em qualquer um dos CLIs, e um truque de transferência de sessão que permite passar trabalho entre eles quando um fica travado.

É sobre isso que este artigo trata. Não "Claude Code vs Codex." É "Claude Code e Codex, na mesma pasta de projeto, com um cérebro compartilhado e um skill de transferência que sobrevive a quedas." Estou rodando essa configuração há cerca de seis semanas. As primeiras três semanas foram difíceis. As últimas três foram o ambiente de desenvolvimento mais resiliente que já tive.

Deixe-me guiá-lo exatamente por como está conectado.

Por Que Parei de Escolher Lados Entre Claude Code e Codex

Antes da configuração, uma breve palavra sobre a mudança de mentalidade — porque a fiação só importa se a filosofia por trás estiver correta.

Durante a maior parte de 2025, a conversa sobre agentes CLI era tribal. Você era uma pessoa do Claude Code, ou do Codex, ou do Cursor, ou do Gemini CLI. As razões eram reais: cada ferramenta tinha ergonomia diferente, comportamento de modelo diferente, arquivos de configuração diferentes, e trocar custava tempo real. Escolher uma e se aprofundar fazia sentido.

Duas coisas mudaram para mim em 2026.

A primeira foram as quedas. Não é culpa da Anthropic especificamente — todo grande provedor de modelos teve pelo menos um dia ruim este ano. A OpenAI teve um incidente de várias horas em fevereiro. A Anthropic teve o engasgo de API que mencionei acima. O lado do Gemini do Google teve um bug de roteamento de modelo em março que degradou silenciosamente as respostas por horas antes de alguém perceber. Se todo o seu fluxo de trabalho depende de um único provedor, uma queda leva seu dia inteiro. Isso não é um problema de tecnologia — é um problema de ponto único de falha.

A segunda foi a estagnação. Às vezes o Claude Code trava. Não "quebrado" — criativamente travado. Ele escolhe uma abordagem, segue com ela, e quando essa abordagem não funciona, continua refinando a mesma abordagem com mais força. Já vi o Opus gastar 40 minutos tentando tornar um teste instável confiável adicionando retentativas quando a correção real era reescrever o teste em um estilo diferente. Um segundo agente — não como substituto, mas como uma segunda opinião — geralmente quebra a estagnação em um único prompt. Trocar de CLI é a forma mais barata que encontrei para obter uma perspectiva fresca do modelo sem perder o contexto do projeto.

Então o objetivo não é "escolher o melhor CLI." O objetivo é o agnosticismo de ferramentas: construir uma configuração onde Claude Code e Codex possam trabalhar na mesma base de código, com o mesmo conhecimento do projeto, e você possa se mover entre eles sem perder sua posição. O CLI se torna intercambiável. O contexto do projeto é o que é sagrado. Este é o mesmo instinto sobre o qual escrevi no meu fluxo de trabalho de dois agentes supervisor-construtor, levado mais longe: não apenas dois agentes, mas dois CLIs inteiros tratados como intercambiáveis.

Agora, a fiação.

O Cérebro Compartilhado: CLAUDE.md e AGENTS.md Contêm (Quase) a Mesma Coisa

A primeira coisa que aprendi quando comecei seriamente a rodar ambos os agentes no mesmo repositório é isto: os dois ecossistemas já concordam mais do que o marketing sugere. Tanto o Claude Code quanto o Codex leem um arquivo markdown no nível do projeto ao iniciar. O Claude Code lê CLAUDE.md. O Codex lê AGENTS.md. Os conteúdos são quase intercambiáveis. O formato é markdown simples. A intenção é a mesma: dizer ao agente o que é este projeto, quais são as convenções, quais ferramentas usar, quais testes executar, e o que não tocar.

Quando configurei pela primeira vez o fluxo de trabalho em paralelo, cometi o erro de novato de escrever dois arquivos separados e mantê-los sincronizados manualmente. Isso durou cerca de quatro dias antes que a divergência fizesse os agentes discordarem em coisas básicas — o Codex achava que estávamos usando pnpm, o Claude Code achava que estávamos usando npm, e o acaso determinava qual estava certo em qualquer momento.

A solução é um de dois padrões, e ambos funcionam:

Padrão A — Link simbólico de um para o outro. Escolha o arquivo que quer como fonte de verdade (eu escolhi AGENTS.md porque está se tornando o padrão multi-fornecedor) e crie um link simbólico do outro:

# da raiz do projeto, com AGENTS.md como canônico
mv CLAUDE.md AGENTS.md   # se você está começando do CLAUDE.md
ln -s AGENTS.md CLAUDE.md

Agora ambos os agentes leem o mesmo arquivo. Edite AGENTS.md, ambos os CLIs veem a atualização no próximo início. Isso é o que o guia de migração do Onur Solmaz recomenda e o que eu uso na maioria dos meus repositórios.

Padrão B — Mantê-los separados mas forçar sincronização. Se você quer que cada arquivo tenha algumas linhas específicas da ferramenta (alguns skills se comportam diferente em um vs outro), mantenha ambos os arquivos e escreva um hook de pre-commit que compare a seção compartilhada e avise se divergiram. Isso é mais pesado, mas permite ter um bloco # Específico do Claude Code no final de um e não do outro.

Comecei com o Padrão B e migrei tudo para o Padrão A em duas semanas. O custo de manutenção de manter dois arquivos sincronizados era maior que o valor de ter algumas linhas específicas por ferramenta.

Qualquer que seja o padrão que escolha, aqui está o que realmente deveria viver nesse arquivo compartilhado. Esta é a seção do meu AGENTS.md real para o repositório onde escrevo todo este conteúdo:

# Project: my-ai-crew

## What this is
Multi-brand content generation system. Four brands, each with a distinct
voice. Posts are saved to content/{brand}/[slug].md. No build system,
no tests — the workflow is agent-driven.

## Conventions
- All article files start with `**BRAND:**` — never YAML frontmatter.
- META DESCRIPTION must be 150-160 characters. Count before saving.
- Word count floor: 3,000.
- Brand voices are defined in .claude/agents/aria.md (do not edit
  without explicit instruction).

## Tools available
- WebSearch — use for fact verification, never guess versions/pricing
- Glob — scan content/{brand}/*.md before writing
- Read, Write, Edit — standard file ops

## What NOT to do
- Don't run git commit unless explicitly asked.
- Don't add Co-Authored-By lines without instruction.
- Don't generate placeholder metrics — use real numbers or omit.

## Brand directories
- content/mejba.me/ — personal practitioner voice
- content/ramlit.com/ — agency, business-focused
- content/colorpark.io/ — design agency, opinionated
- content/xcybersecurity.io/ — security, authoritative

Ambos os CLIs leem isso. Ambos os agentes agora conhecem as convenções. A primeira vez que você escreve este arquivo corretamente é a primeira vez que sua configuração de dois CLIs se sente coerente em vez de esquizofrênica.

Há uma sutileza que vale a pena destacar. O Claude Code suporta arquivos CLAUDE.md aninhados em subdiretórios — quando o agente lê um arquivo em content/colorpark.io/, ele pode captar instruções adicionais de um CLAUDE.md colocado nessa subpasta. O Codex tem um mecanismo similar: quando você faz cd para um subdiretório, ele concatena os arquivos AGENTS.md da pasta atual até a raiz do repositório, com arquivos mais próximos sobrescrevendo os anteriores (isso está documentado no guia do AGENTS.md do Codex). Se você criar link simbólico na raiz, também pode fazê-lo no nível de subpasta. Ambos os ecossistemas vão se entender bem.

O Mapa de Arquivos e Pastas: Onde Cada CLI Procura

Uma vez que o cérebro compartilhado está conectado, a próxima pergunta é: onde fica todo o resto? Skills, agentes, configuração, comandos slash. Ambos os CLIs têm sua própria estrutura de pastas, e você precisa de um mapa mental.

Este é o que mantenho fixado nas minhas próprias notas:

Algumas observações sobre esta tabela porque me atrapalharam na primeira vez:

O formato de configuração é a maior diferença de formato. O Claude Code usa JSON para settings.json. O Codex usa TOML para config.toml. Se você nunca escreveu TOML, é algo entre YAML e INI — chaves, valores, seções entre colchetes. Não é difícil, mas você não pode colar seu settings.json no config.toml e esperar que algo funcione. A conversão é mecânica mas manual. (Ou, como mostrarei em um minuto, você pede ao Claude Code para fazer isso por você.)

Comandos slash e skills estão convergindo no Codex. A documentação oficial da OpenAI agora diz que prompts personalizados estão depreciados em favor de skills. Então em 2026, se você está escrevendo instruções reutilizáveis para o Codex, escreve como skills, não como prompts personalizados. O Claude Code ainda distingue entre comandos (em .claude/commands/) e skills (em .claude/skills/), mas a diferença está diminuindo. Ambos os ecossistemas estão chegando a "um skill é um arquivo markdown com frontmatter que descreve quando deve ser ativado." Boas notícias para portabilidade.

Sub-agentes divergem mais do que se esperaria. Os sub-agentes do Claude Code fazem auto-despacho — o agente principal lê as descrições de cada arquivo .claude/agents/*.md ao iniciar, e roteia o trabalho para eles quando uma tarefa corresponde. O Codex requer invocação explícita. Você pode construir agentes em .codex/agents/, mas o Codex não roteia automaticamente para eles; você diz ao Codex qual agente usar. Voltarei a essa diferença porque é o que mais muda como você trabalha.

Skills São Majoritariamente Portáveis. Agentes Precisam de uma Conversão.

A razão pela qual toda essa configuração funciona é que a maioria dos arquivos markdown em .claude/ e .codex/ são estruturalmente iguais. Um skill é uma pasta com um SKILL.md dentro. O SKILL.md tem frontmatter YAML com name e description, depois um corpo markdown com instruções. Essa especificação é a mesma em ambos os lados. O que significa que um skill que escrevi para o Claude Code se transfere para o Codex sem mudanças na maioria das vezes.

Testei isso diretamente. Meu skill caveman — o modo de comunicação ultra-comprimido que reduz o uso de tokens em ~75% (escrevi sobre construir o skill caveman para o Claude Code há um tempo) — foi originalmente escrito para o Claude Code. Copiei a pasta caveman/ de .claude/skills/ para .codex/skills/, reiniciei o Codex, e o skill ativou corretamente no primeiro prompt. Sem mudanças de formato. Sem reescritas de frontmatter. Simplesmente funcionou.

Os skills que não portam bem são os que referenciam nomes de ferramentas específicos do Claude Code. Se seu skill diz "use a ferramenta Glob" — o Codex não tem uma ferramenta chamada Glob. Ele tem acesso ao shell, então o agente ainda pode buscar arquivos via find ou ls, mas você precisará reescrever o skill para referenciar operações de shell ou aceitar que o skill funcionará menos confiavelmente. Cerca de 80% dos skills que migrei não precisaram de mudanças. Os outros 20% precisaram de edições leves nas referências de ferramentas.

Sub-agentes são onde a conversão fica séria. O frontmatter é similar (name, description, model, tools) mas o modelo de despacho é diferente — e isso muda como você escreve o corpo do agente. Um agente do Claude Code é escrito assumindo que será auto-invocado quando uma tarefa corresponder à sua descrição. Um agente do Codex é escrito assumindo que você o invocará explicitamente. Então:

• Descrições de agentes do Claude Code são escritas para o modelo despachante ler. Dizem "use este agente quando X for necessário" porque o agente principal precisa saber quando delegar.
• Descrições de agentes do Codex são escritas para o usuário humano ler. Dizem "este agente lida com X" porque o humano é quem roteia o trabalho.

Quando você migra um agente de um para o outro, não basta copiar o arquivo. Você reescreve a descrição da perspectiva correta. O corpo — o system prompt real — geralmente se transfere sem mudanças.

Esta é a maior diferença prática entre os dois ecossistemas, e é a razão pela qual rodo ambos lado a lado em vez de tratá-los como substituições diretas. O Claude Code é melhor em orquestração multi-agente porque o despacho é automático — cobri a mecânica de despacho em detalhe no meu guia de equipes de agentes do Claude Code. O Codex é melhor em uso controlado e determinístico de agentes porque você decide qual agente roda. Forças diferentes, mesmos blocos de construção.

O Prompt de Conversão que Colo no Claude Code para Inicializar o Codex

Quando inicio um novo repositório e quero ambos os CLIs prontos desde o primeiro dia, não converto nada manualmente. Escrevo a configuração do Claude Code primeiro (porque é onde está a memória muscular) e depois colo este prompt no Claude Code e deixo ele gerar o equivalente do Codex.

Este é o prompt real. Copie, cole no Claude Code, e ele fará a conversão para você:

I want this repo to work in both Claude Code and Codex CLI side by side.
Right now the Claude Code setup is complete. I need you to generate the
parallel Codex setup. Specifically:

1. Read CLAUDE.md and create AGENTS.md with the same content, then
   replace CLAUDE.md with a symlink to AGENTS.md. Use:
     mv CLAUDE.md CLAUDE.md.bak
     # copy CLAUDE.md.bak contents into AGENTS.md
     ln -s AGENTS.md CLAUDE.md
     rm CLAUDE.md.bak  (only after verifying the symlink works)

2. Read .claude/settings.json and create .codex/config.toml that mirrors
   the relevant settings. Convert JSON syntax to TOML. Skip any
   Claude-Code-specific keys that have no Codex equivalent (e.g.
   permissions, hooks) and add a comment listing what was skipped.

3. For each file in .claude/skills/<name>/SKILL.md, create
   .codex/skills/<name>/SKILL.md by copying the file. Check the body
   for any references to Claude-Code-specific tools (Glob, Read tool,
   etc) and either rewrite them as shell equivalents or flag them in a
   comment at the top of the file.

4. For each file in .claude/agents/<name>.md, do NOT auto-port to
   .codex/agents/. Instead, list the agents and ask me which ones I
   want available in Codex. For the ones I select, rewrite the
   description field to be human-routing-friendly (Codex requires
   explicit invocation, not auto-dispatch) and copy the body unchanged.

5. After all conversions, write a CONVERSION_LOG.md at the repo root
   that lists every file created or modified, every skipped key, and
   every tool reference that was rewritten. I want to be able to audit
   this in 30 seconds.

Do not commit anything. Just create the files and the log.

A primeira vez que executei isso, o Claude Code levou cerca de quatro minutos. A maior parte foi o agente lendo cada skill e decidindo se cada um tinha referências de ferramentas específicas do Claude Code. O log de conversão foi útil porque detectou dois skills que referenciavam a ferramenta Glob pelo nome — os reescrevi para usar find do shell em vez disso, e agora ambas as versões do skill funcionam nos seus respectivos CLIs sem mais mudanças.

Você também pode executar a conversão inversa, indo de uma configuração do Codex para uma do Claude Code. O prompt é simétrico — apenas inverta a origem e o destino. Normalmente tenho uma direção de conversão como o pipeline canônico de configuração e a outra como um bootstrap de uma única vez.

O Skill de Transferência de Sessão: Movendo Contexto Entre Agentes

Aqui está a parte de que ninguém fala: mesmo com um AGENTS.md compartilhado, os agentes em si não compartilham estado de conversação. Quando você troca do Claude Code para o Codex no meio de uma tarefa, o novo agente não sabe o que você estava fazendo. Ele conhece as convenções do projeto, mas não a intenção ativa.

Este é o momento onde a maioria desiste da configuração de CLI em paralelo. Experimentam por um dia, batem num muro de contexto ao trocar de ferramenta, e concluem que rodar ambos "não vale a pena." Não é verdade — mas só se você tiver uma transferência deliberada.

Construí um skill que resolve isso. Ele captura as quatro coisas que realmente importam ao transferir trabalho entre agentes: os arquivos ativos que você esteve tocando, a intenção atual (o que está tentando fazer), os bloqueadores (o que está travado ou falhou), e o próximo passo (o que o agente receptor deve fazer primeiro). Ele escreve esses quatro campos em um arquivo .handoff.md na raiz do repositório. O agente receptor lê esse arquivo no próximo prompt e sabe exatamente onde continuar.

Este é o skill real, que fica em .claude/skills/session-handoff/SKILL.md:

---
name: session-handoff
description: Capture the active session state into .handoff.md so another CLI agent (Codex, Gemini, etc.) can pick up the work. Use when the user says "handoff", "pass to codex", "switch agents", or "context for next agent".
allowed-tools: Read, Write, Bash
---

# Session Handoff

When this skill fires, write `.handoff.md` at the repo root with these
exact four sections. Be terse. The receiving agent reads this and
needs to act on it immediately.

## Format

```markdown
# Session Handoff — [ISO timestamp]
From: [claude-code | codex | other]

## Active files
- [path/to/file:line-range] — [one-line reason]
- [path/to/file] — [one-line reason]

## Current intent
[1-3 sentences: what we're trying to accomplish in this work session]

## Blockers
- [Specific thing that's stuck. Include error message if any.]
- [Or "none" if not stuck — just switching for fresh perspective.]

## Next step
[Exactly one sentence. The single action the receiving agent should
take first.]

Rules

• Do NOT include full file contents. Just paths and line ranges.
• Do NOT summarize the conversation. Capture state, not history.
• If .handoff.md already exists, overwrite it (no append).
• After writing, print "Handoff written to .handoff.md" and exit.
• The receiving agent should be told (by the human) to read .handoff.md as their first action.

O skill espelho em `.codex/skills/session-handoff/SKILL.md` é idêntico exceto por uma mudança — a descrição é reescrita porque o Codex não faz auto-despacho. A versão do Codex é mais como uma dica de uso do que um sinal de roteamento. A diferença em texto simples: a descrição do Claude Code diz "ative isso quando o usuário disser X." A do Codex diz "use este skill para escrever um arquivo de transferência."

Para ativar uma transferência no Claude Code, simplesmente digito "handoff to codex" — o skill detecta a palavra-chave e escreve o arquivo. Para ativá-lo no Codex, digito `$session-handoff` (a sintaxe de invocação explícita do Codex) e ele faz a mesma coisa. Depois troco de aba, e a primeira coisa que digo ao agente receptor é: "Leia .handoff.md e continue."

O arquivo de transferência geralmente tem entre 15 e 30 linhas. O agente receptor o lê, tem contexto completo em cinco segundos, e começa a trabalhar. Usei esse skill provavelmente 200 vezes nas últimas seis semanas. É a peça individual de cola que faz a configuração de CLI em paralelo parecer coerente em vez de fragmentada.

Se você construir apenas uma coisa de todo este artigo, construa este skill. É pequeno. Economiza horas. Se nunca construiu um skill de Claude Code do zero, meu [guia de skills avançados do Claude Code](https://www.mejba.me/blog/agent-skills-advanced-claude-code) explica o formato e as armadilhas.

## Como o Lado a Lado Realmente Se Parece: Painel Dividido no VS Code

A fiação acima é a configuração estática. Aqui está a dinâmica — como minha tela realmente se parece durante uma sessão de trabalho.

VS Code, painel de terminal dividido, orientação vertical. Painel esquerdo: Claude Code, rodando Opus 4.7, na raiz do projeto. Painel direito: Codex CLI, rodando GPT-5.4, mesma raiz de projeto. Ambos os agentes têm o mesmo `AGENTS.md`. Ambos têm acesso aos mesmos skills. Ambos podem editar os mesmos arquivos (se coordenam pelo sistema de arquivos, não por mensagens entre CLIs — git é a fonte de verdade sobre o estado do disco).

Por padrão uso Claude Code no início de qualquer sessão. É o agente que mais ajustei, e tem meu conjunto completo de sub-agentes de `.claude/agents/` disponíveis. Planejo, estruturo e faço os primeiros 60% das mudanças lá.

Troco para o Codex em cenários específicos:

**Claude Code fica travado numa abordagem.** Quarenta minutos depois, está girando na mesma ideia. Executo o skill de transferência, troco para o Codex, e peço para olhar o mesmo problema com olhos frescos. Cerca de 70% das vezes, o Codex escolhe um ângulo diferente e desbloqueia o trabalho. Nos 30% restantes, concorda com a abordagem do Claude Code mas sugere um ajuste específico que o faz funcionar. De qualquer forma, a estagnação se quebra.

**Trabalho de refatoração longo e mecânico.** O desempenho do Codex CLI em tarefas baseadas em terminal é genuinamente superior ao do Claude Code em tarefas rotineiras pesadas em shell, segundo a [comparação da DeployHQ 2026](https://www.deployhq.com/blog/comparing-claude-code-openai-codex-and-google-gemini-cli-which-ai-coding-assistant-is-right-for-your-deployment-workflow) (Codex CLI atingiu 77.3% no Terminal-Bench 2.0 vs 65.4% do Claude Code). Quando a tarefa é "renomear 30 variáveis em 12 arquivos seguindo este padrão" ou "rodar a suíte de testes, analisar as falhas, escrever correções," o Codex é mais rápido e usa menos tokens.

**A API do Claude está fora do ar.** Esta é a razão original pela qual construí a configuração em paralelo. Quando a Anthropic tem um incidente, mudo completamente para o painel do Codex e continuo trabalhando. Os skills se transferem. O contexto do projeto se transfere. A única coisa que perco é a agente Aria (porque Aria tem comportamento de sub-agente específico do Claude Code que não se traduz completamente), e normalmente não estava usando Aria para o trabalho que transfiro para o Codex de qualquer forma.

**Revisão adversarial.** Quando quero uma revisão de código que *não* seja do mesmo modelo que escreveu o código, faço o trabalho no Claude Code, depois peço ao Codex para revisar o diff. Linhagem de modelo diferente, dados de treinamento diferentes, pontos cegos diferentes. Detecto bugs dessa forma que nenhum agente encontra ao revisar seu próprio trabalho. Escrevi sobre este padrão extensamente no [artigo de revisão adversarial com plugin do Codex](https://www.mejba.me/blog/codex-plugin-claude-code-adversarial-review) — mesma ideia, integração mais estreita quando você quer.

O padrão que emergiu depois de algumas semanas: Claude Code é meu principal, Codex é meu paralelo. Estou no Claude Code 70-80% do tempo. Codex é 20-30%, mais 100% quando o Claude está fora do ar.

## Mantendo as Duas Configurações Sincronizadas (A Disciplina)

Todo o sistema quebra se as duas configurações divergirem. O modo de falha mais comum que vejo — incluindo na minha própria configuração, quando fico preguiçoso — é editar `CLAUDE.md` (que agora é o link simbólico) e acidentalmente escrever mudanças que só o Claude Code entende. Ou adicionar um novo skill a `.claude/skills/` e esquecer de replicá-lo em `.codex/skills/`. Duas semanas depois, você troca de CLI e descobre que metade das suas ferramentas está faltando.

A disciplina que realmente funciona para mim, depois de várias iterações:

**Edições ao arquivo canônico são sempre consideradas "agnósticas de ferramenta" por padrão.** Se estou escrevendo algo no `AGENTS.md` que só um CLI deveria saber, coloco numa seção claramente marcada no final: blocos `# Apenas Claude Code` e `# Apenas Codex`. Ambos os CLIs leem o arquivo inteiro, mas os cabeçalhos de seção me dizem (ao humano) quais linhas se aplicam onde. Reduz muito o trabalho de manutenção.

**Mudanças em skills passam por um script de sincronização.** Tenho um pequeno script de shell que copia arquivos novos ou modificados de `.claude/skills/` para `.codex/skills/` (e vice-versa), preservando qualquer sobrescrita de nomes de ferramentas que já tenha feito. Executo manualmente depois de editar qualquer skill, antes da próxima sessão. Cinco segundos de trabalho, previne a deriva lenta.

**Mudanças em sub-agentes não sincronizam automaticamente.** Deixo os agentes em `.claude/agents/` para uso do Claude Code, e só porto manualmente os que quero ativamente no Codex. A maioria dos meus agentes são exclusivos do Claude Code porque o comportamento de auto-despacho é todo o sentido de tê-los. Os dois ou três que porto para o Codex, mantenho sincronizados manualmente porque as descrições precisam ser diferentes de qualquer forma.

**Arquivos de configuração (`settings.json` e `config.toml`) nunca sincronizam automaticamente.** Divergem naturalmente porque expõem configurações diferentes. Os trato como independentes, e reviso cada um uma vez por mês para garantir que não introduzi uma discrepância de comportamento não intencional.

Essa é a carga operacional, honestamente. Cerca de dez minutos por semana de trabalho de sincronização explícito. Em troca, tenho dois CLIs que ambos conhecem meu projeto e ambos podem trabalhar nele de forma intercambiável.

## Quando a Configuração em Paralelo Não Vale a Pena

Estaria mentindo se dissesse que essa configuração é adequada para todos.

Se você é novo no Claude Code, não faça isso ainda. Ajuste o Claude Code primeiro. Escreva bem seu `CLAUDE.md`, construa um punhado de skills, acostume-se com como os sub-agentes funcionam. Adicionar o Codex no primeiro dia significa que está aprendendo dois CLIs ao mesmo tempo, e vai se confundir sobre qual comportamento vem de qual ferramenta. Escolha um, aprofunde-se, depois adicione o outro.

Se seu trabalho está majoritariamente dentro das ferramentas de um ecossistema — uso intensivo de Claude Skills, muitos servidores MCP conectados especificamente ao Claude, sub-agentes que dependem do auto-despacho — a configuração em paralelo pode não compensar. A camada portável é menor para você do que para alguém que usa ambas as ferramentas principalmente através de skills em markdown simples.

Se você é um desenvolvedor solo lançando um projeto paralelo nos fins de semana, o argumento de resiliência importa menos. Uma queda custa a tarde de sábado. Irritante, não catastrófico. A configuração em paralelo compensa mais quando seu sustento depende do agente funcionando — quando uma queda significa que o trabalho do cliente não é entregue.

E se você é sensível a custos, rodar dois CLIs significa que tem assinaturas ou acesso API a dois provedores. Eu rodo ambos com planos Pro, o que custa mais por mês do que rodar um. Vale a pena para mim porque o valor de resiliência é alto. Provavelmente não vale a pena para alguém cujo uso é leve.

## A Verdadeira Vitória: Resiliência e Perspectiva Fresca

A configuração vale o esforço por duas razões que são fáceis de subestimar até que você tenha vivido sem elas.

Primeiro, resiliência. Nas seis semanas desde que rodo ambos os CLIs, enfrentei dois incidentes separados da Anthropic e um bug prolongado de atualização do CLI do Claude Code. Nos três casos, perdi aproximadamente zero tempo de trabalho, porque mudei para o Codex em cinco minutos e continuei trabalhando. Comparado com os dias pré-configuração, onde uma tarde ruim poderia me custar um entregável completo de cliente, o investimento em CLI paralelo se pagou no primeiro incidente.

Segundo, perspectiva fresca. Mesmo em dias quando nenhum agente está quebrado, trocar de CLI no meio da tarefa é a ferramenta de criatividade mais barata que já usei. Linhagem de modelo diferente. RLHF diferente. Diferente ênfase em dados de treinamento. O mesmo prompt, enviado ao Claude Code e ao Codex, às vezes produz soluções com abordagens radicalmente diferentes. Adotei o hábito de deliberadamente rodar ambos no mesmo problema difícil e combinar as melhores ideias. É como ter dois engenheiros seniores na mesma tarefa, exceto que um deles custa quase nada extra e nunca se cansa.

A mentalidade agnóstica de ferramentas é a verdadeira mudança. O CLI é intercambiável. O conhecimento do projeto é o que importa. Trate `AGENTS.md` (ou qualquer arquivo de instruções compartilhado que tenha) como o arquivo mais importante do seu repositório. Trate skills como ativos portáveis, não como scripts específicos de ferramenta. Trate sub-agentes como o que cada CLI faz à sua maneira, e não tente forçá-los a serem idênticos entre fornecedores.

Se a Anthropic lançasse um concorrente do Codex amanhã, meu fluxo de trabalho o absorveria numa tarde. Se a OpenAI lançasse algo que tornasse o Claude Code obsoleto, a mesma coisa. Os agentes vêm e vão. O conhecimento do projeto permanece.

Essa é a vitória.

## Perguntas Frequentes

### O Claude Code e o Codex podem editar os mesmos arquivos ao mesmo tempo?
Sim, ambos os CLIs podem editar arquivos no mesmo projeto simultaneamente, mas não se coordenam no nível de memória — se coordenam pelo sistema de arquivos. Se ambos os agentes tocarem o mesmo arquivo no mesmo minuto, você terá um problema de leitura obsoleta. Regra prática: rode-os em paralelo em arquivos diferentes, ou faça transferência explicitamente usando o skill de session-handoff descrito acima.

### Preciso pagar pelo Claude Code e Codex separadamente?
Sim. O Claude Code é o CLI da Anthropic e usa a cobrança da Anthropic (plano Pro ou API). O Codex é o CLI da OpenAI e usa a cobrança da OpenAI (ChatGPT Plus/Pro ou API). Não há assinatura compartilhada. O custo de rodar ambos é aproximadamente o dobro do custo de rodar um, mas a resiliência e a perspectiva fresca fazem valer para profissionais em atividade.

### Qual é a diferença real entre CLAUDE.md e AGENTS.md?
Funcionalmente, nenhuma — ambos são arquivos markdown simples que o agente lê ao iniciar para aprender as convenções do projeto. A diferença é qual CLI lê qual por padrão. O AGENTS.md está se tornando o padrão multi-fornecedor, suportado pelo Codex e outros, enquanto CLAUDE.md é o nome nativo do Claude Code. A configuração mais limpa é manter o AGENTS.md como o arquivo real e criar um link simbólico do CLAUDE.md para ele.

### Meus skills do Claude Code funcionarão no Codex sem mudanças?
A maioria, sim. Ambos os ecossistemas usam o mesmo formato SKILL.md (frontmatter YAML com name/description, corpo markdown). Os skills que precisam de edição são os que referenciam nomes de ferramentas específicos do Claude Code como Glob ou servidores MCP específicos que não estão instalados na sua configuração do Codex. Aproximadamente 80% portam sem mudanças na minha experiência; os outros 20% precisam de 5-10 linhas de edições.

### O Codex tem sub-agentes como o Claude Code?
O Codex agora suporta skills (o substituto moderno dos prompts personalizados) e sub-agentes via `.codex/agents/`, mas o modelo de despacho é diferente: o Codex requer que você invoque explicitamente um sub-agente, enquanto o Claude Code despacha automaticamente baseado na descrição do agente corresponder à tarefa. Se você depende do roteamento automático entre muitos sub-agentes, o Claude Code ainda é o orquestrador mais forte. Se prefere controle determinístico sobre qual agente roda, o modelo de invocação explícita do Codex é mais limpo.

## Vamos Trabalhar Juntos

Procurando construir sistemas de IA, automatizar fluxos de trabalho ou escalar sua infraestrutura tecnológica? Adoraria ajudar.

* **Fiverr** (projetos personalizados e integrações): [fiverr.com/s/EgxYmWD](https://www.fiverr.com/s/EgxYmWD)
* **Portfólio**: [mejba.me](https://www.mejba.me)
* **Ramlit Limited** (soluções empresariais): [ramlit.com](https://www.ramlit.com)
* **ColorPark** (design e branding): [colorpark.io](https://www.colorpark.io)
* **xCyberSecurity** (serviços de segurança): [xcybersecurity.io](https://www.xcybersecurity.io)