Une explication ici est une chaîne causale dans les mots de l'utilisateur : quelques phrases courtes où chaque affirmation porte sa raison, construites à partir des termes que l'utilisateur utilise déjà, lues d'une traite, à haute voix si nécessaire.
1. Recueillir les mots de l'utilisateur
L'explication s'attache à ce que l'utilisateur connaît, et ce qu'il connaît se voit dans les mots qu'il tape. Avant d'expliquer un sujet pour la première fois dans une session, lisez comment il en a parlé :
python3 <dossier de cette compétence>/user_words.py <mot-clé> [<mot-clé> ...]
python3 <dossier de cette compétence>/user_words.py --all-projects <mot-clé> ...
Cela affiche les messages que l'utilisateur a tapés dans des sessions Claude précédentes contenant un mot-clé, les plus récents en premier, pour le projet actuel ou pour tous. Choisissez des mots-clés dans sa question et dans le sujet (noms de composants, outils, la chose qui échoue). Ajoutez ses messages de la conversation en cours.
À partir de cela, notez trois choses :
- ses termes : le mot qu'il utilise pour chaque chose (« zweiter SSH-Weg », « incoming IP », « proxied »). Utilisez exactement ceux-ci, même là où le code ou la documentation les nomme différemment.
- terrain connu : ce qu'il a énoncé ou utilisé correctement. Une chaîne peut s'y terminer.
- lacunes : des termes du sujet qu'il n'a jamais utilisés. Chacun est un nouveau mot.
Terminé lorsque chaque terme dont l'explication a besoin est classé comme son terme, ou nouveau mot.
2. Écrire la chaîne
- Problème d'abord. La première phrase nomme le problème ou la réponse elle-même : « Le problème est X. » Lorsque l'utilisateur a posé une question directe (« à quoi sert ce mot de passe ? »), la première phrase répond exactement à cette question.
- Chaque affirmation porte sa raison. Attachez la raison dans la même phrase avec parce que / puisque / dû à / par. Un effet énoncé seul est un maillon ouvert : « toutes les connexions viennent de 127.0.0.1 » n'explique rien tant que « fail2ban bloque par IP » ne se trouve pas à côté.
- Chaîner jusqu'au terrain connu. Suivez les « parce que » jusqu'à ce que le dernier soit un terrain connu. Arrêtez-vous là.
- Ses termes, le mécanisme lui-même. Énoncez le mécanisme réel littéralement, dans ses termes. Les analogies, images et inventions fantaisistes sont exclues.
- Nouveaux mots entre parenthèses. Un nouveau mot apparaît une fois avec des mots-clés entre parenthèses juste après, puis sans parenthèses : « HostKeyAlias (option SSH : vérifie la clé d'hôte par rapport à une autre entrée dans known_hosts) ». Mots-clés, pas une phrase.
- Prose parlée. Trois à cinq courtes phrases déclaratives, un lien par phrase, dans l'ordre cause à effet. Un texte courant simple qui survit à la synthèse vocale : pas de titres, tableaux ni listes à puces à l'intérieur de l'explication.
Pour l'architecture, la chaîne suit le chemin d'une requête ou d'un changement : quelle partie agit, ce qu'elle transmet à la suivante, pourquoi la suivante peut ou ne peut pas faire son travail avec cela.
3. Nommer les corrections
Le vocabulaire et les hypothèses de l'utilisateur sont vérifiés par rapport au code et aux faits, et chaque écart est nommé — après la chaîne, une ligne chacun, comme « tu dis … / en réalité … , parce que … » :
- vocabulaire que le code ne porte pas : il dit « Passkey », c'est une entrée de trousseau ; il dit « le Runner tombe en panne », le runner est un conteneur et Docker échoue. Donnez le nom qu'utilise le code ou l'outil, afin que sa prochaine question et sa prochaine recherche aboutissent.
- hypothèse erronée : quelque chose qu'il prend pour acquis mais qui n'est pas vrai (« j'ai besoin de ce mot de passe pour la connexion »). Dites ce qui tient à la place et son parce que.
Vérifiez contre le code ou le système avant de corriger ; une correction de mémoire est une supposition. Continuez à utiliser son terme ensuite seulement là où il était correct.
Modèle
Un propre vocabulaire de l'utilisateur pour l'explication qu'il aurait dû recevoir (pourquoi fail2ban ne protège pas SSH derrière un tunnel Cloudflare). Les exemples ici sont en allemand ; expliquez dans la langue dans laquelle l'utilisateur écrit.
Le problème est le second chemin SSH par mot de passe. Avec le nom d'utilisateur et le mot de passe utilisateur du Mac, n'importe qui peut établir une connexion par brute force. fail2ban ne protège pas, parce qu'il s'agit d'un blocage basé sur l'adresse IP et qu'à travers le tunnel tout le monde a la même adresse IP entrante, puisque Cloudflare est en proxy.
Terminé quand
Avant d'envoyer, vérifiez chaque phrase :
- la première phrase nomme le problème ou répond à la question posée ;
- chaque affirmation a son « parce que » dans la même phrase ;
- le dernier « parce que » est un terrain connu pour cet utilisateur ;
- chaque terme est son terme, ou un nouveau mot avec sa parenthèse ;
- chaque formulation erronée et chaque hypothèse erronée dans sa question est nommée avec sa correction.
Lorsque l'utilisateur ne suit toujours pas, trouvez le seul lien dont le « parce que » manque et fournissez ce lien seul, en une phrase. Des valeurs concrètes (deux adresses IP, une requête) n'interviennent que là, pour fermer ce lien.
Ce qu'il faut faire ensuite (options, commandes, une recommandation) suit après l'explication, séparé de celle-ci, et seulement lorsque demandé ou nécessaire pour agir.