Eine rules.md ist eine Markdown Datei im Projekt Root, die einem KI Coding Agent dauerhaft erklärt, wie er in deinem Projekt arbeiten soll: Build Befehle, Code Konventionen, Test Regeln und Architektur Entscheidungen. Der Begriff fasst eine ganze Familie verwandter Dateien zusammen, allen voran AGENTS.md als offener Standard und CLAUDE.md als Variante von Anthropic.

Ohne so eine Datei muss der Agent den Projektkontext bei jeder Session neu erraten. Mit ihr liest er die Regeln einmal ein und hält sich daran, von der Ordnerstruktur über die bevorzugten Test Tools bis zu Dateien, die er niemals anfassen darf. AGENTS.md wird inzwischen von über 30 Agents nativ gelesen, darunter Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Windsurf und Zed.

Die Datei nutzt reines Markdown, ohne JSON, ohne YAML, ohne Spezialsyntax. Genau das macht sie robust: Menschen und Maschinen lesen dieselbe Quelle, und neue Teammitglieder finden die Projektregeln an einer Stelle statt verstreut über mehrere toolspezifische Konfigurationen.

Bei Never Code Alone sind Rules Dateien gelebte Praxis, kein Theoriethema. Wir betreiben eine eigene AGENTS.md aus den NCA dotfiles und setzen sie täglich mit lokalen Modellen wie Qwen3 Coder über OpenCode und mit Claude Code ein. Aus dieser Arbeit wissen wir, welche Struktur funktioniert und welche das Context Window unnötig belastet.

Wir helfen Teams, ihre Rules Dateien sauber aufzusetzen und über mehrere Tools hinweg konsistent zu halten, im Vibe Coding Consulting. Dazu gehören wirksames Prompting für KI Coding Agents, das passende Context Window Management, der Aufbau von Agent Skills sowie abgesicherte Workflows nach unseren Regeln zur Vibe Coding Security. Ob das für dein Projekt passt, klären wir gemeinsam im Beratungsprojekt.

KI Coding Agents arbeiten mit einem begrenzten Context Window. Sie kennen weder deine Namenskonventionen noch deine Teststrategie, solange du es ihnen nicht sagst. Ohne Regeln raten sie, und Raten erzeugt halluzinierte APIs, falsche Imports und Code, der zwar läuft, aber nicht zu deinem Projekt passt.

Eine Rules Datei löst das, indem sie genau die Informationen liefert, die der Agent aus dem Code nicht ableiten kann: welche Befehle den Dev Server starten, welche Ordner Geschäftslogik enthalten, welche Dateien tabu sind. Entwickler berichten regelmäßig von deutlich weniger Korrekturen schon in der ersten Session, sobald eine solche Datei existiert.

Diese Inhalte gehören typischerweise hinein:

• Build und Test Befehle wie npm run dev, pytest oder ruff check
• Architektur und Ordnerstruktur in wenigen Zeilen
• Code Konventionen wie Type Hints oder benannte Exporte
• Harte Regeln, etwa dass Handler keine Geschäftslogik enthalten
• Verweise auf bestehende Doku statt Copy Paste

2026 haben sich die Tools auf ein gemeinsames Muster geeinigt, eine Markdown Datei im Repo Root, aber auf mehrere konkurrierende Namen. AGENTS.md steht inzwischen als offener Standard unter der Agentic AI Foundation der Linux Foundation und wird quer durch die Toollandschaft gelesen. Die folgende Übersicht zeigt, welches Format zu welchem Tool gehört und wofür es gedacht ist.

Die Faustregel: Pflegst du nur eine Datei, mach sie zur AGENTS.md. Ergänze CLAUDE.md oder .cursor/rules nur dann, wenn du toolspezifische Features brauchst. Rund 90 Prozent der Inhalte sind ohnehin identisch, denn Build Befehle, Architektur und Test Konventionen ändern sich nicht je Tool.

Eine einzige Rules Datei ist der richtige Start. Sobald sie aber zu lang wird, lädt der Agent bei jedem Aufruf Regeln mit, die mit der aktuellen Aufgabe nichts zu tun haben. Das verschwendet Context und schwächt genau die Hinweise, die zählen. Anthropic empfiehlt rund 200 Zeilen pro CLAUDE.md, bei AGENTS.md gilt als Faustregel: ab etwa 300 Zeilen lässt die Trefferquote nach und du teilst besser auf.

Beim Aufteilen verteilst du die Regeln auf die Verzeichnisse, die sie betreffen. Der Agent liest dann die Datei, die der bearbeiteten Datei am nächsten liegt, und tiefer verschachtelte Dateien haben bei Konflikten Vorrang. So bleibt jeder Kontext schlank und trotzdem vollständig. Eine typische Nested Struktur sieht so aus:

Aus der Praxis haben sich klare Prinzipien herausgebildet. Sie zielen alle auf dasselbe: maximale Wirkung bei minimalem Context Verbrauch.

• Kurz halten. Die besten Dateien aus großen GitHub Analysen waren knapp und konkret. Starte mit 20 bis 30 Zeilen und wachse nur bei Bedarf.
• Referenzieren statt kopieren. Ein Verweis wie Für API Details siehe docs/api.md spart Tokens und verhindert, dass Datei und echte Doku auseinanderlaufen.
• Testen. Lass einen Agenten typische Aufgaben allein anhand der Datei erledigen und bessere dort nach, wo er hängen bleibt.
• Bei Standard Markdown bleiben. File Imports und Glob Patterns funktionieren nicht in jedem Tool, einfaches Markdown dagegen überall.
• Niemals Secrets. Rules Dateien liegen im Git und werden von externen Diensten gelesen. Zugangsdaten gehören in eine .env und einen Secret Manager.

Wie sich der Token Verbrauch dabei senken lässt, zeigt unser Leitfaden zu weniger Tokens im KI Einsatz. Wie du die Qualität des generierten Codes absicherst, behandeln wir bei Code Qualität mit KI Agenten.

Drei Anti Patterns tauchen immer wieder auf. Wer sie kennt, spart sich viel Frust.

• Die Textwand. Eine riesige Datei mit allen Regeln auf einmal. Lange Steuerdateien gelten als bekanntes Anti Pattern, denn Struktur schlägt Volumen.
• Generierte Dateien blind übernehmen. Eine Studie der ETH Zürich zeigte, dass automatisch von Sprachmodellen erzeugte Kontextdateien in fünf von acht getesteten Szenarien die Erfolgsrate senkten und die Kosten um 20 bis 23 Prozent erhöhten. Handgeschriebene Dateien halfen, wenn auch moderat.
• Version Drift. Wenn Regeln veralten, sinkt die Agent Leistung über Wochen unbemerkt. Behandle die Datei wie Code, mit Review und Pflege.

Diese Muster hängen eng mit den allgemeinen Agentic Coding Patterns zusammen und lassen sich mit derselben Disziplin vermeiden, die auch technische Schulden im Vibe Coding verhindert.

Eine Rules Datei beschreibt, wie der Agent arbeiten soll. Aber eine Regel, die niemand prüft, ist nur ein Wunsch. Quality Gates machen aus dem Wunsch Verbindlichkeit: Linting, statische Analyse, Tests und Review Agents prüfen jeden Agent Output automatisch gegen genau die Standards, die in der CLAUDE.md oder AGENTS.md stehen. Erst diese Kombination schließt den Kreis, denn der Agent kann eine Regel übersehen, das Gate nicht.

In der Praxis heißt das: Die Rules Datei definiert Architektur Patterns und Test Pflichten, ein Review Agent in frischer Session prüft gegen diese Regeln, und die CI Pipeline blockiert alles, was durchrutscht. Gerade bei KI generiertem Code ist das entscheidend, weil typische Sicherheitsrisiken wie hardcodierte Credentials im Review leicht übersehen werden. Wie der komplette Gate Stack von Linting bis Review Agent aussieht, zeigt unser Praxisartikel zu Quality Gates für KI Code. Und wie du Claude Code mit Hooks und Gates absicherst, schauen wir uns mit Teams im Vibe Coding Consulting anhand ihrer eigenen Pipeline an.

In unseren Beratungsprojekten sehen wir regelmäßig dasselbe Muster: Teams starten mit einer gut gemeinten, aber überladenen Datei und wundern sich, warum der Agent nach 20 Minuten Session schlechter wird. Die Lösung ist fast immer Aufteilen und Kürzen, nicht weitere Regeln hinzufügen.

Unsere eigene AGENTS.md aus den NCA dotfiles ist bewusst schlank und macht lokale Modelle wie Qwen3 Coder im Planungsmodus produktiv. Wir kombinieren sie mit Terminal Agents wie OpenCode, Crush und Codex sowie mit Frameworks wie GSD für Claude Code und Sammlungen wie Everything Claude Code. Wer parallele Agenten orchestriert, profitiert zusätzlich von sauberen Regeln je Claude Agent Team.

Die wichtigsten Fragen zu Rules Dateien, ihrer Struktur und dem Aufteilen für KI Coding Agents, kompakt beantwortet.