CLAUDE.md Best Practices (plus AGENTS.md, GEMINI.md)

Die beste CLAUDE.md ist kurz (deutlich unter 200 Zeilen), konkret und überprüfbar: die Befehle zum Bauen und Testen, die Konventionen, die der Agent nicht aus dem Code erraten kann, und die Fehler, die er schon einmal gemacht hat. Alles andere, etwa ein Rundgang durch den Ordnerbaum, lange Abläufe oder allgemeine Ratschläge wie „schreib sauberen Code“, gehört entweder woandershin oder gar nicht hinein.

Dieser Leitfaden behandelt, was CLAUDE.md, AGENTS.md und GEMINI.md sind, wo jeder Agent nach ihnen sucht, was du schreiben und was du weglassen solltest, wie Imports funktionieren und wie du eine Datei pflegst, die jeder Agent im Projekt liest.

Was diese Dateien sind

Coding-Agenten starten jede Session ohne Erinnerung an dein Projekt. Eine Anweisungsdatei ist die Notiz, die du ihnen hinterlässt: eine einfache Markdown-Datei, die die CLI beim Start liest und vor deiner ersten Nachricht dem Kontextfenster des Modells hinzufügt.

AGENTS.md entstand aus einer Zusammenarbeit von OpenAI Codex, Amp, Google Jules, Cursor und Factory und wird heute von der Agentic AI Foundation unter der Linux Foundation betreut. Es ist das, was einem gemeinsamen Standard am nächsten kommt. Claude Code hat seinen eigenen Namen behalten, aber neuere Versionen (ab v2.1.277) lesen AGENTS.md nativ, wenn im Arbeitsverzeichnis oder darüber keine CLAUDE.md oder CLAUDE.local.md liegt.

Wo die Dateien liegen

Alle drei Agenten folgen derselben Idee: eine globale Datei für dich, eine Projektdatei für das Team und optionale Dateien tiefer im Baum für einen Teil des Codes.

Claude Code

Dateien im Arbeitsverzeichnis und in den Verzeichnissen darüber werden beim Start geladen und aneinandergehängt, nicht überschrieben. Verschachtelte Dateien in Unterverzeichnissen werden bei Bedarf geladen, wenn Claude zum ersten Mal Dateien in diesem Ordner anfasst. Mit /context siehst du, welche Memory-Dateien tatsächlich geladen sind, und mit /memory öffnest du eine zum Bearbeiten.

Codex

Codex liest eine globale ~/.codex/AGENTS.md (oder AGENTS.override.md), geht dann vom Git-Root bis zum aktuellen Verzeichnis und nimmt pro Ordner eine Datei: AGENTS.override.md, falls vorhanden, sonst AGENTS.md. Tiefere Dateien stehen später im zusammengesetzten Text und gewinnen daher, wenn zwei Regeln kollidieren. Die Gesamtmenge ist durch project_doc_max_bytes begrenzt, standardmäßig 32 KiB, und die Kette wird einmal pro Session aufgebaut. Mehr zur CLI selbst auf der Codex-Seite.

Gemini CLI

Gemini CLI lädt ~/.gemini/GEMINI.md, dann die Dateien in deinen Workspace-Verzeichnissen und deren Elternverzeichnissen und holt weitere Dateien, wenn seine Tools andere Ordner besuchen. Alles wird aneinandergehängt und mit jedem Prompt gesendet. /memory show gibt den kombinierten Text aus, und /memory reload liest ihn nach deinen Änderungen neu ein.

Was hineingehört

Schreibe für einen fähigen neuen Teamkollegen, der das Repo nie gesehen hat und keine Fragen stellen wird. Jede Zeile sollte etwas sein, worauf der Agent reagieren kann und was du überprüfen kannst.

• Befehle. Wie man installiert, baut, einen Test ausführt, alle Tests ausführt, linted und Typen prüft. Das ist der nützlichste Abschnitt überhaupt; ohne ihn rät der Agent.
• Konventionen, die der Code nicht zeigt. „Nutze pnpm, nicht npm.“ „Neue API-Routen laufen über withAuth().“ „Datumswerte werden in UTC gespeichert.“
• Grenzen. „Bearbeite nie Dateien unter generated/.“ „Fasse den Migrations-Ordner nicht an, ohne zu fragen.“
• Wie man eine Aufgabe abschließt. „Führe pnpm test und pnpm typecheck aus, bevor du sagst, dass du fertig bist.“ „Commit-Nachrichten folgen Conventional Commits.“
• Bekannte Fallen. Der Fehler, den der Agent letzte Woche zweimal gemacht hat, als Regel formuliert.

