SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor · Aktualisiert 2026-10-28

AGENTS.md im Monorepo richtig verschachteln

Eine zentrale AGENTS.md veraltet und verbraucht Kontext für ungenutzte Verzeichnisse. So strukturieren Sie Root- und Dienstdateien mit klaren Regeln.

Bedeutung verschachtelter AGENTS.md-Dateien in einem Monorepo

Verschachtelte AGENTS.md-Dateien in einem Monorepo bedeuten, dass eine kleine Datei im Repository-Stammverzeichnis und eine weitere Datei in jedem Dienstverzeichnis liegt. Die Datei im Stammverzeichnis enthält die wenigen Regeln, die überall gelten, sowie eine Übersicht über die Speicherorte der übrigen Dateien. Jede Dienstdatei enthält die Befehle und Konventionen, die nur für dieses Verzeichnis gelten. Ein Agent, der services/worker/queue.py bearbeitet, liest dann die Datei im Stammverzeichnis und die Datei für den Worker. Für das Frontend, das er nicht bearbeitet, wird kein Kontext verbraucht.

Sie müssen nichts installieren. AGENTS.md ist eine Konvention. Das Upstream-Projekt beschreibt dies eindeutig:

AGENTS.md ist einfach Standard-Markdown. Verwenden Sie beliebige Überschriften. Der Agent analysiert lediglich den von Ihnen bereitgestellten Text.

Deshalb lohnt es sich, diese Technik richtig zu erlernen. Das Format ändert sich nicht plötzlich. Probleme entstehen durch die Ablage und die Pflege. Für beides sind Sie verantwortlich.

Warum funktioniert eine große AGENTS.md im Repository-Stammverzeichnis nicht mehr?

Eine einzelne 600-zeilige AGENTS.md im Stammverzeichnis eines Repositorys, das eine Webanwendung, einen Hintergrund-Worker und ein Terraform-Verzeichnis enthält, scheitert auf vier verschiedene Arten.

Sie wird veraltet, weil niemand für sie verantwortlich ist. Der Engineer, der in apps/web ein Testskript umbenennt, bearbeitet Dateien unter apps/web. Die AGENTS.md im Stammverzeichnis ist nicht Teil dieses Diffs. Daher sieht kein Reviewer die Abweichung. Sechs Wochen später beschreibt die Datei einen Build-Schritt, den es nicht mehr gibt, und die Person, die ihn entfernt oder verändert hat, erinnert sich nicht mehr an die Änderung.

Sie verbraucht bei jeder Aufgabe Kontext. Diese Dateien werden zu Beginn der Sitzung geladen, bevor der Agent weiß, was Sie fragen werden. In der Dokumentation von Claude Code steht dazu eine konkrete Empfehlung: "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Codex lädt keine weiteren Anweisungsdateien, sobald ihre kombinierte Größe 32 KiB erreicht, den Standardwert project_doc_max_bytes. Eine Root-Datei, die vier Dienste dokumentiert, verbraucht bei jeder einzelnen Aufgabe Budget für drei davon.

Anweisungen beginnen, sich gegenseitig zu widersprechen. Das Webverzeichnis benötigt pnpm test. Der Worker benötigt pytest -q. In einer gemeinsamen Datei ist jede Regel nur in bestimmten Situationen korrekt. Daher muss der Agent raten, welche Regel gilt. Die Dokumentation von Claude Code beschreibt das Ergebnis so: "if two instructions contradict each other, Claude may pick one arbitrarily." Das Aufteilen der Datei hält die jeweils andere Regel nicht aus dem Kontext fern. Claude Code fügt alle geladenen Anweisungsdateien zusammen, statt eine Datei durch eine andere zu ersetzen. Daher ist die Root-Datei immer vorhanden. Sobald der Agent Dateien in apps/web und services/worker geöffnet hat, befinden sich beide Verzeichnisdateien gemeinsam im Kontext. Eine Datei pro Verzeichnis verknüpft die jeweilige Regel mit dem Verzeichnis, für das sie gilt. Nennen Sie das Verzeichnis am Anfang der Datei, wie es die folgenden Beispiele mit # apps/web tun. Dann gibt jeder Befehl weiterhin an, wo er gilt, wenn mehrere Dateien gleichzeitig geladen sind. Wenn eine Regel, die Sie nach eigener Einschätzung klar formuliert haben, trotzdem übersprungen wird, hilft es mehr, die Gründe zu prüfen, warum eine Anweisung nicht greift, als die Formulierung ein viertes Mal umzuschreiben.

