Curated Shared Instructions for Software Teams Adopt

coding-agentsdeveloper-aiagentsshared-instructionsinstruction-followingagent-governancequality-gatesdeveloper-experienceservice-templates

Überblick

Kuratierte, geteilte Instruktionen machen aus Ad-hoc-Prompts gepflegte Team-Assets für AI-unterstützte Delivery. Teams kodieren Architekturkonventionen, Coding-Standards, Testerwartungen, Security-Grenzen und Workflow-Normen in Dateien wie AGENTS.md, CLAUDE.md, .cursorrules und pfadgebundenen *.instructions.md-Sammlungen, damit Coding-Agenten die tatsächlichen Praktiken des Teams übernehmen und nicht die privaten Prompt-Gewohnheiten einzelner Entwickler (Thoughtworks Radar, awesome-copilot instructions). Thoughtworks beschreibt es inzwischen als aufkommendes Anti-Pattern, sich darauf zu verlassen, dass einzelne Entwickler Prompts von Grund auf schreiben, und hebt hervor, Instruktionsdateien im Baseline-Repository zu verankern, das zum Scaffolding neuer Services verwendet wird, sodass das Template zum Verteilungsmechanismus für AI-Guidance wird (Thoughtworks Radar).

Was sich seit dem letzten Release geändert hat, ist die Verschiebung des Schwerpunkts von Dokumentation zu Prozessdisziplin. MiniMax' Open-Source-Benchmark für Coding-Agenten in Produktionsqualität argumentiert, dass Unzufriedenheit von Nutzern meist nicht daher kommt, dass Agenten Aufgaben nicht abschließen, sondern dass sie sie unsachgemäß abschließen: Emojis einfügen, nachdem sie angewiesen wurden, es nicht zu tun, destruktive Commands ausführen, obwohl vorher gesichert werden sollte, Namenskonventionen aus der Projektdokumentation ignorieren. Die Aufgabe wird fertiggestellt, aber der Prozess verstößt gegen die Spezifikation, und gängige Code-Agent-Evaluierungen haben hier einen blinden Fleck (MiniMax benchmark). Das rahmt geteilte Instruktionen als Betriebsregeln neu, deren Einhaltung bewertet werden sollte, nicht nur verfasst.

Die Praxis bleibt in Adopt, weil das Tooling dieses Framing jetzt unterstützt. Qodos Rules System positioniert verstreute Organisationsstandards als eine zentralisierte, sich weiterentwickelnde und erzwingbare Single Source of Truth, verdrahtet in Multi-Agent-Review, und schließt damit die Lücke zwischen dem Definieren von „gut“ und dessen Anwendung dort, wo Entwickler arbeiten (Qodo Rules System). Offene Playbook-Projekte kombinieren Regeln und Prompts mit ausführbaren Gates und Evals statt nur mit Prosa (Agents Playbook, AI Workflow Playbooks). Der Wert entsteht weiterhin aus knapper, spezifischer, überprüfter Guidance, die mit deterministischen Checks verbunden ist, nicht aus langen Prompt-Dateien.

