# AGENTS.md schreiben: Vorlage und Regeln für KI-Agenten > AGENTS.md-Format, Unterstützung in KI-Tools, eine fertige Vorlage, Regeln und Fehler. So stimmst du AGENTS.md mit CLAUDE.md und anderen Anweisungsdateien ab. Source: https://ailoot.ai/blog/de/agents-md-guide-template/ Canonical: https://ailoot.ai/blog/de/agents-md-guide-template/ Language: de Publisher: Ailoot (https://ailoot.ai/) Translation: guide-034 Revision: sha256-77ca7fbb271141cc468a78aee4d1c483f8655c4cf76ff3f215d3c0121e5989d3 Praktische Materialien zu Vibe Coding und zur Arbeit mit Agenten: [Ailoot-Dokumentation](https://ailoot.ai/docs/). ## AGENTS.md in einem Absatz
Das Wichtigste AGENTS.md ist eine einfache Markdown-Datei im Stammverzeichnis deines Projekts. Sie enthält Anweisungen für einen KI-Agenten: wie Abhängigkeiten installiert werden, wie Tests ausgeführt werden, welcher Codestil gilt und was nicht angefasst werden darf. Das Format ist offen, wurde im August 2025 von OpenAI geschaffen und trat im Dezember desselben Jahres der Linux Foundation bei. Viele Programmierwerkzeuge können die Datei verwenden. Das Laden hängt jedoch von Client und Version ab: Manche erkennen AGENTS.md automatisch, andere benötigen einen ausdrücklich eingestellten Dateinamen oder eine Lesekonfiguration. Seit Version 2.1.277 (September 2026) liest auch Claude Code AGENTS.md, wenn das Projekt keine CLAUDE.md-Datei enthält. Ist CLAUDE.md vorhanden, liest Claude Code standardmäßig nur diese Datei; AGENTS.md wird mit der Zeile `@AGENTS.md` oder über einen Symlink eingebunden.
Im Folgenden wird das Format anhand von [agents.md](https://agents.md), der Dokumentation zu [OpenAI Codex](https://github.com/openai/codex), [JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html), den [Cursor Rules Docs](https://cursor.com/docs/rules), dem [Changelog des GitHub Copilot Coding Agent](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) und der [Pressemitteilung der Linux Foundation zur Agentic AI Foundation](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) erläutert. Alle Zahlen und Funktionen entsprechen dem Stand vom 30. Mai 2026. Die Unterstützung von AGENTS.md in Claude Code wird gemäß der [Dokumentation von Anthropic](https://code.claude.com/docs/en/memory#agents-md) beschrieben, ergänzt um ein Update vom 24. September 2026. Wenn du keine Ahnung hast, was dieser Zoo von Tools auf dem Markt ist oder warum sie eine gemeinsame Datei brauchen, lies zuerst die Anleitung [„Womit programmieren im Jahr 2026: 8 KI-Tools von Claude Code bis Antigravity“](https://ailoot.ai/blog/de/ai-coding-tools/). Dieser Artikel konzentriert sich speziell auf das Format AGENTS.md und darauf, wie du in 30 Minuten deine eigene Datei schreibst. ## Was ist AGENTS.md und woher kommt das Format?
Das Wichtigste AGENTS.md ist ein offenes Markdown-Dateiformat, in dem du selbst Anweisungen für KI-Agenten schreibst. OpenAI veröffentlichte es im August 2025 zusammen mit Codex CLI und lud sofort Mitautoren ein: Cursor, Sourcegraph Amp, Google Jules und Factory. Die Idee ist einfach: „Erstellen wir nicht für jedes Tool eine proprietäre Datei, sondern einigen wir uns auf eine gemeinsame.“ Am 9. Dezember 2025 wurden AGENTS.md, zusammen mit MCP von Anthropic und goose von Block, als eines der drei Gründungsprojekte der neuen Agentic AI Foundation in die Linux Foundation aufgenommen. Bis Dezember desselben Jahres enthielten bereits mehr als 60.000 GitHub-Repositories AGENTS.md im Stammverzeichnis.
Früher hatte jedes KI-Tool eine eigene Regeldatei: Anthropic hatte `CLAUDE.md`, Cursor hatte `.cursorrules`, GitHub hatte `.github/copilot-instructions.md`, Aider hatte `.aider.conf.yml` und JetBrains hatte `.junie/guidelines.md`. Wenn dein Team drei verschiedene Agenten hatte, bedeutete das drei parallele Dateien mit denselben Inhalten, die innerhalb einer Woche auseinanderdrifteten. OpenAI war als Erstes davon genervt. Im August 2025 veröffentlichte das Unternehmen Codex CLI und führte gleichzeitig [agents.md](https://agents.md) als offenes Format ein. Auf der Website heißt es: > „Betrachte AGENTS.md als README für Agenten.“ > > ([agents.md](https://agents.md), aus dem Englischen übersetzt) Diese Standardregel gilt für Clients, die diesen Such- und Vorrangmechanismus tatsächlich implementieren. Prüfe die installierte Version; bei ausdrücklich konfiguriertem Laden kann ein anderer Dateipfad gelten. Der Kernpunkt ist, dass AGENTS.md das README ergänzt. README ist für Menschen geschrieben: „Was ist das Projekt, wie führe ich es lokal aus, wie kann ich dazu beitragen?“ AGENTS.md ist für den Agenten geschrieben: genaue Shell-Befehle, überprüfbare Kriterien für „fertig“ und Grenzen wie „das hier niemals anfassen“. Auf der Website heißt es: > „AGENTS.md ergänzt README: Die Datei enthält zusätzlichen, manchmal detaillierten Kontext, den der Agent braucht – Build-Schritte, Tests und Konventionen, die README überladen würden oder für menschliche Mitwirkende schlicht nicht nötig sind.“ > > ([agents.md](https://agents.md), aus dem Englischen übersetzt) Im September 2025 unterstützte der GitHub Copilot Coding Agent das Format ([Changelog, 28.08.2025](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/)). Bis Dezember waren Cursor, Junie, Gemini CLI, Aider und ein Dutzend weitere Tools hinzugekommen. Am 9. Dezember 2025 gründete die Linux Foundation die [Agentic AI Foundation (AAIF)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation): Ihre drei Gründungsprojekte waren AGENTS.md von OpenAI, MCP von Anthropic und goose von Block. Zu den Gründungsmitgliedern gehörten AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft und OpenAI. Bis zum 24. Februar 2026 umfasste die Foundation bereits [146 Organisationen](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members), darunter Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, UiPath und Hitachi. Von da an war AGENTS.md nicht mehr „noch so ein Ding von OpenAI“, sondern wurde zum De-facto-Standard. ## Welche KI-Agenten lesen AGENTS.md und welche nicht?
Das Wichtigste AGENTS.md wird in vielen Programmierwerkzeugen verwendet, darunter den unten aufgeführten Clients. Die Tabelle zeigt Ladewege, keine einheitliche native Unterstützung: Automatische Erkennung, ausdrückliche Konfiguration, Dateivorrang und der Umgang mit verschachtelten Dateien können sich unterscheiden. Claude Code von Anthropic war lange eine Ausnahme: Issue \#6235, in dem Unterstützung gefordert wurde, blieb von August 2025 bis August 2026 offen. Seit Version 2.1.277 (18. September 2026) liest Claude Code AGENTS.md selbstständig, wenn das Projekt keine CLAUDE.md-Datei enthält. Ist CLAUDE.md vorhanden, wird standardmäßig nur diese Datei gelesen; AGENTS.md wird über die Zeile `@AGENTS.md` in CLAUDE.md oder per Symlink eingebunden.
Unterstützungstabelle mit Stand vom 30. Mai 2026; die Zeile zu Claude Code wurde am 24. September 2026 aktualisiert: | Tool | Liest AGENTS.md | Datum / Quelle | |----|----|----| | OpenAI Codex CLI | Ja (natives Format) | August 2025, [agents.md](https://agents.md) | | GitHub Copilot Coding Agent | Ja | 28.08.2025, [GitHub Changelog](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) | | Cursor | Ja, Stammverzeichnis + verschachtelte Ordner | [Cursor Rules Docs](https://cursor.com/docs/rules) | | JetBrains Junie | Ja, Projekt + global `~/.junie/AGENTS.md` | [Junie Docs](https://junie.jetbrains.com/docs/guidelines-and-memory.html) | | Gemini CLI (Google) | Ja, über `.gemini/settings.json` mit `fileName: AGENTS.md` | [agents.md](https://agents.md) | | Jules (Google) | Ja, Mitautor des Standards | August 2025 | | Sourcegraph Amp | Ja, Mitautor des Standards | August 2025 | | Aider | Ja, über `read: AGENTS.md` in `.aider.conf.yml` | [agents.md](https://agents.md) | | Factory | Ja, Mitautor des Standards | August 2025 | | OpenCode | Ja | — | | Zed | Ja | [agents.md](https://agents.md) | | Warp | Ja | [agents.md](https://agents.md) | | VS Code | Ja | [agents.md](https://agents.md) | | Windsurf | Ja | — | | Devin (Cognition) | Ja, über Spec Kit Skills | April 2026 | | RooCode, Kilo Code, Augment Code | Ja | [agents.md](https://agents.md) | | **Claude Code (Anthropic)** | **Ja, wenn das Projekt keine CLAUDE.md-Datei enthält** | Seit Version 2.1.277 (18.09.2026), [Claude Code-Dokumentation](https://code.claude.com/docs/en/memory#agents-md) | Anthropic stieß als Letzter der großen Anbieter dazu. Im August 2025 wurde im offiziellen Repository `anthropics/claude-code` das Issue \#6235 eröffnet, das um Unterstützung für AGENTS.md bat. Das Issue blieb fast ein Jahr offen und wurde am 17. August 2026 geschlossen; Version 2.1.277 mit AGENTS.md-Unterstützung erschien am 18. September. Die Logik von Anthropic ist folgende: CLAUDE.md hat Vorrang, und AGENTS.md wird gelesen, wenn sich weder im Arbeitsverzeichnis noch in einem übergeordneten Verzeichnis eine CLAUDE.md-Datei befindet. Laut der [Dokumentation](https://code.claude.com/docs/en/memory#agents-md) funktioniert es so: | Was im Projekt liegt | Was Claude Code liest | |----|----| | Nur AGENTS.md | AGENTS.md | | AGENTS.md und CLAUDE.md (oder CLAUDE.local.md) | Nur CLAUDE.md | | CLAUDE.md mit der Zeile `@AGENTS.md` | CLAUDE.md, die AGENTS.md einbindet | Der Haken: Auch eine persönliche `CLAUDE.local.md` zählt, und dann hört Claude Code auf, AGENTS.md zu lesen. Dieses Verhalten kannst du unter Project instructions in `/config` ändern – zum Beispiel, damit Claude Code beide Dateien gleichzeitig liest. In Versionen vor 2.1.277 wird AGENTS.md nicht automatisch eingelesen; die Zeile `@AGENTS.md` in CLAUDE.md bleibt die Lösung. ## Wie unterscheidet sich AGENTS.md von CLAUDE.md und `.cursorrules`?
Das Wichtigste Technisch ist an ihnen nichts Besonderes: Alle vier Formate (AGENTS.md, CLAUDE.md, `.cursorrules`, `.github/copilot-instructions.md`) sind gewöhnliche Markdown-Dateien mit Anweisungen für einen Agenten. Der Unterschied besteht darin, wer sie liest und wo sie liegen. AGENTS.md kann die gemeinsamen Anweisungen mehrerer Clients enthalten; deren Erkennung oder Konfiguration bleibt clientspezifisch. CLAUDE.md ist nur für Claude Code gedacht, bietet ihm aber Zugriff auf erweiterte Funktionen: pfadbezogene Regeln, `CLAUDE.local.md` für persönliche Anpassungen, `@import` zum Einbinden anderer Dateien sowie eine Hierarchie aus Projekt-, Benutzer- und lokalen Regeln. `.cursorrules` ist in Cursor veraltet – das neue System verwendet `.cursor/rules/*.mdc` mit automatischer Zuordnung nach Dateityp. `.github/copilot-instructions.md` wird nur für Copilot im Web benötigt.
Vergleich der vier Formate mit Stand vom 30. Mai 2026: | Format | Wer liest es? | Wo liegt es? | Stärke | Schwäche | |----|----|----|----|----| | **AGENTS.md** | Mehrere Clients; Ladeweg je Version prüfen | Dokumentierter Suchpfad des Clients oder ausdrücklich konfigurierte Datei | Gemeinsame Regeln ohne Bindung an einen einzelnen Anbieter | Erkennung, Vorrang und persönliche Ergänzungen sind clientspezifisch | | **CLAUDE.md** | Nur Claude Code | Stammverzeichnis + `~/.claude/CLAUDE.md` + `CLAUDE.local.md` | Hierarchie, pfadbezogene Regeln, `@import`, Skills, Hooks | Nur Claude. Funktioniert nicht in Cursor / Codex / Copilot | | **`.cursor/rules/*.mdc`** | Nur Cursor | `.cursor/rules/.mdc` | Automatische Zuordnung nach Dateityp (TS, Python, bestimmte Pfade) | Nur Cursor, nicht standardisierte `.mdc`-Syntax | | **`.github/copilot-instructions.md`** | GitHub Copilot (Web + klassisch) | `.github/` | Funktioniert direkt im Browser auf GitHub.com | Nur Copilot, dupliziert AGENTS.md | Die zentrale Idee: AGENTS.md kann Regeln gemeinsam halten, wenn jeder Client richtig angebunden ist; persönliche, nicht eingecheckte Einstellungen bleiben eine separate Aufgabe. Claude Code hat dafür `CLAUDE.local.md`, Cursor hat lokale `.mdc`-Dateien unter User. AGENTS.md bietet diese Möglichkeit allein nicht – du musst es entweder mit anderen Dateien kombinieren oder dich im Team darauf einigen, persönliche Regeln in gitignorierten Abschnitten zu schreiben. Ein weiteres wichtiges Detail sind Monorepos. Codex und Cursor setzen die Regel „die nächstgelegene AGENTS.md gewinnt“ um: > „Lege in einem Monorepo eine separate AGENTS.md in jedes Paket. Agenten lesen automatisch die nächstgelegene Datei im Verzeichnisbaum, und die nächstgelegene gewinnt.“ > > ([agents.md](https://agents.md), aus dem Englischen übersetzt) [agents.md](https://agents.md) erwähnt, dass OpenAIs Haupt-Monorepo 88 AGENTS.md-Dateien für verschiedene Unterpakete enthält. Wenn du in einem Monorepo arbeitest, verteile die Regeln auf mehrere Ebenen: allgemeine Regeln ins Stammverzeichnis, spezifische in die Unterordner. ## Was sollte eine gute AGENTS.md enthalten?
Das Wichtigste Der Aufbau einer guten AGENTS.md umfasst 8 Abschnitte, die sich in den meisten beliebten Dateien finden: Projektübersicht, Einrichtungsbefehle, Codestil, Tipps zur Entwicklungsumgebung, Testanweisungen, PR-Richtlinien, Sicherheitsaspekte und Grenzen (was nicht zu tun ist). Alles andere ist optional. Die Hauptregel: Jeder Punkt muss ein genauer Befehl oder ein konkretes Beispiel sein, keine allgemeine Aussage wie „schreibe sauberen Code“.
Die Website [agents.md](https://agents.md) bietet ein flexibles Format – „beliebiges Markdown“. Doch 80 % der guten Dateien da draußen enthalten dieselben acht Abschnitte. Die Hauptregel: Jeder Punkt sollte ein genauer Befehl oder ein konkretes Beispiel sein. Eine abstrakte Aussage wie „schreibe sauberen Code“ wird der Agent ignorieren. 1. **Projektübersicht** – 2–3 Zeilen. Was ist das Projekt, für wen ist es und was ist sein Hauptziel? Keine Werbung. Beispiel: „Telegram-Bot für das Onboarding in einen kostenpflichtigen Workshop. Stack: Next.js 14, Prisma, PostgreSQL. Wird durch einen neuen Eintrag in `purchases` ausgelöst.“ 2. **Einrichtungsbefehle** – genaue Shell-Befehle für die lokale Ausführung. `npm install`, `npm run dev`, `npm run build`. Kein „so machen wir das normalerweise“. 3. **Codestil / Konventionen** – konkrete Regeln mit einem Beispiel, nicht „schreibe sauber“. Zum Beispiel: „TypeScript strict, einfache Anführungszeichen, keine Default-Exports, Komponentennamen in PascalCase, Hooks beginnen mit `use`.“ 4. **Tipps zur Entwicklungsumgebung** – wo wichtige Dinge liegen. Welche Variablen in `.env` benötigt werden, wo Geheimnisse gespeichert sind, welche Ports verwendet werden und wie mit der lokalen DB gearbeitet wird. 5. **Testanweisungen** – wie ein bestimmter Test ausgeführt wird und was als „grün“ gilt. Zum Beispiel: `npm test -- --testPathPattern=user-auth`; es wird erwartet, dass 100 % bestehen. 6. **PR- / Commit-Richtlinien** – Format der Commit-Nachricht, Checkliste vor dem PR (Tests, Linter, Dokumentation) und wer genehmigt. 7. **Sicherheitsaspekte** – was niemals geschehen darf. „Commite `.env` niemals. Geheimnisse gehören ausschließlich in Vault. Gib in Logs keine persönlichen Daten von Benutzern aus.“ 8. **Grenzen / Das niemals tun** – Verbote mit einer Alternative. „Verwende auf main nicht `git push --force`. Wenn du zurücksetzen musst, verwende `git revert` oder `git reset` auf einem Feature-Branch.“ Wende für jeden Abschnitt das Prinzip „Befehl statt Idee“ an. Der Agent wird „Sei vorsichtig mit Migrationen“ ignorieren. Er wird sich an „Führe vor `alembic upgrade head` `alembic check` aus. Wenn ein Fehler gemeldet wird, wende die Migration nicht an, sondern frag mich“ halten. ## Fertige AGENTS.md-Vorlage zum Kopieren und Anpassen
Das Wichtigste Unten findest du eine Einstiegsvorlage für AGENTS.md für ein typisches Webprojekt. Kopiere sie ins Stammverzeichnis des Repositorys, ersetze ``, ``, die genauen Befehle und entferne Abschnitte, die du nicht brauchst. Die Anpassung dauert 20–30 Minuten – oder länger, wenn du das zum ersten Mal machst.
````markdown # AGENTS.md ## Project overview - . Stack: . Main entities: . Details for people are in README.md. ## Setup commands ```bash # first install npm install cp .env.example .env # then fill in manually; see list below # run npm run dev # dev server on :3000 npm run build # production build npm run start # run production build ``` ## Dev environment - Node 20+ (via nvm: `nvm use 20`) - PostgreSQL 16 locally on :5432 (`docker-compose up postgres`) - Redis is optional, needed only for queues (`docker-compose up redis`) - `.env`: `DATABASE_URL`, `STRIPE_KEY`, `RESEND_API_KEY`, `JWT_SECRET` - Never read the entire `.env` file. If you need one variable: `grep "^VAR=" .env` ## Code style - TypeScript strict mode - Single quotes, no semicolons (unless ESLint requires them) - Imports: external first, then internal via `@/`, then relative - Components in PascalCase; hooks start with `use` - No `any` without an explicit comment explaining “why it can’t be typed” Example of a good module: ```ts import { z } from 'zod' const UserSchema = z.object({ email: z.string().email(), name: z.string().min(2), }) export function parseUser(raw: unknown) { return UserSchema.parse(raw) } ``` ## Testing ```bash npm test # all tests npm test -- --testPathPattern=auth # auth only npm test -- --watch # watch mode ``` All tests must pass (be green) before committing. If a test is red, don’t commit; ask me what to do. ## Pull request guidelines - Commit format: `(): ` (`feat(auth): add magic-link`) - Before PR: `npm run build && npm test && npm run lint` - PR description = what changes, why, and how to test - Don’t approve your own PR—always wait for human review ## Security - Secrets only in `.env` and Vault, never in code - Don’t log personal data (email, phone, name) - When working with the production DB, use read-only queries only unless explicitly authorized - Don’t hardcode external service API keys (Stripe, OpenAI) in tests ## Never do this - Don’t `git push --force` to main. If you need to roll back, use `git revert` or open a new PR - Don’t run DB migrations without `alembic check` (or the equivalent in your ORM) - Don’t use `npm install -g` or `sudo` for project dependencies - Don’t add dependencies without approval (especially heavy ones: webpack plugins, ORM) ```` Im Durchschnitt umfasst die Vorlage 80–120 Zeilen. Wenn die Datei mehr als 150 Zeilen hat, ist das ein Zeichen dafür, dass du sie überarbeiten solltest: Verschiebe etwas nach `docs/`, verlinke darauf oder fasse etwas in einer Zeile zusammen. In der Praxis funktionieren Dateien mit 100–150 Zeilen am besten; ab diesem Punkt beginnen die Qualitätsgewinne wieder abzunehmen. ## Welche 5 Regeln machen AGENTS.md wirklich nützlich?
Das Wichtigste Eine gute AGENTS.md befolgt fünf Regeln: Befehle statt Ideen, Verbote mit Alternativen, genau eine Quelle der Wahrheit, überprüfbare Abschlusskriterien und weniger als 150 Zeilen.
1. **Befehle statt Ideen.** Ein Agent versteht „Sei vorsichtig mit Migrationen“ nicht. Er wird `alembic check` vor `alembic upgrade head` ausführen. Agenten arbeiten mit Befehlen und Bedingungen, nicht mit Stimmungen. Formuliere alle wichtigen Regeln als „Mach X, andernfalls Y“. 2. **Verbote mit einer Alternative.** Ein bloßes „nicht mit Force pushen“ wird vom Agenten nach zwei oder drei Prompts stillschweigend ignoriert. Die Kombination „Tu X nicht, sondern mach stattdessen Y“ funktioniert. Beispiel: „Verwende auf main nicht `git push --force`; wenn du zurücksetzen musst, verwende `git revert` oder öffne einen neuen PR.“ 3. **Genau eine Quelle der Wahrheit.** Die AGENTS.md im Stammverzeichnis ist die maßgebliche Quelle für das ganze Projekt. In einem Monorepo verwendest du verschachtelte AGENTS.md-Dateien in Unterordnern und hältst dich an die Regel „die nächstgelegene gewinnt“. Keine parallelen Dateien mit widersprüchlichen Anweisungen. 4. **Überprüfbare Kriterien für „fertig“.** „Tests müssen bestehen“ ist nutzlos. Ein genaues Kriterium lautet: `npm test` gibt Exit-Code 0 zurück und schreibt kein `FAIL` in stdout. „Der Code sollte sauber sein“ ist ebenfalls nutzlos. Ein genaues Kriterium lautet: `npm run lint` läuft ohne Warnungen durch. Ein Agent versteht erst dann, was „fertig“ bedeutet, wenn du die Bedingung ausdrücklich beschreibst. 5. **Eine Datei mit weniger als 150 Zeilen.** Jenseits von 150 Zeilen verschlechtern sich die Metriken: Der Agent verbraucht mehr Kontext beim Lesen und übersieht wichtige Regeln. Wenn alles nicht hineinpasst, verschiebe Details nach `docs/architecture.md` und verlinke sie in AGENTS.md; in der Datei bleiben nur Befehle und Grenzen. ## Welche 10 Fehler machen AGENTS.md zum Müll?
Das Wichtigste Der Hauptgrund, warum AGENTS.md nicht funktioniert, ist eine vage Formulierung. In einer Studie mit mehr als 2.500 Repositories zeigte der GitHub Blog, dass die meisten Dateien scheitern, weil sie zu allgemein formuliert sind. Zum Beispiel liefert „Du bist ein hilfreicher Programmierassistent“ dem Agenten genau null nützliche Informationen. Im Folgenden stehen 10 typische Fehler und wie sie in schlechten Dateien aussehen: README duplizieren, unstrukturierter Fließtext, mehr als 30 Verbote ohne Alternativen, widersprüchliche Prioritäten, fest eingetragene Geheimnisse, veraltete Dokumentation und architektonischer Overkill für einfache Aufgaben.
1. **Vage Regeln ohne Befehle.** Der Agent ignoriert „Sei vorsichtig mit Migrationen“ – dieser Satz ist für ihn inhaltsleer. Nur ein konkreter Befehl mit einer Bedingung funktioniert: „Führe vor `alembic upgrade head` `alembic check` aus. Wenn ein Fehler vorliegt, wende die Migration nicht an, sondern frag mich.“ 2. **„Sauberer Code.“** Eine nutzlose Formulierung. Ersetze sie durch ein konkretes Muster: „Verwende funktionale Komponenten mit Hooks. Beispiel: `function LoginForm() { const [email, setEmail] = useState(''); ... }`“ 3. **Unstrukturierter Fließtext.** Wenn AGENTS.md aus 300 Zeilen Fließtext ohne Überschriften besteht, verbraucht der Agent 80K Kontext-Tokens mit irrelevanten Passagen und übersieht Wichtiges. Verwende H2/H3-Überschriften, kurze Abschnitte und Aufzählungen. 4. **Eine Datei mit mehr als 150 Zeilen.** Oberhalb dieser Schwelle verschlechtern sich die Qualitätsmetriken. Teile den Inhalt auf eine Hauptdatei und Links zu Details in `docs/` auf. 5. **Mehr als 30 Verbote ohne Alternativen.** Wenn die Datei eine lange Liste mit „Tu nicht X, tu nicht Y“ enthält, ohne zu erklären „Mach stattdessen Z“, tappt der Agent im Dunkeln. 6. **README.md duplizieren.** Wenn du „wie installieren und ausführen“ bereits in README beschrieben hast, kopiere es nicht in AGENTS.md. Verweise stattdessen mit einer Zeile auf README und beschreibe in AGENTS.md, was der Agent braucht, menschliche Mitwirkende aber nicht. 7. **Geheimnisse fest eintragen.** AGENTS.md kann öffentlich sein, weil die Datei in Git liegt. Keine echten API-Schlüssel, Tokens oder Passwörter. Verweise nur auf Speicherorte für Geheimnisse: „Siehe Vault: `secret/staging/db`.“ 8. **Widersprüchliche Prioritäten ohne Rangfolge.** „Schnell vorankommen“ + „90 % Testabdeckung halten“ lässt den Agenten unsicher zurück, wofür er sich entscheiden soll. Lege die Rangfolge ausdrücklich fest: „Zuerst Testabdeckung ≥80 %, dann Geschwindigkeit. Bei einem Konflikt haben Tests Vorrang.“ 9. **Veraltete Dokumentation.** Eine Architekturbeschreibung, die REST+Polling angibt, obwohl tatsächlich schon WebSockets verwendet werden. Der Agent folgt der veralteten Beschreibung und beschädigt die Architektur. Regel: Aktualisiere AGENTS.md im selben PR wie den Code, wenn sich die Architektur ändert. 10. **Architektonischer Overkill für eine einfache Aufgabe.** Wenn jemand um eine Änderung von zwei Zeilen in einer Konfiguration bittet, sollte der Agent nicht die gesamte Topologie von 14 Microservices lesen müssen. Verschiebe die „tiefe“ Architektur nach `docs/architecture.md`; lasse in AGENTS.md nur „Wenn die Aufgabe die Architektur betrifft, lies `docs/architecture.md`.“ Die [Studie des GitHub Blog zu mehr als 2.500 AGENTS.md-Repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) nennt die wichtigste Schlussfolgerung: > „Die meisten Agent-Dateien scheitern, weil sie zu allgemein sind. ‚Du bist ein hilfreicher Programmierassistent‘ funktioniert nicht.“ > > ([GitHub Blog](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/), aus dem Englischen übersetzt) ## Wie verwaltet man AGENTS.md und CLAUDE.md in einem Repository?
Das Wichtigste Es gibt drei Szenarien: (1) Nur Claude Code – behalte CLAUDE.md; AGENTS.md ist nicht nötig. (2) Nur Tools außer Claude (Codex, Cursor, Copilot, Junie) – verwende AGENTS.md als einzige Quelle der Wahrheit. (3) Ein gemischtes Team mit Claude Code und anderen – mache AGENTS.md zur Hauptdatei. Wenn du keine separaten Regeln für Claude hast, kannst du auf CLAUDE.md verzichten: Seit Version 2.1.277 liest Claude Code AGENTS.md selbstständig. Wenn du separate Regeln hast, verknüpfe AGENTS.md per Symlink oder `@AGENTS.md`-Import mit CLAUDE.md. Benenne unter macOS und Linux nur um, wenn AGENTS.md nicht existiert. Sind beide Dateien vorhanden, sichere und vereine zuerst ihre Regeln. Nutze danach eine kurze CLAUDE.md mit `@AGENTS.md`-Import. Überschreibe niemals die vorhandene AGENTS.md. Unter Windows benötigen Symlinks den Entwicklermodus; daher ist ein Import einfacher.
Die wichtigste praktische Frage lautet, wie man mit beiden Dateien arbeiten kann, ohne Inhalte zu duplizieren. Es gibt drei Szenarien: **Szenario 1: Nur Claude Code.** Behalte CLAUDE.md und nutze alle Funktionen von Claude Code: `~/.claude/CLAUDE.md` für Anweisungen auf Benutzerebene, `CLAUDE.md` für das Projekt, `CLAUDE.local.md` für persönliche Anpassungen, `@import` zum Einbinden anderer Dateien und `.claude/skills/` für spezialisierte Skills. AGENTS.md ist nicht nötig. **Szenario 2: Mehrere Programmierclients.** Halte gemeinsame Regeln in AGENTS.md und binde jeden Client einzeln ein. Gemini CLI unterstützt einen konfigurierten Kontextdateinamen; Aider kann eine Datei über seine Lesekonfiguration laden. Das sind ausdrückliche Ladewege, keine identische automatische Erkennung. | Ladeweg | Was du prüfen solltest | |----|----| | Automatische Erkennung von AGENTS.md | Dokumentierte Regeln der installierten Version für Stammverzeichnis, verschachtelte Dateien und Vorrang | | Ausdrückliche Konfiguration, etwa bei Gemini CLI oder Aider | Konfigurierter Dateiname beziehungsweise Lesepfad und Anzeige des geladenen Kontexts | | Bedingtes Laden oder Import in Claude Code | Installierte Version und Dateivorrang; siehe den [separaten AGENTS.md-Leitfaden für Claude Code](https://ailoot.ai/blog/de/claude-code-agents-md-support/) | Beginne eine frische Sitzung in einem ungefährlichen Test-Repository. Füge eine eindeutige harmlose Anweisung hinzu, etwa „Nenne im Test die Markierung instructions-loaded“, und prüfe neben der Antwort auch die dokumentierte Anzeige geladener Dateien oder die Protokolle des Clients. Wiederhole das für jeden tatsächlich verwendeten Client und jede Version. Die Behauptung des Modells, es habe die Datei gelesen, ist kein unabhängiger Nachweis; eine erfolgreiche Prüfung belegt nicht die Unterstützung aller anderen Tools. **Szenario 3: Ein gemischtes Team (Claude Code + andere).** Das ist 2026 die häufigste Konfiguration. Die Lösung: AGENTS.md zur Hauptdatei machen. Wenn du keine Regeln speziell für Claude Code hast, lege gar keine CLAUDE.md an: Seit Version 2.1.277 liest Claude Code AGENTS.md, wenn sich im Projekt keine CLAUDE.md befindet. Wenn du solche Regeln hast, kannst du CLAUDE.md entweder als Symlink oder als kurzen Wrapper mit einem `@AGENTS.md`-Import anlegen. Prüfe und sichere vor Änderungen beide Dateien. Sind beide vorhanden, vereine widerspruchsfreie gemeinsame Anweisungen in AGENTS.md und behalte Claude-spezifische Regeln in CLAUDE.md mit einem `@AGENTS.md`-Import. Bewahre vorhandene Symlinks, statt sie zu ersetzen. Für eine reguläre CLAUDE.md **nur bei fehlender AGENTS.md** verhindert diese macOS/Linux-Prüfung das Überschreiben vorhandener Ziele und Symlinks: ```bash if [ -e AGENTS.md ] || [ -L AGENTS.md ]; then printf '%s\n' 'STOP: AGENTS.md exists; merge both files first.' >&2 elif [ -f CLAUDE.md ] && [ ! -L CLAUDE.md ]; then mv CLAUDE.md AGENTS.md && ln -s AGENTS.md CLAUDE.md else printf '%s\n' 'STOP: inspect the existing CLAUDE.md path first.' >&2 fi ``` Nach erfolgreicher Umbenennung ist CLAUDE.md ein Symlink auf AGENTS.md. Alle Agenten, die AGENTS.md lesen, sehen denselben Inhalt. Claude Code, das CLAUDE.md liest, sieht über den Symlink denselben Inhalt. Unter Windows erfordert das Erstellen eines Symlinks den Entwicklermodus (oder Administratorrechte), was für das ganze Team möglicherweise unpraktisch ist. Eine Alternative ist eine kurze CLAUDE.md, die AGENTS.md einbindet: ```markdown # CLAUDE.md @AGENTS.md ## Claude Code specific - Use .claude/skills/ for specialized prompts - When working with Skills, consult .claude/skills/INDEX.md - Use Plan Mode before major changes (Shift+Tab) ``` In Claude Code bindet diese Syntax AGENTS.md mit einer Zeile ein und ergänzt darunter Claude-Code-spezifische Zusätze. Wenn du AGENTS.md später entfernen willst, löschst du einfach den Import. Diese Zeile führt nicht zu doppeltem Einlesen: Laut Claude-Code-Dokumentation wird dieselbe AGENTS.md nicht zweimal geladen, selbst wenn sie automatisch eingelesen werden könnte. Kanonischer Aufbau für ein Team mit mehreren Tools im Jahr 2026: ``` repo-root/ ├── AGENTS.md # maßgebliche Quelle, ≤150 Zeilen ├── CLAUDE.md # nur bei Claude-spezifischen Regeln: Symlink → AGENTS.md ODER @AGENTS.md + Ergänzungen ├── .cursor/rules/ # gezielte Überschreibungen nur für Cursor ├── .github/copilot-instructions.md # „Siehe AGENTS.md“, falls verwendet └── docs/architecture.md # ausführliche Architektur, auf die AGENTS.md verweist ``` Mehr über CLAUDE.md erfährst du in der Anleitung [„CLAUDE.md richtig konfigurieren“](https://ailoot.ai/blog/de/claude-md-template/). Warum ein Agent eine große Anweisungsdatei braucht, erfährst du unter [„Was ist Context Engineering?“](https://ailoot.ai/blog/de/context-engineering/). ## Was änderte sich 2026: Warum stellte die AAIF AGENTS.md unter das Dach der Linux Foundation?
Das Wichtigste Am 9. Dezember 2025 gründete die Linux Foundation die Agentic AI Foundation (AAIF) mit drei Gründungsprojekten: AGENTS.md von OpenAI, MCP von Anthropic und goose von Block. Zu den Gründungsmitgliedern gehörten AWS, Anthropic, Block, Bloomberg, Cloudflare, Google, Microsoft und OpenAI. Bis zum 24. Februar 2026 umfasste die Foundation 146 Organisationen. Damit war AGENTS.md nicht mehr „ein Ding von OpenAI“, sondern wurde neben MCP zum Branchenstandard. Praktisch gesehen gehört AGENTS.md im Stammverzeichnis zur Grundausstattung, wenn du ein Produkt entwickelst, das mit Agenten verschiedener Anbieter funktionieren soll. Ohne die Datei musst du drei oder vier parallele Dateien pflegen, die innerhalb eines Monats auseinanderdriften.
Die wichtigste politische Geschichte im KI-gestützten Programmieren im Mai 2026 war nicht die Veröffentlichung eines weiteren Modells, sondern die Zusammenführung der Formate. Zuvor hatte jeder Anbieter eine eigene Regeldatei, was für die Anbieter praktisch, für Teams mit mehreren Tools aber mühsam war. In einer [Pressemitteilung vom 9. Dezember 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) kündigte die Linux Foundation die Agentic AI Foundation als Dachorganisation für drei Formate an: - **AGENTS.md** von OpenAI – ein Format für Anweisungsdateien für Agenten - **Model Context Protocol (MCP)** von Anthropic – ein Protokoll, um externe Tools mit Agenten zu verbinden - **goose** von Block – ein Open-Source-Agent-Framework Aus der Pressemitteilung der Linux Foundation: > „Indem diese Projekte unter dem Dach der AAIF zusammengeführt werden, können sie sich mit der Transparenz und Stabilität weiterentwickeln, die nur offene Governance bietet.“ > > ([Pressemitteilung der Linux Foundation, 9. Dezember 2025](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation), aus dem Englischen übersetzt) Bis zum 24. Februar 2026 gehörten der AAIF [146 Organisationen an](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) (97 neue Mitglieder in zwei Monaten). Zu den neuen Gold-Mitgliedern gehörten Red Hat, ServiceNow, Akamai, Lenovo, JPMorgan Chase, Huawei, Hitachi, UiPath, American Express und Autodesk. Anthropic ist auf Platin-Niveau und fördert MCP. OpenAI ist auf Platin-Niveau und fördert AGENTS.md. Block ist mit goose auf Platin-Niveau. Dadurch ändert sich die Positionierung von AGENTS.md: vom „OpenAI-Format“ zum Branchenstandard. Im Frühjahr 2026 stand Claude Code noch abseits; im September lernte es mit Version 2.1.277, AGENTS.md selbstständig zu lesen. CLAUDE.md ist nicht verschwunden und hat standardmäßig weiterhin Vorrang, wenn die Datei im Projekt liegt. Ein praktischer Ausgangspunkt sind gemeinsame Projektregeln in AGENTS.md und der Import, Wrapper oder ausdrücklich konfigurierte Lesepfad, den jeder verwendete Client benötigt. Prüfe bei Claude Code installierte Version und Dateivorrang, bevor du über CLAUDE.md-Import oder Symlink entscheidest. Verifiziere das Laden in jedem Client; diese Anleitung belegt keine Abdeckungsquote. ## Wie geht es weiter? AGENTS.md ist der erste Baustein dafür, „wie man sich mit einem Agenten abstimmt, damit er vorhersehbar funktioniert“. Als Nächstes kommt der zweite Baustein – ein Wissensordner des Projekts, der Geschäftskontext, Zielgruppe, Produkte und Preise enthält. Der dritte Baustein ist [Context Engineering](https://ailoot.ai/blog/de/context-engineering/), das alles zusammenführt: welche Dateien der Agent in jedem Schritt sieht, wie der Zustand zwischen Sitzungen erhalten bleibt und wie zwischen verschiedenen Modellen gewechselt wird. Praktische Materialien: [Ailoot-Dokumentation](https://ailoot.ai/docs/).
### Quellen - [agents.md – offizielle Website des Standards](https://agents.md) - [Linux Foundation: Gründung der Agentic AI Foundation (9. Dezember 2025)](https://www.linuxfoundation.org/press/linux-foundation-announces-the-formation-of-the-agentic-ai-foundation) - [AAIF begrüßt 97 neue Mitglieder (24. Februar 2026)](https://www.linuxfoundation.org/press/agentic-ai-foundation-welcomes-97-new-members) - [OpenAI gründet die Agentic AI Foundation mit](https://openai.com/index/agentic-ai-foundation/) - [GitHub Changelog: Copilot Coding Agent unterstützt AGENTS.md (28. August 2025)](https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/) - [GitHub Blog: Erkenntnisse aus mehr als 2500 AGENTS.md-Repositories](https://github.blog/ai-and-ml/github-copilot/how-to-write-a-great-agents-md-lessons-from-over-2500-repositories/) - [Claude-Code-Dokumentation: Wie Claude AGENTS.md liest](https://code.claude.com/docs/en/memory#agents-md) - [Dokumentation zu JetBrains Junie](https://junie.jetbrains.com/docs/guidelines-and-memory.html) - [Cursor Rules Docs](https://cursor.com/docs/rules)
Weitere Materialien und Tools: [Ailoot](https://ailoot.ai/). ## Fragen und Antworten ### Was tue ich, wenn AGENTS.md und CLAUDE.md schon existieren? Sichere und vergleiche beide vor Änderungen. Vereine gemeinsame Regeln in AGENTS.md, behalte Claude-spezifische in CLAUDE.md und ergänze einen @AGENTS.md-Import. Benenne keine Datei über die andere um. ### Wie mache ich Anweisungen überprüfbar? Schreibe genaue Einrichtungs- und Testbefehle, definiere das erwartete Ergebnis und benenne unveränderliche Bereiche. Lagere ausführliche Architektur in verlinkte Dokumente aus, damit die Hauptanweisungen leicht erfassbar bleiben. ## Ailoot · Das Unternehmen und sein Projektportfolio Ailoot baut auf bewährte Betriebserfahrung, einen großen Kundenstamm, stabilen Service und kontinuierliche KPI-Kontrolle. Das Unternehmen und sein Projektportfolio: Millionen von Kunden; monatliche Umsätze in Milliardenhöhe. Ailoot nutzt diese Betriebserfahrung für den API-Zugang zu KI-Funktionen in Kundenprodukten, Agenten, Anwendungen und Automatisierungen.