AGENTS.md Best Practices: So geben Sie KI-Coding-Agenten einen besseren Kontext

Was ist AGENTS.md?

AGENTS.md ist eine Markdown-Datei, die KI-Codierungsagenten projektspezifische Anweisungen gibt. Die offizielle Website AGENTS.md beschreibt es als einen README-ähnlichen Ort für Agenten: eine vorhersehbare Datei, in der sie Setup-Befehle, Testbefehle, Codestil, Projektstruktur und Grenzen finden können.

Es ist kein Ersatz für README.md, Tests, Codeüberprüfung oder menschliches Urteilsvermögen. Es sollte keine vollständige Projektenzyklopädie oder ein langer Architekturaufsatz werden. Seine Aufgabe ist enger gefasst: Coding-Agenten den Repository-Kontext zu geben, den sie benötigen, um sicher zu agieren.

Der GitHub Copilot-Coding-Agent unterstützt benutzerdefinierte AGENTS.md-Anweisungen, einschließlich Dateien auf Stammebene und verschachtelter Dateien für bestimmte Repository-Bereiche. Das macht das Muster für Teams nützlich, legt aber auch die Qualitätsmesslatte höher. Ein schlechtes AGENTS.md kann einen Agenten genauso leicht in die Irre führen, wie ein gutes ihn führen kann.

Warum AGENTS.md für KI-Codierungsagenten wichtig ist

KI-Coding-Agents benötigen betrieblichen Kontext: wo wichtige Dateien gespeichert sind, wie Abhängigkeiten installiert werden, wie Tests ausgeführt werden, welche Lint- oder Typprüfungen erforderlich sind, welche Framework-Versionen wichtig sind, welche Verzeichnisse tabu sind und was eine saubere PR beinhalten sollte.

Ein gutes AGENTS.md reduziert das Rätselraten. Ein fehlerhaftes AGENTS.md sorgt für neue Vermutungen.

Die Forschung ist immer noch uneinheitlich: Der Kontext kann hilfreich sein, wenn er spezifisch ist, kann aber schaden, wenn er unnötige Anforderungen hinzufügt. Die praktische Erkenntnis ist einfach: Schreiben Sie den minimalen nützlichen Kontext, den Menschen von einem Agenten erwarten würden.

AGENTS.md Best Practices: Was Sie einbeziehen sollten

1. Projektübersicht

Halten Sie den Überblick kurz: Projektzweck, Sprache, Framework, Laufzeit, Paketmanager und Schlüsselverzeichnisse.

Schlecht: „Das ist eine moderne Web-App.“

Besser: „Dies ist eine Next.js-App, die TypeScript, pnpm, Prisma und PostgreSQL verwendet. Der App-Code befindet sich in /app, die gemeinsame Benutzeroberfläche in /components und das Schema in /prisma/schema.prisma.“

2. Setup-Befehle

Agenten sollten Ihren Paketmanager oder Ihre Skripte nicht erraten. Fügen Sie Befehle hinzu, die tatsächlich funktionieren:

• Abhängigkeiten installieren: pnpm install
• Entwicklungsserver starten: pnpm dev
• Build: pnpm build
• Typprüfung ausführen: pnpm typecheck

Wenn das Setup Grenzen hat, sagen Sie es. „E2E-Tests erfordern Docker – ist besser als „Tests ausführen“.

3. Testbefehle

Testanweisungen sind einer der wertvollsten Teile einer Agents.md-Datei. Fügen Sie den vollständigen Testbefehl, einen fokussierten Testbefehl, ggf. Integrations- oder E2E-Befehle sowie bekannte Testeinschränkungen hinzu:

• Führen Sie alle Tests aus: pnpm test
• Führen Sie eine Datei aus: pnpm test path/to/file.test.ts
• Führen Sie E2E aus: pnpm test:e2e
• Lint ausführen: pnpm lint

Sagen Sie auch, was als ausreichende Validierung gilt. Dokumentenänderungen und Authentifizierungsänderungen sollten nicht die gleichen Prüfungen erfordern.

