1Explicar demais também atrapalha

Pergunte algo simples e a IA devolve doze tópicos. Tudo parece útil, nada diz por onde começar. Quem está aprendendo sai mais perdido do que entrou.

Marta, professora do 4º ano, perguntou como montar uma roda de leitura de 30 minutos. Recebeu uma aula inteira sobre teoria da leitura antes do primeiro passo prático.

2"O validador passa" não é prova

Este é o hábito mais caro. Em palavras simples: a IA diz "testei, deu certo" sem ter testado direito. Ela afirma com segurança que algo funciona, sem ter conferido do jeito certo. O caso abaixo aconteceu no piloto real do mentor do Nei, dentro do Claude Code.

Um validador conferia se o mentor tinha escrito a previsão antes de rodar o código. A sessão de trabalho rodou o validador sem o registro da conversa e disse "passa". Rodado de fora, com o registro, ele reprovou.

3Supor sem avisar e falar no genérico

Quando falta informação, a IA completa com o caso mais comum e não conta que fez isso. E quando você queria o jeito de um especialista, ela responde com a média da internet.

Rui, consultor de vendas, perguntou como responder a um cliente que achou o preço alto. Ele segue há anos o método de Otávio Lessa, um especialista em vendas consultivas.

4Por que um mentor, e não mais um pedido

Escrever um pedido melhor ajuda, mas não basta. No piloto, nem a instrução explícita "preveja antes de rodar" fez a IA mudar. Só mudou quando entrou um mecanismo que obrigava.

O mentor que você vai montar neste curso junta três coisas. Ele aprende só com o que o especialista publicou. Cada regra dele mostra o trecho de onde saiu. E ele só diz "funciona" depois de rodar.

1Método é o que a pessoa faz, persona é como ela soa

Persona é o jeito de falar: bordões, piadas, sotaque. Método é o que a pessoa faz quando ensina: por onde começa, o que confere, quando para. O mentor copia só o método.

Ele também nunca se apresenta como a pessoa nem escreve em nome dela. É um aluno muito aplicado do acervo, não um sósia.

Rui acompanha há anos Otávio Lessa, um especialista fictício em vendas consultivas. Ele não quer uma imitação que fale "como o Otávio". Quer alguém que faça as perguntas que o Otávio faria antes de uma proposta.

2O domínio cabe numa frase estreita

O domínio é o assunto que o mentor ensina. Quanto mais largo, mais ele volta a falar no genérico. Uma boa frase começa com "ensinar a", seguida de uma tarefa que dá para cercar.

Marta escolheu a professora Helena Duarte, especialista fictícia em avaliação escolar. A primeira frase dela foi larga demais. A segunda cabe num acervo.

3O escopo real do mentor do Nei

Kit é o conjunto de arquivos prontos da comunidade INEMA que cria o mentor; você o baixa na aula 3. Ele guarda essa decisão num arquivo chamado ESCOPO.md. Veja como ficou no piloto, com o próprio Nei como especialista e o Claude Code como assunto.

Repare que a lista de fora é curta e concreta. Ela protege a pessoa e evita que o mentor finja ser ela.

4Escolha alguém que publicou o bastante

O mentor só aprende com o que a pessoa publicou. Sem material, não há regra com prova. Para treinar, o kit sugere de 20 a 50 fontes e cerca de 50 mil palavras.

Pode ser uma pessoa real que você acompanha; os nomes desta aula são inventados só para o exemplo.

Rui conferiu antes de decidir: o Otávio tem dezenas de vídeos e um blog antigo. A Marta viu que a Helena tem livros, palestras gravadas e artigos.

1Confira as três ferramentas antes

Tudo nesta aula acontece no terminal. O kit precisa de três ferramentas no computador: Python, git e o Claude Code, que você já abriu antes.

Para abrir: no Windows, procure "PowerShell" no menu Iniciar; no Mac, procure "Terminal" no Spotlight; no Linux, aperte Ctrl+Alt+T. Abre uma janela com uma linha piscando. Ali você cola o comando e aperta Enter.

Marta abriu o terminal do notebook da escola e digitou os dois comandos abaixo. Cada um respondeu com um número de versão.

