CLAUDE.md und Projektkontext: was ein KI-Agent über Ihre Codebasis wissen muss

Teil 2 von 3 der Serie „KI-Entwicklung mit Leitplanken“. Teil 1: Spezifikation vor Code · Teil 3 (automatische Qualitätsprüfungen) erscheint am 12. November.

Stellen Sie sich vor, Sie bekommen jeden Morgen einen neuen Entwickler. Er ist sehr gut, sehr schnell, kennt jedes Framework, und er hat Ihr Projekt noch nie gesehen. Am Abend vergisst er alles wieder.

So arbeitet ein KI-Agent. Jede Sitzung beginnt bei null. Was er über Ihr Projekt weiß, liest er aus dem Code ab, und was nicht im Code steht, rät er.

Die Lösung ist so einfach, dass sie oft übersehen wird: eine Datei, die der Agent zu Beginn jeder Sitzung liest. Bei Claude Code heißt sie CLAUDE.md, andere Werkzeuge haben eigene Namen (AGENTS.md, .cursorrules). Das Prinzip ist dasselbe.

Wo der Agent ohne Kontext danebenliegt

Bei bauernjobs.de, meiner Jobplattform für die Landwirtschaft, gibt es seit Februar 2026 eine CLAUDE.md. Die Regeln darin sind fast alle aus Fehlern entstanden. Ein paar Beispiele:

Die Ordnerstruktur. Die Anwendung läuft auf Laravel 13, hat aber die Struktur von Laravel 10 behalten: Middleware in app/Http/Kernel.php, Zeitpläne in app/Console/Kernel.php. Ein Modell, das Laravel 13 kennt, legt neue Middleware in bootstrap/app.php an. Dort wird sie nie geladen. Der Code sieht richtig aus, läuft aber nicht. Eine Zeile im Kontext verhindert das: „Laravel-10-Struktur, kein bootstrap/app.php. Folge dem bestehenden Layout.“

Die Laufzeitumgebung. Auf meinem Rechner ist eine ältere PHP-Version installiert als im Projekt. Ohne Hinweis führt der Agent php artisan auf dem Host aus, bekommt seltsame Fehler und beginnt, „Kompatibilitätsprobleme“ zu beheben, die es nicht gibt. Die Regel: „Alles PHP läuft im Docker-Container, nie auf dem Host.“

Das Verhalten, das man nicht sieht. Nachrichten zwischen Landwirt und Saisonkraft werden übersetzt, aber nicht sofort, sondern alle drei Minuten im Stapel. Wer das nicht weiß, „repariert“ die vermeintlich fehlende Echtzeitübersetzung. Im Kontext steht deshalb ausdrücklich, welche Befehle in welchem Takt laufen und dass das so gewollt ist.

Was in eine Kontextdatei gehört

Nach drei Jahren mit bauernjobs.de und dem Umbau dieser Website hier (ghinea.net) ist meine Liste kurz:

Was das Projekt ist, in drei Sätzen. Für wen, was es tut, was das Besondere ist.
Wie man es startet und prüft. Die exakten Befehle für Tests, Formatierung, statische Analyse. Der Agent soll sie ausführen, nicht erfinden.
Wo die Dinge liegen, wenn es vom Framework-Standard abweicht. Nur die Abweichungen, nicht die ganze Ordnerstruktur.
Konventionen, die man im Code nicht erkennt. Bei ghinea.net zum Beispiel: JSON-LD nie von Hand in Blade schreiben, sondern über eine Hilfsklasse. Keine Google Fonts, weil die Datenschutzerklärung sie nicht abdeckt.
Was gewollt ist, obwohl es seltsam aussieht. Die Stapelübersetzung. Ein Ordner, der eingecheckt ist, obwohl er generiert wird. Eine Seite, die es absichtlich nur auf Deutsch und Englisch gibt.
Was der Agent nicht tun darf. Bei mir: keine Commits ohne Aufforderung, nichts auf dem Produktionsserver verändern.

