AGENTS.md und CLAUDE.md schreiben: was 100 Top-Repos tun

Wofür AGENTS.md und CLAUDE.md da sind

Ein Coding-Agent beginnt jede Sitzung, ohne das Projekt zu kennen. In der Regeldatei schreiben Sie einmal auf, was Sie sonst jedes Mal neu erklären würden: Build- und Testbefehle, Coderegeln, die Verzeichnisstruktur und alles, was auf keinen Fall passieren darf. Dieser Beitrag zeigt, wie man diese Datei schreibt: welchen Namen sie bekommt, was hineingehört und wie lang sie sein sollte.

AGENTS.md gehört keinem einzelnen Tool. Es ist ein offenes Format, das die Agentic AI Foundation unter dem Dach der Linux Foundation betreut; laut der eigenen Website nutzen es mehr als 60.000 Open-Source-Projekte. Es ist eine einfache Markdown-Datei ohne Pflichtfelder. CLAUDE.md dagegen ist die Datei, die Claude Code zu Beginn jeder Sitzung liest. Auch sie ist einfaches Markdown, bringt aber eigene Funktionen mit: Sie kann andere Dateien importieren (@pfad) und eigene Ebenen für Benutzer oder Organisation haben.

Wir bauen ein Tool, das diese Dateien jeden Tag liest: Wenn diffox einen Pull Request prüft, liest es auch die Regeldatei des Repositorys (wie das funktioniert, steht in einem eigenen Beitrag). Die folgenden Messungen sind ein Nebenprodukt dieser Arbeit.

Welches Tool welche Datei liest

Die folgende Tabelle haben wir am 13. Oktober 2026 aus der Dokumentation der fünf Tools zusammengestellt. Mit neuen Versionen kann sich das ändern; jeder Toolname verlinkt auf seine Quelle.

Quelle: die eigene Dokumentation jedes Tools, 13. Oktober 2026. Die Zeile zu Claude Code gilt für Version 2.1.277 und neuer.

Die Tabelle zeigt zweierlei. Erstens können alle fünf Tools AGENTS.md lesen: Gemini CLI mit einer Einstellung, Claude Code nur, wenn keine CLAUDE.md daneben liegt. Zweitens geht jedes Tool anders mit Unterordnern um: Codex führt alles vom Stammverzeichnis abwärts zusammen, Copilot nimmt die nächstgelegene Datei, und Claude Code lädt die Datei eines Unterordners erst, wenn Sie dort eine Datei öffnen.

Google hat Gemini CLI am 18. Juni 2026 für kostenlose Nutzer sowie für Abonnenten von Google AI Pro und Ultra eingestellt und sie auf Antigravity CLI verwiesen; mit einem kostenpflichtigen API-Schlüssel oder einer Firmenlizenz können Sie Gemini CLI weiter nutzen. Die Regel-Dokumentation von Antigravity haben wir am 28. Oktober 2026 gelesen. Antigravity liest eine Datei namens AGENTS.md oder GEMINI.md ganz ohne Einstellung. Die Datei eines Unterordners lädt es, sobald der Agent in diesem Ordner eine Datei liest oder bearbeitet. Die gefundenen Dateien führt es zusammen; widersprechen sich Regeln, gilt die aus dem Unterordner. Pro Datei liegt die Grenze bei 24 KB. CLAUDE.md ist nicht unter den Dateien, die die Dokumentation aufzählt; stehen Ihre Regeln in AGENTS.md, liest Antigravity sie ebenfalls.

AGENTS.md ist verbreiteter als CLAUDE.md

Um zu sehen, welche Datei verbreiteter ist, haben wir die Repositories nach einer einzigen Regel ausgewählt: die 100 GitHub-Repositories mit den meisten Sternen, am 13. Oktober 2026. Ein großer Teil der Liste ist keine Software, die gebaut wird (Linksammlungen, Bücher, Kurse). Wir haben sie ausgewählt, ohne darauf zu achten, ob sie eine Regeldatei haben, und die Liste deshalb so gelassen, wie sie ist.