$ python3 --version
Python 3.12.3
$ git --version
git version 2.43.0

2Primeiro comando: baixar o kit

O kit fica num repositório público no GitHub. O comando abaixo baixa uma cópia dele para a sua pasta pessoal.

Rui colou o comando no terminal do escritório. Em poucos segundos apareceu a pasta mentor-especialista dentro da pasta dele.

$ git clone https://github.com/inematds/mentor-especialista.git ~/mentor-especialista
Cloning into '/home/rui/mentor-especialista'...
done.

3Segundo comando: criar o mentor

Agora entra o script novo-mentor.py. Ele pede um slug, o nome do especialista e a frase de domínio que você escreveu na aula 2.

Marta usou o slug helena e colou a frase de domínio que tinha guardado nas Notas. Veja a resposta real do kit.

$ python3 ~/mentor-especialista/novo-mentor.py helena --nome "Helena Duarte" --dominio "ensinar a montar a avaliação de uma unidade no ensino fundamental" --destino ~/mentores
Mentor criado em /home/marta/mentores/mentor-helena

Próximos passos:
  1. cd /home/marta/mentores/mentor-helena
  2. Preencha ESCOPO.md (fontes) e ajuste mentor.config.json (metas, transcritor)
  3. Abra o Claude Code nessa pasta e rode, em ordem:
       /helena-coletar
       /helena-compilar
       /helena-regras

4O que cada pasta guarda

Dentro de mentores/mentor-helena nasceu uma estrutura pronta. Você não precisa decorar. Basta saber onde mora cada parte.

A pasta .claude começa com ponto, por isso fica oculta no gerenciador de arquivos. As três peças que você vai conferir moram nela: o agente, as seis skills e o portão de execução, que é um hook.

1Cada tipo de fonte tem o seu coletor

Um coletor é um programa pequeno do kit que busca o texto de uma fonte e guarda numa pasta do mentor. Eles já vieram na pasta criada na aula 3; não há nada a acrescentar. São quatro: um para vídeo, um para página da internet, um para código publicado e um para arquivo que você já tem.

A lista de fontes mora no ESCOPO.md, na pasta do mentor. Cada linha diz o tipo, a origem e o coletor.

Rui monta o mentor de Otávio Lessa, consultor fictício de vendas consultivas. A tabela dele ficou assim: palestras em vídeo, artigos do blog e os posts que o Otávio publica toda semana.

2Legenda primeiro, transcrição só se faltar

Quase todo vídeo já tem legenda, feita pela própria plataforma. O coletor de vídeo pede só essa legenda, sem baixar o vídeo. Por isso é rápido.

Quando o vídeo não tem legenda, o coletor chama um transcritor que roda no seu computador. Funciona, mas leva minutos por vídeo. Sem transcritor configurado, o vídeo vai para o relatório de falhas.

O piloto do mentor do Nei mostra a diferença em números reais.

Marta monta o mentor de Helena Duarte, especialista fictícia em avaliação escolar. Das 12 palestras da Helena, 11 tinham legenda. Ela deixou a única sem legenda para o fim.

3Sem coletor? Exporte e entregue o arquivo

Posts de rede social, livro e anotações de palestra não têm coletor automático. Existem serviços que coletam posts em massa, mas cobram por uso. Esse tipo de serviço se chama API, e o kit não chama nenhuma API paga.

O caminho é manual. O mais simples: abra o perfil, copie os posts e cole num arquivo .txt do bloco de notas. Depois entregue esse arquivo ao coletor de arquivos, num comando no terminal.

Rui copiou 40 posts do Otávio para um arquivo chamado posts-otavio.txt. Um comando colocou tudo no acervo.

$ python3 tools/coletar_arquivo.py posts-otavio.txt --tipo posts --origem "posts copiados em 2026-10"
ok   6120 pal.  raw/posts/posts-otavio.txt

1Toda coleta deixa três rastros

O texto coletado vai para a pasta raw, separado por tipo. Ao mesmo tempo, o coletor escreve uma linha no manifesto, o arquivo MANIFESTO.json.

