Inhalt
Projektregeln für Coding-Agents sind Textdateien im Repository, die einem Agent vor jeder Aufgabe erklären, wie Ihr Projekt funktioniert: Befehle, Architektur, Konventionen und Grenzen. Gut geschrieben, sind sie der wirksamste Hebel für bessere Ergebnisse, weil der Agent nicht mehr raten muss. Dieser Leitfaden zeigt, was hineingehört, was nicht – und wie Sie die Dateien dauerhaft aktuell halten.
Was Kontextdateien für Coding-Agents sind
Jedes Agentic-Coding-Werkzeug bietet eine Möglichkeit, dauerhafte Anweisungen zu hinterlegen, die automatisch in den Kontext jeder Sitzung geladen werden. Je nach Werkzeug heißen diese Dateien unterschiedlich, zum Beispiel AGENTS.md als werkzeugübergreifende Konvention, CLAUDE.md bei Claude Code, Regeldateien in einem Konfigurationsordner bei Cursor oder eine Instruktionsdatei für GitHub Copilot. Prüfen Sie in der Dokumentation Ihres Werkzeugs, welche Dateinamen und Speicherorte unterstützt werden.
Inhaltlich erfüllen alle denselben Zweck: Sie ersetzen das Onboarding-Gespräch, das ein neuer Kollege am ersten Tag bekäme. Ohne diese Informationen orientiert sich der Agent an allgemeinen Mustern aus seinen Trainingsdaten – und die passen selten genau zu Ihrem Projekt. Typische Folgen fehlender Regeln sind falsche Bibliotheken, abweichender Codestil, doppelte Hilfsfunktionen oder Tests, die anders aufgebaut sind als die bestehenden.
Die wichtigsten Inhalte guter Projektregeln
| Abschnitt | Inhalt | Beispiel |
|---|---|---|
| Projektüberblick | Zweck, Zielgruppe, zentrale Module in zwei bis fünf Sätzen | „Buchungs-App für Physiotherapiepraxen, Backend in Kotlin, App in Flutter“ |
| Befehle | Build, Tests, Linter, lokaler Start – exakt und kopierbar | npm run test -- --watch=false |
| Architektur | Schichten, Verzeichnisstruktur, wo neuer Code hingehört | „Geschäftslogik nur in /domain, nie in UI-Komponenten“ |
| Konventionen | Namensregeln, Fehlerbehandlung, Logging, Teststil | „Fehler als Result-Typ zurückgeben, keine Exceptions im Domain-Layer“ |
| Abhängigkeiten | Bevorzugte Bibliotheken, verbotene Pakete | „HTTP nur über den vorhandenen ApiClient“ |
| Grenzen und Tabus | Was der Agent nicht ändern oder ausführen darf | „Keine Änderungen an Migrationsdateien, die bereits deployed sind“ |
| Definition of Done | Was vor Abschluss einer Aufgabe erfüllt sein muss | „Tests und Linter grün, Changelog-Eintrag ergänzt“ |
So schreiben Sie Regeln, die Agents wirklich befolgen
Konkret statt allgemein
„Schreibe sauberen Code“ ist wirkungslos, weil jeder Agent das ohnehin versucht. Wirksam sind Regeln, die eine konkrete Entscheidung vorwegnehmen: „Verwende für Datumswerte ausschließlich die Hilfsfunktionen in utils/date.ts.“ Fragen Sie sich bei jeder Regel: Würde ein erfahrener Entwickler ohne Projektkenntnis hier etwas anders machen? Wenn nein, kann die Regel weg.
Kurz und priorisiert
Kontextdateien werden bei jeder Sitzung mitgeladen und konkurrieren mit der eigentlichen Aufgabe um Aufmerksamkeit. Lange Dateien mit Hunderten Regeln führen dazu, dass einzelne Anweisungen untergehen. Halten Sie die Hauptdatei kompakt und stellen Sie das Wichtigste an den Anfang. Detailwissen zu einzelnen Bereichen gehört in separate Dateien, auf die Sie verweisen, oder – wenn Ihr Werkzeug das unterstützt – in Regeldateien in Unterverzeichnissen, die nur dort gelten.
Begründungen mitliefern
Ein kurzer Halbsatz zum Warum hilft dem Agent, die Regel auch in Grenzfällen richtig anzuwenden: „Keine direkten Datenbankzugriffe aus Controllern – wir brauchen die Repository-Schicht für Mandantentrennung.“
Positive Formulierungen und Beispiele
Sagen Sie, was stattdessen zu tun ist, nicht nur, was verboten ist. Ein kurzes Codebeispiel für das gewünschte Muster wirkt oft stärker als ein Absatz Erklärung. Mehr zu den Grundlagen lesen Sie in unserem Beitrag zu Context Engineering.
Was nicht in Kontextdateien gehört
- Secrets und Zugangsdaten: Kontextdateien liegen im Repository und landen im Modellkontext. Passwörter, API-Keys oder interne URLs mit Token haben dort nichts zu suchen – siehe auch Agentic Coding und Datensicherheit.
- Aufgabenspezifische Anweisungen: Was nur für die aktuelle Aufgabe gilt, gehört in den Auftrag, nicht in die dauerhaften Regeln.
- Veraltete Informationen: Eine falsche Regel ist schlimmer als keine, weil der Agent ihr vertraut.
- Kopien vorhandener Dokumentation: Verweisen Sie auf Architektur- oder API-Dokumente, statt sie zu duplizieren.
- Selbstverständlichkeiten: Allgemeine Best Practices, die jeder Agent kennt, verbrauchen nur Platz.
Schritt für Schritt zur ersten Kontextdatei
- Agent einen Entwurf erstellen lassen: Viele Werkzeuge können das Repository analysieren und eine erste Version vorschlagen. Das spart Zeit, ersetzt aber nicht die Prüfung.
- Befehle verifizieren: Führen Sie jeden genannten Build- und Testbefehl selbst aus. Falsche Befehle sind der häufigste Fehler in automatisch erzeugten Dateien.
- Architektur und Tabus ergänzen: Das Wissen, das nur im Kopf erfahrener Teammitglieder steckt, kann kein Agent erraten. Hier liegt der größte Mehrwert.
- Kürzen: Streichen Sie alles Allgemeine und Doppelte.
- Testlauf: Geben Sie dem Agent zwei, drei typische Aufgaben und prüfen Sie, ob er die Regeln einhält.
- Per Pull Request einchecken: Behandeln Sie Kontextdateien wie Code – mit Review und Versionierung.
Projektregeln dauerhaft pflegen
Kontextdateien veralten genauso wie jede Dokumentation. Bewährt haben sich drei Gewohnheiten. Erstens: Wenn ein Agent einen Fehler macht, der auf fehlendes Projektwissen zurückgeht, wird die Regel ergänzt – idealerweise im selben Pull Request wie die Korrektur. Zweitens: Architekturänderungen enthalten immer auch eine Aktualisierung der Regeln. Drittens: In regelmäßigen Abständen, etwa einmal pro Quartal, prüft jemand die Datei auf Veraltetes und Überflüssiges.
Für Teams mit mehreren Repositories lohnt sich zusätzlich eine gemeinsame Basis für übergreifende Standards wie Sicherheitsvorgaben oder Commit-Konventionen, ergänzt um projektspezifische Dateien. Wer noch einen Schritt weitergehen möchte, kombiniert Projektregeln mit Spezifikationen pro Feature, wie im Ansatz des Spec-Driven Development beschrieben. In unseren Workshops, für die wir KI-Entwickler aus der Praxis als Trainer vermitteln, erarbeiten Teams solche Regeln häufig direkt am eigenen Code.
Sie planen eine App? Kostenloses Festpreis-Angebot in 2 Minuten anfordernFazit
Gute Projektregeln sind kurz, konkret, begründet und aktuell. Sie enthalten verifizierte Befehle, Architekturprinzipien, Konventionen und klare Grenzen – aber keine Secrets und keine Allgemeinplätze. Wer die Datei wie Code behandelt und jeden wiederkehrenden Agent-Fehler in eine Regel übersetzt, verbessert die Ergebnisse seiner Coding-Agents nachhaltig.
Häufige Fragen
Wie lang sollte eine Kontextdatei für Coding-Agents sein?
So kurz wie möglich, so lang wie nötig. Eine kompakte Hauptdatei mit den wichtigsten Befehlen, Prinzipien und Tabus wirkt meist besser als ein umfangreiches Dokument, in dem einzelne Regeln untergehen.
Funktioniert eine AGENTS.md mit allen Werkzeugen?
Viele Werkzeuge unterstützen diese Konvention, aber nicht alle und nicht immer auf dieselbe Weise. Prüfen Sie die Dokumentation Ihres Werkzeugs und verweisen Sie bei Bedarf aus der werkzeugspezifischen Datei auf eine gemeinsame Quelle.
Wer sollte die Projektregeln pflegen?
Das ganze Team, mit einer klar benannten verantwortlichen Person. Änderungen laufen wie Code über Pull Requests mit Review.
Dürfen interne Informationen in Kontextdateien stehen?
Architektur- und Prozesswissen ja, Zugangsdaten und vertrauliche Geschäftsdaten nein. Die Dateien werden vom Agent an das genutzte Modell übertragen und sollten entsprechend behandelt werden.