Sie wird mit Fakten gefüllt, die der Agent aus dem Code lesen kann. Dazu gehören ein Verzeichnisbaum, eine Liste der Abhängigkeiten und eine Zusammenfassung der Aufgaben der einzelnen Pakete. Die /doctor-Prüfung von Claude Code dient genau dazu, solche Inhalte zu entfernen. Sie "cuts content Claude can derive from the codebase, such as directory layouts, dependency lists, and architecture overviews" und behält "pitfalls, rationale, and conventions that differ from tool defaults." Dieser Satz ist der beste Test, den ich kenne, um zu entscheiden, ob eine Zeile überhaupt in die Datei gehört.

Liest der Agent die Root-Datei oder nur die nächstgelegene?

Hier unterlaufen den meisten Anwendern Fehler bei der Modellvorstellung. Daher ist es sinnvoll, die Upstream-Konvention zu zitieren, anstatt sie nur sinngemäß wiederzugeben:

Platzieren Sie eine weitere AGENTS.md in jedem Paket. Agenten lesen automatisch die nächstgelegene Datei im Verzeichnisbaum. Die Datei mit der geringsten Distanz hat Vorrang, sodass jedes Teilprojekt eigene Anweisungen mitliefern kann.

Und zu Konflikten:

Die AGENTS.md, die der bearbeiteten Datei am nächsten liegt, gewinnt; explizite Chat-Prompts des Benutzers überschreiben alles.

„Hat Vorrang“ wird von vielen so verstanden, dass die Root-Datei ignoriert wird. Das ist nicht der Fall. In den Tools, die diese Konvention implementieren, wird jede Datei auf dem Pfad von der Repository-Root bis zum Arbeitsverzeichnis gelesen und zusammengefügt. Die nächstgelegene Datei gewinnt nur dort, wo zwei Dateien unterschiedliche Anweisungen zum selben Thema enthalten.

Codex äußert sich explizit zum Mechanismus: „Codex verkettet Dateien von der Root abwärts und verbindet sie mit Leerzeilen. Dateien, die näher an Ihrem aktuellen Verzeichnis liegen, überschreiben frühere Anweisungen.“ Claude Code folgt demselben Pfad. Beim Sitzungsstart liest es „jede AGENTS.md und .claude/AGENTS.md in Ihrem Arbeitsverzeichnis und den darüber liegenden Verzeichnissen“. Die Dokumentation beschreibt das Lademodell unmissverständlich: „Alle gefundenen Dateien werden in den Kontext verkettet, anstatt sich gegenseitig zu überschreiben.“ Verzeichnisse unterhalb des Arbeitsverzeichnisses verhalten sich anders: Claude Code lädt die AGENTS.md eines Unterverzeichnisses bei Bedarf, „wenn Claude dort eine Datei mit dem Read-Tool öffnet“.

Daraus ergeben sich zwei praktische Konsequenzen. Die Root-Datei ist ein Präfix für jede Sitzung im Repository. Behandeln Sie daher jede Zeile dort als eine Zeile, für die Sie hundertmal pro Woche bezahlen. Eine verzeichnisspezifische Datei kostet nichts, solange der Agent keine Datei in diesem Verzeichnis öffnet. Details sind dort also kostengünstig und gehören dorthin.

