Du arbeitest im Monorepo, startest eine Sitzung in packages/webapp/ und erwartest, dass der Agent die Konventionen des Teams kennt – doch er sieht nur die AGENTS.md direkt neben deinem Arbeitsverzeichnis. Die Datei im Repo-Root mit Commit-Policy, Branch-Strategie und CI-Ablauf bleibt für ihn unsichtbar. Also wiederholst du die Regeln in jeder Sitzung von Neuem – oder schaust zu, wie der Agent sie bricht. Diese Woche ändert sich das: Hermes führt die ganze Kette automatisch zusammen.

Tief im Monorepo sah Hermes früher nur eine Ebene

AGENTS.md ist die primäre Projektkontextdatei von Hermes Agent: Sie sagt dem Agenten, wie dein Projekt strukturiert ist, welche Konventionen gelten und worauf zu achten ist. Doch bisher lud Hermes, wenn du eine Sitzung in monorepo/packages/webapp/ gestartet hast, nur die AGENTS.md im aktuellen Verzeichnis — die Datei im Repo-Root mit den „gesamten-Repo“-Konventionen (Commit-Policy, Branch-Strategie, CI-Ablauf) blieb unsichtbar, sofern du sie nicht in jedes tiefe Verzeichnis kopiert hast.

Duplizierung bringt ihre eigenen Probleme mit sich: Drift, nicht synchronisierte Updates, verschwendetes Kontextbudget.

Die am 2026-08-08 in Hermes Agent main gemergte Verzeichniskette behebt das: Immer wenn dein Arbeitsverzeichnis innerhalb eines Git-Repositorys liegt, lädt der Sitzungsstart eine zusammengeführte Kette von AGENTS.md-Dateien in den System-Prompt — zuerst der Git-Root, dann jedes Zwischenverzeichnis, zuletzt das cwd. Der Mechanismus ist ein Port von grok-clis directoryChain.

So funktioniert die Kette

monorepo/                       (git root, cwd = packages/webapp/)
├── AGENTS.md                  ← loaded first (repo-wide conventions)
└── packages/
    ├── AGENTS.md              ← loaded second
    └── webapp/
        └── AGENTS.md          ← loaded last (most specific, takes precedence)

Die wichtigsten Verhaltensweisen:

• Herkunfts-Labels: jede Datei wird unter einer Überschrift mit relativem Pfad wie ## ../../AGENTS.md oder ## AGENTS.md eingefügt, sodass der Agent erkennen kann, aus welchem Verzeichnis jede Regel stammt;
• Tiefer gewinnt: tiefere Dateien erscheinen später im Prompt, sodass spezifischere Vorgaben Vorrang vor repo-weiten Vorgaben haben;
• Inhalts-Deduplizierung: identischer Inhalt, der entlang der Kette erneut auftaucht (kopierte oder per Symlink verknüpfte Dateien), wird nur einmal behalten — kein verschwendetes Kontextbudget;
• Budget-Obergrenzen: jede Datei durchläuft ihr eigenes Kürzungsbudget, und die zusammengeführte Kette hat eine zusätzliche Gesamtobergrenze — ein tiefes Monorepo kann den Kontextdatei-Verbrauch nicht unbegrenzt vervielfachen;
• Sicherheitsscan: jede Datei durchläuft den bestehenden Bedrohungsscan für Kontextdateien (_scan_context_content), bevor sie in den System-Prompt gelangen kann; bösartiger Inhalt wird blockiert.

Außerhalb eines Git-Repos: Elternverzeichnisse leaken nie

Die Kette hat eine bewusste Sicherheitsgrenze: Wenn das Arbeitsverzeichnis nicht innerhalb eines Git-Repositorys liegt, besteht die Kette nur aus [cwd] — Elternverzeichnisse werden nie herangezogen. Eine in /tmp oder $HOME platzierte AGENTS.md kann daher niemals in fremde Sitzungen hineinleaken — ganz im Sinne der bestehenden .hermes.md-Sicherheitsbegründung.

Das Prioritätssystem: ein Kontextdatei-Typ pro Sitzung

