Modular CLAUDE.md: Multi-Stack Claude Code Setup

Die meisten CLAUDE.md-Dateien in freier Wildbahn sind ein einziges, massives Dokument, das jeden Stack, jede Konvention und jeden Sonderfall abdeckt, den das Team jemals besprochen hat. Der Inhalt selbst ist meistens in Ordnung. Das Problem liegt in der Bereitstellung. Wenn man 400 oder mehr Zeilen an Anweisungen in jede Claude-Code-Sitzung lädt, verschwendet das Kontext und verwischt die Prioritäten, weil Claude alles lädt, egal woran man gerade arbeitet.

Das ist wichtiger als es scheint. LLMs haben endliche Kontextfenster, und jedes Token an Anweisungen konkurriert mit dem Code, den Claude tatsächlich liest und bearbeitet. Wenn man über mehrere Stacks hinweg arbeitet, bedeutet eine monolithische CLAUDE.md, dass Claude Ihre Docker-Konventionen liest, während Sie eine React-Komponente reparieren, und Ihre SQL-Richtlinien aufnimmt, während Sie einen Python-Endpunkt debuggen. Ein modulares Zwei-Ebenen-Setup behebt das, indem nur die Regeln geladen werden, die für die aktuelle Arbeit relevant sind. Das Ergebnis ist schneller, genauer und einfacher zu warten.

Das Problem mit der monolithischen CLAUDE.md

Eine typische monolithische CLAUDE.md fängt klein an. Man fügt ein paar Coding-Standards hinzu, einige Git-Konventionen, vielleicht eine Notiz zum bevorzugten Testing-Ansatz. Dann wächst das Projekt. Jemand ergänzt Laravel-Regeln. Jemand anderes fügt React-Patterns hinzu. Der DevOps-Ingenieur hinterlegt Docker- und CI/CD-Richtlinien. Das Datenbankteam ergänzt SQL-Konventionen. Sechs Monate später hat man eine 500-Zeilen-Datei über sechs Stacks, und niemand will sie kürzen, weil alle befürchten, etwas kaputt zu machen.

Die Kosten sind real:

Verschwendung des Kontextfensters. Claude lädt jede Anweisung in jeder Sitzung, selbst wenn man nur Dateien in einem einzigen Stack bearbeitet. Eine reine Python-Sitzung lädt trotzdem Laravel-, React-, Docker- und SQL-Regeln.
Signalverwässerung. Wichtige Regeln gehen im Rauschen unter. Wenn alles gleich prominent ist, sticht nichts hervor.
Merge-Konflikte. Fünf Entwickler, die eine Datei bearbeiten, bedeuten ständige Konflikte, besonders in aktiven Projekten.
Veraltete Inhalte. Alte Regeln bleiben bestehen, weil niemand weiß, ob ihr Entfernen Probleme verursacht. Die Datei wächst nur.

Das ist dasselbe Problem, das die Softwareentwicklung vor Jahrzehnten mit dem God Object gelöst hat. Die Lösung ist ebenfalls dieselbe: nach Verantwortlichkeit aufteilen, bei Bedarf laden.

Die Lösung: Modulare Zwei-Ebenen-Regeln

Der claude-code-vscode-multistack-starter ersetzt den monolithischen Ansatz durch eine Zwei-Ebenen-Architektur. Die erste Ebene deckt universelle Belange ab, die in jeder Sitzung gelten. Die zweite Ebene umfasst stack-spezifische Regeln, die nur geladen werden, wenn Claude passende Dateien berührt.

So sieht die Verzeichnisstruktur aus:

.claude/
  rules/
    common.md          # unconditional - always loaded
    testing.md         # unconditional
    git.md             # unconditional
    security.md        # unconditional
    laravel.md         # conditional - paths frontmatter
    react-next.md      # conditional
    python-fastapi.md  # conditional
    node-express.md    # conditional
    docker-devops.md   # conditional
    sql.md             # conditional
  agents/
    laravel-architect.md
    react-ui.md
    python-api.md
    node-backend.md
    devops-reviewer.md
    sql-investigator.md
  hooks/
    session-start.sh
    post-edit-check.sh
  prompts/
    bugfix.md
    refactor.md
    code-review.md
    onboarding.md
  settings.json
CLAUDE.md
scripts/
  detect-stack.sh
  install-local.sh

Ebene 1: Bedingungslose Regeln werden in jeder Sitzung geladen. Das sind übergreifende Belange, die unabhängig von den bearbeiteten Dateien gelten: grundlegende Coding-Standards, Testing-Philosophie, Git-Konventionen und Sicherheitsleitplanken. Sie haben kein paths-Frontmatter, sodass Claude sie immer sieht.

Ebene 2: Bedingte Stack-Regeln werden nur geladen, wenn Claude Dateien liest oder bearbeitet, die bestimmten Glob-Patterns entsprechen. Das ist ein natives Feature von Claude Code. Jede Regeldatei enthält einen paths-Block in ihrem YAML-Frontmatter, der Claude mitteilt, wann sie aktiviert werden soll.

