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

Meine erste AGENTS.md war ein 200-zeiliges Einfügen unseres Team-Styleguides. Sie enthielt Namenskonventionen, Code-Review-Checklisten, Deployment-Verfahren und Architekturprinzipien. Der Agent ignorierte das meiste davon. Nicht weil die Anweisungen falsch waren — sondern weil es Dokumentation war, keine Handlungsanweisungen.

Diese Unterscheidung ist wichtiger als jedes einzelne Muster in diesem Beitrag. AGENTS.md ist eine operative Richtlinie für einen KI-Agenten, kein README für Menschen. Der Agent muss nicht verstehen, warum Sie Conventional Commits verwenden. Er muss den genauen Befehl kennen, den er ausführen soll, und wissen, wie „fertig” aussieht.

TL;DR

Die meisten Probleme mit AGENTS.md entstehen, weil menschliche Dokumentation statt Handlungsanweisungen für Agenten geschrieben wird. Effektive Dateien sind befehlsorientiert (exakte Aufrufe, keine Beschreibungen), aufgabenorientiert organisiert (Abschnitte für Coding, Review, Release) und mit klaren Abschlusskriterien versehen (explizite „Fertig”-Kriterien). Anti-Muster, die zuverlässig ignoriert werden: Prosatexte, vage Anweisungen („sei vorsichtig”) und widersprüchliche Prioritäten. AGENTS.md ist ein offener Standard, der von über 60.000 Projekten übernommen wurde ¹ und mit Codex, Cursor, Copilot, Amp, Windsurf und weiteren Tools funktioniert ².

Kontext: AGENTS.md wird von der Agentic AI Foundation unter der Linux Foundation verwaltet ³, mit Platinum-Mitgliedern wie Anthropic, Google, Microsoft und OpenAI. Dieser Beitrag behandelt praktische Muster. Für Codex-spezifische Konfiguration siehe den Codex-Leitfaden. Für das Claude Code-Äquivalent (CLAUDE.md) siehe den Claude Code-Leitfaden.

Was ignoriert wird

Diese Muster erzeugen zuverlässig keine beobachtbare Veränderung im Verhalten des Agenten. Ich habe jedes einzelne identifiziert, indem ich identische Aufgaben mit und ohne die jeweilige Anweisung ausgeführt und anschließend die Aufgabenabschlussgenauigkeit über mehr als 10 Durchläufe pro Muster verglichen habe. GitHubs Analyse von über 2.500 Repositories mit AGENTS.md-Dateien kam zum selben Ergebnis: „Die meisten Agenten-Dateien scheitern, weil sie zu vage sind — nicht wegen technischer Einschränkungen” ¹¹. Die folgenden Muster haben die Genauigkeit in keiner messbaren Weise verbessert.

Prosatexte 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 dies, repräsentiert es als vage Präferenz und schreibt dann Code ohne Tests. Es gibt keine umsetzbare Anweisung — keinen Befehl zum Ausführen, keinen Schwellenwert, keine Definition von „ordnungsgemäß 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 klingt nach Mensch-zu-Mensch-Anleitung, nicht nach Agentenanweisungen. Vergleichen Sie mit dem, was funktioniert: „Führen Sie alembic check vor dem Anwenden von Migrationen aus. Abbruch, 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

Der Agent kann nicht alle vier gleichzeitig erfüllen. Wenn Anweisungen ohne explizite Prioritätsreihenfolge in Konflikt stehen, überspringt das Modell Überprüfungsschritte und stürzt sich auf die Codegenerierung. Forschung der ICLR 2026 (AMBIG-SWE) hat ergeben, dass Agenten „ohne explizite Ermutigung standardmäßig nicht-interaktives Verhalten zeigen” — sie fahren stillschweigend fort, anstatt klärende Fragen zu stellen, was die Lösungsrate von 48,8 % auf 28 % senkte ¹². Beheben Sie widersprüchliche Anweisungen durch Nummerierung der Prioritäten: „Priorität 1: Tests bestehen. Priorität 2: Unter 5 Minuten. Priorität 3: Schnell ausliefern.”

Stilrichtlinien ohne Durchsetzung

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

Wenn Sie nicht den genauen Linting-Befehl angeben, der den Stil durchsetzt (ruff check --select D oder pylint --rcfile=.pylintrc), hat der Agent keinen Mechanismus, seine eigene Einhaltung zu überprüfen. Das Muster ist universell: Anweisungen ohne Überprüfungsbefehle sind Vorschläge, keine Regeln.

Was funktioniert

Diese Muster erzeugen konsistente, messbare Verä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, welche Argumente er übergeben muss, und kann den Erfolg anhand des Exit-Codes überprüfen. 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 eliminieren den häufigsten Fehlermodus: Der Agent meldet „fertig”, ohne es zu überprüfen. Wenn „fertig” als spezifische Exit-Codes definiert ist, führt der Agent jede Prüfung aus, bevor er den Abschluss meldet. Ohne diese Definition bedeutet „fertig” nur „ich glaube, ich bin fertig” — eine häufige Ursache für agentenverursachte Fehler.

Aufgabenorientierte 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>"`

Aufgabenorientierte Dateien ermöglichen es dem Agenten, relevante Anweisungen basierend auf seiner aktuellen Tätigkeit auszuwählen. Flache Listen zwingen den Agenten, jede Anweisung unabhängig vom Kontext zu durchsuchen. Das „When…”-Präfix bildet direkt 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 Workarounds — sie löschen Lock-Dateien, umgehen Prüfungen oder ignorieren Fehler stillschweigend. Die „Niemals”-Liste ist genauso wichtig wie die Eskalationspfade. Das explizite Verbot destruktiver Wiederherstellungsmuster verhindert die schlimmsten Fehlermodi.

