4.1 Migração assistida por IA

🎯O que você ganha aqui

Um prompt-template testado e batido pra converter projeto Claude → Codex (e vice-versa), checklist de validação pós-migração, lista das 5 armadilhas que pegam todo mundo, e a ponte natural pra Trilha 5 (polyskill).

Conteúdo detalhado

🎯 A premissa — agente migra agente

A migração à mão é cara e tem bugs sutis (esquece um sidecar, troca um path, perde uma flag). Solução: abrir o agente DESTINO e pedir que ele leia a config atual e gere a equivalente. Migração em minutos, com chance de pegar nuance que humano esqueceria.

Por que funciona

• O agente conhece o formato dele (configuração nativa)
• Pode CONSULTAR documentação (web fetch, MCP)
• Itera rápido sobre arquivos sem ter dor de carpal
• Anota o que mudou pra você revisar

✗ À mão

• 2-4h pra projeto médio
• Esquece detalhes (sidecar, sintaxe)
• Não consulta doc atualizada
• Bug sutil só aparece em produção

✓ Assistida por IA

• 10-30 min pro mesmo projeto
• Cobre detalhes que humano pula
• Pode ler doc oficial no processo
• Relatório do que mudou

Conceitos-chave

Agent migra agent
Princípio central

Doc fetch
Web em real-time

Iteração rápida
Min vs horas

Validação humana
Indispensável depois

📋 O prompt-template — copia, cola, roda

Resultado vago vem de prompt vago. Use este template padronizado pra garantir cobertura completa da migração:

Template — Claude → Codex

Este projeto foi criado pra Claude Code. Quero usar Codex também.

Faça o seguinte (cobertura completa, não pule etapa):

1. Leia o `CLAUDE.md` atual.
   Gere um `AGENTS.md` equivalente. Mantém instruções,
   convenções e comandos de build/test.
   Remove sintaxe backtick-bang (vira prosa de fallback).

2. Leia `.claude/settings.json`.
   Crie `.codex/config.toml` equivalente. Converte:
   - permissions (allow/deny/ask) → sandbox_mode + approval_policy
   - hooks → entries equivalentes (mesma matcher, mesmo command)
   - env vars → seção [env]
   - MCP servers de .mcp.json → [mcp_servers.<nome>]

3. Pra cada sub-agent em `.claude/agents/*.md`:
   Converte pra `.codex/agents/<nome>.toml`.
   Frontmatter → chaves TOML. Body → string em `instructions = """..."""`.
   Adapta description pra mencionar invocação explícita.

4. Pra cada skill em `.claude/skills/<nome>/`:
   Copia pra `.agents/skills/<nome>/` (note: .agents/, NÃO .codex/).
   Remove campos não-portáveis do frontmatter (allowed-tools,
   disable-model-invocation, model). Converte backtick-bang em prosa.
   Se a skill precisa de MCP, cria `agents/openai.yaml` sidecar.

5. Pra cada slash command em `.claude/commands/*.md`:
   Copia pra `.codex/commands/`. Remove backtick-bang.

6. Antes de terminar: pesquise documentação oficial do Codex
   pra confirmar formatos atuais (sandbox, profiles, MCP).

7. Devolva um RELATÓRIO no final:
   - Arquivos criados (com path)
   - Conversões não-óbvias que fez
   - Coisas que removeu (e por quê)
   - O que NÃO conseguiu portar e precisa ajuste manual

Template — Codex → Claude

É o mesmo prompt, invertendo origem e destino. Pontos a inverter:

