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:

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.

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 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