AGENTS.md

AGENTS.md als Betriebsanleitung

0:00 Im letzten Modul haben wir gelernt, Kontext gezielt zu geben. Jetzt machen wir daraus etwas Dauerhaftes. Es gibt eine einfache Faustregel: Was in jeder Sitzung gilt, gehört nicht in jeden Prompt. Genau dafür gibt es eine Datei — die Projektanweisungen, die Pi automatisch lädt. Wir schauen uns an, was hineingehört, wie man Architektur und Standards knapp beschreibt und wo die drei Ebenen liegen, auf denen solche Anweisungen wirken.

0:25 Und wir sprechen über die Versuchung, aus dieser Datei ein Handbuch zu machen — denn die kostet Sie in jeder Sitzung Kontext.

Regeln, die bleiben

0:33 Acht Kapitel, und ein Gedanke trägt sie alle: Diese Datei liegt im Repository. Das heißt, sie wird versioniert, sie wird reviewt, und sie gilt für jeden im Team — unabhängig davon, wer den Agenten startet. Das ist die eigentliche Neuigkeit gegenüber persönlichen Prompt-Sammlungen. Wir beginnen mit der Aufgabe der Datei, arbeiten uns über Architektur, Stil und Qualität vor und enden mit der Frage, wie sich eine Codebasis insgesamt agentenfreundlich machen lässt.

1:01 Der Satz, den ich Ihnen mitgeben will, kommt in Kapitel sieben: Jede Zeile kostet Kontext. Vier Punkte. Erstens der Fundmechanismus: Pi sucht Kontextdateien global, in übergeordneten Verzeichnissen und lokal — und das eröffnet mehr Möglichkeiten, als man zunächst denkt. Zweitens die Trennung: Was gehört dauerhaft in eine Datei, was bleibt im Prompt?

1:23 Drittens die drei inhaltlichen Blöcke: Architektur, Stil und Qualität, jeweils knapp und prüfbar formuliert. Und viertens der Grund, warum kurze Regelwerke besser wirken als lange — nicht aus Stilgefühl, sondern aus technischer Notwendigkeit.

Die Aufgabe von AGENTS.md verstehen

1:39 Fangen wir mit dem Mechanismus an. Er ist so simpel, dass man ihn leicht unterschätzt: eine Markdown-Datei im Projekt, die automatisch geladen wird. Genau diese Automatik macht sie so wirksam. Die Datei liegt im Projekt und wird von Pi automatisch als Kontext geladen. Die Dokumentation nennt dabei drei Fundorte: das globale Pi-Verzeichnis, die übergeordneten Verzeichnisse aufwärts und das Arbeitsverzeichnis selbst.

2:04 Und ein praktisches Detail: Die von anderen Werkzeugen bekannte Variante wird gleichwertig gelesen — bestehende Dateien funktionieren also weiter. Denken Sie an die Betriebsanleitung, die an der Maschine hängt: Sie liest sie nicht jedes Mal vor, aber jeder, der die Maschine bedient, hat sie gesehen. Genau diese Rolle übernimmt die Datei hier.

2:24 Vier Gewinne. Regeln wirken in jeder Sitzung, ohne dass Sie sie wiederholen — das spart nicht nur Tipparbeit, es verhindert auch Abweichungen zwischen Personen. Die Datei liegt im Repository, wird also reviewt, versioniert und geteilt; damit ist sie normale Projektarbeit und kein Nebenschauplatz. Wissen bleibt im Projekt, selbst wenn Personen wechseln — für viele Teams das stärkste Argument.

2:47 Und die Kompatibilität zur bekannten Variante bedeutet, dass Sie nichts migrieren müssen, um anzufangen. Worauf es hier ankommt, ist die Kürze. Drei Zeilen, und jede ist prüfbar: ein Prüfbefehl nach Codeänderungen, eine Konvention, wo Tests liegen, und eine Freigabepflicht für neue Abhängigkeiten. Kein Handbuch, keine Absichtserklärung.

3:07 Beachten Sie besonders die erste Zeile — der Prüfbefehl ist die wertvollste Information in der ganzen Datei, weil sie dem Agenten erlaubt, seine Arbeit selbst zu bewerten. Und die Fußnote beschreibt die richtige Wachstumsstrategie: kurz anfangen und nach jeder Korrektur eine Zeile ergänzen.

