MÓDULO 2.2

✂️ CLAUDE.md → AGENTS.md

Portátil de um lado, resíduo do outro. Seu arquivo de instruções tem duas naturezas misturadas: regras que valem pra qualquer agente e comandos que só o Claude Code entende. Neste módulo você separa as duas com o adapt-instructions.sh, revisa o corte à mão e deixa o Claude continuar lendo tudo por um @AGENTS.md.

Tópicos

~30

Minutos

Básico

Nível

Prática

Tipo

🧳 O que é portátil numa instrução

Abra o seu CLAUDE.md e leia linha por linha fazendo uma única pergunta: esta frase continuaria verdadeira se o executor fosse o Codex, o Gemini CLI ou um modelo local? Se a resposta for sim, a linha é portátil. Ela fala do seu mundo — do seu jeito de publicar, dos seus caminhos, das suas convenções — e não do programa que está lendo.

No CLAUDE.md global desta máquina, a maioria esmagadora do arquivo é portátil. Regras como "publicar = commit + push pro git, nunca cutucar o Vercel direto", "o autor do commit segue a conta GitHub de destino do repo", "versionamento semver vX.XX.YY: minor incrementa o XX e carrega o YY, nunca zera", "API keys sempre em ~/projetos/openpcbotv2/.env ou ~/projetos/wifi/.env, carregar em runtime e nunca imprimir o valor" — nenhuma delas menciona o Claude. São política de trabalho. Qualquer agente que as leia se comporta melhor.

Olhe os dois números da direita: no CLAUDE.md global desta máquina o corte deu 71 linhas portáteis contra 7 de resíduo. Quase tudo que você escreveu nunca foi sobre o Claude — era sobre o seu trabalho.

✓ Portátil (vai pro AGENTS.md)

✓Regras de publicação: "publicar = commit + push; o deploy é do webhook, não meu".
✓Autoria de commit: qual conta e qual e-mail por repositório de destino.
✓Versionamento: o esquema vX.XX.YY e quando cada dígito zera.
✓Caminhos: onde ficam as keys, onde saem os artefatos, onde vive o portal.
✓Idioma, tom e formato de resposta esperado.

✗ Não portátil (fica no resíduo)

✗Nome de ferramenta exclusiva: AskUserQuestion, Artifact, advisor.
✗Nome de plugin: superpowers, context-mode, claude-mem.
✗Configuração de hook e precedência sobre injeções de hook.
✗Slash commands que só existem num runtime (/code-review).
✗Qualquer valor de segredo — isso não entra em lugar nenhum.

💡 Novo aqui?

Runtime é o programa que executa o agente: Claude Code, Codex CLI, Gemini CLI, OpenCode. Instrução é o arquivo Markdown que o runtime lê antes de agir — CLAUDE.md no Claude, AGENTS.md no resto. Portátil quer dizer que o texto não depende de qual programa está lendo. Resíduo é o que sobra depois de tirar o portátil: pequeno, específico e descartável quando você troca de executor.

Conceitos-chave

Portátil

Vale pra qualquer executor; fala do seu trabalho.

Resíduo

Só faz sentido dentro de um runtime específico.

Teste da troca

"Continua verdadeiro com outro executor?"

Proporção real

71 portáteis para 7 de resíduo nesta máquina.

🧪 O que é resíduo Claude

O resíduo não é lixo. São instruções legítimas e úteis — só que amarradas a um programa. O script do kit reconhece o resíduo por uma lista de palavras-chave, que é literalmente uma expressão regular dentro do arquivo: AskUserQuestion, superpowers, context-mode, fable-mindset, claude-mem, ultrareview, /code-review, Artifact, advisor, plugin e hook. Toda linha que casa com um desses termos vai pro resíduo; todas as outras vão pro portátil.