Cada linha guarda o hash do arquivo. O que falhou vai para o RELATORIO-FALHAS.md, com o motivo. Nada some em silêncio.

2O stats.py diz quanto falta

As metas de coleta ficam no arquivo de ajustes do mentor: quantos itens e quantas palavras por tipo. O stats.py soma o acervo e compara. Termina com exit 0 quando tudo bate.

Se algo falta, termina com exit 1 e escreve o motivo. No piloto, as lives passaram, mas 6 guias somaram 7.269 palavras, contra a meta de 8.000.

$ python3 tools/stats.py
tipo          itens   palavras   meta
guia              6       7269   ≥5 itens / ≥8000 pal.
video            13     169937   ≥10 itens / ≥60000 pal.
TOTAL            19     177206

REPROVADO:
  - meta não batida em 'guia': faltam 731 palavras

A sessão não maquiou o resultado. Relatou a reprovação e sugeriu fontes extras. Com mais 1 guia e a live transcrita, a coleta fechou com 21 itens e 187.382 palavras.

Marta viu "faltam 3 item(ns)" em vídeo. Acrescentou três palestras da Helena no ESCOPO.md e coletou de novo.

3Os dois defeitos que o piloto achou

O primeiro: o kit mandava coletar cada fonte num subagente, todos ao mesmo tempo. Mas o manifesto não tinha trava. Dois escrevendo juntos, um apaga a linha do outro.

A própria sessão percebeu, rodou um coletor por vez e explicou por quê. Você não precisa fazer nada: vale como exemplo de IA que avisa em vez de fingir. O segundo defeito: a live transcrita foi salva como transcript.txt. A próxima transcrição escreveria por cima dela.

Rui pediu a coleta dos 30 vídeos do Otávio de uma vez. Com a trava, o manifesto terminou com 30 entradas, e o stats.py confirmou.

1Acervo cru não é memória

A coleta das aulas 4 e 5 guardou tudo, sem edição, na pasta raw. No piloto do Nei, eram 22 fontes e cerca de 189 mil palavras. É fala de live, com repetição, piada e frase cortada no meio.

O Claude Code não consegue ler 189 mil palavras de uma vez com atenção. Ele precisa de um resumo organizado, que caiba na frente dele. Esse resumo organizado, que funciona como um fichário, é a wiki.

Rui coletou 30 vídeos do Otávio Lessa, um consultor fictício de vendas consultivas. Ao perguntar "como o Otávio abre uma reunião?", o mentor sem wiki citou só o último vídeo lido. Com a wiki, ele abriu a página do método e trouxe as 6 fontes que tratam disso.

2O cru fica intocável, e o hash denuncia

A wiki pode ser reescrita quantas vezes for preciso. O acervo cru, nunca. Se alguém "corrige" uma fala no cru, a prova de onde veio cada ideia some.

Para travar isso, a coleta gravou no manifesto um hash de cada arquivo. O script de conferência do kit, o stats.py, recalcula a impressão digital e compara. Rode depois de qualquer mexida na pasta.

Marta apagou um palavrão de uma transcrição da Helena Duarte, uma especialista fictícia em avaliação escolar. Ela achou que era só uma limpeza. A conferência acusou o arquivo na hora. Ela pediu ao Claude Code: "desfaça a minha edição neste arquivo", e o aviso sumiu.

$ python3 tools/stats.py
  - raw alterado depois da coleta (sha256 diferente): raw/guia/makeshorts-fabrica-de-shorts-com-ia-70fe54.md

3Compilar: quatro tipos de página

Transformar o cru em wiki se chama compilar. O kit traz uma skill para isso: /<slug>-compilar. O slug é o nome curto que você deu ao mentor na aula 3. Ele aparece no nome da pasta: mentor-otavio tem o slug otavio.

Cada página responde a uma pergunta. Fonte: o que esta live diz? Tema: o que ele sabe sobre um assunto, como preço. Princípio: o que ele defende de novo e de novo. Método: como ele faz, passo a passo.

Com acervo grande, a skill divide o trabalho entre subagentes, cada um com um lote de fontes. No piloto do Nei, 5 subagentes escreveram 73 páginas em 3,3 minutos.

