CLAUDE.md, agents.md & Co: Eine Datei steuert deine gesamte KI-Entwicklung

Du gibst der KI einen Auftrag. Sie liefert Code. Und er ist falsch.

Nicht weil die KI dumm wäre. Sondern weil sie dein Projekt nicht kennt. Sie weiss nicht, dass deine Website auf Deutsch ist. Sie weiss nicht, dass dein Firmenname zusammengeschrieben wird. Sie weiss nicht, dass du BEM für CSS-Klassen verwendest und Eleventy als Static Site Generator nutzt.

Also rät sie. Und raten ist das Gegenteil von Zuverlässigkeit.

Genau das passiert jeden Tag tausendfach: Entwickler setzen leistungsstarke KI-Assistenten ein - Claude Code, Cursor, GitHub Copilot - und wundern sich, warum das Ergebnis nicht zu ihrem Projekt passt. Die Antwort ist so simpel wie mächtig: Der KI fehlt Kontext.

Und die Lösung? Eine einzige Datei. Eine Markdown-Datei, die im Projektordner liegt und der KI alles beibringt, was sie wissen muss. Kein Plugin. Kein Abo. Keine Konfiguration. Nur Text, der gelesen wird.

In diesem Artikel zeige ich dir, was KI-Kontext-Dateien sind, warum jedes grosse Tool eine eigene Variante hat - und wie du in 15 Minuten deine eigene erstellst.

Was sind KI-Kontext-Dateien?

KI-Kontext-Dateien sind Markdown-Dateien in deinem Projekt, die einem KI-Assistenten projektspezifischen Kontext liefern. Sie beschreiben: Welchen Tech-Stack nutzt das Projekt? Welche Regeln gelten für Code? Wie ist die Ordnerstruktur aufgebaut? Welche Befehle gibt es? Was darf die KI tun - und was nicht?

Wie ein Onboarding-Dokument

Stell dir vor, du stellst einen neuen Entwickler ein. Am ersten Tag bekommt er ein Dokument: „So arbeiten wir hier." Darin steht alles - von den Coding-Konventionen über die Deployment-Pipeline bis zu den ungeschriebenen Regeln des Teams.

Eine KI-Kontext-Datei ist genau das. Nur für die KI.

Der Unterschied: Ein Mensch kann nachfragen, wenn etwas unklar ist. Eine KI rät. Deshalb muss die Datei präzise, vollständig und unmissverständlich sein.

Warum Markdown?

Markdown ist kein Zufall. Es ist:

• Universell lesbar - jeder Entwickler, jede KI versteht es
• Versionierbar - lebt im Git-Repository, hat eine History
• Menschenlesbar - kein XML, kein YAML, kein JSON - sondern klarer Text mit Struktur
• Leichtgewichtig - eine Datei, kein Framework

Das Format zwingt dich zur Klarheit. Wer in Markdown schreibt, schreibt für Menschen und Maschinen gleichzeitig.

Die Landschaft: Wer nutzt was?

Was 2024 als experimentelles Feature begann, ist 2025/2026 zum Standard geworden. Praktisch jeder KI-gestützte Code-Editor hat sein eigenes Format:

Die gute Nachricht: Der Inhalt ist portierbar

Obwohl jedes Tool seinen eigenen Dateinamen hat, ist das Konzept identisch: Textbasierter Kontext für eine KI. Der Kern einer CLAUDE.md funktioniert genauso in einer AGENTS.md oder CONVENTIONS.md. Du schreibst den Kontext einmal - und portierst ihn.

Die Unterschiede liegen im Detail: Claude Code unterstützt hierarchische Kontext-Dateien (eine im Projektroot, weitere in Unterordnern). Codex legt Wert auf Sandbox-Befehle. Cursor und Windsurf setzen auf Verzeichnisse mit mehreren Regel-Dateien statt einer einzigen Datei.

Aber zu 90 Prozent schreibst du dasselbe: „Das ist mein Projekt, das sind meine Regeln, so arbeiten wir hier."

Anatomie einer echten Kontext-Datei

Theorie ist gut, Praxis ist besser. Ich zeige dir die sechs Bereiche, die eine gute Kontext-Datei ausmachen - mit echten, vereinfachten Beispielen aus unserer täglichen Arbeit.

1. Projekt-Übersicht

Die KI muss wissen, womit sie arbeitet. Tech-Stack, Framework-Versionen, Architektur-Entscheidungen.

## Projekt
- Static Site Generator: Eleventy v3
- Templating: Nunjucks
- CSS: ITCSS (7 Layer)
- Hosting: Statische Dateien