Globale und lokale Instruktionen unterscheiden

3:25 Jetzt zu den Ebenen. Es gibt drei, und die Zuordnung ist im Alltag wichtiger, als sie klingt — vor allem, weil persönliche Vorlieben in einem Team-Repository nichts verloren haben. Drei Ebenen: global im persönlichen Pi-Verzeichnis, gültig für alle Projekte; in übergeordneten Verzeichnissen, etwa der Wurzel eines Monorepos; und im aktuellen Projekt.

3:46 Dazu kommt eine vierte Möglichkeit: Sie können den Systemprompt durch eine Projektdatei ersetzen oder ergänzen. Das Bild: Hausordnung, Etagenregeln und der Zettel an der Wohnungstür. Alle drei gelten, aber sie haben unterschiedliche Reichweiten — und wenn sie sich widersprechen, sollten Sie das auflösen, statt es stehen zu lassen.

4:07 Persönlicher Arbeitsstil gehört global — Ihr Wunsch nach knappen Antworten interessiert das Team nicht und sollte es nicht im Review beschäftigen. In Monorepos legen Sie gemeinsame Regeln oben ab und Spezielles im Paket, wo es gepflegt wird. Beachten Sie: Systemprompt-Dateien im Projekt greifen erst nach vergebenem Projektvertrauen — der Mechanismus aus Modul drei wirkt hier direkt.

4:28 Und der vierte Punkt ist eine Pflegeempfehlung: Klare Ebenentrennung verhindert widersprüchliche Anweisungen, die niemand mehr auflösen kann. Die Logik dieser Tabelle ist die Frage nach der Reichweite. Ganz oben stehen Dinge, die nur Sie betreffen: Antwortstil, Sprache. Dann firmenweite Vorgaben wie Lizenzheader oder Namensschemata, die in einem Monorepo an die Wurzel gehören. Dann die eigentlichen Projektregeln: Testbefehl, Ordnerstruktur.

4:55 Und unten das Rollenverhalten über die Systemprompt-Datei — der stärkste Eingriff, deshalb sparsam. Die entscheidende Regel steht in der Fußzeile: Widersprüche zwischen Ebenen auflösen, nicht stapeln. Gestapelte Widersprüche führen zu Verhalten, das niemand erklären kann.

Projektregeln dauerhaft hinterlegen

5:12 Jetzt zur Frage, welche Regeln überhaupt hineingehören. Und die Antwort kommt nicht aus dem Vorratsdenken, sondern aus Ihrem Alltag: Was haben Sie zum zweiten Mal korrigiert? Dauerhafte Projektregeln sind Vorgaben, die für jede Änderung gelten: Befehle, Ordnerkonventionen, verbotene Muster, Freigabepflichten. Sie gehören in die Anweisungsdatei, nicht in den Prompt. Der Auslöser für eine neue Regel ist immer derselbe: Sie haben dieselbe Korrektur zweimal getippt.

5:40 Denken Sie an das Rezeptheft in der Küche: Es enthält nicht alles, was man wissen könnte, sondern die Handgriffe, die man immer wieder braucht — aufgeschrieben, weil man sie sonst jedes Mal neu erklärt. Wiederholte Korrekturen sind das Signal für eine fehlende Regel — nehmen Sie das wörtlich, es ist ein gutes Erkennungsmerkmal.

6:00 Regeln im Repository gelten für alle gleich, was Reibung im Team reduziert. Der Agent hält sich an Befehle, die er kennt, und nicht an vermutete; das klingt selbstverständlich, erklärt aber viele Enttäuschungen. Und ein Nebeneffekt, der oft überrascht: Neue Kolleginnen und Kollegen profitieren mit. Was einem Agenten das Projekt erklärt, erklärt es auch Menschen.

6:22 Der rote Faden: Beobachten, formulieren, einsortieren, prüfen, aufräumen. Sie notieren eine Korrektur, sobald sie zum zweiten Mal auftritt — nicht beim ersten Mal, sonst wird die Datei zum Sammelbecken. Formuliert wird als Imperativsatz: „Nutze X", „Ändere Y nie". Einsortiert wird thematisch, nicht chronologisch, sonst findet niemand etwas.

