AGENTS.md und CLAUDE.md: Eine Config-Datei schreiben, die der Agent wirklich nutzt

Eine gute Config-Datei schreiben ist der wirkungsvollste und gleichzeitig aufwandsärmste Schritt beim agentischen Programmieren. Du setzt den Kontext einmalig auf, und jede Session profitiert davon: Der Agent hört auf, deinen Test-Befehl zu raten, hört auf, nach seinen eigenen Defaults umzuformatieren, hört auf, das eine Verzeichnis zu bearbeiten, das du für tabu erklärt hast. Diese Seite zeigt die konkrete Praxis hinter der AI-Native „Context & Configuration"-Skill — einer der 17 AI-native Skills, die wir über die Levels hinweg bewerten. Dauerhaftes Projektgedächtnis in CLAUDE.md / AGENTS.md zu pflegen ist ein definierendes Merkmal eines Level-3-Agentic-Developers — es lohnt sich also, das richtig zu machen.

Der Kerngedanke ist bei allen Tools derselbe, auch wenn die Mechanik variiert: Eine Config-Datei trägt das, was ein Agent nicht selbst aus dem Code erschließen kann. Das Modell kennt deine Programmiersprache bereits. Es weiß nicht, dass deine Tests einen bestimmten Flag benötigen, dass du vor drei Monaten eine Bibliothek abgelöst hast, oder dass infra/ generiert ist und nie manuell bearbeitet werden darf. Diese Lücke füllt die Datei.

Die Landschaft: eine Philosophie, viele Dateien

Jeder große Agent liest eine Projekt-Kontext-Datei. Sie teilen eine Philosophie, unterscheiden sich aber in Dateiname und Lademechanismus. Hier die Übersicht für 2026:

File	Tool(s)	Status
AGENTS.md	OpenAI Codex, Cursor, GitHub Copilot agent, + ~20 Tools	Offener, Tool-übergreifender Standard
CLAUDE.md	Claude Code	Natives Format von Claude Code
GEMINI.md	Gemini CLI	Natives Format von Gemini
.github/copilot-instructions.md	GitHub Copilot	Repo-Anweisungen für Copilot
.cursor/rules (ehemals .cursorrules)	Cursor	Regelformat von Cursor

Das Fazit: AGENTS.md ist der entstehende zentrale Standard — eine offene Spezifikation, die bereits ~20 Tools lesen. Der Haken: Claude Code liest AGENTS.md nicht nativ; es liest ausschließlich CLAUDE.md. Deshalb ist das kanonische Single-Source-of-Truth-Muster: AGENTS.md als Master führen und Claude per minimalem CLAUDE.md-Import einbinden:

@AGENTS.md

<!-- Claude-spezifische Hinweise können hier folgen -->

Ein Symlink funktioniert ebenfalls (ln -s AGENTS.md CLAUDE.md), aber unter Windows ist der @import vorzuziehen — Symlinks benötigen dort Adminrechte. So pflegst du eine einzige Datei, und beide Ökosysteme lesen sie.

Was konkret hineingehört