4. Projektstruktur

Listen Sie nur die Struktur auf, die Agenten benötigen: /app für Routen, /components für die Benutzeroberfläche, /lib für Dienstprogramme, /server für Backend-Logik, /tests für Vorrichtungen und /prisma für Schemata und Migrationen. Markieren Sie generierte, veraltete oder riskante Ordner deutlich.

5. Codestil und Konventionen

Beispiele schlagen vage Regeln. Anstatt „sauberen Code zu verwenden“, schreiben Sie Regeln, die sich auf das Verhalten auswirken:

• Verwenden Sie benannte Exporte für gemeinsam genutzte Dienstprogramme.
• Verwenden Sie Result<T, E> für die Fehlerbehandlung auf Serviceebene.
• Benennen Sie Tests als should_do_expected_behavior_when_condition.
• Bevorzugen Sie vorhandene Helfer in /tests/helpers, bevor Sie Vorrichtungen hinzufügen.

Das Ziel besteht darin, Konventionen zu kodieren, die der Agent nicht aus einer Datei ableiten kann.

6. Git- und PR-Workflow

Teilen Sie den Agenten mit, wie die Arbeit für die Überprüfung vorbereitet werden soll: Benennung der Zweige, Commit-Richtlinie, PR-Zusammenfassungsformat, erforderliche Prüfungen und ob Agenten Commits durchführen dürfen. Eine nützliche Regel lautet: „Machen Sie keinen Commit, es sei denn, Sie werden ausdrücklich dazu aufgefordert. Fügen Sie eine Zusammenfassung, geänderte Dateien, Testergebnisse und Risikobereiche bei.“

7. Grenzen und Sicherheitsregeln

Grenzen sind oft nützlicher als Vorlieben.

• Bearbeiten Sie niemals .env-Dateien.
• Geben Sie niemals Geheimnisse, Token oder Anmeldeinformationen weiter.
• Ändern Sie die Produktionskonfiguration nicht ohne Genehmigung.
• Schreiben Sie Migrationen nicht ungefragt um.
• Fügen Sie keine Abhängigkeiten hinzu, ohne zu erklären, warum.
• Schwächen Sie nicht die Authentifizierungs-, Autorisierungs- oder Berechtigungsprüfungen.

8. Sicherheit und Definition of Done

Halten Sie die Sicherheitsanweisungen direkt: Überprüfen Sie Eingaben, vermeiden Sie die Protokollierung persönlicher Daten, bewahren Sie Authentifizierungsprüfungen auf, geben Sie keine API-Schlüssel preis und fragen Sie nach, bevor Sie sensiblen Code ändern.

Definieren Sie dann „erledigt“

• Testdurchführung oder Erläuterung.
• Bei Bedarf wird eine Flusen-/Typprüfung durchgeführt.
• Dokumente aktualisiert, wenn sich das Verhalten ändert.
• PR-Zusammenfassung erstellt.
• Auf Risikobereiche hingewiesen.
• Für Authentifizierung, Zahlungen, Berechtigungen, Migrationen, Infrastruktur und persönliche Daten ist eine menschliche Überprüfung erforderlich.

Was Sie nicht in AGENTS.md einfügen sollten

Mehr Kontext ist nicht immer besser. Vermeiden Sie lange Produkthistorien, veraltete Architekturaufsätze, widersprüchliche Regeln, riesige Styleguides, doppelte README-Inhalte, einmalige Aufgabennotizen, private Anmeldeinformationen und Anweisungen, die Agenten dazu ermutigen, die Überprüfung zu überspringen.

Vermeiden Sie generische Füllwörter wie „Schreiben Sie hochwertigen Code – oder „Seien Sie vorsichtig“.

Eine einfache Regel funktioniert gut: Wenn eine Anweisung nicht ändert, was der Agent tun soll, entfernen Sie sie.

AGENTS.md-Vorlage

Verwenden Sie dies als Ausgangspunkt und machen Sie es dann spezifisch für Ihr Repository.

# AGENTS.md

