AGENTS.md Guide: 25 % mehr Korrektheit oder 30 % weniger

Augment Code führte eine systematische Studie zu AGENTS.md-Dateien in ihrem Monorepo durch. Die besten Dateien gaben ihrem Codierungsagenten einen Qualitätssprung, der einem Upgrade von Haiku auf Opus entspricht; die schlechtesten machten die Ausgabe schlechter, als gar keine AGENTS.md zu haben. Dieselbe Datei verbesserte best_practices um 25% bei einer Routine-Fehlerbehebung und senkte completeness um 30% bei einer komplexen Feature-Aufgabe im selben Modul. Hier ist, was funktioniert.

Wie sie gemessen haben

Sie verwendeten AuggieBench, eine interne Evaluierungssuite. Sie starteten mit qualitativ hochwertigen PRs aus einem großen Repository, die typische tägliche Agentenaufgaben widerspiegeln, richteten die Umgebung und den Prompt ein und forderten den Agenten auf, den PR zu reproduzieren. Sie verglichen die Ausgabe mit dem goldenen PR (der Version, die nach der Überprüfung durch mehrere Senior Engineers übernommen wurde). PRs mussten auf ein einzelnes Modul oder eine App beschränkt sein, und der Umfang musste so sein, dass eine AGENTS.md plausibel helfen könnte. Jede Aufgabe wurde zweimal ausgeführt – mit und ohne die Datei.

Was funktioniert

1. Progressive Offenlegung > Umfassende Abdeckung

Behandeln Sie häufige Fälle und Arbeitsabläufe auf hoher Ebene; verschieben Sie Details in Referenzdateien, die der Agent bei Bedarf laden kann. Halten Sie den Umfang jeder Referenz klar. Dateien mit 100–150 Zeilen und einer Handvoll fokussierter Referenzdokumente erzielten 10–15% Verbesserungen in allen Metriken in mittelgroßen Modulen (~100 Kern-Dateien). Darüber hinaus kehrten sich die Gewinne um.

2. Prozessuale Arbeitsabläufe

Ein nummerierter, mehrstufiger Workflow kann den Agenten vom Scheitern zum Fertigstellen bewegen. Beispiel: ein sechsstufiger Workflow zur Bereitstellung einer neuen Integration. Fehlende Verkabelungsdateien sanken von 40% auf 10%, der Agent wurde schneller fertig, die Korrektheit stieg um 25%, die Vollständigkeit um 20%. Halten Sie die Hauptdatei prägnant und verwenden Sie Referenzdateien für Verzweigungsfälle.

3. Entscheidungstabellen

Wenn es zwei oder drei vernünftige Wege gibt (z. B. React Query vs. Zustand für State-Management), erzwingen Sie die Wahl vorab mit einer Tabelle. Beispiel:

Frage → React Query → Zustand
Server ist die einzige Datenquelle? ✅
Mehrere Codepfade mutieren diesen Zustand? ✅
Optimistische Updates gemischt mit lokalem Zustand benötigt? ✅

PRs in diesem Bereich erzielten 25% höhere best_practices-Werte.

4. Kurze Produktionsbeispiele

3–10-zeilige Ausschnitte aus tatsächlichem Produktionscode verbesserten die Wiederverwendung und die Einhaltung von Mustern. Beispiel: Copy-Paste-Vorlagen für Redux-Toolkit-Primitive (createSlice mit typisiertem Initialzustand, createAsyncThunk mit Fehlerbehandlung, typisiertes useAppSelector). code_reuse stieg um 20%.