AGENTS.md im Monorepo richtig verschachteln

Was verschachtelte AGENTS.md-Dateien in einem Monorepo bedeuten

Verschachtelte AGENTS.md-Dateien in einem Monorepo bestehen aus einer kleinen Datei im Repository-Stammverzeichnis und einer weiteren Datei in jedem Dienstverzeichnis. Die Datei im Stammverzeichnis enthält die wenigen Regeln, die überall gelten, sowie eine Übersicht darüber, wo sich die anderen Dateien befinden. Jede dienstspezifische Datei enthält die Befehle und Konventionen, die nur für dieses Verzeichnis gelten. Ein Agent, der services/worker/queue.py bearbeitet, liest anschließend die Datei im Stammverzeichnis und die Datei für den Worker. Für das Frontend, das er nicht bearbeitet, wird kein Kontext verbraucht.

Es muss nichts installiert werden. AGENTS.md ist eine Konvention. Das Upstream-Projekt formuliert es eindeutig:

AGENTS.md ist einfach standardmäßiges 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 wird sich nicht ändern. Probleme entstehen bei der Platzierung und Pflege. Für beides sind Sie verantwortlich.

Warum funktioniert eine einzige große root AGENTS.md nicht mehr?

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

Sie veraltet, weil niemand dafür verantwortlich ist. Der Engineer, der ein Testskript in apps/web umbenennt, bearbeitet Dateien unter apps/web. Die root AGENTS.md 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. Die Person, die ihn entfernt 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 anfordern werden. Die Dokumentation von Claude Code nennt dafür eine konkrete Empfehlung: „target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.“ Codex verarbeitet keine weiteren Anweisungsdateien mehr, sobald ihre kombinierte Größe 32 KiB erreicht, den Standardwert project_doc_max_bytes. Eine root-Datei, die vier Dienste dokumentiert, verbraucht dieses Budget bei jeder einzelnen Aufgabe zu drei Vierteln für Dienste, die gerade nicht relevant sind.

Anweisungen beginnen, sich zu widersprechen. Das Webverzeichnis benötigt pnpm test. Der Worker benötigt pytest -q. In einer gemeinsamen Datei ist jede Regel nur unter bestimmten Bedingungen korrekt. Daher muss der Agent raten, welche Regel gilt. Die Dokumentation von Claude Code beschreibt das Ergebnis so: „if two rules contradict each other, Claude may pick one arbitrarily.“ Eine Datei pro Verzeichnis beseitigt diese Unklarheit, weil immer nur eine der beiden Regeln im Kontext steht. Wenn eine Regel, die Sie nach eigener Einschätzung eindeutig formuliert haben, trotzdem übersprungen wird, ist es sinnvoller, die Gründe zu prüfen, warum eine Anweisung nie greift, als den Wortlaut ein viertes Mal zu überarbeiten.

Sie füllt sich mit Fakten, 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 entfernt genau solche Inhalte. 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 festzustellen, ob eine Zeile überhaupt in die Datei gehört.

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

Hier liegt das häufigste Missverständnis zum Verhalten des Modells. Deshalb ist es sinnvoll, die Konvention aus der Upstream-Dokumentation zu zitieren, statt sie nur sinngemäß wiederzugeben:

Legen Sie in jedem Paket eine weitere AGENTS.md ab. Agents lesen automatisch die nächstgelegene Datei im Verzeichnisbaum. Daher hat die nächstgelegene Datei Vorrang, und jedes Teilprojekt kann eigene Anweisungen enthalten.

Für Konflikte gilt:

Die AGENTS.md, die sich am nächsten an der bearbeiteten Datei befindet, hat Vorrang. Explizite Benutzeranweisungen im Chat überschreiben alle anderen Vorgaben.

„Hat Vorrang“ wird häufig so verstanden, dass die Root-Datei ignoriert wird. Das ist nicht der Fall. In den Tools, die diese Konvention implementieren, wird jede Datei vom Repository-Root bis zum Arbeitsverzeichnis gelesen und zusammengeführt. Die nächstgelegene Datei hat nur dann Vorrang, wenn zwei Dateien unterschiedliche Vorgaben zum selben Thema enthalten.