In 47 der 100 Repositories liegt im Stammverzeichnis mindestens eine dieser beiden Dateien. 42 Repositories haben AGENTS.md, 24 haben CLAUDE.md; 5 davon haben nur CLAUDE.md. Die Dateien der anderen Tools sind seltener: die von Copilot in 11 Repositories, der Regelordner von Cursor in 4, GEMINI.md in 3. Die alte Datei .cursorrules findet sich noch in 1 der 100 Repositories; .windsurfrules und .clinerules kommen in keinem vor.

Zählt man die Dateien in Unterordnern und die der anderen Tools mit, haben 55 Repositories mindestens eine dieser Dateien.

Gibt es beide Dateien, liest Claude Code nur CLAUDE.md

Hier liegt der häufigste Irrtum. Claude Code hat AGENTS.md lange gar nicht gelesen, und viele Quellen schreiben das bis heute. Seit Version 2.1.277 liest es die Datei, aber nur unter einer Bedingung: Weder im Arbeitsverzeichnis noch in den Verzeichnissen darüber darf eine CLAUDE.md (oder CLAUDE.local.md) liegen. Gibt es beide, liest Claude Code standardmäßig nur CLAUDE.md.

In der Praxis heißt das: Liegt eine CLAUDE.md daneben, erreicht eine Regel, die Sie in AGENTS.md ergänzen, Claude Code nicht. Codex dagegen liest standardmäßig nur AGENTS.md. Dann müssen Sie beide Dateien von Hand synchron halten.

Eine CLAUDE.local.md, die Sie für persönliche Notizen anlegen, hat dieselbe Wirkung: Solange sie existiert, liest Claude Code AGENTS.md nicht. Damit beide gelesen werden, setzen Sie in /config die Einstellung „Project instructions“ auf claude-md-and-agents-md.

In 19 der 100 Repositories liegen beide Dateien zusammen im Stammverzeichnis. Wir haben uns einzeln angesehen, wie diese Repositories die beiden Dateien verbinden.

8 Repositories lassen CLAUDE.md direkt auf AGENTS.md zeigen: 5 davon, indem sie @AGENTS.md in CLAUDE.md schreiben, 3 mit einem symbolischen Link. Bei n8n, AutoGPT, RustDesk und Clash Verge Rev besteht CLAUDE.md aus einer einzigen Zeile. In 2 Repositories verweist CLAUDE.md mit einem einfachen Satz auf AGENTS.md; laut der Dokumentation von Claude Code sieht der Agent diese Datei nur, wenn er beschließt, sie zu öffnen. 3 Repositories pflegen denselben Text in beiden Dateien, und in 1 davon haben die beiden Kopien nicht mehr gleich viele Regeln. In den übrigen 6 Repositories stehen in den beiden Dateien verschiedene Texte: Dort lesen Claude Code und Codex im selben Projekt unterschiedliche Anweisungen.

Zwei Wege, CLAUDE.md auf AGENTS.md zeigen zu lassen

Auch die Daten sprechen dafür: Halten Sie die Regeln in einer Datei und lassen Sie die andere darauf verweisen. Der eigentliche Text gehört in AGENTS.md, weil mehr Tools sie lesen. Legen Sie diese CLAUDE.md daneben:

@AGENTS.md

## Claude Code
Hinweise nur für Claude Code kommen hierher.

Die Importzeile lädt AGENTS.md als Teil von CLAUDE.md; darunter stehen nur Hinweise, die allein Claude Code betreffen. Haben Sie keine solchen Hinweise, tut es auch ein symbolischer Link: ln -s AGENTS.md CLAUDE.md.

Der symbolische Link hat zwei Haken. Wer das Repository unter Windows klont, sieht statt des Links unter Umständen eine einzeilige Textdatei. Außerdem weigert sich Claude Code, über den Link zu schreiben, und bearbeitet stattdessen die eigentliche Datei. Nutzt jemand im Team Windows, ist die Importzeile die sicherere Wahl.

Inzwischen reicht auch AGENTS.md allein, denn aktuelle Versionen von Claude Code lesen sie direkt. Die einzeilige CLAUDE.md für ältere Versionen stehen zu lassen, schadet nicht: Claude Code lädt dieselbe Datei nicht zweimal.

Was beliebte Repositories in die Datei schreiben

Um zu sehen, was in den Dateien steht, haben wir uns die Überschriften der 47 gelesenen Dateien angesehen. Hat eine Datei einem Thema eine eigene Überschrift gegeben, zählt sie für dieses Thema.