Adoptionssignale

  • Thoughtworks listet kuratierte, geteilte Instruktionen ab April 2026 in Adopt und plädiert dafür, AI-Guidance als kollaboratives Engineering-Asset statt als persönlichen Workflow zu behandeln, und beschreibt die Entwicklung von allgemeinen Prompt-Bibliotheken zu Instruktionen, die in Service-Templates und einer lebenden Referenzanwendung verankert sind, die als Source of Truth für Standards dient (Thoughtworks Radar).
  • MiniMax hat einen Benchmark speziell für Prozesstreue in Produktionsqualität open-sourced, mit der Prämisse, dass nur Agenten, die Prozessspezifikationen befolgen können, zuverlässig in reale Software-Engineering-Workflows integriert werden können (MiniMax benchmark).
  • Qodo hat in seinem 2.1-Release ein Rules System ausgeliefert, um Standards, die in Lint-Configs, internen Docs, alten Pull Requests und den Köpfen erfahrener Engineers leben, in eine zentralisierte und erzwingbare Definition davon zu verwandeln, wie „gut“ aussieht (Qodo Rules System).
  • Community-Playbook-Repositories verpacken Agent-Guidance als Regeln, Prompts, Memory, Evals und ausführbare Gates, die Qualität vor dem Merge erzwingen, ausdrücklich um zu verhindern, dass Agenten Spezifikationen überspringen, Edge Cases ignorieren, Security-Reviews umgehen und ungetesteten Code ausliefern (Agents Playbook, AI Workflow Playbooks).
  • Praxisnahe Field Manuals behandeln AGENTS.md inzwischen als Team-Infrastruktur und Governance als etwas, das über die Delivery-Schleife verteilt wird, motiviert durch Agenten, die Output produzierten, der gegen eine vom Team festgelegte Vorgabe verstieß (Ship It With AI).
  • Wiederverwendbare Instruktionssammlungen werden als Artefakte veröffentlicht und installiert statt eingefügt: GitHubs awesome-copilot verteilt team- und projektspezifische *.instructions.md-Dateien für bestimmte Technologien und Coding-Praktiken (awesome-copilot instructions).
  • OpenSSF veröffentlicht einen sicherheitsfokussierten Leitfaden zum Schreiben von AI-Code-Assistant-Instruktionen für Claude-Markdown, Copilot-Instruktionsdateien, Cline, Cursor-Regeln und Kiro-Steering, mit der Begründung, dass Assistenten explizite Guidance benötigen, um sicheren und robusten Code zu produzieren (OpenSSF guide, OpenSSF announcement).
  • Breiter angelegte Engineering-Trend-Kommentare konvergieren auf dasselbe Designprinzip: Build-Systeme und Dokumentation, die für Menschen und Maschinen vorhersehbar, berechtigungsbewusst und beobachtbar sind, und Golden Paths statt Golden Rules bieten (2026 Tech Trends).

Risiken

  • Instruktionen sind keine Durchsetzung. Agenten schließen Aufgaben ab, während sie gegen festgelegte Prozessvorgaben verstoßen, einschließlich expliziter Verbote und Anforderungen im Stil von „vor der Änderung sichern“, sodass hinter Regeln Linter, Tests, Scanner und Merge-Gates stehen müssen (MiniMax benchmark, Agents Playbook).
  • Unmessene Compliance ist unverwaltete Compliance. Gängige Coding-Agent-Evaluierungen haben sich auf die Aufgabenerfüllung konzentriert und das Befolgen von Instruktionen weitgehend ungetestet gelassen; Teams, die die Einhaltung nie evaluieren, bemerken Regressionen nach einem Modell- oder Client-Upgrade nicht (MiniMax benchmark).
  • Kopierte Markdown-Dateien veralten. Prompt- und Instruktionsdateien, die als temporäre Dokumentation beginnen, versinken in Repos, verlieren die Versionsverfolgung und veralten, wodurch Agenten fälschlich von Commands und Konventionen ausgehen, die nicht mehr gelten (Aviator).
  • Verstreute Standards bleiben ein Risiko. Wenn Regeln gleichzeitig in Lint-Configs, internen Docs, alten Pull Requests und den Köpfen erfahrener Engineers leben, verbreiten sich Inkonsistenz und Tech-Debt mit Generierungsgeschwindigkeit; eine Regelebene hilft nur, wenn sie tatsächlich die Single Source of Truth ist (Qodo Rules System).
  • Instruktionsdateien sind Angriffsfläche. Offengelegte Forschung fand über 30 Schwachstellen in zehn großen KI-integrierten Entwicklungsumgebungen, wobei alle zehn anfällig für Prompt Injection waren, die zu Codeausführung oder Datenexfiltration führte, mit beobachtetem Missbrauch in einem öffentlichen Skills-Marketplace (CSA research note).
  • Guidance behebt nicht die Qualität generierten Codes. Assistenten reproduzieren unsichere Muster aus Trainingsdaten und können keinen qualitativ hochwertigen Quellcode garantieren, mit großer Varianz je nach Sprache und Aufgabe, sodass Security-Instruktionen Review und AppSec-Tooling ergänzen, nicht ersetzen (Kusari, BSI).

