---
title: "Was gehört in AGENTS.md und CLAUDE.md?"
seoTitle: "AGENTS.md und CLAUDE.md: was Agenten wirklich hilft"
navTitle: "AGENTS.md und CLAUDE.md"
description: "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."
slug: agents-md-claude-md-best-practices
lang: de
date: 2026-08-06
updated: 2026-08-06
author: "Chatcode"
category: guide
faq:
  - q: "Machen AGENTS.md und CLAUDE.md Coding-Agenten treffsicherer?"
    a: "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."
  - q: "Kann Claude Code eine vorhandene AGENTS.md nutzen?"
    a: "Standardmäßig lädt Claude Code AGENTS.md nicht direkt. Schreib `@AGENTS.md` in eine kleine CLAUDE.md, um die gemeinsamen Anweisungen zu importieren, und ergänze darunter nur wirklich Claude-spezifische Hinweise."
  - q: "Wie lang sollte eine AGENTS.md oder CLAUDE.md sein?"
    a: "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."
---

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:

1. Er gilt für den Großteil der Arbeit in diesem Bereich.
2. Der Agent kann ihn nicht schnell und zuverlässig aus dem Repository selbst
   herausfinden.
3. Wenn er befolgt wird, ändert sich eine beobachtbare Aktion oder Prüfung.

Gute Beispiele sind:

- `pnpm test --filter api` ist 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 über `pnpm generate` geä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](https://learn.chatgpt.com/docs/agent-configuration/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](https://code.claude.com/docs/en/memory).

Wenn ein Team beide Agenten nutzt, halte die gemeinsamen Anweisungen in
`AGENTS.md` und importiere sie aus einer kleinen `CLAUDE.md`:

```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?](https://arxiv.org/abs/2607.27250) 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.md` wurde 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](https://arxiv.org/abs/2601.20404)
  untersuchte 10 Repositorys und 124 Pull Requests. Das Vorhandensein von
  `AGENTS.md` ging mit einer um 28,64 % geringeren medianen Laufzeit und
  16,58 % weniger Ausgabe-Tokens einher, bei vergleichbarem
  Abschlussverhalten.
- [Evaluating AGENTS.md](https://arxiv.org/abs/2602.11988) 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:

```md
## 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:

```md
## 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

```md
# 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](/articles/skills-sh-install-skills-ai-coding-agents).
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.
