🔁 Seis seções, nesta ordem, com estes títulos
O arquivo do agente manda responder "com estas seções, nesta ordem e com estes títulos": Pronto → Menor versão → Previsão → Saída real → Versão quebrada → Relatório. O título exato importa porque quem confere a resposta depois é um script que procura cabeçalhos ## Pronto, ## Previsão e assim por diante.
Como ler: a Previsão está em ciano porque é a única seção com uma condição de tempo: ela precisa aparecer na conversa antes do primeiro comando que executa código. A seta tracejada mostra que a Versão quebrada não termina em "deu erro": a correção volta a ser rodada e comparada, como uma nova Saída real.
🆕 Novo aqui?
- Previsão é o palpite concreto, escrito, do que vai aparecer: "bloqueia e lista 2 itens", "exit 0". Sem número ou forma, não dá para comparar depois.
- Saída real é o que o terminal imprimiu, colado como está. Resumo do tipo "rodou certinho" não conta.
- Versão quebrada é uma variação feita para falhar (entrada ruim, caso de borda, outro ambiente), rodada de verdade, com a causa explicada.
Ordem fixa
Pronto vem primeiro
Título exato
O script lê cabeçalhos
Previsão antes
Condição de tempo
Toda tarefa
Que envolva código
🎯 Por que cada passo existe
Nenhuma seção está ali por estética. Cada uma barra um dos maus hábitos que você viu na trilha 1 e corresponde a uma regra do Nei (trilha 4). Quando o mentor pula uma seção, você sabe exatamente qual hábito voltou.
| Seção | Mau hábito que barra | Regra do Nei |
|---|---|---|
| Pronto | Supor sem avisar o que é "terminado" | R2 — critério de pronto e de aborto |
| Menor versão | Explicar demais: o projeto inteiro de uma vez | R7 — começar mínimo |
| Previsão | Rodar e depois dizer "era o esperado" | R3 — medir com e sem |
| Saída real | Parecer certo sem estar | R1 — conferir antes de dizer pronto |
| Versão quebrada | Mostrar só o caminho feliz | R8 — falhar cedo, na entrada |
| Relatório | Conhecimento genérico, sem rastro do método | Cada passo aponta a regra que guiou |
✓ Previsão que serve
- ✓"Bloqueia e lista 2 itens: criar ok.txt e subitem indentado. Exit 0."
- ✓"1/3, 2/3 e 3/3; a 4ª libera e a 5ª recomeça em 1/3."
✗ Previsão que não serve
- ✗"Deve funcionar."
- ✗"A previsão se confirmou", escrito depois de rodar.
As duas previsões da esquerda são do teste 1 do piloto, escritas antes de rodar. A frase da direita, embaixo, é de uma rodada que o validador reprovou: o módulo 6.1 conta essa história.
🧑🏫 Seções do especialista: "Sua vez", "Custo" e cia.
As seis seções fixas são o esqueleto que todo mentor tem. O que dá a cara do especialista vem das regras: cada regra de regras.md tem uma linha - no mentor: dizendo onde ela aparece na resposta. Quando essa linha pede uma seção própria, o agente inclui essa seção além das fixas.
| Regra | Seção que a linha "no mentor" pede |
|---|---|
| R4 — menor custo | Custo: qual modelo/esforço usa e por quê; se a tarefa repete, sugere virar script |
| R5 — fundamento | Por baixo: uma linha sobre o mecanismo que vale para qualquer ferramenta |
| R6 — construir junto | Sua vez: termina com um exercício no projeto do aluno, não com a solução pronta |
| R7 — começar mínimo | Corte: ao revisar, aponta o que sai antes do que entra |
| R8 e R10 | Risco: o que faria falhar e, antes de passo irreversível, pede confirmação |
📎 O que aconteceu de verdade no piloto
- • A resposta do teste 1 trouxe uma seção ## Sua vez (vinda da R6) e um parágrafo "Por baixo (R5)" ligando o hook ao padrão de um gate de CI.
- • Na fase 3, o diário anotou o atrito: as regras pediam Custo, Sua vez, Por baixo e Risco, mas o agente do kit 1.1 tinha um loop fixo e o validador só cobrava as fixas.
- • A correção do kit 1.2: o agente lê as linhas "no mentor", e a skill /regras acrescenta essas seções a mentor.config.json → secoes_resposta, com no máximo 1 a 3 seções novas.
- • Atenção: o mentor.config.json do piloto ainda lista só as 5 seções fixas que o validador cobra (Pronto, Previsão, Saída real, Versão quebrada, Relatório). Se você quer que "Sua vez" seja cobrada, ela precisa entrar nessa lista.
🧪 Copie e rode: quais seções suas regras pedem?
Objetivo: comparar as seções pedidas pelas regras com as que o validador vai cobrar.
cd <pasta do seu mentor>
grep -n -- '- no mentor:' regras.md
python3 -c 'import json; print(json.load(open("mentor.config.json"))["secoes_resposta"])'
Como verificar: toda seção nomeada nas linhas "no mentor" que você quer cobrar deve aparecer na lista impressa. Se faltar, rode /<slug>-regras de novo (kit 1.2) ou acrescente à mão, sendo econômico.
🌐 Antes de responder: idioma do pedido e regras da casa
O loop começa antes do "Pronto". O agente tem uma lista de cinco coisas que faz sempre, antes de escrever a primeira linha. Duas delas nasceram de falhas do piloto.
Ler regras.md
Valem ativa e banco. Uma inferencia pode ser usada, avisando: "isto é inferência, não está nas fontes".
Consultar a wiki pela porta certa
hot.md → index.md → só as páginas necessárias. Nunca o raw/ inteiro; um arquivo do raw só para conferir uma citação.
Pedido vago? Perguntar de 1 a 3 coisas
Se precisar supor, a suposição vai escrita. No teste 1, o "Pronto" abriu com três suposições explícitas (onde fica o TODO.md, o que fazer sem ele, o teto de 3).
Responder no idioma do pedido, inclusive o resumo
Veio do piloto: no teste 1, a lição saiu em português e o resumo final da sessão saiu em inglês. Gravidade baixa, mas corrigida no kit 1.2.
Temporários em .mentor/tmp/, nunca em /tmp
Também do piloto: no teste 2, a revisão usou /tmp, fora do projeto. Agora tudo fica dentro do projeto e fora do git (.mentor/ está no .gitignore).
✓ O agente faz sempre
- ✓Lê regras.md e avisa quando usa inferência
- ✓Entra na wiki por hot.md e index.md
- ✓Pergunta de 1 a 3 coisas quando o pedido é vago
- ✓Responde no idioma do pedido; temporários em .mentor/tmp/
✗ Proibido, pelo próprio arquivo do agente
- ✗Dizer "funciona" sem uma "Saída real" que mostre isso
- ✗Citar a pessoa sem localizador (arquivo + trecho/tempo) que exista no raw
- ✗Entregar um bloco de código sem o caminho do loop
🪝 Lição real do teste 1: o hook que prendia a sessão
No teste 1 do piloto, o pedido ao /nei-ensina foi um hook de Stop que não deixa o turno terminar enquanto o TODO.md tiver linhas - [ ]. A sessão levou 0,9 min mais o subagente. A parte valiosa foi a Versão quebrada: um item que o agente não consegue fechar sozinho, como "aguardar aprovação do cliente".
Como ler: a linha vermelha é a v0 recebendo 6 eventos de parada seguidos, todos bloqueados. A linha verde é a correção: um contador por sessão com teto de 3, que é o "critério de aborto" escrito no Pronto (R2). Na 4ª ele libera e avisa; o laço infinito virou, no máximo, 3 insistências.
🧪 Copie e rode: reproduzir o teto de 3
Objetivo: simular 5 eventos de Stop contra o hook corrigido do piloto, sem abrir o Claude Code. O hook lê o JSON do evento pela entrada padrão (stdin), como o Claude Code faria.
cp -r <pasta do mentor-nei>/exemplos/hook-todo-stop ./sandbox-todo && cd sandbox-todo
printf -- '- [ ] aguardar aprovação do cliente\n' > TODO.md
for i in 1 2 3 4 5; do
echo '{"session_id":"aula","stop_hook_active":true}' \
| CLAUDE_PROJECT_DIR=$PWD python3 .claude/hooks/stop_todo.py 2>&1 \
| grep -o 'bloqueio [0-9]/3\|liberado após 3 bloqueios' | sed "s/^/tentativa $i -> /"
done
Como verificar: a saída deve ser exatamente esta (conferida antes de publicar a aula):
tentativa 1 -> bloqueio 1/3 tentativa 2 -> bloqueio 2/3 tentativa 3 -> bloqueio 3/3 tentativa 4 -> liberado após 3 bloqueios tentativa 5 -> bloqueio 1/3
Troque stop_todo.py por stop_todo_v0.py e rode de novo: as 5 tentativas bloqueiam. Essa é a versão quebrada.
💡 Dois detalhes que a resposta mediu, em vez de supor
- • CRLF: o mentor esperava que um TODO salvo no Windows quebrasse. Mediu e não quebrou: splitlines() já remove o \r. "Um medo a menos, confirmado pela medição" (R3).
- • Prova em sessão real: com claude -p "diga apenas oi" na sandbox, o hook obrigou o Claude a criar o ok.txt e marcar os itens com [x]. O mentor conferiu o arquivo, não só a fala do agente (R1).
✅ validar_resposta.py: a prova vem de fora
O mentor dizer que seguiu o loop não prova nada. Quem confere é tools/validar_resposta.py, um script de biblioteca padrão que lê a resposta salva e, se você der, o transcript da sessão.
🆕 Novo aqui? Transcript
É o registro completo da sessão que o Claude Code grava em disco, um arquivo .jsonl (uma linha JSON por evento) em ~/.claude/projects/<pasta do projeto>/<sessão>.jsonl. Nele está cada texto do assistente e cada comando Bash, na ordem em que aconteceram. Os subagentes da mesma sessão ficam em <sessão>/subagents/, e o validador também os lê.
(a) Seções
Todas as seções do perfil estão como cabeçalho? Perfil ensino lê secoes_resposta; revisao lê secoes_revisao.
(b) Regras
Cita ao menos uma regra (R1, R2…) e todas as citadas existem em regras.md.
(c) Transcript
Houve ≥1 Bash real, e um texto com "previs…" veio antes do 1º Bash que executa algo. Ler, listar e rodar os scripts do kit não contam.
🧪 Copie e rode: conferir uma resposta salva
Objetivo: dar a nota de fora para a última lição do seu mentor.
cd <pasta do seu mentor> ls -t ~/.claude/projects/*/*.jsonl | head -3 # ache o transcript da sessão python3 tools/validar_resposta.py testes/respostas/<arquivo>.md \ --transcript <caminho do .jsonl>
Como verificar: a última linha deve ser OK: resposta seguiu o loop e o exit, 0. No teste 1 do piloto, o validador contou 14 execuções Bash no transcript e passou. Se aparecer REPROVADO, cada linha com - diz o que faltou.
⚠️ Sem o transcript, metade da prova some
Rodado só com o arquivo da resposta, o validador confere títulos e regras, mas não a ordem "previu, depois rodou". No piloto, uma sessão afirmou "o validador passa" justamente porque o rodou sem o log. O módulo 6.1 mostra o que essa diferença revelou.
Checagem rápida: a resposta tem todas as seções com os títulos certos, mas o mentor escreveu "a previsão bateu" só depois de rodar. O que o validador faz com --transcript?
📌 Resumo do Módulo
Próximo Módulo:
5.3 - Skills: ensina, revisa, ingere. As três receitas de uso, com comandos para rodar.