NCA Social Media
Grüne Neon Browseransicht mit Schriftzug RULES.MD und kleiner Rakete auf dunkel

Was ist eine rules.md Datei?

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.

Inhaltsverzeichnis

rules.md mit NCA: Schnelle Hilfe vom Experten

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.

Rules Dateien sauber aufsetzen mit Never Code Alone

Finde das passende Angebot für dein Projekt

🤖

Hey! Ich bin CodeBot. Lass uns herausfinden, wie wir dein Projekt zum Fliegen bringen.

Was soll entstehen?

Warum KI Coding Agents Regeln brauchen

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

Die Rules Formate im Überblick

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.

Format Tool und Besonderheit Geltungsbereich
AGENTS.md Offener Standard, gelesen von Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed Repo Root, projektweit
CLAUDE.md Anthropic Claude Code, dreischichtiges Memory Modell, unterstützt Imports Projekt, User und lokal
.cursor/rules Cursor, MDC Format mit YAML Frontmatter und Glob Aktivierung Datei und Pfad gescoped
SKILL.md Anthropic Skills, beschreibt eine aufgabenbezogene Fähigkeit Pro Skill, bei Bedarf geladen

rules.md aufteilen: Vom Single File zur Nested Struktur

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:

Code: 
          
project/
├── AGENTS.md          # Repo Layout, globale Konventionen
├── src/
│   └── AGENTS.md      # Framework, Code Style, Tests
├── infra/
│   └── AGENTS.md      # Terraform, niemals anfassen Regeln
└── tests/
    └── AGENTS.md      # Teststrategie, Mocking
Level Struktur Wann sinnvoll
Level 1: Single File Eine AGENTS.md im Repo Root Kleine Projekte und der Start
Level 2: Nested Files Eine Datei pro relevantem Verzeichnis Ab etwa 200 bis 300 Zeilen
Level 3: Layered Root plus Override Dateien je Tool Mehrere Tools und Teams
Level 4: Modular Regeln pro Sprache getrennt gehalten Monorepo und Polyglott Stacks
Aufsteigendes Säulendiagramm vier Rules Levels Single Nested Layered Modular

Best Practices für wirksame Rules Dateien

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.

Häufige Fehler beim Umgang mit Rules Dateien

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.

Split context by area, keep files tight, and let tools load only what's relevant.

Maximiliano Contieri, Senior Software Engineer – DEV Community

Aus der NCA Praxis: Rules Dateien, die funktionieren

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.

CYPRESS.IO Ambassador und IT Consultant für QA Engenieering und Qualität in PHP Projekten.

NCA Vibe Coding Consulting

Roland Golla ist Entwickler aus Leidenschaft – seit über 20 Jahren. Er hat hunderte Projekte begleitet, von Legacy-Refactoring bis KI-Integration. Bei Vibe Coding verbindet er das Beste aus beiden Welten: Die Geschwindigkeit von KI-generiertem Code mit der Qualität professioneller Softwareentwicklung. Kein Bullshit, keine Agentur-Floskeln – direkte Hilfe von jemandem, der selbst täglich im Code steckt.

E-Mail Kontakt

Häufige Fragen zu rules.md und AGENTS.md

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

Was ist eine rules.md Datei 2026?

Eine rules.md ist eine Markdown Datei im Projekt Root, die einem KI Coding Agent dauerhaft erklärt, wie er arbeiten soll: Build Befehle, Code Konventionen, Test Regeln und Architektur. Der Begriff steht stellvertretend für die ganze Familie, vor allem AGENTS.md und CLAUDE.md.

AGENTS.md oder CLAUDE.md: was nutze ich 2026?

Pflegst du nur eine Datei, nimm AGENTS.md. Sie ist der offene Standard und wird von über 30 Agents nativ gelesen. CLAUDE.md ergänzt du nur, wenn du Claude spezifische Features wie das dreischichtige Memory Modell oder Imports brauchst. Rund 90 Prozent der Inhalte sind ohnehin gleich.

Wann sollte ich meine rules.md 2026 aufteilen?

