Agentenbereite Codebasen: Negative Regeln, präzise Namen, Verzeichnis-READMEs

Ein Entwickler in r/ClaudeAI schilderte, wie er seine Android-Codebasis anpasste, nachdem Claude Code wiederholt neue Funktionen in eine monolithische UserManager-Klasse (Auth, Sessions, Profile, Analytics) gestopft hatte. Die wichtigste Erkenntnis: Der Agent erscheint jedes Mal kalt, wie ein neuer Mitarbeiter am ersten Tag, ohne Erinnerung an Architekturentscheidungen. Die Lösung waren explizite Regeln in einer CLAUDE.md im Repository-Stammverzeichnis.

Drei Muster, die den größten Unterschied machten

1. Negative Regeln sind besser als positive

Statt „halte dich an gutes Design“ schreibt der Entwickler Anweisungen wie:

Berühre NICHT BaseActivity – sie wird von 12 Funktionen gemeinsam genutzt und bricht still.

Der Agent ist standardmäßig optimistisch und wählt den Weg des geringsten Widerstands. Gefährliche Pfade explizit zu sperren, stoppt schlechte Entscheidungen effektiver als vage Anleitungen.

2. Namen sind wichtiger als man denkt

Eine Klasse namens UserSessionExpiryHandler ist ein Vertrag. Sie nur Handler zu nennen, ist Rauschen. Der Agent vergleicht Muster stark anhand von Namen; gute Namen reduzieren, wie viel Datei-Lesen er benötigt. Der Entwickler empfiehlt, generische Suffixe zu vermeiden und den Zweck im Namen explizit zu machen.

3. Jedes Verzeichnis erhält eine README, die auflistet, was NICHT dorthin gehört

Statt „dieser Ordner ist für die UI“ sagt die README:

Keine Geschäftslogik in presentation/

Diese negative Formulierung „scheint beim Agenten stärker zu landen“ und verhindert mehr falsche Platzierungen als positive Anleitung.

Praktische Regeln für CLAUDE.md

• Halte Dateien klein. Eine Klasse, eine Aufgabe.
• Erstelle lieber eine neue Datei, als eine alte zu erweitern.
• Erzeuge keine Monolithen – trenne Zuständigkeiten frühzeitig.

Der Entwickler berichtet, dass das Muster, bei dem der Agent eine 600-Zeilen-Datei dreimal in einer Sitzung erneut liest, nach Anwendung dieser Regeln praktisch verschwand. Er vermutet, dass die Token-Kosten deutlich gesunken sind, hat es aber nicht ordentlich gemessen.

Für wen es gedacht ist

Entwickler, die KI-Codierungsagenten (Claude Code, Copilot usw.) verwenden und Token-Verschwendung reduzieren sowie schlechte Architekturentscheidungen verhindern möchten.