# dentro de scripts/adapt-instructions.sh — a regra do corte, em uma linha:
CLAUDE_ONLY='AskUserQuestion|superpowers|context-mode|fable-mindset|claude-mem|ultrareview|/code-review|Artifact|advisor|plugin|hook'

Repare no que isso implica. A regra "nunca usar AskUserQuestion (menu interativo), sempre perguntar em texto livre" é resíduo pelo nome da ferramenta — mas a intenção ("prefiro responder em texto, não escolher de menu") é portátil. O script não sabe distinguir intenção de nome: ele corta por palavra. Por isso o resultado é uma proposta, não um arquivo final. Quando você revisar, reescreva a intenção em linguagem neutra e deixe o nome da ferramenta no resíduo.

🎯 Ver o resíduo antes de cortar

Objetivo: descobrir, sem escrever nada, quantas linhas do seu arquivo são específicas do Claude e quais são.

cd ~/projetos/<seu-projeto>

# quantas linhas no total
wc -l CLAUDE.md

# quais linhas são resíduo (mesma regex do script)
grep -nE 'AskUserQuestion|superpowers|context-mode|fable-mindset|claude-mem|ultrareview|/code-review|Artifact|advisor|plugin|hook' CLAUDE.md

Como verificar: some as linhas que o grep mostrou e compare com o wc -l. No CLAUDE.md global desta máquina o resultado foi 7 de resíduo em 78 linhas — 71 portáteis. Se no seu projeto o resíduo passar de um terço do arquivo, provavelmente há configuração de ferramenta onde deveria haver regra de trabalho.

Ferramentas nomeadas

AskUserQuestion, Artifact, advisor. O Codex não tem essas ferramentas; citar o nome delas num AGENTS.md só gera confusão.

Plugins

superpowers, context-mode, claude-mem, fable-mindset. Plugin é empacotamento do Claude Code; não existe conceito equivalente no Codex CLI.

Hooks e precedência

Regras do tipo "este arquivo vence o que o hook injetar". Fazem sentido onde existe hook de sessão; no Codex, SessionStart nem existe.

Slash commands

/code-review, /formato-curso-v5. O roteamento por barra é convenção de interface, não conteúdo. Traduza pro nome da skill quando migrar.

Conceitos-chave

Regex do corte

Onze termos decidem o que é resíduo. Está no script, dá pra editar.

Intenção vs nome

A intenção quase sempre é portátil; o nome da ferramenta não.

Corte por linha

O script trabalha linha a linha, sem entender parágrafo.

Proposta

O resultado pede revisão humana; não é entrega.

⚙️ adapt-instructions.sh e os .proposto.md

O script recebe a pasta de um projeto e procura um CLAUDE.md lá dentro. Se não achar, ele avisa e sai com código 0 — não é erro, é "nada a adaptar". Se achar, grava dois arquivos ao lado do original, com o sufixo .proposto.md. Esse detalhe é a garantia de segurança do módulo inteiro: o script nunca sobrescreve nada. Você lê, corrige e só então renomeia à mão.

🎯 Gerar o par de propostas

Objetivo: produzir AGENTS.proposto.md e CLAUDE.proposto.md num projeto seu, sem tocar no arquivo original.

cd ~/projetos/agente-claude-codex

# 1. ensaio: gera, mostra as contagens e apaga os arquivos
scripts/adapt-instructions.sh ~/projetos/<seu-projeto> --dry-run

# 2. pra valer: deixa os dois .proposto.md na pasta do projeto
scripts/adapt-instructions.sh ~/projetos/<seu-projeto>

# Propostos (revisar e renomear manualmente):
#   ~/projetos/<seu-projeto>/AGENTS.proposto.md  (71 linhas)
#   ~/projetos/<seu-projeto>/CLAUDE.proposto.md   (7 linhas)

# 3. veja o que mudou antes de aceitar
diff ~/projetos/<seu-projeto>/CLAUDE.md \
     ~/projetos/<seu-projeto>/AGENTS.proposto.md | head -40

