Auf dieser Seite
Leitfäden für KI-Agenten schreiben
Ein KI-Agent beginnt jede neue Sitzung ohne Wissen über das Projekt. Er kennt die Programmiersprache und verbreitete Bibliotheken, aber nicht die Architektur dieses Codes, seine Konventionen und den Befehl, mit dem hier die Tests laufen. Manches davon kann er sich aus dem Code erschließen, das kostet aber bei jeder Aufgabe Zeit und Kontext. Den Rest rät er, und zwar plausibel.
Ich arbeite spezifikationsgetrieben mit KI-Agenten. Die Leitfäden dafür liegen versioniert im Repository des jeweiligen Projekts. Dieser Artikel beschreibt, was sich allgemein bewährt hat. Er ergänzt den Überblick in Vom Prompt zum Pull Request.
Was hineingehört
Ein Leitfaden beantwortet die Fragen, die ein Agent sonst aus dem Code erraten müsste:
- Befehle. Wie wird gebaut, getestet, geprüft? Mit dem genauen Aufruf.
- Aufbau. Welche Schichten gibt es, und was gehört wohin?
- Konventionen. Wie heißen Dinge? Welche Muster sind üblich, welche unerwünscht?
- Grenzen. Was darf nicht angefasst werden? Was braucht eine Rückfrage?
- Fertig. Woran ist zu erkennen, dass eine Aufgabe abgeschlossen ist?
Ein ausgedachtes, vereinfachtes Beispiel:
## Prüfen
Vor jedem Commit: `bun run check` (Typen, Linting, Tests, Build).
Schlägt ein Test fehl, wird der Code korrigiert, nicht der Test. Tests werden nicht übersprungen. Scheint ein Test selbst falsch, erst nachfragen.
## Aufbau
- `src/pages/` Routen, keine Logik
- `src/components/` wiederverwendbare Bausteine
- `src/lib/` reine Funktionen ohne Bezug zum Framework
`lib` importiert nie aus `components`.
## Nicht anfassen
- `public/fonts/` Schrift-Subsets, werden per Skript erzeugt
## Vorher fragen
- neue Abhängigkeiten, Änderungen an der Build-Konfiguration
## Fertig
`bun run check` ist grün, neue Logik in `src/lib/` hat Tests, die Änderung ist im Pull Request beschrieben.
Was nicht hineingehört
Die Versuchung ist groß, alles aufzuschreiben. Ein langer Leitfaden wird schlechter befolgt als ein kurzer, weil das Wichtige darin untergeht, und er belegt in jeder Sitzung Kontext. Als Richtwert: so kurz, dass ein Mensch ihn in wenigen Minuten liest.
- Nichts, was der Code eindeutig zeigt. Dass es einen Ordner
src/pages/gibt, sieht der Agent selbst. Dass dort keine Logik hingehört, sieht er nicht. - Nichts Allgemeines. „Schreibe sauberen Code” ändert kein Verhalten.
- Keine Geheimnisse. Zugangsdaten, Tokens, interne Adressen und echte Personendaten gehören nicht in den Leitfaden. Er liegt im Repository und wird in jeder Sitzung an das Modell übertragen. Er nennt höchstens, woher ein Wert kommt, etwa aus einer lokalen
.env, die nicht eingecheckt wird. - Keine Regel, die ein Werkzeug ohnehin prüft. Format prüft der Linter, Schichtregeln prüfen Architekturtests. In Java geht das etwa mit ArchUnit, in TypeScript mit Lint-Regeln für Importgrenzen. Im Leitfaden steht dazu höchstens ein Satz wie im Beispiel oben. So lernt der Agent die Regel nicht erst am roten Build.
Die Faustregel: Jeder Satz muss etwas am Verhalten des Agenten ändern. Würde der Agent ohne den Satz dasselbe tun, ist er überflüssig.
Regeln mit Begründung
„Keine Abfragen in Schleifen” wird befolgt. „Keine Abfragen in Schleifen, weil die Listen hier mehrere tausend Einträge haben” wird befolgt und eher auch auf Fälle übertragen, die der Satz nicht nennt.
Eine Begründung macht aus einer Regel ein Prinzip. Das gilt für Agenten wie für Menschen.
Kontext in Schichten
Nicht alles ist für jede Aufgabe wichtig. Ich gliedere deshalb in Schichten:
- Der Leitfaden ist kurz und gilt immer.
- Ein Architekturüberblick beschreibt die großen Zusammenhänge.
- Eine Karte des Codes sagt, wo etwas zu finden ist.
- Anleitungen für einzelne Aufgaben, sogenannte Skills, werden nur herangezogen, wenn sie gebraucht werden.
Der Leitfaden verweist auf die anderen Schichten, damit der Agent sie findet. Er muss dadurch nicht bei jeder Aufgabe das halbe Repository lesen. Die Karte veraltet als Erste; wo es geht, sollte sie deshalb per Skript entstehen.
Aus Fehlern werden Regeln
Die meisten Regeln entstehen nicht am Schreibtisch. Macht ein Agent denselben Fehler zweimal, fehlt eine Angabe. Ich ergänze sie an der passenden Stelle und prüfe, ob der Fehler danach ausbleibt.
Umgekehrt entferne ich Regeln, die nichts mehr bewirken. Ein Leitfaden, der nur wächst, wird zu der Dokumentation, die niemand liest.
Derselbe Text hilft Menschen
Ein guter Leitfaden für einen Agenten ist ein brauchbarer Kern für den Einstieg einer neuen Person. Befehle, Aufbau, Konventionen und Grenzen sind genau das, was in der ersten Woche gebraucht wird.
Ich schreibe deshalb einen Text für beide. Das hat einen Nebeneffekt: Ein veralteter Befehl fällt schnell auf, weil der Agent daran scheitert. Dokumentation, die nur für den Einstieg gedacht ist, veraltet dagegen, weil sie zwischen zwei Neuzugängen niemand anfasst. Veraltete Konventionen fallen allerdings auch im Leitfaden nicht von selbst auf. Der Agent befolgt sie einfach. Eine Änderung am Leitfaden gehört deshalb in denselben Pull Request wie die Codeänderung, die ihn betrifft.
Für mehrere Agenten
Verschiedene Werkzeuge suchen ihre Hinweise an verschiedenen Stellen. Bei mir steht der Inhalt nur an einer Stelle, etwa in einer AGENTS.md, die viele Werkzeuge lesen. Werkzeugspezifische Dateien wie CLAUDE.md enthalten nur eine Import-Zeile wie @AGENTS.md oder sind ein symbolischer Link darauf. Ein bloßer Hinweis im Text reicht nicht. Dann hängt es vom Agenten ab, ob er die Datei öffnet. Ändert sich eine Konvention, ändere ich sie an einer Stelle.
Ein Leitfaden ist keine Absicherung
Ein Leitfaden senkt die Zahl der Korrekturen. Er ist aber keine Sicherheitsgrenze. Was ein Agent nicht darf, etwa auf Zugangsdaten oder die Produktion zugreifen, begrenzen Rechte und Freigaben, nicht ein Satz in einer Markdown-Datei. Auch die Prüfung jeder Änderung ersetzt der Leitfaden nicht.
Wie Aufgaben so beschrieben werden, dass sich das Ergebnis prüfen lässt, steht im Artikel über Spezifikationen.
Thema für Ihr Projekt?
Passende Leistung: Agentische Entwicklung einführen. Schildern Sie mir kurz, worum es geht. Ich melde mich mit einer ersten Einschätzung.
Projekt anfragen