AGENTS.md und CLAUDE.md für Claude Code, Codex und Cursor

Informationen zum Dienst finden Sie in der Ailoot-Dokumentation.

Was ändert sich, wenn Sie Claude Code, Codex und Cursor gemeinsam verwenden?#

Im beschriebenen Beispiel ist Claude Code das Haupttool, während Codex und Cursor für bestimmte Aufgaben verwendet werden. Meine CLAUDE.md enthält etwa 250 Zeilen mit Anweisungen: was in welcher Reihenfolge zu lesen ist, was nicht angefasst werden darf, welche Befehle für das Deployment zu verwenden sind und welche Regeln für das Commit-Format gelten. Als ich Codex CLI zum ersten Mal im Projekt ausprobierte, kannte es keine dieser Regeln: Es führte git push --force aus, stöberte in .env herum und benannte Dateien achtlos um.

Zuerst kopierte ich CLAUDE.md von Hand nach AGENTS.md. Zwei Wochen später stellte ich fest, dass das Projekt bereits vier Versionen derselben Anweisungen hatte: in CLAUDE.md, AGENTS.md, .cursorrules und .windsurf/rules/. Sie unterschieden sich alle ein wenig. Das ist kein Problem von Claude oder Cursor, sondern die grundlegende Falle jedes Systems mit mehreren Wahrheitsquellen. Ich bespreche dieses Problem ausführlicher im Leitfaden zur Arbeit mit mehreren Agenten.

Im Juni 2026 bot Anthropics Dokumentation zum Claude-Code-Speicher eine Lösung: eine gemeinsame Datei plus einen Import. Seit September 2026 liest Claude Code AGENTS.md selbst, wenn es im Projekt keine CLAUDE.md gibt. Ein Import ist nötig, wenn Sie Regeln haben, die speziell für Claude gelten. Im Folgenden erkläre ich, wann eine einzelne AGENTS.md ausreicht, wie Sie einen Import einrichten und wie Sie gemeinsame Regeln von Claude-spezifischen Regeln trennen.

Liest Claude Code AGENTS.md selbst?#

Vor September 2026 lautete die Antwort „nein“. Issue #6235, in dem Unterstützung für AGENTS.md angefordert wurde, war seit August 2025 offen und wurde am 17. August 2026 geschlossen. Die Dokumentation zum Speicher verwies während der gesamten Zeit auf eine Lösung: eine CLAUDE.md erstellen und AGENTS.md darin als Import einfügen. Ab Version 2.1.277 steht in der Dokumentation etwas anderes:

Welche Dateien Claude Code liest, hängt genau davon ab, welche Dateien im Projekt vorhanden sind:

Für diese Prüfung zählen CLAUDE.md, .claude/CLAUDE.md und CLAUDE.local.md im Arbeitsverzeichnis und in allen darüberliegenden Verzeichnissen. Eine persönliche ~/.claude/CLAUDE.md, eine zentral verwaltete Unternehmensdatei und Regeln aus .claude/rules/ zählen nicht dazu: Sie werden zusammen mit AGENTS.md geladen.

Wenn keine CLAUDE.md vorhanden ist, liest Claude Code beim Start alle Dateien AGENTS.md und .claude/AGENTS.md im Arbeitsverzeichnis und in den darüberliegenden Verzeichnissen. Eine AGENTS.md in einem Unterverzeichnis wird geladen, sobald Claude Code eine Datei in diesem Unterverzeichnis öffnet. @path-Importe in AGENTS.md funktionieren ebenfalls. Claude Code liest weder AGENTS.local.md noch AGENTS.override.md oder den Inhalt des Verzeichnisses .agents/.

Der Haken: Auch eine persönliche CLAUDE.local.md zählt. Wenn Sie eine erstellen, um Ihre nicht committeten Regeln aufzubewahren, hört Claude Code stillschweigend auf, AGENTS.md zu lesen. Die folgende Einstellung löst das Problem.

Das Verhalten lässt sich unter Project instructions in /config ändern:

