hustyladislav/writing-for-agents

Referenz zum Schreiben jedes Dokuments, das ein Agent konsumiert: ein Skill, eine AGENTS.md / CLAUDE.md, ein durch einen Zeiger erreichbares Dokument. Die Verpackung unterscheidet sich; das Schreiben nicht: Dieselben Hebel machen jedes einzelne vorhersagbar, da der Agent jeden Durchlauf denselben Prozess durchläuft, anstatt dieselbe Ausgabe zu erzeugen.

Wenn das Dokument, das Sie schreiben, ein Skill ist, lesen Sie SKILL-MECHANICS.md für Frontmatter, Auswahl des Aufrufs und Router-Skills.

Kontextzeiger

Ein Kontextzeiger ist ein Verweis, der im Kontext des Agenten gehalten wird, ein außerhalb des Kontextes liegendes Material benennt und die Bedingung für dessen Erreichen kodiert. Die Beschreibung eines Skills ist einer; eine Zeile in AGENTS.md, die ein Dokument nennt, ist dasselbe Objekt. Die Formulierung des Zeigers, nicht sein Ziel, entscheidet, wann der Agent das Material erreicht und wie zuverlässig. Ein zwingend benötigtes Ziel hinter einem schwach formulierten Zeiger ist ein Varianzfehler: Schärfen Sie zuerst die Formulierung und betten Sie das Material nur ein, wenn das Schärfen fehlschlägt.

Ein Zeiger erfüllt zwei Aufgaben: Er sagt, was das Material ist, und listet die Verzweigungen auf, die sein Erreichen auslösen sollen (eine Verzweigung ist ein eindeutiger Fall, den das Dokument behandelt, sodass verschiedene Durchläufe unterschiedliche Pfade durch es nehmen). Jedes Wort eines ständig geladenen Zeigers kostet in jedem Durchlauf, also verdient es eine noch strengere Kürzung als der Textkörper:

• Stellen Sie das führende Wort an den Anfang: Der Zeiger ist der Ort, an dem er seine auslösende Wirkung entfaltet.
• Ein Auslöser pro Verzweigung. Synonyme, die eine einzelne Verzweigung umbenennen, sind eine Verzweigung, die zweimal geschrieben wurde; ziehen Sie sie zusammen und behalten Sie nur wirklich unterschiedliche Verzweigungen.
• Streichen Sie die Identität, die der Textkörper bereits trägt.

Die zwei Lasten

Jedes Dokument und jeder Zeiger, den Sie hinzufügen, verbraucht eines von zwei Budgets:

• Kontextlast sind die Kosten des ständig geladenen Materials im Fenster des Agenten: eine Zeile in AGENTS.md, eine Skill-Beschreibung, alles, was sich in jedem Durchlauf im Kontext befindet und Tokens und Aufmerksamkeit verbraucht, unabhängig davon, ob es ausgelöst wird oder nicht.
• Kognitive Last sind die Kosten für den Menschen: Welche Dokumente existieren und wann nach welchem greifen. Der Mensch ist der Index. Keine zu minimierende Kosten: Es ist der Preis menschlicher Handlungsfähigkeit; geben Sie ihn dort aus, wo menschliches Urteilsvermögen zählt, entfernen Sie ihn dort, wo es das nicht tut.

Material, das nur durch einen Zeiger erreicht wird, entgeht der Kontextlast auf Kosten der eigenen Zeile des Zeigers; Material ohne Zeiger lastet vollständig auf der kognitiven Last.

Informationshierarchie

Ein Dokument besteht aus zwei Inhaltstypen: Schritte (die geordneten Aktionen, die der Agent ausführt) und Referenz (Definitionen, Regeln, Fakten, die bei Bedarf konsultiert werden). Beide mischen sich frei: Nur Schritte (ein Rezept), nur Referenz (die Regeln einer Bewertung, dieser Skill) oder beides. Die Kernentscheidung ist, wo jedes Stück in der Informationshierarchie sitzt, einer Leiter, die danach geordnet ist, wie unmittelbar der Agent das Material benötigt:

1. Schritt in der Datei ist die primäre Ebene: Was der Agent tut, in der Reihenfolge.
2. Referenz in der Datei wird bei Bedarf konsultiert. Oft eine legitime flache Menge gleichrangiger Elemente (jede Regel einer Bewertung auf einer Sprosse), was eine gute Anordnung ist, kein Zeichen für ein Problem.
3. Offengelegte Referenz wird in eine separate Datei ausgelagert, die durch einen Kontextzeiger erreicht wird und nur geladen wird, wenn der Zeiger auslöst. Umfasst eine Geschwisterdatei im selben Ordner bis hin zu vollständig externer Referenz, die überall leben kann und auf die jedes Dokument verweisen kann.

Schieben Sie zu wenig nach unten, und die Spitze bläht sich auf; schieben Sie zu viel, und Sie verstecken Material, das der Agent tatsächlich benötigt. Diese Spannung ist die gesamte Entscheidung.

Progressive Offenlegung ist die Bewegung auf der Leiter nach unten (aus der Hauptdatei heraus und hinter einen Zeiger), sodass die Spitze lesbar bleibt. Nicht in erster Linie eine Token-Optimierung: Es ist die Art und Weise, wie die Hierarchie geschützt wird. Verzweigung ist der sauberste Test für Offenlegung: Fügen Sie ein, was jede Verzweigung benötigt, und schieben Sie hinter einen Zeiger, was nur einige Verzweigungen erreichen. Wenn ein Dokument Schritte hat, begräbt die Referenz in der Datei, die offengelegt werden sollte, diese und macht die Beachtung der Schritte zu einem Münzwurf: ein Hebel für Varianz, nicht nur einer für Lesbarkeit.

Co-Location ist der Begleiter innerhalb der Datei: Wo die Leiter entscheidet, wie weit unten ein Stück sitzt, entscheidet Co-Location, was daneben sitzt, sobald es dort ist. Halten Sie die Definition, Regeln und Einschränkungen eines Konzepts unter einer Überschrift statt verstreut, sodass das Lesen eines Teils seine Nachbarn mitbringt. Der Test: Das Dokument sollte sich wie eine für den Agenten geschriebene Dokumentation lesen. Gruppiertes Material liest sich so; verstreutes Material nicht. (Zu unterscheiden von Duplizierung: Diese wiederholt eine Bedeutung an zwei Stellen; Verstreuung fragmentiert eine Bedeutung über viele.)

Ausuferung ist hier der Fehlermodus: Ein Dokument, das einfach zu lang ist, selbst wenn jede Zeile lebendig und einzigartig ist. Die Aufmerksamkeit verdünnt sich über den Überschuss, und jede zusätzliche Zeile ist eine weitere, die relevant gehalten werden muss. Die Abhilfe ist die Leiter: Legen Sie Referenz hinter Zeigern offen und teilen Sie nach Verzweigung oder Sequenz auf, sodass jeder Pfad nur das trägt, was er benötigt.

Schritte und Abschlusskriterien

Jeder Schritt endet mit einem Abschlusskriterium, der Bedingung, die dem Agenten sagt, dass die Arbeit erledigt ist. Zwei Eigenschaften machen es zu einem Hebel:

