AGENTS.md mit dox automatisch aktuell halten

Warum Ihre AGENTS.md drei Wochen später nicht mehr stimmt

Eine AGENTS.md-Datei veraltet, weil sie nicht mit dem Code verknüpft ist. Sie schreiben sie einmal manuell, an dem Tag, an dem das Repository einen bestimmten Zustand hat. Dann ändert sich der Test-Runner, ein Paket wird umbenannt, ein Dienst wird gelöscht, und die Datei beschreibt weiterhin den Stand von Juni. Nichts schlägt fehl, weil kein Build-Schritt die Datei liest.

Der Agent liest die Datei und verlässt sich darauf. Genau das verursacht die Probleme. In einem Repository ohne AGENTS.md prüft ein Coding-Agent zunächst die Umgebung, bevor er handelt. In einem Repository mit einer falschen AGENTS.md beendet er diese Prüfung, weil er bereits eine Antwort hat. Er führt den in Ihrer Datei genannten Befehl aus, die Shell antwortet mit Missing script: "test", und nun beginnt der Agent zu raten. Häufig bearbeitet er package.json, um das Skript hinzuzufügen, das Ihre Dokumentation versprochen hat. Die veraltete Datei ist nicht unbemerkt wirkungslos geblieben. Sie hat eine unerwünschte Änderung verursacht.

dox ist eine mögliche Lösung dafür. Es handelt sich um eine Reihe von Regeln für den Agenten. Diese Regeln machen die Aktualisierung der Dokumentation zu einem Bestandteil des Abschlusses der Arbeit. Dadurch wird die Datei im selben Commit geändert wie der Code, durch den sie veraltet ist.

Was dox ist und was nicht

dox ist eine einzelne Markdown-Datei. Das Repository ist agent0ai/dox, steht unter der MIT-Lizenz und besteht am 11. August 2026 aus einem 3906-Byte-AGENTS.md, einer README, einer LICENSE und zwei Bildern. Es gibt kein zu installierendes Paket und keine Laufzeitumgebung.

Das ist relevant, weil der Begriff Generator ein Programm nahelegt, das Ihren Code analysiert. Ihr Code wird von nichts analysiert. dox ist ein Vertrag, den Ihr Coding-Agent liest: Ihr Agent ist der Generator, und dox ist der Befehlssatz, der festlegt, wann er die Dokumentation liest, wann er sie überarbeitet und welche Struktur jedes Dokument hat.

Die Datei hat zehn Abschnitte, von denen zwei die eigentliche Arbeit erledigen. „Read Before Editing“ weist den Agenten an, vom Repository-Root aus jeden Pfad zu verfolgen, den er ändern möchte, und in der aktuellen Sitzung jede AGENTS.md entlang jedes Pfads zu lesen, ohne sich auf sein Gedächtnis zu verlassen. „Update After Editing“ weist ihn an, dass jede relevante Änderung einen DOX-Durchlauf erfordert. Das bedeutet, dass vor dem Abschluss der Aufgabe ein Schritt zur Aktualisierung der Dokumentation ausgeführt werden muss. Der Durchlauf aktualisiert das nächstgelegene zuständige Dokument, wenn sich Zweck, Struktur, Arbeitsablauf, Berechtigungen oder Benutzereinstellungen geändert haben.

Der Rest definiert die Struktur. Eine untergeordnete AGENTS.md hat standardmäßig die folgende Reihenfolge: Purpose, Ownership, Local Contracts, Work Guidance, Verification und Child DOX Index. Die Root-Datei enthält die projektweiten Regeln sowie den übergeordneten Child DOX Index. Über diesen Index findet ein Agent die untergeordneten Dokumente. „Closeout“ ist die Checkliste, die der Agent am Ende einer Aufgabe ausführt: die geänderten Pfade erneut anhand der Kette prüfen, die nächstgelegenen zuständigen Dokumente aktualisieren, alle betroffenen Indizes aktualisieren, Widersprüche entfernen, die vorhandene Verifikation ausführen und melden, welche Dokumente er bewusst nicht geändert hat.