Dieses Verhalten wurde am 27. Oktober 2026 anhand der Dokumentation von Codex und Claude Code überprüft. Tools implementieren die Konvention leicht unterschiedlich und ändern sich mit der Zeit. Überprüfen Sie daher die Laderegeln für den Agenten, den Ihr Team einsetzt.

Ein ausgearbeitetes Layout für ein Repository mit drei Diensten

repo/
  AGENTS.md                   rules true everywhere, plus the map
  apps/web/AGENTS.md          TypeScript client, Vite, Vitest
  services/worker/AGENTS.md   Python queue consumer, pytest
  infra/AGENTS.md             Terraform and the deploy scripts

Die Datei im Stammverzeichnis ist absichtlich kurz. Sie gibt an, wo gesucht werden soll, und enthält nur die Regeln, die in jedem Verzeichnis gelten.

# AGENTS.md

This is a monorepo. Each top-level directory ships its own AGENTS.md.
Read this file and the AGENTS.md nearest the code you are editing
before you change anything.

- `apps/web` browser client
- `services/worker` queue consumer
- `infra` Terraform and deploy scripts

## Rules for the whole repository

- The package manager is `pnpm`. `npm install` writes a second lockfile
  that CI ignores, so the install you tested is not the install that ships.
- Any `generated/` directory is build output. Edit the schema in
  `schemas/` and run `pnpm codegen` instead.
- `.env.local` holds real credentials. Do not read it and do not print it.
- If you change code in a directory, update that directory's AGENTS.md
  in the same commit.

In der Datei des jeweiligen Verzeichnisses stehen die Details. Sie kann so ausführlich sein, wie es das Verzeichnis erfordert.

# apps/web

Browser client. Vite and React, TypeScript with `strict` on.

## Commands

- `pnpm dev` serves on port 5173.
- `pnpm test` runs Vitest once and exits.
- `pnpm typecheck` runs `tsc --noEmit`.

## Conventions

- One component per file under `src/components/`.
- All HTTP goes through `src/api/client.ts`. Do not call `fetch` directly,
  because the client attaches the auth header and retries on 429.

## Traps

- `pnpm build` does not type check. Vite strips the types instead of
  checking them, so a broken type still produces a green build.
  Run `pnpm typecheck` as a separate step.

Die Datei für den Worker hat dieselbe Struktur, aber andere Inhalte: den Installationsbefehl, pytest -q, den Grund, warum der Consumer idempotent bleiben muss, und die Migration, die ausgeführt werden muss, bevor die Tests erfolgreich sind. In der Infrastrukturdatei stehen die Regeln, die verhindern, dass ein Agent Schaden anrichtet. Führen Sie niemals terraform apply aus. Führen Sie terraform plan aus und beenden Sie den Vorgang dort. Nennen Sie außerdem das bereits konfigurierte State-Backend, damit der Agent nicht versucht, ein neues zu initialisieren.

Beachten Sie, was in keiner dieser Dateien steht: eine Beschreibung des Zwecks der einzelnen Dienste. Das ist für Menschen bestimmt. Upstream zieht dieselbe Grenze und sagt: "README.md files are for humans: quick starts, project descriptions, and contribution guidelines", während AGENTS.md "the extra, sometimes detailed context coding agents need: build steps, tests, and conventions" enthält. Die Aufteilung zwischen AGENTS.md und einer an Menschen gerichteten README erläutert diese Grenze Satz für Satz. Eine DESIGN.md, die festhält, warum der Code so strukturiert ist behandelt die dritte Datei, die Entscheidungen statt Befehle erklärt.

Wer aktualisiert die Datei, wenn sich der Code ändert?

Eine Regel genügt, und sie gehört in die Datei im Root-Verzeichnis: Wer Code in einem Verzeichnis ändert, aktualisiert die AGENTS.md dieses Verzeichnisses im selben Commit.