6:45 Dann prüfen Sie in der nächsten Sitzung, ob die Regel greift. Und der letzte Schritt wird immer vergessen: Regeln streichen, die nicht mehr gelten. Eine Regel, die nie greift, kostet nur Kontext. In dieser Übung leiten Sie drei Regeln aus echten Korrekturen ab — jede als Imperativ formuliert. Das Erfolgskriterium hat einen zweiten Teil, der wichtig ist: In einer neuen Sitzung belegen Sie an einem Beispiel, dass die Regeln greifen.

7:12 Denn eine Regel, die formuliert ist, aber nicht wirkt, ist wertlos — und das kommt häufiger vor, als man denkt, meist weil sie zu abstrakt formuliert war. Aus diesem Nachweis lernen Sie mehr über gute Formulierung als aus jeder Stilempfehlung.

Architekturkonventionen beschreiben

7:27 Jetzt zum ersten inhaltlichen Block. Architektur klingt nach einem großen Thema, aber für unsere Zwecke passt sie in fünf Zeilen — und es geht ausdrücklich nicht um Architekturtheorie. Gemeint sind knappe Aussagen über Struktur und Zuständigkeit: welche Schicht welche Aufgabe hat, wohin neuer Code gehört, welche Abhängigkeitsrichtung erlaubt ist. Nicht mehr.

7:48 Der Vergleich: ein Grundriss mit Raumbeschriftung, nicht ein Aufsatz über Architekturgeschichte. Der Nutzen ist unmittelbar: Ohne diese Angaben legt der Agent neue Dateien dorthin, wo es ihm plausibel erscheint — und plausibel heißt bei einem gewachsenen Projekt oft: dorthin, wo schon zu viel liegt. Ohne Vorgabe entscheidet der Agent nach Plausibilität, nicht nach Ihrer Konvention.

8:11 Abhängigkeitsregeln verhindern Umbauten quer durch alle Schichten — gerade bei Refactorings die wichtigste Leitplanke. Ein Verzeichnisbaum in wenigen Zeilen wirkt stärker als ein Absatz Prosa, weil er eindeutig ist. Und klare Zuständigkeiten machen Reviews kürzer: Sie diskutieren nicht mehr, ob eine Datei am richtigen Ort liegt, weil das schon aufgeschrieben ist.

8:32 Das ist Zeitgewinn, der sich mit jedem Merge Request wiederholt. Worauf es in diesem Ausschnitt ankommt: Jede Zeile nennt einen Ort und eine Grenze. Fachlogik ohne Framework-Importe. Die HTTP-Schicht ruft nur die Fachlogik. Adapter separat. Und der letzte Punkt ist eine Handlungsanweisung für neuen Code, samt Testpflicht. Beachten Sie, was hier fehlt: Begründungen, Muster-Namen, Diagramme.

8:58 Die gehören in die Architekturdokumentation, nicht in diese Datei. Und die Fußnote gibt den Maßstab, der über alle vier Blöcke gilt: Regeln, die man nicht prüfen kann, gehören nicht hinein.

Coding Standards definieren

9:11 Zweiter inhaltlicher Block: Stil. Und hier kommt gleich die wichtigste Abgrenzung — schreiben Sie nicht auf, was Ihre Werkzeuge schon erzwingen. Das wäre eine zweite Wahrheit ohne Nutzen. In die Datei gehört, was Linter und Formatierer nicht ohnehin prüfen: Namensmuster, erlaubte Bibliotheken, Fehlerbehandlung, Umgang mit Kommentaren und Logging.

9:32 Alles, was ein Werkzeug automatisch korrigiert, muss keine Textregel sein. Der Vergleich: Sie schreiben nicht an die Wand, dass das Licht ausgeht, wenn ein Bewegungsmelder das erledigt. Und ein Praxishinweis: Ein konkretes Beispiel wirkt in dieser Datei fast immer besser als eine abstrakte Regel — weil das Modell Muster besser übernimmt als Prinzipien.

9:54 Was der Formatierer prüft, braucht keine Textregel — das entlastet die Datei und verhindert Widersprüche, wenn sich die Werkzeugkonfiguration ändert. Bibliotheksvorgaben verhindern ungewollte neue Abhängigkeiten; das ist einer der häufigsten Reibungspunkte bei agentengestützter Arbeit. Fehlerbehandlung ist gleichzeitig Stil- und Sicherheitsfrage, gehört also hierher.