Dox an einen Commit binden, nicht an main

Das Repository hat keine Tags und keine Releases. Daher gibt es keine Versionsnummer, an die Sie es binden können. Binden Sie es stattdessen an den Commit. Die aktuelle AGENTS.md ist Commit f34ec7ad1055d3393887e5a2670e8cb7320c9165 vom 1. August 2026.

mkdir -p .agent
curl -fsSL -o .agent/dox-f34ec7a.md \
  https://raw.githubusercontent.com/agent0ai/dox/f34ec7ad1055d3393887e5a2670e8cb7320c9165/AGENTS.md
wc -c .agent/dox-f34ec7a.md

wc -c sollte 3906 ausgeben. Eine andere Zahl bedeutet, dass Sie die in diesem Leitfaden beschriebene Datei nicht abgerufen haben. Lesen Sie sie daher, bevor Sie ihr vertrauen. Wenn Sie den Commit-Hash falsch eingeben, lässt -f curl mit curl: (22) The requested URL returned error: 404 abbrechen und schreibt keinen Inhalt. wc -c gibt dann 0 aus. Eine abgeschnittene Datei ist schlechter als gar keine Datei, weil der Agent dann nur einen Teil eines Vertrags befolgt, ohne dies zu erkennen.

cp .agent/dox-f34ec7a.md AGENTS.md
git add AGENTS.md .agent/dox-f34ec7a.md
git commit -m "Add DOX rules (agent0ai/dox @ f34ec7a)"

Dieser cp gilt für ein Repository, das noch keine AGENTS.md hat. Wenn bereits eine vorhanden ist, überschreiben Sie sie nicht. Fügen Sie die Dox-Abschnitte oberhalb des vorhandenen Inhalts ein, lassen Sie Ihre eigenen Regeln darunter stehen und lesen Sie das Ergebnis einmal vollständig von oben nach unten. Zwei Dokumente mit widersprüchlichen Regeln führen dazu, dass der Agent die Regel befolgt, die er zuletzt gelesen hat.

Bitten Sie Ihren Agenten anschließend innerhalb des Repositorys um den ersten Durchlauf. Die README enthält den genauen Wortlaut:

Initialize DOX tree for this project now.

Dabei werden die untergeordneten AGENTS.md-Dateien und die Verzeichnisse erstellt, die auf sie verweisen. Prüfen Sie das Ergebnis, bevor Sie ihm vertrauen:

git status --short
find . -name AGENTS.md -not -path './.git/*' | sort

Jede Datei in dieser Ausgabe von find sollte irgendwo weiter oben in einem Child-DOX-Index aufgeführt sein. Ein untergeordnetes Dokument, auf das kein Index verweist, kann vom Agenten übersehen werden, weil er über den Index Dokumente findet, die nicht direkt auf dem von ihm durchlaufenen Pfad liegen.

Was dox sehen kann und was es nicht wissen kann

Der Agent, der Ihren Baum erstellt, liest das Repository. Daher kann alles, was im Repository enthalten ist, in das Inventar aufgenommen werden: die Verzeichnisstruktur, Paketmanifeste und Lockfiles, die Skripte in package.json, Makefile oder pyproject.toml, CI-Workflow-Dateien, Dockerfiles, Einstiegspunkte und CODEOWNERS, falls vorhanden. Ein daraus erstelltes Inventar ist tatsächlich selbstpflegend. Wenn ein Paket verschoben wird, verschiebt der nächste Durchlauf auch die zugehörige Beschreibung.

Alles Folgende müssen Sie selbst angeben, weil es nicht im Repository enthalten ist und daher nicht gelesen werden kann:

• warum eine Regel existiert; nur das verhindert, dass ein Agent sie als unnötige Komplexität entfernt
• welcher von zwei funktionierenden Pfaden unterstützt wird und welcher gelöscht werden soll
• alles außerhalb des Repositorys, etwa die Staging-Umgebung oder der Grund, warum eine Abhängigkeit zwei Versionen zurückgehalten wird
• was Sie nächste Woche vorhaben; das ist der Unterschied zwischen einer aktuellen und einer nützlichen Datei

dox berücksichtigt diese Einschränkung. In den eigenen Regeln steht, dass Work Guidance den aktuellen Standards des Projekts oder den Anweisungen des Benutzers entsprechen muss. Wenn es noch keine solchen Standards oder Anweisungen gibt, bleibt der Abschnitt leer. Verification muss eine vorhandene Prüfung abbilden. Gibt es im Repository kein Test-Framework, bleibt dieser Abschnitt leer, bis eines vorhanden ist. Eine generierte Datei, die einen Standard erfindet, ist schlechter als ein leerer Abschnitt, weil der Agent die Erfindung anschließend durchsetzen wird.

Handgeschriebene Absichten aus dem generierten Inventar heraushalten

Das ist der Fehler, wegen dem viele bei generierter Dokumentation aufgeben. Sie schreiben einen Absatz, der erklärt, dass die Jobs als Single-Consumer-Warteschlange betrieben werden müssen. Drei Wochen später schreibt ein Durchlauf die Datei neu, und der Absatz ist verschwunden – innerhalb eines Diffs mit vierzig Zeilen, in denen hauptsächlich Dateinamen neu angeordnet werden. Niemand bemerkt es.

Dafür gibt es zwei Mechanismen, und Sie sollten beide verwenden.

Verschieben Sie zunächst dauerhafte Absichten in eine andere Datei. Architekturentscheidungen und ihre Begründung gehören in eine für den Agenten geschriebene DESIGN.md. Notizen für Menschen gehören dorthin, wo Sie HUMAN.md aus AGENTS.md herauslösen. AGENTS.md enthält dann das Inventar und die lokalen Verträge. Genau dieser Teil sollte sich ändern, wenn sich der Code ändert.

Sichern Sie zweitens die Absichten ab, die in AGENTS.md bleiben müssen. Umschließen Sie sie mit Markern und behandeln Sie den Block als von Menschen verwaltet:

## User Preferences

<!-- dox:keep start -->
The jobs queue stays single consumer. Ordering is the reason this service exists.
Deploys ship on Tuesday. A Friday deploy is a human decision, not an agent decision.
<!-- dox:keep end -->

Markdown-Kommentare werden auf der Seite nicht dargestellt, und der Agent liest sie trotzdem. Machen Sie nun überprüfbar, dass der Block erhalten bleibt, damit ein Durchlauf, der ihn entfernt, deutlich fehlschlägt. Führen Sie dies in der CI (Continuous Integration) bei jedem Pull Request aus:

git fetch -q origin main
sed -n '/dox:keep start/,/dox:keep end/p' AGENTS.md > /tmp/keep.head
git show origin/main:AGENTS.md | sed -n '/dox:keep start/,/dox:keep end/p' > /tmp/keep.base
diff -u /tmp/keep.base /tmp/keep.head

diff gibt nichts aus und beendet sich mit 0, wenn der Block unverändert ist. Jede Ausgabe bedeutet, dass der Durchlauf Text im Besitz von Menschen neu geschrieben hat. Eine Person genehmigt die Änderung oder setzt sie zurück. Die Prüfung funktioniert, ohne dass sich jemand daran erinnern muss.

Bei Pull Requests neu generieren, nicht nach einem Zeitplan

Der beste Zeitpunkt zum Aktualisieren eines Dokuments ist der Commit, durch den es veraltet ist. Führen Sie den DOX-Durchlauf im selben Pull Request wie die strukturelle Änderung aus. Dadurch bleibt der Diff klein genug, um ihn tatsächlich zu lesen.

Eine blockierende Prüfung, die dies erzwingt:

#!/usr/bin/env bash
set -euo pipefail
git fetch -q origin main
base=$(git merge-base origin/main HEAD)
changed=$(git diff --name-only "$base" HEAD)
if grep -qE '^(src|apps|packages)/' <<<"$changed" && ! grep -q 'AGENTS\.md$' <<<"$changed"; then
  echo "Code changed but no AGENTS.md was touched. Run a DOX pass, or say why not."
  exit 1
fi

Passen Sie die Pfade an Ihr Repository an. Der Vorteil besteht darin, dass die Prüfung auf dem Branch fehlschlägt, wo die Korrektur kostengünstig ist. Außerdem schlägt sie aus einem Grund fehl, den ein Reviewer beheben kann.

Ein Zeitplan ist die Absicherung, nicht der Mechanismus. Ein wöchentlicher Job erkennt, was auf einem Branch niemand bemerkt hat: Dateien, die durch ein Rebase verschoben wurden, ein Paket, das bei einem Merge gelöscht wurde, oder ein Dokument, das ein nicht mehr vorhandenes Verzeichnis nennt. Führen Sie ihn auf einem kleinen System aus, beispielsweise auf demselben System, das Sie zum Ausführen eines Coding-Agenten auf einem VPS verwenden könnten. Lassen Sie den Job einen Pull Request öffnen, statt direkt nach main zu pushen.

#!/usr/bin/env bash
set -euo pipefail
cd /srv/src/myapp
git fetch -q origin
git switch -c "dox/refresh-$(date +%Y%m%d)" origin/main
# Your agent CLI goes on the next line, in whatever non-interactive mode it offers.
# Prompt: "Run a DOX pass over this repository. Change AGENTS.md files only."
git add '*AGENTS.md'
git commit -m "dox: refresh AGENTS.md tree" || { echo "nothing to refresh"; exit 0; }
git push -q -u origin HEAD
gh pr create --fill

Dieser Kommentar ist absichtlich ein Platzhalter. Jeder Agent verfügt über eine eigene CLI (command line interface) und ein eigenes Flag für den nicht interaktiven Betrieb. Ein von einer Webseite kopierter Befehl, der nicht zu Ihrer Version passt, schlägt in cron fehl, ohne dass jemand den Fehler sieht. Ergänzen Sie den Befehl und führen Sie das Skript einmal manuell aus, bevor Sie es einplanen. Auch || exit 0 ist wichtig: git commit beendet sich mit nothing to commit, working tree clean mit einem Status ungleich 0, wenn der Baum bereits aktuell ist. Unter set -e würde ein erfolgreicher Lauf dadurch als Fehler gemeldet.

Jeder Durchlauf kostet Tokens, weil „Read Before Editing“ den Agenten bei jeder Aufgabe die gesamte Kette lesen lässt. Das ist der Kompromiss. Sie sollten die Kosten im Blick behalten, wenn Sie bereits zählen, was die Ausführung Ihres Agenten kostet.

Monorepos: viele Verträge, ein Index

Eine einzige AGENTS.md im Stammverzeichnis eines Repositorys mit vierzig Paketen erzeugt einen Regenerierungs-Diff, den niemand liest, und ein Dokument, das für die aktuelle Aufgabe des Agents größtenteils irrelevant ist. dox bietet dafür den Child DOX Index: Das Stammverzeichnis enthält die repositoryweiten Regeln und verweist auf die untergeordneten Dateien. Jede dauerhafte Grenze besitzt ihre eigene Datei. Wie dieser Baum aufgebaut wird und welche Tools verschachtelte Dateien überhaupt lesen, wird unter verschachtelte AGENTS.md-Dateien für Monorepos behandelt.

dox verändert die Prüfoberfläche. Ein Pull Request, der packages/api ändert, sollte ausschließlich innerhalb von packages/api einen Dokumentations-Diff erzeugen:

git diff --stat -- '*AGENTS.md'