Na wiki do Otávio, Rui achou um princípio que ele mesmo repetia aos clientes: "proposta só depois do diagnóstico assinado". A página citava 4 vídeos diferentes.

4Pronto é o validador terminar sem erro

A sessão pode dizer "wiki pronta" sem estar. Por isso o kit traz um validador de ligações. Ele confere se todo link leva a uma página que existe e se toda fonte do manifesto ganhou página.

O resultado sai em exit 0 quando está tudo certo. Com problema, ele lista cada link quebrado e termina em exit 1.

$ python3 tools/validar_links.py
76 páginas, 1307 links, 22 fontes
OK: 0 links quebrados

Na primeira rodada, o validador de Marta acusou 3 links quebrados. Ela colou a lista de volta na conversa e pediu a correção. Na segunda rodada, terminou em 0.

1A porta de entrada mostra o que pesa

O mentor não abre as 76 páginas a cada pergunta. Ele começa pelo hot.md: a página de abertura da wiki, com a lista dos assuntos mais citados. Ela fica na pasta wiki do mentor. O número entre parênteses diz quantas fontes falam daquilo.

Ler a hot é o jeito mais rápido de julgar a wiki. Se o topo da lista não tem a cara do especialista, o resto também não vai ter.

Marta abriu a hot do mentor da Helena Duarte, uma especialista fictícia em avaliação escolar. O primeiro item era "devolutiva antes da nota (12)". Ela reconheceu na hora.

2Toda ligação vai e volta

Cada página de fonte aponta para as ideias que ela sustenta. Cada ideia aponta de volta para as fontes. Quando falta a volta, o mentor acha a ideia mas não sabe de onde ela veio. Aí ele afirma sem poder mostrar a prova.

Desde a versão 1.3 do kit, o validador de ligações cobra a ida e a volta. Ligação de mão única vira erro e o resultado deixa de ser exit 0.

$ python3 tools/validar_links.py
mão única: subagentes → fontes/video-transcript, mas a fonte não liga de volta

Rui ingeriu um vídeo novo do Otávio Lessa, consultor fictício de vendas. A página nova apontava para "diagnóstico antes da proposta", mas ninguém reabriu essa página. O validador acusou a volta que faltava.

3É a pessoa ou é a IA genérica?

Aqui entra o seu julgamento. Leia o enunciado de uma página de princípio e pergunte: isto caberia em qualquer manual da área? Se sim, é genérico.

Página da pessoa tem trecho literal, exemplo do mundo dela e um limite que só quem pratica conhece. Página genérica tem lista de boas práticas sem nenhum caso.

Marta achou na wiki da Helena: "valorize o progresso de cada aluno". Bonito e vazio. Outra página dizia "a rubrica com três níveis vai para a turma antes da prova". Essa era a Helena.

4Confira o trecho no acervo

O teste final é procurar a frase no raw. Se ela está lá, a página tem prova. Se não está, alguém inventou, e quase sempre foi a IA.

$ grep -rl "Arquivo existir não é prova" raw/
raw/guia/agente-claude-codex-migrar-do-claude-pro-codex-ou--ac8311.md
$ grep -rl "Sempre revise seu trabalho" raw/
$

Como fazer: troque o texto entre aspas por 4 ou 5 palavras da página e rode no terminal, dentro da pasta do mentor. O $ não se digita. Saiu um nome de arquivo: a frase existe. Não saiu nada: a frase não existe no acervo.

1Frase de efeito soa bem, mas não diz o que fazer

Até aqui você juntou o acervo e montou a wiki. Agora vem a terceira fase do método: tirar dali as regras. O kit define assim: regra é o que a pessoa faz de forma recorrente ao ensinar ou construir.

Frase de efeito é o contrário. Cabe num slide, todo mundo concorda, e ninguém sabe o que fazer na próxima tarefa.

Marta, professora de ciências, monta o mentor da Profa. Helena Duarte, autora fictícia de livros sobre avaliação. "Avaliar é um ato de cuidado" aparece em todo lugar. Mas a conduta da Helena é outra: devolver a prova com um comentário em cada questão errada, antes de mostrar a nota.

2Toda regra mora num bloco do regras.md

