panbergco/agent-cli-writer

Agent CLI-Writer

Ein Agent greift zum Befehl, nicht zum Handbuch. Eine Regel, die nur in einem Dokument lebt, wird befolgt, wenn der Agent sie zufällig liest. Die Messungen dahinter finden sich in references/evidence.md.

Die Regel: Jede Regel des Tools wird vom Tool selbst zum Zeitpunkt ihrer Anwendung ausgesprochen. Was es ausgibt, was es verweigert und was es einfach macht, ist das Handbuch.

Was ein Agent mit einem Tool macht

• Greift zuerst zum Befehl; öffnet das Handbuch nur bei Unsicherheit und ist oft sicher und falsch.
• Liest, um einen bereits gemachten Plan zu bestätigen: Es sucht nach Syntax, nicht nach Regeln.
• Vergisst alles zwischen Sitzungen und lernt das Tool jedes Mal neu.
• Sendet mehrere Aufrufe gleichzeitig.
• Bezahlt für jedes Zeichen, das das Tool gedruckt hat, bei jeder späteren Anfrage erneut.
• Kann nicht günstig warten: Es fragt ab oder schläft, und jede Abfrage ist eine bezahlte Anfrage.
• Tut, was die Antwort vor ihm sagt, zuverlässiger als das, was ein Dokument früher sagte.

Methode

Zwölf Prüfungen, jede mit Angabe, wie sie zu verifizieren ist. tool ist ein erfundenes Kommando.

1. Lehre am Ort der Nutzung. Die Antwort auf einen Befehl sagt, was der gerade gegangene Weg kostet, und nennt den besseren Weg.

   $ tool machine new
   created m-41 (stoppt nach 60 Minuten von selbst)
   hinweis: manuell in dieser Maschine gestartete Arbeit führt keine Aufzeichnung.
            für einen Auftrag, den Sie verfolgen möchten: tool job start --from <verz> -- <cmd>
   

   Überprüfung: Jedes Verb mit einer bekannten falschen Verwendung sagt dies in seiner eigenen Ausgabe.
2. Eine Verweigerung ist eine Lektion. Sage, was verweigert wurde, warum, und den genauen nächsten Befehl mit den eigenen Argumenten des Aufrufers. Gib jedes Problem in einer Antwort an. Beende niemals mit einem Exit-Code ungleich Null ohne Worte. Ein Nutzungsfehler druckt nur die richtige Form dieses einen Unterbefehls.

   tool: refused: `job wait j-7` würde diesen Zug bis zu 40 Minuten blockieren.
         next:  tool job show j-7          (aktueller Stand)
                tool job start … --notify  (Benachrichtigung bei Ende)
   

   Überprüfung: Kein Exit-Pfad ohne Nachricht; jede Verweigerung enthält ein next:.
3. Trage das Handbuch im Tool. tool rules gibt die Betriebsregeln vollständig aus und endet mit einem Versionscode. Verben, die ein Agent von Hand steuert, verweigern einen nicht-interaktiven Aufrufer, der den aktuellen Code nicht gesetzt hat (TOOL_RULES=<code>), in einer Zeile. Verben, die die Maschinenschnittstelle sind, bleiben offen. Der Code ändert sich, wenn sich die Regeln ändern. Überprüfung: Ein neuer Agent, dem nur der Befehlsname gegeben wurde, hat die Regeln in seinem Kontext vor seinem ersten Aufruf, der etwas erstellt, ändert oder löscht.
4. Mache den richtigen Weg zum einfachen Weg. Bevor du „X bevorzugen“ schreibst, lasse X die gesamte Arbeit erledigen: Nimm die Eingabe, die Agenten wirklich haben, gib sofort zurück, führe eine Aufzeichnung. Agenten umgehen einen empfohlenen Befehl, der blockiert, die Historie verwirft oder ihre Eingabe nicht annehmen kann. Gib Konsequenzen an, keine Präferenzen: „Y führt keine Aufzeichnung“ funktioniert, wo „X bevorzugen“ nicht funktioniert. Überprüfung: Nenne für jedes „bevorzugen“ in der Dokumentation, was der vermiedene Pfad bietet, was der bevorzugte nicht hat, und schließe diese Lücke.
5. Ein Befehl beantwortet: „Wo stehe ich und warum?“. tool status in wenigen Zeilen: Was gehört mir, was läuft, wie das letzte endete und warum, was als nächstes zu tun ist. Agenten, die den Speicher oder die Logs des Tools direkt lesen, bedeutet, dass Status eine Tatsache vermissen lässt. Überprüfung: Zähle solche Lesevorgänge in echten Transkripten; die drei häufigsten Fragen gehören in den Status.
6. Langlaufende Arbeit: Starten, Zurückgeben, Berichten. Bei etwa einer Minute: start gibt sofort einen Handle zurück; show <handle> gibt Zeitplan, Exit-Code und letzte Zeilen, auch wenn der Worker oder der Aufrufer weg ist; das Ende wird dem Aufrufer mit Ergebnis und Grund mitgeteilt. Eine Nachricht qualifiziert nur, wenn sie etwas Neues enthält, auf das der Agent jetzt reagieren kann: kein periodisches „mach weiter“. Überprüfung: Nichts blockiert standardmäßig länger als 60 Sekunden; jeder Job hat eine Aufzeichnung und eine Endbenachrichtigung mit Ergebnis, Grund und nächstem Schritt.
7. Wenig drucken. Die Standardausgabe passt auf einen Bildschirm: etwa 40 Zeilen oder 2.000 Zeichen. Mehr geht in eine Datei, deren Pfad gedruckt wird, oder hinter --full. Keine Banner, keine Fortschrittsanimation; einmalige Anweisungen pro Sitzung. Ausgabe, die abgeschnitten ist, sagt dies und sagt, wo der Rest ist. Überprüfung: Messe die zurückgegebenen Zeichen pro Befehl über eine reale Woche und weise den drei größten Summen ein Budget zu.
8. Zwei Leser: eine Person und ein Programm. Text auf einem Terminal. Bei Weiterleitung oder mit --json: Nur JSON-Zeilen, stabile Feldnamen, eine abschließende Zusammenfassung. Der Exit-Code ist das Ergebnis: 0 erledigt, und separate Codes für verweigert, falsche Nutzung, Zeitüberschreitung, nie ausgeführt. Diagnose auf Standardfehler. Überprüfung: tool <verb> | cat parst; --help listet jeden Exit-Code auf.
9. Sicher zu wiederholen, sofort sicher. Einen Befehl zweimal auszuführen, führt die Sache nicht zweimal aus, oder sagt, dass es bereits getan wurde. Zwei Aufrufe gleichzeitig von einem Agenten verlieren nicht die Schreibvorgänge des anderen: Sperren oder den zweiten mit Worten verweigern. Destruktive Verben benötigen ein explizites Flag und bieten --dry-run. Überprüfung: Ein Test führt jedes schreibende Verb zweimal gleichzeitig aus.
10. Begrenze es und hinterlasse eine Aufzeichnung. Standardzeitlimits; was das Tool erstellt, verfällt von selbst; list zeigt Hinterlassenschaften; cleanup entfernt, was dieser Aufrufer erstellt hat; die Kosten einer Sache sind ein Befehl. Jede Aktion wird mit wem, wann und dem Build des Tools aufgezeichnet; tool version benennt es. Überprüfung: Töte den Aufrufer während der Ausführung; nichts läuft unbegrenzt weiter, und die Aufzeichnung sagt, was passiert ist.
11. Ein Name für eine Sache. Das gleiche Nomen im Befehl, seiner Ausgabe, seinen Fehlern und seiner Dokumentation; ein Verb für eine Aktion über alle Nomen hinweg. Unbekannte Flags und zusätzliche Argumente werden verweigert, niemals ignoriert. Überprüfung: Liste die Nomen auf, die das Tool ausgibt; jedes Konzept hat genau eines.
12. Geheimnisse bleiben draußen. Niemals auf einer Kommandozeile, niemals zurückgegeben, niemals in einer Aufzeichnung: aus einer Datei, der Standardeingabe oder der Umgebung, in der Ausgabe maskiert.