Was nicht hineingehört

Alles, was der Code selbst sagt. Eine Liste aller Modelle oder Controller veraltet beim nächsten Commit und kostet bei jeder Sitzung Kontext.
Allgemeine Ratschläge. „Schreibe sauberen Code“ ändert nichts. „Formatierung nach PSR-12, pint --test muss grün sein“ ändert etwas.
Geheimnisse. Keine Passwörter, keine API-Schlüssel. Die Datei liegt im Repository.

Zwei Ebenen: Regeln und Fahrplan

Eine CLAUDE.md beschreibt, wie im Projekt gearbeitet wird. Sie sagt nichts darüber, woran gerade gearbeitet wird und warum.

Dafür nutze ich eine zweite Datei. Bei ghinea.net ist das openspec/project.md: der aktuelle Stand, die Angebote, offene Entscheidungen und eine Roadmap mit nummerierten Punkten (A1, B4, D9 …). Die CLAUDE.md verweist darauf: „Lies das zuerst bei jeder nicht trivialen Aufgabe.“

Dazu kommt eine Konfiguration für OpenSpec, die Regeln für jeden Planungsschritt festlegt. Bei mir zum Beispiel:

Jeder Vorschlag nennt den Roadmap-Punkt, auf den er sich bezieht.
Jeder Vorschlag hat einen Abschnitt „Nicht Teil dieser Änderung“.
Jede neue öffentliche Seite braucht deutsche und englische Sprachdateien und einen Eintrag in der Sitemap.

Die dritte Regel ist entstanden, nachdem die erste Angebotsseite live ging, aber nicht in der Sitemap stand und unter der deutschen URL einen 404 lieferte. Seitdem steht sie in jeder Aufgabenliste, die der Agent schreibt.

Die gefährlichste Kontextdatei ist die veraltete

Beim Audit von bauernjobs.de im September 2026 fiel auf: In der CLAUDE.md stand ein falscher Pfad für den Adminbereich. Der Pfad war irgendwann geändert worden, die Kontextdatei nicht.

Das ist schlimmer als gar keine Angabe. Ein Agent ohne Information schaut im Code nach. Ein Agent mit falscher Information vertraut ihr, und zwar mit derselben Sicherheit, mit der er richtige Informationen verwendet.

Deshalb gilt bei mir:

Die Kontextdatei wird im selben Commit geändert wie der Code. Wenn eine Route umzieht, ändert sich auch die Zeile, die sie beschreibt.
Der Agent pflegt sie mit. Am Ende einer Änderung prüft er, ob etwas in CLAUDE.md nicht mehr stimmt. Das gehört zum Abschluss wie die Tests.
Fakten mit Datum. „Der alte Server wurde am 25.09.2026 abgeschaltet“ ist überprüfbar. „Der alte Server wird nicht mehr benutzt“ ist es nicht.

Was Sie daraus mitnehmen können

Wenn Ihr Team KI-Agenten einsetzt und es keine Kontextdatei gibt, ist das der günstigste Hebel, den Sie haben. Eine Stunde Arbeit:

Lassen Sie den Agenten einen ersten Entwurf aus dem Code erzeugen (bei Claude Code: /init).
Streichen Sie alles, was der Code selbst sagt.
Ergänzen Sie die fünf Dinge, die jeder neue Kollege in der ersten Woche falsch macht.
Behandeln Sie die Datei ab jetzt wie Code: Review, Commit, Pflege.

Kontext sagt dem Agenten, was gilt. Er garantiert aber nicht, dass sich der Agent daran hält. Dafür braucht es Prüfungen, die automatisch laufen und nicht verhandelbar sind. Darum geht es im dritten Teil, der am 12. November erscheint.

Ihr Team arbeitet mit Claude Code, Cursor oder Copilot, aber jeder anders? Als Fractional Tech Lead schreibe ich mit Ihnen die Kontextdateien und Regeln, damit die Agenten im ganzen Team nach denselben Standards arbeiten. Erstgespräch buchen