Wenn Sie CLAUDE.local.md behalten möchten, ohne auf AGENTS.md zu verzichten, stellen Sie claude-md-and-agents-md ein. Es kommt zu keinem doppelten Einlesen: Wenn AGENTS.md bereits über die Zeile @AGENTS.md oder einen symbolischen Link eingebunden ist, lädt Claude Code die Datei unabhängig von der Einstellung kein zweites Mal.

Mit dem Befehl /memory können Sie prüfen, ob die Datei erkannt wurde: Ab Version 2.1.280 erscheint der Pfad zu AGENTS.md in der Liste. In Versionen vor 2.1.277 und in Sitzungen mit deaktiviertem integriertem Plugin agents-md liest Claude Code nur CLAUDE.md; außerdem gibt es unter /config keinen Eintrag Project instructions. Vor Version 2.1.281 verhielten sich Sitzungen über Amazon Bedrock und Sitzungen mit deaktivierter Telemetrie genauso. Auch in der ersten Sitzung nach einer Aktualisierung von einer älteren Version wird AGENTS.md möglicherweise nicht erkannt; ab der nächsten Sitzung funktioniert es.

Was bedeutet das für ein Setup mit einer einzigen Datei? Wenn Sie keine Regeln haben, die nur für Claude gelten, können Sie auf CLAUDE.md verzichten: AGENTS.md genügt, und Claude Code, Codex und Cursor lesen die Datei. Wenn Sie solche Regeln haben (Planmodus für riskante Verzeichnisse, Skills, Hooks), brauchen Sie CLAUDE.md, und Claude Code liest AGENTS.md nicht mehr von selbst. Fügen Sie dann AGENTS.md in CLAUDE.md mit der Zeile @AGENTS.md ein; so funktioniert das Setup wie vor September. Es hilft auch bei älteren Claude-Code-Versionen. Weiter unten erkläre ich es genauer.

Wie importiert man @AGENTS.md in CLAUDE.md?#

Ein minimales funktionsfähiges Beispiel aus der offiziellen Dokumentation:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

So läuft es ab: Die erste Zeile, @AGENTS.md, ist eine Importanweisung. Wenn Claude Code zu Beginn einer Sitzung CLAUDE.md einliest, findet es diesen Import und setzt den gesamten Inhalt von AGENTS.md an dessen Stelle ein. Danach folgt die Überschrift ## Claude Code: Sie ist einfach Markdown, dient aber als Abschnitt für „Claude-spezifische Ergänzungen“. Darunter steht eine Regel, die nur für Claude Code gilt: Für Änderungen im Abrechnungsverzeichnis soll der Planmodus verwendet werden. Codex CLI oder Cursor öffnen diese Datei nicht; sie verwenden die unveränderte AGENTS.md.

Ein Zitat aus der Dokumentation zur Funktionsweise von Importen:

Einige praktische Details:

• Relative und absolute Pfade. @AGENTS.md ist relativ zur Datei, die den Import enthält. @/Users/me/shared/rules.md oder @~/.claude/personal.md sind absolute Pfade. Ich verwende @~/.claude/personal.md für persönliche Präferenzen, die nicht ins Repository gehören.
• Vier Ebenen tief. AGENTS.md kann @docs/coding-style.md importieren, und coding-style.md kann bis zu vier Ebenen tief eine weitere Datei importieren. Das reicht für jede praktische Struktur.
• Backticks verhindern Importe. Wenn im Text `@README` steht, ist das nur eine Erwähnung des Namens und kein Import. Das ist nützlich, wenn man Leserinnen und Lesern erklären möchte, wie Importe funktionieren, ohne tatsächlich einen auszulösen.
• Genehmigung für Dateien außerhalb des Projekts. Wenn ein Import auf eine Datei außerhalb des Arbeitsverzeichnisses verweist, etwa @~/.claude/personal.md, zeigt Claude Code beim ersten Mal einen Dialog mit einer Liste dieser Dateien. Wenn Sie ablehnen, bleiben externe Importe deaktiviert, und der Dialog wird nicht erneut angezeigt. @AGENTS.md im Projektstamm löst keinen Dialog aus. So wird verhindert, dass versehentlich eine nicht zugehörige Datei in den Kontext geladen wird.

