Verschachtelte AGENTS.md im Monorepo richtig nutzen

Bedeutung verschachtelter AGENTS.md-Dateien in einem Monorepo

Verschachtelte AGENTS.md-Dateien in einem Monorepo bedeuten, dass eine kleine Datei im Repository-Stammverzeichnis und jeweils eine weitere Datei im Verzeichnis jedes Dienstes liegt. Die Datei im Stammverzeichnis enthält die wenigen Regeln, die überall gelten, sowie eine Übersicht darüber, wo sich die anderen Dateien befinden. 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.

Es muss nichts installiert werden. AGENTS.md ist eine Konvention. Das Upstream-Projekt erklärt dies ausdrücklich:

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 wird sich nicht unerwartet ändern. Probleme entstehen durch die Ablage und die Pflege. Für beides sind Sie verantwortlich.

Warum funktioniert eine einzige große AGENTS.md im Root-Verzeichnis nicht?

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

Sie veraltet, weil niemand für sie verantwortlich ist. Der Engineer, der ein Testskript in apps/web umbenennt, bearbeitet Dateien unter apps/web. Die AGENTS.md im Root-Verzeichnis 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 beschädigt hat, hat die Änderung inzwischen vergessen.

Sie verbraucht bei jeder Aufgabe Kontext. Diese Dateien werden zu Beginn der Sitzung geladen, bevor der Agent weiß, was Sie fragen 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 beendet das Zusammenführen von Anweisungsdateien, sobald deren 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 dieser Dienste.

Anweisungen beginnen, sich zu widersprechen. Das Web-Verzeichnis benötigt pnpm test. Der Worker benötigt pytest -q. In einer gemeinsamen Datei ist jede Regel nur unter bestimmten Bedingungen korrekt. Der Agent muss daher erraten, 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.

Sie füllt sich mit Informationen, die der Agent aus dem Code lesen kann. Dazu gehören eine Verzeichnisstruktur, eine Liste der Abhängigkeiten und eine Zusammenfassung der Aufgaben der einzelnen Pakete. Der /doctor-Check von Claude Code dient genau dazu, solche Inhalte zu entfernen. Er "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 Datei im Root-Verzeichnis oder nur die nächstgelegene?

Hier liegt das häufigste Missverständnis vor. Deshalb ist es sinnvoll, die Konvention der Upstream-Dokumentation wörtlich zu zitieren, statt sie nur zusammenzufassen:

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

Zu Konflikten heißt es:

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 von vielen so verstanden, dass die Datei im Root-Verzeichnis 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 gewinnt nur dann, wenn zwei Dateien unterschiedliche Vorgaben zum selben Thema enthalten.

Codex beschreibt den Mechanismus ausdrücklich: „Codex verkettet Dateien vom Root-Verzeichnis aus nach unten und trennt sie durch Leerzeilen. Dateien, die näher am aktuellen Verzeichnis liegen, überschreiben frühere Vorgaben.“ Claude Code durchläuft für seinen eigenen Dateinamen denselben Pfad. Dateien in den Verzeichnissen oberhalb des Arbeitsverzeichnisses „werden beim Start vollständig geladen“, und „alle gefundenen Dateien werden in den Kontext verkettet, statt sich gegenseitig 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 Datei im Root-Verzeichnis ist in jeder Sitzung des Repositorys ein Präfix. Behandeln Sie daher jede Zeile dort so, als würden Sie sie pro Woche hundertmal bezahlen. Eine Datei in einem einzelnen Verzeichnis verursacht keine Kosten, wenn der Agent an einer anderen Stelle arbeitet. Ausführliche Vorgaben sind dort daher günstig und sollten dort abgelegt werden.

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

Beispielaufbau 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 vor, wo gesucht werden soll, und enthält nur die Regeln, die für jedes 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. Sie kann so lang sein, wie es für dieses Verzeichnis erforderlich ist.

# 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 denselben Aufbau, aber andere Inhalte: den Installationsbefehl, pytest -q, den Grund, warum der Consumer idempotent bleiben muss, sowie 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 niemals terraform apply aus. Führen Sie terraform plan aus und beenden Sie den Vorgang 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 enthalten ist: eine Beschreibung des Zwecks der einzelnen Dienste. Das ist für Menschen bestimmt. Upstream zieht dieselbe Grenze und erklärt: „README.md-Dateien sind für Menschen bestimmt: Kurzanleitungen, Projektbeschreibungen und Richtlinien für Beiträge“, während AGENTS.md „den zusätzlichen, teilweise detaillierten Kontext enthält, den Coding-Agenten benötigen: Build-Schritte, Tests und Konventionen“. Die Aufteilung zwischen AGENTS.md und einer auf Menschen ausgerichteten README erläutert diese Grenze Satz für Satz. 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, und sie gehört in die Datei im Stammverzeichnis: 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 Stammverzeichnis gehört allen. Das bedeutet, dass sie niemandem gehört. Außerdem ist sie nie Teil des Diffs, den gerade jemand prüft.