10:15 Und noch einmal der Hinweis auf Beispiele: Ein Codeschnipsel als Vorbild ist konkreter als drei Sätze, die dasselbe beschreiben. Vier Beispiele, an denen sich das Muster gut zeigen lässt. „Fehler nie verschlucken, immer typisiert weitergeben" — das ist prüfbar, man sieht es im Code. „Keine neuen Abhängigkeiten ohne Rückfrage" — eine Prozessregel, die viel Ärger erspart.

10:39 „Kommentare erklären das Warum, nicht das Was" — die einzige Kommentarregel, die man wirklich braucht. Und die Logging-Regel, die verhindert, dass Debug-Ausgaben in Produktion landen. Achten Sie darauf: Alle vier sind kurz, alle vier sind überprüfbar, keine ist eine Absichtserklärung.

Test und Qualitätsanforderungen festlegen

10:57 Dritter Block, und für mich der wichtigste. Wenn Sie nur eine Zeile in diese Datei schreiben, dann den Prüfbefehl. Er verwandelt „fertig" von einer Meinung in eine Feststellung. Hier legen Sie fest, was nach einer Änderung ausgeführt wird und wann eine Änderung fertig ist: Testbefehl, Typprüfung, Linter, gegebenenfalls Mindestabdeckung — und der Umgang mit fehlschlagenden Tests.

11:20 Der letzte Punkt ist kein Detail: Ohne Vorgabe kann es passieren, dass ein Agent den einfachsten Weg zum grünen Zustand wählt, und der einfachste Weg ist manchmal, den Test abzuschalten. Was Sie nicht ausschließen, dürfen Sie nicht als ausgeschlossen annehmen. Der Agent kann prüfen, sobald er den Befehl kennt — das ist der ganze Hebel. „Fertig" wird damit objektiv statt Verhandlungssache.

11:43 Und eine einzige Zeile wie „nach jeder Änderung den Prüfbefehl ausführen" wirkt sofort, ohne weitere Konfiguration. Der vierte Punkt ist die eben erwähnte Leitplanke: Rote Tests dürfen nie mit einem Übersprung-Vermerk beruhigt werden. Schreiben Sie das ausdrücklich hin. Es ist eine dieser Regeln, die man für selbstverständlich hält — bis man sie in einem Diff vermisst.

12:06 Worauf es hier ankommt, ist die Prüfbarkeit jeder Zeile. Nach jeder Änderung ein konkreter Befehl. Neue Fachlogik braucht einen Test. Tests nicht stilllegen. Und bei rotem Test: Ursache melden statt umgehen. Lesen Sie diese vier Zeilen als Vertrag — jede lässt sich in einem Diff überprüfen. Genau das unterscheidet wirksame von dekorativen Regeln. Und wenn Sie im Alltag merken, dass eine Zeile nie zur Anwendung kommt, gehört sie gestrichen.

12:35 Auch das ist Pflege dieser Datei. Diese Übung ist klein und hat große Wirkung. Sie schreiben den Prüfbefehl in die Anweisungsdatei — und das Erfolgskriterium lautet: Der Agent prüft eine Änderung selbst, ohne dass der Befehl im Prompt stand. Damit sehen Sie unmittelbar, wie Kontextdateien wirken: Etwas, das Sie nie erwähnt haben, passiert trotzdem.

12:55 Für viele ist das der Moment, in dem der Nutzen dieser Datei zum ersten Mal wirklich greifbar wird — und meist ist es auch die letzte Übung, nach der noch jemand fragt, ob sich der Aufwand lohnt.

Kurze Instruktionen statt überladener Regelwerke schreiben

13:07 Jetzt das Kapitel gegen die häufigste Fehlentwicklung. Diese Datei wächst. Und irgendwann wird sie zum Handbuch, das niemand liest — aber jeder Aufruf bezahlt. Die Datei wird bei jedem Aufruf mitgeschickt. Jede Zeile verbraucht also dauerhaft Kontextbudget — nicht einmal, sondern immer wieder. Daraus folgt: wenige, präzise, prüfbare Regeln statt eines Handbuchs. Der Vergleich: Es ist der Zettel am Schaltkasten, nicht das Servicehandbuch im Regal.