Wenn dieser Befehl bei einer Änderung an einem Paket sechs Dateien auflistet, ist der Baum falsch aufgebaut. Entweder sind die Grenzen zu grob, oder eine Regel, die in das Stammverzeichnis gehört, wurde in jedes untergeordnete Verzeichnis kopiert. dox formuliert die Korrektur direkt: Übergeordnete Regeln gehören in die Dokumentation der übergeordneten Ebene, konkrete Details in die Dokumentation der untergeordneten Ebene. Doppelte Regeln sorgen dafür, dass ein routinemäßiger Durchlauf alles neu schreibt. Wenn dieselben Regeln tatsächlich für mehrere getrennte Repositorys gelten, handelt es sich um ein anderes Problem. Dafür ist gemeinsam genutzte Agent-Skills über Repositorys hinweg das bessere Tool.

Diff wie Code prüfen

Ein generierter Dokumentations-Diff lässt sich leicht ungelesen freigeben. Dadurch wird eine falsche Datei veröffentlicht. Lesen Sie ihn mit derselben Skepsis wie generierten Code. Achten Sie auf vier Punkte.

• einen Befehl, den die Datei jetzt nennt und den Sie vor dem Merge selbst ausführen sollten. Erfundene Build-Anweisungen sind die häufigste Fehlerquelle.
• eine gelöschte Zeile, die eine wichtige Absicht enthielt. Ergänzungen sind unkritisch. Der Verlust entsteht durch Löschungen.
• einen absoluten Pfad, einen Hostnamen, eine interne URL oder etwas, das wie ein Zugangsschlüssel aussieht
• einen Inventareintrag für etwas, das nicht mehr existiert und den ls in einer Sekunde aufklärt

Prüfen Sie anschließend die Größe mit wc -l AGENTS.md. Eine Root-Datei mit mehr als 200 Zeilen ist ein Signal, sie aufzuteilen. Der gesamte Nutzen der Kette besteht darin, dass der Agent den kleinen relevanten Teil statt des gesamten Inhalts liest.

Wenn es fehlschlägt

Der Durchlauf hat Ihren Intent-Block gelöscht. Der Check diff oben gibt die entfernten Zeilen aus. Stellen Sie die Datei mit git restore --source=origin/main AGENTS.md vom Ausgangspunkt des Branches wieder her. Führen Sie den Durchlauf anschließend mit einer engeren Anweisung erneut aus, die die Abschnitte nennt, die geändert werden dürfen.

Beide Branches haben den Inhalt neu generiert. Sie erhalten CONFLICT (content): Merge conflict in AGENTS.md sowie Konfliktmarker <<<<<<< HEAD in der Datei. Bearbeiten Sie die Marker nicht manuell. Die Datei wird generiert. Die korrekte Auflösung ist ein neuer Durchlauf über den zusammengeführten Tree.

Der Agent ignoriert die Datei vollständig. Prüfen Sie, welchen Dateinamen Ihr Tool tatsächlich einliest. Wenn es eine andere Datei einliest, verweisen Sie es mit ln -s AGENTS.md CLAUDE.md auf denselben Inhalt. Committen Sie den Symlink, damit eine einzige Quelle erhalten bleibt und nicht zwei voneinander abweichende Dokumente entstehen.

Der Tree hat nicht indizierte untergeordnete Dokumente erhalten. Vergleichen Sie die Ausgabe von find . -name AGENTS.md mit den Indexeinträgen in den übergeordneten Dokumenten. Wenn ein untergeordnetes Dokument in keinem Index genannt wird, kann der Agent direkt daran vorbeilaufen.

Wenn ein Generator überdimensioniert ist

