AGENTS.md und Projektregeln

AGENTS.md und Projektregeln

0:00 Jedes Team hat ungeschriebene Regeln. Wie hier getestet wird, welcher Ordner tabu ist, warum diese eine Bibliothek nicht verwendet wird. Neue Kolleginnen lernen das in den ersten Wochen — durch Nachfragen, durch Code-Reviews, manchmal durch einen Fehler. Ein Agent lernt es nie. Er fängt bei jeder Session von vorn an und entscheidet dann eben selbst, plausibel und möglicherweise falsch. In diesem Modul geht es um die Datei, die das ändert: AGENTS.md.

0:27 Wir klären, was hineingehört, was ausdrücklich nicht, wie sich mehrere Dateien schichten — und warum eine Regel niemals eine technische Grenze ersetzt.

AGENTS.md und dauerhafte Projektregeln

0:37 Der Leitgedanke dieses Moduls steht in einem Satz: Was Sie einem neuen Teammitglied am ersten Tag sagen würden, gehört ins Repository. Acht Kapitel führen von der Rolle dieser Datei über Architekturvorgaben und Testregeln bis zur Frage, wie man ein gewachsenes Regelwerk wieder straff bekommt. Denn der häufigste Fehler ist nicht die fehlende Datei — es ist die, die niemand mehr liest, weil sie zu lang geworden ist. Beispielprojekt bleibt unser Buchungsdienst kanuverleih.

Die Rolle von AGENTS.md

1:04 Beginnen wir mit der Einordnung. Es gibt bereits eine Datei, die erklärt, worum es in einem Projekt geht — die README. Warum also eine zweite? Die Antwort hat mit unterschiedlichen Adressaten zu tun, und sie ist praktischer, als sie zunächst klingt. Sehen wir uns an, was diese Datei leistet, wie sie gelesen wird und wo ihre Grenzen liegen.

1:25 AGENTS.md ist ein offenes Format für Anweisungen an Coding-Agenten: gewöhnliches Markdown, keine Pflichtfelder, keine besondere Syntax. Codex liest die Datei vor der Arbeit und wendet ihre Regeln auf jede Session im Projekt an. Das Format hat sich inzwischen über Werkzeuggrenzen hinweg durchgesetzt — Sie schreiben also nicht für einen Hersteller.

1:45 Der Vergleich, der am besten trägt: Es ist die Betriebsanleitung, die an der Maschine hängt. Nicht das Handbuch für den Konstrukteur, sondern die Handvoll Hinweise für den, der sie täglich bedient. Diese Gegenüberstellung erklärt, warum es zwei Dateien braucht. Die README wendet sich an Menschen: Überblick, Einstieg, erklärend im Ton.

2:06 Die AGENTS.md wendet sich an Agenten: Befehle, Konventionen, anweisend im Ton. Der Unterschied im Ton ist kein Stilproblem, sondern ein Wirkungsproblem — dazu gleich mehr. Und beide sollen kurz bleiben, aber aus verschiedenen Gründen: die README, damit Menschen sie lesen; die AGENTS.md, weil sie in jeder einzelnen Session Platz im Kontextfenster kostet.

2:29 Doppelungen zahlen Sie also doppelt. Vier Gründe, warum sich der Aufwand lohnt. Die Datei gilt in jeder Session, ohne dass jemand daran denken muss — das ist der entscheidende Vorteil gegenüber dem Prompt. Sie gilt für alle im Team gleich, nicht nur für die Geübten, die ohnehin wissen, was sie mitgeben müssen. Sie ist versioniert und damit im Review diskutierbar wie jede andere Quelldatei. Und sie entlastet den Prompt von Wiederholungen.

2:55 In Summe: Sie verwandeln eine persönliche Gewohnheit in eine Eigenschaft des Projekts. Vier Fallen, die alle etwas mit Maß und Wirkung zu tun haben. Eine Datei ohne exakte Befehle bleibt wirkungslos — dazu kommen wir gleich ausführlich. Was schon im Linter steht, muss hier nicht noch einmal stehen; der Linter setzt es durch, die Datei nur nahe. Jede Zeile kostet Kontext und muss sich rechnen.

3:19 Und der letzte Punkt ist wichtig für Ihre Erwartung: Ein ausdrücklicher Auftrag im Chat schlägt die Datei. Wenn Sie im Prompt etwas anderes verlangen, gewinnt der Prompt.