Schreiben des Handbuchs für das Tool

Das Handbuch erklärt; das Tool setzt durch. Nichts Verbindliches lebt allein darin.

• Beschreibung: Was das Tool tut und wann es zu laden ist, in den Worten, die eine Aufgabe verwenden würde, unter Nennung der Verben.
• Reihenfolge: Zuerst die verbindlichen Regeln, jede mit ihrer Konsequenz; dann eine kurze Tabelle mit Ziel und Befehl; dann Fehler und was zu tun ist.
• Größe: Maximal 150 Zeilen, keine Zeile über 100 Zeichen. Agenten drucken Dateien mit langen Zeilen abgeschnitten und verlieren das Ende jeder breiten Tabellenzeile.
• Tabellen: Nichts Verbindliches innerhalb einer Tabellenzelle.

Nachweis an einem frischen Agenten

Eine neue Sitzung, die das Tool oder sein Handbuch noch nie gesehen hat, erhält eine reale Aufgabe und den Namen des Befehls:

1. Zeichne jeden Aufruf, seine Ausgabe und seinen Exit-Code auf.
2. Zähle: Hilfe-Suchen, fehlgeschlagene Aufrufe, Wiederholungen eines fehlgeschlagenen Aufrufs, Abfragen, direkte Lesevorgänge von Speicher oder Logs, zurückgegebene Zeichen.
3. Jede Zahl über Null ist ein Fehler des Tools, nicht des Agenten. Korrigiere die Nachricht oder den Pfad, dann führe es in einer anderen frischen Sitzung erneut aus.
4. Führe es noch einmal mit geladenem Handbuch aus: Nichts darf schlechter werden, und das Handbuch darf dem Tool nicht widersprechen.

Erledigt, wenn ein frischer Agent die Aufgabe ohne Hilfe-Suche, ohne fehlgeschlagenen Aufruf, aus dem er sich herausraten musste, ohne Abfrage und ohne direktes Lesen des Speichers abschließt.

Fehlermodi

Nur-Handbuch-Regel (das Tool sagt sie nie) · Stummer Fehler (Exit ungleich Null, keine Worte) · Warum ohne nächsten Schritt (ein Grund und kein Befehl) · Gesamte-Hilfe-Ausgabe · Bevorzugt, aber schlechter (der empfohlene Pfad fehlt, was der andere hat) · Statuslücke (Agenten lesen den Speicher) · Blocker (ein Befehl hält den Zug) · Nerven (eine periodische Nachricht mit nichts Neuem) · Geh-nachschauen-Hinweis (sagt, dass etwas passiert ist, nicht was) · Textwand · Stilles Abschneiden · Verlorener Schreibvorgang (zwei Aufrufe gleichzeitig, ein Ergebnis) · Zwei Namen · Hinterlassenschaften (nichts verfällt).