2.1 Convertendo Claude → Codex

🪄 O prompt mágico de conversão

Um prompt único, copy/paste, que converte o projeto inteiro em um turn. Refinado do vídeo do Nate Herk com adições da documentação oficial.

Cole isso no Claude Code (ou Codex):

Construí este projeto com Claude Code. Preciso que o Codex também consiga usar.

Faça em ordem:
1. Pesquise documentação atual de Codex CLI (AGENTS.md, .codex/, agents TOML)
2. Pesquise como funciona @import no Claude Code
3. Crie AGENTS.md a partir do CLAUDE.md mantendo apenas conteúdo UNIVERSAL
   (code style, build/test commands, project structure, boundaries)
4. Refatore CLAUDE.md pra começar com @AGENTS.md + só seções Claude-only
   (hooks, permission, path-scoped rules)
5. Crie .codex/config.toml com project_doc_fallback_filenames=["CLAUDE.md"]
6. Para cada arquivo .claude/agents/*.md, gere .codex/agents/*.toml equivalente
   (markdown body → developer_instructions)
7. Copie .claude/skills/ para .agents/skills/ (mantém SKILL.md original)
8. Hooks Claude não têm equivalente direto no Codex — documente em README
9. Atualize .gitignore: settings.local.json continua ignorado

NÃO mexa em nada fora de .claude/, .codex/, .agents/, CLAUDE.md, AGENTS.md.
Mostre diff de cada arquivo criado/alterado antes de aplicar.

💡 Por que esse prompt funciona

Tem 3 ingredientes: (1) pesquisa explícita antes (evita uso de info desatualizada), (2) ordem clara dos passos (não inverte), (3) limite de escopo (não-mexer-em-X) — evita refator surpresa.

📝 Checklist pós-migração

Antes de confiar, valida. Sem checklist você descobre o que faltou só quando o Codex quebra:

✓ 1

AGENTS.md criado e enxuto

Universal só. Sem hooks, sem regras temporárias.

✓ 2

CLAUDE.md começa com @AGENTS.md

DRY aplicado. Resto: só Claude-only.

✓ 3

.codex/config.toml com fallback

Codex lê CLAUDE.md se AGENTS.md sumir.

✓ 4

Cada agent Claude virou TOML Codex

developer_instructions com markdown body.

✓ 5

.agents/skills/ tem cópia das skills

Ou symlink pra .claude/skills/.

✓ 6

Hooks documentados em README

Codex não tem equivalente — registre o gap.

✓ 7

.gitignore ok

settings.local.json e .codex/local.toml ignorados.

✓ 8

Smoke test passou

Primeiro spawn no Codex deu output aderente.

🔄 project_doc_fallback_filenames

Sua arma secreta pra testar Codex em projeto Claude existente: 1 linha em ~/.codex/config.toml e zero migração.

# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]

Fluxo recomendado

Ativa fallback hoje (1 minuto)
Usa Codex no projeto Claude existente por 1-2 semanas
Decide se Codex vale o esforço de migração formal
Se sim, roda o prompt mágico do tópico 1

🧪 Convertendo um agent específico

Quando você precisa converter UM agent (não o projeto inteiro), o padrão é direto. Sabendo a anatomia, você revisa o output da IA.

Antes: .claude/agents/audit.md

---
name: audit
description: Audita dead code
tools: [Read, Grep, Bash]
---

Procure imports não usados,
funções sem caller, TODOs
antigos. Retorne lista de
até 20 itens, priorizada.

Depois: .codex/agents/audit.toml

name = "audit"
description = "Audita dead code"
sandbox_mode = "read-only"
developer_instructions = """
Procure imports não usados,
funções sem caller, TODOs
antigos. Retorne lista de
até 20 itens, priorizada.
"""

Regra de revisão: verifique se (a) developer_instructions tem o corpo markdown sem truncar, (b) tools viram sandbox_mode apropriado, (c) o nome bate.

⚠️ Armadilhas comuns

Os 5 erros mais frequentes na migração — cada um custa pelo menos 1h de debug se você não souber antes:

✗ Armadilhas

1Esperar hooks Claude no Codex
2Duplicar conteúdo em CLAUDE.md e AGENTS.md (sem @import)
3Esquecer de copiar skills pra .agents/skills/
4Slash commands Claude (/agents) usados como no Codex
5Ignorar project_doc_fallback_filenames

✓ Soluções

1Documente hooks como skill invocável no Codex
2@AGENTS.md no topo do CLAUDE.md
3Symlink: ln -s ../.claude/skills .agents/skills
4No Codex use spawn explícito
5Configura o fallback de cara, ganha 2 semanas

✅ Validando com smoke test

Checklist é necessário mas não suficiente. Faça um smoke test real: peça pro Codex uma task que exige saber as convenções do projeto.

Smoke test sugerido:

Liste todos os módulos exportados em src/. Para cada um, indique:
- Path
- 1 linha do que faz (lendo o código)
- Se tem teste em tests/ correspondente

Use o code style do projeto. Não modifique arquivos.

Sinais de sucesso: Codex usa nomenclatura correta dos módulos (não inventa), respeita "não modifique" (não fura), output segue formato pedido. Se sim, AGENTS.md foi bem escrito.

📚 Resumo do Módulo

✓

1 prompt único migra o projeto — com pesquisa explícita + ordem + escopo

✓

Checklist de 8 itens valida pós-migração

✓

project_doc_fallback = migração zero-cost

✓

Agents .md → .toml é determinístico

✓

Hooks Claude não têm paridade

✓

Smoke test real é a única validação honesta

Próximo Módulo:

2.2 — Skills compartilhadas vs agents divergentes

← Voltar para Trilha Próximo: Skills vs Agents →