Mapa da trilha
Conteúdo detalhado
🔄 Migração assistida por IA + manutenção em paralelo
Você não migra à mão. Você pede o agente novo migrar pra ele mesmo.
Em vez de copiar/renomear/converter à mão, você abre o agente DESTINO (Codex se está vindo do Claude, e vice-versa) e pede que ele faça a leitura da config atual e crie a equivalente.
Migração à mão leva horas e tem bugs sutis. Agente faz em minutos, com chance de pegar nuance (sintaxe TOML, sidecar) que você esqueceria.
Princípio "agente migra agente", pesquisa de documentação como parte do prompt, validação posterior pelo humano.
Prompt explícito que diz pro agente: leia CLAUDE.md, gere AGENTS.md equivalente; leia .claude/agents/, gere .codex/agents/ em TOML; leia .claude/skills/, copie/adapte pra .agents/skills/; pesquise documentação dos dois pra garantir.
Quem manda prompt vago tem resultado vago. O template padronizado garante cobertura completa: AGENTS.md + .codex/ + .agents/ + adaptação de agents pra TOML.
Ordem do prompt importa, pedir pesquisa de documentação explicitamente, listar arquivos esperados, pedir relatório do que mudou.
Lista do que SEMPRE conferir depois que o agente diz "migrado": AGENTS.md tem instruções equivalentes; agents em TOML carregam sem erro; skills aparecem no comando de listagem; MCP servers conectam; permissões fazem sentido.
Agente pode dizer "feito" e ter pulado algo. Checklist é a apólice. Cinco minutos validando salva horas de "por que isso não funciona".
Validação por funcionalidade (não só por arquivo), teste de smoke (invocar uma skill simples), conferir openai.yaml em skills com MCP deps.
(1) Skill em .codex/skills em vez de .agents/skills; (2) backtick-bang copiado sem fallback; (3) description longa truncada; (4) agents em markdown em vez de TOML; (5) auto-dispatch esperado no Codex.
São os 5 erros que aparecem em quase toda migração. Sabendo, você bate o olho e detecta. Sem saber, fica horas debugando "por que não dispara".
Path de pasta certo, conversão de injeção, limite de description, formato TOML, invocação explícita.
Depois da migração inicial, toda mudança grande no CLAUDE.md precisa virar mudança no AGENTS.md (e vice-versa). Skills idem. É o "imposto" de manter os dois runtimes.
Sem disciplina, os dois divergem em semanas e você acaba com dois projetos diferentes. Disciplina manual funciona; polyskill (T5) automatiza pra skills.
Rule "mudou aqui, mudou lá", hook ou checklist pre-commit, divergence detection, polyskill como solução pra skills (não pra CLAUDE.md/AGENTS.md).
Você pode ter Claude Code como agente principal e Codex só pra rodar skills específicas (ou vice-versa). Não é tudo ou nada. Compartilha o código-fonte, mantém só skills duplicadas.
Reduz custo de duplicação. Muita gente migra tudo achando que precisa, quando bastaria portar 2-3 skills críticas pro Codex.
Agente principal vs auxiliar, escopo mínimo de duplicação, "skill polyglot" portada com polyskill (T5).
Depois da migração inicial e da experiência de manter os dois, vem o "ok, eu não quero mais fazer isso manualmente". Aí entra a Trilha 5: polyskill. Source único, dois outputs, drift policy.
Pra ter contexto da dor antes de ver a solução. Quem entende a dor de manter duas skills divergentes valoriza muito mais o polyskill.
Source-of-truth canônico, adapters por runtime, build automatizado, hash de drift, round-trip Claude ↔ Codex.