Eine gute Regel ist konkret. „Nutze 2 Leerzeichen Einrückung“ funktioniert; „formatiere den Code ordentlich“ nicht. „Führe npm test vor dem Commit aus“ funktioniert; „stell sicher, dass alles läuft“ nicht.

Ein kompaktes Beispiel

# Project notes

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- One test: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Conventions
- TypeScript strict; no `any` in new code.
- Server code lives in `src/server`, UI in `src/ui`; never import server code from UI.
- Database access only through `src/server/db.ts`.

## Don’t
- Don’t edit `src/generated/` (run `pnpm codegen` instead).
- Don’t add dependencies without saying why in the summary.

## Learned the hard way
- The payments tests need `STRIPE_KEY=test`; they fail silently without it.

Das sind etwa 20 Zeilen, und sie decken das meiste ab, was ein Agent am ersten Tag braucht.

Was du weglassen solltest

Kurz halten

Jede Zeile in CLAUDE.md wird zu Beginn jeder Session gesendet und bleibt für das ganze Gespräch im Kontext. Die Doku von Anthropic empfiehlt, unter 200 Zeilen pro Datei zu bleiben, und merkt an, dass längere Dateien die Zuverlässigkeit senken, mit der Claude sie befolgt. Das Muster ist bekannt: Je mehr Regeln, desto mehr verwässert jede einzelne.

Einige Gewohnheiten helfen:

• Füge eine Regel nur hinzu, wenn du sie brauchst. Der Agent hat denselben Fehler zweimal gemacht, ein Review hat etwas gefunden oder du tippst immer wieder dieselbe Korrektur. Das ist das Signal.
• Räume beim Hinzufügen auf. Wenn eine Regel einen Monat lang keine Rolle gespielt hat, streiche sie.
• Bevorzuge Verweise statt Einfügen. „Der Release-Prozess steht in docs/release.md“ kostet eine Zeile; den Prozess einzufügen kostet fünfzig.
• Nutze HTML-Kommentare für Notizen an Menschen. Claude Code entfernt Block-Kommentare der Form <!-- -->, bevor es die Datei sendet.

Wenn dich die Token-Kosten beschäftigen, geht der Leitfaden zum Token-Verbrauch von Claude Code darauf ein, was den Kontext sonst noch füllt.

Imports und pfadbezogene Regeln

Claude Code lässt eine CLAUDE.md mit @path andere Dateien einbinden:

See @README.md for the overview.
Coding rules: @docs/conventions.md
@~/.claude/my-preferences.md

Pfade sind relativ zur Datei, die den Import enthält, Imports können bis zu vier Ebenen tief verschachtelt werden, und @ in Code-Spans oder Codeblöcken wird ignoriert. Wenn ein Projekt zum ersten Mal Dateien von außerhalb des Repos importiert, bittet Claude Code dich, sie freizugeben.

Ein Haken: Imports ordnen den Text, sparen aber keine Tokens. Eine importierte Datei wird beim Start vollständig geladen, genau wie die übergeordnete. Für Regeln, die nur in einem Teil des Baums zählen, nutze .claude/rules/*.md mit einem paths:-Glob im Frontmatter, damit sie nur geladen werden, wenn Claude an passenden Dateien arbeitet:

---
paths: ["src/api/**/*.ts"]
---
- Every handler validates input with zod before touching the database.

Gemini CLI unterstützt in GEMINI.md dieselbe @file.md-Import-Syntax.

Eine Datei für jeden Agenten

Nutzt dein Team mehr als eine CLI, laufen drei Dateien mit denselben Regeln unweigerlich auseinander. Das übliche Setup:

1. Lege die gemeinsamen Regeln in AGENTS.md. Codex, Cursor, Copilot, opencode und die meisten anderen lesen sie direkt.

2. Erstelle eine CLAUDE.md, die sie importiert und alles Claude-Spezifische ergänzt:

   @AGENTS.md
   
   ## Claude Code only
   - Use the project's /review skill before opening a PR.