Vorteile & Nachteile

Vorteile

  • Eine gepflegte Instruktionsebene richtet mehrere Entwickler und mehrere Agenten auf dieselben Build-, Test-, Review- und Security-Praktiken aus, statt jeden Beitragenden Prompts von Grund auf neu erfinden zu lassen.
  • Die Verteilung von Instruktionsdateien über Service-Templates und Referenzanwendungen bedeutet, dass jedes neue Repository aktuelle Architektur- und Coding-Standards standardmäßig übernimmt, statt einen manuellen Rollout pro Team zu erfordern.
  • Da das Befolgen von Instruktionen inzwischen durch Benchmarks und Regelsysteme messbar und erzwingbar ist, können Teams Prozess-Compliance als testbare Eigenschaft der Agent-Ausgabe behandeln statt als Sache der Hoffnung.

Nachteile

  • Instruktionen sind Leitplanken, keine Kontrollen: Agenten verstoßen nachweislich gegen explizite Prozessvorgaben wie „vor der Änderung sichern“ oder dokumentierte Namenskonventionen, sodass deterministische Gates weiterhin zwingend bleiben.
  • Eingecheckte Markdown-Dateien veralten schnell, verlieren die Versionsdisziplin und lenken Agenten unbemerkt auf Commands, APIs und Grenzen, die es nicht mehr gibt.
  • Instruktions- und Regeldateien sind Teil der Angriffsfläche von KI-Coding, und Prompt Injection durch von Agenten lesbaren Content hat in weit verbreiteten KI-integrierten IDEs zu Codeausführung und Datenexfiltration geführt.

Empfehlung

Übernehmen Sie kuratierte, geteilte Instruktionen für jedes Repository, an dem mehrere Entwickler oder Agenten Code beitragen, und schreiben Sie sie als Betriebsregeln statt als Prosa. Beginnen Sie mit einer knappen Datei auf Repository-Ebene, die exakte Build- und Test-Commands, Projektstruktur, Code-Style, Git-Workflow und Grenzen abdeckt, und verwenden Sie dann pfadgebundene Instruktionsdateien für Framework-spezifische Details (awesome-copilot instructions). Verteilen Sie die Baseline über Service-Templates und, wo Sie eine pflegen können, eine lebende Referenzanwendung, damit neue Repositories aktuelle Standards standardmäßig übernehmen statt die Datei von gestern zu kopieren (Thoughtworks Radar).

Investieren Sie in diesem Quartal in die Durchsetzungs- und Evaluierungshälfte. Jede wichtige Regel sollte sich in einen Command, Linter, Test, Scanner oder Merge-Gate auflösen, nach dem Playbook-Muster, Regeln mit ausführbaren Gates und Evals zu kombinieren (Agents Playbook, AI Workflow Playbooks). Fügen Sie eine kleine Regressionssuite für das Befolgen von Instruktionen im Geiste von MiniMax' Benchmark hinzu: eine Handvoll Aufgaben mit expliziten Prozessvorgaben, geprüft nach Modell-, Client- oder Regeländerungen, damit Sie erfahren, wann die Einhaltung nachlässt, statt es erst im Review zu entdecken (MiniMax benchmark). Wo bereits ein Vendor-Rule-System im Review-Pfad steht, zentralisieren Sie die kanonische Definition dort und generieren Repository-Dateien daraus, statt zwei Wahrheiten zu pflegen (Qodo Rules System).

Pflegen Sie Instruktionen wie Code und behandeln Sie sie als sensibel. Checken Sie sie in git ein, weisen Sie Owner zu, reviewen Sie Änderungen, löschen Sie veraltete Guidance, und aktualisieren Sie die Datei, wenn Agenten einen Fehler wiederholen. Nutzen Sie die OpenSSF-Guidance, um sicherheitsrelevante Instruktionen zu formen, aber behalten Sie Secret Scanning, Least-Privilege-Zugriff für Agenten und Service-Accounts, Sandboxing, Audit-Logging automatisierter Aktionen und Branch Protection als die eigentlichen Controls (OpenSSF guide, 2026 Tech Trends, CSA research note).

Quellen