Das funktioniert aus einem technischen Grund, nicht aus einem kulturellen. Die Datei für das jeweilige Verzeichnis befindet sich im selben Diff wie der Code. Der Reviewer des Pull Requests sieht daher beides gleichzeitig. Eine Datei im Root-Verzeichnis gehört allen und damit niemandem. Sie ist nie Teil des Diffs, den gerade jemand prüft.

Ergänzen Sie die Regel um eine Prüfung im Pull Request. Sie ermittelt für jede geänderte Datei die nächstgelegene AGENTS.md in einem übergeordneten Verzeichnis. Anschließend meldet sie, wenn diese Datei nicht geändert wurde.

#!/usr/bin/env bash
# Warn when code changed but the nearest AGENTS.md above it did not.
changed=$(git diff --name-only origin/main...HEAD)

nearest_doc() {
  d=$(dirname "$1")
  while [ "$d" != "." ]; do
    if [ -f "$d/AGENTS.md" ]; then echo "$d/AGENTS.md"; return; fi
    d=$(dirname "$d")
  done
  echo "AGENTS.md"
}

printf '%s\n' "$changed" | while read -r f; do
  [ -n "$f" ] || continue
  case "$f" in AGENTS.md|*/AGENTS.md) continue ;; esac
  doc=$(nearest_doc "$f")
  printf '%s\n' "$changed" | grep -Fqx "$doc" && continue
  echo "note: $f changed but $doc was not updated"
done

Auf einem Branch, in dem der API-Client überarbeitet wurde, ohne die Dokumentation anzupassen, sieht die Ausgabe so aus:

note: apps/web/src/api/client.ts changed but apps/web/AGENTS.md was not updated

Behandeln Sie dies als Warnung und nicht als Fehler. Eine harte Sperre führt dazu, dass jemand eine leere Zeile in die Datei einfügt, damit CI erfolgreich ist. Eine Datei, die nur zur Zufriedenstellung eines automatisierten Systems geändert wurde, ist weniger wert als gar keine Datei. Die Warnung liefert dem Reviewer eine Frage, die er stellen kann. Genau das ist der Teil, der tatsächlich funktioniert.

Wie erkenne ich, dass eine AGENTS.md veraltet ist?

Sie können heute zwei Prüfungen ausführen. Außerdem gibt es ein Symptom, das Sie innerhalb einer Sitzung sehen werden.

Vergleichen Sie das Alter jeder Datei mit dem Alter des beschriebenen Codes. %cs gibt das Commit-Datum als YYYY-MM-DD aus.

for f in $(git ls-files '*AGENTS.md'); do
  d=$(dirname "$f")
  printf '%s  doc:%s  code:%s\n' "$f" \
    "$(git log -1 --format=%cs -- "$f")" \
    "$(git log -1 --format=%cs -- "$d")"
done
apps/web/AGENTS.md          doc:2026-02-11  code:2026-08-07
services/worker/AGENTS.md   doc:2026-07-29  code:2026-08-09
infra/AGENTS.md             doc:2026-08-01  code:2026-08-01

Ein Dokumentdatum, das sechs Monate hinter dem Codedatum liegt, beweist nicht, dass die Datei falsch ist. Es zeigt Ihnen, welche Datei Sie zuerst lesen sollten. Mehr benötigen Sie von einer Prüfung, die eine Sekunde dauert, nicht.

Suchen Sie nach Pfaden, die nicht mehr existieren. Dokumentation veraltet auf eine ganz bestimmte Weise: Sie beschreibt weiterhin Code, der gelöscht wurde. Jeder Pfad in diesen Dateien steht in Backticks. Dadurch lassen sich die Pfade einfach extrahieren und prüfen.

grep -o '`[^`]*`' apps/web/AGENTS.md | tr -d '`' | grep '/' | while read -r p; do
  [ -e "$p" ] || [ -e "apps/web/$p" ] || echo "missing: $p"
done

