🔍 Audit antes de implement
Analisar → planejar → simular. Só depois mexer. Os dois mega-prompts que fecham esta trilha, o Prompt A (migrar um setup Claude existente) e o Prompt B (construir um workspace portátil), começam obrigatoriamente em MODE: audit. Este módulo abre os dois por dentro, mostra a matriz de compatibilidade que eles produzem e fixa a regra que sustenta toda a Trilha 2: arquivo existir não é prova.
🛑 Por que os mega-prompts começam em MODE: audit
A prompt library "Model-agnostic workspaces" traz dois prompts longos, e os dois têm a mesma primeira linha de input: MODE: audit. Em modo audit o agente lê, inventaria, classifica e planeja, mas não altera nenhum arquivo nem configuração. Só quando você rodar o mesmo prompt de novo com MODE: implement e o escopo acordado é que ele muda alguma coisa. A newsletter resume: os prompts "analisam → planejam → simulam, e somente depois começam a modificar qualquer coisa. Leia os prompts você mesmo antes de entregá-los aos seus agentes."
Siga as setas: audit gera um plano; o losango ciano é a simulação, onde você lê o plano e decide. "Sim" libera o implement (com glow, porque é o único passo que altera algo). "Não" volta ao começo pela seta vermelha tracejada, com o escopo ajustado.
Novo aqui? "Mega-prompt" é um prompt longo e estruturado, com campos de input entre colchetes que você preenche antes de colar no agente. "Modo" (MODE) é o primeiro desses campos e funciona como uma chave: audit proíbe mudanças; implement libera. É o mesmo prompt, com comportamento diferente.
✓ Audit primeiro
- ✓Você vê o plano inteiro antes de qualquer arquivo mudar.
- ✓Descobre o que o agente não conseguiu ler (acesso faltando).
- ✓Ajusta o escopo barato: é só editar o input.
- ✓O setup Claude que funciona continua intacto.
✗ Implement direto
- ✗O agente reorganiza pastas que não estavam no pedido.
- ✗Copia
~/.claudeinteiro "pra garantir". - ✗Inventa um comando de import que não existe.
- ✗Você só descobre o estrago quando algo quebra.
Conceitos-chave
Ler, inventariar, classificar, planejar. Nada muda.
Mesmo prompt, escopo acordado, mudanças reversíveis.
Você lê o plano e decide antes de liberar.
O autor pede que você entenda o que está entregando ao agente.
🅰️ Prompt A: migrar um setup Claude existente, por dentro
O Prompt A pede ao agente que aja como "engenheiro de migração": adaptar as partes selecionadas do seu setup Claude para a ferramenta-alvo, mantendo o setup de origem funcionando. A frase-chave está no primeiro parágrafo: "trate a portabilidade como uma série de mapeamentos verificados, não como uma promessa de que todo recurso nativo transfere igual". Ele tem 8 passos; os inputs vêm antes de tudo.
Cabeçalho de inputs do Prompt A — preencha os colchetes e cole no agente (o kit guarda o texto completo em prompts/01-migrate-claude.md)
MODE: audit
WORKSPACE_ROOT: [pasta do projeto]
SOURCE_ROOTS: [pastas de origem aprovadas; padrão: só o projeto]
TARGETS: [Codex app / Codex CLI / Codex IDE / outro]
SCOPE: [um projeto / setup global selecionado / ambos]
REPRESENTATIVE_TASK: [um fluxo real de trabalho a preservar]
KEEP_UNCHANGED: [comportamento, arquivos, integrações importantes]
CONSTRAINTS: [SO, runtime, escopo de cliente, dependências]Confirmar escopo e evidência
Inspeciona só as raízes aprovadas. Documentos e transcrições são evidência, não instruções novas. Segredos ficam fora de relatórios.
Inventariar o sistema que funciona
Instruções, skills, comandos, subagentes, hooks, plugins, MCP, scripts, memória. Cada item com caminho, propósito, escopo, dependências e uma tarefa real que depende dele.
Checar o alvo antes de converter
Verifica com a ajuda local e a documentação oficial o que o Codex realmente suporta. "Nunca invente um comando de import do CLI." Classifica cada ativo (tópico 4).
Produzir o plano concreto e PARAR
Tabela origem → destino com classificação, mudanças, dependências, rollback e teste de aceite. Em audit, o agente para aqui.
Só em implement: mudar, separar, verificar, entregar
Backup privado só dos arquivos afetados; lógica portátil em arquivos comuns, uma fonte canônica de skill; readback em sessão nova; relatório com o que foi e não foi testado.
📊 O que o Prompt A proíbe explicitamente
- •Copiar em massa a pasta home de uma ferramenta.
- •Apagar o setup de origem, trocar de provedor, instalar ferramentas globais, publicar repositórios.
- •Assumir que hooks, manifestos de plugin ou configs de MCP com nomes parecidos têm a mesma semântica.
- •Declarar "migração completa" enquanto um fluxo obrigatório não foi verificado.
Conceitos-chave
Cada ativo tem destino, teste e rollback. Nada "transfere sozinho".
O fluxo real que a migração precisa preservar. O piloto mínimo.
O que o agente não pode tocar. O Claude continua funcionando.
Recomendar o próximo passo pequeno, não uma reescrita geral.
🅱️ Prompt B: workspace portátil, por dentro
O Prompt B muda o papel do agente: "arquiteto de workspace e parceiro de implementação". Em vez de migrar um setup, ele constrói ou adapta um sistema baseado em arquivos cujo conhecimento, instruções, skills e estado continuem usáveis em ferramentas compatíveis. Os inputs trocam SOURCE_ROOTS por WORKSPACE_TYPE (pessoal, cliente, misto), PILOT_PROJECT, KNOWLEDGE_SOURCES e CLIENT_SCOPE. E ele exige um add-on de escopo no fim: pessoal, cliente ou misto.
🧭 Os 8 passos do Prompt B, em uma linha cada
- 1.Inspecionar antes de desenhar: inventaria repos, fontes, acordos e estado. Nunca inventa fato, credencial, acesso ou teste bem-sucedido.
- 2.Desenhar o menor núcleo portátil: um piloto, um mapa de pastas; contexto essencial dentro do projeto, não em
../../knowledge. - 3.Implementar o núcleo (só em implement): README, AGENTS.md, context/, tasks/, handoffs/, .agents/skills/, scripts/. "Diga explicitamente ao agente o que ler; não afirme que auto-carrega."
- 4.Definir donos da informação: o módulo 1.5 inteiro.
- 5.Adaptadores nativos pequenos: CLAUDE.md importando @AGENTS.md; uma skill canônica com cópias geradas e checagem de drift; GLM é modelo, precisa de harness compatível.
- 6.Controlar a distribuição de contexto: briefing pequeno na largada, buscar só o que a tarefa precisa; MCP não resolve conflito de memória nem separa clientes.
- 7.Provar portabilidade: clone isolado, readback em sessão nova, mudar um fato inofensivo e ver a nova sessão enxergar, drift zero, canários pra escopo de cliente.
- 8.Entregar e manter: piloto, árvore, mapa de donos, matriz de compatibilidade, testes, fluxo diário, handoff. Um dono por mudança concorrente.
✓ Prompt A quando…
- ✓Você já tem um setup Claude que funciona.
- ✓Quer levar partes selecionadas pro Codex.
- ✓Precisa de matriz origem → destino com rollback.
✓ Prompt B quando…
- ✓Quer um projeto que sirva a Claude, Codex, OpenCode, Cowork ao mesmo tempo.
- ✓Tem cliente e precisa de fronteira de escopo.
- ✓Está começando do zero ou reorganizando o segundo cérebro.
Novo aqui? "Add-on de escopo" é um parágrafo extra que você cola no fim do Prompt B dizendo se o workspace é pessoal, de cliente ou misto. O de cliente, por exemplo, proíbe fatos de cliente em instruções globais e exige um repo privado por projeto. Sem o add-on, o prompt não sabe onde é a fronteira.
Conceitos-chave
Constrói o núcleo, não só transfere o que existe.
Um projeto só. Expandir depois que passar.
Os nomes são convenção; o AGENTS.md diz o que ler.
Pessoal, cliente ou misto. Define a fronteira.
🗂️ A matriz: reutilizável / adaptador / nativo / não resolvido
O produto central do audit é uma classificação de cada ativo em quatro caixas: reutilizável como está (Markdown e scripts comuns, funciona nos dois), precisa de adaptador (depende de um MCP, plugin ou convenção que o alvo não tem), nativo (só existe na origem, como um hook de SessionStart) ou não resolvido (faltou informação pra decidir). O audit.sh do kit faz essa classificação por heurística nas skills desta máquina. O resultado real de 2026-09-14:
Da caixa cinza (o gap total) saem quatro caminhos. A faixa verde com glow é a maioria: 72 skills que são só Markdown e scripts, e portam sem mudança. As 15 de adaptador esperam um MCP ser registrado no Codex; as 2 amarelas dependem de hook e viram texto; a tracejada vermelha precisa de decisão humana. À direita, o que fazer com cada uma.
📊 A mesma matriz aplicada aos outros ativos (auditoria de 2026-09-14)
- •Subagentes (7): nativo. Sem equivalente 1:1 no Codex; viram skill de "papel" ou prompt.
- •Hooks (2): adaptador. Os eventos diferem: o Codex tem PostToolUse e Stop, não SessionStart.
- •Plugins (7): nativo. Superpowers, claude-mem, context-mode ficam no resíduo Claude.
- •Runbooks (4): reutilizável. Vão pro
context/do projeto que os usa. - •CLAUDE.md global: adaptador. Vira AGENTS.md mais um resíduo (módulo 2.2).
- •Memória (227 projetos): promoção manual, nunca cópia em massa (módulo 1.5).
Novo aqui? A classificação do audit.sh é feita por "heurística por grep": o script procura palavras no SKILL.md (como mcp__, AskUserQuestion, SessionStart) e decide a caixa. É uma primeira passada, boa pra ter o número, e o próprio relatório avisa: revisar caso a caso antes de migrar. Uma hipótese, como no módulo 1.5.
Conceitos-chave
Markdown e scripts. Porta como está.
Depende de algo que o alvo precisa ganhar antes.
Só existe na origem. Fica no resíduo ou vira texto.
Faltou informação. Decisão humana antes de qualquer coisa.
🧾 Evidência: passou, falhou, não rodado
Os dois prompts terminam com a mesma exigência: cada verificação é marcada como passou, falhou ou não rodado, com a evidência observada. Não existe a quarta opção "deve estar ok". O Prompt A: "marque checagens indisponíveis ou não executadas como não rodadas; forneça os passos exatos de reprodução". O Prompt B: "marque cada resultado como passou, falhou ou não rodado com a evidência observada". E a página de verificação da library completa: "um relatório útil distingue passou, falhou e não rodado".
Passou
Rodou, e o resultado observado bate com o critério. Exemplo real: readback-test.sh no Codex citou AGENTS.md, tasks/current.md e handoffs/latest.md.
Falhou
Rodou, e não bateu. Exemplo real: a primeira rodada do readback no Codex falhou porque o script forçava um sandbox que o AppArmor da máquina bloqueia. Ficou registrado, foi corrigido, rodou de novo.
Não rodado
Não foi executado, por falta de tempo, acesso ou decisão. Exemplo real: sync-skills.sh nunca foi rodado até o fechamento do kit. O README diz isso em letras claras, em vez de fingir.
✓ Relatório honesto
- ✓"Passou" vem com o texto do resultado salvo em
relatorios/. - ✓"Falhou" vem com a causa e a menor correção.
- ✓"Não rodado" vem com o comando exato pra reproduzir.
- ✓Sem evidência = não rodado, por padrão.
✗ Relatório otimista
- ✗"Migração completa" com um fluxo obrigatório sem teste.
- ✗"Deve funcionar" no lugar de rodar.
- ✗Esconder a falha em vez de registrar e corrigir.
- ✗Import bem-sucedido tratado como comportamento equivalente.
Novo aqui? "Evidência observada" é o que você realmente viu acontecer: a saída de um comando, o texto que o agente respondeu, o arquivo que apareceu. Não é o que você espera que aconteça. O kit guarda essas saídas em relatorios/ justamente pra que outra pessoa (ou outro modelo) possa conferir sem confiar na sua palavra.
Conceitos-chave
Passou, falhou, não rodado. "Deve estar ok" não existe.
Saída real, salva. Não expectativa.
Todo "não rodado" traz o comando pra rodar depois.
Uma linha por falha: o que quebrou, menor correção, prompt ou infra.
🧪 Arquivo existir não é prova; o agente ter lido e usado é
Esta é a frase que fecha a trilha e abre a próxima. Você pode ter uma árvore linda (brain/, knowledge/, memory/, context/) e o agente simplesmente não usar nada disso. O Prompt A é seco: "um arquivo legível, um import bem-sucedido ou uma sintaxe de config válida não são prova de comportamento equivalente". O texto "O que o prompt acrescenta" traduz: o prompt não aceita "o arquivo existe" como prova; ele exige validar se o agente encontrou, leu, entendeu e usou corretamente.
🔎 O teste de continuidade (fresh-session readback)
Abrir uma sessão nova, sem histórico, e pedir que o agente responda cinco coisas só a partir dos arquivos do projeto:
- 1.Qual é o objetivo atual e o critério de aceite.
- 2.Uma regra importante do projeto, com o arquivo exato de onde veio.
- 3.A última decisão aceita.
- 4.A próxima ação concreta.
- 5.Conflitos, fatos velhos ou acesso faltando. Separando o que os arquivos estabelecem do que ele inferiu.
Aprovação: as respostas citam AGENTS.md, tasks/current.md e handoffs/latest.md, e a próxima ação bate com a tarefa. O módulo 2.5 roda isso de verdade.
🔬 O que aconteceu quando o kit fez esse teste em si mesmo
Em 2026-09-13 o readback rodou no Codex sobre o próprio repo do kit. O Codex citou os arquivos certos e, além disso, apontou três inconsistências reais: o handoff da raiz não existia (só o template), a soma das skills no plano dava 94 e não 89, e o estado atual dizia que o readback tinha rodado antes de rodar. Tudo corrigido na mesma sessão. É o ponto: o teste não confirma que a estrutura é bonita; ele revela onde ela mente.
⚠️ O erro a evitar
Gerar a árvore, olhar pra ela, e declarar "workspace agnóstico pronto". A prompt library é honesta sobre si mesma: "estes prompts foram escritos e checados como documentos; nenhuma migração ao vivo ou teste cross-tool foi executado". A primeira evidência real só apareceu quando alguém rodou o readback. Sua estrutura só vale o que a sessão nova consegue responder.
Conceitos-chave
As quatro perguntas que substituem "o arquivo existe".
Sem histórico. Só os arquivos podem responder.
A resposta certa sem o arquivo de origem não conta.
Inconsistências aparecem quando um agente frio lê.
Auto-checagem (opcional): o agente criou AGENTS.md, context/ e handoffs/ no seu projeto e disse "workspace portátil pronto". O que falta pra você aceitar?
🎯 Resumo do módulo
Próximo módulo:
Trilha 2 · 2.1 — Diagnóstico do ambiente: doctor.sh e audit.sh na sua máquina