Fabien Sanglard: So holt man mit agent.md bessere Codequalität aus LLMs heraus

"Wenn du etwas schreibst, das für Menschen bestimmt ist (Kommentar, Commit-Nachricht, Antwort auf einen Prompt), verwende so wenige Wörter wie möglich. Wähle jedes Wort sorgfältig, um den Umfang auf ein striktes Minimum zu reduzieren. Komm auf den Punkt. Weniger ist mehr."

Die Ironie in diesem ersten Absatz, der viele Wörter und viele Wege verwendet, um dieselbe Botschaft über Prägnanz zu vermitteln. Aber diese Datei ist nicht für den menschlichen Konsum bestimmt, also sollten (trotzdem?) andere Regeln gelten.

Ich ertappe mich dabei, das in Prompts zu tun. Ich schätze, es ist eine Möglichkeit, Teilen des Kontexts, die wir betonen wollen, mehr Gewicht zu verleihen, und es zeigt ein mangelndes Vertrauen in die Fähigkeiten des LLM, die Botschaft zu verstehen, wenn sie nur einmal erwähnt wird.

> - Funktionsnamen kurz halten. Weniger als 30 Zeichen.

Neulich habe ich GPT gebeten, ein Browserspiel nach Rust zu portieren. Es hat dieses Juwel freiwillig geliefert:

draw_image_with_html_image_element_and_sw_and_sh_and_dx_and_dy_and_dw_and_dh(...)

Ich dachte, es hätte was geraucht, aber es stellte sich heraus, dass das tatsächlich der Name der Funktion ist!

https://docs.rs/web-sys/latest/web_sys/struct.CanvasRenderin...

Da wir gerade unsere AGENTS.md teilen, dachte ich, ich teile auch meine, denn meistens ist das so ziemlich alles, was man braucht, damit LLMs guten Code schreiben; alles andere kann projektbezogen hinzugefügt werden:

----

*Konvergenzregel*

Jede substanzielle Aufgabe muss in genau einem von drei Zuständen enden:

A. Erfolg

Die beabsichtigte Fähigkeit funktioniert im echten Pfad und der reale motivierende Fall verbessert sich materiell.

B. Bedeutungsvoller Fortschritt

Die Fähigkeit ist nicht vollständig, aber ein echter Blocker ist entfernt und der nächste Blocker ist mit Beweisen isoliert.

C. Ehrlicher Stopp

Weitere Arbeit würde eine zu breite Ausweitung des Umfangs, übermäßige Schulden, fragiles Patching oder verworrene Logik erfordern. Stopp und berichte den Grund mit konkreten Beweisen.

Hör nicht auf, Patches zu produzieren, sobald die Arbeit aufhört zu konvergieren.

Verwechsle Aktivität nicht mit Fortschritt. Ein fehlgeschlagener Versuch ist nur akzeptabel, wenn er ein engeres Problem, stärkere Beweise oder einen gerechtfertigten Stopp hinterlässt.

Jede Teilarbeit muss den Codebase in einem saubereren, lesbareren und diagnostizierbareren Zustand hinterlassen als zuvor.

----

Ein Großteil der AGENTS.md aus dem Artikel fühlt sich an, als würde man den LLM-Agenten entweder etwas sagen, das sie bereits wissen (zum Beispiel wissen sie meistens, dass sie exhaustive switch/match-Anweisungen anstelle des "Arrow Anti-Pattern" verwenden sollen) oder das aktiv schädlich wirkt ("Funktionsnamen kurz halten" scheint willkürlich und könnte dazu führen, dass LLMs seltsame Abkürzungen für Funktionen schreiben, die schwerer zu lesen und zu überprüfen sind.

Tolles Zeug. AGENTS.md ist für das meiste davon allerdings nicht der ideale Ort. Das meiste, was in diesem Artikel gezeigt wird, kann in CODING_STANDARDS.md. Die Skills, die ich verwende, finden dieses Dokument, wenn es gebraucht wird (beim Schreiben und Überprüfen von Code), sodass es den Kontext nicht verschmutzt, wenn Code gelesen wird.

Ich habe auch Sub-Agent-Reviews (sowohl einer Planungsphase als auch des produzierten Codes), die einige dieser Probleme erkennen und Überarbeitungen verlangen würden. [1]

> - Wenn der Prompt darauf hindeutet, dass ein Bug behoben wird, schreib den Fix nicht sofort. Schreib zuerst den Test. Beobachte, wie er fehlschlägt. Dann schreib den Fix. Und beobachte, wie der Test besteht.

Ich verwende immer /tdd [2]. Gelegentlich führt es zu einigen albernen Tests, aber es erzeugt viel weniger fehlerhaften Code. Es ist nicht nur für Bugs.

[1] https://github.com/gregwebs/skills-sdlc/

[2] https://github.com/mattpocock/skills/blob/main/skills/engine...

Es ist interessant, diese Dinge zu lesen.

Ich würde das als 13 Code-Schreibregeln beschreiben (interpretiert als mindestens 16 – beginnend mit "Code-Einrückung reduzieren") plus einen Satz von Commit-Message-Anweisungen, den ich beschlossen habe zu ignorieren – weil er stilistisch spezifisch und für mich nicht interessant ist.

8 oder 9 dieser Regeln sind nicht notwendig. Grundlegende Informatik ist nichts, worum ich Agenten, die ich verwende, bitten musste, zu befolgen. Z. B. zu erklären, dass man explizite Schnittstellen braucht, ist keine notwendige Anweisung, ebenso wenig wie die Nutzung von frühen Returns.

Unklare Anweisungen haben begrenzten Nutzen. Was "Lass den Leser des Codes atmen" oder "Code-Einrückung reduzieren" bedeutet, ist subjektiv und wird selten effektiv sein. Vielleicht hat das Training für die verwendete Sprache Lücken, die andere nicht haben. Wenn du messen willst, bitte es, einen String auszugeben, wenn es eine Regel anwendet. Du wirst schnell herausfinden, was funktioniert, was nicht und wie oft.

Es sind 3 oder 4 Stilentscheidungen enthalten.

Der Rest ist nichts, was ich verwenden würde, aber wir werden alle von verschiedenen Dingen verbrannt, also verstehe ich das.

Das ist ein Problem, das die Leute meistens selbst lösen müssen. Ich arbeite seit fast einem Jahr mit Claude und habe noch nie gesehen, dass es "Arrow Anti-Pattern"-Code schreibt. Das und vieles andere wäre in meinen Projekten überflüssig. Agentenanweisungen lernt man am besten durch Erfahrung von Projekt zu Projekt.

Allein diese eine Zeile in AGENTS.md hat bessere Ergebnisse erzielt, um Ausführlichkeit und Grandiosität zu reduzieren oder zu beseitigen.

**Verwende immer ASD-STE100 Simplified Technical English

Haftungsausschluss: Ich habe gesehen, dass dies in einem anderen HN-Beitrag aufgeführt war, den ich gerade nicht finden kann.