Was gehört in AGENTS.md und CLAUDE.md?
Was in AGENTS.md und CLAUDE.md gehört, gestützt auf Agent-Benchmarks: nützliche Befehle, betriebliche Vorgaben, teure Fallen und was du weglassen solltest.
Eine Anweisungsdatei im Repository wird schnell zu einer komprimierten README, einem Architekturaufsatz und einer Liste bewundernswerter Engineering-Prinzipien. Der Agent bekommt dieses Material dann bei jeder Aufgabe – auch wenn das meiste davon irrelevant ist.
Aktuelle Benchmark-Ergebnisse legen eine engere Aufgabe für diese Dateien nahe.
Nutze AGENTS.md und CLAUDE.md als kurze Betriebshandbücher: exakte Befehle,
teure Operationen, Prüfschritte, Grenzen und Fakten, die sich aus dem Code nur
schwer ableiten lassen. Erwarte nicht, dass eine längere Projektbeschreibung
dem Modell Engineering-Urteilsvermögen verschafft, das es nicht ohnehin schon
hat.
Kurze Antwort
Nimm einen Fakt in die Anweisungsdatei im Stammverzeichnis auf, wenn alle drei Bedingungen zutreffen:
- Er gilt für den Großteil der Arbeit in diesem Bereich.
- Der Agent kann ihn nicht schnell und zuverlässig aus dem Repository selbst herausfinden.
- Wenn er befolgt wird, ändert sich eine beobachtbare Aktion oder Prüfung.
Gute Beispiele sind:
pnpm test --filter apiist der schnelle Testbefehl für Änderungen an der API.- Die vollständige Integrations-Suite dauert 25 Minuten und sollte einmal laufen, nachdem die gezielten Tests bestanden sind.
- Dateien unter
generated/müssen überpnpm generategeändert werden. - Eine neue Produktionsabhängigkeit oder eine Änderung an einer Datenbankmigration erfordert eine Bestätigung.
- Eine Änderung ist erst fertig, wenn der Typcheck und der relevante gezielte Test bestehen.
Lass pauschale Aussagen wie „schreib sauberen Code“, kopierte Paketlisten und Beschreibungen weg, die sich der Agent durch Lesen des Manifests und des Quellbaums selbst beschaffen kann. Nutze einen Aufgaben-Prompt für einmalige Anforderungen, einen Skill für einen Ablauf bei Bedarf und Tests, Hooks oder CI für Regeln, die maschinell durchgesetzt werden müssen.
AGENTS.md und CLAUDE.md sind ähnlich, aber nicht identisch
Beide Dateien liefern dauerhafte Anweisungen für das Repository, aber wie sie gefunden werden und wofür sie gelten, bestimmt der Agent, der sie liest.
Codex AGENTS.md |
Claude Code CLAUDE.md |
|
|---|---|---|
| Projektdatei im Stammverzeichnis | AGENTS.md |
CLAUDE.md oder .claude/CLAUDE.md |
| Persönliche Voreinstellungen | ~/.codex/AGENTS.md |
~/.claude/CLAUDE.md |
| Spezifischere Hinweise | Verschachtelte AGENTS.md oder AGENTS.override.md |
Verschachtelte CLAUDE.md oder pfadbezogene .claude/rules/ |
| Wie Dateien kombiniert werden | Kette vom Stamm- bis zum Arbeitsverzeichnis; nähere Dateien greifen später | Übergeordnete Dateien laden beim Start; verschachtelte laden, wenn Claude in diesem Teilbaum arbeitet |
| Aktuelle Größenempfehlung | Standardmäßig 32 KiB Limit für alle gefundenen Dateien zusammen | Anthropic empfiehlt weniger als 200 Zeilen pro Datei |
Codex baut seine Anweisungskette einmal pro Lauf bzw. pro gestarteter TUI-Session auf. Es prüft globale Anweisungen und geht dann vom Projekt-Stammverzeichnis bis zum aktuellen Arbeitsverzeichnis. Eine nähere Datei erscheint später im kombinierten Prompt und überschreibt deshalb allgemeinere Anweisungen. Die genaue Suchreihenfolge und das Überschreibungsverhalten stehen in der Codex-Dokumentation zu AGENTS.md.
Claude Code behandelt CLAUDE.md als Kontext, nicht als erzwungene
Konfiguration. Die Dokumentation empfiehlt konkrete, knappe Anweisungen und
erklärt, dass große oder widersprüchliche Dateien die Einhaltung verringern.
Siehe
How Claude remembers your project.
Wenn ein Team beide Agenten nutzt, halte die gemeinsamen Anweisungen in
AGENTS.md und importiere sie aus einer kleinen CLAUDE.md:
@AGENTS.md
## Claude Code only
- Use the path-scoped rule in `.claude/rules/frontend.md` for UI changes.
Anthropic dokumentiert dieses Importmuster ausdrücklich. Ein Symlink kann auch funktionieren, aber der Import lässt Platz für ein paar Claude-spezifische Hinweise und ist unter Windows portabler.
Was die neueste Studie mit zwei Agenten getestet hat
Der Preprint Do Context Files Help Coding Agents? vom Juli 2026 machte aus gemergten Pull Requests dreier Python-Repositorys – PDM, firebase-admin-python und opshin – 17 Coding-Aufgaben. Die Beschreibung des PR diente als Prompt, während die Tests aus dem echten PR verborgen blieben und die Implementierung des Agenten bewerteten.
Claude Code und Codex arbeiteten jeweils unter drei Bedingungen:
- ohne: keine Kontextdatei für das Repository;
- immer aktiv: die vollständige
AGENTS.mdwurde in jeden Turn eingefügt; - selektiv: der Agent bekam einen Hinweis und konnte bei Bedarf nach Themen geordnete Wiki-Dateien lesen.
Nach drei Wiederholungen lagen für 288 Läufe gültige Korrektheitsergebnisse vor:
| Strategie | Claude Code | Codex |
|---|---|---|
| Kein Kontext | 53,3 % | 58,8 % |
| Immer aktiv | 55,6 % | 56,9 % |
| Selektiv | 55,6 % | 52,9 % |
Die Unterschiede waren statistisch nicht signifikant. Bei der manuellen
Auswertung der Autoren scheiterten knapp verfehlte Lösungen an Feature-Design,
Musterwahl oder falscher Verdrahtung – nicht an einem fehlenden Fakt über das
Repository, der in der echten AGENTS.md gestanden hätte. Diesen Kontext
hinzuzufügen oder umzuorganisieren, machte aus diesen Fehlschlägen keine
Erfolge.
Das Ergebnis beweist nicht, dass Anweisungsdateien die Korrektheit nie verbessern. Die Stichprobe umfasst nur drei Python-Repositorys und 15–17 Aufgaben pro Agent. Laut der Power-Analyse des Papers wären etwa 120–200 Aufgaben nötig, um einen Effekt von 10 Prozentpunkten zu erkennen. Außerdem wurde eine stärkere, künstliche Einspeisung getestet, statt die Datei einfach an ihrem natürlichen Ort im Workspace liegen zu lassen: Claude bekam einen angehängten System-Prompt, Codex Text, der dem User-Prompt vorangestellt wurde.
Die Bedingung „selektiv“ hat eine weitere Einschränkung. Ihr Wiki entsprach
nur bei opshin der ursprünglichen AGENTS.md; die beiden anderen Repositorys
bekamen breiter angelegte, generierte Wikis, die etwa 10- bzw. 18-mal so lang
waren. Der selektive Abruf ist daher kein sauberer Vergleich desselben
Inhalts, der nur anders ausgeliefert wird.
Das nützliche Ergebnis war betrieblicher Natur
Die AGENTS.md von opshin sagt, dass die vollständige Test-Suite mehr als 20
Minuten dauert. Ohne diese Warnung ließ Claude die gesamte Suite im Schnitt
3,67-mal pro Zelle laufen. Mit immer aktivem Kontext waren es 2,44-mal, mit
selektivem Kontext 1,67-mal. Die durchschnittliche Laufzeit sank von 2.689
Sekunden auf 2.066 bzw. 2.032 Sekunden – eine Verringerung um etwa 24 % –,
ohne dass sich die Korrektheit entsprechend verbesserte.
Das ist ein guter Beleg für eine bestimmte Art von Anweisung: Sag dem Agenten, was eine Aktion kostet, und gib ihm einen günstigeren korrekten Weg. Ein allgemeiner Beweis für schnellere Ausführung ist es nicht. Die Analyse war explorativ, betraf Claude in einem einzigen Repository und hatte mit fünf Aufgaben zu wenig statistische Power. Bei Codex blieb die Dauer unverändert, und ein anderes Repository bewegte sich leicht in die Gegenrichtung.
Die vorsichtige Schlussfolgerung lautet:
Eine Anweisungsdatei im Repository kann verbessern, wie ein Agent arbeitet, auch wenn sie nicht verbessert, was der Agent lösen kann.
Die breitere Beweislage ist gemischt
Zwei frühere Studien aus dem Jahr 2026 kamen bei der Effizienz zu unterschiedlichen Ergebnissen:
- On the Impact of AGENTS.md Files
untersuchte 10 Repositorys und 124 Pull Requests. Das Vorhandensein von
AGENTS.mdging mit einer um 28,64 % geringeren medianen Laufzeit und 16,58 % weniger Ausgabe-Tokens einher, bei vergleichbarem Abschlussverhalten. - Evaluating AGENTS.md testete generierte und von Entwicklern geschriebene Dateien über Agenten und Modelle hinweg. Die Studie fand keine generelle Verbesserung des Aufgabenerfolgs und im Schnitt über 20 % höhere Inferenzkosten, obwohl die Agenten nicht standardmäßige Anweisungen durchaus befolgten.
Das neue Paper mit zwei Agenten legt nahe, dass unterschiedliche Einspeisungsmechanismen und agentenspezifische Aufgabenschwierigkeit den Widerspruch erklären könnten. Das ist eine Hypothese, keine gesicherte Auflösung. Über alle drei Papers hinweg ist es am besten begründbar, eine Datei an dem Verhalten zu messen, das sie verändert, statt anzunehmen, dass mehr Kontext besser ist.
Was in eine nützliche Kontextdatei gehört
Exakte Befehle und der schnelle Weg
Gib Befehle an, die sofort ausführbar sind, samt richtigem Arbeitsverzeichnis und nützlichen Flags. Unterscheide die gezielte Prüfung von der teuren abschließenden Suite:
## Verification
- API change: run `pnpm test --filter api` first.
- Type check: run `pnpm typecheck` after changing TypeScript.
- Full suite: `pnpm test`; takes about 18 minutes, so run it once after focused tests pass.
„Führ die Tests aus“ bringt wenig. Den richtigen Befehl, seine Kosten und die Reihenfolge zu nennen, erspart das Raten.
Grenzen mit Begründung oder sicherer Alternative
Halte nicht offensichtliche Bereiche fest, die der Agent nicht direkt ändern soll:
## Boundaries
- Do not edit `src/generated/`; change the schema and run `pnpm generate`.
- Ask before adding a production dependency.
- Do not rewrite an existing migration; add a new migration instead.
Ein sicherer Weg ist nützlicher als ein bloßes Verbot.
Repository-spezifische Invarianten
Nimm Konventionen auf, die wichtig und überraschend sind und nicht maschinell durchgesetzt werden. Beispiele sind eine ungewöhnliche Regel für das Mapping von Fehlern, eine Kompatibilitätsanforderung, die Tests nicht abdecken, oder der eine Dienst, der einen anderen Befehl verwenden muss.
Dienstspezifische Fakten gehören in eine verschachtelte Anweisungsdatei oder eine pfadbezogene Regel. Frontend-Details in jede Backend-Aufgabe zu laden, verbraucht Kontext und erhöht die Wahrscheinlichkeit von Konflikten.
Wiederkehrende Fehler, keine hypothetischen
Füge eine Regel hinzu, wenn ein Agent denselben teuren Fehler wiederholt oder ein Review einen Fakt aufdeckt, den er vernünftigerweise nicht ableiten konnte. Entferne die Regel, wenn Repository oder Tooling sie überflüssig machen. So bleibt die Datei in beobachteten Fehlern verankert, statt spekulative Ratschläge anzuhäufen.
Was du weglassen solltest
- Generische Personas: „Du bist ein Senior Engineer“ wurde in diesen Studien nicht direkt untersucht, liefert aber weder eine überprüfbare Aktion noch einen Fakt über das Repository.
- Vage Ideale: „Befolge SOLID“ oder „schreib sauberen Code“ überlässt es dem Agenten, dieselbe Designentscheidung abzuleiten, die er ohnehin treffen wollte.
- Eine zweite README: Beschreibe nur Strukturen, die überraschend sind oder bestimmen, wohin eine Änderung gehört.
- Vollständige Abhängigkeitslisten: Das Manifest ist aktueller und für den Agenten leichter einzusehen.
- Einmalige Anforderungen an eine Aufgabe: Lass sie im Aufgaben-Prompt, damit sie keine fremden Sessions beeinflussen.
- Regeln, die Tooling durchsetzen kann: Formatter, Typchecks, Tests, Hooks und CI sind bei deterministischen Anforderungen stärker als Prosa.
- Secrets oder persönliche Zugangsdaten: Eine Anweisungsdatei ist gewöhnlicher Projektkontext, kein Secret-Speicher.
Eine kompakte Vorlage für den Einstieg
# Repository instructions
## Fast path
- Install: `pnpm install --frozen-lockfile`
- Focused tests: `pnpm test --filter <changed-package>`
- Full suite: `pnpm test` (about 20 minutes; run after focused tests pass)
## Verification
- Run `pnpm typecheck` after TypeScript changes.
- Add or update a focused test when behavior changes.
## Boundaries
- Do not edit `generated/`; run `pnpm generate` from the schema.
- Ask before adding production dependencies or changing migrations.
## Known traps
- Tests under `integration/` require the local database started with `pnpm db:up`.
- Package-specific instructions live in that package's nested `AGENTS.md`.
Ersetze jedes Beispiel durch einen Fakt aus dem echten Repository. Eine zehnzeilige, zutreffende Datei ist besser als eine umfassende Vorlage voller generischer Standardwerte.
Den kleinsten dauerhaften Mechanismus wählen
| Information | Bester Ort |
|---|---|
| Gilt für die meisten Aufgaben im Repository | AGENTS.md oder CLAUDE.md im Stammverzeichnis |
| Gilt nur für einen Teilbaum | Verschachtelte Anweisungsdatei oder pfadbezogene Regel |
| Persönliche Vorliebe über Repositorys hinweg | Anweisungsdatei auf Benutzerebene |
| Mehrstufiger Ablauf, der für bestimmte Aufgaben gebraucht wird | Ein Skill, der bei Bedarf geladen wird |
| Anforderung nur für diese Aufgabe | Der Aufgaben-Prompt |
| Regel, die immer ausgeführt werden muss | Test, Formatter, Hook, Richtlinie oder CI |
Wie du Abläufe für den Bedarfsfall agentenübergreifend installierst und pflegst, zeigt die praktische skills.sh-Anleitung. Eine Anweisungsdatei sollte nicht zum Ersatz für alle anderen Steuerungsmöglichkeiten werden.
Die Datei im eigenen Repository bewerten
Durchschnittswerte aus der Forschung sagen dir nicht, ob eine bestimmte Anweisung deiner Codebasis hilft. Wähle eine wiederholbare Aufgabe, bei der die Anweisung das Verhalten ändern sollte, und führe dann mehrere Durchläufe mit und ohne sie aus, mit demselben Agenten und derselben Modellversion. Erfasse:
- Ergebnisse verborgener oder unabhängig geschriebener Tests;
- Aufrufe gezielter Tests und der vollständigen Suite;
- verstrichene Zeit und Token-Verbrauch;
- unnötige Dateiänderungen und Berechtigungsanfragen;
- ob der Agent die konkrete Regel befolgt hat.
Behalte eine Anweisung, wenn sie ein Ergebnis verbessert oder messbare Verschwendung verhindert. Schreib sie um oder entferne sie, wenn sie ignoriert wird, doppelt vorhanden oder veraltet ist oder den Prompt bloß länger macht. Das Ziel ist nicht die perfekte Kontextdatei, sondern eine kleine Menge von Fakten über das Repository, die die Arbeit zuverlässig verbessert.
Häufige Fragen
Machen AGENTS.md und CLAUDE.md Coding-Agenten treffsicherer?
Nach aktuellem Forschungsstand nicht verlässlich. Neuere Studien finden gemischte Effekte auf die Effizienz und kaum oder keine generelle Verbesserung bei der Korrektheit der Aufgaben. Konkrete betriebliche Anweisungen können trotzdem unnötige Befehle, Zeit und Tokens sparen.
Kann Claude Code eine vorhandene AGENTS.md nutzen?
Wie lang sollte eine AGENTS.md oder CLAUDE.md sein?
Halte die Datei im Stammverzeichnis so kurz, wie es das Repository erlaubt. Anthropic empfiehlt derzeit weniger als 200 Zeilen pro CLAUDE.md. Codex hat standardmäßig ein Limit von 32 KiB für seine gesamte Anweisungskette, doch das ist eine Obergrenze und kein Ziel beim Schreiben.