AGENTS.md und HUMAN.md: kurz erklärt

Was AGENTS.md ist

AGENTS.md ist eine einfache Markdown-Datei im Stammverzeichnis eines Repositorys. Sie beschreibt, wie ein Coding-Agent an diesem Projekt arbeiten soll. Auf der offiziellen Website wird die Datei als „README für Agents: ein dedizierter, vorhersehbarer Ort für den Kontext und die Anweisungen, die Coding-Agents bei der Arbeit an Ihrem Projekt unterstützen“ beschrieben. Das Format wird von der Agentic AI Foundation unter dem Dach der Linux Foundation betreut. Mehr als zwanzig Agents lesen diese Datei, darunter Codex, Cursor, Jules, Devin und GitHub Copilot (Stand: Juli 2026).

Der Grund für diese Konvention ist praktisch. Eine neue Person im Team liest die README, rät den Build-Befehl und fragt jemanden, wenn der Versuch fehlschlägt. Ein Agent kann nicht nachfragen. Er rät, führt npm test in einem Projekt aus, das pnpm test verwendet, liest die Fehlermeldung und versucht etwas anderes. Für jedes dieser Tokens entstehen Kosten. Wenn Sie den tatsächlichen Befehl einmal dokumentieren, entfällt diese ganze Fehlerklasse.

Es gibt keine vorgeschriebenen Felder. Die Website stellt dies ausdrücklich klar: „AGENTS.md ist einfach Standard-Markdown. Verwenden Sie beliebige Überschriften; der Agent analysiert lediglich den bereitgestellten Text.“ Das ist die gesamte Spezifikation. Der Wert liegt nicht im Format. Er liegt darin, dass die Datei an einem Pfad liegt, den jedes Tool bereits prüft.

Wo die Datei abgelegt wird und welche Datei Vorrang hat

Legen Sie die erste Datei im Stammverzeichnis des Repositorys ab. In einem Monorepo können Sie in jedem Teilprojekt weitere Dateien hinzufügen. Die Regel ist einfach: „Agents lesen automatisch die nächstgelegene Datei im Verzeichnisbaum. Die Datei mit dem kürzesten Pfad hat daher Vorrang.“ Ein Konflikt zwischen zwei Dateien wird zugunsten der Datei aufgelöst, die bearbeitet wird. Alles, was Sie in den Chat eingeben, überschreibt beide Dateien.

my-repo/
├── AGENTS.md              # project-wide rules
├── services/
│   ├── api/
│   │   └── AGENTS.md      # wins for edits under services/api/
│   └── web/
│       └── AGENTS.md      # wins for edits under services/web/
└── README.md

Die Verschachtelung ist sinnvoll, weil Sie nur damit eine Regel formulieren können, die in einem Ordner gilt und im nächsten nicht. Eine Regel wie „Jeder Endpunkt validiert seine Eingaben“ gehört neben die Endpunkte. In einer Datei im Stammverzeichnis wird sie bei jeder nicht zugehörigen Aufgabe geladen und bringt keinen Vorteil. Wenn Ihre Datei im Stammverzeichnis bereits für jeden Dienst einen eigenen Abschnitt enthält, ist die Aufteilung in eine verschachtelte Struktur die richtige Lösung. Dort wird auch beschrieben, welche Regeln in die Unterverzeichnisse verschoben werden und welche im Stammverzeichnis bleiben.

Was in einer AGENTS.md stehen sollte

Dokumentieren Sie, was ein Agent nicht durch das Lesen des Codes herausfinden kann. Die exakten Befehle für Build, Tests und Linting stehen an erster Stelle, und zwar in der Form, in der Sie sie in ein Terminal einfügen würden. Fügen Sie den Befehl zum Ausführen eines einzelnen Tests hinzu. Ein Agent, der nur weiß, wie die gesamte Testsuite ausgeführt wird, führt sie sonst vierzigmal aus. Nennen Sie Konventionen, die vom Standard des jeweiligen Tools abweichen. Der Agent kennt den Standard bereits und muss nur Ihre Abweichung kennen. Fügen Sie das Format der Commit-Nachrichten und die Regeln für Pull Requests hinzu, sofern solche Regeln gelten.

