Sieben Fehler in CLAUDE.md, die die Ausgabe von Claude Code heimlich verschlechtern.

Diese Unsicherheit ist genau der Ort, an dem schlechte Konfigurationen entstehen. Keine Fehler, keine Warnungen – nur vage, allgemein gehaltener und leicht fehlerhafter Code, Session für Session. Eine unklare oder überdimensionierte Datei hilft nicht nur nicht, sondern verbraucht Ressourcen und behindert die eigentliche Aufgabe. Deshalb sollten Sie vor dem Ändern einer einzigen Zeile erst genau prüfen, was darin enthalten ist, bevor Sie die Probleme nacheinander beheben.

Fehler 1: eine vage Beschreibung des Stack-Ökosystems

Eine Zeile wie We use React and a database. sagt Claude fast nichts. Es wird vermutlich auf den Next.js-Router tippen, mehr oder weniger zufällig eine State-Bibliothek auswählen und Tests in einem Framework schreiben, das Sie nicht verwenden. Das Ergebnis lässt sich zwar kompilieren, passt aber dennoch nicht zu Ihrer Codebasis.

Schreiben Sie stattdessen alles genau auf:

Framework: Next.js 15, app router only
State: TanStack Query v5 for server state, Zustand for client state
Testing: Vitest + React Testing Library
Package manager: pnpm

Nur genaue Versionen und Konventionen verwandeln allgemeine Ausgaben in Code, der so aussieht, als gehöre er zu Ihrem Repository. Nennen Sie sie explizit.

Fehler 2: Keine Einschränkungen, kein „Tu das niemals“

Das ist der häufigste stillschweigende Misserfolg. Die Menschen beschreiben das Projekt, ziehen aber nie klare Grenzen. Ohne Limits führt Claude npm in einem pnpm-Projekt aus, bearbeitet generierte Dateien und refaktorisiert Code, den man nie erwähnt hat. Das sind keine Halluzinationen – es handelt sich um sinnvolle Vermutungen, weil keine Regel etwas anderes vorschreibt.

Fügen Sie einen Einschränkungsblock hinzu:

Constraints:
- Never install new dependencies without asking first
- Never edit files under /generated or /prisma/migrations
- Always use pnpm, never npm or yarn
- Do not refactor code outside the scope of the current task

Regeln darüber, was man nicht tun soll, sind nützlicher als bloße Beschreibungen, denn sie verhindern teure Fehler bereits im Vorfeld.

Fehler 3: Agenten und Subagenten ignorieren

Die meisten CLAUDE.md-Dateien sind so verfasst, als würde ein einzelnes Modell allein arbeiten, ohne Anleitungen für spezialisierte Subagenten, die neben der Hauptsession laufen. Wenn Sie Subagenten für Tests, Dokumentation oder Bereitstellung verwenden, geben Sie dies in der Datei an: listen Sie alle Agenten auf, den Bereich, für den jeder zuständig ist, sowie die Situationen, in denen der Hauptagent Aufgaben an andere weiterleiten sollte.

Agents & delegation:
- test-agent: runs Vitest, owns /tests — do not write tests in the main session
- docs-agent: handles JSDoc and README updates only
- main agent: feature code, routing, API handlers

Falls Sie das Delegierungsmodell noch entwerfen, hilft es, vor der endgültigen Gestaltung zu verstehen, wie Fähigkeiten, Subagenten, Slash-Befehle und MCP voneinander abweichen.

Fehler 4: Eine überdimensionierte Datei, die Ihren Kontextbudget aufbraucht

Mehr ist nicht besser. Ein 2.000 Zeilen langer CLAUDE.md, der mit vollständigen Stilrichtlinien, API-Dokumentationen und Änderungsprotokollen gefüllt ist, lädt all das bei jeder Sitzung hoch – egal ob relevant oder nicht. Dadurch wird die eigentliche Aufgabe beeinträchtigt, und da die Konzentration bei einem überfüllten Kontext nachlässt, erhält man letztendlich ein Modell, das zwar technisch gesehen Ihre Regeln gelesen hat, sie aber dennoch nicht zuverlässig anwendet.

