Schreiben für Agenten
Der Leser von allem, was Sie mit diesem Skill schreiben, ist ein Agent, der nur den Text hat. Er hat die Unterhaltung nicht gesehen, kann nicht nachfragen, was Sie gemeint haben, und wird auf das reagieren, was die Worte sagen, wörtlich und mit vollem Einsatz. Die meisten Fehlschläge entstehen aus der Lücke zwischen dem, was Sie wissen, und dem, was auf der Seite steht. Arbeiten Sie also von der Position des Lesers aus: Legen Sie vor dem Schreiben fest, wo die Arbeit endet, in welcher Situation sich der Leser befindet und welches Material er benötigt; schreiben Sie es dann in Worten, die der Leser ohne Sie verwenden kann.
Zwei Arten von Eingaben
Eine grobe Anfrage ("Schreibe eine Anweisung, damit ein Agent den fehlerhaften Login-Test repariert"): Sammeln Sie die Fakten aus der Unterhaltung und dem Arbeitsbereich und entwerfen Sie dann von Grund auf neu.
Ein bestehender Prompt: Behalten Sie ihn. Nehmen Sie die kleinste Menge an Änderungen vor, die das tatsächliche Problem beheben, behalten Sie seine Struktur und Formulierung bei, wo sie funktionieren, und fügen Sie keine Anforderung hinzu, die der Autor nicht genannt hat. Eine vollständige Neufassung verbirgt, welche Änderung etwas bewirkt hat, und lässt stillschweigend die Absicht des Autors fallen. Die untenstehenden Standards gelten trotzdem: Wenn dem Prompt ein Rollensatz, ein Beispiel oder eine abschließende Prüfung fehlt, fügen Sie sie hinzu. Wenn Sie etwas hinzufügen, sei es eines dieser Dinge oder eine Regel, die eine echte Lücke schließt, listen Sie es bei der Übergabe auf.
Wenn eine Tatsache, die nur der Benutzer kennt, das Ergebnis des Lesers oder sein Handeln verändern würde, fragen Sie vor dem Schreiben nach: höchstens ein paar Fragen, jeweils mit Ihrer empfohlenen Antwort. Wählen Sie andernfalls eine sinnvolle Voreinstellung und listen Sie sie als Annahme auf.
Vor dem Schreiben
Wo die Arbeit endet
Geben Sie das Ziel an, warum es wichtig ist (wer verwendet das Ergebnis und wofür), was als erledigt gilt und was zurückgegeben werden soll. Beschreiben Sie das Ziel, nicht den Weg: Geben Sie das Ergebnis, die Erfolgskriterien und die Einschränkungen an und lassen Sie den Leser den Weg wählen. Aktuelle Modelle planen besser als eine von Ihnen vorgegebene Sequenz, und ein Schritt, den Sie falsch erraten haben, wird trotzdem ausgeführt. Listen Sie Schritte nur dort auf, wo die Reihenfolge selbst eine Anforderung ist, wie z. B. bei einer Migration, die vor einem Deployment ausgeführt werden muss.
Vorher: 1. Öffne refresh.ts. 2. Wickle refresh() in try/catch. 3. Wiederhole dreimal. 4. Führe die Tests aus.
Nachher: Wenn eine Sitzung abläuft, sollte der Client das Token stillschweigend erneuern, damit der Benutzer eingeloggt bleibt. Erledigt, wenn der neue Timeout-Fall in tests/auth/refresh.test.ts bestanden wird und kein bestehender Test fehlschlägt. Behalten Sie die öffentliche API von AuthClient unverändert bei, da drei andere Pakete sie aufrufen.
Verwandeln Sie qualitative Adjektive in messbare Kriterien, die der Leser anwenden kann. "Gründlich", "prägnant" und "nur die wichtigen" werden wörtlich und unvorhersehbar angewendet: Ein Gutachter, der angewiesen wurde, nur wichtige Probleme zu melden, wird die kleineren finden und darüber schweigen. Nennen Sie die Schwelle oder nennen Sie, was behalten und was weggelassen werden soll. Wenn ein späterer Schritt die Ergebnisse filtert, fordern Sie alles an.
Vorher: Überprüfe sorgfältig und melde nur wichtige Probleme.
Nachher: Melde jedes Problem, das du findest, auch wenn du dir unsicher bist, und kennzeichne jedes als "verhält sich falsch" oder "nur Stil". Ein späterer Schritt übernimmt das Filtern.
In welcher Situation sich der Leser befindet
Wenn der Text eine Aufgabe zuweist (eine Anweisung, ein System-Prompt, ein Issue, ein Plan oder eine Übergabe), beginnen Sie mit einem Rollensatz: Wer der Leser ist, seine Funktion in dieser Aufgabe und die Situation, in der er sich befindet. "Du bist der Code-Reviewer für diesen Pull-Request, den du nicht geschrieben hast; das Team plant, ihn heute zu mergen." Die Rolle legt die Perspektive des Lesers fest und wofür er verantwortlich ist. Beschreibungen eines Tools oder eines Skills haben keine Rolle; sie sagen, was das Ding tut und wann es verwendet wird.
Teilen Sie dem Leser dann mit, was er von seiner Position aus nicht sehen kann: ob jemand während der Aufgabe Fragen beantworten kann oder ob sie unbeaufsichtigt läuft; wer sonst noch in denselben Dateien oder Systemen arbeitet; ob seine Änderungen überprüft oder rückgängig gemacht werden können; ob er Dinge bewerten oder ändern soll; und was er ohne Nachfrage tun darf, einschließlich, ob er weiter delegieren darf. Nennen Sie die spezifischen Situationen, die ein Anhalten und Melden rechtfertigen. "Fragen, wenn unsicher" überlässt es dem Leser zu raten, und er fragt entweder nach allem oder nach nichts.
Du läufst unbeaufsichtigt; niemand kann Fragen beantworten, bis du fertig bist. Halte an und melde dich nur, wenn die Korrektur Daten löschen oder Code außerhalb von src/auth/ berühren würde. Ein anderer Agent bearbeitet gleichzeitig docs/, belasse dieses Verzeichnis also in Ruhe und mache keine Änderungen rückgängig, die du nicht vorgenommen hast.
Welches Material der Leser benötigt
Geben Sie für jede Quelle den Ort und an, was daraus entnommen werden soll. Verweisen Sie auf das, was der Leser selbst öffnen kann (Dateipfade, Befehle, URLs, die er erreichen kann), anstatt zu paraphrasieren, damit er das Original liest. Schreiben Sie alles vollständig aus, was nur in Ihrem Kontext existiert: Entscheidungen aus dem Gespräch, die eigenen Worte des Benutzers zu einer Anforderung, Ergebnisse von Befehlen, die Sie ausgeführt haben, bereits ausgeschlossene Ansätze und warum.
Vorher: Siehe docs/ und unsere frühere Diskussion.
Nachher: Lies den Abschnitt "Rückerstattungen" in docs/billing.md für die Rundungsregel. Eine Anforderung steht in keiner Datei; die Worte des Benutzers waren: "Teilrückerstattungen dürfen den ursprünglichen Betrag niemals übersteigen, auch nicht nach Währungsumrechnung."
Wenn Sie Protokolle, Benutzereingaben oder die Ausgabe eines anderen Agenten einfügen, setzen Sie sie in einen deutlich gekennzeichneten Block und sagen Sie, dass es sich um zu bearbeitendes Material handelt, nicht um Anweisungen. Halten Sie Ihre eigenen Anweisungen außerhalb solcher Blöcke, da Text in Anführungszeichen oder Datenblöcken üblicherweise als Inhalt ohne Autorität behandelt wird.
Schreiben
Verwenden Sie die Worte des Lesers, nicht Ihre. Während der Arbeit haben Sie Bezeichnungen geprägt ("Option B", "der faule Weg", "das P2-Problem") und Abkürzungen ("→ Lock Contention"), die dem Leser nichts sagen. Ersetzen Sie jede durch das, wofür sie steht, definieren Sie echte Fachbegriffe einmal und schreiben Sie, als ob Sie Neulingen etwas erklären. Wenn Sie zuvor geleistete Arbeit beschreiben, sagen Sie, wer sie getan hat, damit der Leser nicht glaubt, er selbst habe diese Aktionen ausgeführt.
Vorher: Option B ausgeschlossen (→ Lock Contention); mit lazy-init weitermachen, auf die P2-Falle achten.
Nachher: Die vorherige Sitzung hat den Neuaufbau des Verbindungspools bei jeder Anfrage ausgeschlossen: Unter Last stieg die p95-Latenz von 80 ms auf 400 ms aufgrund von Lock Contention. Der aktuelle Ansatz erstellt den Pool bei der ersten Nutzung. Ein bekanntes Problem bleibt: …
Geben Sie jeder Regel ihren Grund in einem Nebensatz ("…weil ein Skript dieses Feld parst"). Der Grund ermöglicht es dem Leser, Fälle zu behandeln, die Sie nicht aufgelistet haben, und zeigt, wie weit die Regel reicht. Lassen Sie ihn nur weg, wenn jedes fähige Modell den Grund bereits kennt oder der Kontext ihn offensichtlich macht.
Nennen Sie jede Regel einmal, an der Stelle, wo sie hingehört. Wiederholung verleiht kein Gewicht; sie führt dazu, dass der Leser die Regel übermäßig anwendet (wiederholte "Fragen Sie zuerst"-Anweisungen werden zu Stillständen bei sicheren Schritten), und die Kopien weichen bei Bearbeitungen voneinander ab. Verwenden Sie aus demselben Grund einfache Formulierungen: keine Großbuchstaben, WICHTIG oder Druck wie "das ist kritisch" oder "sei nicht faul". Halten Sie absolute Wörter wie niemals und immer für echte Invarianten, wie Sicherheitsgrenzen und irreversible Aktionen.
Schreiben Sie nicht vor, wie gedacht werden soll. Lassen Sie "denken Sie Schritt für Schritt" und Aufforderungen weg, die Begründung in die Antwort oder in Tags zu schreiben; aktuelle Modelle denken selbstständig, und einige lehnen Anfragen ab, ihre Gedankengänge zu transkribieren. Wenn Sie sehen müssen, warum, bitten Sie um eine kurze Erklärung oder die unterstützenden Beweise, wie Datei:Zeilen-Referenzen oder Befehlsausgaben.
Wenn Sie einen bekannten Fehler beheben, schreiben Sie das Prinzip dahinter mit seinem Grund auf, kein Verbot des einen beobachteten Falls. Eine Liste von Verboten deckt nur das ab, was sie auflistet; ein Prinzip deckt auch die angrenzenden Fälle ab.
Vorher: Verwende kein Object.create(). Verwende kein proto.
Nachher: Bevorzuge explizite Komposition gegenüber Prototyp-Manipulation, weil Reviewern hier Code bevorzugen, der von oben nach unten lesbar ist.
Schreiben Sie in Absätzen. Verwenden Sie Listen nur für Elemente, die wirklich parallel oder sequentiell sind: Felder, geordnete Schritte, unabhängige Prüfungen. Aufzählungen entfernen die "weil"- und "es sei denn"-Verbindungen, die Anweisungen verknüpfen, und Leser neigen dazu, das Format zu spiegeln, das sie erhalten.
Fügen Sie ein kurzes Beispiel dessen ein, was der Leser produzieren soll, gekennzeichnet als Beispiel; es vermittelt Form, Ton und Detailgrad besser als ein Absatz Beschreibung. Lassen Sie es nur weg, wenn die erwartete Ausgabe allein aus den Worten unmissverständlich hervorgeht, wie z. B. ein einzelner auszuführender Befehl.
Beenden Sie einen aufgabenstellenden Text mit einer Prüfung, die der Leser vor der Rückmeldung durchführt: der Befehl oder Test, der das Ergebnis beweist, wenn einer existiert, andernfalls die Erledigungskriterien, die er noch einmal durchgehen soll. Bitten Sie ihn, alles, was er nicht überprüfen konnte, klar zu benennen.
Übergeben
Übergeben Sie den fertigen Text, bereit zum Einfügen oder bereits in seine Datei geschrieben, in der Sprache des bestehenden Prompts oder der vom Benutzer gewünschten. Listen Sie außerhalb des Textes in ein paar Zeilen die Annahmen auf, die Sie getroffen haben und die der Benutzer möglicherweise ändern möchte. Behalten Sie Ihre Entwurfsnotizen außerhalb des Textes.
Überprüfen Sie vor der Übergabe den Entwurf so, wie der Leser es tun würde: fähig, aber nur mit dieser Seite ausgestattet. Wo immer er raten müsste, was Sie meinten, korrigieren Sie die Seite.