Projektwissen dokumentieren

3:30 Jetzt zum Inhalt. Was gehört hinein, und vor allem: in welcher Form? Denn hier entscheidet sich, ob die Datei wirkt oder nur gut gemeint ist. Der Unterschied zwischen einer wirkungslosen und einer wirksamen Regel ist oft nur die Formulierung — und dieser Unterschied lässt sich in einem einzigen Satz erklären. Danach werden Sie ihn in jeder Regeldatei sehen, die Ihnen begegnet.

3:53 Nützlich ist, was der Agent zum Schreiben korrekten Codes braucht: der Aufbau des Repositorys, die wörtlichen Bau- und Testbefehle, Konventionen, die kein Werkzeug erzwingt, und die Bereiche, die niemand anfassen soll. Das ist zugleich der Filter für alles andere. Wenn Sie sich fragen, ob etwas hineingehört, stellen Sie die Frage anders herum: Würde der Agent ohne diese Information schlechteren Code schreiben? Wenn nein, streichen Sie es.

4:19 Alles, was nur nett zu wissen ist, kostet Kontext, ohne etwas zu ändern. Was Sie hier sehen, ist bewusst schmal: Befehle, Aufbau, Tabus. Auf die exakte Gliederung kommt es nicht an — es gibt keine Pflichtstruktur. Worauf es ankommt, steht in der Fußzeile, und das ist der wichtigste Satz dieses Kapitels: anweisend formulieren. „Nutze npm, nicht pnpm" wirkt.

4:43 „Wir bevorzugen npm" wirkt nicht — das ist eine Information, keine Anweisung. Genauso bei Befehlen: Schreiben Sie den Befehl hin, den der Agent ausführen soll, nicht die Beschreibung dessen, was er bewirkt. Fünf Schritte vom Nichts zur brauchbaren Datei. Sie lassen sich einen Entwurf erzeugen — bequem, aber nur der Anfang.

5:05 Dann dampfen Sie ihn ein, denn der Entwurf beschreibt gern, was er im Code sieht, und Vermutungen sind schlimmer als Lücken. Bau- und Testbefehle tragen Sie wörtlich ein. Tabus und Sonderfälle ergänzen Sie. Und dann reviewen Sie die Datei im Team wie jede andere Quelldatei. Der Startpunkt sind zwanzig bis dreißig Zeilen — alles Weitere sollte aus echten Reibungspunkten wachsen, nicht aus Vollständigkeitsdrang.

5:30 Der erste Punkt betrifft den erzeugten Entwurf: Er beschreibt, was er sieht, und das nützt nichts — der Agent sieht den Code ja selbst. Der zweite ist die schon erwähnte Formulierungsfalle: „Wir testen gründlich" hilft niemandem, „npm test muss grün sein" schon. Der dritte betrifft Selbstverständlichkeiten, die nur Platz füllen. Und der vierte ist der gefährlichste: Ungepflegte Regeln führen den Agenten aktiv in die Irre.

5:55 Eine falsche Regel ist schlechter als gar keine, weil er sich darauf verlässt.

Coding Standards und Architektur

6:00 Kommen wir zu den Regeln, die kein Werkzeug für Sie durchsetzt. Formatierung erledigt der Formatierer, Syntaxfehler der Compiler — aber Schichtgrenzen und Abhängigkeitsrichtungen stehen nirgends im Code, sie sind Absprachen. Und genau diese Absprachen sind es, die ein Agent verletzt, ohne es überhaupt zu merken — er sieht ja nur, dass der Code kompiliert.

6:20 Sehen wir uns an, wie man solche Regeln so aufschreibt, dass sie im Alltag tatsächlich greifen. In die AGENTS.md gehören die Konventionen, die weder Compiler noch Linter erzwingen: Schichtgrenzen, erlaubte Abhängigkeitsrichtungen, Namensmuster und die begründeten Abweichungen vom Sprachüblichen. Das letzte ist wichtig — wenn Ihr Projekt an einer Stelle bewusst vom Üblichen abweicht, wird der Agent das „korrigieren", wenn er den Grund nicht kennt.

