Agentenanweisungen

Coding-Agenten benötigen mehr als eine Funktionsspezifikation. Sie müssen wissen, welche Arbeitsweise das Projekt erwartet und welche freigegebenen Entscheidungen einzuhalten sind. Diese Erwartungen können Engineering-Praktiken, freigegebene Technologie, Architektur, Komponentenwiederverwendung, Produktziele, Dokumentation, Barrierefreiheit oder andere anwendungsspezifische Beschränkungen betreffen.

Das SHAPE Framework empfiehlt, dauerhafte Markdown-Anweisungs- und Kontextdokumente gemeinsam in agent_instructions/ zu halten. Dieses Verzeichnis ist erweiterbar. Projekte können beliebig viele angemessen abgegrenzte Markdown-Dateien mit aussagekräftigen Dateinamen anlegen; das Framework schreibt keine feste Liste von Dateinamen vor.

Eine AGENTS.md im Stammverzeichnis bietet Coding-Agenten einen auffindbaren Einstieg. Die wesentliche Anweisung lautet:

Lies und beachte alle Markdown-Dateien (.md) in agent_instructions/ vor Arbeitsbeginn und während der gesamten Implementierung.

Diese zentrale Datei muss nicht jede Datei aufzählen. Beim Hinzufügen eines Anweisungsdokuments sollte keine zweite Liste im Einstiegspunkt gepflegt werden müssen.

Jede Markdown-Datei in agent_instructions/ sollte mit einer Zeile oder Überschrift beginnen, die ihren Zweck nennt. Eine Organisation könnte beispielsweise eine Datei zu freigegebenen Technologien, ein Architekturdokument, einen Designsystem-Leitfaden oder eine Beschreibung der Geschäftsziele bereitstellen. Dies sind Beispiele, keine verpflichtenden Dateinamen oder vorgeschriebene Hierarchie.

Eine selbsterklärende Datei erleichtert Menschen und Agenten das Erkennen ihrer Regeln und senkt die Wahrscheinlichkeit, dass ein neues Dokument allein deshalb ignoriert wird, weil sein Dateiname nicht in einen zentralen Index aufgenommen wurde.

Dauerhafte Anweisungen beschreiben die Arbeitsweise des Agenten und beständige Beschränkungen. Funktionsspezifikationen beschreiben das Verhalten, das die Anwendung liefern soll. Daher gehören Funktionsspezifikationen in den gesonderten Bereich specs/ und nicht vermischt in agent_instructions/, nur weil beide Markdown verwenden.

Organisationen sollten festlegen, wer Änderungen an kontrollierten Anweisungen und gemeinsamen Standards freigeben darf. Ein Agent darf die Regeln seiner Arbeit nicht stillschweigend umschreiben oder sich Befugnisse zu ihrer Übersteuerung zuschreiben. Bei folgenreichen Widersprüchen zwischen Dokumenten müssen Product Engineer und zuständiger Verantwortlicher den Konflikt klären, statt dem Agenten die bequemste Anweisung zur Auswahl zu überlassen.

Anweisungsdateien sollten für die praktische Nutzung hinreichend knapp, untereinander konsistent und mit freigegebenen Entscheidungen synchron bleiben. Projekte können domänenspezifische Beschränkungen ergänzen, ohne die Auffindbarkeitskonvention zu ändern.

Anweisungen können einem Agenten untersagen, Geheimnisse abzurufen oder nicht autorisierte Dienste zu verwenden. Sie verhindern solche Handlungen jedoch nicht, wenn die Ausführungsumgebung die entsprechenden Fähigkeiten gewährt. Berechtigungen und Zugriffsbeschränkungen gehören in technisch durchgesetzte Kontrollen.