🛠️ Mão na massa

O repo inematds/agente-claude-codex reúne scripts, prompts e o template do núcleo portátil. Você clona uma vez e roda tudo de dentro dele.

Sem o kit você refaz na mão o que já está automatizado e testado nesta máquina (readback aprovado em Claude e Codex).

git clone https://github.com/inematds/agente-claude-codex, pasta scripts/, prompts/, template/.

Um script somente leitura que confere git, python3, node, Claude Code, Codex CLI (skills, config, sandbox, MCP), polyskill e os próprios arquivos do kit. Cada item sai como [ok], [aviso] ou [FALTA] com o comando para resolver.

Responde "meu ambiente está pronto?" em segundos e sai com código 1 se faltar algo essencial, o que permite automatizar.

scripts/doctor.sh, código de saída, aviso ≠ falta, sem Claude ou Codex o passo vira "não rodado".

Lista versões, skills, comandos, subagentes, hooks, plugins e MCP dos dois runtimes e grava um relatório Markdown em relatorios/auditoria-<data>.md.

É o passo 2 dos mega-prompts (MODE: audit): você vê o que existe antes de decidir o que migra.

scripts/audit.sh, gap Claude → Codex, relatório datado, separação projeto × global.

A auditoria classifica por heurística (grep) cada skill que só existe no Claude: reutilizável (Markdown puro), adaptador (depende de MCP ou plugin do Claude), nativo (depende de hook) ou não resolvido. Nesta máquina: 72 / 15 / 2 / 1.

A matriz diz onde o esforço está: 72 skills migram sem mudança; o bloqueio real são os 15 MCP, não o formato.

Classificação heurística, revisar caso a caso, MCP como gargalo, subagentes e plugins não migram.

Neste host o AppArmor restringe user namespaces e o bwrap do Codex falha ("loopback: RTM_NEWADDR"). O readback que forçava -s read-only quebrou; a correção mínima foi respeitar o sandbox_mode do config.toml.

Você vai esbarrar nisso em qualquer máquina Linux parecida; o doctor.sh já avisa e a falha está no FALHAS.md com a menor correção.

bwrap, AppArmor, sandbox_mode = "danger-full-access", FALHAS.md (data, o que quebrou, menor correção, prompt ou infra).

O relatório em relatorios/ não é o fim: cada linha vira uma decisão (portar, adaptar, deixar como resíduo Claude) que alimenta o plano de migração em fases.

Sem transformar o inventário em plano você só tem uma lista bonita; o texto-fonte insiste que arquivo existir não é prova de nada.

Relatório datado, matriz → fases, passou / falhou / não rodado, evidência versionada.

Regras de publicação, autor de commit, onde ficam as keys, versionamento semver, destino de artefatos: tudo isso é texto que qualquer agente entende.

É a maior parte do seu CLAUDE.md (71 de 78 linhas no global desta máquina) e viaja sem mudança.

Regra estável, caminho, convenção, AGENTS.md como fonte.

Menções a AskUserQuestion, superpowers, context-mode, claude-mem, fable-mindset, Artifact, advisor e hooks só fazem sentido no Claude Code.

Se isso for pro AGENTS.md, o Codex lê instruções que não pode cumprir e o ruído cresce.

Resíduo, plugin, hook, ferramenta exclusiva, 7 linhas no global.

O script lê o CLAUDE.md do projeto e grava AGENTS.proposto.md e CLAUDE.proposto.md ao lado, para revisão. Nada existente é tocado.

Reversível por construção: você revisa, renomeia e só então o projeto muda.

scripts/adapt-instructions.sh ~/projetos/meu-projeto, --dry-run, .proposto.md.

O novo CLAUDE.md começa com a linha @AGENTS.md e só depois traz o resíduo. O Claude lê os dois; o Codex lê só o AGENTS.md.

Uma fonte de verdade para as regras portáteis, sem cópia divergente.

Import @, uma fonte, resíduo separado, sem duplicação.