6:46 Er hat schließlich Millionen Zeilen üblichen Code gesehen. Eine kurze Notiz, warum es hier anders ist, spart Ihnen diese Diskussion in jedem einzelnen Review. Vier Begründungen. Formatierung erledigt der Formatierer, nicht die Textdatei — das ist die klarste Abgrenzung überhaupt. Schichtgrenzen sieht der Agent im Code nicht zwingend; er sieht, dass ein Import funktioniert, nicht dass er unerwünscht ist.

7:10 Abhängigkeitsrichtungen sind eine Entwurfsentscheidung, kein Geschmack. Und Abweichungen brauchen eine Begründung, sonst wirken sie willkürlich und werden wegoptimiert. Der gemeinsame Nenner: Hier steht, was man nicht aus dem Code ableiten kann. Vier Zeilen für unser Beispielprojekt — und die Kürze ist Absicht. Die API-Schicht ruft die Fachlogik, nie umgekehrt. Die Fachlogik kennt weder HTTP noch SQL.

7:36 Datenbankzugriff läuft über eine eigene Schicht. Und eine neue Abhängigkeit wird erst im Review geklärt. Jede dieser Zeilen ist prüfbar: Man kann im Diff sehen, ob sie eingehalten wurde. Genau das unterscheidet sie von einer Seite Architekturprosa, die zwar richtig ist, aber nichts entscheidet. Vier klare Sätze wirken mehr als ein Kapitel Erklärung.

7:59 Der erste Punkt ist die eben erwähnte Architekturprosa ohne prüfbare Regel. Der zweite ist heikler, als er klingt: Regeln, die der Bestand selbst verletzt, verwirren den Agenten. Er sieht im Code das Gegenteil dessen, was die Regel sagt — und muss raten, was gilt. Wenn es Altlasten gibt, benennen Sie sie als solche. Der dritte Punkt: Zu viele Ausnahmen heben die Regel praktisch auf. Und der vierte gilt für Menschen wie Agenten: Was nur mündlich gilt, gilt für den Agenten gar nicht.

Testanforderungen und Qualitätsregeln

8:30 Jetzt kommen wir zu dem Teil, der über die Qualität der Ergebnisse am meisten entscheidet: Woran erkennt der Agent, dass er fertig ist? Ohne ein objektives Kriterium beantwortet er diese Frage selbst — und sein Maßstab ist nicht Ihrer. Sehen wir uns an, wie Sie ihm den Maßstab vorgeben, und welche Regel dabei überflüssig klingt und es nicht ist.

8:51 Der Agent braucht ein objektives Fertig-Kriterium. Der Testbefehl, der erwartete Umfang neuer Tests und die Bedingungen, unter denen etwas als erledigt gilt, gehören deshalb wörtlich in die Projektregeln. Warum wörtlich? Weil „die Tests müssen laufen" den Agenten dazu bringt, sich einen Befehl auszudenken — und der kann in Ihrem Projekt ein anderer sein. Steht der Befehl da, führt er ihn aus.

9:15 Und was er ausführt, kann er auch nicht falsch erinnern. Vier Regeln, und eine davon verdient besondere Aufmerksamkeit. Jede Verhaltensänderung braucht einen Test. Vor der Fertigmeldung laufen Test und Linter. Fremde Tests werden nicht angepasst, sondern gemeldet. Und dazwischen steht: keine Testdatei löschen, um grün zu werden.

9:36 Das klingt beim ersten Lesen überflüssig — welcher Agent würde das tun? Erfahrungsgemäß ist die Regel nicht überflüssig. Wenn ein Test hartnäckig rot bleibt und im Auftrag „bis die Tests grün sind" steht, gibt es aus Sicht des Modells zwei Wege dorthin. Vier Eigenschaften. Ein gutes Kriterium ist maschinell prüfbar, nicht Ermessenssache — sonst prüft es der Agent nach seinem Ermessen.

10:00 Es steht vor der Arbeit fest, nicht danach; nachträglich formulierte Kriterien passen sich erstaunlich gut an das an, was herausgekommen ist. Es benennt den Befehl, nicht die Absicht. Und es schließt die offensichtlichen Abkürzungen aus. Der letzte Punkt ist der, den man aus Erfahrung ergänzt, nicht aus Theorie. Diese Übung hat einen Prüfschritt, den man gern überspringt. Sie formulieren ein Abschlusskriterium und hinterlegen es.

