Agent-Ready Codebase – warum der größte Hebel im Repository liegt

Du kennst dein Projekt. Wenn du eine Änderung machst, weißt du, welche drei Dateien betroffen sind, welcher Test seit Monaten rot ist und warum der eine Ordner so heißt, wie er heißt. Nichts davon steht irgendwo geschrieben. Es steht in deinem Kopf.

Ein Agent startet jeden Lauf ohne dieses Wissen. Er sucht es sich über Werkzeugaufrufe zusammen: Verzeichnisse auflisten, Dateien lesen, Muster erraten. Jeder dieser Schritte kostet Token, füllt das Kontextfenster und ist eine Gelegenheit, das Falsche zu schließen.

Developer Experience und Agent Experience

Codebases wurden über Jahrzehnte für menschliche Leser optimiert. Für Agenten gelten teilweise dieselben, teilweise andere Anforderungen. Der Unterschied zeigt sich bei vier Fragen.

Beides schließt sich nicht aus. Fast alles, was ein Repository für Agenten gut macht, macht es auch für neue Kolleginnen und Kollegen gut. Der Unterschied ist, dass ein Agent gnadenlos vorführt, was undokumentiert geblieben ist.

Wo diese Lesson ansetzt

In Prompts, die halten geht es darum, wie du einen Coding-Agenten briefst. Diese Lesson dreht die Richtung um: Was du wiederholt in jeden Prompt schreibst, gehört nicht in den Prompt, sondern ins Repository. Wer den Agenten immer weiter briefen muss, hat meistens ein Strukturproblem und kein Formulierungsproblem.

Was du nach dieser Lesson kannst

• Die Lokalität deines Repos messen und benennen, was sie kostet
• Eine Agenten-Doku schreiben, die anweist statt beschreibt
• Eine Architekturkarte anlegen, die teure Erkundung ersetzt
• Festlegen, was ein Agent programmatisch nie lesen darf
• Den Zustand eines Laufs aus dem Kontextfenster auf die Platte verlagern
• Den Beweis vom Prompt in das Projekt verschieben

Es gibt eine Zahl, die mehr über die Agententauglichkeit eines Projekts aussagt als jede Architekturbeschreibung.

Wenn Geschäftslogik über Hilfsklassen, Orchestrierungsschichten und geteilte Helfer verstreut ist, muss er das alles in den Kontext laden, bevor er die erste Zeile ändern kann. Das kostet doppelt: linear zur Dateigröße in Token, und überproportional in Genauigkeit, weil wichtige Anweisungen im Rauschen untergehen.

Schichten gegen Scheiben

Der übliche Zuschnitt organisiert Code nach technischen Schichten. Der agentenfreundliche Zuschnitt organisiert ihn nach fachlichen Anwendungsfällen. Dieselbe Änderung sieht in beiden Welten völlig anders aus.

Die Reichweite von Seiteneffekten

Der zweite Begriff neben Lokalität ist die Reichweite: Wie weit strahlt eine Änderung an einer isolierten Stelle aus? Explizite Schnittstellen und durchgesetzte Abhängigkeitsregeln halten sie klein, und zwar mechanisch. Eine Regel, die nur in einer Absprache existiert, hält einen Agenten nicht auf.

Für Agenten-Anweisungen hat sich ein offenes Dateiformat durchgesetzt: AGENTS.md im Wurzelverzeichnis, bei Bedarf zusätzlich in Unterordnern. Der Agent nimmt jeweils die nächstgelegene Datei im Verzeichnisbaum.

Eine README beschreibt, eine AGENTS.md weist an

Das ist der ganze Unterschied, und er entscheidet über den Nutzen. Prosa über die Philosophie des Projekts hilft einem Agenten nicht. Ausführbare Kommandos und harte Grenzen helfen ihm.

Die rechte Spalte ist in jeder Zeile länger und konkreter. Das ist kein Zufall. Der Wert einer Agenten-Anweisung liegt genau in der Konkretheit, die eine README bewusst weglässt, weil ein Mensch sie sich denken kann.

Der Junior-Test

Die Prüfmethode, mit der du herausfindest, was fehlt: Könnte jemand, der neu im Projekt ist, diese Aufgabe ohne eine einzige Rückfrage erledigen? Jede Stelle, an der die Antwort nein lautet, ist eine Zeile für die Datei.

Was dabei zuverlässig auftaucht, ist das ungeschriebene Wissen, das im Team niemand mehr für erwähnenswert hält.