Projektübersicht

[Kurze Beschreibung des Projekts, des Stacks, der Laufzeit, des Paketmanagers und der Schlüsselverzeichnisse.]

Setup-Befehle

• Abhängigkeiten installieren: [command]
• Entwicklungsserver starten: [command]
• Build: [command]

Testbefehle

• Führen Sie alle Tests aus: [command]
• Fokussierten Test ausführen: [command]
• Führen Sie Lint/Typecheck aus: [command]
• Bekannte Testeinschränkungen: [Anmerkungen]

Projektstruktur

• [path]: [Zweck]
• [path]: [Zweck]

Codestil

• [spezifische Stilregel]
• [spezifisches Muster]

Git-Workflow

• Filialbenennung:
• Commit-Richtlinie:
• PR-Zusammenfassungsformat:
• Erforderliche Prüfungen:

Grenzen

• Nicht bearbeiten:
• Fragen Sie vor der Änderung:
• Begehen Sie niemals Folgendes:

Sicherheitshinweise

• Geben Sie keine Geheimnisse preis.
• Behalten Sie Authentifizierungs- und Berechtigungsprüfungen bei.
• Vermeiden Sie die Protokollierung sensibler Daten.

Definition von „Fertig“.

• Testdurchlauf:
• Lint-/Typecheck-Lauf:
• Zusammenfassung vorbereitet:
• Menschliche Überprüfung erforderlich für:

AGENTS.md Best Practices für die Wartung

AGENTS.md sollte wie Code gepflegt werden. Überprüfen Sie es, wenn sich Skripte ändern, Verzeichnisse verschoben, Testbefehle umbenannt werden, Sicherheitsregeln geändert werden oder das Team einen neuen Codierungsagenten einführt.

Lassen Sie es nicht zu einem Museum alter Entscheidungen werden. Wenn in der Datei npm test steht, das Repo aber jetzt pnpm test verwendet, verschwendet der Agent möglicherweise Zeit. Wenn Agenten angewiesen werden, ein altes Komponentenmuster zu verwenden, wird möglicherweise veralteter Code wiederbelebt.

Überprüfen Sie AGENTS.md bei größeren Umgestaltungen, vor Veröffentlichungen, nach wiederholten Agent-Ausfällen und beim Onboarding eines Repositorys in einen KI-Codierungsworkflow.

Wo EasyClaw passt: Vom statischen Kontext zum AI-Coding-Workflow

AGENTS.md gibt Codierungsagenten einen statischen Repository-Kontext. EasyClaw hilft Teams, diesen Kontext in einen ausführbaren Workflow umzuwandeln.

Diese Unterscheidung ist wichtig. Eine Agents.md-Datei kann einem Agenten mitteilen, wo sich Tests befinden, sie organisiert jedoch keine Quelldateien, sammelt keine Protokolle zu Fehlschlägen, packt keine PR-Zusammenfassungen, koordiniert keine Überprüfungsrollen und sendet keine Teamaktualisierungen.

EasyClaw ist ein Desktop-nativer KI-Agent für Mac und Windows, der Benutzern dabei hilft, unordentliche Aufgaben in ausführbare Workflows umzuwandeln. Für Entwickler kann es dabei helfen, Repositorys, Browserdokumente, Terminalausgaben, Testprotokolle, PR-Notizen, Versionshinweise und Überprüfungschecklisten zu organisieren.

EasyClaw ersetzt nicht AGENTS.md. AGENTS.md definiert Repository-Anweisungen. EasyClaw hilft bei der Ausführung des umgebenden KI-Entwickler-Workflows.

EasyClaw kann den AGENTS.md-Kontext organisieren

Bevor Sie eine Codierungsaufgabe zuweisen, kann EasyClaw dabei helfen, ein Workflow-fähiges Kontextpaket vorzubereiten:

• entsprechende AGENTS.md-Anweisungen
• Quelldateien und geänderte Dateien
• Setup- und Testbefehle
• Akzeptanzkriterien
• bekannte Grenzen
• Risikohinweise
• erwartetes PR-Zusammenfassungsformat

