🗣️ O vocabulário: runtime, harness, skill, MCP, hook, handoff
Seis palavras vão aparecer o curso inteiro. Cada uma tem um significado preciso e um lugar no disco. Este módulo define todas do zero, mostra onde o Claude Code e o Codex procuram cada coisa, e separa o que é seu do que é da ferramenta.
🧱 Modelo vs runtime vs harness
Quando alguém diz "uso o Claude", pode estar falando de três coisas diferentes. O modelo é o cérebro de IA que gera texto (Claude Opus, GPT, DeepSeek). O runtime é o programa que você abre no terminal e que conversa com esse modelo (Claude Code, Codex CLI, dsh). O harness é a estrutura em volta do modelo que dá a ele mãos e olhos: ler arquivos, rodar comandos, guardar histórico, chamar ferramentas. Na prática, runtime e harness costumam ser o mesmo programa; a distinção importa quando você troca um e mantém o outro.
Novo aqui? Um LLM (modelo de linguagem) é só o modelo: recebe texto, devolve texto. Sozinho ele não abre arquivo nenhum. O que faz o Claude Code "editar seu código" é o harness em volta, que transforma o texto do modelo em ações reais e devolve o resultado. O modelo pensa; o harness age.
Da esquerda pra direita: o modelo está no fundo de duas caixas azuis que pertencem à ferramenta. O que é seu fica fora delas, à direita, e é lido por qualquer harness. Trocar de harness é trocar as caixas azuis; a caixa verde da direita não muda.
✓ É seu (portátil)
- ✓As instruções do projeto, em Markdown.
- ✓As skills (procedimentos em SKILL.md).
- ✓O contexto, as decisões e os handoffs.
✗ É da ferramenta (nativo)
- ✗O loop de execução e o formato do histórico.
- ✗Sandbox, permissões, trust por pasta.
- ✗Plugins, hooks e a memória automática.
Conceitos-chave
O LLM: texto entra, texto sai. Não toca em arquivo.
O programa que roda o loop lê → pensa → age.
Ferramentas, histórico, hooks, permissões em volta do modelo.
Modelo + harness vistos de fora: o que lê o seu projeto.
📜 Instruções (CLAUDE.md / AGENTS.md) e ordem de leitura
Todo harness abre uma pasta e procura um arquivo de instruções. O Claude Code procura CLAUDE.md; o Codex, o Gemini e o OpenCode procuram AGENTS.md. Esse é o único ponto do sistema que é realmente preso ao provedor, e a solução é simples: o AGENTS.md vira a fonte, e o CLAUDE.md passa a começar com uma linha que importa o AGENTS.md. Uma regra, escrita uma vez, lida por todos.
Objetivo: fazer o Claude ler o mesmo arquivo que o Codex. Isto é o CLAUDE.md inteiro de um projeto adaptado:
@AGENTS.md
# Específico do Claude Code
- Nunca usar AskUserQuestion; perguntar em texto livre.
- Plugins superpowers / context-mode / claude-mem são do Claude; não citar em nada portátil.Como verificar: abra uma sessão nova do Claude no projeto e peça "cite uma regra do projeto e o arquivo de origem". A resposta deve apontar pro AGENTS.md.
Novo aqui? Ordem de leitura é a lista, escrita no topo do AGENTS.md, do que o agente deve ler e em que sequência: primeiro as regras, depois o contexto, depois a tarefa atual, por fim o último handoff. Nenhum harness carrega essas pastas sozinho; ele só lê o que a instrução manda ler. Por isso a ordem tem que estar escrita.
AGENTS.md
Regras estáveis e a ordem de leitura. Curto. Muda quando uma regra muda.
context/overview.md e current-state.md
O que o projeto é e o que é verdade hoje.
tasks/current.md
O que estamos fazendo agora, quem é o dono, qual o critério de pronto.
handoffs/latest.md
Onde a última sessão parou e qual é a próxima ação exata.
Conceitos-chave
Fonte das instruções. Lido por Codex, Gemini, OpenCode.
A linha que faz o CLAUDE.md importar a fonte.
O pouco que só o Claude entende, abaixo da linha de import.
Escrita no topo; nada é auto-carregado.
🧩 Skill (SKILL.md) e onde cada runtime procura
Uma skill é um procedimento escrito para o agente: uma pasta com um arquivo SKILL.md (nome, descrição, quando usar, passos) e, opcionalmente, scripts e referências ao lado. O formato é o mesmo entre Claude Code e Codex, o que muda é onde cada um procura. Essa diferença de pasta é o que gera cópias manuais, e cópias manuais são o caminho mais curto para versões divergentes.
📂 Onde cada runtime procura skills
- •Claude Code:
~/.claude/skills/(global) e.claude/skills/no projeto. - •Codex CLI:
~/.codex/skills/e~/.agents/skills/(global),.agents/skills/no projeto. - •dsh (DeepSeek em container): uma pasta montada como
/work/.dsh/skills. - •Na máquina auditada: 117 skills no Claude, 27 no Codex, 3 cópias à mão no dsh, 16 próprias num bot. Quatro consumidores, nenhuma fonte única.
Novo aqui? Skill canônica é a versão-fonte, guardada num lugar só. As pastas de cada runtime recebem cópias geradas a partir dela por uma ferramenta (o curso usa o polyskill), com uma checagem de drift: se alguém editou a cópia em vez da fonte, o sistema avisa. Você edita um arquivo; as N cópias são regeradas.
✗ Sem fonte canônica
- ✗skill-claude, skill-codex, skill-gemini, skill-glm: quatro arquivos pra manter.
- ✗Corrige um bug numa, esquece as outras.
- ✗Ninguém sabe qual é a versão certa.
✓ Com fonte canônica
- ✓Uma SKILL.md canônica → adaptador Claude, adaptador Codex, adaptador dsh.
- ✓Build regenera todas as cópias de uma vez.
- ✓Drift check: [ok] ou [DRIFT] por runtime.
Conceitos-chave
Procedimento em Markdown: nome, quando usar, passos.
Onde cada runtime procura. Difere entre eles.
A única versão editável; as outras são geradas.
Divergência entre cópia e fonte. Deve ser detectada, não descoberta por acidente.
🔌 MCP: ferramentas e dados, não memória
MCP (Model Context Protocol) é um padrão para conectar um agente a serviços externos: um gerador de imagem, um agendador de posts, um banco de dados. O agente ganha ferramentas novas ("gerar imagem", "listar posts") que qualquer harness compatível pode usar. É a parte mais fácil de confundir: MCP dá acesso, não dá lembrança. Ele não junta históricos de chat, não resolve conflito de memória, não separa clientes.
Novo aqui? Pense no MCP como uma tomada padronizada. O serviço (a Magnific, o Metricool) oferece a tomada; o harness (Claude, Codex) tem o plugue. Cada harness precisa registrar a tomada por conta própria, mas a chave de acesso é a mesma e fica num arquivo .env referenciado, nunca copiado.
📊 O estado real na máquina auditada
- •Claude: MCP global magnific e metricool, mais dois por projeto.
- •Codex: nenhum MCP registrado.
- •Consequência: 15 skills que dependem de MCP só funcionam no Claude até o Codex registrar as mesmas tomadas.
✓ O que o MCP resolve
- ✓Acesso a ferramenta e dado externo, padronizado.
- ✓Mesmo serviço, plugado em N harnesses.
- ✓Memória exposta via MCP fica portátil (o texto-base faz isso).
✗ O que o MCP não faz sozinho
- ✗Juntar históricos de chat de ferramentas diferentes.
- ✗Decidir qual versão de um fato é a certa.
- ✗Impor separação entre clientes: isso é permissão de backend.
Conceitos-chave
Protocolo de ferramentas e dados para agentes.
Cada runtime pluga a mesma tomada por conta própria.
A chave fica no .env; o registro aponta pra ela.
MCP não lembra nada por você.
⚙️ Hooks, plugins, subagentes: o que é nativo
Três coisas do Claude Code não atravessam a ponte, e é bom saber disso antes de tentar. Um hook é um script que o harness dispara num evento (ao abrir a sessão, depois de editar um arquivo). Um plugin é um pacote que adiciona comandos e comportamentos ao harness. Um subagente é um agente filho com papel próprio, que o principal convoca. Os três dependem do harness ter aquele evento, aquele formato de pacote, aquele mecanismo de convocar. O Codex tem hooks, mas eventos diferentes; não tem os plugins do Claude; não tem subagentes no mesmo formato.
🔍 Comparação real dos dois harnesses
- •Hooks: Claude dispara em SessionStart (injeta um playbook, ajusta cache); Codex dispara em PostToolUse e Stop. O evento "ao abrir sessão" não existe no Codex.
- •Plugins: 7 no Claude (superpowers, claude-mem, context-mode…); 1 no Codex (github). Formatos incompatíveis.
- •Subagentes: 7 no Claude (um "conselho" de papéis); nenhum equivalente 1:1 no Codex.
Hook vira texto
O que o hook injetava ao abrir a sessão (um playbook de ritmo, por exemplo) vai como seção do AGENTS.md. Perde a automação, mantém o conteúdo.
Plugin fica no resíduo
Não se cita plugin em instrução portátil. Ele vive abaixo do @AGENTS.md, na parte que só o Claude lê.
Subagente vira skill de papel
O prompt do "advogado do diabo" vira uma SKILL.md que qualquer harness invoca como procedimento. Perde a convocação automática, mantém o papel.
💡 Regra do texto-base
"Coloque a lógica reutilizável de hook e checagem em scripts comuns; valide cada evento nativo, payload e configuração de confiança separadamente." O script é portátil. O gatilho é da ferramenta.
Conceitos-chave
Script disparado por evento do harness. Eventos diferem.
Pacote do harness. Não atravessa.
Agente filho com papel. Vira skill de papel.
O que só existe naquele harness. Fica no resíduo.
🔁 Handoff e prime: o resumo que viaja
Um handoff é o resumo estruturado que uma sessão escreve antes de fechar: decisões tomadas, tarefas inacabadas, próximos passos, caminhos de arquivo. Vai para um arquivo Markdown, com um latest.md apontando para o mais recente. Prime é o ato inverso: a sessão nova lê esse arquivo antes de fazer qualquer coisa. O ciclo substitui a dependência do histórico bruto, e é o que permite o Claude parar e o Codex continuar.
O arquivo verde no meio é o único elo entre as duas sessões azuis. Repare que a Sessão B não precisa ser o mesmo harness da Sessão A: o handoff é Markdown, então qualquer executor lê.
Novo aqui? Sem handoff, "continuar de onde parei" significa reabrir a sessão antiga no mesmo harness, ou fuçar num arquivo JSONL de milhares de linhas. O handoff é um resumo de uma página, feito pelo próprio agente, que cabe em qualquer contexto. É a diferença entre transportar a conversa inteira e transportar o que importa dela.
✓ Um bom handoff tem
- ✓Decisões tomadas e o motivo.
- ✓Tarefas inacabadas e o que falta.
- ✓Caminhos exatos dos arquivos tocados.
- ✓A próxima ação, concreta, em uma linha.
✗ Um handoff ruim
- ✗Narra a conversa em ordem cronológica.
- ✗Diz "vários arquivos foram alterados" sem dizer quais.
- ✗Afirma que algo funciona sem dizer que teste rodou.
- ✗Inclui credenciais ou o histórico bruto.
Conceitos-chave
Resumo estruturado escrito ao fechar a sessão.
A sessão nova lê o handoff antes de agir.
Ponteiro fixo para o handoff mais recente.
Claude escreve, Codex retoma. Ou o contrário.
Auto-checagem (opcional): qual destes itens é portátil entre Claude Code e Codex sem adaptação?
🎯 Resumo do módulo
Próximo módulo:
1.3 — Os três níveis de migração: um clique, um comando, pessoal