Die Angaben müssen konkret genug sein, damit eine Aussage überprüft werden kann. „Verwenden Sie eine Einrückung mit 2 Leerzeichen“ ist eine brauchbare Anweisung, weil eindeutig feststellbar ist, ob sie eingehalten wurde. „Formatieren Sie den Code ordnungsgemäß“ ist dagegen keine brauchbare Anweisung, weil sich daran nichts überprüfen lässt. Das Gleiche gilt für Pfadangaben: „API-Handler liegen in src/api/handlers/“ ist besser als „Halten Sie die Dateien organisiert“.

Auch Negativregeln sind sinnvoll. „Bearbeiten Sie niemals Dateien unter dist/. Sie werden von npm run build generiert.“ verhindert einen konkreten Fehler. Da die Ursache genannt wird, kann der Agent den entsprechenden Fall ableiten, den Sie nicht ausdrücklich beschrieben haben. Auch eine Regel zum Umfang gehört hierher. Ein Agent, der auf eigene Einschätzung angewiesen ist, überarbeitet sonst mehr, als Sie angefordert haben: Eine weit verbreitete Fähigkeit besteht ausschließlich darauf, die kleinste funktionierende Änderung vorzunehmen.

Was nie in eine solche Datei gehört

Legen Sie niemals ein Geheimnis in einer dieser Dateien ab. Die Datei wird in git versioniert, zu Beginn jeder Sitzung in den Kontext geladen und bei jeder Anfrage an einen Modellanbieter gesendet. Ein API-Schlüssel in einer AGENTS.md ist ein API-Schlüssel in Ihrer Repository-Historie und in den Logs eines Drittanbieters. Verweisen Sie stattdessen auf das Geheimnis, anstatt es einzufügen: „Das Datenbankpasswort steht in .env, das durch gitignore ausgeschlossen ist. Fragen Sie vor dem Lesen nach.“ Die weitergehende Vorgehensweise wird unter Anmeldedaten außerhalb der Reichweite eines Agents halten beschrieben.

Lassen Sie alles weg, was der Agent durch Nachsehen ableiten kann. Eine eingefügte Verzeichnisauflistung, eine Kopie Ihrer Abhängigkeitsliste oder eine Architekturübersicht, die lediglich die Verzeichnisnamen wiederholt: All das ist bereits in der Woche nach dem Erstellen veraltet und verbraucht bis dahin bei jeder Sitzung Kontext. Behalten Sie die Fallstricke und die Gründe. Lassen Sie die Bestandsaufnahme weg. Die Gründe sollten separat erläutert werden, weil ein Agent, der nicht erkennen kann, warum eine ungewöhnliche Struktur existiert, sie stillschweigend umstrukturieren wird. Das ist der Grund für eine DESIGN.md neben dieser Datei.

CLAUDE.md ist das Claude-Code-Gegenstück zu diesem Konzept

Claude Code liest CLAUDE.md und liest AGENTS.md nicht selbstständig ein. Eine Projektdatei liegt unter ./CLAUDE.md oder ./.claude/CLAUDE.md. Persönliche Einstellungen für jedes Projekt gehören in ~/.claude/CLAUDE.md. Eine Organisation kann unter Linux eine systemweite Datei nach /etc/claude-code/CLAUDE.md verteilen. Erkannte Dateien werden vom Dateisystem-Root bis zu Ihrem Arbeitsverzeichnis zusammengeführt. Daher wird die Datei, die dem Verzeichnis am nächsten liegt, in dem Sie die Sitzung gestartet haben, zuletzt gelesen. Jede Sitzung, die Sie in diesem Verzeichnis starten, lädt denselben Stapel. Dadurch können Sie zwei Sitzungen auf einem Rechner parallel ausführen, und diese Sitzungen können sich während der Ausführung Arbeit übergeben.

Wenn Ihr Repository bereits eine AGENTS.md enthält, pflegen Sie keine zweite Kopie. Binden Sie sie ein und ergänzen Sie nur Claude-spezifische Inhalte:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Ein Symlink funktioniert, wenn Sie nichts ergänzen müssen:

ln -s AGENTS.md CLAUDE.md

Der Befehl gibt bei Erfolg nichts aus. Führen Sie in Ihrer nächsten Sitzung /context aus und prüfen Sie, ob CLAUDE.md unter Memory files erscheint. Fehlt die Datei in dieser Liste, wurde sie nicht geladen. Dann hatte ihr Inhalt keine Wirkung. Um einen ersten Entwurf zu erzeugen, statt selbst eine Datei zu schreiben, führen Sie /init aus. Der Befehl liest die Codebasis ein und erstellt eine Ausgangsdatei. Wenn bereits eine CLAUDE.md vorhanden ist, schlägt er Verbesserungen vor, statt sie zu überschreiben.