Verzeichnisbezogene Geltungsbereiche für Monorepos

AGENTS.md unterstützt hierarchische Geltungsbereiche 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 Root-Ebene werden mit tieferen Dateien verkettet. Tools durchlaufen den Pfad vom Projektstamm zum aktuellen Arbeitsverzeichnis und kombinieren jede gefundene AGENTS.md ⁴. OpenAIs eigenes Codex-Repository verwendet 88 separate AGENTS.md-Dateien für sein Monorepo — eine pro Service und Paket ⁴.

In Codex können Sie auch AGENTS.override.md auf jeder Ebene verwenden, um übergeordnete Anweisungen zu ersetzen (nicht zu erweitern) ⁴. 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 Override verwenden: Bei Release-Freezes, im Incident-Modus oder bei jedem Service mit Sicherheitsanforderungen, die projektweite Standardwerte überschreiben.

Tool-übergreifende Kompatibilität

AGENTS.md wird von über 60.000 Projekten genutzt ¹ und von jedem wichtigen KI-Coding-Tool erkannt. So verhält sich dieselbe Datei in verschiedenen Ökosystemen:

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

Schreibreihenfolge: Was Sie zuerst hinzufügen sollten

Wenn Sie eine AGENTS.md von Grund auf schreiben, fügen Sie Abschnitte in dieser Prioritätsreihenfolge hinzu. Jede Ebene baut auf der vorherigen auf:

1. Build- und Testbefehle — der Agent braucht diese, bevor er etwas Sinnvolles tun kann
2. Abschlussdefinition — verhindert falsche „Ich glaube, ich bin fertig”-Meldungen
3. Eskalationsregeln — verhindert destruktive Workarounds, wenn der Agent blockiert ist
4. Aufgabenorientierte Abschnitte — reduziert das Durchsuchen irrelevanter Anweisungen pro Aufgabe
5. Verzeichnisbezogene Geltungsbereiche (nur Monorepos) — hält Service-Anweisungen isoliert

Überspringen Sie Stilpräferenzen, bis die ersten vier Punkte funktionieren. Die meisten AGENTS.md-Dateien scheitern, weil sie mit Stilrichtlinien beginnen und nie zu den Befehlen kommen.

Ihre AGENTS.md testen

Überprü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 erklären. Wenn er sie nicht wortwörtlich wiedergeben kann, werden die Anweisungen entweder nicht gelesen oder sind zu umfangreich, um im Kontext behalten zu werden. Lange AGENTS.md-Dateien werden durch Kontextfenster abgeschnitten — halten Sie jeden Abschnitt unter 50 Zeilen und platzieren Sie die wichtigsten Anweisungen am Anfang.

FAQ

Wie lang sollte eine AGENTS.md-Datei sein?

Halten Sie jeden Abschnitt unter 50 Zeilen und die Gesamtdatei unter 150 Zeilen ¹³. Codex erzwingt ein Standard-Limit von 32 KiB (project_doc_max_bytes) ⁴. Lange Dateien werden durch Kontextfenster abgeschnitten, daher sollten Sie die wichtigsten Anweisungen an den Anfang stellen — Befehle und Abschlussdefinitionen vor Stilpräferenzen.

Ersetzt AGENTS.md tool-spezifische Anweisungsdateien?

Nein. AGENTS.md funktioniert neben CLAUDE.md, .cursor/rules und anderen tool-spezifischen Dateien. Schreiben Sie AGENTS.md als kanonische Quelle und spiegeln Sie dann relevante Abschnitte in tool-spezifische Dateien. Die Muster in AGENTS.md (befehlsorientiert, mit Abschlussdefinitionen) funktionieren in jeder Anweisungsdatei unabhängig vom Tool.

Was tun, wenn der Agent meine AGENTS.md ignoriert?

Testen Sie, indem Sie den Agenten bitten, Ihre Build-Befehle zu erklären. Wenn er sie nicht wortwörtlich wiedergeben kann, ist die Datei entweder zu umfangreich (Inhalt wird aus dem Kontext verdrängt), zu vage (Agent kann keine umsetzbaren Anweisungen extrahieren) oder wird nicht erkannt (überprüfen Sie den Dateispeicherort und die Tool-Dokumentation). GitHubs Analyse von 2.500 Repositories ergab, dass Ungenauigkeit — nicht technische Einschränkungen — die meisten Fehlschläge verursacht ¹¹.

Wichtigste Erkenntnisse

Für einzelne Entwickler:

• Ersetzen Sie Prosa durch Befehle. Jede Anweisung sollte durch Ausführen eines Befehls überprüfbar sein.
• Definieren Sie den Abschluss explizit. „Fertig” bedeutet spezifische Exit-Codes, kein Bauchgefühl.
• Testen Sie Ihre AGENTS.md, indem Sie den Agenten bitten, sie wiederzugeben. Was er nicht wiedergeben kann, wird er nicht befolgen.

Für Teams:

• Verwenden Sie AGENTS.md als einzige Wahrheitsquelle. Spiegeln Sie in tool-spezifische Dateien, pflegen Sie keine parallelen Kopien.
• Organisieren Sie nach Aufgabe (Coding, Review, Release), nicht nach Kategorie (Stil, Tests, Deployment).
• Fügen Sie Eskalationsregeln hinzu. Ohne sie improvisieren blockierte Agenten auf Weisen, die Ihnen nicht gefallen werden.
• Beschränken Sie den Geltungsbereich pro Verzeichnis in Monorepos. Service-spezifische Regeln sollten globale Anweisungen nicht verunreinigen.

Referenzen