Die meisten CLAUDE.md-Hinweise sind für Solo-Entwickler geschrieben, die an einem Projekt nach dem anderen arbeiten. Agenturarbeit ist anders: Sie haben ein Portfolio von Client-Projekten, jedes mit seinen eigenen Konventionen, und derselbe Engineer könnte in einer Woche sechs davon anfassen. Die CLAUDE.md-Strategie, die für einen Solo-Dev funktioniert, scheitert im Agenturmaßstab. Dies ist der funktionsfähige Ansatz, auf den wir uns bei Seahawk Media nach 18 Monaten Iteration über 200+ aktive Client-Repositories geeinigt haben.
Haupterkenntnis: CLAUDE.md im Agenturmaßstab benötigt drei Schichten – agenturweite Standards, Client-spezifische Overrides und projektbezogene Notizen –, damit ein Engineer über sechs Repos mit dem richtigen Kontext navigieren kann.CLAUDE.md at agency scale needs three layers, agency-wide standards, client overrides, and per-engagement notes, so one engineer can move across six repos with the right context.
Wenn Sie eine Agentur betreiben, die Claude Code täglich nutzt, und feststellen, dass Engineers über Projekte hinweg völlig unterschiedliche Ergebnisse erhalten, ist dieser Beitrag die strukturelle Lösung.
Warum Solo-Dev-CLAUDE.md-Ratschläge im Agenturmaßstab scheitern
Der Standard-CLAUDE.md-Ratschlag lautet: Schreiben Sie es einmal, optimieren Sie es für Ihr Projekt, halten Sie es unter 500 Zeilen. Das funktioniert, wenn Sie ein Projekt haben. Wenn Sie 50 Client-Repositories haben, entstehen drei Probleme. Derselbe Engineer kann sich nicht merken, welche Konventionen für welchen Client gelten. Neue Engineers, die in ein Projekt einsteigen, sehen sich fünfzig verschiedenen CLAUDE.md-Dateien gegenüber. Der CLAUDE.md-Inhalt driftet ab, wenn Engineers ein Projekt aktualisieren und die anderen vergessen.
Das Lösen im Agenturmaßstab erfordert einen geschichteten Ansatz: agenturweite Standards an einem Ort, clientspezifische Überschreibungen an einem anderen und Kontext pro Engagement an einem dritten. Die Schichten stapeln sich statt sich zu duplizieren.
Das Drei-Schichten-Modell CLAUDE.md
Schicht 1: agenturweite Standards
Eine einzige CLAUDE.md-Vorlage existiert in einem privaten GitHub-Repository unserer Agentur. Sie umfasst: Code-Stil über alle Sprachen, die wir einsetzen, unsere verbotenen Muster, unsere Test-Konventionen, unsere Sicherheitsstandards, unsere britische Schreibweise-Regel, unsere Standard-Deployment-Einstellungen. Diese Datei hat etwa 400 Zeilen und wird ein paar Mal pro Jahr geändert.
Jedes neue Kundenprojekt beginnt damit, diese Datei zu symlinken oder zu kopieren. Änderungen an der agenturweiten Datei werden mit vierteljährlicher Kadenz in Projekte übernommen. Ingenieure können sich darauf verlassen, dass diese Konventionen identisch sind, unabhängig davon, welches Projekt sie öffnen.
Schicht 2: kundenspezifische CLAUDE.md
Jedes Kunden-Repository hat seine eigene CLAUDE.md, die die agenturweite importiert und kundenspezifische Details hinzufügt: ihren Stack, ihren Hosting-Provider, ihre Plugins, ihre Team-Konventionen, ihre redaktionelle Voice, ihre verbotenen Plugins. Diese Datei umfasst typischerweise 100 bis 200 Zeilen und ändert sich, wenn sich das Kundenengagement neu strukturiert.
Wir verwenden eine einfache Include-Direktive oben: „## Agency standards" mit einem Link zur agenturweiten Datei, dann „## Client-specific" mit den Overrides. Claude liest beide, weil sie beide im Projekt-Tree existieren.
Schicht 3: engagementspezifische Notizen
Spezifischer, zeitlich begrenzter Kontext: das aktuelle Sprint-Ziel, die aktiven Erkenntnisse aus der Discovery, das Log der jüngsten Entscheidungen, die Liste offener Fragen. Existiert in CLAUDE_NOTES.md oder ähnlich, wird wöchentlich während des Engagements aktualisiert, wird bei Engagement-Abschluss archiviert.
Hier scheitern die meisten Agenturen bei der CLAUDE.md-Hygiene. Die ersten zwei Schichten bleiben sauber; die dritte wird unordentlich und veraltet. Wir lösen das mit einer Freitagnachmittags-Review-Kadenz: Jeder Ingenieur überprüft seine aktive CLAUDE_NOTES.md und aktualisiert oder archiviert sie.
Die Forbidden-Pattern-Liste, die sich verstärkt
Das einzelne Element mit der höchsten Hebelwirkung in unserem agencyweiten CLAUDE.md ist die Forbidden-Pattern-Liste. Zwanzig Einträge, vierteljährlich aktualisiert. Beispiele aus der aktuellen Liste:
Never use eval() in any language we ship.
Never use query_posts() in WordPress (use WP_Query instead).WordPress (use WP_Query instead).
Never use any in TypeScript without an explicit "// suppressed: <reason>" comment.
Never use document.write() in any context.
Never commit secrets to git, ever, regardless of branch.
Verwende niemals Gedankenstriche in kundenorientiertem Text (Standardmethode zur Vermeidung von KI-Erkennung).
Deaktiviere RLS auf Supabase-Tabellen niemals, um einen Bug zu beheben.Supabase tables to fix a bug.
Push niemals direkt zu main (immer PR).
Erstelle nie eine neue Datei, wenn eine vorhandene bearbeitet werden kann.
Die Liste wächst, weil wir jedes Mal, wenn ein Engineer eine dieser Regeln bricht, die Regel hinzufügen. Claude liest die Liste der verbotenen Muster in jeder Sitzung und weigert sich, Code zu generieren, der gegen sie verstößt. Die Klasse von Bugs, die wir früher in Staging ausgeliefert haben, ist weg.
Was gehört nicht in CLAUDE.md
Fünf Dinge, die wir explizit nicht in Agency-CLAUDE.md-Dateien einfügen:
Projekt-Statusupdates. Sie veralten; sie gehören in Linear oder Notion.
Lange architektonische Begründungen. Gehören in Design Docs; CLAUDE.md sollte auf sie verweisen, nicht sie duplizieren.
Client-seitige Secrets, Credentials oder irgendetwas Sensibles. Auch private CLAUDE.md-Dateien sind zu anfällig für Lecks.
Persönliche Vorlieben einzelner Engineers. Die Standards müssen agency-weit gelten; Engineer-spezifische Vorlieben gehören in ihre eigene .claude/settings.json.
Marketing-Copy oder Sales-Sprache. CLAUDE.md ist Engineering-Kontext; es sollte so klingen, als hätte es ein Senior Engineer für andere Engineers geschrieben.
Wie CLAUDE.md die Einstellungsgleichung verändert
Ein Senior-Engineer, der über das gesamte Client-Portfolio ausliefern kann, ohne jedes Projekt bei jedem Besuch neu zu lernen, ist dramatisch wertvoller als einer, der das nicht kann. Das dreilagige CLAUDE.md-System macht das möglich. Die Onboarding-Zeit für neue Engineers sank von ungefähr 2 Wochen projektspezifischer Einarbeitung auf 3 Tage, weil die Konventionen kodifiziert statt tribal sind.
Derselbe Engineer, mehr Output, weniger Onboarding-Overhead, weniger Context-Switch-Belastung. Die Hiring-Pipeline schiffte weniger Junior-Engineers und mehr Senior-Engineers, sobald wir dieses System einführten, weil Junior-Engineers nicht mehr nötig waren, um den projektspezifischen Kontext aufzusaugen, der vorher die einzige Möglichkeit war, Konventionen zu transferieren.
Das Wichtigste
Agency-scale CLAUDE.md ist ein geschichtetes System: agentur-weite Standards als Basis, Client-spezifische Overrides in der Mitte, Engagement-spezifische Notizen oben. Die Forbidden-Pattern-Liste ist der höchstgradig wirksame Bereich. Vermeide veraltete Inhalte in der Engagement-Schicht mit einem Friday-Review-Rhythmus.
Implementiere das dreilagige Modell und deine Engineers stoppen mit dem Versand von inkonsistentem Output über das Portfolio hinweg. Überspring es und du bezahlst für KI-Unterstützung, die je nachdem, welches Projekt der Engineer zuletzt geöffnet hat, unterschiedliche Arbeit produziert.
Häufig gestellte Fragen
Was ist eine CLAUDE.md-Datei?
CLAUDE.md ist eine Projektdatei, die Claude Code deine Standards, deinen Stack und deine Konventionen mitteilt, damit seine Ausgabe in deine Codebasis passt. Im Agenturmaßstab reicht eine flache Datei pro Projekt nicht aus, daher nutzt dies ein Drei-Schichten-Modell über viele Client-Repos.
Wie skalierst du CLAUDE.md über viele Client-Projekte?
Mit einem Drei-Schichten-Modell: agenturweite Standards, die überall gelten, Client-spezifische Overrides pro Account und projektbezogene Notizen für ein bestimmtes Projekt. Der gleiche Engineer kann in einer Woche zwischen sechs Client-Repos wechseln und hat in jedem den richtigen Kontext, ohne ihn neu zu schreiben.
Was sollte nicht in CLAUDE.md gehen?
Secrets, alles, was sich ständig ändert, und Rauschen, das die wichtigen Regeln verwässert. Halte dich an dauerhafte Standards und Konventionen. Ein überladenes CLAUDE.md wird ignoriert; ein straff geschichtetes, das die verbotenen Muster klar benennt, ist das, was tatsächlich die Ausgabe verändert.
Ändert CLAUDE.md, wie du einstellst?
Es senkt die Onboarding-Kosten. Wenn Standards in einem geschichteten CLAUDE.md leben, erbt ein neuer Engineer die Konventionen der Agentur durch das Tool, statt sich Monate Stammeswissen anzueignen. Es verschiebt die Einstellung weg von Memorieren der Hausrichtlinien hin zu Urteilsfähigkeit.