Überblick

Kuratierte geteilte Anweisungen machen aus Ad-hoc-Prompts gepflegte Team-Assets für AI-gestützte Delivery. Teams nutzen Dateien wie AGENTS.md, .github/copilot-instructions.md, .cursor/rules/ und *.instructions.md, um Architekturkonventionen, Coding-Standards, Test-Erwartungen, Sicherheitsgrenzen und Workflow-Normen für Coding-Agenten zu kodieren.

AGENTS.md ist als README-ähnliche Datei für Agenten positioniert: ein vorhersehbarer Ort für Build-Schritte, Tests, Konventionen, Security und Kontext, der für ein menschenorientiertes README zu detailliert oder agent-spezifisch sein kann (AGENTS.md). GitHub Copilot und VS Code unterstützen repository-weite, pfadspezifische und agent-orientierte Instruction-Dateien, inklusive AGENTS.md für Multi-Agent-Workspaces (VS Code custom instructions, GitHub Copilot custom instructions).

Bewertung als Adopt, weil mehrere Menschen und Agenten an denselben Repositories arbeiten. Eine gepflegte Instruction-Schicht ist eine der günstigsten Wege, Coding-Agenten an echte Build-, Test-, Review- und Safety-Praxis des Teams zu binden. Der Wert kommt aus prägnanter, spezifischer, geprüfter Guidance plus deterministischen Checks, nicht aus langen Prompt-Dateien.

Adoptionssignale

  • AGENTS.md wird als einfaches, offenes Format für Coding-Agenten beschrieben, mit vorgeschlagenen Abschnitten wie Projektüberblick, Build- und Test-Befehle, Code-Style, Test-Anweisungen, Security, Commit-Messages, PR-Guidelines und Deployment (AGENTS.md).
  • Die AGENTS.md-Website erlaubt verschachtelte AGENTS.md in Monorepos; die nächste AGENTS.md zur bearbeiteten Datei gewinnt, explizite User-Chat-Prompts überschreiben alles (AGENTS.md).
  • AGENTS.md listet Support über ein breites Ökosystem: Codex, Jules, Factory, Aider, Goose, OpenCode, Zed, Warp, VS Code, Devin, Cursor, RooCode, Gemini CLI, GitHub Copilot, Ona, Windsurf und weitere (AGENTS.md).
  • Codex liest AGENTS.md vor der Arbeit, unterstützt globale, Repository- und verschachtelte Instruction-Dateien und konkateniert von Root abwärts, sodass nähere Dateien breitere Guidance überschreiben (Codex AGENTS.md).
  • Codex unterstützt Fallback-Instruction-Dateinamen, ein project_doc_max_bytes-Limit und Verifikationsbefehle, die aktive Instruction-Quellen zusammenfassen (Codex AGENTS.md).
  • VS Code unterstützt .github/copilot-instructions.md, AGENTS.md, CLAUDE.md und *.instructions.md, inklusive pfadbasiertem Einsatz via Glob und verschachtelter AGENTS.md-Discovery hinter Settings (VS Code custom instructions).
  • GitHub Copilot unterstützt repository-weite Custom Instructions, pfadspezifische NAME.instructions.md mit applyTo-Frontmatter und Agent Instructions via AGENTS.md, wobei die nächste Datei im Verzeichnisbaum gewinnt (GitHub Copilot custom instructions).
  • GitHubs Analyse von über 2.500 Repositories zeigt: effektive agents.md-Dateien enthalten exakte Befehle, klare Grenzen, Stack-Details, Code-Beispiele und klar definierte Abschnitte; vage Dateien scheitern (GitHub Blog).
  • Cursor empfiehlt, Rules in Git zu committen, Rules auf essenzielle Befehle und Muster zu fokussieren, kanonische Beispiele zu referenzieren statt lange Guides zu kopieren, und Rules zu aktualisieren, wenn der Agent wiederholt dieselben Fehler macht (Cursor agent best practices).

