app-entwickeln-lassen.de LogoApp entwickeln lassen

Agentic Coding

Projektregeln und Kontextdateien für Coding-Agents richtig schreiben

Redaktion app-entwickeln-lassen.de 6 Min. Lesezeit
Inhalt
  1. Was Kontextdateien für Coding-Agents sind
  2. Die wichtigsten Inhalte guter Projektregeln
  3. So schreiben Sie Regeln, die Agents wirklich befolgen
  4. Was nicht in Kontextdateien gehört
  5. Schritt für Schritt zur ersten Kontextdatei
  6. Projektregeln dauerhaft pflegen
  7. Fazit
  8. Häufige Fragen

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

AbschnittInhaltBeispiel
ProjektüberblickZweck, Zielgruppe, zentrale Module in zwei bis fünf Sätzen„Buchungs-App für Physiotherapiepraxen, Backend in Kotlin, App in Flutter“
BefehleBuild, Tests, Linter, lokaler Start – exakt und kopierbarnpm run test -- --watch=false
ArchitekturSchichten, Verzeichnisstruktur, wo neuer Code hingehört„Geschäftslogik nur in /domain, nie in UI-Komponenten“
KonventionenNamensregeln, Fehlerbehandlung, Logging, Teststil„Fehler als Result-Typ zurückgeben, keine Exceptions im Domain-Layer“
AbhängigkeitenBevorzugte Bibliotheken, verbotene Pakete„HTTP nur über den vorhandenen ApiClient“
Grenzen und TabusWas der Agent nicht ändern oder ausführen darf„Keine Änderungen an Migrationsdateien, die bereits deployed sind“
Definition of DoneWas 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

  1. 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.
  2. Befehle verifizieren: Führen Sie jeden genannten Build- und Testbefehl selbst aus. Falsche Befehle sind der häufigste Fehler in automatisch erzeugten Dateien.
  3. Architektur und Tabus ergänzen: Das Wissen, das nur im Kopf erfahrener Teammitglieder steckt, kann kein Agent erraten. Hier liegt der größte Mehrwert.
  4. Kürzen: Streichen Sie alles Allgemeine und Doppelte.
  5. Testlauf: Geben Sie dem Agent zwei, drei typische Aufgaben und prüfen Sie, ob er die Regeln einhält.
  6. 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 anfordern

Fazit

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.

Dieser Artikel wurde von der Redaktion von app-entwickeln-lassen.de erstellt – dem App- und KI-Entwicklungsangebot der jocapps GmbH aus Freiburg, seit 2014 in der App-Entwicklung aktiv. Die Inhalte dienen der allgemeinen Information und ersetzen keine individuelle (Rechts-)Beratung.

Das könnte Sie auch interessieren

Agentic CodingAgentic Coding im Terminal vs. in der IDE: Was passt zu Ihrem Team?

Agentic Coding im Terminal oder in der IDE? Stärken, Grenzen und Einsatzszenarien beider Ansätze im Vergleich – mit Entscheidungshilfe für Ihr Entwicklerteam.

6 Min. Lesezeit
Agentic CodingAgentic Coding für Mobile Apps: iOS- und Android-Entwicklung mit Agents

Agentic Coding für Mobile Apps: Wo Coding-Agents bei iOS- und Android-Projekten helfen, wo ihre Grenzen liegen und wie Sie den Workflow sauber aufsetzen.

6 Min. Lesezeit
Agentic CodingHäufige Fehler beim Agentic Coding und wie Sie sie vermeiden

Agentic Coding Fehler erkennen und vermeiden: Die zehn typischen Stolpersteine bei Coding-Agents – mit konkreten Gegenmaßnahmen für Teams und Tech-Leads.

7 Min. Lesezeit
Agentic CodingAgentic Coding und Code-Ownership: Wer verantwortet den Code?

Agentic Coding und Code-Ownership: Wer agentengenerierten Code verantwortet, wie Sie Zuständigkeiten regeln und Wissen im Team halten – praxisnah erklärt.

5 Min. Lesezeit
Agentic CodingDie Rolle des Entwicklers im Agentic-Coding-Zeitalter

Die Rolle des Entwicklers im Agentic-Coding-Zeitalter: Welche Aufgaben bleiben, welche Kompetenzen wichtiger werden und wie sich Teams und Karrieren verändern.

5 Min. Lesezeit
Agentic CodingWie Agentic Coding die Time-to-Market von Apps verkürzt

Agentic Coding und Time-to-Market: In welchen Projektphasen Coding-Agents Apps schneller marktreif machen, wo Grenzen liegen – und wie Sie realistisch planen.

5 Min. Lesezeit