• Klarheit: Kann der Agent erledigt von nicht erledigt unterscheiden? Eine vage Grenze ("Verständnis erreicht") lädt zu vorzeitigem Abschluss ein: Beenden des Schrittes, bevor er wirklich erledigt ist, wobei die Aufmerksamkeit zu erledigt sein abgleitet. Die noch sichtbaren vorausliegenden Schritte (die Schritte nach dem Abschluss) liefern den Sog; die Klarheit des Kriteriums ist der Widerstand. Verteidigen Sie in der Reihenfolge: Schärfen Sie zuerst die Grenze (lokal und billig); nur wenn sie irreduzibel unscharf ist und Sie die Eile beobachten, verstecken Sie die späteren Schritte, indem Sie die Sequenz teilen. Verstecken funktioniert nur über eine echte Kontextgrenze hinweg (eine Übergabe oder einen Unteragenten-Einsatz; ein Inline-Aufruf lässt die späteren Schritte im Kontext und löscht nichts).
• Anspruch: Wie viel es erfordert. "Jedes geänderte Modell berücksichtigt" erzwingt gründliche Arbeit, wo "Erstellen Sie eine Änderungsliste" dies nicht tut. Anspruch treibt Arbeit an (die Nachforschungen, die der Agent innerhalb der Arbeit anstellt, latent in der Formulierung, nicht als eigener Schritt geschrieben), und er ist nicht an Schritte gebunden: "Jede Regel angewendet" bindet einen Körper flacher Referenz genauso wie "Jeder Schritt erledigt" eine Sequenz bindet, was zeigt, wie ein reines Referenzdokument dennoch eine Vollständigkeitslatte trägt.

Die stärksten Kriterien sind sowohl überprüfbar als auch erschöpfend.

Wann teilen

Das Teilen eines Dokuments in zwei verbraucht eine der beiden Lasten, also teilen Sie nur, wenn der Schnitt es verdient:

• Nach Sequenz: Teilen Sie eine Abfolge von Schritten, bei denen die Schritte nach dem Abschluss den Agenten dazu verleiten, den Schritt davor zu übereilen. Sie aus dem Blickfeld zu halten, treibt mehr Arbeit an der aktuellen Aufgabe an. Seien Sie sich des Gegenteils bewusst: Das Zusammenführen von Sequenzen setzt jeden Schritt den späteren Schritten dessen aus, was folgt, und lädt zu vorzeitigem Abschluss ein.
• Nach Aufruf, skill-spezifisch: Siehe SKILL-MECHANICS.md.

Führungswörter

Ein Führungswort ist ein kompaktes Konzept, das bereits im Vortraining des Modells existiert und mit dem der Agent denkt, während er das Dokument ausführt (Lektion, Nebel des Krieges, Leuchtspurgeschosse). Als Token wiederholt, nie als Satz, akkumuliert es eine verteilte Definition und verankert eine ganze Verhaltensregion in den wenigsten Tokens, indem es Vorerfahrungen rekrutiert, die das Modell bereits hält. Ein eigenes zu prägen funktioniert, wenn Sie es klar definieren, aber ein erfundenes Wort rekrutiert keine Vorerfahrungen: Sie zahlen in Definitionstokens, was ein vortrainiertes Wort kostenlos gibt; greifen Sie zuerst zu einem vorhandenen Wort.

Es verankert zweifach. Im Textkörper, Ausführung: Der Agent greift jedes Mal, wenn das Wort erscheint, zum selben Verhalten, und innerhalb flacher Referenz fokussiert es die Aufmerksamkeit auf eine Klasse von Dingen, nach denen gesucht werden soll. In einem Zeiger, Aufruf: Wenn dasselbe Wort in Ihren Prompts, Ihren Docs und Ihrer Codebasis lebt, verknüpft der Agent diese gemeinsame Sprache mit dem Material und erreicht es zuverlässiger.

Suchen Sie nach Gelegenheiten, mit Führungswörtern zu refaktorisieren. Ein Dreiklang, der an drei Stellen ausbuchstabiert wird, ein Zeiger, der einen Satz darauf verwendet, auf eine Idee zu verweisen. Jedes ist eine Passage, die danach schreit, in ein einziges Token zusammengebrochen zu werden:

• "schnell, deterministisch, geringer Overhead" → eng (eine enge Schleife).
• "eine Schleife, an die Sie glauben" → rot, wodurch ein unscharfes Tor in einen binären beobachtbaren Zustand verwandelt wird (die Schleife wird beim Fehler rot, oder nicht).