EasyClaw unterstützt Multi-Agent-Entwicklungsworkflows

Die Arbeit eines Coding-Agenten ist selten eine einzelne Rolle. EasyClaw kann einen Multi-Agenten-Workflow unterstützen, bei dem jede Rolle eine definierte Aufgabe hat:

• Repository-Kontext-Agent: liest AGENTS.md und fasst Projektregeln zusammen.
• Anforderungsagent: extrahiert Akzeptanzkriterien und Nichtziele.
• Implementierungsagent: schlägt kleine Codeänderungen vor.
• Testagent: prüft Einheiten-, Integrations- und fokussierte Testbefehle.
• Fehleranalyse-Agent: fasst fehlgeschlagene Testprotokolle zusammen.
• Security Review Agent: Kennzeichnet vertrauliche Codepfade.
• Dokumentationsagent: entwirft die PR-Zusammenfassung und die Versionshinweise.
• Review Agent: markiert unsichere Ansprüche für die Genehmigung durch den Menschen.

Dies ist stärker als eine riesige „Repariere dieses Repo“-Eingabeaufforderung, da jeder Agent eine begrenzte Rolle und überprüfbare Ausgabe hat.

EasyClaw hält die Menschen auf dem Laufenden

Weder AGENTS.md noch EasyClaw sollten den Produktionscode allein genehmigen. Die Beurteilung der Architektur, Sicherheitsentscheidungen, Testqualität und Zusammenführungsgenehmigung liegt immer noch bei menschlichen Prüfern.

EasyClaw kann dabei helfen, Kontrollpunkte zu erstellen: den Aufgabenplan genehmigen, generierten Code überprüfen, die Analyse fehlgeschlagener Protokolle überprüfen, sicherheitsrelevante Änderungen überprüfen und entscheiden, ob die Arbeit für die Zusammenführung bereit ist.

EasyClaw unterstützt geplante und durch Chat ausgelöste Arbeitsabläufe

Die Wartung von AGENTS.md vergisst man leicht. EasyClaw kann geplante Arbeitsabläufe wie wöchentliche AGENTS.md-Überprüfungen, nächtliche Zusammenfassungen fehlgeschlagener Tests, offene PR-Zusammenfassungen, Checklisten vor der Veröffentlichung und Notizen zu Abhängigkeitsrisiken unterstützen.

Ingenieurteams koordinieren auch in Slack, Discord, Telegram oder Teams. EasyClaw kann durch Chat ausgelöste Arbeitsabläufe unterstützen wie:

„Überprüfen Sie die Datei AGENTS.md, vergleichen Sie sie mit Paketskripten und bereiten Sie Verbesserungshinweise vor.“

Oder:

„Fassen Sie fehlgeschlagene Tests aus dem letzten Zweig zusammen und bereiten Sie ein PR-Überprüfungspaket vor.“

EasyClaw unterstützt den Entwickler-Workflow im RPA-Stil

KI-Codierungsworkflows umfassen häufig mehrere Tools: IDEs, Terminals, Browser, GitHub- oder GitLab-Seiten, lokale Dateien, Dokumente, Tabellenkalkulationen, Slack-Threads und Versionshinweise. EasyClaw kann bei der Organisation von Desktop-Workflows im RPA-Stil rund um diese Tools helfen: Kontext sammeln, Protokolle gruppieren, Zusammenfassungen vorbereiten, Berichte verpacken und Ausgaben an den richtigen Ort verschieben.

Hier ergänzt EasyClaw AGENTS.md: Die Datei gibt Anweisungen und die Workflow-Ebene wandelt Anweisungen in wiederholbare technische Aktionen um.

EasyClaw AGENTS.md-Workflow-Beispiel

Stellen Sie sich vor, ein Team möchte die Zuverlässigkeit des Coding-Agents in einem TypeScript-Monorepo verbessern.

Eingabe: vorhandene AGENTS.md, Paketskripte, Testprotokolle, kürzlich fehlgeschlagene Agentenaufgaben, Repository-Struktur, Checkliste für die Codeüberprüfung und PR-Vorlage.