Risiken

  • Instruction-Bloat reduziert Signal. Cursor warnt ausdrücklich davor, ganze Style Guides zu kopieren, jeden möglichen Befehl zu dokumentieren oder seltene Edge Cases in Always-on-Rules zu packen; Linter und Tests sollten deterministisches Enforcement tragen (Cursor agent best practices).
  • Vage Instruktionen scheitern. GitHubs Repository-Analyse sagt, generische Formulierungen wie „You are a helpful coding assistant“ sind schwächer als spezifische Personas, exakte Befehle, Grenzen und Beispiele (GitHub Blog).
  • Widersprüchliche Instruktionen verschlechtern Output. GitHub rät, widersprüchliche Instruction-Sets zu vermeiden; AGENTS.md und Codex definieren Precedence für verschachtelte Dateien und Overrides, die Teams verstehen müssen (GitHub Copilot custom instructions, Codex AGENTS.md).
  • Instruktionen driften von der Realität. Build-Befehle, Test-Targets, API-Namen, Architekturentscheidungen und Security-Regeln ändern sich; veraltete Instruktionen lassen Agenten Zeit verschwenden oder falsche Änderungen mit Überzeugung machen.
  • Client-Verhalten unterscheidet sich. Codex hat Byte-Limits und Fallback-Dateinamen, VS Code wendet pfadspezifische Dateien via Glob oder semantischem Matching an, GitHub Copilot nutzt Base-Branch-Instructions für PR-Review: Teams sollten testen, wie jeder Agent Instruktionen lädt (Codex AGENTS.md, VS Code custom instructions, GitHub Copilot custom instructions).
  • Instruktionen sind keine Controls. „Never commit secrets“ ist hilfreiche Guidance, ersetzt aber kein Secret Scanning, Permission Boundaries, Sandboxing, Code Review oder Branch Protection.

Vorteile & Nachteile

Vorteile

  • Macht wiederholtes Prompting zu geprüften, versionierten Team-Assets mit Build-Befehlen, Test-Erwartungen, Architekturregeln, Coding-Style, Git-Workflow und Sicherheitsgrenzen.
  • Verbessert Konsistenz über Coding-Agenten hinweg, weil sie einen vorhersehbaren Ort für repository-spezifische Guidance vor Edit, Test, Review oder PR finden.
  • Skaliert über Monorepos und gemischte Agent-Teams via AGENTS.md, Copilot Instructions, Cursor Rules, pfadspezifische Instruction-Dateien und verschachtelte Overrides.

Nachteile

  • Geteilte Anweisungen werden veraltet, widersprüchlich oder aufgebläht, wenn sie nicht wie andere Repository-Assets owned, geprüft, getestet und validiert werden.
  • Instruktionen sind Guidance, kein Enforcement; Linter, Tests, Type Checks, Security Scans, Branch Protection und menschliches Review bleiben nötig.
  • Verschiedene Agent-Clients wenden Precedence, File Discovery, Byte-Limits und pfadspezifische Regeln unterschiedlich an; Portabilität muss verifiziert werden.

Empfehlung

Kuratierte geteilte Instruktionen adoptieren für Repositories, in denen mehrere Entwickler oder Agenten Code beitragen. Mit einer prägnanten Repository-Level-Datei starten: Befehle, Testing, Projektstruktur, Code-Style, Git-Workflow und Grenzen. Die meistgenutzten ausführbaren Befehle nach vorne, exakte Flags, Beispiele korrekten Codes oder PR-Outputs statt langer Prosa.

Instruktionen wie Code pflegen. In Git committen, Owner zuweisen, Änderungen prüfen, veraltete Guidance entfernen, Datei aktualisieren, wenn Agenten denselben Fehler wiederholen. Verschachtelte AGENTS.md oder pfadspezifische Instruktionen für Monorepos und Framework-Regeln nutzen, aber das Nearest-File-Precedence-Modell verständlich halten.

Mit deterministischen Checks verbinden. Jede wichtige Regel sollte auf einen Befehl, Linter, Test, Security Scanner, Beispieldatei oder Review-Checklist zeigen. Vom „Agent-Prompt“-Denken zum „Team-Betriebshandbuch“ wechseln: die Datei hilft Agenten, die richtigen Checks zu finden, nicht sie allein durch Prompt zu erzwingen.

Quellen