Lesen Sie die Ausgabe, anstatt diese Prüfung in CI einzubinden. Sie markiert auch Globs wie src/**/*.ts und jede von Ihnen zitierte URL, weil beide einen Schrägstrich enthalten und keine Datei auf der Festplatte sind. Ab Claude Code v2.1.283 führt /doctor prompt-audit eine ähnliche Prüfung für Sie aus: Es sucht nach „Verweisen auf Dateien oder Befehle, die nicht existieren“ sowie nach Dateien, die sich gegenseitig widersprechen, berücksichtigt standardmäßig Ihre AGENTS.md-Dateien und nimmt keine Änderungen vor, bis Sie es auffordern, die vorgeschlagenen Änderungen anzuwenden.

Das Symptom in einer Sitzung. Der Agent liest die Datei und versucht, src/api/client.ts zu öffnen, weil die Datei ihn dazu auffordert. Das Tool gibt Folgendes zurück:

No such file or directory

Also schreibt er seine eigene fetch-Wrapper-Implementierung. Das sind die tatsächlichen Kosten einer veralteten Datei. Der Agent ignoriert Ihre Dokumentation nicht. Er folgt ihr, landet auf einem Pfad, der vor drei Monaten gelöscht wurde, und erstellt Code neu, den Sie bereits haben. Eine Fähigkeit wie Ponytail, die den Agenten auf die kleinste funktionierende Änderung festlegt, macht diesen Drang zur Neuerstellung seltener. Sie kann jedoch keinen Helper finden, auf den Ihre Datei an der falschen Stelle verwiesen hat.

Liest Claude Code AGENTS.md-Dateien?

Ja, ab Claude Code v2.1.277. Die exakte Regel ist wichtig, da das verschachtelte Layout davon abhängt. Überprüft anhand der Dokumentation vom 27. Oktober 2026: "Claude Code kann AGENTS.md als Ihre Projektanweisungen lesen, sodass ein Repository, das bereits für andere Coding-Agents eingerichtet ist, ohne das Hinzufügen einer CLAUDE.md, eines Imports oder einer Einstellung funktioniert." Der Standardwert für Project instructions, claude-md-or-agents-md, lautet: "Ihre AGENTS.md-Dateien, wenn Sie keine CLAUDE.md oder CLAUDE.local.md in Ihrem Arbeitsverzeichnis oder darüber haben." Verschachtelte Dateien werden ebenfalls berücksichtigt: Claude liest die AGENTS.md eines Unterverzeichnisses, "wenn Claude dort eine Datei mit dem Read-Tool öffnet", sofern "dieses Unterverzeichnis keine der drei eigenen CLAUDE.md-Dateien besitzt". Diese drei sind CLAUDE.md, .claude/CLAUDE.md und CLAUDE.local.md. Eine persönliche CLAUDE.local.md in apps/web reicht also aus, um das Laden von apps/web/AGENTS.md zu verhindern.

Das macht den alten Rat, eine CLAUDE.md neben jede AGENTS.md zu legen, zu einer Falle. Mit einer AGENTS.md und einer CLAUDE.md oder CLAUDE.local.md in Ihrem Arbeitsverzeichnis oder darüber liest Claude laut Dokumentation "nur Ihre CLAUDE.md-Dateien". Eine .claude/CLAUDE.md zählt auf die gleiche Weise. Eine Begleitdatei im Stammverzeichnis, die eine einzelne Claude-spezifische Zeile enthält, verbirgt jede AGENTS.md auf dem Pfad, und eine persönliche CLAUDE.local.md bewirkt dasselbe. Wenn Sie eine behalten möchten, geben Sie /config ein und setzen Sie Project instructions auf claude-md-and-agents-md, was beides liest, zuerst die CLAUDE.md des jeweiligen Verzeichnisses und danach dessen AGENTS.md.