Nachdem ich im beschriebenen Projekt zu diesem Setup gewechselt hatte, schrumpfte meine CLAUDE.md von 250 auf 60 Zeilen: @AGENTS.md plus fünf bis sieben Regeln, die nur für Claude Code gelten (Planmodus für riskante Verzeichnisse, was im Admin-Bereich nicht angefasst werden darf und wie Commits formuliert werden). Alles Gemeinsame steht in AGENTS.md, die Codex und Cursor lesen.

Wann sollte man einen symbolischen Link wählen und wann einen Import?#

Die Dokumentation zeigt die Option mit symbolischem Link so:

ln -s AGENTS.md CLAUDE.md

Und direkt danach folgt eine deutliche Warnung zu Windows:

Vergleichstabelle:

Ich verwende im beschriebenen Projekt Importe. Die Gründe:

1. Das Team ist gemischt. Ich arbeite auf dem Mac; im Beispiel ist das Team ungefähr gleichmäßig auf Windows und Mac verteilt. Wenn ein symbolischer Link im Repository liegt, wird er für Windows-Nutzende ohne Entwicklermodus als normale Textdatei mit nur einer Zeile, AGENTS.md, ausgecheckt. Das führt zu merkwürdigen Fehlern: Manchmal funktionieren die Regeln, manchmal nicht, und es ist unklar, warum.
2. Ich möchte Regeln nur für Claude. Unter @AGENTS.md hat meine CLAUDE.md einen Abschnitt „Claude Code“ mit Regeln: --effort high für Architekturaufgaben verwenden, vor git push npm run build ausführen und /api/v1/deploy nicht von Hand aufrufen. Codex versteht diese Befehle nicht.
3. Das Debuggen ist einfacher. Wenn etwas schiefgeht, öffne ich CLAUDE.md und sehe den Import und meine Ergänzungen. Bei einem symbolischen Link gibt es kein „das wurde hier hinzugefügt“. Weitere Informationen zur Fehlersuche bei den Claude-Code-Einstellungen finden Sie im Leitfaden zum sicheren Modus.

Wenn Sie keine Claude-spezifischen Regeln haben, ist ab Version 2.1.277 kein symbolischer Link mehr nötig: Löschen Sie CLAUDE.md, und Claude Code liest AGENTS.md selbst. Behalten Sie den symbolischen Link nur, wenn jemand im Team eine ältere Version als 2.1.277 nutzt und nicht aktualisieren kann. Wenn Sie Claude-spezifische Regeln haben, ist ein Import in neun von zehn Fällen bequemer.

Was lesen Codex, Cursor, Copilot, Windsurf und Gemini CLI?#

Eine Übersicht der sieben wichtigsten Tools (basierend auf der offiziellen Dokumentation der Tools):

Was folgt daraus? Wenn ein Repository eine AGENTS.md hat (sowie bei Bedarf eine CLAUDE.md mit Import für Claude-spezifische Regeln), erhalten fünf der sieben Tools automatisch aktuelle Anweisungen. Cursor und Windsurf haben eigene native Dateien. Sie können sie unverändert lassen (AGENTS.md wird von ihnen ebenfalls gelesen) oder einen @AGENTS.md-Import hinzufügen. Ihre Syntax unterscheidet sich allerdings und wird nicht immer unterstützt.

Die einfachste Strategie für ein neues Projekt:

1. Alle gemeinsamen Regeln in AGENTS.md ablegen – 95 % der Regeln gehören dorthin.
2. CLAUDE.md erstellen, wenn Sie Regeln nur für Claude brauchen: @AGENTS.md in die erste Zeile schreiben und darunter einen Abschnitt mit Claude-spezifischen Regeln ergänzen. Wenn es keine solchen Regeln gibt, ist CLAUDE.md unnötig; Claude Code liest AGENTS.md seit Version 2.1.277 selbst.
3. .cursor/rules/ für Cursor behalten, wenn Sie seltene Cursor-spezifische Funktionen wie die Befehle @Codebase und @Docs benötigen.
4. Für Windsurf genauso vorgehen: das alte .windsurfrules vergessen und .windsurf/rules/ nur verwenden, wenn Regeln für die eigene Syntax nötig sind.