10:27 Und dann testen Sie es an einem bewusst fehlerhaften Lauf: Meldet der Agent trotzdem „fertig"? Wenn ja, greift Ihre Regel nicht — sie ist zu vage oder steht an der falschen Stelle. Diese Gegenprobe ist wichtiger als die Formulierung selbst. Denn eine Regel, deren Wirkung nie geprüft wurde, ist eine Annahme.

Anweisungen aus Prompts herauslösen

10:47 Jetzt zu einer Frage, die Sie im Alltag am schnellsten weiterbringt: Woher wissen Sie überhaupt, welche Regeln Ihr Projekt braucht? Die Antwort steht in keinem Handbuch und in keiner Vorlage aus dem Netz — sie steht in Ihren eigenen Prompts. Man muss nur einmal systematisch hinsehen, statt sie nach dem Absenden zu vergessen. Dieses Kapitel zeigt, wie das praktisch geht.

11:09 Wer dieselbe Anweisung dreimal getippt hat, hat eine Projektregel gefunden. Der Umzug aus dem Prompt in die AGENTS.md macht sie dauerhaft, teilbar und überprüfbar — und verkürzt jeden künftigen Auftrag. Das ist ein bemerkenswert einfaches Verfahren, weil es keine Theorie braucht. Sie müssen nicht überlegen, welche Regeln ein Projekt idealerweise hat.

11:30 Sie beobachten, was Sie tatsächlich immer wieder erklären. Genau das ist die Lücke zwischen dem, was im Repository steht, und dem, was Ihr Projekt ausmacht. Fünf Schritte, davon vier einfach und einer entscheidend. Eine Woche lang Prompts sammeln. Wiederholungen markieren, unabhängig vom genauen Wortlaut — es geht um die Absicht, nicht um die Formulierung. Als Anweisung mit exaktem Befehl umschreiben.

11:55 In die Datei aufnehmen und im Team abstimmen. Und dann Schritt fünf, die eigentliche Probe: den nächsten Auftrag ohne die Wiederholung stellen. Hält der Agent die Regel ein, ohne dass Sie ihn erinnern? Erst dann hat der Umzug funktioniert. Diese Tabelle beantwortet die häufigste Rückfrage zu diesem Thema. Links steht, was diese eine Aufgabe betrifft: das Ziel dieser Änderung, die betroffenen Dateien, eine einmalige Ausnahme.

12:22 Rechts steht, was jede Aufgabe im Projekt betrifft: der Testbefehl, Schichtgrenzen, Tabus, dauerhafte Konventionen. Die Faustregel in der Fußzeile funktioniert erstaunlich zuverlässig: Gilt es auch nächste Woche und für Ihre Kolleginnen? Dann gehört es ins Repository. Gilt es nur jetzt und nur für Sie? Dann in den Prompt.

12:43 Der Hinweis zu dieser Aufgabe ist der interessanteste Teil: Achten Sie auf Anweisungen, die Sie gar nicht mehr bewusst tippen. Genau die sind die besten Kandidaten, weil sie so selbstverständlich geworden sind, dass Sie sie nicht mehr als Anweisung wahrnehmen. Drei davon ziehen Sie um. Und dann prüfen Sie, ob der nächste Auftrag ohne sie zum gleichen Ergebnis kommt.

13:03 Wenn ja, haben Sie Ihre tägliche Tipparbeit dauerhaft reduziert — und nebenbei das Projekt für alle anderen verbessert.

Kontext für Projektbereiche

13:10 Bisher haben wir von einer Datei gesprochen. In größeren Projekten reicht das nicht: Ein Monorepo mit fünf Paketen in drei Sprachen hat keine gemeinsamen Testbefehle. Codex löst das durch Schichtung mehrerer Dateien — und die funktioniert etwas anders, als man zunächst vermutet. Es gewinnt nämlich nicht die erste gefundene Datei, sondern die nächstgelegene. Sehen wir uns an, was das praktisch bedeutet.

13:35 Codex liest die Regeln geschichtet: zuerst die globale Datei in Ihrem Benutzerordner, dann vom Wurzelverzeichnis des Repositorys abwärts bis zum aktuellen Ordner. Alles wird zusammengefügt, und die nächstgelegene Datei wirkt am stärksten. Das Bild dazu: Hausordnung, Etagenregeln, Zimmerregeln. Je näher an dem Ort, an dem Sie stehen, desto konkreter — und im Zweifel gilt das Konkretere. Das ist bequem, weil Sie allgemeine Regeln nicht in jedem Paket wiederholen müssen.