O AGENTS.md abre com "leia 1) este arquivo, 2) context/overview.md, 3) context/current-state.md, 4) tasks/current.md, 5) handoffs/latest.md". Esses nomes são convenção do repo, não são carregados sozinhos.

O prompt B é explícito: diga ao agente o que ler; não assuma auto-load.

Ordem de leitura, convenção ≠ auto-load, briefing pequeno no início.

O script troca toda menção "CLAUDE.md" por "AGENTS.md" na parte portátil, inclusive quando o texto fala do CLAUDE.md de outro projeto. Isso muda o sentido.

É por isso que a saída é .proposto.md: a revisão humana pega esse caso.

Renomeação cega, revisar referências, sed é burro, humano aprova.

Copia template/ pro projeto arquivo a arquivo; se já existe, mantém e avisa [mantido]; se não, cria e avisa [criado].

A primeira versão do kit usava cp -r e sobrescrevia README e CLAUDE.md; a correção foi a regra "nunca sobrescrever".

scripts/init-core.sh ~/projetos/meu-projeto, criado, mantido, reversível.

O context/overview.md tem cabeçalho (ID, escopo, fonte, data, status, revisar em) e seções: o que é, fatos verificados, preferências, hipóteses.

Separar fato de hipótese é o que resolve "qual das versões é a certa" depois.

ID, escopo, fonte, data de observação, status, fato × preferência × hipótese.

Um arquivo que diz o que está sendo feito agora, quem é o dono, qual o critério de pronto verificável e a próxima ação concreta.

É o que faz o agente entender o trabalho atual, não só o histórico.

Objetivo, dono, critério de pronto, próxima ação, bloqueios.

Cada decisão aceita vira um arquivo datado em context/decisions/ com contexto, decisão e consequências. Status: proposta, aceita, revogada.

Decisão aceita vence timestamp: é o critério de conflito do plano.

Decisão datada, status, provenance, nunca apagar, revogar.

Um check de 8 linhas: os arquivos obrigatórios existem e não estão vazios. Sai 0 ou 1.

Um check pequeno e real vale mais que uma estrutura bonita que ninguém valida.

bash scripts/check.sh, [ok] / [FALTA], código de saída.

Clone o projeto sozinho numa pasta limpa e rode o check. O prompt B exige: contexto essencial dentro do projeto, sem depender de ../../knowledge.

Prova de portabilidade: se depende de pasta-mãe, não é portátil.

Clone limpo, sem dependência de pasta-mãe, check passa, evidência.

Nesta máquina o dsh-sandbox tem 3 skills copiadas à mão de formato-curso-inema. Cada edição na origem não chega nas cópias: drift garantido.

Quatro consumidores (Claude 117, Codex 27, dsh 3, openpcbotv3 16) sem fonte única divergem sozinhos.

Drift, cópia manual, fonte canônica, adaptador nas bordas.

scripts/sync-skills.sh import session-handoff lê ~/.claude/skills/session-handoff e grava skills/session-handoff/ no formato portátil.

A skill deixa de ser "do Claude" e vira fonte neutra.

polyskill import --from claude, definition.md, polyskill.yaml, extensões preservadas ou avisadas.