Halten Sie jede Datei bei etwa 200 Zeilen oder weniger. Längere Dateien belegen mehr Kontextfenster, und die Befolgung der Vorgaben nimmt ab. Wenn Sie sehen möchten, was sonst noch um diesen Platz konkurriert, schlüsselt dieser Überblick über den tatsächlichen Inhalt des Agent-Kontextfensters die Bestandteile auf.

Ein Punkt verdient besondere Hervorhebung. Eine AGENTS.md enthält Vorgaben, ist aber kein Berechtigungssystem. Der Inhalt wird als gewöhnlicher Kontext übergeben. Das Modell liest ihn und befolgt ihn normalerweise. Eine Aktion, die dagegen verstößt, wird jedoch nicht blockiert. Wenn eine von Ihnen formulierte Regel stillschweigend übersprungen wird und Sie nicht erkennen können, warum, gehen Sie zunächst die Gründe für das Verwerfen einer Anweisung durch, bevor Sie die Formulierung ein drittes Mal umschreiben. Für eine Regel, die ausnahmslos gelten muss, etwa „nie nach main pushen“, verwenden Sie einen Hook oder eine Berechtigungseinstellung. Diese werden als Code ausgeführt und hängen nicht davon ab, ob das Modell sich entscheidet, die Regel zu befolgen.

Tools, die diese Dateien für Sie erstellen

Zwei Projekte aus der GitHub-Trendliste vom 30 July 2026 zeigen, in welche Richtung sich diese Konvention entwickelt.

agent0ai/dox (1,368 Sterne im July 2026) ist ein Framework, das einen Baum aus AGENTS.md-Dateien aktuell hält. Es wird weder als Paket noch mit einer Laufzeitumgebung ausgeliefert. Sie kopieren den Inhalt seiner AGENTS.md in Ihre eigene AGENTS.md im Stammverzeichnis. Damit ist die Installation abgeschlossen. Bei einem bereits bestehenden Projekt weisen Sie Ihren Agenten an:

Initialize DOX tree for this project now.

Der Agent erstellt anschließend die untergeordneten AGENTS.md-Dateien und ihre Indizes. Vor jeder Änderung durchläuft er diesen Baum. Nach einer abgeschlossenen Änderung aktualisiert er die betroffene Dokumentation. Dahinter steht die Annahme, dass Dokumentation, die ein Agent als Teil seiner Arbeit pflegt, korrekt bleibt. Dokumentation, die eine Person manuell aktualisiert, tut dies dagegen nicht.

HUMAN.md, derselbe Ansatz für Sie

Intuition-Lab/personal-model (Stand Juli 2026: 1,260 Sterne) überträgt das Muster auf eine Person statt auf ein Repository. Das Projekt versteht Ihre HUMAN.md als Ausgabe des Systems und nicht als Datei, die Sie selbst schreiben: „ein lebendes Modell dessen, was jetzt wichtig ist, wie Sie Entscheidungen treffen und wohin sich Ihre Aufmerksamkeit bewegt“. Es läuft lokal unter macOS 13 oder höher, erfasst Aktivitäten, nachdem Sie macOS die erforderlichen Berechtigungen erteilt haben, und stellt das Ergebnis Agents über MCP (model context protocol) bereit. Der kurze Installationsweg:

uv tool install personal-model
persome onboard
persome model open --after 30

Sie benötigen nichts davon, um den größten Teil des Nutzens zu erhalten. Eine von Hand geschriebene HUMAN.md umfasst etwa zwanzig Zeilen: Ihre Rolle, Ihre Zeitzone, den tatsächlich verwendeten Stack, bereits getroffene Entscheidungen, die Sie nicht erneut diskutieren möchten, und den gewünschten Umfang der Erklärungen. Sie erspart dieselben wiederholten Erläuterungen, die eine Projektdatei erspart, nur auf einer übergeordneten Ebene.