As regras ficam num arquivo da pasta do mentor, o regras.md. Cada regra é um bloco com cinco linhas, sempre na mesma ordem. Este é um bloco real do mentor do Nei.

Rui, consultor de vendas, leu a linha 5 e entendeu o ponto. Uma regra que não muda a resposta do mentor não serve para nada, por mais bonita que seja.

3Fundir o que é igual, cortar o que não muda nada

A wiki costuma dizer a mesma conduta de três jeitos. Você não faz três regras: faz uma só, e os três trechos viram provas dela. Depois vem o corte.

O teste do corte é uma pergunta: "se eu apagar esta regra, a próxima resposta do mentor muda em quê?". Se você não aponta a mudança, corte. O mentor lê o arquivo inteiro antes de cada resposta, e regra fraca dilui as fortes.

Rui monta o mentor de Otávio Lessa, consultor fictício de varejo que ele acompanha há anos. Na wiki apareceram três frases parecidas e um bordão de abertura.

4As 10 regras do Nei começam com um verbo

No mentor real do Nei, a fase de regras saiu em 1,1 minuto com 8 regras. Depois que um guia novo entrou no acervo, viraram 10, com 40 citações. Não precisa entender cada uma. Repare só que toda regra começa com um verbo de trabalho.

Marta compara com a lista dela. "Toda criança aprende" não começa com verbo de trabalho e cai. "Pedir que o aluno explique o erro com as próprias palavras" fica.

1Citação é cópia, não resumo

Na aula 8 você viu que cada regra do regras.md traz trechos como prova. Esses trechos saem da pasta raw, palavra por palavra, com o caminho do arquivo. Pulou a aula 8? Basta saber isso.

Marta pediu as regras da Profa. Helena Duarte, a autora fictícia de livros sobre avaliação. Uma citação veio bonita demais. Ela abriu o livro transcrito e a frase não estava lá.

2O status conta fontes diferentes

A linha status diz quanta prova a regra tem. Ativa exige trechos de pelo menos dois arquivos diferentes. Banco tem uma fonte só e espera a segunda. Inferência não tem citação, e o mentor avisa o aluno quando usa.

Rui tinha três trechos do Otávio Lessa sobre retorno em 24 horas, todos do mesmo vídeo. Marcou a regra como ativa e o validador barrou. Três trechos de um vídeo continuam sendo uma fonte.

$ python3 tools/validar_citacoes.py
10 regras (10 ativas), 39 citações encontradas, 0 faltando
REPROVADO:
  - R9: 'ativa' exige ≥2 fontes diferentes (tem 1) — mova para 'banco'

3Um programa procura cada trecho no arquivo

O kit traz um script em Python que faz a conferência. Você roda um comando no terminal, e ele lê cada citação e procura o trecho no arquivo indicado.

Ele perdoa acento, maiúscula, pontuação e marca de tempo da legenda. Não perdoa palavra trocada, a mais ou fora de ordem. No piloto, trocamos uma frase verdadeira da R10 por uma inventada.

$ python3 tools/validar_citacoes.py
10 regras (10 ativas), 40 citações encontradas, 0 faltando
OK
$ python3 tools/validar_citacoes.py --regras regras-teste.md
10 regras (10 ativas), 39 citações encontradas, 1 faltando
REPROVADO:
  - R10: citação não encontrada em raw/guia/agente-claude-codex-…md: "Handoff nunca é permissão para nada."

O fim também conta. Aprovado sai com exit 0; reprovado sai com exit 1. Na aula 11, o mentor usa esse sinal para não dizer "funciona" sem ter rodado.

4Salve antes de testar

No mentor do Nei, alguém estragou o próprio regras.md para testar. Para desfazer, usou o comando de voltar do git. Só que as regras novas ainda não tinham virado um commit. O comando voltou o arquivo para a versão antiga e apagou as regras.

Rui adotou a regra para tudo. Antes de testar, ele faz uma cópia. Se a cópia quebra, ninguém perde nada.

1Seis títulos, sempre na mesma ordem

O mentor mora no Claude Code. Quando você pede uma tarefa com código, ele responde com seis títulos fixos. A ordem vem das instruções que o kit gravou no seu mentor na aula 3. Você não precisa mexer nelas.