Kurz, präzise, scanbar. Keine Prosa - eine Liste.

Für grössere Projekte wird dieser Abschnitt detaillierter:

## Projekt
- Backend: Symfony 7 (PHP 8.4) mit PostgreSQL
- Frontend: React 19, TypeScript, Vite
- Infrastruktur: Docker (10+ Container)
- API: REST mit JSON:API Standard

2. Verhaltensregeln

Hier definierst du, wie die KI arbeiten soll. Sprache, Namenskonventionen, Formatierung.

## Wichtige Regeln
- Deutsche Website - alle Texte mit korrekten Umlauten (ä, ö, ü, ß)
- Firmenname: 360WebManager (zusammengeschrieben, kein Leerzeichen)
- BEM für CSS-Klassen
- Mobile-First Responsive Design

Das klingt trivial? Ohne diese Regeln schreibt Claude „360° Web Manager" mit Leerzeichen und Grad-Zeichen. Copilot generiert englische Kommentare für eine deutsche Website. Cursor erstellt CSS-Klassen ohne BEM-Notation.

Diese vier Zeilen verhindern hunderte Korrekturen.

3. Projektstruktur

Die KI braucht eine Karte. Wo liegt was? Welcher Ordner hat welche Verantwortung?

## Projektstruktur
src/
├── _data/           # Globale Daten (JSON)
├── _includes/
│   ├── components/  # Wiederverwendbare Komponenten
│   ├── sections/    # Seitensektionen
│   └── layouts/     # Basis-Layouts
├── css/             # ITCSS-Architektur (7 Layer)
├── js/              # JavaScript Module
└── index.njk        # Homepage

Ohne Struktur sucht die KI blind. Mit Struktur weiss sie sofort: „Neue CSS-Datei? Gehört in css/6-pages/. Neue Komponente? Gehört in _includes/components/."

4. Commands und Workflows

Wie wird entwickelt? Wie baut man das Projekt? Wie testet man?

## Commands
npm run dev    # Lokaler Server mit Hot-Reload
npm run build  # Production Build
npm run clean  # dist/ löschen

Für komplexere Projekte:

## Commands
# Alle Backend-Operationen im Docker-Container:
docker exec -it app bash

# Tests
php bin/phpunit --filter=UserTest
npm run test:e2e

# Code-Qualität
vendor/bin/phpstan analyse
npm run lint

5. Code-Patterns

Wie sieht guter Code in diesem Projekt aus? Welche Patterns werden verwendet?

## Architektur (CQRS)
Controller → Command/Query → Handler → MessageResponse
- Single-Action Controllers
- Commands mit Validation
- Handlers returnen IMMER MessageResponse

Dieser Abschnitt ist Gold wert bei grösseren Projekten. Statt dass die KI rät, welches Pattern sie verwenden soll, sieht sie die bestehende Architektur und generiert konsistenten Code.

6. Verbote und Pflichten

Was darf die KI nicht? Was muss sie immer tun?

## Regeln
- Migrations: `diff` erstellen erlaubt, `migrate` nur durch User
- PHPStan vor jedem Push ausführen
- Commit Messages: Englisch, Conventional Commits
- NIEMALS Produktionsdaten in Fixtures verwenden

Explizite Verbote sind essenziell. Eine KI, die ungefragt Datenbankmigrationen ausführt, kann Schaden anrichten. Eine, die es nicht darf, ist sicher.

Klein vs. Gross: Der Kontrast

Eine Kontext-Datei für ein kleines Projekt (statische Website) hat 50 bis 100 Zeilen. Sie beschreibt den Stack, die Regeln und die Commands. Das reicht.

Eine Kontext-Datei für ein grosses Projekt (SaaS-Plattform mit Backend, Frontend, Docker, CI/CD) hat 300 bis 500 Zeilen. Sie beschreibt zusätzlich Architektur-Patterns, Container-Strukturen, Test-Strategien und Deployment-Regeln.

Beide folgen derselben Grundstruktur. Der Unterschied ist nur die Tiefe.

Warum Konventionen besser als Konfiguration sind

In der klassischen Entwicklung definierst du Regeln über Konfigurationsdateien: ESLint für Code-Stil, Prettier für Formatierung, tsconfig für TypeScript, SonarQube für Code-Qualität. Jedes Tool hat sein eigenes Format, seine eigene Syntax, seine eigene Lernkurve.

Eine KI-Kontext-Datei ersetzt nicht alle diese Tools. Aber sie macht etwas, das kein Linter kann: Sie erklärt das Warum.

ESLint sagt: „Verwende keine var."