14:04 Vier Ebenen, von allgemein nach speziell. Der Benutzerordner trägt Ihre eigenen Vorlieben über alle Projekte hinweg — Vorsicht, die wirken auch in fremden Repositories. Die Projektwurzel trägt, was für das ganze Repository gilt. Zwischenebenen tragen Regeln je Bereich oder Paket. Und das Arbeitsverzeichnis trägt, was nur für dieses Modul gilt.

14:25 Die Fußzeile nennt noch eine Besonderheit: Eine Datei mit dem Zusatz „override" im Namen verdrängt auf ihrer Ebene die reguläre — praktisch, um vorübergehend etwas anderes gelten zu lassen, ohne die Basis zu löschen. Vier Situationen. Monorepos mit Paketen unterschiedlicher Technik — dort sind die Befehle je Paket verschieden. Bereiche mit eigenen Test- oder Baubefehlen.

14:49 Alt-Code, für den andere Regeln gelten als für Neues; das ist der ehrlichste Umgang mit Altlasten. Und sehr große Regelwerke, die sonst die Größengrenze reißen würden. Der letzte Punkt ist konkret: Die zusammengefügten Regeln sind begrenzt, und wenn Sie darüber kommen, wird abgeschnitten — dazu gleich mehr. Der erste Punkt ist die eben erwähnte Grenze: 32 Kibibyte für alle zusammengefügten Regeln. Was darüber liegt, wird nicht gelesen, und Sie merken es nicht.

15:18 Der zweite ist tückisch: Widersprüche zwischen Ebenen fallen erst im Ergebnis auf, nicht beim Schreiben. Der dritte betrifft das Maß — zu viele Ebenen kann niemand mehr nachvollziehen. Und der vierte ist der, den man selbst verursacht: Global gesetzte Vorlieben wirken auch in fremden Projekten, in denen sie vielleicht gar nicht erwünscht sind.

Bestehende Dateien verbessern

15:39 Eine Frage, die sich nach ein paar Monaten stellt: Was macht man mit einer Datei, die gewachsen ist? Denn das ist der Normalfall — nicht die fehlende Datei, sondern die überfüllte. Sehen wir uns an, wie man sie wieder auf das Wirksame eindampft. Der wichtigste Handgriff dabei ist das Streichen — und ausgerechnet der fällt den meisten Teams am schwersten, weil jede Regel einmal einen Anlass hatte.

16:02 Eine AGENTS.md ist Quellcode und braucht Pflege. Der häufigste Fehler ist nicht die fehlende Datei, sondern die gewachsene: zu lang, teils überholt, in Teilen längst durch Werkzeuge abgedeckt. Der Grund für dieses Wachstum ist verständlich — jedes Mal, wenn etwas schiefgeht, ergänzt jemand eine Regel. Niemand streicht je eine.

16:21 Nach einem Jahr steht dort eine Sammlung, die in jeder Session Kontext kostet und zur Hälfte nicht mehr stimmt. Fünf Schritte für den Frühjahrsputz. Jede Regel gegen den heutigen Code prüfen. Überholtes streichen, statt es zu relativieren — „meistens gilt" ist keine Regel. Beschreibungen in Befehle umschreiben. Werkzeuggedecktes entfernen, denn der Linter ist zuverlässiger als jede Textzeile.

16:46 Und Bereichsspezifisches nach unten in die Unterordner verschieben. Die Fußzeile nennt den wirksamsten Schritt: Streichen. Jede Zeile, die Sie entfernen, spart Kontext in jeder einzelnen Session — dauerhaft und für alle im Team. Vier Prüfsteine. Sie enthält Befehle, die man kopieren kann. Jede Regel lässt sich an einem Beispiel im Code belegen.

17:08 Nichts darin steht schon im README oder wird vom Linter erzwungen. Und sie passt bequem in wenige Bildschirmseiten. Der letzte Punkt ist nicht nur Ästhetik: Eine Datei, die niemand mehr überblickt, wird auch nicht mehr gepflegt — und ungepflegte Regeln sind die, die in die Irre führen. Kurz zu bleiben ist also kein Selbstzweck, sondern die Voraussetzung für Aktualität.