Beachte: Die Verzeichniskette gilt nur für AGENTS.md. Die Projektkontext-Typen von Hermes werden nach Priorität aufgelöst:

.hermes.md / HERMES.md  →  AGENTS.md  →  CLAUDE.md  →  .cursorrules

(Pro Sitzung wird nur der erste passende Typ geladen; SOUL.md wird unabhängig davon als globale Persona geladen.) Wenn dein Repo-Root also CLAUDE.md verwendet (Claude-Code-Stil), greift die Kette nicht — CLAUDE.md wird weiterhin nur vom cwd gelesen. Du willst die Kette? Dann nutze AGENTS.md.

Wie sich das von der progressiven Unterverzeichnis-Erkennung unterscheidet

Stammleser kennen vielleicht bereits Hermes’ anderen Mechanismus: Wenn der Agent mitten in der Sitzung Dateien in einem Unterverzeichnis liest, entdeckt er progressiv die AGENTS.md dieses Verzeichnisses und fügt sie bei Bedarf ein (jedes Unterverzeichnis wird pro Sitzung höchstens einmal geprüft). Die Verzeichniskette ergänzt ihn:

Mechanismus	Zeitpunkt	Abdeckung
Verzeichniskette (neu)	Beim Sitzungsstart	Die vertikale Kette Git-Root → cwd, in den System-Prompt
Progressive Unterverzeichnis-Erkennung	Während der Sitzung	Horizontale Unterverzeichnisse, die der Agent tatsächlich besucht, bei Bedarf eingefügt

Beide sind durch denselben Sicherheitsscan geschützt, und keiner von beiden stört die Byte-Stabilität des System-Prompts (Prompt-Cache-freundlich).

Monorepo-Playbook: AGENTS.md in drei Ebenen aufteilen

Der natürliche Einsatz der Kette ist Granularitäts-Schichtung:

# repo-root AGENTS.md (monorepo level)
## Shared conventions
- Every PR must pass CI and lint
- Commit messages follow Conventional Commits
- Changelog entries go into CHANGELOG.md

# packages/AGENTS.md (package level)
## Package rules
- New packages must be registered in the registry
- Cross-package deps go through public APIs only

# packages/webapp/AGENTS.md (directory level, most specific)
## Frontend-specific
- Components use TypeScript strict mode
- Styling uses design tokens only — no inline colors
- Tests live in __tests__/, run with Vitest

Eine in packages/webapp/ gestartete Sitzung erhält alle drei Ebenen: Repo-Konventionen als Basis, Package-Regeln darüber, Frontend-Spezifika zuletzt. Bei Frontend-Code wird der Agent keine Commits schreiben, die gegen die Repo-Policy verstoßen, und keine Inline-Farben verwenden, die das Design-System brechen.

Upgrade-Tipps

1. Senke die repo-weiten Konventionen (Branch/Commit/CI) in eine AGENTS.md im Root ab; tiefe Verzeichnisse sollten nur Regeln enthalten, die wirklich zu dieser Ebene gehören — kein Kopieren;
2. Kopiere denselben Inhalt nicht in mehrere Verzeichnisse — die Kette dedupliziert zwar, aber „einmal speichern“ ist trotzdem die richtige Lösung;
3. Migration von Claude Code / Cursor? Benenne die CLAUDE.md im Root in AGENTS.md um (oder füge eine AGENTS.md hinzu), und du bekommst die ganze Kette.

Für noch mehr Zuverlässigkeit bei langen Tasks sieh dir unseren Leitfaden zur Konfiguration langer Tasks und Timeouts an; Kontextdateien ergänzen sich gut mit den Produktivitäts-Tipps. Neu bei Hermes Agent? Starte mit der Installationsanleitung, bevor du experimentierst.

Fazit: Organisiere AGENTS.md in drei Ebenen — Repo, Package, Verzeichnis — und Hermes setzt beim Sitzungsstart automatisch den vollständigen Projektkontext zusammen: generische Konventionen gehen nie verloren, spezifische Regeln landen natürlich zuletzt, und das alles ganz ohne Aufwand.