Das Problem: Warum KI-Code immer an derselben Stelle crasht

Wer mit Cursor, Windsurf oder Claude Code arbeitet, kennt diesen Frust: Die KI spuckt einen ganzen Codeblock aus, du kopierst ihn rein, startest den Build — Fehler, rote Tests, Abhängigkeiten am falschen Ort. Das Problem liegt nicht in der Intelligenz der KI, sondern darin, dass sie die ungeschriebenen Regeln deines Projekts nicht kennt.

AGENTS.md ist eine Markdown-Datei im Projekt-Root, geschrieben für die KI. Sie sagt ihr, wie gebaut, getestet und welcher Stil eingehalten wird. README.md ist für Menschen: Projektvorstellung, Contribution-Guide, Branding-Story. Liest die KI das, ist das wie ein neuer Mitarbeiter am ersten Tag, dem man eine Hochglanz-Broschüre in die Hand drückt und sofort Code schreiben lässt — sie weiß, was die Firma macht, aber nicht den Build-Befehl, nicht den Test-Runner, nicht die ESLint-Regeln. Also korrigierst du in jedem Chat aufs Neue: „Nutze pnpm, nicht npm”, „Tests liegen unter packages/web”, „Vergiss den Lint nicht”. Hundert Mal wiederholt, das Projekt bleibt trotzdem chaotisch.

Im Auftragsgeschäft kostet das direkt Geld: Du nimmst einen Next.js + Prisma-Job an, willst mit Cursor schneller liefern, die KI rennt npm install, deine pnpm-Workspace-Config ist im Eimer. Das Datenbank-Schema findet sie nicht, die Migration bricht ab. Der Kunde drückt, du verbrätst drei Stunden damit, KI-generierten Code zu debuggen — so verdient man kein Geld.

Drei klassische Crash-Szenarien, weil die KI die Projekt-Regeln nicht kennt: ① Falscher Package-Manager (Projekt nutzt pnpm, KI macht npm install), Dependencies landen am falschen Ort, Workspace-Config zerschossen. ② Test-Einstieg fehlt (Tests liegen unter packages/web, KI rennt pnpm test im Root, Fehler „keine Tests gefunden”). ③ Code-Stil inkonsistent (Projekt nutzt ESLint + Prettier, KI-Output hat falsche Einrückung und Quotes, CI bricht ab).

Die Chance: AGENTS.md trennt Mensch-Doku und Maschinen-Doku sauber

Das Open-Source-Projekt AGENTS.md auf GitHub (Repo: github.com/agentsmd/agents.md, Stand 2026-08-25 rund 24.000 Stars) löst genau das. Kernidee ist brutal einfach: Eine Markdown-Datei im Projekt-Root, die der KI sagt, wie sie baut, testet und welchen Stil sie fährt.

Kein README-Ersatz, sondern Ergänzung. README bedient menschliche Contributors, AGENTS.md bedient KI-Agenten. Klare Aufgabentrennung, keine Reibung.

Laut Quellpost wurde AGENTS.md bereits von Zehntausenden Open-Source-Projekten übernommen (genaue Zahl unbestätigt). Unterstützt werden VS Code, Cursor, Windsurf, Aider, GitHub Copilot (verifiziert). Aus der Community kommen zudem Hinweise auf OpenAI Codex und Google Jules (⚠️ nicht verifiziert). Wer das jetzt ignoriert, lässt die KI weiter in Dialekt mit sich reden.

Weg 1: Eine minimale AGENTS.md selbst schreiben

Kosten praktisch null. Neue Datei, drei Abschnitte, fertig.

Vorab: Die Beispiele nutzen pnpm (spart Disk, unterstützt Monorepo-Workspaces), turbo ist der Monorepo-Task-Runner, --filter schränkt auf ein Sub-Package ein, damit der ganze Repo nicht angefasst wird.

Abschnitt 1 „Dev environment tips”: Sagt der KI, welcher Package-Manager läuft, wie sie in Sub-Packages springt, wie neue Module entstehen. Aus dem offiziellen Beispiel:

• pnpm dlx turbo run where <project_name> — springt direkt ins richtige Sub-Package, ohne ls-Marathon
• pnpm install --filter <project_name> — installiert nur die Dependencies eines Sub-Packages, ganzer Monorepo bleibt unangetastet
• pnpm create vite@latest <project_name> -- --template react-ts — legt ein neues React + Vite Sub-Package mit TypeScript-Check an

Diese Befehle errät die KI nicht. Stehen sie drin, macht sie es.

Abschnitt 2 „Testing instructions”: Wie laufen Tests, wo liegt der CI-Plan, was muss vor dem Commit durch. Aus dem offiziellen Beispiel:

• pnpm turbo run test --filter <project_name> — fährt alle Checks für ein Sub-Package
• pnpm vitest run -t "<test name>" — nur ein einzelner Test mit passendem Namen
• „Fix any test or type errors until the whole suite is green” — nicht aufhören, bis alles grün ist
• „Add or update tests for the code you change, even if nobody asked” — dieser Satz ist der entscheidende, ohne ihn schleicht die KI gerne beim Test-Schreiben