17:30 Das Ziel dieser Übung ist unbequem: Mindestens ein Drittel soll verschwinden oder in exakte Befehle umgeschrieben werden — ohne dass die Datei an Wirkung verliert. Bei den meisten gewachsenen Regelwerken ist das erreichbar. Der Hinweis nennt eine nützliche Abkürzung: Lassen Sie sich vom Agenten Widersprüche zwischen Datei und Code zeigen.

17:50 Das Erheben kann er gut. Entscheiden müssen Sie — denn ob eine Regel gilt und der Code falsch ist oder umgekehrt, weiß nur Ihr Team.

Arbeiten innerhalb der Leitplanken

17:58 Zum Abschluss die Einordnung, die dieses ganze Modul erst richtig verortet: Was kann eine Regeldatei überhaupt bewirken — und was nicht? Denn hier gibt es ein verbreitetes Missverständnis, das im schlechtesten Fall zu falscher Sicherheit führt — man hält für abgesichert, was nur aufgeschrieben ist. Die Auflösung ist einfach, aber sie muss einmal deutlich ausgesprochen werden.

18:20 Leitplanken sind das Zusammenspiel aus drei Dingen: Projektregeln, Berechtigungen und Prüfschritten. Die AGENTS.md sagt, was gelten soll. Sandbox und Freigaben bestimmen, was technisch möglich ist. Und das Review zeigt, was tatsächlich geschehen ist. Diese drei Ebenen zu verwechseln ist der Fehler, um den es hier geht. Eine Regel ist ein Wunsch in Textform — ein sehr wirksamer Wunsch, aber eben keine Zusicherung.

18:46 Wer sie für eine Grenze hält, sichert sein Projekt an der falschen Stelle ab. Diese drei Zeilen sind der Kern des Kapitels. Die Absichtsebene — die AGENTS.md — wirkt dauerhaft, aber sie ist nicht erzwungen. Die technische Ebene — Sandbox und Freigaben — begrenzt hart; hier kann der Agent schlicht nicht, was nicht erlaubt ist.

19:07 Und die Prüfebene — Diff, Tests, Review — macht sichtbar, was passiert ist. Alle drei zusammen ergeben Kontrolle. Einzeln ergibt jede nur ein Teilbild. Modul sieben vertieft die technische Ebene ausführlich. Der erste Punkt fasst die Kernaussage zusammen: Regeln sind Text, keine Zusicherung, und sie können missachtet werden.

19:28 Der zweite ist die praktische Folge — ohne Diff-Kontrolle fällt eine Missachtung überhaupt nicht auf. Der dritte beschreibt eine typische Fehlreaktion: Man ergänzt immer neue Regeln, wo eine technische Grenze fehlen würde. Und der vierte warnt vor dem Gegenteil: Zu enge Leitplanken erzeugen ständige Rückfragen, und ständige Rückfragen erzeugen genau das gedankenlose Wegklicken, das sie verhindern sollten.

19:52 Der Hinweis ist hier der eigentliche Kniff: Formulieren Sie den Auftrag so, dass die Regel im Weg steht. Ein Auftrag, der ohnehin regelkonform ist, beweist nichts. Erst wenn der Agent in Versuchung gerät — etwa einen Test anzupassen, um schneller grün zu werden —, zeigt sich, ob die Regel greift. Dokumentieren Sie den Lauf.

20:11 Und seien Sie nicht überrascht, wenn das Ergebnis Sie zwingt, eine Regel neu zu formulieren. Genau dafür ist die Übung da. Vier Punkte zum Mitnehmen. AGENTS.md ist für Agenten, die README für Menschen — Doppelungen kosten nur Kontext. Exakte Befehle wirken, Absichtserklärungen nicht. Regeln schichten sich vom Benutzerordner bis ins Arbeitsverzeichnis, und das Nächstgelegene wiegt am schwersten.

20:37 Und der Punkt, der über dieses Modul hinausweist: Regeln sind Absicht, keine Grenze. Die Grenze setzen Sandbox und Review. Im nächsten Modul geht es darum, wie Sie den Agenten dazu bringen, erst zu denken und dann zu schreiben.