Codex beschreibt den Mechanismus ausdrücklich: „Codex hängt die Dateien vom Root aus nach unten aneinander und trennt sie durch Leerzeilen. Dateien, die näher am aktuellen Verzeichnis liegen, überschreiben frühere Vorgaben.“ Claude Code durchläuft denselben Pfad für seinen eigenen Dateinamen. Dateien in der Verzeichnishierarchie oberhalb des Arbeitsverzeichnisses „werden beim Start vollständig geladen“, und „alle gefundenen Dateien werden in den Kontext zusammengeführt, statt einander zu überschreiben“. Verzeichnisse unterhalb des Arbeitsverzeichnisses verhalten sich anders: Claude Code lädt diese Dateien bei Bedarf, „wenn Claude Dateien in diesen Verzeichnissen liest“.

Daraus ergeben sich zwei praktische Konsequenzen. Die Root-Datei ist in jeder Sitzung im Repository ein Präfix. Behandeln Sie daher jede Zeile dort als eine Zeile, deren Kosten Sie pro Woche hundertmal tragen. Eine Datei pro Verzeichnis verursacht keine Kosten, wenn der Agent an einem anderen Ort arbeitet. Details sind dort daher günstig und sollten dort stehen.

Dieses Verhalten wurde im August 2026 anhand der Dokumentation zu Codex und Claude Code geprüft. Die Tools implementieren die Konvention teilweise unterschiedlich und ändern ihr Verhalten. Prüfen Sie daher die Regeln zum Laden der Dateien für den Agent, den Ihr Team verwendet.

Ein beispielhafter Aufbau 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.

Die Datei für das jeweilige Verzeichnis enthält die Details. Ihre Länge richtet sich nach den Anforderungen des Verzeichnisses.

# 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 Infra-Datei stehen die Regeln, die verhindern, dass ein Agent Schaden anrichtet. Führen Sie terraform apply niemals aus. Führen Sie terraform plan aus und beenden Sie die Aktion danach. 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 gedacht. Upstream zieht dieselbe Grenze und sagt: „README.md-Dateien sind für Menschen gedacht: für Schnellstarts, Projektbeschreibungen und Richtlinien für Beiträge“, während AGENTS.md „den zusätzlichen, manchmal detaillierten Kontext enthält, den Coding-Agenten benötigen: Build-Schritte, Tests und Konventionen“. Die Aufteilung zwischen AGENTS.md und einer an Menschen gerichteten README geht diese Grenze Satz für Satz durch. Eine DESIGN.md, die festhält, warum der Code so aufgebaut ist behandelt die dritte Datei, die Entscheidungen statt Befehle erklärt.

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

Eine Regel genügt. 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. Das bedeutet, dass sie niemandem gehört und nie in dem Diff enthalten ist, den jemand ohnehin gerade prüft.

Hinterlegen Sie für den Pull Request eine Prüfung. 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

Bei einem Branch, in dem der API-Client überarbeitet wurde, ohne die Dokumentation zu ändern, sieht die Ausgabe so aus:

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

Lassen Sie die Prüfung eine Warnung statt eines Fehlers ausgeben. Eine harte Sperre bringt die Menschen dazu, eine leere Zeile in die Datei einzufügen, damit CI erfolgreich durchläuft. Eine Datei, die nur zur Zufriedenheit eines Roboters geändert wurde, ist weniger wert als gar keine Datei. Die Warnung liefert dem Reviewer eine Frage. Genau dieser Teil funktioniert in der Praxis.

Woran erkennen Sie eine veraltete AGENTS.md-Datei?

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

Vergleichen Sie das Alter jeder Datei mit dem Alter des von ihr 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. Für eine Prüfung, die eine Sekunde dauert, ist das bereits ausreichend.

Suchen Sie nach Pfaden, die nicht mehr existieren. Dokumentation veraltet auf eine ganz bestimmte Weise: Sie beschreibt weiterhin gelöschten Code. Jeder Pfad in diesen Dateien steht in Backticks. Daher können Sie 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, statt diese Prüfung in CI einzubinden. Sie markiert auch Globs wie src/**/*.ts und jede von Ihnen angegebene URL, weil beide einen Schrägstrich enthalten und keine davon eine Datei auf der Festplatte ist.

