Mapa da trilha
Conteúdo detalhado
🔁 Convertendo projeto Claude Code → Codex
O prompt mágico de conversão, checklist pós-migração e configuração do project_doc_fallback pra Codex ler tudo que Claude já lia.
Um prompt único que diz ao agente: "li o CLAUDE.md, crie AGENTS.md equivalente, converta `.claude/agents/` (markdown) pra `.codex/agents/` (TOML), e copie skills pra `.agents/skills/`."
Substitui 1-2 horas de migração manual por 30 segundos. A IA conhece os dois formatos — basta dar permissão e o prompt certo.
Prompt-driven migration · isomorfismo entre formatos · `developer_instructions` TOML · single-shot conversion.
Lista de 8 itens: AGENTS.md criado, skills copiadas, agents convertidos, configs traduzidas, hooks documentados (Codex não tem equivalente direto), README atualizado, .gitignore correto, primeiro spawn de teste.
Sem checklist, você descobre o que falta só quando o Codex quebra. Com ele, valida em 5 minutos.
Smoke test · paridade de configuração · gap analysis · hooks como sem-paridade.
Em `~/.codex/config.toml`: `project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]`. Faz o Codex ler CLAUDE.md se AGENTS.md não existir.
Você pode testar Codex em qualquer projeto Claude SEM migrar nada. Decide depois se quer converter.
Config global · fallback chain · zero-touch interop · ordem de precedência.
Pegue um `.claude/agents/clickup-searcher.md`. Pergunte: "Converta esse agent pra TOML do Codex em `.codex/agents/clickup-searcher.toml`". O corpo markdown vira o campo `developer_instructions`.
Saber a anatomia da conversão te permite revisar o resultado. Sem isso, você confia cego e descobre bug depois.
YAML frontmatter → TOML fields · markdown body → developer_instructions · review pós-IA.
Hooks Claude (PreToolUse, PostToolUse) não têm equivalente direto. Slash commands Claude (`/agents`, `/clear`) viram outras coisas no Codex (`spawn`, sessão nova). Permissões: Codex sandbox kernel, Claude approval app-layer.
Esperar paridade 1:1 te frustra. Saber o que não converte = ajustar expectativa.
Pontos sem paridade · paradigmas diferentes (kernel vs app-layer) · expectation management.
Peça pro Codex uma task simples no projeto: "liste todos os módulos exportados em src/". Se a resposta usa nomes corretos e segue o estilo do AGENTS.md, migração funcionou.
É a única forma honesta de saber. Confiar só no checklist deixa passar erros sutis.
Smoke test · validação empírica · primeiro turn · aderência observada.
🛠️ Skills compartilhadas vs agents divergentes
Onde os dois ecossistemas convergem e onde divergem. Como aproveitar a parte boa (skills) e não sofrer com a parte chata (agents).
SKILL.md tem YAML frontmatter (`name`, `description`, `allowed-tools`, `disable-model-invocation`) + corpo markdown com instruções. Esse formato é o Agent Skills standard.
Skills bem escritas viram ativos: Claude, Codex, Cursor, Gemini CLI leem todas o mesmo arquivo. Investimento amortizado.
YAML frontmatter · Agent Skills standard · campos obrigatórios · auto-discovery.
`cp -r .claude/skills/ .agents/skills/` resolve. Se a skill usa só `name`, `description`, `allowed-tools` e `disable-model-invocation`, funciona sem mudar nada.
Quem espera ferramenta sofisticada de migração se surpreende: é cp. Saber disso poupa horas de pesquisa.
Compatibilidade de campos · campos comuns · estrutura de pastas · zero-friction copy.
Claude: `.claude/agents/foo.md` — corpo markdown vira system prompt. Codex: `.codex/agents/foo.toml` — campo `developer_instructions` explícito, mais campos opcionais (`model`, `sandbox_mode`, `nickname_candidates`, `mcp_servers`).
TOML te dá mais controle granular. Markdown é mais legível. Os dois fazem o mesmo trabalho — diferença de filosofia.
developer_instructions · campos opcionais TOML · documentação unificada vs config explícita.
Codex: subagent só roda se você escrever `spawn`. Claude: o agente principal decide invocar via Agent tool com base no próprio julgamento.
Em Claude você precisa torcer pra ele invocar o agent certo. Em Codex você comanda explicitamente. Workflows diferentes para esse detalhe.
Auto-invocação · spawn explícito · julgamento do parent · controle manual.
Opção A: symlink `.agents/skills/ → .claude/skills/` (uma fonte). Opção B: duplicar e usar script de sync. Opção A é mais limpa.
Sem estratégia, você muda skill no Claude, esquece de copiar pro Codex, e o Codex roda versão velha — bug silencioso.
Symlink · single source of truth · sync script · drift entre cópias.
Os melhores agents customizados são narrow: um trabalho claro, surface de ferramentas que combina, instruções que evitam drift.
Agent genérico vira preguiça do modelo principal. Agent específico vira alavanca: "spawn clickup-searcher" e pronto.
Narrow surface · opinioned tools · anti-drift · composição de agents.
⚡ Session handoff entre agentes
Travou no Claude? Cria um handoff, cola no Codex e desbloqueia em 10 segundos. Template HANDOVER.md e o fluxo pronto.
Um bloco curto: objetivo, status atual, decisões tomadas, o que evitar, próximo passo. Você cola no novo agente no início da conversa.
Sem handoff, novo agente começa do zero. Com handoff, começa do passo onde você parou.
Context bridge · estado serializado · resumo deliberado · zero-rebuild.
5 seções: Objetivo, Status, Active files, Decisões, Próximo passo. Arquivo na raiz, atualizado quando dá `/clear` ou troca de agente.
CLAUDE.md guarda regras permanentes. HANDOVER.md guarda estado da sessão atual. Não confunda.
Permanente vs efêmero · seções fixas · documento vivo de sessão.
Skill que, ao ser invocada, lê o histórico da conversa e produz um handoff no formato HANDOVER.md. Funciona em Claude e Codex pelo Agent Skills standard.
Você não escreve o handoff. O agente escreve, você revisa, cola no outro. Fricção mínima.
Skill compartilhada · auto-handoff · low-friction transition · workflow assistido.
Sinais: o agente travou em loop, ficou repetindo correção que não funciona, contexto passou de 70%, você quer testar abordagem diferente, sessão ficou longa demais.
Quem só dá handoff "no fim do dia" perde a janela em que ele resolveria. Saber o sinal certo = ganho de tempo.
Context rot · loop detection · gut signal · early switch.
Cenário: Claude trava num bug. Você gera handoff, abre terminal do Codex no mesmo projeto, cola e diz "siga em frente". Codex tem abordagem diferente — frequentemente resolve.
Não é mágica — é abordagem diferente atacando o mesmo problema. Padrão validado pelo Nate Herk e pela comunidade.
Cross-agent fix · perspectiva alternativa · unblock workflow · prática validada.
Cenário real: Claude faz design dark moderno. Handoff pro Codex. Codex restaura valor que se perdeu no styling. Volta pro Claude pra polimento. Os dois colaboram no mesmo HTML.
É o uso mais avançado. Cada turn de handoff equivale a "promover" um pra refinar o trabalho do outro. Cuidado com overwrite (próximo módulo).
Round-trip · iteração colaborativa · papéis complementares · risco de overwrite.
📋 Prompts e dicas prontas (copy/paste)
Biblioteca dos prompts mais usados: conversão, handoff, auditoria, destrava-bug, audit-skills. Cole e adapte.
"Eu construí este projeto com Claude Code. Crie AGENTS.md baseado no CLAUDE.md. Crie .codex/config.toml. Converta todos os agents de .claude/agents/*.md pra .codex/agents/*.toml. Copie .claude/skills/ pra .agents/skills/. Pesquise a documentação dos dois antes."
É o prompt do vídeo do Nate Herk, refinado. Em 1 turn, migração completa.
One-shot conversion · pesquisa explícita · pedidos atômicos numa só instrução.
"Crie um HANDOVER.md com: objetivo da sessão, status atual, lista de active files com 1 linha de descrição cada, decisões tomadas (com why), o que evitar, próximo passo concreto. Formato markdown, máx 60 linhas."
Você não escreve. O agente revisa o histórico e produz. Você cola no novo terminal.
Output limitado · estrutura fixa · why explícito · próximo passo concreto.
"Spawn um subagent. Audita: arquivos não usados, deps não usadas, dead code, TODOs antigos (>30 dias), skills duplicadas entre .claude/ e .agents/. Retorne SOMENTE punch list de até 20 linhas. Não inclua o output completo."
O subagent roda em context fresh, faz a varredura toda, e devolve só o resumo. Seu context principal fica limpo.
Subagent audit · output limitado · context isolation · punch list.
"Estou travado nesse bug. Aqui está o handoff: [cola HANDOVER.md]. Não confie nas tentativas anteriores. Reproduz o erro do zero, isola a causa, propõe correção. Não corrige antes de me mostrar a hipótese."
"Não confie nas tentativas anteriores" é a frase mágica — quebra o viés do contexto trazido.
Bias breaking · reprodução fresca · hipótese antes da ação · debugging disciplinado.
"Audite AGENTS.md. Identifique: regras temporárias virou permanente, histórico de bugs (deveria estar em git log), instruções redundantes com README. Proponha versão enxuta. Não delete sem me mostrar antes."
AGENTS.md/CLAUDE.md incham com o tempo. Audit periódico (3 em 3 meses) mantém custo de tokens baixo.
Pruning · auditoria periódica · noise removal · diff antes de delete.
Seções: Project Overview, Build & Test Commands, Code Style, Boundaries (não-mexer), Personas/Roles, Decision Log. Direto, sem floreio.
Começar do zero gera AGENTS.md inchado. Começar do template enxuto, adicionar só o que dói faltar = enxuto.
Lean start · seção mínima · decision log · boundaries explícitas.
Conteúdo: `@AGENTS.md` na primeira linha + 3 seções Claude-only: Hooks Config, Permission Levels, Path-scoped Rules. Tudo o resto vem do AGENTS.md.
CLAUDE.md vira fino. Atualiza AGENTS.md, Claude lê na hora. Manutenção mínima.
@import · seções Claude-only · DRY · manutenção amortizada.
(1) Esperar paridade 1:1, (2) duplicar conteúdo em CLAUDE.md e AGENTS.md, (3) deixar skills só num dos lados, (4) usar hooks como se Codex tivesse equivalente, (5) ignorar `project_doc_fallback_filenames`.
Cada um custa pelo menos 1h de debug. Saber antes = não cair.
Anti-patterns · gotchas · onboarding mistakes · saver-of-time.