Beschränken Sie sich auf das Wesentliche. Verweisen Sie auf Dateien oder Fähigkeiten, um die Details zu erhalten, anstatt sie direkt einzufügen. Eine Regel, die sich auf ein bestimmtes Paket bezieht, sollte in einer darauf ausgerichteten Datei stehen und nicht im Wurzelverzeichnis. Zählen Sie die Tokens der Datei vor und nach der Kürzung, um sicherzustellen, dass die Anpassung tatsächlich etwas bewirkt hat.

Fehler 5: Anweisungen, auf die Claude nicht reagieren kann

Nehmen Sie beispielsweise Schreibe sauberen, wartbaren, hochwertigen Code. Claude glaubt bereits, dies zu tun, weshalb vage Adjektive keine Wirkung zeigen. Ersetzen Sie sie durch Regeln, die überprüft werden können:

- Functions must be under 40 lines
- No default exports
- Colocate test files next to source files
- No inline styles — use CSS modules

Operative Regeln geben dem Modell ein messbares Ziel. Inspirierende Formulierungen hingegen nicht.

Fehler 6: veraltete Regeln, die im Widerspruch zum Code stehen

CLAUDE.md rot existiert tatsächlich. Angenommen, das Datei enthält immer noch die Anweisung „use Redux“, sechs Monate nachdem das Team auf Zustand umgestiegen ist. Diese Regel hat keine harmlosen Auswirkungen – sie setzt Ihre Konfiguration gegen Ihren tatsächlichen Code, wodurch Claude zwischen dem Vertrauen in die eine oder andere Variante wechselt.

Überprüfen Sie die Datei stets, wenn sich die Abhängigkeiten erheblich ändern, und machen Sie diese Überprüfung zu einem Punkt auf Ihrer PR-Checkliste. Bewahren Sie die Änderungsverfolgung im Git auf, damit Sie sehen können, wann jede Regel zuletzt geändert wurde. Ein veraltetes CLAUDE.md ist oft schlimmer als keines überhaupt.

Fehler 7: eine einzige riesige Textdatei

In einem Monorepo führt eine einzige, unstrukturierte CLAUDE.md dazu, dass Claude Frontend-Regeln auf Backend-Code anwendet und umgekehrt. Wenn alles zu einem einheitlichen Block zusammenfällt, gibt es keine Möglichkeit, den Kontext einzuschränken.

Platzieren Sie globale Regeln in einer root-Datei namens CLAUDE.md und fügen Sie paket- oder servicebezogene Dateien hinzu. In der Root-Datei sollten klare Abschnittsüberschriften verwendet werden:

# Project Overview
# Stack & Versions
# Constraints
# Agents & Delegation
# Per-Package Notes

Durch die richtige Struktur weiß Claude, welche Regeln wo gelten.

Eine schnelle Überprüfung und eine Checkliste

Hören Sie auf zu raten und bewerten Sie die Datei anhand von vier Kriterien: Spezifität, Einschränkungen, Struktur und Größe. Ein Vergleich mit einem gut strukturierten Vorbild hilft ebenfalls, da er zeigt, wie eine gute Datei in der Praxis aussieht.

Gehen Sie diese Fragen durch:

• Enthält sie die genauen Versionen des Frameworks sowie der Bibliotheken?
• Gibt es einen Abschnitt mit Einschränkungen, der klare „Tun Sie das auf keinen Fall“-Regeln enthält?
• Listet sie auf, welche Agenten vorhanden sind und was jeder von ihnen verantwortet?
• Enthält sie weniger als 200 Zeilen, wobei Details in Skills oder verlinkte Dateien ausgelagert sind?
• Sind alle Anweisungen praktikabel und nicht nur idealistisch formuliert?

Hat jemand in den letzten 30 Tagen nach veralteten Regeln darin gesucht?

Ist es nach Überschriften gegliedert oder nach paketbezogenen Dateien, falls Sie ein Monorepo verwenden?

Antworten Sie auf mehr als zwei dieser Fragen mit „Nein“, dann kostet Ihr CLAUDE.md wahrscheinlich mehr, als er einspart.