Claude Code AGENTS.md-Unterstützung: So verwenden Sie sie mit CLAUDE.md

Claude Code unterstützt AGENTS.md ab v2.1.277: In einem Projekt ohne CLAUDE.md liest Claude Code nun Ihre AGENTS.md als Projektanweisungen. Sie brauchen keinen Import, keinen Symlink und keine Einstellung. Enthält Ihr Repository beide Dateien, liest Claude nur CLAUDE.md – es sei denn, Sie stellen die Einstellung Project instructions in /config um, um beide zu laden.

Wenn Ihr Team verschiedene Coding-Agents einsetzt, steuert dieselbe AGENTS.md, die Codex und Cursor bereits lesen, jetzt auch Claude Code. Dieser Leitfaden behandelt die Prioritäten, die Migration und eine AGENTS.md, die jedem Agent beibringt, Ihre APIs mit der Apidog CLI zu testen.

Was ist AGENTS.md in Claude Code?

AGENTS.md ist eine einfache Markdown-Datei mit Anweisungen für Coding-Agents: Build-Befehle, Testbefehle, Code-Stil und Projektregeln. Seit v2.1.277 liest Claude Code sie über ein integriertes Plugin, sodass ein für andere Agents eingerichtetes Repository auch mit Claude Code funktioniert – ganz ohne zusätzliche Dateien. Erforderliche Felder oder eine spezielle Syntax gibt es nicht.

Das Format selbst ist offen. Die AGENTS.md-Website beschreibt es als „a simple, open format for guiding coding agents“, das von über 60.000 Open-Source-Projekten genutzt wird und nun unter der Obhut der Agentic AI Foundation innerhalb der Linux Foundation steht. OpenAI Codex und Cursor dokumentieren beide die AGENTS.md-Unterstützung, und Claude Code war bis zu dieser Version der offensichtliche Ausreißer.

Neu bei dem Format? Beginnen Sie mit how to write AGENTS.md files for API development teams.

Hier die Versionshistorie aus dem offiziellen Claude-Code-Changelog:

Führen Sie claude --version aus, bevor Sie sich darauf verlassen. Bei allem vor 2.1.277 liest Claude Code nur CLAUDE.md-Dateien.

CLAUDE.md vs. AGENTS.md: welche gewinnt?

Standardmäßig setzt sich CLAUDE.md durch. Claude Code liest AGENTS.md nur, wenn im Arbeitsverzeichnis oder in einem übergeordneten Verzeichnis keine CLAUDE.md existiert. Die Claude-Code-Gedächtnisdokumentation beschreibt drei Fälle:

Nicht jede Datei zählt für diese Prüfung. Diese drei blockieren AGENTS.md:

• CLAUDE.md im Arbeitsverzeichnis oder darüber
• .claude/CLAUDE.md im Arbeitsverzeichnis oder darüber
• CLAUDE.local.md im Arbeitsverzeichnis oder darüber

Diese blockieren sie nicht und werden weiterhin neben AGENTS.md geladen: Ihre Benutzerdatei unter ~/.claude/CLAUDE.md, die verwaltete CLAUDE.md Ihrer Organisation sowie Dateien unter .claude/rules/.

Achten Sie auf die CLAUDE.local.md-Falle: Legen Sie eine persönliche Datei für nicht committete Notizen an, hört Claude für Sie auf, die AGENTS.md des Teams zu lesen.

Was Claude Code wann lädt

Wenn nichts im Weg steht, liest Claude Code:

1. Beim Sitzungsstart: jede AGENTS.md und .claude/AGENTS.md im Arbeitsverzeichnis und den darüberliegenden Verzeichnissen. Interaktive Sitzungen geben eine Zeile wie no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md aus.
2. In Unterverzeichnissen: die AGENTS.md eines Unterverzeichnisses, sobald Claude dort mit dem Read-Tool eine Datei öffnet und dieser Ordner keine eigene CLAUDE.md hat.
3. Imports: @path-Imports innerhalb von AGENTS.md werden aufgelöst, und claudeMdExcludes-Muster greifen.

Claude Code liest keine AGENTS.local.md, AGENTS.override.md oder Dateien unter .agents/. Wenn Sie ein Repository mit Codex teilen, das AGENTS.override.md dokumentiert, sollten Sie das bedenken.

So ändern Sie, welche Anweisungsdateien Claude Code lädt

Tippen Sie in einer Sitzung /config ein und stellen Sie Project instructions auf einen von vier Werten:

Für die meisten gemischten Teams ist claude-md-and-agents-md die richtige Einstellung. Sie behält Ihre persönliche CLAUDE.local.md bei und lädt trotzdem die gemeinsame AGENTS.md.

Sie können sie stattdessen auch in einer Settings-Datei festlegen. Claude Code liest diesen Eintrag aus ~/.claude/settings.json, einer --settings-Datei oder den verwalteten Einstellungen und ignoriert ihn in Projekt- und lokalen Settings-Dateien:

{
  "pluginConfigs": {
    "cc-plugin-agents-md@builtin": {
      "options": { "instructionFiles": "claude-md-and-agents-md" }
    }
  }
}

Vor v2.1.285 hieß die Plugin-ID agents-md@builtin. Ab Version 2.1.285 akzeptieren beide IDs; verwenden Sie die alte, wenn ältere Installationen dieselbe Datei nutzen. Die Änderung greift ab Ihrer nächsten Nachricht.

Fehlt Project instructions in /config, kann Ihre Sitzung keine AGENTS.md laden: Sie arbeiten mit einer Version vor 2.1.277, haben das integrierte Plugin über /plugin deaktiviert, oder es ist Ihre erste Sitzung nach dem Upgrade (es funktioniert ab der nächsten).

So migrieren Sie einen älteren AGENTS.md-Workaround

Viele Teams hatten AGENTS.md vor dieser Release-Version manuell in Claude Code eingebunden. Die Dokumentation empfiehlt:

Behalten Sie den @AGENTS.md-Import bei, falls jemand in Ihrem Team noch eine Version älter als 2.1.277 nutzt. Es ist das eine Setup, das mit jeder Version funktioniert.

Import oder Symlink?

Wenn Sie zusätzlich zur gemeinsamen Datei Claude-spezifische Regeln brauchen, nutzen Sie einen Import. Claude liest zuerst die importierte Datei, dann den Rest:

@AGENTS.md

## Claude Code

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

Wenn Sie nichts Claude-spezifisches brauchen, reicht ein Symlink:

ln -s AGENTS.md CLAUDE.md

Zwei Haken: Claudes Edit- und Write-Tools schreiben nicht durch einen Symlink hindurch, und Git unter Windows checkt einen committeten Symlink als einzeilige Textdatei aus, sofern core.symlinks nicht aktiviert ist. Wenn jemand in Ihrem Team Windows nutzt, wählen Sie den Import.

In beiden Fällen gilt: Führen Sie in Ihrer nächsten Sitzung /context all aus und bestätigen Sie, dass CLAUDE.md unter Memory files erscheint.

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

Der Gewinn ist eine einzige zentrale Quelle. Legen Sie Ihre Build- und Testbefehle sowie Konventionen in einer AGENTS.md im Repository-Stamm ab. Codex, Cursor und Claude Code lesen sie alle.

Eine Struktur, die sich in der Praxis bewährt:

• AGENTS.md im Stammverzeichnis: alles, was jeder Agent braucht. Befehle, Ordnerübersicht, Stilregeln, was nicht angefasst werden darf.
• AGENTS.md in großen Unterverzeichnissen: Regeln, die nur dort gelten, etwa services/payments/AGENTS.md. Claude Code lädt diese bei Bedarf, wenn es eine Datei in diesem Ordner liest.
• Optionale CLAUDE.md: nur wenn Sie Claude-spezifisches Verhalten brauchen, etwa den Plan-Modus oder Hooks. Beginnen Sie sie mit @AGENTS.md.

Ein Vorbehalt: Eine über die Einstellung geladene AGENTS.md löst keine InstructionsLoaded-Hooks aus und wird nicht aus --add-dir-Verzeichnissen geladen. Wenn Sie davon abhängen, nutzen Sie den Weg über den @AGENTS.md-Import.

Bringen Sie Ihrem Agent in AGENTS.md das API-Testen mit der Apidog CLI bei

Schreiben Sie Ihre API-Testregeln einmal, und jeder Agent, der das Repository öffnet, führt Tests auf dieselbe Weise aus. Die Apidog CLI liefert dem Agent strukturierte JSON-Ausgaben, die er lesen kann – der gesamte Ablauf bleibt im Terminal.

Richten Sie es einmal pro Maschine ein:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_TOKEN>
apidog skill install

Ein Abkürzung: Sagen Sie Ihrem Agent: „Read https://apidog.com/apidog-cli-installation-guide.md and set up Apidog CLI“. Dieser Leitfaden ist für Agents geschrieben und deckt Installation, Anmeldung und das Skill ab.