Abschnitt 3 „PR instructions”: Commit-Titel-Format, Lint und Test sind Pflicht. Offizielles Beispiel: Title format: [<project_name>] <Title> plus „Always run pnpm lint and pnpm test before committing”.

Unter 50 Zeilen, aber die First-Pass-Quote beim KI-Output steigt spürbar (Community-Feedback, konkrete Zahlen ausstehend).

Weg 2: Verschachtelt im großen Monorepo nutzen

Bei Enterprise-Projekten mit Monorepo-Struktur (mehrere verwandte Projekte in einem Git-Repo, z. B. Frontend, Backend, Shared Code als eigene Unterordner) reicht eine einzige AGENTS.md nicht. AGENTS.md unterstützt Verschachtelung: In jedem Unterordner liegt eine eigene AGENTS.md, die KI lädt automatisch die nächstgelegene.

Praxis: Die Root-AGENTS.md hält globale Regeln (Package-Manager, CI-Flow, Security-Hinweise). In packages/web/, packages/api/, packages/shared/ liegt je eine eigene Datei mit den spezifischen Build-Befehlen, Test-Einstiegen und Sonder-Dependencies. Frontend-Package: „Komponenten aus shadcn, Styles mit Tailwind, Icons aus lucide-react”. Backend-Package: „Migrationen mit Prisma, API-Routes unter src/routes, Auth per JWT”.

Arbeitet die KI in einem Unterordner, lädt sie automatisch die nächste AGENTS.md, höhere Priorität als die Root-Datei. Frontend-KI und Backend-KI bekommen so komplett unterschiedliche Anweisungen, nichts vermischt sich.

Weg 3: Als Differenzierungs-Hebel im Auftragsgeschäft

Der KI-Auftragsmarkt ist ein rotes Meer — jeder nutzt Cursor, die Lieferqualität schwankt wild. Wer im Angebot schreibt „Projekt wird mit AGENTS.md-Standarddokumentation ausgeliefert, KI-gestützte Entwicklung folgt den Projekt-Regeln”, gewinnt gegen Konkurrenten, die nur sagen „Ich nutze KI zum Coden”.

Konkreter Spielplan: Nach Auftragsannahme 30 Minuten die Projektstruktur des Kunden lesen, dann eine maßgeschneiderte AGENTS.md schreiben. Diese Datei ist Teil der Lieferung — der Kunde kann sie später selbst nutzen, wenn er mit KI weiterpflegt.

AGENTS.md-Setup als eigene Leistung positionieren (Richtpreise, lokal anpassen): Basis 65 € (eine Datei plus README-Erklärung), Enterprise 400 € (Monorepo-Verschachtelung plus Security-Regeln plus Team-Schulung). Lieferumfang: ① AGENTS.md-Datei ② 30 Tage Support per Chat ③ 10-Minuten-Screencast als Schulung. Passt für: Kunden mit Cursor/Windsurf-Lizenz, die nicht vorankommen. Passt nicht für: Kunden, die noch rein manuell entwickeln und keine KI-Tools nutzen.

Fall: AGENTS.md als Kompatibilitäts-Schutzwall

AGENTS.md steht unter MIT-Lizenz (Quelle bestätigt), wird von der Community gepflegt (genaue Governance offen), offizielle Seite: agents.md.

Die Kompatibilität ist der größte Schutzwall: VS Code, Cursor, Windsurf, Aider, GitHub Copilot lesen AGENTS.md (verifiziert). Aus der Community: OpenAI Codex, Claude Code, Gemini CLI, Google Jules unterstützen es ebenfalls (⚠️ nicht verifiziert). Eine Datei schreiben, alle gängigen Assistenten nutzen — keine Tool-spezifischen Configs nötig.

Vergleich mit Alternativen: Cursors .cursorrules gilt nur in Cursor, in Windsurf ist es wirkungslos. Claude Codes CLAUDE.md bedient nur Claude. GitHub Copilot hat wieder ein eigenes Instruction-System. AGENTS.md mit „Write once, run anywhere” ist der Grund, warum es so schnell adaptiert wurde.

Migrationskosten gegen Null. Heute Cursor, morgen Windsurf — AGENTS.md wandert einfach mit, kein Rewrite nötig.

Call to Action: Heute Abend die Maschinen-Anleitung anlegen

5-Minuten-Checkliste: ① Projekt-Root öffnen ② AGENTS.md anlegen ③ Offizielles Template kopieren (github.com/agentsmd/agents.md) ④ Drei Befehle eintragen (Build, Test, Lint) ⑤ Beim nächsten KI-Coding-Job beobachten, was passiert.

Bei Monorepo heute Abend 20 Minuten extra investieren und jedes Sub-Package mit einer eigenen verschachtelten Config versorgen. Morgen beim ersten Coding-Sprint wirst du merken: Die KI generiert Code, den du nicht mehr zehnmal korrigieren musst.

AGENTS.md ist aktuell die Konfiguration mit dem besten ROI im KI-Coding-Stack — 30 Minuten Aufwand, jeden Monat Stunden an Debug-Zeit zurück.