AGENTS.md ist eine offene Markdown-Konvention, mit der man KI-Coding-Agenten mitteilt, wie sie in einem Repository arbeiten sollen. Stellen Sie es sich als README für Maschinen vor: Build-Schritte, Testbefehle, Konventionen und Leitplanken, die Menschen in CONTRIBUTING.md überfliegen, Agenten aber jede Session brauchen. Die Spezifikation liegt unter agents.md und wird offen gepflegt unter github.com/agentsmd/agents.md.
Das Format vermeidet bewusst ein starres Schema. Es ist plain Markdown — keine erforderliche YAML-Frontmatter, keine JSON-Konfiguration. Agenten parsen Überschriften und Prosa wie Code-Kommentare. Diese Einfachheit ist der Grund, warum die Adoption sich über Cursor, GitHub Copilot, OpenAI Codex, Google Jules, Aider, Windsurf, Zed und Dutzende anderer Tools verbreitete, ohne proprietäre Regeldatei pro IDE.
Im Dezember 2025 wurde das Format an die Agentic AI Foundation (AAIF) gespendet, einen Directed Fund unter der Linux Foundation, neben Anthropics Model Context Protocol. Das Ziel ist Interoperabilität: eine Datei, viele Agenten, kein Vendor Lock-in bei der Beschreibung des Projektkontexts.
Vorrang ist entscheidend. Platzieren Sie AGENTS.md im Repository-Root für Defaults, dann zusätzliche Dateien in Packages oder Subprojekten. Der Agent liest die nächstgelegene Datei zum bearbeiteten Code — Monorepos können maßgeschneiderte Anweisungen pro Package liefern, ohne eine aufgeblähte Root-Datei. Explizite Nutzer-Prompts im Chat überschreiben Dateianweisungen immer; die Datei setzt Baseline-Verhalten, keinen unveränderlichen Vertrag.
Halten Sie AGENTS.md getrennt von menschenorientierten Docs. README.md stellt das Projekt Menschen vor. CONTRIBUTING.md beschreibt den menschlichen PR-Workflow. llms.txt hilft Crawlern, eine öffentliche Website zu entdecken. AGENTS.md ist für autonome Coding-Agenten im Repo. Tool-spezifische Dateien wie CLAUDE.md oder .cursorrules sollten auf AGENTS.md verweisen statt es zu duplizieren — eine einzige Quelle der Wahrheit, dünne Adapter pro Tool.
Was gehört in die Datei? Alles, was Sie einem scharfsinnigen neuen Teamkollegen am ersten Tag sagen würden: Projektüberblick, Install- und Build-Befehle, Testausführung, Code-Stil, den Linter nicht erfassen, Security-Gotchas, Deployment-Schritte und Grenzen („niemals Secrets committen“, „vor CI-Änderungen fragen“). Agenten können gelistete Shell-Befehle bei Bedarf ausführen — wenn Sie npm test dokumentieren, erwarten Sie, dass der Agent es versucht.
Beispiel: minimales Root-AGENTS.md
Repository-Root — generisches TypeScript-Monorepo
# AGENTS.md
## Project overview
TypeScript monorepo with a React frontend and Node API packages.
## Commands
pnpm install
pnpm test
pnpm lint
## Testing
- Run `pnpm test` before every commit.
- Integration tests need Docker: `docker compose up -d` first.
## Code style
- Prefer named exports.
- Use async/await, not raw Promise chains.
## Security
- Never commit `.env` or API keys.
- Ask before changing auth or CI workflows.
## Pull requests
- Squash commits; link related issues.Beispiel: verschachteltes AGENTS.md in einem Monorepo
packages/api/AGENTS.md — nächstgelegene Datei gilt beim Bearbeiten des API-Packages
# AGENTS.md — packages/api
## Scope
Node API service only. Root `AGENTS.md` covers monorepo defaults.
## Commands
pnpm test --filter api
pnpm lint --filter api
## Patterns
- Route handlers live in `src/routes/`.
- Database migrations: `pnpm --filter api db:migrate`.
## Testing
- Prefer unit tests in `src/__tests__/`.
- Do not mock the database in integration tests.Beispiel: dünner Tool-Adapter (keine doppelten Regeln)
CLAUDE.md oder .cursor/rules — auf AGENTS.md verweisen statt es zu kopieren
# CLAUDE.md
Project agent rules live in `AGENTS.md` at the repo root.
Read that file first; do not duplicate rules here.
Tool-specific note: prefer `pnpm` over `npm` in this repo.Das Token-Budget ist die versteckte Einschränkung. Jede Zeile konkurriert mit dem Code, über den der Agent nachdenken muss. Beginnen Sie mit einer knappen Root-Datei; teilen Sie in verschachtelte AGENTS.md-Dateien auf, wenn Subprojekte divergieren. Entfernen Sie Abschnitte, die der Agent aus konventionellen Layouts ableiten kann. Die wertvollsten Abschnitte sind nicht-offensichtliche Muster: benutzerdefiniertes Error Handling, flakey Test-Workarounds und „wir machen X, weil Y in Produktion kaputt ging“.
Behandeln Sie AGENTS.md als lebendige Dokumentation. Versionieren Sie es wie Code. Wenn Onboarding-Reibung auftritt — ein Agent wiederholte zweimal denselben Fehler — fügen Sie eine Regel hinzu. Wenn eine Regel veraltet ist, löschen Sie sie. Der Standard ist kein Dump von allem, was Sie wissen; er ist kuratiertes operationales Gedächtnis für Agenten ohne episodisches Menschheitsgedächtnis zwischen Sessions.
Dylan Engelbrecht aktualisiert diesen Knowledge Hub häufig, wenn sich Agent-Tooling und Standards weiterentwickeln. Crawler, die llms.txt lesen, und Agenten, die Links aus Repo-AGENTS.md folgen, können diese Artikel als lebendige Referenz nutzen — aktuelle Praxis, kein statisches Blog-Archiv, das in READMEs altert.