Os seis são: Pronto, Menor versão, Previsão, Saída real, Versão quebrada e Relatório. Se um título falta, você já sabe onde olhar.

Marta montou o mentor de uma autora fictícia, a professora Helena Duarte, que escreve sobre avaliação. Ela pediu uma planilha de notas por bimestre. A resposta veio com os seis títulos, e Marta conferiu cada um antes de usar.

2Pronto vem antes de qualquer código

A lição real desta aula saiu do piloto do Nei, o mentor de teste que o kit montou com as aulas e guias dele. Não importa entender o pedido, só o formato da resposta. O pedido foi um hook que não deixa o Claude Code encerrar a resposta enquanto a lista de tarefas tiver item aberto. A lista é um arquivo chamado TODO.md.

Antes de escrever uma linha, o mentor definiu o sucesso e também o critério de aborto: quando desistir para não ficar preso. Ele também escreve as suposições, o que deduziu sem você dizer.

Rui usa a mesma leitura no mentor dele. Quando a parte Pronto não tem limite de tentativas, ele já pede: "qual é o critério de aborto?".

3Previsão escrita, depois a saída real

A Previsão diz o que deve aparecer, com número, antes de rodar. A Saída real cola o que apareceu. Você compara as duas sem precisar entender o código.

Marta não lê programa. Mesmo assim, ela confere se a Previsão dizia "2 itens" e se a Saída real mostra 2 itens. Bateu, ela segue. Não bateu, ela pergunta por quê.

4A versão quebrada mostra o perigo

A primeira versão, a ingênua, funcionava nos casos simples. O mentor então testou um item que ele não consegue fechar sozinho: "aguardar aprovação do cliente". Simulou 6 tentativas seguidas de encerrar.

A versão ingênua bloqueou as 6. Numa sessão real, ela giraria para sempre: um laço sem fim. A correção ganhou um teto de 3 bloqueios.

Rui reconhece o mesmo risco no trabalho dele: um lembrete de cobrança que insiste sem limite irrita o cliente. Por isso ele procura essa parte primeiro.

1Código escrito e não rodado segura a resposta

O kit liga no seu mentor o portão de execução. Ele é um hook: anota cada arquivo de código criado ou mudado. Quando o arquivo roda, a anotação some.

Se o Claude Code tenta encerrar com anotação pendente, o portão devolve a vez a ele com um recado. O recado aparece no terminal, a janela onde o Claude Code conversa com você.

Rui pediu ao mentor dele uma conta de comissão. O mentor escreveu o arquivo e quis encerrar. O portão devolveu a vez, o mentor rodou a conta e só então mostrou o total.

> Crie o arquivo teste_portao.py com um print e NÃO rode.
Criei o teste_portao.py.
Stop hook error occurred: Você escreveu código e não rodou:
teste_portao.py. Rode cada um (ou os testes) e mostre a saída
real antes de dizer que funciona.

2O aviso assusta, mas é a trava

O Claude Code rotula esse bloqueio como "Stop hook error occurred". Parece erro do kit. No piloto, o Nei anotou isso como problema de mensagem, e o kit passou a explicar o aviso no guia.

Marta viu o aviso pela primeira vez e quase fechou tudo. Leu a linha de baixo, viu o nome do arquivo e entendeu: faltava rodar. Esperou, e o mentor rodou sozinho.

3O que não conta como rodar

Rodar é executar o arquivo e ver a saída. Algumas ações parecem trabalho, mas não executam nada. O portão ignora todas elas.

Uma é guardar uma cópia datada com o git. Essa cópia se chama commit. Guardar não é testar.

Marta pediu uma planilha de notas. O mentor abriu o arquivo, leu o conteúdo e guardou um commit. Nada disso rodou a planilha, e o portão segurou a resposta.

$ ls                          # lista arquivos: não roda
$ cat notas.py                # abre e lê: não roda
$ git commit -m "notas"      # guarda cópia: não roda
$ python3 -m py_compile notas.py  # só checa: não roda
$ python3 notas.py            # executa: este conta

4Uma trava, não uma prisão