Ein Hinweis zur Sicherheit: Eine HUMAN.md ist das Profil einer Person und daher grundsätzlich sensibel. Legen Sie sie nicht in einem öffentlichen Repository ab. Speichern Sie sie in ~/.claude/CLAUDE.md oder in einer von git ignorierten CLAUDE.local.md im Projektstammverzeichnis. Diese wird zusammen mit der versionierten Datei geladen und genauso behandelt.

Eine Ausgangsvorlage zum Kopieren

Diese Vorlage ist absichtlich kurz. Löschen Sie die Abschnitte, die nicht zutreffen, und fügen Sie keine Abschnitte hinzu, die Sie nicht aktuell halten können.

# AGENTS.md

## Project
A Django API serving the mobile app. Python 3.12, PostgreSQL 16.

## Setup
uv sync
docker compose up -d db
./manage.py migrate

## Commands
Run one test: pytest tests/test_orders.py::test_refund
Run everything: pytest
Lint: ruff check . && ruff format --check .

## Conventions
Type hints on every public function. Line length 100, not 88.
Migrations are generated, never hand-edited.
Never edit files under static/dist/, they come from npm run build.

## Secrets
Local credentials live in .env, which is gitignored. Ask before reading it.

## Pull requests
Title format: [area] short description. Run the linter before opening one.

Schreiben Sie den Inhalt zunächst auf und korrigieren Sie ihn anschließend direkt an dieser Stelle. Eine Zeile sollten Sie hinzufügen, wenn Sie dieselbe Korrektur zweimal im Chat eingegeben haben. Diese eine Regel hält die Datei nützlich und verhindert, dass sie zu einem Dokument wächst, das niemand liest – auch keine Maschinen. Sobald die Datei stabil ist, wird sie zusammen mit dem Repository versioniert. Das ist besonders wichtig, wenn der Agent an einem anderen Ort als auf Ihrem Laptop ausgeführt wird: einen Coding-Agent auf Ihrem eigenen Server ausführen beschreibt diese Einrichtung.

FAQ

Ist AGENTS.md dieselbe Datei wie CLAUDE.md?

Es handelt sich um dasselbe Konzept unter zwei Dateinamen. Claude Code liest CLAUDE.md und ignoriert AGENTS.md, sofern Sie die Dateien nicht miteinander verknüpfen. Verwenden Sie eine Datei als zentrale Quelle und verknüpfen Sie die andere damit, entweder mit einer Zeile @AGENTS.md am Anfang Ihrer CLAUDE.md oder mit ln -s AGENTS.md CLAUDE.md. Zwei vollständige, separat gepflegte Kopien weichen innerhalb eines Monats voneinander ab.

Garantiert das Schreiben einer AGENTS.md, dass der Agent sie befolgt?

Nein. Der Inhalt wird als Kontext übergeben. Das Modell liest ihn und hält sich im Allgemeinen daran, aber nichts verhindert eine Aktion, die ihm widerspricht. Vage Anweisungen werden am unzuverlässigsten befolgt. Zwei Dateien mit gegensätzlichen Vorgaben überlassen dem Agenten die Auswahl. Für eine Regel, die jedes Mal gelten muss, verwenden Sie einen Hook oder eine Berechtigungsregel. Diese werden vom Client unabhängig von der Entscheidung des Modells durchgesetzt.

Sollte AGENTS.md in git eingecheckt werden?

Ja, wenn die Angaben für das Projekt gelten, etwa Build-Befehle, die Verzeichnisstruktur und Konventionen. Genau dafür ist die Datei gedacht. Die Agenten Ihrer Teammitglieder starten dann mit demselben Kontext wie Ihr Agent. Persönliche Angaben oder Angaben, die nur für einen Rechner gelten, gehören in eine separate, von git ignorierte Datei. Zugangsdaten gehören in keine der beiden Dateien.

Was ist HUMAN.md, und brauche ich eine solche Datei?

HUMAN.md ist ein maschinenlesbares Profil einer Person und kein Projektprofil. Es enthält Ihre Rolle, Ihre Einschränkungen und bereits getroffene Entscheidungen. Dadurch werden diese Entscheidungen nicht in jeder Sitzung erneut infrage gestellt. Sie benötigen dafür zunächst keine Tools. Zwanzig selbst geschriebene Zeilen in Ihrer benutzerspezifischen Anweisungsdatei bieten bereits den größten Teil des Nutzens. Behandeln Sie die Datei als personenbezogene Daten und nehmen Sie sie nicht in ein Repository auf, das Sie veröffentlichen.