Ein Paket, ein Testbefehl und zwei Personen, die beide das Repository kennen: Schreiben Sie die zwanzig Zeilen von Hand. Eine zwanzigzeilige AGENTS.md veraltet nicht schnell genug, um einen Verzeichnisbaum, einen Index, eine CI-Prüfung und einen wöchentlichen Job zu rechtfertigen. Lesen Sie die Datei erneut, wenn Sie den Build ändern. Das sind die gesamten Wartungskosten. Sie sind geringer als die Kosten für die umgebende Infrastruktur.

dox lohnt sich, wenn das Repository Grenzen hat, die niemand vollständig im Kopf behält: mehrere Pakete mit unterschiedlichen Regeln oder Mitwirkende, die ohne entsprechenden Hintergrund dazukommen. Der Wert liegt nicht im generierten Text. Entscheidend ist, dass die Dokumentation zu etwas wird, woran ein Pull Request scheitern kann. Nur deshalb bleibt eine Datei in einem Repository aktuell.

FAQ

Muss ich etwas installieren, um dox zu verwenden?

Nein. dox ist eine einzelne Markdown-Datei unter der MIT-Lizenz. Am 11. August 2026 enthält das Repository weder ein Paket noch Releases. Sie kopieren den Inhalt in die AGENTS.md Ihres Projekts, und Ihr Coding-Agent befolgt die dort enthaltenen Regeln. Fixieren Sie den kopierten Commit, zum Zeitpunkt der Erstellung f34ec7ad1055d3393887e5a2670e8cb7320c9165, und nennen Sie ihn in Ihrer Commit-Nachricht. So können Sie später feststellen, auf welcher Version der Regeln Ihr Verzeichnis basiert.

Wie verhindere ich, dass eine Neugenerierung meine manuell geschriebenen Regeln löscht?

Trennen Sie Absicht und Bestandsaufnahme. Dauerhafte Begründungen gehören in ein separates Dokument. Alles, was in der AGENTS.md erhalten bleiben muss, gehört in einen markierten Block. Prüfen Sie diesen Block anschließend in CI: Extrahieren Sie ihn aus dem Branch und aus origin/main mit sed, vergleichen Sie beide mit diff, und lassen Sie den Build bei jeder Abweichung fehlschlagen. Eine Person genehmigt die Änderung dann oder setzt sie zurück, statt dass sie innerhalb eines großen Diffs unbemerkt bleibt.

Wie oft sollte ich die AGENTS.md neu generieren?

Bei dem Pull Request, durch den sie falsch wird. Eine strukturelle Änderung und ihre Dokumentation gehören in denselben Diff. Nur dann hat jemand den nötigen Kontext, um beides zu prüfen. Ein wöchentlicher geplanter Lauf dient als Absicherung gegen Abweichungen, die einen Branch passiert haben. Er sollte einen Pull Request öffnen, statt direkt in main zu committen.

Sollen Build-Befehle in die AGENTS.md im Stammverzeichnis oder in eine untergeordnete Datei?

In das nächstgelegene Dokument, für das sie gelten. Repository-weite Regeln und der Index der untergeordneten Dokumente gehören ins Stammverzeichnis. Ein Befehl, der für ein einzelnes Paket gilt, gehört in die AGENTS.md dieses Pakets. dox löst Konflikte anhand der Entfernung: Das nähere Dokument steuert lokale Details, und kein untergeordnetes Dokument darf eine Regel des übergeordneten Dokuments abschwächen. Wenn Sie denselben Befehl in jedes untergeordnete Dokument kopieren, schreibt ein routinemäßiger Lauf den gesamten Verzeichnisbaum neu.

Lohnt sich dox für ein kleines Repository?

Meistens nicht. Ein Paket mit einem Testbefehl und einer zwanzigzeiligen AGENTS.md veraltet nur langsam. Sie können sie in der Minute korrigieren, in der Sie das Problem bemerken. dox lohnt sich, wenn das Repository mehrere Grenzen mit unterschiedlichen Regeln oder Mitwirkende ohne den nötigen Hintergrund hat. Dann übernimmt die Kette der Dokumente Aufgaben, die sonst keine einzelne Person übernimmt.