AGENTS.md für AI Coding: Repository-Regeln für produktive KI-Agenten
AGENTS.md wird relevant, sobald AI Coding nicht mehr nur im Editor stattfindet, sondern Aufgaben in echten Repositories übernimmt. Für wachsende Teams ist die Datei kein weiteres README, sondern ein Steuerungsinstrument: Sie beschreibt, wie KI-Agenten bauen, testen, ändern und wo sie nicht eigenständig entscheiden sollen.
Was AGENTS.md für AI Coding leistet
AGENTS.md gibt Coding Agents wie Codex, Claude Code, Cursor, Gemini CLI oder GitHub Copilot einen stabilen Projektkontext. Statt bei jeder Aufgabe dieselben Hinweise in den Prompt zu schreiben, liegen zentrale Regeln versioniert im Repository.
Der praktische Nutzen entsteht in vier Bereichen:
- Build- und Testpfade: Agenten wissen, welche Befehle vor einem Pull Request laufen müssen und welche Checks lokal aussagekräftig sind.
- Architekturgrenzen: Module, Ownership und unerwünschte Abhängigkeiten werden sichtbar, bevor ein Agent quer durch das System Änderungen vorschlägt.
- Qualitätsstandards: Regeln zu Typisierung, Migrationsskripten, API-Kompatibilität oder Feature Flags reduzieren plausible, aber unpassende Lösungen.
- Sicherheitsgrenzen: Secrets, Produktionsdaten, Compliance-Pfade und verbotene Aktionen gehören ausdrücklich in den Kontext.
Damit wird AGENTS.md zu einer kleinen, aber wichtigen Schnittstelle zwischen Softwarearchitektur, Engineering-Qualität und AI Governance. Die Datei ersetzt keine guten Reviews. Sie sorgt aber dafür, dass jeder Agent mit denselben Grundannahmen startet.
Wo Teams AGENTS.md falsch einsetzen
Der häufigste Fehler ist Vollständigkeit. Teams kopieren Architekturentscheidungen, Onboarding-Text, historische Begründungen und jede Sonderregel in eine Datei, die der Agent bei jeder Aufgabe lesen soll. Das erhöht Kosten, verlängert Läufe und macht falsche Prioritäten wahrscheinlicher.
Eine wirksame AGENTS.md sollte knapp und operativ bleiben:
- Nur Regeln aufnehmen, die Verhalten ändern: Wenn ein Hinweis keine konkrete Entscheidung beeinflusst, gehört er eher in normale Dokumentation.
- Befehle aktuell halten: Veraltete Testbefehle sind schlimmer als keine Befehle, weil Agenten ihnen oft konsequent folgen.
- Nicht-funktionale Anforderungen nennen: Security, Performance, Datenschutz und Barrierefreiheit werden sonst leicht von funktionalen Änderungen verdrängt.
- Review-Punkte explizit machen: Bereiche wie Datenmodelle, Berechtigungen oder Zahlungslogik sollten menschliche Freigabe verlangen.
- Ownership festlegen: Jemand muss die Datei pflegen, sonst wird sie zu einer weiteren Quelle technischer Schulden.
Für größere Organisationen ist zusätzlich wichtig, AGENTS.md nicht als Schattenprozess einzuführen. Die Datei muss zu Code-Review-Regeln, CI, Architekturentscheidungen und internen Compliance-Vorgaben passen. Sonst entsteht ein zweites Regelwerk, das niemand wirklich besitzt.
Warum das wichtig ist
AI Coding skaliert schlechte Annahmen genauso schnell wie gute. Wenn ein Agent die falschen Testbefehle nutzt, eine Architekturgrenze übersieht oder Sicherheitsanforderungen nicht kennt, wird aus Geschwindigkeit schnell Nacharbeit. Das betrifft nicht nur Entwickler, sondern Budget, Release-Risiko und Vertrauen in automatisierte Entwicklungsprozesse.
AGENTS.md ist deshalb vor allem eine Führungsfrage. Technische Entscheider sollten klären, welche Regeln wirklich geschäftskritisch sind, wer sie pflegt und wie ihre Wirkung im Review sichtbar wird. Richtig eingesetzt macht die Datei AI Coding nicht magisch, aber berechenbarer. Eine Architecture & AI Review kann prüfen, ob Agenten-Kontext, Repository-Struktur und Qualitätsprozess zusammenpassen.