Como verificar: o CLAUDE.md original continua idêntico (git status não mostra modificação nele, só dois arquivos novos não rastreados). As duas contagens somadas, mais o cabeçalho que o script adiciona, batem aproximadamente com o total do original.

💡 Dica prática

Rode sempre o --dry-run primeiro. Ele gera, imprime as duas contagens e remove os arquivos em seguida. Você fica sabendo a proporção portátil/resíduo do projeto sem sujar a pasta — útil quando você vai varrer dezenas de projetos pra decidir por onde começar.

Vale escalar isso. Nesta máquina, 165 projetos têm CLAUDE.md, 54 já têm AGENTS.md e 39 têm os dois. Ou seja: 15 projetos têm AGENTS.md sem CLAUDE.md (nasceram portáteis) e 126 ainda estão presos a um runtime só. Além disso, 13 projetos marcados como trusted no Codex não têm AGENTS.md — são os candidatos óbvios a piloto, porque o Codex já pode trabalhar neles mas ainda não sabe as regras.

✓ O que o script garante

✓Nunca sobrescreve CLAUDE.md nem AGENTS.md existentes.
✓Sai com código 0 e uma mensagem clara quando não há o que adaptar.
✓Insere a ordem de leitura no topo do portátil, sempre.
✓Põe @AGENTS.md como primeira linha do resíduo.
✓--dry-run limpa os arquivos que acabou de criar.

✗ O que ele NÃO faz

✗Entender parágrafos: o corte é por linha, sem contexto.
✗Renomear .proposto.md pro nome final — isso é seu.
✗Distinguir intenção de nome de ferramenta.
✗Preservar menções a CLAUDE.md de outros projetos (veja o tópico 6).
✗Provar que algum agente leu o resultado — isso é o readback, no 2.5.

Conceitos-chave

.proposto.md

Saída pra revisão, ao lado do original. Você renomeia.

--dry-run

Mede a proporção sem deixar arquivo pra trás.

Idempotente

Rodar duas vezes gera o mesmo par; nada acumula.

Escala

165 CLAUDE.md nesta máquina; comece pelos 13 trusted.

🔗 @AGENTS.md: o Claude importando o portátil

A pergunta que todo mundo faz nesse ponto: "se eu tirar as regras do CLAUDE.md, o Claude para de saber delas?". Não. O Claude Code entende uma linha de import: um @ seguido do caminho de outro arquivo Markdown puxa o conteúdo daquele arquivo pra dentro das instruções. Então o novo CLAUDE.md começa com @AGENTS.md e continua com as sete linhas de resíduo. O Claude lê os dois. O Codex lê só o AGENTS.md. Nenhum dos dois perde nada que lhe diga respeito.

Compare os dois lados: à direita, três runtimes lendo o arquivo diretamente; à esquerda, o Claude chegando ao mesmo arquivo pela seta tracejada do import. O que importa é que existe um único bloco central — se houvesse dois, você teria duas verdades pra manter.

🎯 Aceitar as propostas com segurança

Objetivo: promover os .proposto.md a arquivos reais, guardando o original como backup datado.

cd ~/projetos/<seu-projeto>

# 1. backup do original, com data no nome
cp CLAUDE.md CLAUDE.md.bak-$(date +%Y%m%d)

# 2. promover as propostas JÁ REVISADAS
mv AGENTS.proposto.md AGENTS.md
mv CLAUDE.proposto.md CLAUDE.md

# 3. o novo CLAUDE.md tem que começar com o import
head -1 CLAUDE.md
# @AGENTS.md

Como verificar: abra uma sessão nova do Claude nessa pasta e peça "cite a regra de autoria de commit e diga de qual arquivo ela veio". A resposta tem que citar AGENTS.md. Se citar CLAUDE.md, o import não foi resolvido — confira se o caminho está certo e se o @ está na primeira linha.

