Ihr AGENTS.md wurde für ein schlechteres Modell geschrieben: Prüfung der Prompt-Schulden
Alte AGENTS.md-Regeln überdauern die von ihnen behobenen Modelloblüten. Lernen Sie, Prompt-Defizite zu erkennen, Fähigkeiten auf Router zu beschränken, Berechtigungen einzustellen und bereits im Voraus festzulegen, was erledigt ist.
Jede Zeile in einer AGENTS.md-Datei wurde in der Regel hinzugefügt, um einen tatsächlichen Fehler zu beheben. Die Modelle verbessern sich, der Fehler verschwindet, doch die Regel bleibt bestehen. Das ist sogenanntes Prompt-Darlehen: Eine Workaround-Lösung für die Schwäche eines Modells, die zu einer dauerhaften Richtlinie wird. Die Lösung besteht darin, der Datei eine engere Aufgabe zu geben, die Invarianten, versteckte Einschränkungen und Berechtigungsgrenzen sowie eine Definition dessen, was als abgeschlossen gilt, abdeckt.
Jedes Mal, wenn ein Programmier-Agent auf eine Weise versagt, an die sich die Leute erinnern, fügt jemand eine Regel hinzu. Er ändert zu viel, weshalb die Datei vorschreibt, nur das Notwendige anzufassen. Er überspringt die Überprüfung, wodurch jede Zeile erneut die vollständige Testsuite erfordert. Er ändert eine Abhängigkeit ohne Anfrage, wodurch Änderungen an Abhängigkeiten nur noch mit Genehmigung möglich sind. Er bewegt sich im Repository umher, weshalb die Datei klarlegt, welche Dokumente zuerst gelesen werden sollen.
Jede Regel machte bei ihrer Erstellung Sinn. Dann änderte sich das Modell.
OLD: Read A → Edit B → Test C
NEW: Boundaries → Permissions → Definition of done
Die neueste Generation von Modellen, wobei GPT-6 Astra als Beispiel genannt wird, befolgt Anweisungen deutlich besser als frühere Programmiermodelle, was die Kostenstruktur bei der Anwendung solcher Anweisungen verändert. Ein schwaches Modell könnte eine allzu umfassende Regel ignorieren, während ein starkes Modell ihr buchstäblich folgen könnte. Somit kann eine Anweisung, die dazu dient, die Mängel eines älteren Modells auszugleichen, bei einem neueren Modell zu Problemen führen. Wenn man ein Modell aktualisiert, ohne seine Anweisungen zu überprüfen, übernimmt man die alten Schwächen als dauerhafte Richtlinie innerhalb des neuen Systems. Das Modell hat sich verbessert, doch die Anweisungsstruktur bleibt unverändert.
Jeder Fehler hinterlässt ein „Fossil“
Code sammelt technischen Schulden, wenn eine schnelle lokale Lösung zu einer strukturellen Beschränkung wird. Anweisungen an KI-Systeme erzeugen auf dieselbe Weise Schulden.
Nehmen wir an, ein älteres Programmiermodell vergaß ständig, seine Änderungen zu überprüfen, weshalb jemand hinzufügte:
Always run the entire test suite after every change.
Zu dieser Zeit könnte die Zuverlässigkeit verbessert worden sein. Ein Jahr später erkennt das Modell bereits die betroffenen Tests und überprüft seine eigene Arbeit, doch die Anweisung existiert immer noch. Schon eine einwortige Korrektur kann zwanzig Minuten an Integrationstests auslösen. Nichts ist kaputt, und der Agent befolgt den Repository-Standard getreulich. Das Problem ist, dass ein alter Verhaltenspatch zu einer dauerhaften Ingenieurpolitik geworden ist.
Das ist Schulden durch überstürzte Maßnahmen. Eine Regel löst ein echtes Problem, das Problem verschwindet, und die Regel bleibt bestehen.
Fähigkeiten kosten etwas, bevor sie genutzt werden
Fähigkeiten erscheinen günstig, da ihr vollständiger Inhalt nur bei Bedarf geladen wird. Das Agent Skills-Format beschreibt eine schrittweise Offenlegung: Zuerst werden der Name und die Beschreibung einer Fähigkeit geladen, die vollständige Datei erst, wenn eine Aufgabe übereinstimmt.
Doch bevor das Modell eine Fähigkeit auswählen kann, muss es zunächst die verfügbaren Optionen erkennen, wodurch Namen und Beschreibungen bereits um die Aufmerksamkeit konkurrieren.
Stellen Sie sich ein Repository vor, das separate Fähigkeiten für Datenbankmigrationen, PostgreSQL, Schema-Design, Persistenz im Backend, Abfragen optimieren sowie Wiederherstellung umfasst. Jede dieser Fähigkeiten enthält eine allgemeine Beschreibung, in der SQL, Migrationen, Schemata, Abfragen, Modelle und Speicher gleichzeitig erwähnt werden. Schon eine kleine Anpassung einer Abfrage erscheint nun für die Hälfte der verfügbaren Fähigkeiten relevant, weshalb das Modell erst klassifizieren muss, bevor es codieren kann.
Das bessere Vorgehen bleibt weiterhin die schrittweise Offenlegung von Informationen, wie auch OpenAI in seiner Dokumentation zu den Fähigkeiten empfiehlt: Detaillierte Anleitungen befinden sich in Hilfdateien, die erst dann bereitgestellt werden, wenn sie für eine Aufgabe benötigt werden.
database/
├── router.md
└── references/
├── migrations.md
├── performance.md
└── recovery.md
Die Root-Datei enthält nur das Notwendige, um die Aufgabe zu leiten. Eine Schema-Änderung führt zu migrations.md, eine langsame Abfrage zu performance.md, ein Wiederherstellen oder Datenverlust zu recovery.md. Die Details werden nicht weggeworfen – sie werden angezeigt, wenn die Aufgabe dem Agenten einen Grund gibt, sie zu lesen, wodurch der Kontext besser genutzt wird als das Aufnehmen operativer Kenntnisse aufgrund von Spekulationen.
AGENTS.md sollte das enthalten, was der Code nicht erklären kann
Anweisungen auf Repository-Ebene verhalten sich anders, weil sie den Agenten bei fast jeder Aufgabe begleiten. Dateien wie AGENTS.md werden als ständiger Kontext in eine Sitzung geladen, wie es die Speicherdokumente von Claude Code beschreiben, und dadurch entstehen Kosten, wenn sie falsch, veraltet oder unnötig umfassend sind.
Ein praktischer Test: Könnte ein fähiger Ingenieur, der sich diesen Repository ansieht, dies sicher und kostengünstig lösen? Wenn ja, gehört die Regel möglicherweise nicht in AGENTS.md. Wenn nein, gehört sie wahrscheinlich dorthin.
Vergleichen Sie zwei Anweisungen. Die erste beinhaltet repository-spezifisches Wissen, das ein Modell nicht sicher ableiten kann, daher bleibt sie erhalten:
KEEP
Generated API clients in /src/sdk are immutable.
Edit the generator source instead.
Der zweite beschreibt einen Workflow, der für eine architektonische Refaktorierung geeignet sein könnte, aber für die Korrektur eines einzigen Tippfehlers übertrieben ist, weshalb er entfernt werden sollte:
MOVE OR REMOVE
Before making any change:
1. Read ARCHITECTURE.md
2. Inspect the repository map
3. Review all package documentation
4. Identify downstream dependencies
Beständige Anweisungen sollten hauptsächlich drei Aspekte berücksichtigen: Invarianten, die unbedingt gewahrt bleiben müssen, versteckte Einschränkungen, die im Codebasis nicht offensichtlich sind, sowie Grenzen der Autonomie, die zeigen, wo der Agent vorgehen darf und wo ein Mensch entscheiden muss. Das ist eine weitaus kleinere Aufgabe als das Lehren eines Modells, wie man Softwareentwicklung betreibt.
Bessere Modelle machen Genehmigungen wichtiger
Ein stärkeres Befolgen von Anweisungen führt zu einem subtileren Versagen. Der Agent kann Ihre Grenzen so sorgfältig einhalten, dass er genau dort anhält, wo Sie wollten, dass er weitermacht.
Nehmen wir an, er implementiert eine Änderung und ein durch diese Änderung betroffener lokaler Test fehlschlägt. Er meldet, dass auth_spec.ts fehlschlägt, und fragt, ob er es reparieren soll. Das Modell weiß, wie man den Test repariert. Es weiß jedoch nicht, ob diese Reparatur in seinen erteilten Befugnissen liegt. In solchen Fällen hilft eine Genehmigung mehr als ein anderes Verfahren:
Local tests use disposable fixtures and have no production access.
Run affected tests, fix regressions caused by the requested change,
and rerun them without asking for approval at each step.
Diese Zeilen teilen dem Agenten drei Dinge mit, die er nicht immer ableiten kann: Die Umgebung ist sicher, die Behebung fällt in den Zuständigkeitsbereich und er darf fortfahren. Auf diese Weise gezogene Grenzen leiten die Entscheidungen besser als pauschale Verbote wie „Erweitere den Zuständigkeitsbereich niemals.“
Eine Möglichkeit, die Verantwortlichkeiten in der Praxis aufzuteilen:
Braucht menschliche Genehmigung:
- Löschung von Produktionsdaten.
- Änderung der Authentifizierungsrichtlinie.
- Verletzung eines Vertrags einer öffentlichen API.
- Einführung einer Migration mit Betriebsrisiken.
Der Agent kann in der Regel mit folgenden Aktionen fortfahren:
- Bereinigung eines Tests, den seine eigene Änderung gestört hat.
- Aktualisierung nahegelegener lokaler Typen.
- Formatierung der von ihm geänderten Dateien.
- Erneute Ausführung der betroffenen lokalen Tests.
Die Konsequenzen sind es, die die Listen voneinander unterscheiden. Nebenliegende Aktionen verdienen nicht alle denselben Grad an Genehmigung.
Definiere erst, was abgeschlossen ist, bevor du den Ablauf beschreibst
Ältere Anfragen beschreiben oft die Route:
Read these files.
Modify these modules.
Run this command.
Inspect this output.
Run these tests.
Das kann hilfreich sein, wenn ein Workflow tatsächlich anfällig ist, aber ein fähiger Agent profitiert in der Regel mehr von einem klaren Endpunkt. Vergleichen Sie die reine Anfrage.
Implement the avatar endpoint.
mit einer Version, die eine Ziellinie hinzufügt:
Run the affected local tests, inspect the returned payload,
fix regressions caused by this change, and stop when the requested
behavior works or an external blocker requires a decision from me.
Der zweite gibt nie an, welches Datei zuerst geöffnet werden soll. Er beschreibt vielmehr, wie das Ergebnis aussieht. Dieser Unterschied wird deutlicher, je mehr Urteilsvermögen die Modelle entwickeln, um selbst den Weg durch eine Codebasis zu wählen. Die Menschen legen das Ziel sowie die gefährlichen Grenzen fest, und der Agent berechnet den Weg.
Halten Sie die Anweisungshierarchie bewusst
Eine ordentliche Struktur weist drei getrennte Ebenen auf. Die erste ist die Repository-Datei:
AGENTS.md
↓
Repository invariants
Safety boundaries
Global permissions
Der zweite umfasst Fähigkeiten:
Skills
↓
Specialized workflows
Loaded only when relevantTask prompt
↓
Immediate objective
Local constraints
Definition of done
Drittens ist die Aufgabenanweisung selbst. Probleme entstehen, sobald die verschiedenen Komponenten miteinander verschmelzen: ein einmaliger Aufgabenablauf, der in AGENTS.md aufgenommen wird, eine globale Sicherheitsregel, die in einer Fähigkeit versteckt ist, die das Modell vielleicht nie lädt, eine Fähigkeit, die zu einer Enzyklopädie wird, oder eine Aufgabenanweisung, die Wissen aus dem Repository wiederholt, das das Modell bereits besitzt. Je leistungsfähiger die Modelle werden, desto teurer wird diese Duplizierung.
Auditorie der Aufgabenanweisungen bei Modelländerungen
Ein Modell-Upgrade sollte eine Überprüfung der Anweisungen auslösen. Das liegt nicht daran, dass jede alte Anweisung falsch ist, sondern weil sich die zugrunde liegenden Annahmen geändert haben könnten. Eine nützliche Auditorie umfasst vier Schritte.
Übersicht über historische Anpassungen erstellen
Sammeln Sie alles, was das Verhalten des Agenten beeinflusst:
AGENTS.md- Beschreibungen von Fähigkeiten
- Inhalte der Fähigkeiten
- Systemebene-Anweisungen aus dem Repository
Für jede Regel sollte man herausfinden, warum sie existiert und welcher Fehler ursprünglich dazu führte, dass sie hinzugefügt wurde.
Echte Invarianten von Gewohnheiten unterscheiden
Prüfen Sie, ob ein fähiger Ingenieur die Regel aus dem Repository sicher und kostengünstig ableiten kann. Wenn ja, testen Sie, ob sie anwendbar ist. Falls nicht, behalten Sie sie bei. Regeln, die Produktionsrisiken, generierte Artefakte, verstecktes Infrastrukturverhalten sowie nicht offensichtliche Betriebsbeschränkungen betreffen, erfordern besondere Aufmerksamkeit.
Spezialisierte Fähigkeiten in Routinen umwandeln
Falls eine Fähigkeit mehrere Arbeitsabläufe umfasst, verkleinern Sie ihren Eingangspunkt. Laden Sie Migrationsanleitungen nur für Migrationsvorgänge und Wiederherstellungsanleitungen nur dann, wenn eine Wiederherstellung relevant ist. Das spezialisierte Wissen bleibt erhalten, ohne in jede nahegelegene Aufgabe eingeführt zu werden.
Jede Verbotsregel erneut lesen, um das dahinterliegende Risiko zu verstehen
Regeln im Stil von „BERÜHRE NIEMALS X“, „FRAGE IMMER ZUERST BEVOR DU Y TUST“ oder „VERÄNDERE NUR Z“ können durchaus richtig sein, doch jede sollte anhand der Konsequenzen überprüft werden, die sie verhindern soll. Manchmal ist eine bessere Regel, dass X in der lokalen Entwicklung frei geändert werden darf, in der Produktion jedoch zunächst eine Abfrage erforderlich ist, oder dass Regressionen durch eigene Änderungen des Systems behoben werden können, während umfassendere Änderungen einer Genehmigung bedürfen.
Das Ziel ist nicht maximale Autonomie. Es geht darum, menschliche Aufmerksamkeit dort einzusetzen, wo die Konsequenzen dies rechtfertigen.
Was sollte jede Aktualisierung überdauern
Auch mit den besten Modellen sollten einige Anweisungen erhalten bleiben. Eine Bereitstellung kann ein undokumentiertes Legacy-Flag benötigen. Generierte Dateien mögen als editierbar erscheinen, obwohl Änderungen überschrieben werden. Eine lokale Umgebung kann trotz Verwendung von temporären Konfigurationen der Produktionsumgebung ähneln. Eine Migration muss möglicherweise mit zwei laufenden Versionen einer Anwendung funktionieren. Solche Anweisungen haben hohen Wert, denn allein die Intelligenz reicht nicht aus, um sie zuverlässig aufzudecken.
Der zu verwendende Filter ist der Informationswert. Wenn eine Anweisung etwas enthält, das das Modell nicht sicher erkennen kann, sollte sie beibehalten werden. Wenn sie lediglich beschreibt, wie ein älteres Modell durch eine gewöhnliche ingenieurtechnische Aufgabe geführt werden musste, sollte man sie neu überdenken. Viele Anweisungen sind nicht der Grund für „Prompt-Debt“. Die eigentliche Schuld liegt bei jenen Anweisungen, deren Existenzgrund verschwunden ist.
Die alte Vorgehensweise bei der Programmierung von Agenten bestand darin, den Ablauf immer detaillierter auszuführen. Da sich die Modelle verbessern, funktioniert ein einfacheres Design besser: Man behält die Invarianten bei, legt die Berechtigungen fest und definiert, was als abgeschlossen gilt. Den mittleren Teil überlässt man dem Agenten, und wenn ein neues Modell verfügbar wird, prüft man zunächst die Regeln, bevor man weiterentwickelt.