AGENTS.md → CLAUDE.md
.codex/config.toml → .claude/settings.json (TOML → JSON)
.codex/agents/*.toml → .claude/agents/*.md (TOML struct → markdown frontmatter+body)
.agents/skills/ → .claude/skills/ (pode continuar em .agents/, mas Claude espera .claude/skills/)
Sidecar openai.yaml → frontmatter da skill (allowed-tools, etc.)
Prosa de fallback pode virar backtick-bang (opcional)

💡Salva como skill ou slash command

Esse template é candidato natural pra virar slash command (/migrate-from-claude) ou skill (migrate-claude-to-codex) no agente destino. Você só roda /migrate-from-claude e funciona.

Conceitos-chave

Ordem importa
Doc fetch primeiro

Lista explícita
Por tipo de arquivo

Relatório final
Pede explicação

Reverso simétrico
Inverte direção

✅ Checklist pós-migração

Agente pode dizer "migrado" e ter pulado algo. 5 minutos validando salva horas de "por que isso não funciona". Marca cada item:

🗂️ Estrutura de arquivos

☐ AGENTS.md existe na raiz (ou CLAUDE.md, na direção inversa)
☐ .codex/config.toml existe (ou .claude/settings.json)
☐ .codex/agents/ tem um .toml por sub-agent
☐ .agents/skills/ tem uma pasta por skill (NÃO em .codex/skills/)

⚙️ Validação técnica

☐ Abrir o Codex no projeto — carrega sem erro de parse
☐ Listar agents disponíveis — todos aparecem
☐ Listar skills — todas aparecem
☐ $ + nome da skill auto-completa
☐ MCP servers conectam (se aplicável)

🧪 Smoke test funcional

☐ Invoca uma skill simples ($skill ou prompt natural)
☐ Roda um sub-agent ("use agent X para...")
☐ Roda um slash command
☐ Verifica que hooks (se tiver) disparam nos eventos certos
☐ Confere se backtick-bang foi convertido (não vira texto literal)

📝 Sanidade do AGENTS.md

☐ Comandos de build/test ainda no topo
☐ Convenções centrais preservadas
☐ Sem sintaxe Claude-only (backtick-bang, Task tool refs)
☐ Tamanho razoável (< 2KB)

Conceitos-chave

Validação ≠ fé
Não confia no agente

Smoke test
Invoca uma de cada

Paths críticos
.agents vs .codex

Sintaxe morta
Bang residual

⚠️ As 5 armadilhas mais comuns

Em quase TODA migração aparece pelo menos uma destas. Sabendo, você detecta antes. Sem saber, fica horas debugando.

1. Skill em .codex/skills/ em vez de .agents/skills/

Sintoma: "$skill não dispara, mas o arquivo está lá".

Fix: mover pasta inteira pra .agents/skills/<nome>/. Refresh do Codex (Plugins → reload).

2. Backtick-bang copiado sem fallback

Sintoma: Skill funciona no Claude, no Codex devolve resposta esquisita com `!git status` tipo texto.

Fix: trocar por prosa ("antes de começar, rode git status e leia o resultado"), ou colocar lógica num script.

3. Description longa truncada (limite ~8K)

Sintoma: Skill dispara só em alguns prompts; nem todos os triggers funcionam.

Fix: mover triggers e exemplos pros primeiros 1-2KB da description. Resto (contexto adicional) pode ir depois — e pode ser truncado.

4. Agents em markdown em vez de TOML

Sintoma: Codex não lista os agents, ou erro de parse no startup.

Fix: converter frontmatter pra chaves TOML, body pra instructions = """...""". Renomear extensão pra .toml.

5. Esperar auto-dispatch de sub-agent no Codex

Sintoma: "Por que meu code-reviewer não está sendo chamado quando peço revisão?".

Fix: chamar pelo nome — "use o agent code-reviewer para revisar X". Codex não auto-dispara por description (ver T3.1).

Conceitos-chave

Path certo
.agents/skills/

Bang → prosa
Fallback semântico

Front-loading
Triggers no topo

Invocação nominal
"use agent X"

🔁 Manutenção sincronizada — o "imposto"

Migração inicial é um evento. Manutenção é recorrente. Toda mudança importante no CLAUDE.md precisa replicar no AGENTS.md (e vice-versa). Skills idem. Sub-agents idem. Sem disciplina, divergem em semanas.

A regra simples: "mudou aqui, mudou lá"

Sempre que você editar:

📘 CLAUDE.md → atualiza AGENTS.md
⚙️ .claude/settings.json permissões/hooks → atualiza .codex/config.toml
👤 .claude/agents/<x>.md → atualiza .codex/agents/<x>.toml
🧩 .claude/skills/<x>/SKILL.md → atualiza .agents/skills/<x>/SKILL.md

🔧 Ferramentas manuais

• Pre-commit hook que avisa divergência
• Checklist do PR template
• Slash command /sync-runtimes
• Diff entre os dois arquivos pelo agente

🦜 Solução automática (skills)

• polyskill resolve pra skills
• Source única em definition.md
• Build emite os dois lados
• Drift policy detecta edição fora-de-banda

💡Esquema híbrido recomendado

Use polyskill pra skills (item de maior superfície e mudança) + disciplina manual pra CLAUDE.md/AGENTS.md/settings/agents (mudam pouco, à mão é viável). Esse é o equilíbrio prático.

Conceitos-chave

"Mudou aqui, lá"
Regra simples

Pre-commit hook
Avisa divergência

Polyskill auto
Pra skills

Manual pro resto
Settings/agents

🤝 Migração parcial — só skills

Não é tudo ou nada. Você pode manter Claude Code como agente principal e usar Codex SÓ pra rodar 2-3 skills críticas (ou vice-versa). Compartilha código-fonte, mantém apenas skills duplicadas.

Quando faz sentido

• Skill que ROCK no Codex e meia-boca no Claude (ou inverso)
• Você quer Codex só pra "second opinion" em casos travados
• Time tem 1-2 devs preferindo o outro runtime, mas não migrou tudo
• Plano gratuito limitado, complementa com o outro

🎯

Escopo mínimo

Portar SÓ as 2-3 skills que você usa mais. Resto fica só no agente principal.

📂

AGENTS.md mínimo

Versão simplificada do CLAUDE.md, focada no necessário pra essas skills funcionarem.

🚫

Sem sub-agents

Pula a conversão de sub-agents se você não usa eles em rotina nesse runtime.

Conceitos-chave

Não é tudo ou nada
Migra o que importa

Agent principal
Continua um só

Skills críticas
Escolhe poucas

Polyskill scope
Resolve essas skills

🚀 Próximo passo — polyskill

Depois da migração inicial e da experiência de manter os dois lados sincronizados manualmente, vem o "ok, eu não quero mais fazer isso à mão". Aí entra a Trilha 5: polyskill.

O que polyskill resolve (e o que não resolve)

✓ Resolve:

• Skills duplicadas (source única)
• Drift silencioso (hash de arquivo)
• Limite description Codex (auto front-load)
• Backtick-bang → prosa
• Sidecar openai.yaml (auto-gera)

✗ NÃO resolve:

• CLAUDE.md ↔ AGENTS.md (manual)
• settings.json ↔ config.toml (manual)
• Sub-agents Claude ↔ Codex (manual)
• Diferenças de modelo entre runtimes

🦜Quem mais ganha

Quem mais ganha com polyskill é quem tem 5+ skills usadas regularmente. Pra 1-2 skills, manutenção à mão ainda é viável. Pra 10+, polyskill vira indispensável.

Conceitos-chave

Source canônica
definition.md

Adapters runtime
claude, codex, ...

Drift policy
Hash + reconcile

Threshold
~5 skills+

🎯Resumo do módulo

✓

Agente migra agente — não faça à mão, peça pro destino fazer.

✓

Use o prompt-template padronizado — cobre AGENTS.md, config.toml, agents, skills, commands.

✓

Checklist pós-migração em 5 min — estrutura, técnica, smoke test, sanidade.

✓

5 armadilhas comuns: path, bang, description, TOML, dispatch — sabendo, detecta na hora.

✓

Manutenção = "mudou aqui, mudou lá" — disciplina + polyskill pra skills.

✓

Migração parcial é válida — só skills críticas, agente principal único.

✓

Polyskill resolve skills, não tudo — limites claros do que automatiza.

Próxima trilha:

T5 — polyskill cross-runtime (spec, arquitetura, drift policy, CLI completo)

← Voltar para Trilha 4 Trilha 5: polyskill →