Arbeitsablauf:

1. EasyClaw organisiert AGENTS.md, Skripte, Protokolle und Repo-Notizen.
2. Der Repository-Kontextagent identifiziert veraltete oder vage Anweisungen.
3. Der Testagent prüft, ob Testbefehle mit Paketskripten übereinstimmen.
4. Der Security Review Agent überprüft Grenzen für Geheimnisse, Authentifizierung und Produktionskonfiguration.
5. Documentation Agent entwirft eine strengere Überarbeitung von AGENTS.md.
6. Der Überprüfungsagent markiert unsichere Elemente zur menschlichen Überprüfung.
7. EasyClaw enthält Verbesserungshinweise, die überarbeitete Vorlage und eine Teamzusammenfassung.
8. Ein Entwickler überprüft die endgültige Datei und schreibt sie fest.

Ausgabe: verbesserter AGENTS.md-Entwurf, veraltete Anweisungsliste, fehlende Hinweise zu Testbefehlen, Vorschläge zu Sicherheitsgrenzen, PR-bereite Zusammenfassung und Checkliste für die menschliche Genehmigung.

Dabei handelt es sich nicht um eine automatische „EasyClaw-Reparatur“ von AGENTS.md. Es handelt sich um einen strukturierten Workflow zur Aufrechterhaltung eines besseren Coding-Agent-Kontexts.

AGENTS.md vs. EasyClaw Workflow

AGENTS.md ist die Kontextschicht. EasyClaw ist die Workflow-Ebene rund um Kontext, Ausführung, Überprüfung und Übergabe.

Häufige AGENTS.md-Fehler

Der häufigste Fehler besteht darin, die Datei zu lang zu machen. Weitere Fehler sind vage Regeln, fehlerhafte Befehle, veraltete Ordnerbeschreibungen, widersprüchliche Konventionen, fehlende Sicherheitsgrenzen, keine Testanweisungen, keine Definition von „Done“ und die Behandlung von AGENTS.md als eine Möglichkeit, eine menschliche Überprüfung zu vermeiden.

Letzte Gedanken

Bei den Best Practices von AGENTS.md geht es nicht darum, eine möglichst lange Anweisungsdatei zu schreiben. Dabei geht es darum, den KI-Programmierungsagenten die kleinstmögliche nützliche Menge an Repository-Kontext zur Verfügung zu stellen, die sie benötigen, um sicher und effektiv zu arbeiten.

Ein gutes AGENTS.md erklärt Setup, Tests, Struktur, Konventionen, Arbeitsablauf, Grenzen und Definition von erledigt.

EasyClaw passt die nächste Schicht. Es ersetzt nicht AGENTS.md, Codierungsagenten, CI/CD oder Codeüberprüfung. Es hilft Entwicklern, Repository-Anweisungen in sichtbare, wiederholbare KI-Coding-Workflows mit Multi-Agent-Zusammenarbeit, geplanten Berichten, durch Chat ausgelösten Befehlen, Desktop-Unterstützung im RPA-Stil und von Menschen überprüften Ergebnissen umzuwandeln.

AGENTS.md gibt KI-Coding-Agenten Kontext. EasyClaw hilft dabei, diesen Kontext in einen zuverlässigen Entwicklungsworkflow umzuwandeln.

FAQ

Probieren Sie EasyClaw für AGENTS.md-Workflows aus

Wenn Ihr Team damit beginnt, AGENTS.md für Codex, Copilot, Cursor, Claude Code oder andere KI-Codierungsagenten zu verwenden, bleiben Sie nicht bei der Kontextdatei stehen. Verwenden Sie EasyClaw, um diese Repository-Anweisungen in einen wiederholbaren KI-Codierungsworkflow umzuwandeln: organisierter Kontext, Multi-Agent-Überprüfung, Fehlerprotokollanalyse, geplante technische Berichte, PR-Zusammenfassungen und Human-in-the-Loop-Übergaben.