GitHubs Analyse von über 2.500 Repositories („How to write a great AGENTS.md") hat ergeben, dass die Configs, die Agenten messbar besser machen, sechs Abschnitte gemeinsam haben. In grober Prioritätsreihenfolge:

1. Commands — früh platziert, mit genauen ausführbaren Befehlen und Flags (npm test, npm run build, pytest -v), nicht nur Tool-Namen. Das ist der Abschnitt mit dem höchsten ROI: Agenten wissen bereits, dass pytest existiert; sie wissen nicht, welche Flags dein Projekt erfordert. Platziere ihn ganz oben.
2. Testpraktiken — wie du testest, was vor einem Commit laufen soll, Coverage-Erwartungen.
3. Projektstruktur — wo was liegt, damit der Agent nicht suchen muss.
4. Code-Style — zeig ein echtes Code-Snippet, keine drei Absätze Prosa.
5. Git-Workflow — Branch-Naming, Commit-Konventionen, PR-Regeln.
6. Grenzen — was der Agent niemals anfassen darf (generierte Verzeichnisse, Secrets, Vendor-Code, Migrations).

Beachte die Reihenfolge nach Wirkung. „Befehle mit Flags" steht aus gutem Grund an erster Stelle: Das ist das Einzige, was das Modell am zuverlässigsten nicht erraten kann und am häufigsten falsch macht. Wenn du sonst nichts sauber schreibst, schreib das.

Aufnehmen / Weglassen: der Zeile-für-Zeile-Test

Anthropics Memory-Dokumentation zieht eine klare Zwei-Spalten-Grenze. Nutze sie als Filter für jede Zeile, die du hinzufügen möchtest.

Aufnehmen	Weglassen
Bash-Befehle, die der Agent nicht erraten kann	Alles, was sich aus dem Code ableiten lässt
Code-Style-Regeln, die vom Standard abweichen	Sprachkonventionen, die das Modell bereits kennt
Testanweisungen / bevorzugter Test-Runner	Ausführliche API-Docs (stattdessen verlinken)
Repo-Etikette (Branch-Naming, PR-Konventionen)	Häufig wechselnde Informationen
Projektspezifische Architekturentscheidungen	Lange Erklärungen und Tutorials
Dev-Env-Besonderheiten (erforderliche Env-Variablen)	Datei-für-Datei-Beschreibungen der Codebasis
Nicht-offensichtliche Fallstricke	Selbstverständlichkeiten wie „schreibe sauberen Code"

Es gibt einen Test, der die gesamte Tabelle auf eine Gewohnheit reduziert:

Der Zeile-für-Zeile-Test: „Würde das Entfernen dieser Zeile den Agenten zu Fehlern verleiten? Wenn nicht, streiche sie."

Wende diesen Test auf jede Zeile an. „Use TypeScript" — der Agent sieht die .ts-Dateien; streichen. „Führe Datenbankmigrationen mit npm run db:migrate aus, bearbeite migrations/ niemals manuell" — das konnte er nicht erraten, und ein Fehler korrumpiert den Zustand; behalten.

Auf der richtigen Abstraktionsebene schreiben

Anthropics Guidance zum Context Engineering destilliert gutes Schreiben auf vier Prinzipien.

1. Konkretheit / Überprüfbarkeit. Schreibe Regeln so präzise, dass du sie am Output des Agenten überprüfen kannst. Vage Vorgaben lassen sich nicht verifizieren — also werden sie nicht zuverlässig befolgt.

• „2-Space-Einrückung" — nicht „Code sauber formatieren."
• „npm test vor jedem Commit ausführen" — nicht „Deine Änderungen testen."
• „API-Handler liegen in src/api/handlers/" — nicht „Dateien ordentlich ablegen."

2. Right altitude. Ziel ist der Bereich zwischen starrem Hardcoding und vagem Handwedeln: „konkret genug, um Verhalten zu lenken, flexibel genug, um eine starke Heuristik zu sein." Zu rigide bricht es beim ersten Randfall; zu vage lenkt es gar nichts.

3. Minimal-aber-ausreichend. Minimal bedeutet nicht kurz. Es bedeutet: genug Kontext vorab liefern, damit der Agent nicht raten oder neu entdecken muss — und nichts darüber hinaus. Füller streichen, tragende Details behalten.

4. Struktur. Verwende beschriftete Abschnitte — Markdown-Überschriften oder XML-Tags. Eine scannbare Datei ist eine Datei, die der Agent (und deine Teamkollegen) tatsächlich verarbeiten.

Schlank halten

Der eigentliche Grund für Schlankheit ist das Token-Budget. Die Config-Datei wird vollständig bei jeder einzelnen Session geladen. Sie wird nicht bei Bedarf abgerufen; sie wird beim Start dem Kontext vorangestellt. Daher hat Aufblähung direkte, messbare Kosten: Eine aufgeblähte CLAUDE.md reduziert die Befolgung von Anweisungen messbar. Anthropics eigene Formulierung ist direkt — aufgeblähte CLAUDE.md-Dateien veranlassen Claude, deine eigentlichen Anweisungen zu ignorieren. Jede unnötige Zeile, die du hinzufügst, schwächt deine guten Zeilen.

Die Zielwerte sind konkret:

• Anthropic empfiehlt unter ~200 Zeilen als Richtwert für CLAUDE.md.
• Codex erzwingt ein hartes 32-KiB-Limit für AGENTS.md (project_doc_max_bytes); zu große Dateien werden abgeschnitten, alles dahinter wird stillschweigend nicht geladen.

Und eine Falle, die es wert ist, benannt zu werden: Imports sparen kein Budget. Eine per @import eingebundene Datei wird beim Start trotzdem in den Kontext geladen — du hast die Datei aufgeteilt, nicht den Fußabdruck verkleinert. Um tatsächlich zu reduzieren, was jede Session lädt, verlagere bedingt relevante Inhalte:

• Path-scoped rules für übergreifende Belange, die viele Dateien betreffen — sie laden nur, wenn der Agent in diesem Pfad arbeitet.
• Skills für bedarfsgesteuerte Verfahren — sie laden nur bei Aufruf.
• Links für lange oder detaillierte Referenzmaterialien — verweise darauf, anstatt es einzufügen.

Das Prinzip ist dasselbe, das der Zeile-für-Zeile-Test auf Abschnittsebene anwendet: Wenn etwas nur manchmal relevant ist, gehört es nicht in die immer geladene Datei.

DESIGN.md: eine Team-Konvention, kein Standard

Eine DESIGN.md ist die Lehrbuch-Anwendung von „Config schlank halten, Details verlinken." Es ist ein separates Design-/Architekturdokument — die Schlüsselentscheidungen, das Domänenmodell, die Architekturmuster, das Warum dieser Aufbau — das deine AGENTS.md per @import einbindet oder referenziert, anstatt es einzufügen. So bleibt die immer geladene Config kurz, während der tiefe Kontext nur einen Hop entfernt bleibt.

Sei jedoch ehrlich über seinen Status: Anders als AGENTS.md und CLAUDE.md gibt es keine primäre Quelle, die DESIGN.md als Standard-Agent-Config-Datei etabliert. Es ist eine nützliche Team-Konvention, kein dokumentierter Standard. Nutze sie, weil sie für dein Team funktioniert — nicht weil eine Spezifikation es vorschreibt.

Scope & Hierarchie

Beide Ökosysteme schichten Dateien von allgemein nach spezifisch, lösen die Prioritäten aber unterschiedlich auf.

CLAUDE.md hat vier Scopes, Laden von allgemein → spezifisch:

1. Managed Policy — von deiner Organisation / IT gesetzt, gilt organisationsweit.
2. User — ~/.claude/CLAUDE.md, gilt für alle deine Projekte.
3. Project — ./CLAUDE.md, ins Git eingecheckt und mit dem Team geteilt.
4. Local — ./CLAUDE.local.md, per gitignore ausgeschlossen, für persönliche Overrides.

In Monorepos laden Dateien aus übergeordneten Verzeichnissen automatisch; Dateien in Unterverzeichnissen laden bei Bedarf. Imports verwenden die Syntax @path/to/file (relativ oder absolut), verschachteln sich bis zu 4 Hops tief, und der Parser überspringt Code-Blöcke, sodass ein Pfad innerhalb eines Fenced Blocks nicht als Import interpretiert wird.

AGENTS.md löst nach Nähe auf. Codex läuft vom Git-Root abwärts bis zu deinem aktuellen Arbeitsverzeichnis und verkettet die gefundenen Dateien, Root zuerst. Da nähere Dateien später erscheinen, überschreiben sie — die nächste Datei gewinnt. In einem Monorepo hältst du eine AGENTS.md pro Paket, und die dem bearbeiteten Code nächstgelegene hat Vorrang. Über allem: Eine explizite Anweisung im Chat überschreibt jede Datei.

Und die Tool-übergreifende Brücke von vorhin verbindet die beiden Systeme: AGENTS.md als Master führen, eine CLAUDE.md hinzufügen, die @AGENTS.md enthält — und die Hierarchie ist ohne Duplikation über alle Tools hinweg geteilt.

Richtunggebend, nicht erzwingend

Hier ist die Nuance, die dich vor einem falschen Sicherheitsgefühl bewahrt: Diese Dateien sind richtungsgebender Kontext, keine deterministische Durchsetzung. Sie lenken den Agenten; sie binden ihn nicht.

Betonungswörter wie IMPORTANT und YOU MUST verbessern die Befolgung messbar — garantieren sie aber nicht. Für Anforderungen, die jedes einzelne Mal eingehalten werden müssen (Formatter ausführen, Commit bei fehlgeschlagenen Tests blockieren, nie auf main schreiben), ist das deterministische Sicherheitsnetz hooks (in Claude Code) — nicht stärkere Formulierungen in der Config.

Die Faustregel: Nutze die Config für Guidance und Heuristiken; greife zu hooks, sobald „der Agent macht das meistens" nicht mehr ausreicht und du „der Agent macht das immer" brauchst.

Pflegen wie Code

Eine Config-Datei ist ein lebendes Artefakt, kein einmaliger Write. Behandle sie so wie den Rest des Repos.

• Bootstrap mit /init. Lass das Tool einen ersten Entwurf aus deiner Codebasis generieren, dann verfeinere ihn manuell — die generierte Version ist ein Startpunkt, nicht die fertige Datei.
• Überprüfen, wenn etwas schiefläuft. Jedes Mal, wenn der Agent etwas Dummes tut, frage dich, ob eine fehlende oder irreführende Zeile in der Config die Ursache war.
• Regelmäßig kürzen. Wende den Zeile-für-Zeile-Test auf die gesamte Datei an. Zeilen, die letztes Quartal unverzichtbar waren, können jetzt totes Gewicht sein.
• Änderungen am Verhalten messen. Vertraue nicht darauf, dass eine Änderung geholfen hat — beobachte, ob sich das Verhalten des Agenten tatsächlich verändert hat. Wenn du keinen Unterschied siehst, leistet die Zeile wahrscheinlich keine Arbeit.
• In Git einchecken. Eine geteilte, versionskontrollierte Config bedeutet, dass das gesamte Team beiträgt und davon profitiert, und Änderungen tauchen im Review auf.

Die wertvollste Gewohnheit ist die selbstverbessernde Schleife: Wenn der Agent einen Fehler macht, füge eine einzige einzeilige Regel hinzu, damit er sich nicht wiederholt. Über einige Wochen konvergiert diese Schleife deine Config genau auf die Fallstricke, die dein Projekt tatsächlich hat — nicht mehr, nicht weniger.

Ein AGENTS.md-Starter-Template

Hier ist ein einsatzbereites Skeleton mit allen sechs High-ROI-Abschnitten, gefüllt mit realistischen Platzhaltern. Tausche deine Spezifika ein und lösche alles, was den Zeile-für-Zeile-Test nicht besteht.

# AGENTS.md

## Commands
- Install: `npm ci`
- Dev server: `npm run dev`
- Test (all): `npm test`
- Test (single file): `npm test -- path/to/file.test.ts`
- Lint + autofix: `npm run lint -- --fix`
- Typecheck: `npm run typecheck`
- Build: `npm run build`

## Testing
- Run `npm test` and `npm run typecheck` before every commit.
- New code needs a test in the matching `*.test.ts` file.
- Integration tests need a running DB: `npm run db:up` first.

## Project structure
- `src/api/handlers/` — HTTP route handlers
- `src/services/` — business logic (no HTTP/DB code here)
- `src/db/` — schema + queries; migrations in `src/db/migrations/`
- `web/` — React frontend (separate AGENTS.md inside)

## Code style
- 2-space indentation, single quotes, no default exports.
- Throw typed errors from `src/errors.ts`, never bare `Error`.
```ts
// Good: typed error, narrow return
export async function getUser(id: string): Promise<User> {
  const user = await db.users.find(id);
  if (!user) throw new NotFoundError('user', id);
  return user;
}

Git workflow

• Branch from main: feature/<short-desc> or fix/<short-desc>.
• Conventional Commits (feat:, fix:, chore:).
• Open a PR; never push directly to main.

Boundaries

• NEVER edit src/db/migrations/ by hand — generate with npm run db:migrate:new.
• NEVER touch dist/, node_modules/, or *.generated.ts (all generated).
• NEVER commit secrets; required env vars are documented in .env.example.

Für eine einzige Wahrheitsquelle über alle Tools hinweg lege eine einzeilige `CLAUDE.md` daneben, die `@AGENTS.md` enthält, und verlinke tiefergehende Architekturnotes (eine `DESIGN.md`, deine ADRs) statt sie einzufügen.

## Wie geht es weiter?

Eine schlanke, präzise Config-Datei ist eines der konkreten Verhaltensweisen, die KI-unterstützte Entwickler von echten AI-Native-Entwicklern unterscheiden. [Finde dein AI-Native-Level](/quiz) in drei Minuten — es bewertet genau diese Art von Handwerk — und wenn du bereit bist, deine Toolchain zu verdrahten, starte mit [dem empfohlenen ProCoders Stack](/stack).