Zum Beispiel wird die Laravel-Regeldatei nur ausgelöst, wenn man PHP-Dateien, Routes, App-Code, Migrationen oder Views berührt:

---
paths:
  - "**/*.php"
  - "**/routes/**"
  - "**/app/**"
  - "**/database/migrations/**"
  - "**/resources/views/**"
---

Die anderen Stack-Regeln folgen demselben Muster. React-Regeln werden bei .tsx, .jsx und next.config.* ausgelöst. Python-Regeln bei .py und pyproject.toml. Node-Regeln bei server.js, app.js und Middleware-Dateien. Docker-Regeln bei Dockerfile und Compose-Dateien. SQL-Regeln bei .sql-Dateien und Migrations-Verzeichnissen.

Der praktische Unterschied ist erheblich. Eine reine Python-Sitzung lädt etwa 80 Zeilen Regeln: die vier bedingungslosen Dateien plus python-fastapi.md. Eine Laravel-plus-Docker-Sitzung lädt etwa 120 Zeilen. Vergleichen Sie das mit einer monolithischen Datei, bei der jede Sitzung 400 oder mehr Zeilen lädt, egal was man gerade tut.

Was in CLAUDE.md gehört und was in Regeldateien

Mit diesem Setup wird CLAUDE.md ein schlanker Router statt einer Enzyklopädie. Sie beschreibt das Projekt auf hoher Ebene, listet die aktiven Stacks auf, legt Standardverhaltenserwartungen fest und importiert die bedingungslosen Regeln über die @-Syntax.

So sieht die eigentliche CLAUDE.md aus:

# Claude Code Project Guide

This repository is a multi-stack starter configuration for Claude Code in VS Code.

## How this repo works

- **Unconditional rules** in `.claude/rules/` (common, testing, git, security)
  load every session.
- **Stack-specific rules** in `.claude/rules/` use `paths` frontmatter to load
  only when you touch matching files.
- **Subagents** in `.claude/agents/` handle focused tasks.
- **Hooks** in `.claude/settings.json` run automation on session start and
  after edits.
- **Prompts** in `.claude/prompts/` provide reusable workflow templates.

## Imported rules (always loaded)

@.claude/rules/common.md
@.claude/rules/testing.md
@.claude/rules/git.md
@.claude/rules/security.md

Die Faustregel ist einfach. Wenn etwas für jede Sitzung gilt, macht man es zu einer bedingungslosen Regel oder schreibt es direkt in CLAUDE.md. Wenn es nur beim Berühren bestimmter Dateien relevant ist, fügt man paths-Frontmatter hinzu und lässt Claude es bei Bedarf laden.

Subagents für fokussierte Arbeit

Subagents sind spezialisierte Agenten, die in .claude/agents/ mit eigenen System-Prompts, Tool-Zugriff und Modellauswahl definiert werden. Sie sind nützlich, wenn eine Aufgabe von fokussierter Expertise profitiert statt von allgemeiner Anleitung.

Der Starter enthält sechs Agenten, einen pro Stack:

laravel-architect — Eloquent-Modelle, Migrationen, API-Resources, Form Requests, Service-Patterns
react-ui — Komponentenarchitektur, State-Management, Barrierefreiheit, Styling
python-api — FastAPI-Endpunkte, Pydantic-Modelle, Async-Patterns
node-backend — Express-Middleware, Fehlerbehandlung, Route-Struktur
devops-reviewer — Dockerfiles, CI/CD-Pipelines, Infrastruktur-Review
sql-investigator — Query-Optimierung, Schema-Review, Datenanalyse

Jeder Agent hat Frontmatter, das seine Fähigkeiten definiert. Hier ist der Laravel-Architect:

---
name: laravel-architect
description: Laravel architecture specialist for Eloquent models, migrations,
  API resources, Form Requests, service patterns, and routing.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
maxTurns: 25
---

Der wesentliche Unterschied zwischen Agenten und Regeln ist der Geltungsbereich. Regeln bieten eine Hintergrundanleitung, die beeinflusst, wie Claude an Code herangeht. Agenten bewältigen mehrstufige, fokussierte Aufgaben, bei denen eine spezialisierte Perspektive gewünscht ist. Man kann sich Regeln als Coding-Standards vorstellen und Agenten als spezialisierte Teammitglieder, die man in ein Gespräch hinzuzieht.

Hooks für leichtgewichtige Automatisierung

Der Starter konfiguriert zwei Hooks in .claude/settings.json, die automatisch an bestimmten Lifecycle-Punkten ausgeführt werden:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/session-start.sh",
            "timeout": 30
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/post-edit-check.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

Der SessionStart-Hook führt session-start.sh bei jedem Start einer neuen Claude-Sitzung aus. Er ruft detect-stack.sh auf, das nach Markierungsdateien sucht und ein JSON-Objekt mit den erkannten Stacks ausgibt:

{
  "stacks": ["laravel", "docker-devops", "sql"],
  "detected_at": "2026-04-01T12:00:00Z"
}