Eine Versionsnummer allein bestätigt nicht, dass es funktioniert hat. Sie benötigen v2.1.277 oder höher, aber vor v2.1.281 lesen einige Sitzungen, wie solche auf Amazon Bedrock oder bei deaktivierter Telemetrie, nur CLAUDE.md-Dateien. In einigen Fällen überspringt auch die erste Sitzung nach einem Upgrade von v2.1.276 oder früher AGENTS.md: Die Dokumentation besagt: "Claude liest AGENTS.md ab Ihrer nächsten Sitzung". Überprüfen Sie also die Sitzung selbst. In einer interaktiven Sitzung gibt Claude Code eine Zeile wie no CLAUDE.md found; AGENTS.md loaded: gefolgt vom Pfad aus, und in aktuellen Versionen listet /memory die Datei auf. Vor v2.1.280 listeten /memory und /context keine AGENTS.md auf, die Claude direkt gelesen hat. Fragen Sie auf diesen Versionen also Claude, was seine Projektanweisungen besagen.

Die Import-Form ist immer noch korrekt, wenn Claude AGENTS.md nicht direkt lesen kann: eine ältere Version, eine Sitzung vor v2.1.281 auf Amazon Bedrock oder mit deaktivierter Telemetrie, eine Sitzung, in der das integrierte Plugin zum Lesen deaktiviert ist, oder ein Projekt, das eine CLAUDE.md mit auf claude-md gesetzten Project instructions beibehält. Fügen Sie dies in services/worker/CLAUDE.md ein:

@AGENTS.md

## Claude Code

Use plan mode for changes under `services/worker/migrations/`.

Die Symlink-Form ist korrekt, wenn nichts Tool-spezifisches hinzuzufügen ist.

git ls-files '*AGENTS.md' | while read -r f; do
  ln -s AGENTS.md "$(dirname "$f")/CLAUDE.md"
done
ls -l apps/web/CLAUDE.md

ln gibt bei Erfolg nichts aus, prüfen Sie also die Auflistung: apps/web/CLAUDE.md -> AGENTS.md. Starten Sie dann eine Sitzung und führen Sie /context aus, wobei die geladenen Dateien unter Memory files erscheinen. Unter Windows erfordert ein Symlink Administratorrechte oder den Entwicklermodus, und Git checkt einen committeten Symlink als einfache Textdatei aus, sofern core.symlinks nicht aktiviert ist, was diesen Klon mit einer einzeiligen CLAUDE.md anstelle Ihrer Anweisungen hinterlässt. Wenn jemand, der das Repository klont, unter Windows arbeitet, verwenden Sie stattdessen den @AGENTS.md-Import. Wenn Sie eine der beiden Problemumgehungen eingerichtet haben, bevor Claude Code AGENTS.md von selbst lesen konnte, können Sie sie beibehalten: Die Dokumentation besagt, dass das Beibehalten des Imports "Claude niemals dazu bringt, AGENTS.md zweimal zu lesen", und eine verlinkte CLAUDE.md wird einmal gelesen.

Eine Falle ist damit verbunden. Nach /compact wird die CLAUDE.md im Projektstammverzeichnis neu von der Festplatte gelesen, aber verschachtelte Dateien in Unterverzeichnissen werden nicht erneut injiziert. Claude Code lädt sie bei Bedarf neu, wenn der Agent das nächste Mal mit einer Datei in diesem Verzeichnis arbeitet. Die Dokumentation erläutert dies für CLAUDE.md-Dateien und beschreibt die Komprimierung nicht separat für eine direkt gelesene AGENTS.md, erwarten Sie also, dass sich verschachtelte Dateien beider Namen auf diese Weise verhalten. Wenn eine verzeichnisspezifische Regel mitten in einer langen Sitzung nicht mehr zu gelten scheint, ist dies normalerweise der Grund, und das Lesen einer beliebigen Datei im Verzeichnis stellt sie wieder her.

Einstellungen, die andere Agents auf AGENTS.md verweisen

Codex liest AGENTS.md nativ. Auf jeder Ebene prüft es zuerst auf AGENTS.override.md, was einem Verzeichnis eine lokale Überschreibung ermöglicht, ohne die freigegebene Datei zu bearbeiten. Es stoppt die Zusammenführung, sobald die kombinierte Größe 32 KiB erreicht, den Standardwert project_doc_max_bytes, was ein weiterer Grund ist, die Stammdatei klein zu halten.