Das Symptom innerhalb 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

Daraufhin führt er vernünftigerweise seinen eigenen fetch-Wrapper ein. Das sind die tatsächlichen Kosten einer veralteten Datei. Der Agent ignoriert Ihre Dokumentation nicht. Er folgt ihr, landet bei einem Pfad, der vor drei Monaten gelöscht wurde, und erstellt Code neu, den Sie bereits besitzen. Eine Fähigkeit wie Ponytail, die den Agenten auf die kleinste funktionierende Änderung beschränkt, verringert diesen Drang zur Neuerstellung. Sie kann jedoch keinen Helper finden, auf den Ihre Datei am falschen Ort verwiesen hat.

Liest Claude Code AGENTS.md-Dateien?

Nein. Das sollte ausdrücklich erwähnt werden, weil das verschachtelte Layout davon abhängt. Laut Dokumentation gilt im August 2026: „Claude Code liest CLAUDE.md, nicht AGENTS.md.“ Das Muster funktioniert weiterhin. Sie benötigen lediglich neben jeder AGENTS.md-Datei eine CLAUDE.md-Datei.

Die Importform ist geeignet, wenn Sie zusätzlich zu den gemeinsamen Zeilen tool-spezifische Zeilen benötigen. 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 geeignet, wenn keine tool-spezifischen Ergänzungen erforderlich sind.

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 daher die Auflistung mit apps/web/CLAUDE.md -> AGENTS.md. Starten Sie anschließend eine Sitzung und führen Sie /context aus. Die geladenen Dateien erscheinen unter Memory files. Unter Windows benötigen Sie für einen Symlink Administratorrechte oder den Entwicklermodus. Verwenden Sie dort stattdessen den Import mit @AGENTS.md.

Ein weiterer wichtiger Punkt betrifft /compact. Die Root-Datei wird danach erneut von der Festplatte gelesen. Verschachtelte Dateien in Unterverzeichnissen werden jedoch nicht erneut geladen. Sie werden beim nächsten Lesen einer Datei in diesem Verzeichnis wieder geladen. Wenn eine Regel für ein bestimmtes Verzeichnis während einer langen Sitzung scheinbar nicht mehr angewendet wird, ist das normalerweise der Grund. Durch das Ändern einer beliebigen Datei in diesem Verzeichnis wird die Regel erneut geladen.

Wie unterscheidet sich das von dem Gedächtnis eines Agents oder von einem Skill?

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

AGENTS.md wird von Ihnen geschrieben, in git versioniert, in einem Pull Request geprüft und ist für alle Personen identisch, die das Repository klonen. Das Gedächtnis des Agents wird vom Agent geschrieben, außerhalb des Repositorys gespeichert und ist lokal auf einen Rechner beschränkt. Die Dokumentation von Claude Code zieht dieselbe Grenze: CLAUDE.md enthält „Anweisungen und Regeln“, die Sie schreiben, das automatische Gedächtnis enthält „Erkenntnisse und Muster“, die Claude schreibt, und das Gedächtnisverzeichnis wird nicht zwischen Rechnern geteilt. Der Test ist einfach. Wenn eine Tatsache für einen Kollegen bei einem frischen Clone gelten muss, darf sie nicht im Gedächtnis gespeichert werden. Wie das Gedächtnis eines Agents zwischen Sitzungen erhalten bleibt behandelt diesen Teil des Themas.

Ein Skill ist der dritte Mechanismus. AGENTS.md wird in jeder Sitzung geladen. Ein Skill wird geladen, wenn er benötigt wird. Die Dokumentation von Claude Code enthält dafür eine brauchbare Regel: „Wenn ein Eintrag ein mehrstufiges Verfahren 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 das, was eine verschachtelte AGENTS.md löst. Der erste Teil ist der Zweck von Agent-Skills. Wenn dasselbe Verfahren in mehreren Repositorys benötigt wird, sollten Sie den Skill repositoryübergreifend teilen, statt dieselben Absätze in zehn verschiedene AGENTS.md-Dateien zu kopieren.