Fügen Sie dann einen Abschnitt wie diesen zu Ihrer AGENTS.md hinzu:

## API testing (Apidog CLI)

- Apidog project ID: 123456. Staging environment ID: 7890.
- Never build Apidog JSON payloads from memory. Run
  `apidog cli-schema get <key>` first, then
  `apidog cli-schema validate <key> --file <path>`, and write only after it passes.
- After changing any handler under `src/routes/`, find its endpoint with
  `apidog endpoint list --project 123456` and its cases with
  `apidog test-case list --project 123456 --endpoint <endpointId>`.
- If a route has no test case, create one with
  `apidog test-case create --project 123456 --file case.json`.
- Run cases with
  `apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json`
  and summarize every failure before you say the task is done.
- Do not edit or delete endpoints in Apidog unless the task asks for it.

Nun erledigt ein einzelner Prompt die Arbeit in Claude Code, Codex oder Cursor:

I changed POST /orders to require a currency field. Update the Apidog test
case for it and run it against staging, following AGENTS.md.

Der Agent befolgt Ihre Regeln und führt Befehle wie diese aus:

apidog endpoint list --project 123456
apidog test-case list --project 123456 --endpoint <endpointId>
apidog cli-schema get test-case-create
apidog cli-schema validate test-case-create --file case.json
apidog test-case create --project 123456 --file case.json
apidog run --test-case <caseId> --project 123456 -e 7890 -r cli,json

Jedes der obigen Flags stammt aus apidog <cmd> --help der Apidog CLI 2.2.12. Denselben apidog run-Befehl mit -r junit können Sie direkt in Ihre CI integrieren, und --upload-report sendet die Ausführungsübersicht an die App, damit Ihr Team sie sehen kann. Details zur Claude-Code-Seite finden Sie in how to use the Apidog CLI in Claude Code; Codex-Nutzern hilft the Apidog CLI in Codex. Apidog Free umfasst bis zu 4 Nutzer, sodass ein kleines Team das heute ausprobieren kann.

Fehlerbehebung: Meine AGENTS.md wird nicht geladen

1. Suchen Sie nach einer CLAUDE.md auf dem Pfad. Eine CLAUDE.md, .claude/CLAUDE.md oder CLAUDE.local.md im Arbeitsverzeichnis oder darüber gewinnt standardmäßig. Ihre ~/.claude/CLAUDE.md zählt dabei nicht.
2. Prüfen Sie Ihre Version. Führen Sie claude --version aus. Sie brauchen 2.1.277 oder neuer, und auf Bedrock, Vertex AI, Foundry, Gateways oder mit deaktivierter Telemetrie 2.1.281 oder neuer.
3. Prüfen Sie die Einstellung. Öffnen Sie /config und stellen Sie sicher, dass Project instructions nicht auf claude-md oder managed-only steht.
4. Bestätigen Sie das Laden. Führen Sie /memory aus und suchen Sie den AGENTS.md-Pfad in der Liste.

FAQ

Liest Claude Code jetzt AGENTS.md? Ja, ab v2.1.277. Ohne CLAUDE.md im Arbeitsverzeichnis oder darüber liest Claude Code AGENTS.md automatisch als Projektanweisungen.

Wenn ich sowohl CLAUDE.md als auch AGENTS.md habe, welche nutzt Claude Code? Standardmäßig nur CLAUDE.md. Stellen Sie Project instructions in /config auf claude-md-and-agents-md, um beide zu laden – zuerst CLAUDE.md.

Sollte ich meine CLAUDE.md löschen, die @AGENTS.md importiert? Nicht nötig. Durch den Import wird AGENTS.md nie doppelt geladen, und er funktioniert weiterhin für Teamkollegen mit Versionen vor 2.1.277. Löschen Sie sie nur, wenn sie sonst nichts enthält und alle aktualisiert haben.

Liest Claude Code AGENTS.override.md wie Codex? Nein. Claude Code ignoriert AGENTS.override.md, AGENTS.local.md und alles unter .agents/.

Funktioniert AGENTS.md auf Amazon Bedrock oder Google Vertex AI? Ja, ab v2.1.281. Frühere Versionen auf Bedrock, Vertex AI, Foundry, Gateways oder mit deaktivierter Telemetrie lesen nur CLAUDE.md; nutzen Sie dort einen @AGENTS.md-Import.