AGENTS.md-Muster: Was das Verhalten von Agenten wirklich verändert

Meine erste AGENTS.md war eine 200 Zeilen lange Kopie des Styleguides unseres Teams. Sie enthielt Namenskonventionen, Checklisten für Code-Reviews, Deployment-Abläufe und Architekturprinzipien. Der Agent ignorierte das meiste davon. Nicht weil die Anweisungen falsch gewesen wären, sondern weil sie Dokumentation waren und keine Betriebsanweisungen.

AGENTS.md sollte befehlsorientierte Anweisungen mit exakten Aufrufen enthalten, nach Aufgaben gegliederte Abschnitte (Programmieren, Review, Release) und explizite „Fertig“-Kriterien, die der Agent überprüfen kann. Schreiben Sie operative Richtlinien, keine Dokumentation für Menschen. Nehmen Sie die konkreten Shell-Befehle, Linter-Konfigurationen und Testbefehle auf, die der Agent ausführen muss. Vermeiden Sie Fließtextabsätze, vage Anweisungen wie „sei vorsichtig“ und widersprüchliche Prioritäten ohne explizite Reihenfolge. AGENTS.md ist ein offener Standard, den über 60.000 Projekte übernommen haben und der über Codex, Cursor, Copilot und weitere Agenten-Tools hinweg funktioniert.

Diese Unterscheidung wiegt schwerer als jedes einzelne Muster in diesem Beitrag. AGENTS.md ist operative Richtlinie für einen KI-Agenten, keine README für Menschen. Der Agent muss nicht verstehen, warum Sie Conventional Commits verwenden. Er muss den exakten Befehl kennen und wissen, wie „fertig“ aussieht.

TL;DR

Die meisten Probleme mit AGENTS.md entstehen, weil darin Dokumentation für Menschen steht statt Betriebsanweisungen für Agenten. Wirksame Dateien sind befehlsorientiert (exakte Aufrufe statt Beschreibungen), nach Aufgaben gegliedert (Abschnitte für Programmieren, Review, Release) und mit definiertem Abschluss (explizite „Fertig“-Kriterien). Anti-Muster, die zuverlässig ignoriert werden: Fließtextabsätze, vage Anweisungen („sei vorsichtig“) und widersprüchliche Prioritäten. AGENTS.md ist ein offener Standard, den über 60.000 Projekte übernommen haben ¹ und der über Codex, Cursor, Copilot, Amp, Devin Desktop und weitere Tools hinweg funktioniert ².

Kontext: AGENTS.md wird von der Agentic AI Foundation unter dem Dach der Linux Foundation verwaltet ³; zu den Platinum-Mitgliedern zählen Anthropic, Google, Microsoft und OpenAI. Dieser Beitrag behandelt die praktischen Muster. Zur Codex-spezifischen Konfiguration siehe den Codex-Leitfaden. Zum Äquivalent von Claude Code (CLAUDE.md) siehe den Claude-Code-Leitfaden.

Was ignoriert wird

Diese Muster erzeugen zuverlässig keine beobachtbare Änderung im Verhalten des Agenten. Identifiziert habe ich jedes einzelne, indem ich identische Aufgaben mit und ohne die jeweilige Anweisung ausgeführt und anschließend die Trefferquote bei der Aufgabenerledigung über mehr als 10 Durchläufe pro Muster verglichen habe. GitHubs Analyse von über 2.500 Repositories mit AGENTS.md-Dateien kam zum selben Schluss: „Die meisten Agent-Dateien scheitern, weil sie zu vage sind“ ¹¹. Die folgenden Muster verbesserten die Trefferquote in keiner messbaren Weise.

Fließtextabsätze ohne Befehle

<!-- BAD: Agent skips this -->
We value clean, well-tested code. Our team follows TDD principles
and believes in comprehensive test coverage. Please ensure all
changes are properly tested before submitting.

Der Agent liest das, hinterlegt es als vage Präferenz und schreibt anschließend Code ohne Tests. Es gibt keine umsetzbare Anweisung, keinen Befehl zum Ausführen, keinen Schwellenwert, der erreicht werden müsste, und keine Definition von „ordentlich getestet“.