• Welche Tests bekannt rot sind und ignoriert werden dürfen
• In welcher Reihenfolge Pakete gebaut werden müssen
• Welches Build-Flag lokal nötig ist und in der Pipeline nicht
• Welcher Ordner generiert wird und deshalb nie von Hand geändert werden darf
• Welche Bibliothek für einen Zweck gesetzt ist, obwohl drei im Projekt liegen

Eine erste Fassung

Ohne Karte rekonstruiert jeder Lauf die Struktur des Projekts neu. Verzeichnisse auflisten, Dateien öffnen, aus Namen auf Zuständigkeiten schließen. Das Ergebnis dieser Arbeit wird am Ende der Sitzung weggeworfen und beim nächsten Lauf noch einmal erzeugt.

Eine Architekturkarte ist die vorgefertigte Antwort auf diese Erkundung: eine statische Übersicht, die einmal erzeugt und danach gelesen wird.

Was hineingehört

• Modulgrenzen: welche Bereiche es gibt und wofür jeder zuständig ist
• Abhängigkeitsrichtung: wer darf wen benutzen, und wer ausdrücklich nicht
• Wo was liegt: Einstiegspunkte, Konfiguration, generierte Bereiche
• Konventionen mit einem Beispiel statt mit einer Erklärung
• Bekannte Fallstricke: die Stellen, an denen schon dreimal jemand hereingefallen ist

Das Prinzip dahinter kennst du bereits

Praktisch heißt das: Der Einstiegspunkt bleibt klein und verweist. Die Karte kommt dazu, wenn Struktur gebraucht wird. Eine Entscheidungsbegründung kommt dazu, wenn jemand sie infrage stellt. Nichts davon wird vorsorglich geladen.

Wie das in einem echten Projekt aussieht

Diese Website liegt in einem Arbeitsbereich mit rund zehn Projekten nebeneinander. Die Agenten-Doku dafür ist auf vier Ebenen verteilt.

Zusammen sind das gut vierhundert Zeilen. Als eine einzige Datei wären sie unbrauchbar, weil jeder Lauf alles lesen müsste. Aufgeteilt liest ein Agent, der an einer Farbdefinition arbeitet, die Styling-Regeln und nicht die Content-Regeln.

Das ist der eigentliche Wert der lokalen Datei: Sie überschreibt, was weiter oben steht. Ein Agent, der im Projektordner arbeitet, bekommt die Projektwahrheit und nicht die Wurzelwahrheit.

Dieser Hebel wird am häufigsten übersehen, weil er nichts hinzufügt. Er nimmt weg. Und er ist der einzige in dieser Lesson, der an einem Vormittag fertig ist.

Drei Maßnahmen

1. Ausschlussregeln konfigurieren. Build-Artefakte, generierter Code, Abhängigkeitsverzeichnisse und fremde Pakete gehören programmatisch gesperrt.
2. Im richtigen Verzeichnis starten. Eine Sitzung, die logisch nur ein Teilpaket betrifft, gehört nicht in die Wurzel eines Monorepos.
3. Nur auschecken, was gebraucht wird. Über eingeschränkte Arbeitskopien lässt sich der Dateibaum verkleinern, sodass die Suchwerkzeuge des Agenten gar nicht erst auf Irrelevantes stoßen.

Der Monorepo-Fall

Der typische Fehlermodus ist gut beobachtbar: Der Agent arbeitet an einem Backend-Dienst, liest dabei die Konventionen aus einem Frontend-Paket und produziert Code, der im falschen Stil geschrieben ist und die falschen Bibliotheken benutzt. Das ist kein Modellfehler. Das ist ein Kontextfehler.

Daraus wird oft der Schluss gezogen, Monorepos seien für Agenten ungeeignet. Das trifft es nicht. Ein Monorepo ist unproblematisch, wenn die Isolation konfiguriert ist, und problematisch, wenn nicht. Ein Polyrepo erzwingt dieselbe Isolation durch physische Trennung und bezahlt sie mit Aufwand an anderer Stelle.

Die Liste, die du fast sicher zu kurz schreibst

• Abhängigkeitsverzeichnisse und mitgelieferte Fremdbibliotheken
• Build-Ausgaben und Zwischenverzeichnisse
• Generierter Code: Schnittstellen-Clients, Migrationen, Typdefinitionen aus Schemas
• Große Testdaten, Momentaufnahmen und Fixtures
• Lockfiles
• Binärdateien und Assets
• Pakete, an denen gerade nicht gearbeitet wird
• Archivordner, die aus Sentimentalität liegen geblieben sind

