Anweisungsdateien für KI-gestützte Programmieragenten müssen fortlaufend überprüft werden, statt grenzenlos zu wachsen. Jedes Mal, wenn das Modell einen Fehler macht, wird eine neue Regel ergänzt; jedes Mal, wenn sich ein Tool ändert, kommt eine neue Umgehungslösung hinzu, während frühere Modellrichtlinien nach dem Erscheinen neuerer Modelle bestehen bleiben. Das Ergebnis kann eine Datei sein, die einen Einrichtungsleitfaden für Entwickler, einen Styleguide, ein Fehlerbehebungsprotokoll und eine Sammlung veralteter Prompting-Techniken miteinander verbindet.
Dem Artikel zufolge kann diese Ansammlung den Programmieragenten weniger effektiv machen. Moderne Modelle können Repositorys zunehmend selbstständig untersuchen, gängige Frameworks erkennen, vorhandenen Mustern folgen und mit gewöhnlichen Fehlern umgehen. Sie kennen jedoch weder die teaminternen Entscheidungen und verborgenen Einschränkungen noch die darin angesammelten betrieblichen Erfahrungen. Das Ziel besteht daher nicht darin, die Anweisungsdatei so kurz wie möglich zu machen, sondern die kleinste Menge an Informationen mit hoher Aussagekraft beizubehalten, die das Ergebnis tatsächlich verändert.
Kontext als begrenzte Ressource behandeln
Die Anweisungsdatei wird bei jeder zutreffenden Anfrage zum für das Modell verfügbaren Kontext hinzugefügt. Ihre Zeilen konkurrieren mit der Aufgabe des Entwicklers, dem relevanten Code, den Toolausgaben, dem Gesprächsverlauf und anderen Anweisungen um die Aufmerksamkeit des Modells. Eine größere Kontextfenstergröße bedeutet nicht, dass jedes zusätzliche Token kostenlos ist.
Die praktische Frage lautet nicht: Was kann man dem Modell über das Repository mitteilen? Sondern: Was muss das Modell wissen und kann es nicht zuverlässig entdecken, ableiten oder abrufen? Der Artikel empfiehlt, sich auf spezifische, einflussreiche und schwer ableitbare Informationen zu konzentrieren.
Was sollte in der Datei bleiben?
Zu den wertvollsten Informationen gehören nicht offensichtliche Fakten über das System, etwa Zuständigkeitsgrenzen zwischen Repository-Komponenten, die Tatsache, dass ein altes Verzeichnis noch in der Produktion verwendet wird, oder dass bestimmte Dateien generiert werden und nicht manuell geändert werden dürfen. Es ist hilfreich zu erläutern, dass eine bestimmte Schnittstelle den öffentlichen HTTP-Vertrag besitzt oder dass Fachregeln zu einer bestimmten Schicht gehören, statt das Modell diese Grenzen aus Verzeichnisnamen ableiten zu lassen.
Außerdem sollte der kürzeste zuverlässige Weg zum Bauen und Validieren dokumentiert werden, wobei nur getestete Befehle aufgenommen werden sollten. Als Beispiele nennt der Artikel, vor dem ersten Build dotnet restore App.slnx auszuführen und anschließend dotnet build App.slnx --no-restore zu verwenden, bei Änderungen an APIs bestimmte Tests auszuführen oder nach Änderungen an Verträgen ein Tool zur Validierung generierter Dateien einzusetzen. Besondere Anforderungen sollten erläutert werden, etwa dass Integrationstests Docker benötigen und nicht parallel ausgeführt werden dürfen, denn ein falscher Befehl, der selbstbewusst wiederholt wird, ist schlimmer als das Fehlen eines Befehls.
Ebenfalls sinnvoll ist die Dokumentation lokaler Entscheidungen, die der Code nicht dauerhaft eindeutig bestimmen kann: das verwendete Test-Framework, die Präferenz für Minimal APIs gegenüber Controllern, das Muster Result<T> zur Behandlung erwartbarer Fachfehler oder die Verwendung von TimeProvider anstelle eines direkten Aufrufs der Systemuhr. Dies sind keine allgemeinen Programmierregeln, sondern Entscheidungen, die für die Codebasis spezifisch sind, und daher in eine Anweisungsdatei gehören.
Strenge Einschränkungen sollten hingegen Wörtern wie „immer“, „nie“ und „muss“ vorbehalten bleiben, wenn es sich tatsächlich um absolute Regeln handelt, etwa die Wahrung des öffentlichen JSON-Vertrags, das Verbot von Kundendaten in Protokollen, die Abwärtskompatibilität von Datenbankmigrationen oder das Verbot, Produktionsumgebungsdateien ohne eine ausdrückliche Bereitstellungsaufgabe zu ändern. Außerdem kann auf Quellen der Wahrheit verwiesen werden, statt deren Inhalte zu kopieren, etwa auf Dateien mit Richtlinien für das Schnittstellendesign, Dateien zur Festlegung der Laufzeitversionen, Bereitstellungsdokumentation und Architekturentscheidungen.
Was kann gelöscht oder verschoben werden?
Der Artikel empfiehlt, allgemeine Ratschläge wie das Schreiben von sauberem Code, das Befolgen bewährter Praktiken, die Verwendung aussagekräftiger Namen und den angemessenen Umgang mit Fehlern zu entfernen. Solche Aussagen entscheiden keine konkrete praktische Frage. Nützlicher ist eine spezifische lokale Regel, etwa Validierungsfehler mit der Antwort 400, nicht vorhandene Ressourcen mit der Antwort 404 und Nebenläufigkeitskonflikte mit der Antwort 409 unter Verwendung der vorhandenen ProblemDetails-Hilfsmittel zu verknüpfen.
Dateien benötigen in der Regel kein vollständiges Verzeichnisinventar, da das Modell die Repository-Struktur schnell lesen kann. Ebenso müssen Formatierungsregeln, die von Tools erzwungen werden, nicht wiederholt werden; es genügt, den passenden Validierungsbefehl zu nennen, etwa dotnet format --verify-no-changes. Das vollständige Kopieren von README-Dateien, Architekturleitfäden und Beitragsrichtlinien sollte vermieden werden, damit der Wartungsaufwand nicht steigt und keine Widersprüche zwischen den Dokumenten entstehen.
Der Artikel warnt außerdem vor alten „Prompt-Mythen“, etwa das Modell aufzufordern, tief durchzuatmen, sich wie ein leitender Ingenieur zu verhalten oder vor jeder Änderung jede Datei zu lesen. Diese Aussagen vermitteln kein Wissen über das Projekt und können zu unnötiger Untersuchung führen. Besser ist es, das gewünschte Ergebnis, die Einschränkungen und die erforderliche Validierung zu beschreiben: die kleinste Änderung vorzunehmen, die die Grundursache behebt, das öffentliche Verhalten zu bewahren und die gezielten Tests auszuführen.
Vorübergehende Lösungen sollten nach der Behebung des Problems, das sie erforderlich gemacht hat, entfernt werden. Andernfalls wird der Agent weiterhin einen Pfad meiden, der nicht mehr fehlerhaft ist. Anweisungen sollten außerdem für eine Modellklasse und nicht für eine bestimmte Version formuliert werden; Anweisungen, die sich in modellabhängige Pfade verzweigen, werden instabil, wenn sich Modelle und ihr Verhalten ändern.
Geltungsbereich der Anweisungen auswählen und sie überprüfen
Nicht jede Richtlinie eignet sich für die allgemeine Repository-Datei. GitHub Copilot unterstützt allgemeine Anweisungen in .github/copilot-instructions.md, pfadspezifische Dateien unter .github/instructions/ sowie Agentenanweisungen wie AGENTS.md. Wenn beide vorhanden sind, wird die allgemeine Anweisungsdatei gemeinsam mit der passenden pfadspezifischen Datei verwendet.
Die Systemstruktur, gemeinsame Befehle und allgemeinen Einschränkungen sollten im allgemeinen Geltungsbereich platziert werden. Regeln für Frameworks, Testmuster und generierte Dateien, die nur einen bestimmten Teil betreffen, sollten in eine pfadspezifische Datei verschoben werden. Detaillierte Erläuterungen, die Geschichte von Entscheidungen und seltene Abläufe sollten besser in verknüpften Dokumenten verbleiben. So beansprucht eine Regel für React-Komponententests nicht die Aufmerksamkeit des Modells während einer Aufgabe zur Datenbankmigration.
Der Artikel schlägt vor, jede Richtlinie anhand von vier Ergebnissen zu überprüfen: beibehalten, wenn sie korrekt, einflussreich und schwer abzuleiten ist; löschen, wenn das Modell sie kennt, ein Tool sie erzwingt oder sie unklar beziehungsweise veraltet geworden ist; verschieben, wenn sie nützlich ist, aber zu einem anderen Pfad oder Dokument gehört; und überprüfen, wenn sie sich auf einen Befehl, eine vorübergehende Lösung oder eine möglicherweise geänderte Version bezieht.
Zu den Zeitpunkten für eine Überprüfung gehören die Einführung eines leistungsfähigeren Modells, eine Änderung des Build-Systems, eine Umstrukturierung des Repositorys sowie die Beobachtung, dass Agenten Anweisungen ignorieren oder falsch anwenden. Anschließend wird die kleinere Datei anhand einer konkreten Aufgabe getestet, tatsächliche Fehlerfälle werden erfasst, die geringste Anzahl an Anweisungen zur Vermeidung ihrer Wiederholung wird ergänzt und die Datei wird mit einer weiteren Aufgabe erneut getestet.
Teil der Projektwartung
Der Artikel empfiehlt, Änderungen an Anweisungsdateien in den üblichen Pull Requests zu überprüfen, die Reviewer zu fragen, ob eine Regel wiederverwendbar ist oder nur eine einzelne Aufgabe behandelt, und einen Verantwortlichen für Betriebsbefehle und Umgebungsanforderungen zu benennen. Vorübergehende Lösungen sollten in demselben Pull Request entfernt werden, der die Ursache des Problems behebt. Außerdem sollten die Befehle nach Aktualisierungen von SDK-Paketen, Frameworks, Testtools oder des Buildpfads erneut überprüft werden.
Die Qualität einer Datei sollte nicht anhand ihrer Zeilenzahl gemessen werden. Eine 30 Zeilen lange Datei, die falsche Befehle enthält, kann schlechter sein als eine 100 Zeilen lange Datei, die die Grenzen eines Multi-Projekt-Repositorys und Informationen beschreibt, die das Modell nicht ableiten kann. Das bessere Kriterium ist, dass die Datei es einem fähigen Modell ermöglicht, schnell mit der Arbeit zu beginnen, indem sie ihm das zur Verfügung stellt, was nur das Team weiß: worum es sich bei dem System handelt, welche Grenzen wichtig sind, welche lokalen Entscheidungen getroffen wurden, wie der Build und die Überprüfung durchgeführt werden, was nicht beschädigt werden darf und wo die tiefergehenden Details zu finden sind.