Mit diesem Ansatz erhalten Sie 80 % des Nutzens bei 20 % des Aufwands. Als ich gemischte Teams in „Antigravity“ organisierte, stellte sich heraus, dass mehr als zwei Wahrheitsquellen (gemeinsam plus nur für Claude) mühsam zu pflegen sind. Wenn jemand im Team eine Regel zu .cursorrules hinzufügt und AGENTS.md nicht aktualisiert, sind Cursor und Codex eine Woche später uneins.

Wie übernimmt /init in Claude Code eine vorhandene AGENTS.md?#

Anthropic beschreibt /init in der Dokumentation so:

Was bedeutet das in der Praxis? Das beschriebene Repository hatte eine .cursorrules aus der Zeit, als ich Cursor ausprobierte (etwa 80 Zeilen), und eine von Hand zusammengestellte AGENTS.md (120 Zeilen). Als ich claude /init ausführte, nahm der Befehl beide Dateien, fasste ähnliche Regeln zusammen und erstellte innerhalb einer Minute eine saubere CLAUDE.md. Anschließend prüfte ich sie und nahm kleinere Änderungen vor: Ich entfernte veraltete Punkte und ergänzte eine Struktur mit Überschriften. Das ging schneller als ein vollständiger Neuanfang.

Der interaktive Modus, in dem /init auch AGENTS.md liest, wird über eine Umgebungsvariable aktiviert:

CLAUDE_CODE_NEW_INIT=1 claude

Nach dem Start von /init stellt Claude mehrere Rückfragen: welche Artefakte konfiguriert werden sollen (CLAUDE.md, Skills, Hooks), welchen Technologie-Stack das Projekt verwendet und welche Befehle für Tests zu nutzen sind. Anschließend untersucht ein Subagent die Codebasis – er liest package.json, README.md und Konfigurationsdateien – und ergänzt fehlende Teile. Am Ende zeigt er einen Vorschlag, den Sie vor dem Speichern bearbeiten können. Weitere Informationen zur Einrichtung von Claude Code beim Start eines Projekts finden Sie im separaten Leitfaden.

Nun zum Nachteil. Wenn das Projekt bereits eine aktive AGENTS.md hat, erstellt /init daneben eine CLAUDE.md mit einer Kopie ihrer Regeln. Von diesem Zeitpunkt an liest Claude Code standardmäßig nur noch CLAUDE.md. Damit gibt es wieder zwei Wahrheitsquellen: Sie aktualisieren AGENTS.md, während Claude weiterhin mit der alten Kopie arbeitet. Der Befehl /import macht etwas Ähnliches: Er hängt eine einmalige Kopie von AGENTS.md an CLAUDE.md an. Um eine einzige Quelle zu bewahren, setzen Sie nach /init den Import @AGENTS.md in die erste Zeile von CLAUDE.md und entfernen Sie daraus alles, was AGENTS.md wiederholt.

/init ist der richtige Ausgangspunkt für ein neues Projekt oder eines, das von Cursor oder Copilot umgestellt wird. Sie müssen nicht online nach der „besten CLAUDE.md-Vorlage“ suchen – Anthropic berücksichtigt bereits, was sich im Repository befindet. Wenn das Projekt bereits eine aktive AGENTS.md hat und es keine Claude-spezifischen Regeln gibt, ist /init unnötig: Claude Code liest AGENTS.md selbst.

Wie trennt man gemeinsame und Claude-spezifische Anweisungen?#

Ich trenne sie nach diesem Grundsatz. Gemeinsame Regeln für AGENTS.md:

• Was im Code nicht angefasst werden darf. Die Ordner .env, node_modules, prisma/migrations (nur über prisma migrate), .next/, .git/.
• Wie Dinge benannt werden. Branches: feat/, fix/, chore/. Commits: Präfixe feat:, fix:, docs: plus eine kurze Beschreibung. Komponentendateien in kebab-case.
• Test- und Lint-Befehle. npm run build, npm run lint, npm test. Welchen Befehl Sie vor git push ausführen müssen.
• Architekturprinzipien. Was in src/lib/ und src/components/ gehört, wo die Geschäftslogik liegt und wo die Benutzeroberfläche ist.
• Sicherheit. Geheimnisse niemals committieren. Auf die Produktionsdatenbank nur über prod-psql zugreifen. Per SSH nur über den Alias prod auf die Produktion zugreifen, nicht über root@IP.

Claude-spezifische Regeln für CLAUDE.md (unter @AGENTS.md):

• Planmodus. Für Änderungen in riskanten Verzeichnissen (zum Beispiel src/billing/) den plan mode verwenden.
• Aufwandsstufe. Für Architekturaufgaben --effort high, für Routinearbeiten medium verwenden.
• Skills. Welche KI-Agenten und Skills in welchen Situationen ausgeführt werden sollen. Zum Beispiel: „Bei der Arbeit an einem Leitfaden den Skill build-masterskaya-guide ausführen.“
• Claude-Speicher. Was in den automatischen Speicher und was in CLAUDE.local.md gehört. Weitere Informationen zum Claude-Speicher finden Sie im Leitfaden zu Memory und CLAUDE.md.
• Hooks. Wenn in .claude/settings.json Hooks konfiguriert sind, beschreiben Sie in CLAUDE.md, was sie tun (Codex und Cursor kennen sie nicht und müssen sie auch nicht kennen).
• Skills und Befehle. Eine Liste der Schrägstrichbefehle, die ich häufig verwende (/init, /cd, /memory, /plan).

Die Grenze ist nicht immer eindeutig. „Führe git push --force niemals für main aus“ ist klar eine gemeinsame Regel und gehört daher in AGENTS.md. „Verwende vor einem git push auf einen Hot-Branch zuerst den Planmodus“ ist dagegen spezifisch für Claude Code und gehört in CLAUDE.md. Die Prüffrage lautet: „Wenn ich Claude Code morgen entfernte und nur Codex behielte, würde diese Regel weiterhin gelten?“ Wenn ja, gehört sie in AGENTS.md. Wenn nein, gehört sie in CLAUDE.md.

Was gehört in AGENTS.md und was in CLAUDE.md oder .claude/rules?#

Wenn die Regeln mehr als 200 Zeilen umfassen, ist es Zeit, sie aufzuteilen. Anthropics Dokumentation empfiehlt, pro Datei etwa 200 Zeilen anzustreben, weil Claude bei langen CLAUDE.md-Dateien die Regeln zunehmend stillschweigend weniger befolgt, obwohl es sie anscheinend liest.

Eine Struktur für ein großes Projekt, die sich bei mir bewährt hat:

my-project/
├── AGENTS.md                    # 100-150 Zeilen, gemeinsam
├── CLAUDE.md                    # 30-50 Zeilen: @AGENTS.md + nur für Claude
└── .claude/
    ├── CLAUDE.md                # Alternative zur Datei im Stammverzeichnis, gleiche Datei
    └── rules/
        ├── api.md               # mit paths: ['src/api/**']
        ├── components.md        # mit paths: ['src/components/**']
        ├── testing.md           # ohne paths, immer aktiv
        └── security.md          # ohne paths, immer aktiv

Jede Datei in .claude/rules/ kann ein Frontmatter enthalten:

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Every endpoint validates input with zod
- Errors use the standard `{error, code}` format
- OpenAPI comments are required