CLAUDE.md sagt: „Wir verwenden const/let statt var, weil unser Projekt auf ES2022+ setzt und Block-Scoping konsistenter ist."

Der Unterschied: ESLint erzwingt eine Regel. CLAUDE.md erklärt einen Kontext. Und eine KI, die den Kontext versteht, schreibt von Anfang an besseren Code - statt erst nach dem Linting korrigiert zu werden.

Das ist der fundamentale Shift: Von reaktiver Korrektur zu proaktiver Korrektheit.

Linter fangen Fehler nach dem Schreiben. Kontext-Dateien verhindern Fehler vor dem Schreiben. Beides hat seinen Platz. Aber wenn du nur eins haben kannst: Nimm den Kontext.

Und es gibt einen weiteren Vorteil: Konventionen in einer Kontext-Datei sind flexibel. Du kannst nuancierte Regeln formulieren, die kein Linter abbilden kann:

• „Verwende deutsche Variablennamen für Business-Logic, englische für technische Utilities"
• „Komponenten-Dateien bekommen einen Prefix basierend auf ihrer Seite"
• „In diesem Projekt bevorzugen wir explizite Imports gegenüber Barrel-Files"

Versuche das mal in einer .eslintrc zu konfigurieren.

Nachbau-Anleitung: In 15 Minuten zur eigenen Kontext-Datei

Genug Theorie. Lass uns eine Kontext-Datei bauen - Schritt für Schritt.

Abkürzung: /init in Claude Code

Wenn du Claude Code nutzt, gibt es eine Abkürzung: den /init-Befehl. Du tippst /init ins Terminal, und Claude scannt dein gesamtes Projekt - Ordnerstruktur, Tech-Stack, vorhandene Konfigurationen, Package-Dateien. Daraus generiert er eine erste CLAUDE.md nach bestem Wissen.

Reicht das als fertige Kontext-Datei? Nein. Claude kennt deine internen Konventionen nicht, weiss nicht wie dein Team arbeitet und welche Regeln dir wichtig sind. Aber als Startpunkt ist /init enorm praktisch: Du bekommst ein solides Grundgerüst, das du dann mit den folgenden Schritten verfeinerst.

Kein Claude Code? Kein Problem. Die folgende Anleitung funktioniert mit jedem Tool.

Schritt 1: Basis-Template (2 Minuten)

Erstelle eine Datei namens CLAUDE.md (oder AGENTS.md, CONVENTIONS.md - je nach deinem Tool) im Wurzelverzeichnis deines Projekts.

# Projektname

## Projekt-Übersicht
- **Typ:** [Website / Web-App / API / Mobile App]
- **Tech-Stack:** [Framework, Sprache, Datenbank]
- **Sprache:** [Deutsch / Englisch / Mehrsprachig]

Drei Zeilen. Aber die KI weiss jetzt: Was baue ich, womit baue ich es, und in welcher Sprache.

Schritt 2: Struktur dokumentieren (5 Minuten)

Das musst du nicht selbst tippen. Gib der KI einen Prompt und lass sie die Arbeit machen:

„Scanne die Projektstruktur und erstelle einen kommentierten Verzeichnisbaum der wichtigsten Ordner. Fokussiere dich auf Ordner, die für die Entwicklung relevant sind - ignoriere node_modules, dist, build und andere generierte Verzeichnisse. Schreib das Ergebnis als Markdown-Abschnitt '## Projektstruktur' in die CLAUDE.md."

Das Ergebnis sieht dann etwa so aus:

## Projektstruktur
src/
├── components/    # UI-Komponenten
├── pages/         # Seitenvorlagen
├── styles/        # CSS/SCSS
├── utils/         # Hilfsfunktionen
├── api/           # API-Routen
└── config/        # Konfiguration

Prüfe das Ergebnis kurz: Fehlt ein wichtiger Ordner? Ist die Beschreibung korrekt? Zwei Minuten Kontrolle, fertig.

Schritt 3: Regeln definieren (5 Minuten)

Denk an die letzten fünf Mal, als die KI etwas falsch gemacht hat. Genau das schreibst du hier rein:

## Regeln
- [Sprach-Regel, z.B. "Alle Texte auf Deutsch mit korrekten Umlauten"]
- [Naming-Regel, z.B. "CSS-Klassen in BEM-Notation"]
- [Architektur-Regel, z.B. "Neue API-Routen immer in /api/ anlegen"]
- [Verbot, z.B. "Keine direkten DOM-Manipulationen, immer über React State"]