Hinterlegen Sie diese Regel mit einer Prüfung im Pull Request. Die Prüfung sucht für jede geänderte Datei nach der nächsten 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 zu ändern, 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 bringt die Leute dazu, eine leere Zeile in die Datei einzufügen, damit CI erfolgreich ist. 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, die er stellen kann. Genau das funktioniert in der Praxis.

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 innerhalb einer Sitzung sichtbar wird.

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 vor dem Codedatum liegt, beweist nicht, dass die Datei falsch ist. Es zeigt Ihnen, welche Datei Sie zuerst lesen sollten. Mehr müssen Sie von einer Prüfung, die eine Sekunde dauert, nicht erwarten.

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 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 erkennt auch Globs wie src/**/*.ts und jede von Ihnen angegebene URL, weil beide einen Schrägstrich enthalten und keine Datei auf der Festplatte sind.

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

Der Agent führt deshalb die naheliegende Aktion aus und schreibt einen eigenen fetch-Wrapper. Das sind die tatsächlichen Kosten einer veralteten Datei. Der Agent ignoriert Ihre Dokumentation nicht. Er folgt der Dokumentation, landet bei einem Pfad, der vor drei Monaten gelöscht wurde, und erstellt Code neu, den Sie bereits haben. Ein Skill wie Ponytail, der den Agenten auf die kleinste funktionierende Änderung beschränkt, macht diesen Drang zur Neuerstellung seltener. Er kann jedoch keinen Helper finden, auf den Ihre Datei an der falschen Stelle verwiesen hat.

Liest Claude Code AGENTS.md-Dateien?

Nein. Das sollte ausdrücklich erwähnt werden, weil das verschachtelte Layout davon abhängt. Die Dokumentation besagt 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 Regeln werkzeugspezifische 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 werkzeugspezifischen 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 Symlinks Administratorrechte oder den Entwicklermodus. Verwenden Sie dort stattdessen den @AGENTS.md-Import.

Ein weiterer Fallstrick gehört hierher. Nach /compact wird die Root-Datei erneut von der Festplatte gelesen. Verschachtelte Dateien in Unterverzeichnissen werden jedoch nicht erneut eingebunden. 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 dies normalerweise der Grund. Durch eine Änderung an einer beliebigen Datei in diesem Verzeichnis wird die Regel wieder geladen.

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

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

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. Der Agentenspeicher wird vom Agenten geschrieben, außerhalb des Repositorys gespeichert und gilt nur auf einem Rechner. Die Dokumentation von Claude Code zieht dieselbe Grenze: CLAUDE.md enthält „Anweisungen und Regeln“, die Sie schreiben. Der automatische Speicher enthält „Erkenntnisse und Muster“, die Claude schreibt. Das Speicherverzeichnis wird nicht zwischen Rechnern gemeinsam verwendet. Der Test ist einfach. Wenn eine Tatsache für eine Kollegin oder einen Kollegen nach einem frischen Klon gelten muss, darf sie nicht im Speicher liegen. Wie der Agentenspeicher sitzungsübergreifend erhalten bleibt behandelt diesen Teil des Themas.

Eine Skill ist der dritte Mechanismus. AGENTS.md ist Kontext, der in jeder Sitzung geladen wird. Eine Skill ist eine Prozedur, die bei Bedarf geladen wird. Die Dokumentation von Claude Code gibt eine brauchbare Regel vor: „Wenn ein Eintrag eine mehrstufige Prozedur ist oder nur für einen Teil der Codebasis relevant ist, verschieben Sie ihn in eine Skill oder in 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 mehr als einem Repository benötigt wird, sollten Sie die Skill für mehrere Repositories freigeben, anstatt dieselben Absätze in zehn verschiedene AGENTS.md-Dateien zu kopieren.

Im Upstream-Projekt steht: „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 beschriebenen Code liegen 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. Upstream sagt: „Die nächstgelegene Datei hat Vorrang.“ Das beschreibt, was bei einem Konflikt geschieht, nicht, welche Dateien geladen werden. Codex „fügt Dateien vom Stammverzeichnis aus nach unten zusammen und verbindet sie durch Leerzeilen“. Claude Code fügt ebenfalls jede Datei zusammen, die es beim Aufwärtslaufen vom Arbeitsverzeichnis aus findet, statt sie zu überschreiben. Die nächstgelegene Datei hat nur dann Vorrang, wenn zwei Dateien unterschiedliche Anweisungen zum selben Thema enthalten. Schreiben Sie gemeinsame Regeln einmal im Stammverzeichnis und wiederholen Sie sie nicht in jedem Verzeichnis.

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

Sie sollte so klein sein, dass Sie nichts dagegen hätten, wenn sie bei jeder Anfrage, die Sie in diesem Repository stellen, vorangestellt wird. 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 überflüssig. Verschieben Sie die Details in Dateien der jeweiligen Verzeichnisse und hinterlassen Sie dort 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 enthalten ist, den ein Mensch 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 regelmäßig git log -1 --format=%cs in jeder Datei mit demselben Befehl, der im dokumentierten Verzeichnis ausgeführt wird.

Liest Claude Code AGENTS.md-Dateien?

Nein. Seit 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 Symlink 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 „Memory files“ 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. 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 bestimmtes Verzeichnis gilt, gehört in die AGENTS.md-Datei dieses Verzeichnisses. Eine Information, die der Agent direkt aus dem Code lesen kann, etwa die Verzeichnisstruktur oder die Abhängigkeitsliste, gehört in keine der beiden Dateien.