Das häufigste Thema sind Regeln für Commits und Pull Requests (29 Dateien). Danach folgen Befehle für Installation und Ausführung (26), Codestil (26), Verzeichnisstruktur (21), Tests (16) und Sicherheit (7). Unabhängig von den Überschriften enthalten 36 der 47 Dateien einen Befehl, im Codeblock oder im Fließtext. Die Zählung stützt sich nur auf die Wörter in den Überschriften und ist daher grob, aber die Reihenfolge ist eindeutig: Der Agent will zuerst wissen, was er wie ausführt und wie er eine Änderung abliefert.

Zwei gute Beispiele von Kubernetes und AutoGPT

Beide Beispiele stammen aus den Dateien dieser Zählung. Die AGENTS.md von Kubernetes hat 38 Zeilen. Jede Regel sagt, was man nicht tun soll und was man stattdessen tut; neben jedem Befehl steht, wofür er da ist:

## Constraints

- **Generated files are read-only.** Never hand-edit `zz_generated.*` or `generated.pb.go`. Run `make update`.
- **go.mod/go.work are generated.** Use `hack/pin-dependency.sh` + `hack/update-vendor.sh`. Never `go mod tidy`.
…
## Commands

Run `make help` for all available targets. Common workflows:

```
make test WHAT=./pkg/kubelet GOFLAGS=-v     # Unit tests (one package)
make test-integration WHAT=./test/integration/scheduler
make verify                                 # All verification checks
make update                                 # ALL generators and formatters
```

Die AGENTS.md von AutoGPT hat 92 Zeilen; sie beschreibt die Verzeichnisstruktur, den Testbefehl jedes Teils und messbare Regeln für Pull Requests. Die CLAUDE.md des Projekts besteht dagegen nur aus der Zeile @AGENTS.md: die Verknüpfung, die wir oben empfohlen haben.

## Testing

- Backend: `poetry run test` (runs pytest with a docker based postgres + prisma).
- Frontend integration tests: `pnpm test:unit` (Vitest + RTL + MSW, primary testing approach).
…
## Pull requests

…
- Keep out-of-scope changes under 20% of the PR.

Beide Dateien sind in Sätzen geschrieben, die ein Agent ebenso prüfen kann wie ein Mensch: „generierte Dateien nicht von Hand bearbeiten, make update ausführen“ oder „Änderungen außerhalb des Umfangs sollen ein Fünftel des Pull Requests nicht überschreiten“. Die Zitate stammen aus dem Commit, den die Zählung gelesen hat; „…“ markiert ausgelassene Zeilen.

Eine AGENTS.md-Vorlage für den Anfang

Ein kurzes AGENTS.md-Gerüst aus den Überschriften, die beliebte Repositories am häufigsten anlegen, und aus den beiden Beispielen oben. Es ist nur ein Beispiel; wir haben es auf Englisch geschrieben, weil die Agenten, die diese Dateien lesen, und die meisten Teams auf Englisch arbeiten. Ersetzen Sie Befehle und Pfade durch die Ihres Projekts:

# Project name

## Commands
- Install: `pnpm install`
- Test one package: `pnpm test --filter api`
- Lint and format: `pnpm lint && pnpm format`

## Project structure
- `apps/web` - Next.js front end
- `packages/api` - API service

## Code style
- TypeScript strict mode. Never use `any`; use `unknown`.

## Testing
- Add or update the test that covers your change.

## Commits and pull requests
- Conventional commits: `feat(api): ...`
- Keep unrelated changes out of the pull request.

## Never
- Never hand-edit files under `generated/`. Run `pnpm generate`.
- Never commit secrets; read them from the environment.

Wenn Sie Claude Code nutzen, legen Sie die einzeilige CLAUDE.md daneben: @AGENTS.md. Jede Zeile der Vorlage ist ein Befehl oder eine prüfbare Regel; zu erklären, was das Projekt tut, ist Aufgabe der README.

So schreiben Sie eine gute Regel

Der nützlichste Maßstab dafür, was in die Datei gehört, steht in der Dokumentation von Claude Code: Eine Anweisung soll so konkret sein, dass sie sich überprüfen lässt. „2 Leerzeichen Einrückung verwenden“ statt „Code ordentlich formatieren“; „vor dem Commit npm test ausführen“ statt „Änderungen testen“. Die folgenden sechs Punkte verbinden diesen Maßstab mit dem, was wir beim Schreiben unserer eigenen Datei gelernt haben:

