Uma explicação aqui é uma cadeia causal nas palavras do usuário: algumas frases curtas em que cada afirmação carrega sua razão, construída a partir dos termos com os quais o usuário já trabalha, lida de uma só vez, em voz alta se necessário.
1. Colete as palavras do usuário
A explicação se apega ao que o usuário sabe, e o que ele sabe se mostra nas palavras que digita. Antes de explicar um tópico pela primeira vez em uma sessão, leia como ele falou sobre ele:
python3 <pasta desta skill>/user_words.py <palavra-chave> [<palavra-chave> ...]
python3 <pasta desta skill>/user_words.py --all-projects <palavra-chave> ...
Isso imprime as mensagens que o usuário digitou em sessões anteriores do Claude que contêm uma palavra-chave, da mais nova para a mais antiga, para o projeto atual ou para todos. Escolha palavras-chave da pergunta dele e do tópico (nomes de componentes, ferramentas, a coisa que falha). Adicione as mensagens dele da conversa atual.
A partir disso, anote três coisas:
- seus termos: a palavra que ele usa para cada coisa ("segundo caminho SSH", "IP de entrada", "proxied"). Use exatamente estas, mesmo onde o código ou a documentação as nomeiem de forma diferente.
- terreno conhecido: o que ele afirmou ou usou corretamente. Uma cadeia pode terminar aí.
- lacunas: termos do tópico que ele nunca usou. Cada um é uma palavra nova.
Feito quando cada termo que a explicação precisa está classificado como termo dele ou palavra nova.
2. Escreva a cadeia
- Problema primeiro. A primeira frase nomeia o problema ou a própria resposta: "O problema é X." Quando o usuário fez uma pergunta direta ("para que serve a senha?"), a primeira frase responde exatamente essa pergunta.
- Cada afirmação carrega seu porquê. Anexe a razão na mesma frase com porque / já que / devido a / por. Um efeito declarado sozinho é um elo solto: "todas as conexões vêm de 127.0.0.1" não explica nada até que "fail2ban bloqueia por IP" esteja ao lado.
- Encadeie até o terreno conhecido. Siga os porquês até que o último seja terreno conhecido. Pare aí.
- Termos dele, o mecanismo em si. Declare o mecanismo real literalmente, nos termos dele. Analogias, imagens e invenções estão descartadas.
- Palavras novas entre colchetes. Uma palavra nova aparece uma vez com palavras-chave entre colchetes logo atrás, depois sem: "HostKeyAlias (opção SSH: verifica a chave do host contra outra entrada em known_hosts)". Palavras-chave, não uma frase.
- Prosa falada. Três a cinco frases curtas declarativas, um elo por frase, na ordem causa para efeito. Texto corrido simples que sobrevive à conversão texto-para-fala: sem cabeçalhos, tabelas ou listas de marcadores dentro da explicação.
Para arquitetura, a cadeia percorre o caminho de uma requisição ou de uma mudança: qual parte age, o que ela entrega à próxima, por que a próxima pode ou não pode fazer seu trabalho com aquilo.
3. Nomeie as correções
A formulação e as suposições do usuário são verificadas contra o código e os fatos, e cada desvio é nomeado – depois da cadeia, uma linha cada, como "você diz … / o correto é … , porque …":
- formulação que o código não suporta: ele diz "Passkey", é uma entrada do chaveiro; ele diz "Runner caiu", o runner é um contêiner e o Docker falhou. Dê o nome que o código ou a ferramenta usa, para que a próxima pergunta dele e o próximo resultado de busca dele acertem.
- suposição errada: algo que ele toma como dado que não é verdade ("preciso da senha para a conexão"). Diga o que vale em vez disso e seu porquê.
Verifique contra o código ou o sistema antes de corrigir; uma correção vinda da memória é um palpite. Continue usando o termo dele depois apenas onde ele estava certo.
Modelo
A própria formulação da explicação que o usuário deveria ter recebido (por que o fail2ban não protege SSH atrás de um túnel Cloudflare). Os exemplos aqui estão em alemão; explique no idioma em que o usuário escreve.
O problema é o segundo caminho SSH por senha. Com nome de usuário e senha de usuário do Mac, qualquer pessoa pode fazer uma conexão por força bruta. fail2ban não protege, porque é bloqueio baseado em IP e, através do túnel, todo mundo tem o mesmo IP de entrada, já que Cloudflare faz proxy.
Feito quando
Antes de enviar, verifique cada frase:
- a primeira frase nomeia o problema ou responde à pergunta feita;
- cada afirmação tem seu porquê na mesma frase;
- o último porquê é terreno conhecido para este usuário;
- todo termo é termo dele, ou uma palavra nova com seu colchete;
- toda formulação errada e suposição errada na pergunta dele é nomeada com sua correção.
Quando o usuário ainda não entender, encontre o elo cujo porquê está faltando e forneça apenas esse elo, em uma frase. Valores concretos (dois IPs, uma requisição) entram apenas aí, para fechar aquele elo.
O que fazer em seguida (opções, comandos, uma recomendação) vem depois da explicação, separado dela, e apenas quando solicitado ou necessário para agir.