O portão bloqueia no máximo uma vez por arquivo editado. Se o pedido diz "não rode", o mentor explica e encerra na segunda tentativa. Foi o que aconteceu no piloto.

Pedidos sem código também passam livres. No piloto, "agora só liste os arquivos" não teve bloqueio nenhum.

Rui pede ao mentor um resumo de uma reunião com cliente. Não há código, então o portão nem aparece.

> Agora só liste os arquivos com ls.
CLAUDE.md  ESCOPO.md  raw  regras.md  teste_portao.py  wiki

1Três tarefas fixas, iguais para todo mentor

O validador só é justo se a prova for sempre a mesma. Por isso o kit guarda os testes numa pasta própria do seu mentor. Ninguém muda as tarefas no meio do caminho.

O teste 1 pede uma lição sobre algo que você não domina. O teste 2 entrega um código que parece funcionar e quebra em outro computador. O teste 3 pede para o mentor aprender uma fonte nova.

Marta montou o mentor de Helena Duarte, uma especialista fictícia em avaliação escolar. Antes de usar o mentor nas aulas, ela abriu a pasta de testes para ver o que ia ser cobrado.

2Teste 1: peça algo que você não domina

A lição é pedida com a skill de ensinar, dentro do Claude Code. Escolha um assunto em que você não saberia dizer se a resposta está certa. Assim o mentor não se apoia no que você já sabe.

No piloto, o Nei pediu um hook que impede a sessão de encerrar enquanto a lista de pendências tiver item aberto. Veja o começo da lição.

Rui fez o mesmo com o mentor de Otávio Lessa, um consultor fictício de vendas consultivas. Pediu uma planilha de previsão de fechamento por etapa do funil, coisa que ele nunca tinha montado.

3O validador confere de fora

A skill salva a lição em testes/respostas/. Depois, no terminal, um script em Python lê o arquivo. Ele confere se as cinco partes estão lá e se toda regra citada existe.

Com o registro da sessão junto, ele confere mais uma coisa: se houve execução real, e se a previsão veio antes dela. Aprovado termina em exit 0; reprovado, em exit 1.

Marta rodou o validador na lição do mentor de Helena sobre rubrica de redação. Saiu exit 1: faltava a parte "Versão quebrada". Ela pediu só essa parte de novo.

$ python3 tools/validar_resposta.py testes/respostas/2026-10-05-hook-stop-todo.md --transcript logs/teste1.jsonl
execuções Bash no transcript: 14
seções exigidas: 5, regras citadas: R1 … R8
OK: resposta seguiu o loop
$ echo $?
0

mkdir -p logs && cp "$(ls -t ~/.claude/projects/*/*.jsonl | head -1)" logs/teste1.jsonl

4O placar do piloto: 4 de 5 antes de 5 de 5

O teste só conta se você também aprendeu algo. O Nei anotou o dele: um bloqueio sem teto prende a sessão para sempre quando o item não depende da IA.

O placar tem cinco critérios. Na primeira passada, o teste 2 ficou parcial: o mentor reproduziu e corrigiu, mas não escreveu a previsão antes de rodar. A próxima aula conta como isso foi resolvido.

Rui anotou no arquivo de resultados do mentor de Otávio: "teste 1, passou, aprendi que a previsão por etapa erra se eu não separar cliente novo de renovação".

1O teste 2 e por que prever importa

O teste 2 entrega um script com emojis que funciona no computador comum. No terminal comum ele termina em exit 0. Num console do Windows em cp1252, ele quebra. ele quebra e termina em exit 1. No UTF-8, roda liso.

Quem escreve o que espera antes de rodar mostra que entendeu. Quem escreve depois só descreve o que viu. Por isso o teste exige a previsão primeiro.

Marta faz isso nas aulas de ciências: cada aluno escreve o palpite antes do experimento. Sem o papel, depois do resultado, todo mundo "já sabia".

$ python3 testes/aceitacao/script_emoji.py
✅ 3 perguntas salvas em relatorio.txt
exit=0
$ PYTHONIOENCODING=cp1252 python3 testes/aceitacao/script_emoji.py
UnicodeEncodeError: 'charmap' codec can't encode character '\U0001f50e'
exit=1

