✅ Readback: provar em sessão nova
Você montou o núcleo portátil e portou a skill. Agora vem a única pergunta que importa: um agente que nunca viu o projeto consegue retomá-lo? Neste módulo você roda o readback nos dois runtimes, lê a resposta com critério e aprende a marcar cada check como passou, falhou ou não rodado.
❓ As 5 perguntas do readback
O readback é um teste de continuidade: você abre uma sessão nova, sem histórico, e pede ao agente que leia o projeto e responda cinco perguntas. Se ele responde citando os arquivos certos, o núcleo portátil funciona. Se ele inventa, ou responde do próprio conhecimento genérico, o núcleo existe mas não está sendo usado.
Leia da esquerda pra direita: as cinco perguntas entram numa sessão sem histórico e saem como um de três vereditos. Não existe "mais ou menos passou": ou cita o arquivo, ou não cita.
O prompt é curto e genérico de propósito. Ele não diz onde os arquivos estão: se o agente precisa que você aponte, a ordem de leitura do AGENTS.md não está funcionando. Este é o texto exato, tirado da prompt library e guardado no kit em prompts/03-readback-handoff.md:
Objetivo: colar numa sessão nova de qualquer runtime, dentro da pasta do projeto.
Read this project's active instructions, current context, task, and latest handoff. Do not edit.
Report: (1) the current objective and acceptance criteria; (2) one important project rule,
with its exact source file; (3) the latest accepted decision; (4) the next concrete action; (5)
conflicts, stale facts, or missing access. Separate what the files establish from what you
infer. Do not rely on a previous conversation.Como verificar: a resposta tem 5 itens numerados e cada um nomeia um arquivo do projeto. "Separate what the files establish from what you infer" é a parte mais importante: ela obriga o agente a confessar o que inventou.
Novo aqui? "Sessão nova" quer dizer um processo do agente que começa do zero, sem memória da conversa anterior. No Claude Code é claude -p "..."; no Codex é codex exec "...". Tudo o que o agente sabe do projeto tem que vir dos arquivos que ele lê naquela hora.
Conceitos-chave
Teste de continuidade: sessão nova responde 5 perguntas citando arquivos.
O que os arquivos dizem, separado do que o agente deduziu.
O prompt não diz onde estão os arquivos; a ordem de leitura precisa funcionar sozinha.
Readback só lê. Um agente que "corrige" durante o teste contamina a evidência.
🧪 readback-test.sh: claude -p e codex exec
Colar o prompt na mão funciona, mas cansa e não deixa rastro. O kit tem um script que faz as duas execuções em sequência, dentro da pasta do projeto, e salva a resposta bruta de cada runtime em relatorios/. O veredito continua sendo seu: o script marca "não rodado" só quando o runtime não existe na máquina.
Objetivo: rodar o readback nos dois runtimes contra um projeto seu e guardar a evidência.
cd ~/projetos/agente-claude-codex
scripts/readback-test.sh ~/projetos/<seu-projeto> both
# → claude (sessão nova em /home/.../<seu-projeto>)
# salvo: relatorios/readback-claude-2026-09-14.md (25 linhas)
# → codex exec (sessão nova em /home/.../<seu-projeto>)
# salvo: relatorios/readback-codex-2026-09-14.md (386 linhas)Como verificar: os dois arquivos existem em relatorios/ e têm mais de uma dúzia de linhas. Se um deles só tem um aviso do harness, aquele runtime conta como não rodado, mesmo que o arquivo exista. Troque <seu-projeto> pela pasta real; both pode virar claude ou codex para rodar um só.
Por dentro, o script é simples: extrai o prompt do arquivo de prompts, entra na pasta do projeto, chama claude -p e depois codex exec --skip-git-repo-check, e redireciona a saída. A parte que importa está no que ele não faz: não força sandbox no Codex. A primeira versão forçava -s read-only e o teste falhou antes de ler qualquer arquivo. Você vai ver esse caso no tópico 5.
✓ O script faz
- ✓Roda cada runtime numa sessão nova, dentro da pasta do projeto.
- ✓Salva a resposta bruta com data no nome, pra virar evidência versionada.
- ✓Marca "não rodado" quando o binário não existe, em vez de falhar.
- ✓Imprime o critério de aprovação no final, pra você ler com a resposta ao lado.
✗ O script não faz
- ✗Não dá o veredito. Um arquivo com 386 linhas pode ser uma reprovação.
- ✗Não edita nada no projeto, nem quando o agente sugere correções.
- ✗Não força sandbox: respeita o
sandbox_modedo~/.codex/config.toml. - ✗Não roda em loop. Cada
codex execgasta cota da conta OpenAI.
💡 Dica prática
Rode o readback logo depois de terminar o núcleo (módulo 2.3) e de novo depois de portar a skill (módulo 2.4). O primeiro mede o contexto; o segundo mede se a skill instalada mudou alguma coisa na resposta. Se a resposta for idêntica, a skill não está sendo descoberta pelo runtime.
Conceitos-chave
Modo não interativo do Claude Code: recebe o prompt, responde, sai.
Equivalente no Codex CLI; --skip-git-repo-check evita recusa fora de repo.
Evidência datada e versionada; sem ela o teste "não aconteceu".
Cada execução custa; rode por projeto, não por curiosidade.
🔎 Ler a resposta: cita os arquivos certos?
A resposta chega como texto longo. Não leia como prosa: leia como checklist. Para cada uma das cinco perguntas, você procura três coisas: o item existe, ele nomeia um arquivo do projeto, e o conteúdo bate com o que está no arquivo. A quarta pergunta tem um critério a mais: a próxima ação citada tem que ser a mesma que está em tasks/current.md.
Três degraus que muita gente confunde: o arquivo existir e o agente ter lido são necessários, mas só o terceiro, a resposta usar o conteúdo e bater com ele, conta como evidência.
Objetivo e critério de pronto
Tem que vir de tasks/current.md. Se o agente descreve o objetivo pelo README, a tarefa atual não está sendo lida.
Regra com arquivo-fonte
Precisa nomear AGENTS.md (ou o CLAUDE.md que importa dele). Regra sem fonte é palpite.
Última decisão aceita
Vem de context/decisions/. Resposta boa distingue "proposta" de "aceita", como os dois runtimes fizeram no caso real.
Próxima ação
Deve bater com tasks/current.md e com handoffs/latest.md. Se os dois divergem, o agente deve dizer isso na pergunta 5.
Conflitos e acesso faltando
A parte mais valiosa. Um agente que encontra inconsistências reais está lendo de verdade. Um que diz "nenhum conflito" num projeto recém-criado provavelmente não leu.
📋 Critério de aprovação, em uma linha
As cinco respostas citam AGENTS.md, tasks/current.md e handoffs/latest.md, e a próxima ação da resposta é a mesma da tarefa. Qualquer coisa a menos é reprovação, mesmo que a prosa esteja bonita.
Conceitos-chave
A unidade mínima de evidência: nome do arquivo + conteúdo que bate.
Existe → leu → usou. Só o último degrau prova.
Resposta = tasks/current.md = handoffs/latest.md.
Quem encontra inconsistência real está lendo.
🧾 O caso real: o Codex achou três furos no próprio kit
Em 13 de setembro de 2026 o readback foi rodado contra o próprio repositório do kit, minutos depois de ele ser criado. O resultado é o melhor argumento a favor do teste: os dois runtimes passaram, e cada um apontou problemas reais que quem escreveu o repo não tinha visto. Abaixo, trechos literais dos arquivos salvos em relatorios/.
Trecho real: relatorios/readback-codex-2026-09-13.md, pergunta 5.
5. Problemas encontrados:
- Falhou: leitura de handoffs/latest.md; arquivo ausente. Existe apenas o
modelo em template/handoffs/latest.md.
- Conflito documental: PLANO.md diz que nenhum readback foi rodado;
context/current-state.md diz que a primeira execução ocorreu.
- Ambiguidade: os grupos de skills no plano somam 94, embora o gap
declarado seja 89; sobreposição não é explicada.
- Não rodado: validação dos runtimes, drift e teste da cópia isolada.
Nenhum arquivo foi editado por mim.O que isso prova: o Codex leu PLANO.md, context/current-state.md e a matriz de skills, cruzou os três e achou uma soma errada (73+17+4 = 94, não 89), um handoff que só existia como template e uma frase contraditória. Os três foram corrigidos naquela sessão.
Trecho real: relatorios/readback-claude-2026-09-13.md, pergunta 5 (a resposta veio em inglês; o conteúdo é o que importa).
5. Conflicts, stale facts, missing access.
- The working tree has six modified files and an untracked handoffs folder,
all uncommitted. The handoff's "estado aceito" says "repo criado, commit
inicial", which does not reflect these later edits.
- There is no git remote configured, so the open question about publishing
to inematds/agente-claude-codex is unresolved and a push is currently
impossible. The local git email is already the correct inematds address.
- Branch is master, while the environment lists main as the main branch.O que isso prova: o Claude foi além dos arquivos Markdown e olhou o estado do git. Edições não commitadas e branch master foram corrigidas no commit seguinte; o remote foi criado quando o dono autorizou a publicação.
1ª rodada no Codex: falhou antes de ler
O script forçava -s read-only; o sandbox bwrap não sobe neste host por causa do AppArmor. Resposta inteira dizia "não consegui ler os arquivos".
Correção mínima e 2ª rodada: passou
Removido o flag; o script passou a respeitar o sandbox_mode do config. O Codex citou AGENTS.md, PLANO.md e tasks/current.md e apontou os três furos.
Claude: passou e achou dívida de git
Citou AGENTS.md, context/decisions, tasks/current.md e handoffs/latest.md, e listou o que estava fora do lugar no repositório.
Handoff atualizado com a evidência
Cada check entrou em handoffs/latest.md como passou, falhou ou não rodado, com o número da rodada. O próximo agente lê isso, não a conversa.
Repare: os dois runtimes concordaram nas perguntas 1 a 4 e discordaram só no que cada um resolveu investigar a mais. É exatamente o que se espera de um núcleo portátil bom: o contexto é o mesmo, o executor muda.
Conceitos-chave
Trecho da resposta salva, não resumo de memória.
Soma errada, arquivo ausente, frase contraditória: coisas que o autor não viu.
Cada execução tem número; "passou na 2ª rodada" carrega a história.
Concordância nas 4 primeiras perguntas é o sinal de portabilidade.
🧯 FALHAS.md: uma linha por falha
Toda falha que o readback expõe vira uma linha num arquivo na raiz do projeto: data, o que quebrou, a menor correção possível, e se a causa foi prompt (você pediu de um jeito que induziu o erro) ou infra (máquina, rede, serviço, permissão). Depois de umas dez linhas o padrão aparece sozinho, e você para de reconstruir coisas que só precisavam de uma proteção.
Arquivo real: FALHAS.md do kit, as duas linhas que saíram desta sessão de readback.
# Falhas (mais recente no topo)
| data | o que quebrou | menor correção | prompt \| infra |
|---|---|---|---|
| 2026-09-13 | readback-test.sh forçava `-s read-only` no codex exec; bwrap falha por AppArmor neste host | remover o flag, respeitar sandbox_mode do config.toml | prompt \| infra |
| 2026-09-13 | resumo do audit.sh contava linhas da seção 3 (73+17+4=94 ≠ 89) | restringir grep à seção 2.1 | prompt |Como usar: copie o cabeçalho pro seu projeto. Escreva a linha ao terminar de corrigir, antes de partir pra próxima tarefa. Se a correção foi "reescrever tudo", provavelmente era só um guard, um retry ou uma validação que faltava; registre isso.
✓ Linha boa
- ✓Uma linha, sem narrativa. Detalhe longo vira arquivo separado e linkado.
- ✓Correção nomeada como ação mínima: "remover o flag", "restringir grep".
- ✓Marca as duas causas quando são as duas, como no caso do sandbox.
- ✓Mais recente no topo, pra bater o olho e ver o padrão.
✗ Linha ruim
- ✗"Deu erro no Codex, refiz o script." Sem o quê, sem a correção mínima.
- ✗Escrita no fim da sessão, de memória, três falhas de uma vez.
- ✗Sem classificar prompt ou infra: perde a informação que mais ensina.
- ✗Guardada só na conversa, que o próximo agente não vê.
Novo aqui? "Sandbox" é um cercadinho que o Codex cria com uma ferramenta chamada bwrap para o agente não mexer fora da pasta. "AppArmor" é um módulo de segurança do Linux que, nesta máquina, proíbe a técnica que o bwrap usa. Resultado: o cercadinho não sobe e o agente não lê nada. A correção não foi "consertar o Linux", foi parar de forçar o cercadinho num host onde ele não funciona.
Conceitos-chave
Um teto, um retry, um guard, uma validação. Raramente uma reescrita.
Você induziu o erro, ou a máquina/serviço falhou. Às vezes os dois.
Ao terminar de corrigir, antes da próxima tarefa. Nunca no fim da sessão.
Depois de ~10 linhas, você vê o que sempre quebra e protege antes.
🚦 Quando marcar passou, falhou ou não rodado
Os três estados são a gramática de todo relatório deste curso, e o terceiro é o mais importante. Não rodado não é vergonha: é honestidade. O erro grave é o oposto, marcar "passou" num check que ninguém executou porque o arquivo "parecia certo". A prompt library é explícita: um arquivo legível, um import bem-sucedido ou uma sintaxe válida não são prova de comportamento equivalente.
✓ Passou
O check foi executado, o resultado foi observado e atende ao critério. Tem arquivo de evidência ou saída de comando pra mostrar.
✗ Falhou
Executado, observado, não atende. Fica registrado com o motivo e vira linha no FALHAS.md. Uma reprovação preservada vale mais que uma aprovação inventada.
— Não rodado
Não foi executado, por falta de runtime, de tempo, de decisão do dono ou de cota. Anota o passo exato pra reproduzir depois.
Exemplo real: bloco "Checks rodados e resultado" do handoffs/latest.md do kit, depois do readback.
## Checks rodados e resultado
- scripts/audit.sh — passou (89 skills só no Claude: 71 reutilizáveis, 15 adaptador, 2 nativo, 1 sem SKILL.md).
- scripts/adapt-instructions.sh ~/.claude --dry-run — passou (71 linhas portáteis, 7 resíduo Claude).
- template/scripts/check.sh — passou.
- scripts/readback-test.sh . codex — passou na 2ª rodada (1ª falhou por sandbox bwrap; corrigido).
- scripts/readback-test.sh . claude — passou: citou AGENTS.md, context/decisions, tasks/current.md e handoffs/latest.md.
- scripts/sync-skills.sh — não rodado (aguarda escolha do piloto).
- Cópia isolada + check.sh — não rodado.Repare: os dois "não rodado" estão lá, com o motivo. Quem abrir a próxima sessão sabe exatamente o que falta, e não descobre na hora errada que "sync-skills" nunca foi testado.
⚠️ O erro a evitar
Declarar "migração completa" enquanto um fluxo obrigatório está "não rodado". A prompt library manda o contrário: recomende o menor passo restante, nunca uma reescrita especulativa do sistema inteiro.
Conceitos-chave
Passou, falhou, não rodado. Sem quarto estado.
"Passou" sem arquivo ou saída de comando é "não rodado" disfarçado.
Todo "não rodado" vem com o comando exato pra rodar depois.
O relatório termina com uma ação, não com um plano de reescrita.
Auto-checagem (opcional): o readback no Codex devolveu 380 linhas, bem escritas, mas nenhuma cita tasks/current.md. Como você marca?
🎯 Resumo do módulo
Próximo módulo:
2.6 — Handoff e prime: o ciclo diário