Vage Anweisungen

<!-- BAD: "Careful" means nothing to an agent -->
- Be careful with database migrations
- Optimize queries where possible
- Handle errors gracefully

„Vorsichtig“ ist keine Einschränkung. „Wo möglich“ ist keine Auslösebedingung. „Elegant“ ist keine Verhaltensspezifikation. Das liest sich wie Orientierung von Mensch zu Mensch, nicht wie eine Anweisung an einen Agenten. Vergleichen Sie damit, was funktioniert: „Führe alembic check aus, bevor du Migrationen anwendest. Brich ab, wenn der Downgrade-Pfad fehlt.“

Widersprüchliche Prioritäten

<!-- BAD: Which one wins? -->
- Move fast and ship quickly
- Ensure comprehensive test coverage
- Keep the runtime budget under 5 minutes
- Run the full integration test suite before every commit

Alle vier gleichzeitig kann der Agent nicht erfüllen. Kollidieren Anweisungen ohne explizite Prioritätsreihenfolge, überspringt das Modell Verifikationsschritte und stürzt sich auf die Codegenerierung. Eine Untersuchung von der ICLR 2026 (Ambig-SWE) ergab: „Ohne explizite Aufforderung interagieren Modelle so gut wie nie, selbst bei stark unterspezifizierten Eingaben“ – Agenten arbeiten stillschweigend weiter, statt Rückfragen zu stellen –, während eine Aufforderung zur Interaktion die Leistung bei unterspezifizierten Aufgaben um bis zu 74 % steigert ¹². Beheben Sie widersprüchliche Anweisungen, indem Sie Prioritäten nummerieren: „Priorität 1: Tests bestehen. Priorität 2: unter 5 Minuten. Priorität 3: schnell ausliefern.“

Styleguides ohne Durchsetzung

<!-- BAD: No way to verify compliance -->
Follow the Google Python Style Guide for all code.
Use numpy-style docstrings for public functions.

Solange Sie nicht den exakten Lint-Befehl angeben, der den Stil durchsetzt (ruff check --select D oder pylint --rcfile=.pylintrc), fehlt dem Agenten jeder Mechanismus, seine eigene Regeltreue zu prüfen. Das Muster dahinter gilt universell: Anweisungen ohne Verifikationsbefehl sind Vorschläge, keine Regeln.

Was funktioniert

Diese Muster erzeugen konsistente, messbare Änderungen im Verhalten des Agenten.

Befehlsorientierte Anweisungen

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Befehle sind eindeutig. Der Agent weiß genau, was er ausführen soll und welche Argumente er übergeben muss, und kann den Erfolg am Exit-Code ablesen. Jede Anweisung in Ihrer AGENTS.md sollte die Frage beantworten: „Welcher Befehl beweist, dass dies korrekt erledigt wurde?“

Abschlussdefinitionen

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Explizite Abschlussdefinitionen beseitigen den häufigsten Fehlermodus: Der Agent meldet „fertig“, ohne es überprüft zu haben. Ist „fertig“ als bestimmte Exit-Codes definiert, führt der Agent jede Prüfung aus, bevor er die Fertigstellung meldet. Ohne diese Definition bedeutet „fertig“ nur „ich glaube, ich bin fertig“ – eine häufige Quelle für Fehler, die Agenten einschleppen.

Nach Aufgaben gegliederte Abschnitte

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions
- Test command: `pytest tests/ -v -k "test_<module>"`

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`
- List changed files: `git diff --name-only HEAD~1`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`
- Tag: `git tag -a v<version> -m "Release v<version>"`

Nach Aufgaben gegliederte Dateien erlauben dem Agenten, die passenden Anweisungen danach auszuwählen, was er gerade tut. Flache Listen zwingen ihn, jede Anweisung unabhängig vom Kontext zu verarbeiten. Das Präfix „Wenn …“ bildet unmittelbar ab, wie der Agent über den Aufgabenkontext nachdenkt.

Eskalationsregeln

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- If you encounter merge conflicts: stop and show the conflicting files
- Never: delete files to resolve errors, force push, or skip tests