Claude lädt diese Regeln nur, wenn es mit Dateien arbeitet, die diesem Muster entsprechen. Wenn es src/components/Button.tsx bearbeitet, werden die API-Regeln nicht in den Kontext aufgenommen. So wird das Kontextfenster nur für relevante Inhalte verwendet. Das Verzeichnis .claude/rules/ funktioniert auch ohne CLAUDE.md: Wenn das Projekt nur eine AGENTS.md enthält, werden seine Regeln zusätzlich geladen und deaktivieren das direkte Lesen von AGENTS.md nicht.

Cursor und Windsurf unterstützen dasselbe Vorgehen über ihre Verzeichnisse .cursor/rules/ und .windsurf/rules/. Der AGENTS.md-Standard kann auf diese Verzeichnisse verweisen, aber die Syntax für mehrere Tools ist noch nicht vollständig stabil. Sicherer ist es, gemeinsame Regeln in AGENTS.md zu belassen und pfadbezogene Regeln in .claude/rules/ und .cursor/rules/ zu duplizieren. Das sind seltene Sonderfälle, nicht der Großteil der Regeln.

Nützliche Speicherorte für CLAUDE.md (von der weitesten bis zur engsten Reichweite geordnet):

Eine beispielhafte ~/.claude/CLAUDE.md könnte zwei Regeln enthalten: „Antworte in der bevorzugten Sprache des Benutzers“ und „Schreibe Ailoot genau so.“ Diese Regeln gelten für jedes Projekt und müssen daher nicht in jedem Repository wiederholt werden.

Von diesen vier Ebenen deaktivieren nur eine projektbezogene CLAUDE.md und CLAUDE.local.md das direkte Lesen von AGENTS.md. Eine persönliche ~/.claude/CLAUDE.md und eine zentral verwaltete Richtlinie stehen dem nicht im Weg; Claude Code liest sie zusammen mit AGENTS.md.

Was tun, wenn AGENTS.md im Projekt bereits veraltet ist?#

Im beschriebenen Projekt hatte ich eine AGENTS.md aus dem Mai 2025 – 180 Zeilen, viele davon veraltet (sie erwähnte Anthropic-API-Endpunkte, die sich inzwischen geändert hatten, Beispiele mit der nicht mehr existierenden Syntax claude --tools und Regeln zu ~/.claude/projects/ mit einer veralteten Struktur).

So bin ich beim Aktualisieren vorgegangen:

1. Im Planmodus mit claude überprüfen. Ich öffne das Repository, führe claude --safe-mode aus und frage: „Lies AGENTS.md erneut und schlage eine Liste veralteter oder wiederholter Punkte vor. Bearbeite nichts; liste sie nur auf.“ In zwei Minuten erhielt ich eine Liste mit 23 Punkten zur Prüfung.
2. Offensichtlich überholte Punkte entfernen. Von den 23 Punkten waren 9 eindeutig veraltet – Befehlssyntax, Endpunkte und Flag-Namen. Ich löschte diese Zeilen.
3. Doppelte Einträge zusammenführen. Weitere 6 Punkte wiederholten einander in anderer Formulierung („nicht mit Force pushen“, „niemals --force verwenden“, „git push -f vermeiden“). Ich fasste sie zu einer Zeile zusammen.
4. Neue Punkte hinzufügen. Ich ergänzte, was Claude/Codex im vergangenen Monat regelmäßig falsch gemacht hatten, nach dem Grundsatz „eine Zeile pro Fehlermuster“. So kamen 8 neue Punkte hinzu.
5. Einen Subagenten zur abschließenden Prüfung einsetzen. Ich bat Claude um eine Prüfung mit der Anweisung „Widersprüche, Mehrdeutigkeiten und Duplikate finden.“ Dabei wurden drei Formulierungen entdeckt, die klarer sein konnten. Ich überarbeitete sie.

Nach einer Stunde umfasste AGENTS.md 110 aktuelle Zeilen, und ich kannte jede einzelne persönlich. Daraus ließ sich leicht eine 30-zeilige CLAUDE.md erstellen. Auch Codex ging anschließend merklich sorgfältiger mit Tests um – ich vermute, einige seiner „merkwürdigen“ Entscheidungen gingen auf veraltete Anweisungen zurück, denen es in gutem Glauben gefolgt war.

