Eine CLAUDE.md, die nach sechs Monaten noch stimmt

Die üblichen Vorlagen beschreiben den Zustand: welche Sprache, welche Befehle, welche Ordner. Das ist richtig und reicht für die erste Woche.

Danach beginnt der Teil, den keine Vorlage abbildet. Ein Umbau nimmt eine Entscheidung zurück. Eine Regel stellt sich als falsch heraus. Ein Bereich wird entfernt, und drei Monate später fragt jemand, wo er geblieben ist.

Die Datei dieses Projekts ist in 26 Commits von 71 Zeilen auf über 1.100 gewachsen. Der größte Teil davon ist nicht Beschreibung, sondern Begründung — und genau der Teil entscheidet, ob sie nach einem halben Jahr noch stimmt.

Code wird ausgeführt. Läuft er nicht mehr, fällt es auf. Eine Beschreibung wird gelesen, und eine falsche Beschreibung liest sich genauso flüssig wie eine richtige.

Dazu kommt der Leser. Ein Mensch, der einen veralteten Satz liest, gleicht ihn stillschweigend mit dem ab, was er im Repo sieht. Ein Assistent tut das nicht — er nimmt den Satz als gegeben und baut darauf auf.

Deshalb ist der teuerste Fehler in so einer Datei nicht die Lücke, sondern die Aussage, die einmal gestimmt hat.

Ein eigenes Änderungsprotokoll neben der Datei wird nach drei Einträgen nicht mehr gepflegt. Der Weg, der hier funktioniert, sind Stand-Blöcke im Kopf der Datei selbst.

Jeder Block trägt ein Datum und beantwortet eine Frage: Was hat sich zuletzt geändert und warum. Der neueste steht oben, ältere rutschen nach unten, gelöscht wird keiner.

Das klingt nach Ballast und ist das Gegenteil. Wer nach vier Monaten wissen will, warum eine Seite anders gebaut ist als die daneben, findet die Antwort im Block von damals — samt der Ansage, auf die sie zurückgeht. Diese Datei trägt inzwischen sieben solcher Blöcke.

Eine Regel ohne Anlass ist eine Meinung, und Meinungen werden beim nächsten Umbau überstimmt. Eine Regel mit Anlass ist eine Erfahrung, und die überlebt.

Ein Beispiel aus diesem Repo: Knöpfe bekommen eine Mindesthöhe statt einer festen Höhe. Als Regel allein klingt das nach Geschmack. Der Anlass steht daneben — eine längere Beschriftung lief oben und unten aus der Fläche heraus, weil die Höhe festgeschrieben war.

Dazu gehört die Prüfanweisung: Wer eine Beschriftung verlängert, sieht sie sich bei 360 Pixel Fensterbreite an. Dort bricht zuerst etwas um. Aus drei Zeilen wird so eine Regel, die niemand versehentlich zurücknimmt.

Offene Punkte wandern normalerweise in ein Ticketsystem. Dort sind sie richtig aufgehoben für die Planung — und unsichtbar für den, der gerade an der Datei arbeitet.

Was hier stattdessen funktioniert: ein Warnzeichen im Fließtext, direkt an der Stelle, die betroffen ist. Zwölf solcher Absätze stehen derzeit in dieser Datei.

Der Unterschied ist die Konsequenz. Ein offener Punkt in einem Ticket ist eine Aufgabe. Ein offener Punkt an der Stelle, an der jemand gleich etwas ändern will, ist eine Warnung — und wenn daran eine Folge hängt, steht sie gleich dabei.

Entfernter Code ist nicht weg, er ist in der Versionsgeschichte. Nur findet ihn dort niemand, der nicht weiß, wonach er sucht.

Deshalb bekommt jede größere Entfernung einen eigenen Abschnitt: was entfernt wurde, warum, unter welcher Commit-Kennung es liegt, und der Befehl, mit dem man es zurückholt. Dazu die Liste dessen, was danach wieder einzutragen ist — Navigationseinträge, Umgebungsvariablen, Weiterleitungen.

Das ist der Abschnitt, der am seltensten gebraucht wird und am meisten spart, wenn es soweit ist.

Erlaubnisse sind langweilig, Verbote sind wertvoll. Ein Assistent, der weiß, was gewünscht ist, trifft trotzdem hundert Entscheidungen, zu denen nichts dasteht.

Ein Abschnitt darüber, welche Muster ausdrücklich nicht gebaut werden, erspart genau diese Rückfragen. In diesem Projekt steht dort unter anderem, dass Kachelraster mit Symbolen keine Gliederung ersetzen und dass ein Etikett über jeder Überschrift nicht die Hausform ist.

Wichtig ist die Alternative daneben. Ein Verbot ohne Ersatz führt dazu, dass etwas anderes Beliebiges entsteht.

Über tausend Zeilen klingen nach zu viel. Sie sind es nicht, solange die Datei navigierbar bleibt — Überschriften, Ankerlinks, Tabellen statt Absätzen, wo eine Tabelle trägt.

Die Grenze liegt woanders. Sobald ein Abschnitt Entscheidungen enthält, die nicht jeder Arbeitsschritt braucht, gehört er ausgelagert: in eine eigene Regeldatei oder in eine Referenz, die bei Bedarf gelesen wird.

Die Faustregel dahinter ist einfach. Was bei jedem Handgriff gilt, steht in der Hauptdatei. Was nur für eine bestimmte Aufgabe gilt, steht dort, wo diese Aufgabe beschrieben ist.

Nicht daran, dass sie vollständig aussieht. Sondern an einer Frage, die man an jede Zeile stellen kann: Würde eine fremde Person daraus dieselbe Entscheidung treffen wie ich letzten Monat?

Wo die Antwort nein lautet, fehlt nicht Text, sondern der Anlass. Und wo die Antwort niemandem einfällt, war die Regel vermutlich nie eine.