Tipp: Formuliere Regeln als klare Anweisungen, nicht als Wünsche. Nicht „Es wäre schön, wenn..." sondern „Verwende IMMER..." oder „NIEMALS...".

Und keine Sorge: Du musst nicht alle Regeln jetzt kennen. In Claude Code kannst du jederzeit während der Arbeit neue Regeln ergänzen - einfach sagen: „Merke dir: Wir verwenden immer Named Exports, keine Default Exports." Claude schreibt die Regel dann selbstständig in die CLAUDE.md. So wächst deine Kontext-Datei organisch, jedes Mal wenn dir beim Arbeiten etwas auffällt.

Schritt 4: Workflows und Commands (3 Minuten)

## Commands
[dein-start-command]    # Entwicklungsserver
[dein-build-command]    # Production Build
[dein-test-command]     # Tests ausführen
[dein-lint-command]     # Code-Qualität prüfen

Fertig. In 15 Minuten hast du eine Kontext-Datei, die sofort die Qualität deiner KI-generierten Code-Ausgabe verbessert.

Starter-Template zum Kopieren

Hier das vollständige Template:

# CLAUDE.md - [Projektname]

## Projekt-Übersicht
- **Typ:** [Website / Web-App / API / ...]
- **Tech-Stack:** [z.B. Next.js 15, TypeScript, Tailwind]
- **Sprache:** [Deutsch / Englisch]
- **Hosting:** [z.B. Vercel, AWS, Hetzner]

## Projektstruktur
[Verzeichnisbaum der wichtigsten Ordner]

## Regeln
- [Regel 1: Sprache und Formatierung]
- [Regel 2: Namenskonventionen]
- [Regel 3: Architektur-Vorgaben]
- [Regel 4: Verbote]

## Commands
[start]   # Entwicklungsserver
[build]   # Production Build
[test]    # Tests
[lint]    # Linting

Fortgeschritten: Die lebende Datei

Eine Kontext-Datei ist kein statisches Dokument. Sie ist eine lebende Datei, die mit deinem Projekt wächst.

Versionskontrolle ist Pflicht

Die Kontext-Datei gehört ins Git - genau wie jede andere Projektdatei. Jede Änderung wird getrackt. Jede Entscheidung ist nachvollziehbar. Wenn sich der Tech-Stack ändert, ändert sich die Datei. Wenn neue Regeln dazukommen, werden sie ergänzt.

Das hat einen Nebeneffekt: Neue Teammitglieder (menschliche wie KI) können die History lesen und verstehen, warum bestimmte Entscheidungen getroffen wurden.

Die KI aktualisiert sich selbst

Das ist vielleicht das Mächtigste an diesem Konzept: Du kannst die KI anweisen, ihre eigene Kontext-Datei zu aktualisieren.

Claude Code hat dafür ein eingebautes Memory-System. Wenn du sagst: „Merke dir, dass wir ab sofort Vitest statt Jest verwenden", aktualisiert Claude seine eigene Kontext-Datei. Beim nächsten Gespräch weiss er es bereits.

Aber auch ohne Memory-Feature kannst du sagen: „Update die CLAUDE.md - wir nutzen jetzt PostgreSQL statt MySQL." Die KI ändert ihre eigene Arbeitsanleitung.

Das ist der Moment, in dem das Konzept zirkulär wird: Die KI liest die Datei, arbeitet danach, und verbessert sie. Ein sich selbst optimierender Feedback-Loop.

Fazit: Eine Datei, maximaler Impact

KI-Kontext-Dateien sind keine Raketenwissenschaft. Sie sind eine Markdown-Datei mit klarem Text. Aber ihr Effekt ist enorm:

• Weniger Korrekturen - die KI macht von Anfang an das Richtige
• Konsistenter Code - über Sessions, Tools und Teammitglieder hinweg
• Schnelleres Onboarding - neue KI-Tools (und Menschen) verstehen sofort das Projekt
• Lebende Dokumentation - die Datei wächst mit und bleibt aktuell

Das Konzept ist tool-agnostisch. Ob du Claude Code, Cursor, Copilot oder Codex nutzt - das Prinzip ist identisch: Gib der KI Kontext, und sie liefert bessere Ergebnisse.

Starte heute. Erstelle eine CLAUDE.md (oder das Äquivalent für dein Tool). 15 Minuten Investition. Hunderte Stunden Zeitersparnis.

Dieser Artikel ist Teil der Software-Pfad-Serie auf dem 360WebManager Blog. Die Serie macht Softwareentwicklung verständlich - von den Grundlagen bis zu fortgeschrittenen Themen wie KI-gestützte Entwicklung.