Die wichtigsten Grundsätze für eine aktuelle AGENTS.md:

• Jede Regel behandelt einen wiederkehrenden Fehler. Wenn mir eine Regel im Laufe des Monats kein einziges Mal eingefallen ist, lohnt es sich nicht, sie beizubehalten.
• Regeln als Anweisungen, nicht als Theorie formulieren. „Zwei Leerzeichen verwenden“ ist eine Regel. „Der Code-Stil sollte ordentlich sein“ ist keine.
• Konkretes vor Allgemeinem. „Vor git push npm run build ausführen“ ist eine Regel. „Änderungen testen“ ist keine.

Was funktioniert mit diesem Setup definitiv NICHT?#

Einige Dinge, die ich in sechs Monaten Arbeit mit diesem Setup auf die harte Tour gelernt habe:

1. Die Autovervollständigung von Cursor verwendet AGENTS.md nicht. Wenn Cursor im Editor eine Zeile vervollständigt, liest es AGENTS.md nicht in Echtzeit – dafür ist eine separate, schnelle Engine zuständig. Regeln in AGENTS.md sind nur dann relevant, wenn Sie im Cursor-Chat eine Anfrage stellen. Die Regel „Verwende kein var, sondern const“ in AGENTS.md wirkt sich also nicht auf die Autovervollständigung aus; dafür müssen Sie ESLint oder die TypeScript-Konfiguration verwenden.

2. Claude-Code-Hooks in AGENTS.md funktionieren nicht für Codex. Wenn in .claude/settings.json ein PreToolUse-Hook eingerichtet ist, der eine bestimmte Aktion blockiert, ist diese Information nur für Claude nützlich. Codex kennt keine Hooks; für das Tool ist es so, als „entscheide das Tool selbst“. Sinnvoll ist es, „Tue X nicht“ in AGENTS.md zu schreiben und „Es gibt einen Hook, der X physisch blockiert“ in CLAUDE.md unter den Import.

3. Copilot und .github/copilot-instructions.md. GitHub Copilot liest seine eigene Datei und versteht AGENTS.md weiterhin nicht besonders gut. Wenn Ihr Team Copilot aktiv nutzt, erstellen Sie entweder eine separate .github/copilot-instructions.md mit einer gekürzten Version der Regeln oder verwenden Sie Copilot-Erweiterungen, die AGENTS.md kennen. Das ändert sich schnell; in drei bis sechs Monaten kann die Lage anders aussehen.

4. Git verfolgt einen symbolischen Link nicht als Änderung an CLAUDE.md. Wenn Sie ln -s AGENTS.md CLAUDE.md ausführen und eine Woche später AGENTS.md aktualisieren, zeigt Git nur einen Diff für AGENTS.md. Das ist normal, aber Kolleginnen und Kollegen, die den PR prüfen, bemerken möglicherweise nicht, dass auch CLAUDE.md (über den symbolischen Link) aktualisiert wurde. Lösung: Schreiben Sie ausdrücklich in die PR-Beschreibung: „AGENTS.md aktualisiert; Claude Code sieht dieselbe Datei über den symbolischen Link.“

5. Verschachtelte Importe sind schwer zu debuggen. Wenn AGENTS.md @docs/coding-style.md importiert, das wiederum @docs/typescript.md importiert, lässt sich ein Konflikt zwischen Regeln nur schwer untersuchen. Ich beschränke Importe auf eine Ebene (CLAUDE.md → AGENTS.md) und verschachtele sie nicht weiter. Anthropic stellt einen InstructionsLoaded-Hook bereit, der protokolliert, welche Dateien geladen wurden – nützlich zur Fehlersuche bei gestaffelten Setups. Hinweis: Der Hook wird ausgelöst, wenn AGENTS.md über einen Import oder symbolischen Link eingebunden wird, aber nicht, wenn Claude Code die Datei selbst liest.

Das komplette Vibe-Coding-Setup für einen Abend: KI-Klon + Second Brain + Context Engineering.

Lernen Sie Ailoot kennen.