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

URL: https://agentvera.dev/de/blog/claude-md-agents-md/ · Veröffentlicht: 2026-10-22

CLAUDE.md Best Practices: wo die Datei liegt, was hineingehört und was nicht, Imports, kurz bleiben und eine AGENTS.md für Claude, Codex und Gemini.

**Kurz gesagt:**

- Eine CLAUDE.md funktioniert am besten unter 200 Zeilen und mit Build- und Testbefehlen, Konventionen, die der Code nicht zeigt, und Fehlern, die der Agent schon gemacht hat.
- Ordnerrundgänge, lange Abläufe, Secrets und allgemeine Ratschläge gehören nicht hinein; unverletzliche Regeln setzt du mit Hooks oder Berechtigungen durch, nicht mit Prosa.
- Um Regeln über CLIs hinweg zu teilen, halte sie in AGENTS.md, importiere sie mit @AGENTS.md aus CLAUDE.md und füge AGENTS.md zu context.fileName in den Einstellungen von Gemini CLI hinzu.

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](/de/glossary/context-window/ "Kontextfenster") des Modells hinzufügt.

| Datei | Gelesen von | Hinweise |
| --- | --- | --- |
| `CLAUDE.md` | Claude Code | Unterstützt `@path`-Imports und pfadbezogene Regeln |
| `AGENTS.md` | Codex, Cursor, Copilot, opencode, Aider, goose, Amp, Gemini CLI (bei Konfiguration) und mehr | Ein offenes Format, oft „ein README für Agenten“ genannt |
| `GEMINI.md` | Gemini CLI | Unterstützt `@file.md`-Imports; der Dateiname ist konfigurierbar |

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

| Geltungsbereich | Ort | Geteilt? |
| --- | --- | --- |
| Managed Policy | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Vom Admin für alle festgelegt |
| Benutzer | `~/.claude/CLAUDE.md` | Nur du, alle Projekte |
| Projekt | `./CLAUDE.md` oder `./.claude/CLAUDE.md` | Eingecheckt, das ganze Team |
| Lokal | `./CLAUDE.local.md` | Nur du; trage sie in `.gitignore` ein |
| Verschachtelt | `src/payments/CLAUDE.md` und so weiter | Wird geladen, wenn Claude dort Dateien liest oder bearbeitet |

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](/de/agents/codex/ "Codex CLI").

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

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

| Weglassen | Warum | Stattdessen hierhin |
| --- | --- | --- |
| Ein Rundgang durch das Repo Datei für Datei | Der Agent kann Ordner selbst auflisten, und der Rundgang veraltet | Nirgendwohin, oder ein Code-Map-Tool |
| Lange Schritt-für-Schritt-Abläufe (Release, Migrationen) | Werden in jedem Turn geladen, auch wenn sie nicht gebraucht werden | Ein [Skill](/de/glossary/agent-skills/ "Agent Skills") oder ein Dokument, auf das die Datei verweist |
| Regeln nur für einen Ordner | Kosten überall Kontext | Eine verschachtelte CLAUDE.md / AGENTS.md oder `.claude/rules/` mit `paths:` |
| Allgemeine Ratschläge („schreib sauberen Code“) | Keine Wirkung auf das Verhalten | Löschen |
| Secrets, Tokens, interne URLs | Die Datei wird eingecheckt und an das Modell gesendet | Umgebungsvariablen |
| Dinge, die nie passieren dürfen | Anweisungen sind Kontext, keine Durchsetzung | Ein [Hook](/de/glossary/claude-code-hooks/ "Claude Code Hooks") oder eine Berechtigungsregel |

## 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](/de/blog/claude-code-token-usage/ "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:

```markdown
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:

```markdown
---
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:

   ```markdown
   @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`:

   ```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](/de/download/ "AgentVera herunterladen") 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](/de/features/review-inbox/ "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](/de/features/project-map/ "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](/de/features/brain/ "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](/de/features/skill-gallery/ "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](/de/blog/claude-code-hooks-guide/ "Claude Code Hooks Anleitung") und verlagere schmale Nebenaufgaben in [Subagenten](/de/blog/claude-code-subagents/ "Claude Code 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.

## Häufige Fragen

**Wie lang sollte eine CLAUDE.md-Datei sein?** Anthropic empfiehlt, unter 200 Zeilen pro Datei zu bleiben. Die Datei wird zu Beginn jeder Session in den Kontext geladen, längere Dateien kosten also mehr Tokens, und in der Praxis befolgt der Agent sie weniger zuverlässig.

**Was ist der Unterschied zwischen CLAUDE.md und AGENTS.md?** Sie erfüllen dieselbe Aufgabe. CLAUDE.md ist die Datei, die Claude Code liest; AGENTS.md ist ein offenes Format, das Codex, Gemini CLI (bei entsprechender Konfiguration), Cursor, Copilot, opencode, Aider, goose und viele andere lesen. Neuere Claude-Code-Versionen lesen AGENTS.md ebenfalls, wenn es keine CLAUDE.md gibt.

**Kann ich eine Anweisungsdatei für Claude Code, Codex und Gemini CLI nutzen?** Ja. Halte die gemeinsamen Regeln in AGENTS.md, lege daneben eine CLAUDE.md mit der Zeile @AGENTS.md (plus Hinweisen nur für Claude) und setze context.fileName in den Einstellungen von Gemini CLI so, dass es AGENTS.md einschließt.

**Sollte CLAUDE.md in Git eingecheckt werden?** Die Projekt-CLAUDE.md ja: Sie ist gemeinsames Teamwissen. Persönliche Vorlieben gehören in ~/.claude/CLAUDE.md oder in CLAUDE.local.md, die du in .gitignore einträgst.

**Garantiert CLAUDE.md, dass der Agent eine Regel befolgt?** Nein. Sie ist Kontext, keine Durchsetzung. Der Agent befolgt klare, konkrete Regeln meist, aber wenn eine Aktion nie passieren darf, blockiere sie mit einem Hook oder einer Berechtigungseinstellung statt mit einem Satz in CLAUDE.md.

---

**Über AgentVera.** AgentVera ist eine Desktop-App für macOS, Windows und Linux, entwickelt von Solviera Teknoloji. Sie führt 18 KI-Coding-Agenten (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) nebeneinander aus, pro Projekt, in echten Terminals mit den eigenen CLI-Installationen und Logins des Nutzers. Der kostenlose Plan hat unbegrenzt viele Agenten. Download: https://agentvera.dev/de/download/ · Preise: https://agentvera.dev/de/pricing/