Sie gewinnen zweifach: weniger Tokens und ein schärferer Haken, an den der Agent sein Denken hängen kann. Gehen Sie davon aus, dass jedes Dokument Wiederholungen trägt, die Führungswörter in den Ruhestand schicken können. Finden Sie sie.

Negation ist der Fehlermodus neben diesem Hebel: Das Steuern durch Verbot zieht das verbotene Verhalten in den Kontext und macht es verfügbarer, nicht weniger. Denken Sie nicht an einen Elefanten, und der Elefant ist alles, was es gibt; die Negation ist ein schwacher Modifikator, den das stark aktivierte Konzept überrennt, sodass das Verbot sich halb wie eine Anweisung liest, die Sache zu tun. Prompten Sie das Positive: Geben Sie das Zielverhalten an ("schreiben Sie einzeilige Kommentare"), sodass das verbotene nie ausgesprochen wird. Ein Verbot verdient seinen Platz nur als harte Leitplanke, die Sie nicht positiv formulieren können; selbst dann kombinieren Sie es mit dem positiven Ziel, damit die Aufmerksamkeit auf dem landet, was zu tun ist.

Kürzen

• Halten Sie jede Bedeutung in einer einzigen Quelle der Wahrheit: Ein autoritativer Ort, sodass das Ändern des Verhaltens eine Ein-Ort-Bearbeitung ist. Duplizierung (dieselbe Bedeutung an mehr als einem Ort) kostet Wartung und Tokens und bläht die Prominenz einer Bedeutung auf der Leiter über ihren tatsächlichen Rang hinaus auf. (Der zufällige Gegensatz zu einem Führungswort, das absichtlich ein Token wiederholt, nie die Bedeutung.)
• Die Umgebung ist ebenfalls eine Quelle der Wahrheit (package.json-Skripte, Konfigurationsdateien, das Verzeichnislayout, --help-Ausgabe), und ein Dokument, das sie wiederholt, ist ein Cache: Eine Kopie einer Nachschlageoperation, die ihre Last nur verdient, wenn die Nachschlageoperation teuer ist. Cachen Sie, was der Agent nicht durch Nachschlagen finden kann: Die ungeschriebene Konvention, den Grund hinter einer Wahl, die Falle, die keine Konfiguration preisgibt. Überlassen Sie die Ein-Datei-, Ein-Befehl-Nachschlageoperationen der Umgebung, wo sie nicht veralten können.
• Überprüfen Sie jede Zeile auf Relevanz: Bezieht sie sich noch auf das, was das Dokument tut? Eine Zeile verliert an Relevanz, indem sie nie auf die Aufgabe einzahlt (bloße Ausführung oder eine Verzweigung, die offengelegt werden sollte) oder indem sie veraltet, wenn sich das Verhalten oder die Welt, die sie beschreibt, ändert. Kürzere Dokumente sind einfacher relevant zu halten. Ohne eine Kürzungsdisziplin ist das Standard-Schicksal Sediment: Veraltete Schichten, die sich absetzen, weil Hinzufügen sich sicher und Entfernen riskant anfühlt, bis Sie sich durch sie hindurchbohren müssen, um zu finden, was noch lebendig ist.
• Jagen Sie No-Ops Satz für Satz: Eine Anweisung, der das Modell standardmäßig bereits gehorcht, zahlt Last, um nichts zu sagen. Der Test (Ändert sie das Verhalten gegenüber dem Standard?) ist modellrelativ, nicht leserrelativ: Zwei Personen, die sich über einen No-Op uneinig sind, sind sich über den Standard uneinig und klären dies durch Ausführen des Dokuments, nicht durch Debatte. Wenn ein Satz nicht besteht, löschen Sie den ganzen Satz, anstatt Wörter daraus zu trimmen. Der Test bewertet auch Führungswörter: Ein Wort, das zu schwach ist, um den Standard zu schlagen (sei gründlich, wenn der Agent bereits einigermaßen gründlich ist), ist ein No-Op, und die Lösung ist ein stärkeres Wort (unerbittlich), nicht eine andere Technik.