scripts/sync-skills.sh build gera skills/*/dist/<runtime>/. Com FORCE=1 sobrescreve alvo editado à mão.

A cópia por runtime é derivada, nunca editada: editar a fonte e rebuildar.

dist/, derivado, --force, nunca editar cópia.

scripts/sync-skills.sh install session-handoff --both copia pro ~/.claude/skills e ~/.codex/skills (e espelha em ~/.agents/skills), fazendo backup .nome.bak-<ts> se já existia.

Instalar é a única ação que toca a home dos runtimes; por isso backup antes.

--both, --claude, --codex, backup ao lado, ~/.agents/skills.

scripts/sync-skills.sh drift compara cada dist/ com o que está instalado. Sai 1 se houver diferença.

É o teste de que ninguém editou a cópia por fora; entra no critério de aceite.

diff -rq, [ok], [DRIFT], [não instalada], código de saída.

As 15 skills "adaptador" (heygen, magnific, printing-press…) citam ferramentas MCP. No Codex só funcionam depois de registrar o servidor com codex mcp add.

Portar antes do MCP gera skill que não roda; ordem importa.

MCP no Codex, codex mcp add, keys referenciadas do .env, nunca copiar valor.

Objetivo atual e critério de pronto; uma regra com o arquivo exato de origem; última decisão aceita; próxima ação concreta; conflitos, fatos velhos ou acesso faltando. Separar o que os arquivos estabelecem do que o agente infere.

É o teste de continuidade do prompt B: encontrou, leu, entendeu, usou?

Fresh-session readback, sem conversa anterior, citar fonte, inferência marcada.

scripts/readback-test.sh ~/projetos/meu-projeto both roda os dois e salva a resposta bruta em relatorios/readback-<runtime>-<data>.md.

Automatiza a coleta; o veredito continua sendo seu.

claude -p, codex exec --skip-git-repo-check, relatório por runtime, sandbox do config.toml.

Critério: AGENTS.md, tasks/current.md e handoffs/latest.md aparecem citados e a "próxima ação" bate com a tarefa.

Prosa bonita sem citação é alucinação de contexto; citação é evidência.

Citação de arquivo, próxima ação confere, passou / falhou.

No primeiro readback aprovado, o Codex encontrou handoff faltando, soma errada no audit e frase contraditória no plano. Todas corrigidas na hora.

O readback não só prova, ele audita: um agente novo lê sem o viés de quem escreveu.

Inconsistência, auditoria por sessão nova, correção registrada.

Duas falhas reais: sandbox forçado (-s read-only) e contagem do audit. Cada uma vira uma linha: data, o que quebrou, menor correção, prompt ou infra.

Depois de umas 10 linhas o padrão aparece e você para de reconstruir o que só precisava de uma proteção.

FALHAS.md, menor correção, prompt × infra, uma linha por falha.

Passou: citou os arquivos e a ação confere. Falhou: rodou e não citou. Não rodado: runtime ausente, sandbox quebrou, ou ninguém rodou. Sem evidência conta como não rodado.

O PDF-fonte admite: nenhum teste ao vivo foi feito pelos autores. O seu readback é a primeira evidência real.

Três estados, evidência salva, nunca "provavelmente passou".

Projeto e escopo, objetivo, estado aceito, arquivos alterados, checks rodados com resultado, perguntas abertas, próxima ação exata. Sem credenciais, sem "está em outro worktree".

Um handoff bom substitui reler 2,3 GB de JSONL.

Decisão, pendência, próximo passo, caminho de arquivo, sem segredo.

O template do kit tem 7 seções fixas. latest.md é sempre o mais recente; versões antigas podem ficar em handoffs/AAAA-MM-DD.md.

Estrutura fixa é o que deixa outro runtime (ou outra pessoa) retomar sem adivinhar.

latest.md, seções fixas, datado, uma estrutura para todos.

Prime é a leitura de AGENTS.md → context → tasks → handoffs no início. No Claude vira skill; no Codex, instrução no AGENTS.md; no dsh, uma skill de prime.

Sem prime, o handoff é um arquivo que ninguém lê.

Prime, ordem de leitura, skill × instrução, briefing pequeno.

O teste final: handoff escrito numa sessão do Claude, retomado numa sessão nova do Codex, e vice-versa, em projeto real.

Esse é o critério de pronto do sistema inteiro.

Handoff cruzado, mesmo Markdown, executores intercambiáveis.

Nesta máquina: 6.859 sessões do Claude (2,3 GB) e 209 do Codex. Depois que o ciclo roda, arquivar as com mais de 90 dias.

Memória bruta é matéria-prima; o que vale é o que foi promovido a overview ou handoff.

JSONL, arquivar, promover fato, matéria-prima × fonte.

Nenhuma sessão termina sem handoffs/latest.md e tasks/current.md atualizados. O readback do dia seguinte é a checagem.

É a única disciplina que torna a troca de modelo indolor.

Fim de sessão, atualizar dois arquivos, readback como auditoria.