Ohne Eskalationsregeln greifen Agenten bei Blockaden zu immer kreativeren Umgehungen: Sie löschen Lock-Dateien, umgehen Prüfungen oder verschweigen Fehlschläge. Die „Niemals“-Liste wiegt genauso schwer wie die Eskalationspfade. Destruktive Notlösungen ausdrücklich zu verbieten, verhindert die schlimmsten Fehlermodi.

Verzeichnis-Scoping für Monorepos

AGENTS.md unterstützt hierarchisches Scoping als Kernfunktion der Spezifikation ². Dateien, die näher am Arbeitsverzeichnis liegen, haben Vorrang:

/repo/AGENTS.md                        ← Project-wide rules
  └─ /repo/services/AGENTS.md          ← Service defaults
      ├─ /repo/services/api/AGENTS.md  ← API-specific rules
      └─ /repo/services/web/AGENTS.md  ← Frontend-specific rules

Anweisungen auf Wurzelebene werden mit tiefer liegenden Dateien verkettet. Codex läuft von der Projektwurzel bis zum aktuellen Arbeitsverzeichnis und kombiniert dabei jede AGENTS.md, die auf dem Weg liegt ⁴; die Spezifikation selbst legt den Vorrang der nächstgelegenen Datei fest, andere Tools können die Hierarchie also anders auflösen ². OpenAIs eigenes codex-Repository praktiziert genau das: Es liefert eine verschachtelte AGENTS.md unterhalb der Datei im Wurzelverzeichnis aus ⁴.

In Codex können Sie zudem auf jeder Ebene eine AGENTS.override.md einsetzen, um übergeordnete Anweisungen zu ersetzen (nicht zu ergänzen) ⁴. Der Override-Mechanismus ist Codex-spezifisch, andere Tools implementieren ihn nicht.

<!-- /repo/services/payments/AGENTS.override.md (Codex only) -->
# Payment Service Rules (OVERRIDE)

This service has additional security requirements.
All changes require: `bandit -r . -ll` passing with zero findings.
No dependency updates without explicit approval.
Test with: `pytest -v --tb=long -x` (fail fast, full tracebacks)

Wann Sie Override einsetzen sollten: bei Release-Freezes, im Incident-Modus oder für jeden Dienst mit Sicherheitsanforderungen, die projektweite Vorgaben aushebeln.

Tool-übergreifende Kompatibilität

AGENTS.md wird von über 60.000 Projekten genutzt ¹ und von jedem großen KI-Coding-Tool erkannt. So verhält sich dieselbe Datei in den verschiedenen Ökosystemen (Tabelle im August 2026 verifiziert):

Wenn Ihr Team mehrere Tools nutzt: Schreiben Sie AGENTS.md als kanonische Quelle. Ergänzen Sie tool-spezifische Dateien (CLAUDE.md, .cursorrules), die die relevanten Abschnitte entweder importieren oder spiegeln. Pflegen Sie keine parallelen Anweisungssätze, die auseinanderdriften.

Schreibreihenfolge: Womit Sie anfangen

Wenn Sie eine AGENTS.md von Grund auf schreiben, ergänzen Sie die Abschnitte in dieser Prioritätsreihenfolge. Jede Schicht baut auf der vorherigen auf:

1. Build- und Testbefehle – die braucht der Agent, bevor er überhaupt etwas Nützliches tun kann
2. Abschlussdefinition – verhindert falsche Fertigmeldungen nach dem Motto „ich glaube, ich bin fertig“
3. Eskalationsregeln – verhindern destruktive Umgehungen, wenn der Agent feststeckt
4. Nach Aufgaben gegliederte Abschnitte – reduzieren das Verarbeiten irrelevanter Anweisungen pro Aufgabe
5. Verzeichnis-Scoping (nur Monorepos) – hält dienstspezifische Anweisungen isoliert

Stilpräferenzen bleiben liegen, bis die ersten vier funktionieren. Die meisten AGENTS.md-Dateien scheitern, weil sie mit Stilvorgaben beginnen und nie bei den Befehlen ankommen.