Conceitos-chave

Import (@)

Uma linha puxa outro Markdown pras instruções do Claude.

Fonte única

As regras existem em um arquivo só; ninguém duplica.

Backup datado

Antes de promover, guarde o original com a data.

Prova de leitura

Perguntar de onde veio a regra revela qual arquivo entrou.

🧭 Ordem de leitura explícita no topo

Aqui está o detalhe que separa um workspace que funciona de um que só parece organizado: nada auto-carrega. O runtime lê o arquivo de instrução — e só. As pastas context/, tasks/ e handoffs/ são convenção humana; nenhum programa vai abri-las por conta própria. Se você quer que o agente leia, você escreve que ele deve ler, no topo do AGENTS.md. É por isso que o script injeta essa linha automaticamente em todo portátil que gera.

# AGENTS.md — instruções portáteis do projeto

> Ordem de leitura para qualquer agente: 1) este arquivo, 2) context/overview.md,
> 3) context/current-state.md, 4) tasks/current.md, 5) handoffs/latest.md.
> Estes nomes são convenção: nada é carregado automaticamente fora do
> AGENTS.md/CLAUDE.md.

AGENTS.md

As regras. Como trabalhar, o que nunca fazer, onde ficam as coisas. O único arquivo que o runtime realmente carrega sozinho.

context/overview.md

O que é este projeto, pra quem, com quais fatos datados. Estável: muda em semanas, não em horas.

context/current-state.md

Onde a coisa está agora: o que já roda, o que está quebrado, o que foi decidido e ainda não implementado.

tasks/current.md

Objetivo, dono, critério de pronto, próxima ação concreta, bloqueios. Uma tarefa por vez, com nome de arquivo de verdade.

handoffs/latest.md

O que a última sessão fez e o que a próxima deve saber. É a ponte entre runtimes: o Claude escreve, o Codex retoma.

💡 Dica prática

Ordem é hierarquia de confiança, não só sequência. Quando tasks/current.md contradiz o overview.md, quem está errado é o overview — ele envelheceu. Escreva isso no AGENTS.md: "em caso de conflito, o mais específico e mais recente vence, e avise o conflito em vez de escolher em silêncio". Agente que aponta contradição vale mais que agente que adivinha.

Conceitos-chave

Nada auto-carrega

Fora do AGENTS.md/CLAUDE.md, ninguém abre nada sozinho.

Convenção

Os nomes das pastas são acordo entre humanos.

Ordem = confiança

O mais específico e recente vence no conflito.

Injetada pelo script

Todo AGENTS.proposto.md já nasce com a ordem no topo.

🪤 A armadilha do sed

Na hora de montar o portátil, o script faz duas coisas: filtra as linhas de resíduo e, no que sobra, roda sed 's/CLAUDE\.md/AGENTS.md/g'. A troca é global e cega. Ela não distingue "o CLAUDE.md deste projeto" de "o CLAUDE.md daquele outro projeto" — e a segunda menção não deveria mudar, porque aquele outro projeto continua com um CLAUDE.md de verdade no disco. O próprio cabeçalho do script avisa disso em uma linha de comentário.

# o que o script faz com a parte portátil:
grep -vE "$CLAUDE_ONLY" "$SRC" | sed 's/CLAUDE\.md/AGENTS.md/g'

# antes (correto):
#   Ver o `CLAUDE.md` do portal para o passo a passo de atualização.
#   Cada projeto pode ter seu próprio `CLAUDE.md` dizendo qual conta usar.
# depois (quebrado — esses arquivos não existem):
#   Ver o `AGENTS.md` do portal para o passo a passo de atualização.
#   Cada projeto pode ter seu próprio `AGENTS.md` dizendo qual conta usar.

⚠️ Por que isso machuca de verdade