Das gibt Claude sofort Kontext über die Projektstruktur, ohne dass der Entwickler sie manuell erklären muss. Der Hook prüft außerdem, ob eine .env-Datei fehlt, wenn .env.example vorhanden ist.

Der PostToolUse-Hook führt post-edit-check.sh nach jeder Edit- oder Write-Operation aus. Er liest den Pfad der bearbeiteten Datei aus dem Tool-Input, bestimmt den Dateityp und führt eine leichtgewichtige Lint-Prüfung durch: php -l für PHP, ruff check für Python, npx eslint für JavaScript und TypeScript, und eine Erinnerung zur manuellen Überprüfung für SQL-Dateien. Diese Prüfungen laufen automatisch, ohne den Entwickler zu unterbrechen.

Ergebnisse und Vorteile

Die praktischen Verbesserungen durch dieses Setup zeigen sich sofort:

Schlankerer Kontext. Eine Single-Stack-Sitzung lädt 50 bis 80 Zeilen Regeln statt 400 oder mehr. Das lässt mehr Kontext für den Code, an dem Claude tatsächlich arbeitet.
Bessere Genauigkeit. Claude folgt stack-spezifischen Patterns zuverlässiger, wenn sie nicht in irrelevanten Anweisungen vergraben sind. Das Signal steigt, das Rauschen sinkt.
Einfachere Wartung. Jeder Stack-Verantwortliche bearbeitet seine eigene Regeldatei. Der Laravel-Entwickler aktualisiert laravel.md, der Frontend-Entwickler aktualisiert react-next.md, und niemand gerät in Konflikte bei einer gemeinsamen monolithischen Datei.
Schnelleres Onboarding. Neue Teammitglieder fügen ihre Stack-Regeln hinzu, ohne gemeinsame Dateien anzufassen. Die bedingungslosen Regeln repräsentieren teamweite Vereinbarungen, die sich seltener ändern.
Portabel. Das gesamte .claude/-Verzeichnis lässt sich sauber zwischen Projekten kopieren. Das Installationsskript übernimmt den Transfer automatisch.

So können Sie es ausprobieren

Der Starter ist Open Source und sofort einsatzbereit. Es gibt zwei Möglichkeiten, loszulegen:

Option 1: Klonen und installieren. Klonen Sie das Repository und führen Sie das Installationsskript gegen ein bestehendes Projekt aus:

git clone https://github.com/InkByteStudio/claude-code-vscode-multistack-starter.git
cd claude-code-vscode-multistack-starter
./scripts/install-local.sh /path/to/your/project

Das Skript kopiert das .claude/-Verzeichnis und die CLAUDE.md in Ihr Projekt, macht Hook-Skripte ausführbar und führt eine Stack-Erkennung durch, um anzuzeigen, welche Stacks gefunden wurden.

Option 2: Manuelles Kopieren. Kopieren Sie das .claude/-Verzeichnis und die CLAUDE.md in Ihr Projektstammverzeichnis. Entfernen Sie die Stack-Regeln und Agenten, die Sie nicht benötigen.

In beiden Fällen sollten Sie als Erstes nach der Installation anpassen. Löschen Sie Stacks, die Sie nicht verwenden. Passen Sie die bedingungslosen Regeln an die Konventionen Ihres Teams an. Fügen Sie neue Stack-Regeln für Technologien hinzu, die der Starter noch nicht abdeckt. Der Starter ist ein Fundament, kein fertiges Produkt.

Bauen Sie ein besseres Claude-Code-Setup

Die Kernidee ist einfach. Hören Sie auf, jede Regel in eine einzige Datei zu packen. Teilen Sie nach Verantwortlichkeit auf, laden Sie bei Bedarf, und lassen Sie Claude sich auf das konzentrieren, was für die aktuelle Aufgabe zählt. Dieses Prinzip gilt unabhängig davon, ob Sie diesen Starter direkt verwenden oder Ihre eigene modulare Konfiguration von Grund auf erstellen.

Für eine praktische Schritt-für-Schritt-Anleitung zum Aufbau dieses Setups von Grund auf, lesen Sie das begleitende Tutorial: Claude Code Setup in VS Code: Build a Better Multi-Stack CLAUDE.md Starter.

Wenn Sie Claude Code neben anderen KI-Coding-Tools evaluieren, lohnt sich ein Vergleich dieses modularen Ansatzes mit der Konfigurationshandhabung anderer Tools. Die bedingten Regeln von Claude Code über paths-Frontmatter bieten ein Maß an Kontrolle, das Single-File-Konfigurationen in anderen Tools nicht erreichen können. Teams, die bereits in KI-Coding-Agenten und eigene MCP-Server investieren, werden feststellen, dass eine modulare Claude-Code-Konfiguration sich natürlich in denselben Workflow einfügt.

Für Teams, die an Governance und Sicherheit rund um agentische Entwicklung arbeiten, kombinieren Sie dieses Setup mit unserem Leitfaden zur Absicherung von KI-Coding-Agent-Workflows und dem Agentic-AI-Sicherheits-Playbook.

Warum die meisten CLAUDE.md-Dateien zu groß sind: Ein besseres Multi-Stack-Setup für Claude Code