• Sagen Sie, was zu tun ist. Ein Satz, der „mach das“ oder „mach das nie“ sagt, lässt sich prüfen; eine Projektbeschreibung nicht. 3 der 47 gelesenen Dateien enthalten keinen einzigen solchen Satz; im Median enthält eine Datei 10.
• Schreiben Sie den genauen Befehl hin. Aus „Tests ausführen“ kann der Agent nicht ableiten, welchen Befehl Sie meinen; schreiben Sie pnpm test --filter api, führt er genau diesen aus.
• Schreiben Sie den Grund neben die Regel. In unserer eigenen Datei steht neben jeder Regel der Fehler, der sie nötig gemacht hat. Eine Regel ohne Grund löscht der Erste, den sie stört.
• Lassen Sie weg, was Ihre Tools ohnehin prüfen. Eine Regel, die Formatter und Linter schon durchsetzen, kostet in der Datei nur Zeilen; je länger die Datei, desto schlechter werden die Anweisungen befolgt.
• Schreiben Sie jede Regel nur an eine Stelle. Steht dieselbe Regel in zwei Dateien, veraltet eine davon, und zwar die, die am wenigsten gelesen wird.
• Ergänzen Sie Regeln, wenn ein Fehler wiederkehrt, und löschen Sie sie, wenn sie nicht mehr gelten. Schreiben Sie die Regel, wenn der Agent denselben Fehler zum zweiten Mal macht. In Claude Code listet /doctor prompt-audit veraltete und widersprüchliche Anweisungen auf.

Für diffox ist der erste dieser Punkte direkt wichtig. Wenn diffox einen Pull Request prüft, liest es die Regeldatei im Stammverzeichnis des Repositorys: zuerst AGENTS.md, sonst CLAUDE.md. Einem symbolischen Link und der Zeile @AGENTS.md folgt es dabei. Die Sätze, die sagen, was zu tun ist, gibt es den spezialisierten Agenten als Review-Regeln mit. Eine prüfbare Regel hilft also auch dem Review.

Die meisten Regeldateien bleiben unter 200 Zeilen

Zur Länge nennt die Dokumentation von drei Tools drei verschiedene Grenzen. Claude Code peilt weniger als 200 Zeilen pro Datei an, weil eine lange Datei mehr Kontext verbraucht und die Anweisungen schlechter befolgt werden. Cursor empfiehlt weniger als 500 Zeilen pro Regel. Codex hört auf, Dateien anzuhängen, sobald ihre Summe 32 KiB erreicht.

Der Median der 47 gelesenen Dateien liegt bei 92 Zeilen; die kürzeste hat 4, die längste 1.017 Zeilen. 14 überschreiten 200 Zeilen, 2 überschreiten 500. Die Zahl der Dateien, die für sich allein die 32-KiB-Grenze von Codex überschreiten, beträgt 1.

Im Monorepo bekommt ein Unterordner seine eigene Regeldatei

Große Repositories bringen ihre Regeln nicht in einer Datei unter. In 27 der 98 Repositories, deren ganzen Baum wir lesen konnten, liegt auch in einem anderen Ordner als dem Stammverzeichnis eine AGENTS.md oder CLAUDE.md: insgesamt 278 Dateien.

Die Datei in einem Unterordner gilt für Änderungen in diesem Ordner: Die Regeln für das Frontend liegen im Frontend-Ordner, die für das Backend im Backend. Die Datei im Stammverzeichnis bleibt kurz, und der Agent lädt nur die Regeln des Bereichs, in dem er arbeitet.

Wie oft das greift, zeigt eine eigene Messung aus dem September 2026: In 17 Repositories mit einer Regeldatei in einem Unterordner änderten 202 der 417 zuletzt gemergten Pull Requests mindestens eine Datei in einem solchen Ordner.

Beachten Sie aber: Jedes Tool behandelt Unterordner anders. Schreiben Sie dasselbe Thema auf zwei Ebenen unterschiedlich, hängt es vom Tool ab, welcher Satz gilt. Lassen Sie keine Sätze stehen, die einander widersprechen.