Como ler: as três primeiras estações descrevem o que o mentor deve fazer; a quarta, em ciano, é o que impede que ele deixe de fazer a parte mais importante. A linha tracejada fecha o círculo: o portão não é uma peça à parte, ele mora no mesmo .claude/settings.json que você conhece no módulo 5.1.
Mapa da trilha
Conteúdo detalhado
🗺️ Mapa: settings, agente e skills
Onde cada peça mora em .claude/, quem chama quem, por que o portão escuta Stop e SubagentStop, e o que é do projeto e o que é global.
O mapa do comportamento do mentor: você dispara uma skill, a skill chama o subagente mentor, e um hook registrado no settings.json vigia tudo de fora.
Sem esse mapa, ajustar o mentor vira tentativa e erro: você edita o arquivo errado e não entende por que nada muda.
Hook é programa, não IA · Subagente tem contexto próprio · Skill é a receita disparada com /.
O arquivo .claude/settings.json que liga o portao-execucao.py aos eventos PostToolUse (matcher Write|Edit|MultiEdit|Bash), Stop e SubagentStop, com timeout de 10 s.
É a causa número um de "escrevi o hook e ele não faz nada": o script está na pasta, mas não está no registro.
Evento · matcher · $CLAUDE_PROJECT_DIR · timeout · JSON inválido = arquivo ignorado.
O arquivo do mentor: um cabeçalho (frontmatter) com nome e quando usar, e um corpo com o método, o loop obrigatório e as proibições.
O mentor roda como subagente para que quem ensina não seja quem dá a nota: a sessão principal confere de fora.
description é o gatilho · Contexto limpo · Método, não persona.
Uma pasta com SKILL.md; o nome da pasta vira o comando /nome. O kit traz 6: coletar, compilar e regras (construção); ensina, revisa e ingere (uso).
Saber o que é skill e o que é agente diz onde mexer: a receita na skill, o método no agente.
Skill roda na sessão principal · ensina e revisa chamam o mentor · ingere não chama.
Stop dispara quando a sessão principal vai encerrar o turno; SubagentStop, quando um subagente vai encerrar o dele. O mentor é subagente.
Se o portão escutasse só o Stop, o mentor entregaria código sem rodar e a barreira só apareceria depois, longe de quem escreveu.
Barrar perto de quem escreveu · stop_hook_active = "já insisti" · Hook de parada precisa de saída.
A diferença entre .claude/ do projeto (vale só ali) e ~/.claude/ (vale em todo lugar), com a árvore real do piloto: settings, 1 hook, 1 agente, 6 skills.
O mentor mora no projeto para que o portão vigie só ele; hook experimental vai para uma pasta separada, como o piloto fez no teste 1.
Projeto isola · Dois Stop hooks rodam juntos · Conferir a árvore gerada.
🔁 O loop obrigatório do mentor
Pronto → Menor versão → Previsão → Saída real → Versão quebrada → Relatório: por que cada passo existe, as seções do especialista, a lição real do teste 1 e o validador de fora.
O formato fixo de toda resposta com código: Pronto, Menor versão, Previsão, Saída real, Versão quebrada e Relatório.
Com títulos exatos, um programa consegue conferir a resposta; a nota deixa de depender da sua impressão.
Previsão = palpite concreto · Saída real = colada do terminal · Versão quebrada = falha provocada.
A ligação de cada seção com um mau hábito da trilha 1 e com uma regra do Nei: Pronto/R2, Menor versão/R7, Previsão/R3, Saída real/R1, Versão quebrada/R8.
Quando uma seção falta, você sabe qual hábito voltou e qual regra foi quebrada.
Previsão útil tem número · "A previsão se confirmou" depois de rodar não vale · Relatório aponta a regra.
Seções extras pedidas pelas linhas "no mentor:" das regras, como Custo (R4), Por baixo (R5), Sua vez (R6), Corte (R7) e Risco (R8, R10).
É o que diferencia um mentor de outro com o mesmo esqueleto. Só são cobradas se estiverem em secoes_resposta.
"no mentor:" · secoes_resposta · 1 a 3 seções novas, no máximo.
O que o mentor faz antes do Pronto: lê regras, consulta hot → index → páginas, pergunta se o pedido for vago, responde no idioma do pedido e usa .mentor/tmp/.
Duas dessas regras vieram de falhas do piloto: resumo em inglês numa lição em português e temporários em /tmp.
ativa/banco/inferência · Nunca o raw inteiro · Suposição escrita.
Um hook de Stop para TODO.md cuja versão ingênua bloqueou 6 de 6 vezes; a correção com contador por sessão libera na 4ª tentativa.
Mostra a Versão quebrada ensinando de verdade: bloqueio sem teto prende a sessão quando o item não depende do agente.
Critério de aborto · stop_hook_active · Medir em vez de supor (CRLF não quebrou).
O script que confere seções, regras citadas e, com --transcript, se houve execução real e se a previsão veio antes dela.
Autoavaliação não é prova. No teste 1, ele contou 14 execuções Bash e aprovou; sem o transcript, metade da checagem some.
Transcript .jsonl · Perfil ensino × revisao · Exit 0 = OK.
🧰 Skills: ensina, revisa, ingere
As três skills de uso com os resultados reais dos testes do piloto, as três de construção revisitadas, comandos para rodar e onde cada resposta fica.
A tabela das 6 skills com fase, "pronto quando" e o tempo medido no piloto (de 0,9 a 3,3 min por skill).
Todas terminam num script com exit 0: a skill não depende da própria palavra para dizer que acabou.
Exit code · Mesmo formato em todas · Só biblioteca padrão.
Repassa a dúvida ao mentor sem reescrever, salva a resposta, roda o validador e mostra um checklist de 1 linha por regra ativa.
Cada ✓ aponta um trecho da resposta; se houver ✗, o mentor corrige uma vez só. Nada de autoavaliação.
Repassar sem reescrever · R1 ✓ / R3 ✗ · Uma correção, não um laço.
Previsão (só lendo), Reprodução, Correção num arquivo .revisado ao lado, Lado a lado com a mesma entrada, e Relatório.
No teste 2, a revisão reproduziu o UnicodeEncodeError em cp1252 e achou um 2º ponto de quebra que o Nei não tinha previsto: o emoji dentro dos dados.
Original intacto · Mesma saída útil · Medir o tamanho, não supor.
Coleta, página de fonte, propagação na wiki, promoção de regras, controle (index, hot, log) e três validadores.
No teste 3, um guia novo virou 2 métodos e duas regras ativas (R9, R10) em 2,4 min: de 31 para 40 citações.
banco → ativa com a 2ª fonte · Links nos dois sentidos · log.md só acrescenta.
As fases 1 a 3 vistas como arquivos ajustáveis, com as correções do piloto: trava no manifesto, nome por título + ID, parágrafos de 30 s, seções no config.
Instrução que se repete pertence ao SKILL.md, não ao pedido do dia.
Ajuste a skill · Rode uma vez depois de editar · Nunca relaxe o validador.
Os três comandos prontos (ensina, revisa com o script_emoji.py, ingere) e a tabela de onde fica cada arquivo.
São os três testes de aceitação do mentor; rodar os três é o jeito de saber se o seu está pronto.
testes/respostas/ · <nome>.revisado.<ext> · .mentor/tmp/.
🚧 Portão de execução
O hook que transforma "não diga que funciona sem rodar" em mecanismo: estado por sessão, o que não conta como execução, anti-loop, a prova no piloto e como provocá-lo.
Um hook que responde {"decision": "block"} no evento de parada quando há código escrito e não executado.
Proibição em texto depende de o modelo lembrar; o portão não depende de obediência.
Exige execução, não julga resultado · Zero tokens · Erro interno = exit 0.
PostToolUse de Write/Edit marca o arquivo, PostToolUse de Bash limpa o que foi executado, Stop/SubagentStop bloqueia; tudo em .mentor/estado/<sessão>.json.
Entender o estado explica cada bloqueio e cada liberação, e mostra onde configurar extensões e pastas ignoradas.
Por session_id · Não lê o transcript · Estados de 7+ dias apagados.
A lista de comandos que o portão trata como leitura: ls, cat, git, rm, chmod, linters, py_compile, bash -n, node --check, tsc --noEmit e até cat | python3.
Um portão fácil de enganar é pior que nenhum: dá falsa segurança.
Sintaxe ≠ comportamento · pytest limpa todos os .py · Na dúvida, bloqueia.
Com stop_hook_active=true o portão libera e marca os sujos como avisados; o mesmo arquivo só volta a bloquear se for editado de novo.
É a lição do teste 1 aplicada ao próprio portão: hook de parada sem saída prende a sessão.
avisados · Reeditar reativa · Nunca derruba a sessão.
O rótulo que a interface mostra quando o portão bloqueia, e a prova real: uma sessão claude -p escreveu teste_portao.py sem rodar e foi barrada.
Quem não conhece o rótulo acha que o kit quebrou e desliga o portão justamente quando ele funcionou.
1 bloqueio, como desenhado · test_portao.py: 28 passed · 2º portão: previsão (kit 1.3) · Kit: 81 testes.
Dois exercícios: pedir ao Claude Code um calc.py "sem rodar" e simular os eventos JSON direto no terminal, lendo o estado no fim.
Só confie no portão depois de vê-lo bloquear; a simulação leva 30 segundos e não gasta nada.
Evento por stdin · CLAUDE_PROJECT_DIR · Mesmo session_id.