2Rodadas 1, 2 e 3: a instrução não bastou

Na rodada 1, a skill de revisão só sugeria prever. O mentor reproduziu a quebra e corrigiu, mas não escreveu a previsão antes. O kit 1.2 passou a exigir uma seção "Previsão".

Na rodada 2 o mentor escreveu as cinco seções. Na rodada 3 recebeu a ordem explícita: "escreva uma linha Previsão: antes do primeiro comando". Nas duas, rodou primeiro e escreveu a previsão depois.

Rui conhece isso da equipe de vendas. O vendedor só preenche a previsão do mês na planilha depois que o cliente já assinou.

3Rodada 4: o portão nega a execução

O kit 1.3 trouxe o portão de previsão. É um hook que olha cada comando antes de o Claude Code rodá-lo. Ler e listar arquivos passa direto. Executar código só passa com uma previsão já escrita na conversa.

Ele é irmão do portão de execução da aula 11. Um cobra rodar; o outro cobra prever antes de rodar.

Rui ligou o portão no mentor de Otávio Lessa, um consultor fictício de vendas consultivas. Ao revisar a planilha de comissões, o mentor teve um comando negado e escreveu a previsão antes de rodar.

4Quem confirma é o validador, de fora

O placar não fechou porque o mentor disse que acertou. Fechou porque o validador leu o registro da sessão e achou a previsão antes da primeira execução.

1Um link novo vira páginas e regras

A skill de ingerir, chamada dentro do Claude Code, recebe um link do especialista que ainda não está no acervo. Ela guarda o texto, cria a página da fonte na wiki e liga a fonte aos conceitos. Também anota tudo no diário da wiki, o log.md.

No piloto, o Nei ingeriu um guia novo sobre usar dois agentes de IA juntos. Levou 2,4 minutos.

Helena Duarte, a especialista fictícia do mentor de Marta, publicou um vídeo novo sobre avaliar alunos que ainda não leem sozinhos. Marta colou o link na skill de ingerir.

2Regra nova, com prova, e conferida de fora

R9 e R10 já nasceram ativas porque a segunda fonte para cada uma já estava no acervo. Cada regra, no regras.md, traz as frases do especialista e de onde vieram.

Depois de ingerir, rode os três validadores: o do acervo, o dos links e o das citações. Os três precisam terminar em exit 0.

Rui ingeriu no mentor de Otávio Lessa, consultor fictício de vendas consultivas, um artigo sobre renovação de contratos. O validador de citações acusou uma frase que não estava na fonte. Ele pediu ao mentor para corrigir só aquela citação, conferindo na fonte, e rodou de novo.

3Atualizar o kit sem tocar no conteúdo

Quando sai versão nova do kit, você baixa a novidade e, no terminal, roda o gerador com a opção de atualizar. Ele troca as ferramentas, o agente, as skills e os portões. Seu acervo, sua wiki e suas regras ficam como estão.

Antes, salve o estado da pasta com um commit do git. Na aula 9 você viu o porquê: no piloto, regras não salvas se perderam num teste.

Rui estava no kit 1.2. Com a atualização, o mentor de Otávio ganhou o portão de previsão da aula 13, e as 6 regras dele continuaram iguais.

$ cd ~/mentor-especialista && git pull
$ python3 novo-mentor.py --atualizar ~/mentores/mentor-otavio
Mentor otavio atualizado para o kit 1.3.0: … arquivo(s)
Versões anteriores em .mentor/backup-<data> (se você tinha personalizado o agente, compare).
Não mexi em: raw/, wiki/, regras.md, ESCOPO.md, CLAUDE.md, testes/respostas/.

4Vários mentores: cada um com o núcleo dele

Com um mentor funcionando, dá vontade de montar outros e consultar todos juntos. O agente lê o regras.md, o hot.md e o index.md pela pasta dele. Copiar só o arquivo do agente para outro lugar deixa o mentor sem núcleo: ele volta a responder no genérico.

Marta montou um segundo mentor, de um autor fictício de literatura infantil. Ela chama cada um na pasta dele e compara as duas lições lado a lado.