13:36 Beides hat seinen Platz, aber nur eines hängt dort, wo täglich gearbeitet wird. Als Faustregel hat sich eine Bildschirmseite bewährt, thematisch gruppiert. Lange Regelwerke verdrängen den Code, um den es eigentlich geht — ein direkter, messbarer Effekt. Widersprüche in langen Dateien fallen niemandem auf, weil niemand sie ganz liest; und der Agent löst sie nach Wahrscheinlichkeit, nicht nach Ihrer Absicht.

14:00 Was nur selten gilt, gehört in einen Skill statt in diese Datei — das ist genau die Unterscheidung, die wir im nächsten Modul brauchen. Und die Faustregel mit der Bildschirmseite ist keine Schikane, sondern eine gute Sollbruchstelle: Wenn Sie sie überschreiten, prüfen Sie, was raus kann. Vier typische Fehlentwicklungen. Onboarding-Dokumentation in die Datei kopieren — gut gemeint, aber der falsche Ort; verlinken ist besser.

14:26 Regeln formulieren, die man nicht prüfen kann, etwa „schreibe sauberen Code"; das ist Dekoration. Widersprüche zwischen globaler und lokaler Datei stehen lassen, weil es „schon irgendwie passt". Und die Datei nie aufräumen, obwohl das Projekt sich längst verändert hat. Der gemeinsame Kern: Diese Datei braucht Pflege wie Code — zwei Zeilen pro Sprint genügen, aber sie müssen passieren.

AGENTS.md als Bestandteil einer KI freundlichen Codebasis einsetzen

14:50 Zum Abschluss weiten wir den Blick. Die Anweisungsdatei ist ein Baustein, aber nicht der einzige. Eine Codebasis kann insgesamt so gebaut sein, dass Agenten und Menschen sich darin leichter zurechtfinden. Eine KI-freundliche Codebasis macht Absicht explizit: Regeln in der Anweisungsdatei, klare Ordnerstruktur, sprechende Namen, ausführbare Prüfbefehle — und wiederverwendbare Bausteine wie Skills und Prompt Templates für Abläufe.

15:17 Interessant ist die Beobachtung dahinter: Das sind alles Dinge, die auch menschlichen Teams helfen. Es gibt hier keinen Zielkonflikt zwischen „KI-freundlich" und „gut gemacht" — was Absicht sichtbar macht, hilft beiden. Das ist eine der angenehmeren Erkenntnisse dieses Seminars. Explizite Regeln nutzen Menschen und Agenten gleichermaßen — kein Mehraufwand für einen fremden Zweck.

15:40 Ausführbare Checks sind die Brücke zwischen Absicht und Nachweis; ohne sie bleiben Regeln Behauptungen. Abläufe gehören in Skills, Formulierungen in Prompt Templates — die beiden nächsten Module machen genau das. Und der vierte Punkt ist eine Haltungsfrage: Diese Datei wird mit dem Projekt gepflegt, nicht einmal geschrieben und dann vergessen.

16:00 Sonst beschreibt sie in einem Jahr ein Projekt, das es nicht mehr gibt. Der rote Faden: Vom Nötigsten zum Ausbau. Erst die Anweisungsdatei mit Befehlen, Struktur und Grenzen. Dann ein Prüfbefehl, der alles Nötige in einem Aufruf erledigt — diese Investition zahlt sich sofort aus. Danach wiederkehrende Abläufe als Skills, häufige Formulierungen als Templates.

16:22 Und der letzte Schritt ist der unspektakuläre, der über die Halbwertszeit entscheidet: nach jedem größeren Umbau die Regeln nachziehen. Zwei Zeilen Pflege je Sprint halten die Datei brauchbar. Mehr braucht es meist nicht.

Regeln statt Wiederholung

16:37 Halten wir drei Dinge fest. Pi lädt die Anweisungsdatei automatisch — global, aus übergeordneten Verzeichnissen und lokal; Sie müssen nichts dafür tun außer sie anzulegen. Regeln müssen prüfbar sein, sonst wirken sie nicht; das ist der Maßstab für jede Zeile. Und Kürze ist keine Stilfrage, sondern Technik: Jede Zeile kostet Kontext in jeder Sitzung.

16:58 Im nächsten Modul geht es um Fähigkeiten, die über Regeln hinausgehen — um Packages und Erweiterungen, mit denen Sie Pi genau das beibringen, was Ihnen fehlt.