Eine Erklärung ist hier eine kausale Kette in den Wörtern des Users: einige kurze Sätze, in denen jede Behauptung ihren Grund trägt, aufgebaut aus den Begriffen, mit denen der User bereits arbeitet, in einem Durchgang lesbar, notfalls laut vorlesbar.
1. Die Wörter des Users sammeln
Die Erklärung knüpft an das an, was der User weiß, und was er weiß, zeigt sich in den Wörtern, die er tippt. Bevor Sie ein Thema zum ersten Mal in einer Sitzung erklären, lesen Sie, wie er darüber gesprochen hat:
python3 <dieser skill-ordner>/user_words.py <schlüsselwort> [<schlüsselwort> ...]
python3 <dieser skill-ordner>/user_words.py --all-projects <schlüsselwort> ...
Es gibt die Nachrichten aus früheren Claude-Sitzungen aus, die der User getippt hat und die ein Schlüsselwort enthalten, neueste zuerst, für das aktuelle Projekt oder für alle. Wählen Sie Schlüsselwörter aus seiner Frage und aus dem Thema (Komponentennamen, Werkzeuge, das, was fehlschlägt). Fügen Sie seine Nachrichten aus dem aktuellen Gespräch hinzu.
Notieren Sie daraus drei Dinge:
- seine Begriffe: das Wort, das er für jede Sache verwendet („zweiter SSH-Weg“, „incoming IP“, „proxied“). Verwenden Sie genau diese, auch wenn der Code oder die Dokumentation es anders nennt.
- bekannter Grund: was er richtig angegeben oder verwendet hat. Eine Kette kann dort enden.
- Lücken: Begriffe aus dem Thema, die er nie verwendet hat. Jeder davon ist ein neues Wort.
Fertig, wenn jeder Begriff, den die Erklärung benötigt, entweder seinem Begriff oder einem neuen Wort zugeordnet ist.
2. Die Kette schreiben
- Problem zuerst. Der erste Satz nennt das Problem oder die Antwort selbst: „Das Problem ist X.“ Wenn der User eine direkte Frage gestellt hat („wozu das Passwort?“), beantwortet der erste Satz genau diese Frage.
- Jede Behauptung trägt ihren Grund. Hängen Sie den Grund mit weil / da / durch im selben Satz an. Eine alleinstehende Wirkung ist ein offenes Glied: „alle Verbindungen kommen von 127.0.0.1“ erklärt nichts, bis „fail2ban sperrt nach IP“ danebensteht.
- Kette bis zum bekannten Grund. Folgen Sie den Weil-Sätzen, bis der letzte Grund dem User bekannt ist. Hören Sie dort auf.
- Seine Begriffe, der Mechanismus selbst. Geben Sie den tatsächlichen Mechanismus wörtlich in seinen Begriffen wieder. Analogien, Bilder und erfundene Darstellungen sind nicht erlaubt.
- Neue Wörter in Klammern. Ein neues Wort erscheint einmal mit Stichwörtern in Klammern direkt dahinter, dann nackt: „HostKeyAlias (SSH-Option: prüft den Host-Key gegen einen anderen Eintrag in known_hosts)“. Stichwörter, kein Satz.
- Gesprochene Prosa. Drei bis fünf kurze Aussagesätze, ein Glied pro Satz, in der Reihenfolge Ursache zu Wirkung. Klarer Fließtext, der Text-to-Speech übersteht: keine Überschriften, Tabellen oder Aufzählungspunkte innerhalb der Erklärung.
Für Architektur verläuft die Kette entlang des Pfads einer Anfrage oder einer Änderung: welcher Teil handelt, was er an den nächsten weitergibt, warum der nächste damit seine Aufgabe erfüllen kann oder nicht.
3. Die Korrekturen benennen
Die Formulierung und Annahmen des Users werden am Code und an den Fakten geprüft, und jede Abweichung wird benannt – nach der Kette, eine Zeile pro Abweichung, als „du sagst … / richtig ist … , weil …“ :
- Formulierung, die der Code nicht trägt: er sagt „Passkey“, es ist ein Schlüsselbund-Eintrag; er sagt „Runner fällt aus“, der Runner ist ein Container und Docker fällt aus. Geben Sie den Namen, den der Code oder das Werkzeug verwendet, damit seine nächste Frage und sein nächster Treffer ihn finden.
- falsche Annahme: etwas, das er als gegeben voraussetzt, was aber nicht stimmt („das Passwort brauche ich für die Verbindung“). Sagen Sie, was stattdessen gilt, und seinen Grund.
Überprüfen Sie am Code oder am System, bevor Sie korrigieren; eine Korrektur aus dem Gedächtnis ist eine Vermutung. Verwenden Sie seinen Begriff danach nur dort weiter, wo er richtig war.
Modell
Die eigene Formulierung des Users für die Erklärung, die er hätte bekommen sollen (warum fail2ban SSH hinter einem Cloudflare-Tunnel nicht schützt). Die Beispiele hier sind Deutsch; erklären Sie in der Sprache, in der der User schreibt.
Das Problem ist der zweite SSH-Weg per Passwort. Mit Username und Userpasswort des Macs kann jeder per Brute Force eine Verbindung herstellen. fail2ban schützt nicht, weil es IP-based Blocking ist und durch den Tunnel jeder dieselbe incoming IP hat, da Cloudflare proxied.
Fertig, wenn
Prüfen Sie vor dem Senden jeden Satz:
- der erste Satz nennt das Problem oder beantwortet die gestellte Frage;
- jede Behauptung hat ihren Grund im selben Satz;
- der letzte Grund ist dem User bekannt;
- jeder Begriff ist sein Begriff oder ein neues Wort mit seiner Klammer;
- jede falsche Formulierung und jede falsche Annahme in seiner Frage ist mit ihrer Korrektur benannt.
Wenn der User immer noch nicht folgt, finden Sie das eine Glied, dessen Grund fehlt, und liefern Sie nur dieses Glied in einem Satz. Konkrete Werte (zwei IPs, eine Anfrage) kommen nur dort hinein, um dieses Glied zu schließen.
Was als Nächstes zu tun ist (Optionen, Befehle, eine Empfehlung) folgt nach der Erklärung, getrennt von ihr, und nur, wenn danach gefragt oder zum Handeln nötig.