Aider übernimmt dies über .aider.conf.yml mit der Zeile read: AGENTS.md.

Gemini CLI übernimmt dies über .gemini/settings.json mit { "context": { "fileName": "AGENTS.md" } }.

Upstream dokumentiert eine abwärtskompatible Umbenennung für Repositories, die noch den älteren, singulären Namen verwenden: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md.

In einem sehr großen Monorepo überspringt die Einstellung claudeMdExcludes von Claude Code übergeordnete Dateien nach Pfad oder Glob, was nützlich ist, wenn sich das Verzeichnis eines anderen Teams über Ihrem befindet. Seine Muster gelten auch für die AGENTS.md-Dateien, die Claude Code liest.

Wie unterscheidet sich das von dem Agentenspeicher oder von einem Skill?

Diese Mechanismen sehen ähnlich aus und scheitern aus völlig unterschiedlichen Gründen. Deshalb sollten Sie genau unterscheiden, welchen Mechanismus Sie benötigen.

AGENTS.md wird von Ihnen geschrieben, in git committet, in einem Pull Request geprüft und ist für alle Personen identisch, die das Repository klonen. Der Agentenspeicher wird vom Agenten geschrieben, außerhalb des Repositorys gespeichert und gilt nur für einen Rechner. Die Dokumentation von Claude Code zieht dieselbe Grenze: CLAUDE.md enthält von Ihnen verfasste „Anweisungen und Regeln“, während der automatische Speicher von Claude verfasste „Erkenntnisse und Muster“ enthält. Das Speicherverzeichnis wird nicht zwischen Rechnern gemeinsam verwendet. Der Test ist einfach: Wenn eine Information auch für einen Kollegen in einem frisch geklonten Repository gelten muss, darf sie nicht im Speicher liegen. So bleibt der Agentenspeicher zwischen Sitzungen erhalten behandelt diesen Teil des Themas.

Ein Skill ist der dritte Mechanismus. AGENTS.md enthält Kontext, der in jeder Sitzung geladen wird. Ein Skill enthält eine Prozedur, die bei Bedarf geladen wird. Die Dokumentation von Claude Code liefert dafür eine brauchbare Regel: „Wenn ein Eintrag eine mehrstufige Prozedur ist oder nur für einen Teil der Codebasis relevant ist, verschieben Sie ihn in einen Skill oder eine pfadbezogene Regel.“ Der zweite Teil dieses Satzes beschreibt genau den Anwendungsfall für eine verschachtelte AGENTS.md. Der erste Teil beschreibt, wofür Agent-Skills gedacht sind. Wenn dieselbe Prozedur in mehreren Repositorys benötigt wird, sollten Sie den Skill für mehrere Repositorys freigeben, statt dieselben Absätze in zehn verschiedene AGENTS.md-Dateien zu kopieren.

Im Upstream-Hinweis steht: „Zum Zeitpunkt der Erstellung dieses Dokuments enthält das zentrale OpenAI-Repository 88 AGENTS.md-Dateien.“ Diese Zahl ist das zentrale Argument. Ein großes Repository benötigt keine größere Datei. Es benötigt mehr kleine Dateien. Jede Datei sollte neben dem beschriebenen Code liegen und von der Person gepflegt werden, die diesen Code zuletzt geändert hat.

FAQ

Ersetzt eine verschachtelte AGENTS.md die Root-Datei oder ergänzt sie diese?