3. Füge in Gemini CLI AGENTS.md zu den gesuchten Dateinamen hinzu, in .gemini/settings.json:

   { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Ein Symlink (ln -s AGENTS.md CLAUDE.md) funktioniert auf macOS und Linux ebenfalls, aber der Import-Ansatz ist klarer und hängt nicht davon ab, wie Windows mit Links umgeht. Claude Code hat in /config außerdem eine Einstellung „Project instructions“, wenn du willst, dass es CLAUDE.md und AGENTS.md gemeinsam liest.

Die erste Version schreiben

Du musst nicht bei einer leeren Seite beginnen. In Claude Code liest /init das Repo und entwirft eine CLAUDE.md. Behandle diesen Entwurf als Rohmaterial: Behalte die Befehle, lösche den Ordnerrundgang und streiche alles, was du einem neuen Teamkollegen an seinem ersten Morgen nicht sagen würdest.

Lass die Datei dann aus echter Arbeit wachsen. Frage dich bei jeder Korrektur am Agenten, ob sie auch nächste Woche noch gälte. Wenn ja, ist sie eine Kandidatin für eine Regel.

Mit AgentVera umsetzen

AgentVera führt Claude Code, Codex, Gemini CLI und andere CLIs nebeneinander in echten Terminals aus. Jeder Agent liest weiterhin seine eigene CLAUDE.md, AGENTS.md oder GEMINI.md genau wie oben beschrieben; AgentVera ersetzt diese Dateien nicht. Einige Funktionen arbeiten daneben:

• Regelvorschläge aus deinen Korrekturen. Wenn du die Arbeit eines Agenten mit einer Notiz aus dem Review-Posteingang zurückschickst oder Verify ein fehlgeschlagenes Kriterium findet, macht ein kleines Claude-Modell aus der Korrektur eine kurze Regel. Sie erscheint unter Rule suggestions; Add to instructions hängt sie an die CLAUDE.md und AGENTS.md des Projekts an (je nachdem, welche existieren), und Regeln, die schon in den Dateien stehen, werden übersprungen. Existiert keine der beiden Dateien, legt es AGENTS.md und eine CLAUDE.md an, die sie mit @AGENTS.md importiert.
• Rollen pro Agent statt einer aufgeblähten gemeinsamen Datei. Das Feld „Role and instructions“ im Agenten-Dialog wird nur diesem einen Agenten übergeben (Claude bekommt es an seinen Systemprompt angehängt, Codex als Developer-Anweisungen). Agentenspezifische Rollen bleiben so aus der gemeinsamen Datei heraus. Cursor, Gemini CLI und Amp nutzen dieses Feld nicht und stützen sich stattdessen auf die AGENTS.md oder Regeldateien des Projekts.
• Eine Code-Map, damit du den Ordnerrundgang weglassen kannst. Die Projekt-Map wird lokal gebaut und Agenten als MCP-Tools angeboten (map_related, map_outline, map_usages und weitere), und neue Agenten bekommen eine kurze Zusammenfassung von Modulen, Einstiegspunkten und dem Testbefehl. Das ist der Teil, den man sonst gern von Hand in CLAUDE.md einfügt.
• Projektgedächtnis. AgentVera Brain liest deine Git-getrackten Dokumente, darunter CLAUDE.md und AGENTS.md, zusammen mit Commits, PRs und früheren Gesprächen und verfolgt, welche Entscheidungen aktuell oder veraltet sind. Ein optionales Kontextpaket (standardmäßig aus) kann den Anweisungen neuer Agenten hinzugefügt werden.
• Abläufe als Skills. Die Skill-Galerie verwaltet SKILL.md-Ordner für Claude Code und Codex, dorthin gehören lange Abläufe.
• Regeln, die immer laufen müssen. CLAUDE.md ist ein Ratschlag; für Prüfungen, die jedes Mal stattfinden müssen, nutze Claude Code Hooks und verlagere schmale Nebenaufgaben in Subagenten.

Checkliste

• Unter 200 Zeilen; idealerweise unter 100.
• Build-, Test-, Lint- und Typprüfungs-Befehle sind aufgeführt und korrekt.
• Jede Regel ist konkret genug, um sie zu überprüfen.
• Kein Ordnerrundgang, keine Secrets, keine allgemeinen Ratschläge.
• Ordnerspezifische Regeln stehen in verschachtelten Dateien oder pfadbezogenen Regeln.
• Lange Abläufe stehen in Skills oder Dokumenten, verlinkt durch eine Zeile.
• Harte Grenzen werden mit Hooks oder Berechtigungen durchgesetzt, nicht mit Prosa.
• Gemeinsame Regeln stehen in AGENTS.md; CLAUDE.md importiert sie.
• Persönliche Vorlieben stehen in ~/.claude/CLAUDE.md oder CLAUDE.local.md.

Fazit

Eine Anweisungsdatei ist der günstigste Weg, einen Agenten so arbeiten zu lassen, als hätte er schon einmal an deinem Projekt gearbeitet. Halte sie kurz, halte sie konkret und lass sie nur aus Fehlern wachsen, die du tatsächlich gesehen hast. Lege gemeinsame Regeln in AGENTS.md, damit jede CLI dasselbe liest, verlagere Abläufe in Skills und setze die wirklich wichtigen Dinge mit Hooks statt mit Sätzen durch.