Um agente que lê "veja o AGENTS.md do portal" vai tentar abrir ~/projetos/portal/AGENTS.md. O arquivo não existe. A partir daí ele faz uma de duas coisas ruins: inventa o conteúdo, ou declara que não há instruções para o portal e segue sem elas — que é exatamente o cenário em que o commit sai com o autor errado. Uma substituição de texto inofensiva virou uma regra perdida.

🎯 Revisar o sed antes de renomear

Objetivo: listar toda menção que o sed trocou e decidir, uma a uma, se a troca estava certa.

cd ~/projetos/<seu-projeto>

# 1. onde o original falava de CLAUDE.md
grep -n 'CLAUDE\.md' CLAUDE.md

# 2. onde a proposta passou a falar de AGENTS.md
grep -n 'AGENTS\.md' AGENTS.proposto.md

# 3. as duas listas lado a lado: cada linha a mais é uma troca a conferir
diff <(grep -c 'CLAUDE\.md' CLAUDE.md) <(grep -c 'AGENTS\.md' AGENTS.proposto.md)

# 4. reverter uma menção que era de OUTRO projeto
sed -i 's|AGENTS.md do portal|CLAUDE.md do portal|' AGENTS.proposto.md

Como verificar: depois do passo 4, grep -n 'do portal' AGENTS.proposto.md volta a citar CLAUDE.md. Regra de bolso: toda menção que vem acompanhada de um nome de projeto ("do portal", "do inemavox", "de cada projeto") é referência externa e deve ser revertida; menções soltas ("este arquivo", "o CLAUDE.md deste repo") são internas e a troca está correta.

✓ Troca correta

✓"as regras deste CLAUDE.md" → fala do arquivo local, que virou AGENTS.md.
✓"escreva no CLAUDE.md do projeto atual" → o atual é justamente o que você migrou.
✓Títulos de seção que nomeiam o próprio arquivo.

✗ Troca a reverter

✗"o CLAUDE.md do portal" → outro repositório, que não foi migrado.
✗"cada projeto pode ter seu CLAUDE.md" → fala de projetos de terceiros.
✗Caminhos literais como ~/.claude/CLAUDE.md — é um caminho real no disco.
✗Citações de documentação externa que usam o nome do arquivo do Claude.

💡 Dica prática

Quando terminar a revisão, registre a rodada: uma linha em FALHAS.md se algo quebrou ("o sed trocou a referência ao CLAUDE.md do portal; menor correção: reverter a linha; categoria: prompt") e um parágrafo em handoffs/latest.md dizendo quais projetos já têm AGENTS.md promovido. Sem isso, daqui a duas semanas você não vai lembrar quais dos 165 projetos já passaram por aqui.

Conceitos-chave

Substituição cega

O sed troca texto, não entende referência.

Referência externa

Menção a arquivo de outro projeto: não deve mudar.

Caminho literal

~/.claude/CLAUDE.md existe no disco; preserve.

Revisar antes de renomear

A proposta só vira arquivo depois da sua leitura.

Auto-checagem (opcional): o AGENTS.proposto.md ficou com a frase "consulte o AGENTS.md do portal para atualizar o card". O que fazer?

🎯 Resumo do módulo

✓

Portátil vs resíduo — a pergunta é "continuaria verdadeiro com outro executor?". No CLAUDE.md global desta máquina: 71 portáteis, 7 de resíduo.

✓

adapt-instructions.sh — gera AGENTS.proposto.md e CLAUDE.proposto.md ao lado do original e nunca sobrescreve nada.

✓

@AGENTS.md — o Claude importa o portátil e mantém só o resíduo; Codex, Gemini e OpenCode leem o AGENTS.md direto.

✓

Ordem de leitura e a armadilha do sed — nada auto-carrega, então escreva a ordem no topo; e revise cada menção trocada antes de renomear.

Próximo módulo:

2.3 — Instalar o núcleo portátil: init-core.sh sem sobrescrever

← Voltar para a Trilha Próximo módulo →