Sie ergänzt sie. Laut Upstream gilt „die nächstgelegene Datei hat Vorrang“; dies beschreibt das Verhalten bei Konflikten, nicht den Ladevorgang. Codex „verknüpft Dateien von der Root abwärts und fügt sie mit Leerzeilen zusammen“, und Claude Code verknüpft jede Datei, die es beim Durchlaufen des Verzeichnisbaums vom Arbeitsverzeichnis aus findet, anstatt sie zu überschreiben. Die nächstgelegene Datei gewinnt nur dort, wo zwei Dateien unterschiedliche Anweisungen zum selben Thema enthalten. Schreiben Sie gemeinsame Regeln einmal in die Root-Datei und wiederholen Sie diese nicht in jedem Verzeichnis.

Wie groß sollte die Root-Datei AGENTS.md sein?

So klein, dass es Sie nicht stört, wenn sie bei jeder Anfrage, die Sie in diesem Repository stellen, vorangestellt wird, denn genau das passiert. Die Dokumentation von Claude Code empfiehlt eine Länge von unter 200 Zeilen pro Datei und warnt, dass längere Dateien die „Einhaltung verringern“. Codex beendet das Zusammenführen von Anweisungsdateien standardmäßig bei 32 KiB Gesamtgröße. Wenn Ihre Root-Datei vier Dienste dokumentiert, ist der Großteil davon für eine einzelne Aufgabe unnötiger Ballast. Verlagern Sie Details in verzeichnisspezifische Dateien und hinterlassen Sie in der Root-Datei einen Verweis darauf.

Wie verhindere ich, dass diese Dateien veralten?

Fügen Sie eine Regel in die Root-Datei ein: Wer Code in einem Verzeichnis ändert, aktualisiert im selben Commit auch die AGENTS.md dieses Verzeichnisses. Die Datei direkt neben dem Code zu platzieren, sorgt für die Einhaltung der Regel, da die Änderung dann im selben Pull-Request-Diff landet, den ein Mensch ohnehin prüft. Fügen Sie eine CI-Warnung hinzu, die jeden geänderten Pfad der nächstgelegenen AGENTS.md darüber zuordnet, und vergleichen Sie regelmäßig git log -1 --format=%cs für jede Datei mit demselben Befehl, der für das von ihr dokumentierte Verzeichnis ausgeführt wird.

Liest Claude Code AGENTS.md-Dateien?

Ja, ab v2.1.277. Überprüft anhand der Dokumentation am 27. Oktober 2026: Claude Code liest standardmäßig AGENTS.md, wenn Sie keine CLAUDE.md oder CLAUDE.local.md in Ihrem Arbeitsverzeichnis oder darüber haben. Es liest die AGENTS.md eines Unterverzeichnisses, wenn es dort eine Datei mit dem Read-Tool öffnet und dieses Unterverzeichnis keine eigene CLAUDE.md, .claude/CLAUDE.md oder CLAUDE.local.md besitzt. Fügen Sie nicht neben jede AGENTS.md eine CLAUDE.md hinzu: Wenn eine Datei im oder oberhalb des Arbeitsverzeichnisses liegt, liest Claude „Ihre CLAUDE.md-Dateien nur“. Wenn Sie zusätzlich eine CLAUDE.md benötigen, setzen Sie Project instructions in /config auf claude-md-and-agents-md oder fügen Sie @AGENTS.md in die erste Zeile ein. Führen Sie /memory in einer Sitzung aus und bestätigen Sie, dass der Pfad AGENTS.md in der Liste erscheint.

Wo platziere ich eine Regel, die nur manchmal relevant ist?

Nicht in der AGENTS.md. Diese Datei wird in jeder Sitzung geladen, daher konkurriert jede Zeile darin mit der Anfrage, die Sie tatsächlich eingegeben haben. Ein Verfahren mit mehreren Schritten, das nur gelegentlich benötigt wird, gehört in einen Skill, der bei Bedarf geladen wird. Eine Regel, die für ein einzelnes Verzeichnis gilt, gehört in die AGENTS.md dieses Verzeichnisses. Ein Fakt, den der Agent direkt aus dem Code lesen kann, wie etwa der Verzeichnisbaum oder die Abhängigkeitsliste, gehört in keine der beiden.

War dieser Artikel hilfreich?