Ihre AGENTS.md testen

Prüfen Sie, ob der Agent Ihre Anweisungen tatsächlich liest und befolgt:

# Codex: Show the full instruction chain
codex --ask-for-approval never "Summarize your current instructions"

# Codex: Generate a scaffold (slash command inside an active session)
# Type /init at the Codex prompt, not as a shell command
codex  # then type: /init

# Claude Code: Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
codex --ask-for-approval never "What is your definition of done?"

Der Härtetest: Bitten Sie den Agenten, Ihre Build-Befehle zu erläutern. Kann er sie nicht wörtlich wiedergeben, werden die Anweisungen nicht gelesen oder sie sind zu ausschweifend, um im Kontext zu bleiben. Lange AGENTS.md-Dateien schneiden Kontextfenster ab – halten Sie jeden Abschnitt unter 50 Zeilen und stellen Sie die wichtigsten Anweisungen nach vorn.

FAQ

Wie lang sollte eine AGENTS.md-Datei sein?

Meine Faustregel: jeden Abschnitt unter 50 Zeilen halten, die gesamte Datei unter 150. Das Prinzip dahinter stammt aus Marmelabs Leitfaden zur Agent Experience – die Datei sollte „kurz und auf den Punkt“ bleiben, weil Agenten sie zu Beginn jeder Sitzung lesen ¹³; die konkreten Zeilenzahlen stammen von mir, nicht von dort. Codex erzwingt standardmäßig ein Limit von 32 KiB (project_doc_max_bytes) ⁴. Lange Dateien schneiden Kontextfenster ab; stellen Sie deshalb die wichtigsten Anweisungen, Befehle und Abschlussdefinitionen vor die Stilpräferenzen.

Ersetzt AGENTS.md tool-spezifische Anweisungsdateien?

Nein. AGENTS.md arbeitet neben CLAUDE.md, .cursor/rules und anderen tool-spezifischen Dateien. Schreiben Sie AGENTS.md als kanonische Quelle und spiegeln Sie die relevanten Abschnitte anschließend in die tool-spezifischen Dateien. Die Muster aus AGENTS.md (befehlsorientiert, mit definiertem Abschluss) funktionieren in jeder Anweisungsdatei, unabhängig vom Tool.

Was, wenn der Agent meine AGENTS.md ignoriert?

Testen Sie es, indem Sie den Agenten bitten, Ihre Build-Befehle zu erläutern. Kann er sie nicht wörtlich wiedergeben, ist die Datei entweder zu ausschweifend (Inhalt aus dem Kontext gedrängt), zu vage (der Agent kann keine umsetzbaren Anweisungen ableiten) oder sie wird gar nicht gefunden (prüfen Sie den Dateipfad und die Dokumentation des Tools). GitHubs Analyse von über 2.500 Repositories ergab, dass die meisten Agent-Dateien scheitern, weil sie zu vage sind ¹¹.

Die wichtigsten Erkenntnisse

Für einzelne Entwickler:

• Ersetzen Sie Prosa durch Befehle. Jede Anweisung sollte sich durch Ausführen von etwas überprüfen lassen.
• Definieren Sie den Abschluss explizit. „Fertig“ bedeutet bestimmte Exit-Codes, keine Gefühlslage.
• Testen Sie Ihre AGENTS.md, indem Sie den Agenten bitten, sie aufzusagen. Was er nicht aufsagen kann, wird er nicht befolgen.

Für Teams:

• Nutzen Sie AGENTS.md als einzige Quelle der Wahrheit. Spiegeln Sie in tool-spezifische Dateien, statt parallele Kopien zu pflegen.
• Gliedern Sie nach Aufgabe (Programmieren, Review, Release), nicht nach Kategorie (Stil, Tests, Deployment).
• Nehmen Sie Eskalationsregeln auf. Ohne sie improvisieren blockierte Agenten auf eine Weise, die Ihnen nicht gefallen wird.
• Grenzen Sie in Monorepos pro Verzeichnis ab. Dienstspezifische Regeln sollten die globalen Anweisungen nicht verunreinigen.

Quellen