🎚️ Reconheça quando a IA explica demais ou de menos
O primeiro mau hábito é de calibragem. Você pergunta uma coisa pontual e recebe uma aula de seis seções, com história, alternativas e ressalvas. Ou o contrário: pede para entender e recebe só o código pronto, sem o porquê. Nos dois casos você sai mais perdido do que entrou. A IA não sabe o que você já sabe, e também não pergunta.
🆕 Novo aqui?
Claude Code é o assistente da Anthropic que roda no terminal: lê os arquivos da pasta, escreve código e executa comandos no seu computador. Mentor, neste curso, é um agente dentro do Claude Code que ensina no método de um especialista: em vez de despejar resposta, ele constrói junto com você e prova o que diz. O kit que monta esse mentor se chama Mentor-Especialista.
Como ler: as duas pontas em ciano são onde a IA cai sozinha. O centro em verde é estreito de propósito: ele só existe quando a explicação começa numa menor versão que roda e avança um passo de cada vez. É por isso que o loop do mentor tem um passo chamado "Menor versão".
✓ Explicação calibrada
- ✓Começa dizendo o que é "pronto" para aquela dúvida
- ✓Mostra a menor peça que roda, antes de empilhar o resto
- ✓Cada passo novo vem com a saída real que ele produziu
✗ Explicação descalibrada
- ✗Arquivo inteiro de uma vez, "agora é só colar"
- ✗Três alternativas e nenhuma recomendação
- ✗Teoria longa antes de qualquer coisa rodar
Calibragem
Partir do que você já sabe
Menor versão
Uma peça que roda
Um passo
Uma coisa de cada vez
Sintoma
Sair mais perdido
🎭 Desconfie da resposta que parece certa sem estar
O segundo hábito é o mais caro. O tom da resposta não muda com a qualidade dela: a IA diz "funciona" com a mesma segurança quando rodou e quando só imaginou que rodaria. Para quem está aprendendo, não há como separar as duas coisas pelo texto. A única saída é a prova: o comando que rodou e a saída que voltou.
🆕 Novo aqui?
Validador é um script pequeno que confere uma coisa e responde sim ou não, sem opinião.
Exit code é o número que todo comando devolve ao terminar: 0 quer
dizer "deu certo", qualquer outro número quer dizer "falhou". Você vê o último com echo $?.
Transcript é o registro completo da sessão do Claude Code: tudo o que foi pedido, rodado e respondido.
🔬 Caso real do piloto: "o validador passa"
No piloto com o mentor do Nei, o teste 2 pedia para revisar um script que funciona mas quebra em certas condições. Na segunda rodada aconteceu exatamente este hábito:
O mentor faz a revisão completa
Reproduz o erro, corrige, prova lado a lado. As cinco seções estão lá.
Mas roda antes de prever
Escreve "Vou ler… sem executar nada", executa, e depois anota "A previsão se confirmou".
A sessão declara: "o validador passa"
Ela tinha rodado o validador sem o log da sessão, ou seja, sem a parte que confere a ordem.
O validador de fora, com o transcript, reprova
A falha que a própria sessão chamou de OK foi pega por quem olhou de fora, com a prova completa.
⚠️ A lição
"Funciona", vindo da própria IA, é afirmação, não evidência. Isso vale até para o mentor bem montado. Por isso o kit tem verificação de fora (validadores que você roda) e, no Claude Code, um portão que não deixa o turno terminar com código escrito e não executado. Você vai montar os dois nas trilhas 4 e 5.
Tom ≠ acerto
Segurança não é sinal
Prova
Comando + saída real
De fora
Quem confere não é quem fez
Exit code
0 passou, resto falhou
🤫 Peça para a IA dizer o que ela supôs
Todo pedido tem buracos. Onde fica o arquivo? O que acontece se ele não existir? Até quando tentar? A IA preenche cada buraco com a escolha mais plausível e segue em frente sem te contar. Quando o resultado não bate com o que você queria, você nem sabe em que ponto a conversa se separou.
📄 Como o mentor do piloto faz
No teste 1, o pedido foi "me ensina a fazer um hook Stop que bloqueia enquanto o TODO.md tiver itens abertos". Antes de escrever uma linha de código, a resposta do mentor abriu assim (trecho real):
Suposições (não estavam no pedido): - O TODO.md fica na raiz do projeto ($CLAUDE_PROJECT_DIR). - Se o arquivo não existir, o turno termina normalmente. - O hook bloqueia no máximo 3 vezes seguidas por sessão. Esse é o critério de aborto.
Três decisões que o pedido não tomava, agora visíveis. Se alguma estiver errada para você, dá para corrigir antes de qualquer código existir.
🆕 Novo aqui?
Hook é um script que o Claude Code dispara sozinho num momento fixo da sessão. O hook Stop roda quando o Claude vai encerrar a resposta e pode dizer "ainda não, falta isto". Critério de aborto é a regra de quando desistir, para nada ficar girando para sempre.
✓ Suposição declarada
- ✓Listada antes do código, numa seção própria
- ✓Cada uma vira um critério que dá para testar
- ✓Você pode trocar qualquer uma no começo
✗ Suposição escondida
- ✗Aparece só dentro do código, como um caminho fixo
- ✗Você descobre quando quebra no seu caso
- ✗Ninguém sabe se foi decisão ou acidente
🧪 Exercício copiável: arranque as suposições
Objetivo: ver quantas decisões um pedido curto esconde. Funciona no Claude Code comum, sem o mentor.
Quero <descreva aqui uma tarefa pequena que você faria hoje>. Antes de escrever qualquer código, liste numa seção "Suposições (não estavam no pedido)" cada decisão que você teria de tomar sozinho. Para cada uma, diga a escolha que faria e como eu verificaria se ela está certa. Pare depois da lista e espere a minha resposta.
Como verificar: conte os itens da lista. Se você não tinha pensado em pelo menos um deles, o hábito estava lá, invisível. Corrija o que estiver errado e só então peça o código.
Buraco
Decisão que o pedido não tomou
Declarar
Antes do código
Testável
Suposição vira critério
Aborto
Quando desistir
🌫️ Troque o conhecimento genérico por um acervo real
O quarto hábito é responder com a média da internet. A resposta não está errada, mas é de ninguém: não traz o jeito de um especialista que você confia, os atalhos dele, os erros que ele já cometeu e não repete. O mentor resolve isso ancorando cada regra num trecho real do que a pessoa publicou.
🆕 Novo aqui?
Acervo é tudo o que o especialista publicou, coletado numa pasta (o kit chama de raw/): legendas de vídeos, textos de blog, guias, repositórios. Wiki é esse acervo compilado em páginas curtas e ligadas entre si (princípios, métodos, temas), para a IA consultar sem se perder. Citação com localizador é um trecho copiado do acervo mais o endereço exato dele, como arquivo@00:12:30.
Como ler: à esquerda, a resposta para no modelo; não tem de onde veio. À direita, a regra aponta para uma citação e a citação aponta para um endereço que você abre e confere. A seta verde é a diferença inteira: rastreabilidade.
📌 Uma regra real do mentor do Nei
## R1 — Conferir o resultado real antes de dizer "pronto"
- status: ativa
- citacoes:
- "ele passou dizendo que tinha OK, mas não"
— raw/videos/inema-vibecode-do-zero-dia-3-basico-de-infra.txt@02:38:55
- "Arquivo existir não é prova. O agente ter lido e usado é."
— raw/guia/agente-claude-codex-migrar-do-claude-pro-codex-ou--ac8311.md
Repare: a regra não é uma frase bonita sobre qualidade. É um comportamento que aparece em várias fontes diferentes, e cada aparição tem endereço. No piloto, o Nei deu nota 8 de 10 para "reconheço a pessoa nas regras".
Média
Resposta de ninguém
Acervo
O que a pessoa publicou
Localizador
Endereço do trecho
Reconhecível
"É ela, não IA genérica"
🧭 Entenda por que um mentor, e não mais um prompt
Dá para escrever um prompt pedindo "explique na medida, não suponha, prove o que diz". Ajuda por uma conversa, e some na seguinte. Prompt é instrução; o piloto mostrou que instrução sozinha não segura comportamento. O mentor troca instrução por quatro peças com mecanismo, cada uma atacando um hábito.
🆕 Novo aqui?
Prompt é o texto que você manda para a IA. Skill é uma receita salva em arquivo que o Claude Code carrega quando você chama, por exemplo, /nei-ensina. Subagente é uma segunda instância do Claude, com contexto próprio, que recebe uma tarefa e devolve o resultado. Mecanismo, aqui, é algo que roda sozinho e não depende de a IA lembrar da instrução.
Como ler: siga cada fio verde. Dois hábitos caem no mesmo lugar, o loop: ele começa definindo "pronto" e listando suposições, e anda em menor versão. O "parece certa" só cai com algo que roda sem pedir licença: o portão. O genérico cai com acervo e regras citadas. Nenhuma peça é "um prompt melhor".
| Peça | O que faz | Trilha |
|---|---|---|
| Acervo + wiki | Tudo o que o especialista publicou, compilado em páginas ligadas que a IA consulta sem se perder | 2 e 3 |
| Regras com prova | Cada regra de conduta tem citação + localizador, conferidos por script | 4 |
| Loop obrigatório | Pronto → menor versão → previsão → saída real → versão quebrada → relatório por regra | 5 |
| Portão de execução | Um hook impede o turno de terminar se houve código escrito e não executado | 5 |
🧪 Copie e rode: veja um mentor passando nos validadores
Objetivo: antes de construir o seu, ver as peças funcionando no exemplo/ do kit, um mentor completo de uma especialista fictícia (a Profa. Lia), com 3 fontes e 7 regras. Precisa só de Python 3.10+ e git.
git clone https://github.com/inematds/mentor-especialista.git cd mentor-especialista python3 exemplo/tools/stats.py --raiz exemplo; echo "stats exit=$?" python3 exemplo/tools/validar_citacoes.py --raiz exemplo; echo "citacoes exit=$?"
Como verificar: as duas linhas finais devem mostrar exit=0. O primeiro confere o acervo (metas e integridade de cada item); o segundo procura cada citação das regras dentro do acervo. Quer ver o validador reprovar? Abra exemplo/regras.md, troque uma palavra dentro de uma citação, rode de novo (deve mostrar 1 faltando e exit=1) e desfaça com git checkout exemplo/regras.md.
Instrução
Some na próxima conversa
Mecanismo
Roda sem a IA lembrar
4 peças
Acervo, regras, loop, portão
Gabarito
O exemplo/ do kit
🧠 Deixe a IA fazer o trabalho, mas guarde o entendimento para você
A IA pode fazer o trabalho pesado. Compreender continua sendo tarefa de quem usa. O mentor existe para você entender, não só para receber código pronto. Na prática, isso aparece em dois lugares da resposta: a previsão (você vê o que se espera antes de rodar) e a seção "Sua vez", em que o mentor devolve um exercício para você fazer com as próprias mãos.
🎯 "Sua vez" real, do teste 1 do piloto
Depois de construir o hook Stop com você, o mentor fechou assim (trecho real):
No seu próprio projeto (R6): 1. Copie a pasta .claude/ da sandbox e crie um TODO.md com 2 itens. 2. Mude a regex para ignorar - [ ] que estejam dentro de blocos de código. Antes de rodar, escreva quantos itens você espera que o hook liste. 3. Rode o hook e compare com a sua previsão. 4. Critério de pronto: o item dentro do bloco de código não aparece no reason, e os itens de fora aparecem. Você tem 3 tentativas.
Note os ingredientes: a tarefa é sua (não do mentor), pede previsão antes de rodar, tem critério de pronto verificável e um limite de tentativas. É o mesmo loop que o mentor segue, agora na sua mão.
Pronto
O que é "terminado", antes de tocar no código.
Menor versão e previsão
A peça mínima que roda, e o resultado esperado dito antes de rodar.
Saída real e versão quebrada
Rodar de verdade, comparar, e mostrar uma variação que quebra com a causa explicada.
Relatório e "Sua vez"
Passo → o que rodou → o que saiu → regra que guiou. E o exercício que devolve o trabalho para você.
💡 O que o Nei aprendeu no próprio teste
No teste 1, o mentor mostrou a versão ingênua do hook em loop infinito: com um item que o agente não consegue fechar sozinho, ela bloqueou 6 de 6 tentativas. A correção foi um teto de 3 bloqueios por sessão. O registro do piloto diz: "Aprendi: o bloqueio sem teto prende a sessão para sempre". É isso que se espera de um mentor: que você saia sabendo algo que não sabia.
Checagem rápida (não bloqueia nada): a sessão do Claude diz "rodei o validador e passou". O que você faz?
Trabalho
Pode ser da IA
Entendimento
É sempre seu
Sua vez
Exercício com critério de pronto
Aprender algo
A medida de um bom mentor
📌 Resumo do Módulo
Próximo Módulo:
1.2 - Método não é persona: o que copiar do especialista, o domínio numa frase e o seu primeiro mentor gerado.