Im Upstream-Projekt heißt es: „Zum Zeitpunkt der Erstellung dieses Textes enthält das zentrale OpenAI-Repository 88 AGENTS.md-Dateien.“ Diese Zahl ist das entscheidende Argument. Ein großes Repository benötigt keine größere Datei. Es benötigt mehr kleine Dateien. Jede davon sollte neben dem Code liegen, den sie beschreibt, und der Person gehören, die diesen Code zuletzt geändert hat.

FAQ

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

Sie ergänzt sie. In der Upstream-Dokumentation steht: „Die Datei mit dem kürzesten Pfad hat Vorrang.“ Das beschreibt, was bei einem Konflikt geschieht, nicht, welche Dateien geladen werden. Codex „verkettet Dateien vom Stammverzeichnis nach unten und verbindet sie mit Leerzeilen“. Claude Code verkettet ebenfalls jede Datei, die es auf dem Weg vom Arbeitsverzeichnis nach oben findet, statt sie zu überschreiben. Die Datei mit dem kürzesten Pfad hat nur dann Vorrang, wenn zwei Dateien unterschiedliche Anweisungen zum selben Thema enthalten. Legen Sie gemeinsame Regeln einmal im Stammverzeichnis fest, und wiederholen Sie sie nicht in jedem Verzeichnis.

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

Sie sollte so klein sein, dass es Sie nicht stören würde, wenn sie jeder Anfrage vorangestellt wird, die Sie in diesem Repository stellen. Genau das geschieht. Die Dokumentation von Claude Code empfiehlt, weniger als 200 Zeilen pro Datei anzustreben, und warnt, dass längere Dateien „die Befolgung verringern“. Codex beendet das Zusammenführen von Anweisungsdateien standardmäßig bei insgesamt 32 KiB. Wenn Ihre Datei im Stammverzeichnis vier Dienste dokumentiert, ist der größte Teil davon für eine einzelne Aufgabe irrelevant. Verschieben Sie die Details in Dateien der jeweiligen Verzeichnisse, und hinterlassen Sie eine Übersicht.

Wie verhindere ich, dass diese Dateien veralten?

Legen Sie in der Datei im Stammverzeichnis eine Regel fest: Wer Code in einem Verzeichnis ändert, aktualisiert die AGENTS.md-Datei dieses Verzeichnisses im selben Commit. Die Datei neben dem Code abzulegen, sorgt dafür, dass diese Regel eingehalten wird, weil die Änderung dann im selben Pull-Request-Diff landet, den eine Person ohnehin prüft. Fügen Sie eine CI-Warnung hinzu, die jeden geänderten Pfad der nächstgelegenen darüberliegenden AGENTS.md-Datei zuordnet. Vergleichen Sie außerdem in regelmäßigen Abständen git log -1 --format=%cs für jede Datei mit demselben Befehl, der im dokumentierten Verzeichnis ausgeführt wird.

Liest Claude Code AGENTS.md-Dateien?

Nein. Stand August 2026 steht in der Dokumentation: „Claude Code liest CLAUDE.md, nicht AGENTS.md.“ Erstellen Sie im selben Verzeichnis eine CLAUDE.md-Datei mit @AGENTS.md in der ersten Zeile. Dadurch wird die gemeinsame Datei geladen, und Sie können darunter Claude-spezifische Anweisungen ergänzen. Ein mit ln -s AGENTS.md CLAUDE.md erstellter symbolischer Link funktioniert, wenn keine zusätzlichen Anweisungen erforderlich sind. Unter Windows benötigen Sie dafür jedoch Administratorrechte oder den Entwicklermodus. Führen Sie in einer Sitzung /context aus, und prüfen Sie, ob die Datei unter „Speicherdateien“ angezeigt wird.

Wo lege ich eine Regel ab, die nur manchmal relevant ist?

Nicht in AGENTS.md. Diese Datei wird in jeder Sitzung geladen. Dadurch konkurriert jede Zeile darin mit der Anfrage, die Sie tatsächlich eingegeben haben. Eine mehrstufige Vorgehensweise, die 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-Datei dieses Verzeichnisses. Eine Information, die der Agent direkt aus dem Code lesen kann, beispielsweise die Verzeichnisstruktur oder die Abhängigkeitsliste, gehört in keine der beiden Dateien.