Als Faustregel: ab etwa 200 Zeilen bei CLAUDE.md und ab rund 300 Zeilen bei AGENTS.md. Danach lädt der Agent zu viele irrelevante Regeln, das Context Window leidet und die Trefferquote sinkt. Dann verteilst du die Regeln auf Nested Dateien in den jeweiligen Verzeichnissen.

Wie funktionieren Nested Rules Dateien 2026?

Du legst in einzelnen Verzeichnissen eigene Rules Dateien an. Der Agent liest die Datei, die der bearbeiteten Datei am nächsten liegt. Bei Konflikten haben tiefer verschachtelte Dateien Vorrang. So bleibt der Kontext schlank, weil nur die relevanten Regeln für den aktuellen Ordner geladen werden.

Gehören Passwörter in eine rules.md 2026?

Nein, niemals. Rules Dateien liegen im Git und werden von externen Diensten gelesen. Schon ein einziger durchgesickerter Zugang kann ganze Systeme kompromittieren. Halte die Dateien auf Konventionen beschränkt und lege Secrets in eine .env Datei und einen Secret Manager.

Welche Tools lesen AGENTS.md?

AGENTS.md steht als offener Standard unter der Agentic AI Foundation der Linux Foundation und wird unter anderem von Codex, Cursor, GitHub Copilot, Gemini CLI, Aider, Windsurf und Zed gelesen. Viele weitere Tools greifen darauf zurück, wenn ihre eigene Konfigurationsdatei fehlt.

Was gehört in eine gute rules.md?

Build und Test Befehle, eine knappe Beschreibung der Architektur und Ordnerstruktur, Code Konventionen wie Type Hints sowie harte Regeln, etwa dass Handler keine Geschäftslogik enthalten. Verweise auf bestehende Doku sind besser als kopierte Inhalte, weil sie Tokens sparen und Drift vermeiden.

Wie lang sollte eine rules.md sein?

Kurz. Analysen großer GitHub Bestände zeigen, dass die besten Dateien knapp und konkret sind. Starte mit 20 bis 30 Zeilen und ergänze nur, was der Agent wirklich braucht. Eine kürzere Datei lässt dem Agenten mehr Context für die eigentliche Aufgabe.

Sollte ich meine rules.md von der KI generieren lassen?

Mit Vorsicht. Eine Studie der ETH Zürich zeigte, dass automatisch generierte Kontextdateien in fünf von acht Szenarien die Erfolgsrate senkten und Kosten erhöhten. Nutze einen Befehl wie init als Startpunkt, prüfe und kürze danach aber unbedingt von Hand.

Was ist der Unterschied zwischen AGENTS.md und SKILL.md?

AGENTS.md beschreibt das Projekt insgesamt, also Konventionen, Befehle und Struktur. SKILL.md beschreibt eine einzelne, aufgabenbezogene Fähigkeit, die ein Agent bei Bedarf lädt. Beide ergänzen sich: das eine liefert dauerhaften Projektkontext, das andere spezialisiertes Wissen für konkrete Aufgaben.

Brauche ich für jedes Tool eine eigene Datei?

Nein. Da der Großteil der Inhalte tool unabhängig ist, pflegst du eine AGENTS.md als zentrale Quelle. Nur wenn du spezielle Features wie Cursors Glob Aktivierung oder Claudes Imports nutzt, legst du zusätzlich .cursor/rules oder CLAUDE.md an. Konverter Tools helfen beim Synchronisieren.

Verbessert eine rules.md wirklich die KI Ergebnisse?

Ja, wenn sie schlank und gepflegt ist. Entwickler berichten von deutlich weniger Korrekturen schon in der ersten Session. Handgeschriebene, knappe Dateien halfen in Studien messbar. Wichtig ist die Pflege, denn veraltete Regeln senken die Agent Leistung über Wochen unbemerkt.

Code Qualität mit KI Agenten 2026

Code Qualität mit KI Agenten 2026

Wie Sie mit klaren Architekturentscheidungen, einer guten Konfigurationsdatei und Review Agents in frischen Sessions hohe Code Qualität bei Vibe Coding sicherstellen