Das Kontextfenster ist flüchtig. Wird es voll, fasst das Werkzeug den bisherigen Verlauf zusammen und arbeitet mit der Zusammenfassung weiter. Was in dieser Verdichtung wegfällt, ist verloren, und es fällt genau das weg, was nach Detail aussieht: Dateinamen, Zahlen, der Grund für eine Entscheidung.

Ein Agent, der seinen Zustand nur im Kontext hält, verliert bei jeder Verdichtung den Faden. Er liest die Dateien erneut ein, das Fenster füllt sich wieder, die nächste Verdichtung folgt. Diese Schleife ist teuer und ihr Ergebnis wird mit jedem Durchlauf schlechter.

Auslagern statt behalten

Die Gegenmaßnahme ist einfach: Der Agent führt eine Zustandsdatei. Was erledigt ist, was offen ist, was als Nächstes kommt. Die Datei liegt auf der Platte und überlebt jede Verdichtung.

Damit das passiert, muss es in der Agenten-Doku stehen. Eine Anweisung wie "Führe während der Arbeit eine Zustandsdatei und aktualisiere sie nach jedem abgeschlossenen Teilschritt" genügt, wenn sie an einer Stelle steht, die jeder Lauf liest.

Lesen delegieren

Der zweite Hebel gehört in dieselbe Familie: Der Hauptlauf liest keine großen Dateien und keine langen Ausgaben selbst. Er beauftragt einen Teilagenten, der in seinem eigenen, leeren Kontext analysiert und nur das Ergebnis zurückgibt. Als Größenordnung für die Rückgabe nennt Anthropic ein- bis zweitausend Token.

In Prompts, die halten steht das Prinzip: Ohne Beweis ist nichts fertig, und du verlangst den Beweis im Prompt. Dieser Schritt geht eine Ebene tiefer. Wenn das Repository den Beweis erzwingt, musst du ihn nicht mehr erbitten.

Planen, Ausführen, Prüfen

Der Zyklus ist bekannt: Ziel und Grenzen festlegen, dann ändern, dann verifizieren. Der dritte Schritt ist der, der in der Praxis fehlt, und ohne ihn bricht der Rest zusammen.

Drei Hebel

Der dritte Hebel ist der wirtschaftlich unterschätzte. Er verhindert, dass das Modell Ausgabe-Token für Einrückungen, Anführungszeichen und Importreihenfolgen erzeugt. Ausgabe ist die teure Seite der Rechnung, und Formatierung ist deterministisch. Sie gehört der lokalen Maschine, nicht dem Modell.

Ein Kommando statt fünf

Damit der Agent überhaupt prüfen kann, braucht er einen Einstiegspunkt. Fünf einzelne Kommandos in der Doku bedeuten, dass er drei davon vergisst.

Der Wert liegt nicht im Skript, sondern darin, dass es genau ein Kommando gibt, das eine eindeutige Antwort liefert, und dass dieses Kommando in der Agenten-Doku als Abgabebedingung steht. Dasselbe Skript läuft danach als Haken vor jedem Commit und in der Pipeline. Drei Orte, eine Wahrheit.

Die sechs Regeln

Die Reihenfolge

Alle sechs Regeln gleichzeitig anzugehen ist der zuverlässigste Weg, keine davon umzusetzen. Nach Aufwand und Wirkung sortiert ergibt sich eine klare Folge.

Der Selbsttest

• Wie viele Dateien liest ein Agent bei einer typischen Änderung, ohne sie zu ändern?
• Welche Regel schreibst du regelmäßig von Hand in Prompts, obwohl sie immer gilt?
• Welches ungeschriebene Wissen würde eine neue Person am ersten Tag erfragen?
• Welche Verzeichnisse deines Repos hat ein Agent zuletzt gelesen, ohne dass es einen Grund gab?
• Gibt es ein einziges Kommando, das eindeutig sagt, ob eine Änderung trägt?

Was bleibt

Der Befund dieser Lesson ist unbequem und praktisch zugleich. Wer mit Agenten arbeitet und unzufrieden ist, sucht den Fehler meistens beim Modell oder beim Prompt. In den seltensten Fällen liegt er dort. Er liegt in dem, was das Projekt über sich selbst nicht sagt.