Claude Code Setup in VS Code: Einen besseren Multi-Stack CLAUDE.md Starter erstellen

Die meisten Claude Code Setups beginnen mit einer einzelnen CLAUDE.md-Datei, die versucht, alles abzudecken. Das funktioniert gut für kleine Single-Stack-Projekte. Aber wenn man mit mehreren Technologie-Stacks arbeitet, wächst diese Datei zu einem aufgeblähten Instruktionshaufen, der Kontext verschwendet und die Anweisungen verwässert, die Claude tatsächlich für die aktuelle Aufgabe braucht.

In diesem Tutorial erstellst du eine modulare Claude Code Konfiguration für VS Code, die sich an den jeweiligen Stack anpasst. Statt einer riesigen Datei baust du einen leichtgewichtigen CLAUDE.md-Router auf, der durch bedingte Regeln, spezialisierte Subagents, Automatisierungs-Hooks und wiederverwendbare Prompt-Templates unterstützt wird. Am Ende hast du ein portables .claude/-Verzeichnis, das du in jedes Projekt installieren kannst.

Der fertige Starter ist verfügbar unter InkByteStudio/claude-code-vscode-multistack-starter. Du kannst Schritt für Schritt mitarbeiten oder das Repo klonen und als Referenz verwenden.

Was du erstellen wirst

Hier ist die vollständige Struktur, die du erstellen wirst:

.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

Die Architektur folgt einem zweistufigen Muster. Unbedingte Regeln (common, testing, git, security) werden in jeder Session geladen und bieten grundlegende Orientierung. Bedingte Stack-Regeln verwenden paths-Frontmatter, um nur dann geladen zu werden, wenn Claude Dateien liest oder bearbeitet, die bestimmten Glob-Mustern entsprechen. Das bedeutet: Eine Python-Session sieht nur Python-Regeln, eine Laravel-Session nur Laravel-Regeln, und der Kontext bleibt schlank.

Warum modular besser ist als monolithisch

Eine monolithische CLAUDE.md für ein Sechs-Stack-Projekt kann 400 bis 600 Zeilen umfassen. In einer Session, in der du nur Python-Dateien bearbeitest, sind 80 Prozent dieser Anweisungen Rauschen. Bedingtes Laden ändert die Rechnung:

• Monolithisch: circa 400 Zeilen in jeder Session geladen
• Modular (nur Python-Session): circa 80 Zeilen (gemeinsame Regeln plus python-fastapi.md)
• Modular (Laravel plus Docker-Session): circa 120 Zeilen (gemeinsame Regeln plus laravel.md plus docker-devops.md)

Weniger Rauschen bedeutet besseres Signal, und das bedeutet präzisere Antworten. Außerdem pflegt jeder Stack-Verantwortliche seine eigene Datei, statt dass alle um ein gemeinsames Dokument kämpfen.

Schritt 1: Claude Code in VS Code initialisieren

Öffne dein Projekt in VS Code und stelle sicher, dass die Claude Code Extension installiert und authentifiziert ist. Führe den Befehl /init im Claude Code Chat aus, um eine Standard-CLAUDE.md im Projektstammverzeichnis zu erstellen.

Die Standarddatei ist ein einfacher Ausgangspunkt. Du wirst sie im nächsten Schritt komplett ersetzen, aber /init zuerst auszuführen stellt sicher, dass Claude Code das Projekt erkennt und das .claude/-Verzeichnis angelegt wird.

Du solltest nun eine CLAUDE.md-Datei im Projektstammverzeichnis und ein .claude/-Verzeichnis haben.

Schritt 2: Den CLAUDE.md-Router erstellen

Ersetze die Standard-CLAUDE.md durch einen leichtgewichtigen Projektleitfaden, der als Router fungiert. Statt alle Regeln zu enthalten, beschreibt er das Projekt auf hoher Ebene und importiert die unbedingten Regeln über die @-Syntax.

Erstelle CLAUDE.md im Projektstammverzeichnis:

# 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 like architecture
  review, UI work, or SQL investigation.
- **Hooks** in `.claude/settings.json` run lightweight automation on session
  start and after edits.
- **Prompts** in `.claude/prompts/` provide reusable workflow templates for
  common tasks.

## Stack detection

Identify the active stack from the repository structure before making changes.

Common stack indicators:
- Laravel/PHP: `composer.json`, `artisan`, `routes/`, `app/`, `config/`
- React/Next.js: `package.json`, `next.config.*`, `app/`, `pages/`,
  `src/components/`
- Python/FastAPI: `pyproject.toml`, `requirements.txt`, `app/`, `main.py`
- Node/Express: `package.json`, `server.js`, `src/`, `routes/`
- Docker/DevOps: `Dockerfile`, `docker-compose.yml`, `.github/workflows/`
- SQL/Data: migration files, schema dumps, reporting queries, ETL scripts

## Default behavior

- Explain the plan before major edits.
- Prefer the smallest useful diff.
- Reuse existing patterns before adding new abstractions.
- Do not add dependencies unless there is a clear reason.
- Update docs when behavior changes.

## Imported rules (always loaded)

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

## Prompt helpers (available on demand)

@.claude/prompts/bugfix.md
@.claude/prompts/refactor.md
@.claude/prompts/code-review.md
@.claude/prompts/onboarding.md

Du solltest nun eine saubere, gut lesbare CLAUDE.md haben, die die Projektstruktur beschreibt und gemeinsame Regeln importiert, ohne Stack-spezifische Details zu enthalten.

Schritt 3: Unbedingte Regeln hinzufügen

Erstelle vier Regeldateien in .claude/rules/, die in jeder Session geladen werden. Diese decken übergreifende Belange ab, die unabhängig vom verwendeten Stack gelten.

Erstelle .claude/rules/common.md:

# Common Rules

- Match the project's existing naming, folder, and formatting conventions.
- Prefer explicit code over clever code.
- Do not rewrite unrelated files.
- Preserve comments that explain business logic.
- Keep functions and classes cohesive and focused.
- Prefer configuration over hardcoding where the project already supports it.
- When changing behavior, note user-visible impact.
- Use 2-space indentation for JS/TS/JSON, 4-space for Python/PHP unless the
  project uses something else.
- Follow the existing import style and module organization.

Erstelle .claude/rules/testing.md:

# Testing Rules

- Run only the most relevant tests first.
- Prefer one file, one suite, or one command over full-suite runs.
- If adding logic, add or update tests when the project already has test
  coverage in that area.
- If tests are missing, suggest the smallest useful test addition.
- Report what was run, what passed, and what was not verified.
- Use the stack-appropriate test runner:
  - PHP/Laravel: `php artisan test --filter=...` or `./vendor/bin/phpunit`
  - React/Next.js: `npm test -- <name>` or `npx vitest run <name>`
  - Python: `pytest -k ...` or `uv run pytest`
  - Node/Express: `npm test -- <name>` or `npm run test:unit`

Erstelle .claude/rules/git.md:

# Git Rules

- Keep changes scoped to the task.
- Summarize changed files in plain language.
- Use conventional commit style: `type(scope): description`
  - Types: feat, fix, refactor, test, docs, chore, ci, perf
- Call out migrations, config changes, and any manual deployment steps.
- Suggest focused branch names: `type/short-description`
  (e.g., `fix/auth-redirect`, `feat/user-export`).
- Never force-push to main or shared branches without explicit approval.

Erstelle .claude/rules/security.md:

# Security Rules

- Never expose secrets, tokens, or private keys in code or logs.
- Never commit `.env`, credentials, or key files.
- Avoid logging sensitive values (passwords, tokens, PII).
- Validate input boundaries on API and DB changes.
- Sanitize user input before rendering (prevent XSS) or querying
  (prevent SQL injection).
- Flag auth, permission, or data exposure risks clearly.
- For destructive shell or SQL operations, explain scope before execution.
- Run `npm audit`, `pip audit`, or `composer audit` when adding dependencies.

Diese vier Dateien haben kein paths-Frontmatter, was bedeutet, dass Claude sie in jeder Session unbedingt lädt.

Du solltest nun vier Regeldateien in .claude/rules/ haben, die Coding-Standards, Test-Philosophie, Git-Konventionen und Sicherheitsleitlinien abdecken.

Schritt 4: Bedingte Stack-Regeln hinzufügen

Bedingte Regeln sind der Punkt, an dem sich der modulare Ansatz auszahlt. Jede Stack-Regeldatei enthält einen paths-Block im YAML-Frontmatter, der Claude anweist, sie nur beim Lesen oder Bearbeiten von Dateien zu laden, die diesen Glob-Mustern entsprechen.

Hier ist die vollständige Laravel-Regeldatei als Hauptbeispiel. Erstelle .claude/rules/laravel.md:

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

# Laravel / PHP Guidance

## Architecture
- Prefer existing Laravel conventions before custom patterns.
- Keep controllers thin.
- Put reusable business logic in services, actions, or domain classes
  if that pattern already exists.
- Use Form Requests for request validation when appropriate.
- Prefer Eloquent scopes, relationships, and query builders over
  duplicated query logic.

## Database
- Treat migrations as review-sensitive changes.
- Prefer additive schema changes unless a breaking change is intentional.
- For large updates, think about indexing, chunking, locking, and
  rollback impact.

## Commands
- `php artisan test --filter=...`
- `php artisan route:list`
- `php artisan migrate --pretend`
- `composer test`
- `./vendor/bin/phpunit`

## Review checklist
- Validation correct?
- Auth/authorization preserved?
- N+1 or query performance issues?
- Migration safety reviewed?
- API response shape consistent?

Erstelle nun die verbleibenden fünf Stack-Regeldateien. Jede folgt demselben Muster: paths-Frontmatter am Anfang, dann Stack-spezifische Anleitungen.

Erstelle .claude/rules/react-next.md mit diesen Pfaden:

---
paths:
  - "**/*.tsx"
  - "**/*.jsx"
  - "**/components/**"
  - "**/pages/**"
  - "**/next.config.*"
---

Füge Anleitungen zu Komponentendesign, State-Management, Next.js Server/Client-Grenzen, Styling-Konventionen und eine Review-Checkliste zu Barrierefreiheit, Ladezuständen und Type-Korrektheit hinzu.

Erstelle .claude/rules/python-fastapi.md mit diesen Pfaden:

---
paths:
  - "**/*.py"
  - "**/requirements*.txt"
  - "**/pyproject.toml"
---

Füge Anleitungen zu API-Design, Validierung, async-Mustern und eine Review-Checkliste zu Type Hints, Schema-Abgleich und Fehlerbehandlung hinzu.

Erstelle .claude/rules/node-express.md mit diesen Pfaden:

---
paths:
  - "**/server/**"
  - "**/routes/**/*.js"
  - "**/routes/**/*.ts"
  - "**/middleware/**"
  - "**/server.js"
  - "**/app.js"
---

Füge Anleitungen zu Routen-Struktur, Middleware, Fehlerbehandlung und eine Review-Checkliste zu Validierung, Authentifizierung und Logging-Sicherheit hinzu.

Erstelle .claude/rules/docker-devops.md mit diesen Pfaden:

---
paths:
  - "**/Dockerfile*"
  - "**/docker-compose*.yml"
  - "**/compose*.yml"
  - "**/.github/workflows/**"
  - "**/nginx/**"
---

Füge Anleitungen zu Container-Änderungen, CI/CD-Pipelines, Sicherheit bei produktionsrelevanten Änderungen und eine Review-Checkliste zu Build-Reproduzierbarkeit, Secrets-Handling und Rollback-Pfaden hinzu.

Erstelle .claude/rules/sql.md mit diesen Pfaden:

---
paths:
  - "**/*.sql"
  - "**/migrations/**"
  - "**/seeds/**"
  - "**/seeders/**"
---

Füge Anleitungen zu Query-Design, Sicherheit bei UPDATE- und DELETE-Anweisungen, Performance-Überlegungen und eine Review-Checkliste zu NULL-Handling, Join-Duplikation und Rollback-Strategie hinzu.

Du solltest nun sechs bedingte Regeldateien in .claude/rules/ haben, jede mit paths-Frontmatter, das einschränkt, wann sie geladen wird.

Schritt 5: Subagents erstellen

Subagents sind spezialisierte Agenten, die in .claude/agents/ mit eigenen System-Prompts, Tool-Zugriff und Modellauswahl definiert werden. Sie sind nützlich für mehrstufige Aufgaben, bei denen eine fokussierte Perspektive hilft.

Erstelle .claude/agents/laravel-architect.md:

---
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
---

You are a Laravel-focused engineering subagent.

## Priorities
- Follow Laravel conventions already present in the repo.
- Keep controllers thin. Push logic into services, actions, or domain classes.
- Recommend safe migration patterns. Prefer additive schema changes.
- Call out validation, auth, and query performance risks.
- Prefer focused diffs and small follow-up steps.

## When reviewing code
- Check for N+1 queries and suggest eager loading where needed.
- Verify Form Request validation covers edge cases.
- Confirm authorization checks are in place.
- Look for missing indexes on frequently queried columns.

## When writing code
- Use Eloquent relationships and scopes over raw queries.
- Follow existing factory and seeder patterns for test data.
- Keep route definitions clean and grouped logically.
- Use Laravel's built-in helpers before adding custom utilities.

Erstelle die verbleibenden fünf Agenten in .claude/agents/ nach demselben Muster:

• react-ui.md — React- und Next.js-UI-Spezialist. Fokus auf Komponentenstruktur, State-Flow, Barrierefreiheit und Styling. Setze model: sonnet, maxTurns: 20.
• python-api.md — Python- und FastAPI-Spezialist. Fokus auf Endpoint-Design, Pydantic-Modelle, async-Muster und Typsicherheit. Setze model: sonnet, maxTurns: 25.
• node-backend.md — Node.js- und Express-Spezialist. Fokus auf Middleware, Fehlerbehandlung, Routen-Organisation und async-Muster. Setze model: sonnet, maxTurns: 25.
• devops-reviewer.md — Docker- und DevOps-Spezialist. Fokus auf Dockerfiles, CI/CD-Pipelines, Infrastruktur-Review und Sicherheit. Setze model: sonnet, maxTurns: 20.
• sql-investigator.md — SQL- und Datenbank-Spezialist. Fokus auf Query-Optimierung, Schema-Review, Migrationssicherheit und Datenanalyse. Setze model: sonnet, maxTurns: 20.

Jeder Agent enthält ein description-Feld, das Claude mitteilt, wann er die Delegation an diesen Agenten vorschlagen soll. Das tools-Feld steuert, welche Tools der Agent verwenden darf. Das maxTurns-Feld begrenzt, wie viele Schritte der Agent ausführen kann, bevor er die Kontrolle zurückgibt.

Du solltest nun sechs Agent-Dateien in .claude/agents/ haben, eine pro Stack.

Schritt 6: Hooks konfigurieren

Hooks sind leichtgewichtige Shell-Skripte, die automatisch bei bestimmten Claude Code Lifecycle-Events ausgeführt werden. Erstelle die Hooks-Konfiguration und die Skripte.

Erstelle .claude/settings.json:

{
  "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
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [],
    "deny": []
  }
}

Die Variable $CLAUDE_PROJECT_DIR wird zum Projektstammverzeichnis aufgelöst, sodass Pfade unabhängig vom aktuellen Arbeitsverzeichnis funktionieren.

Erstelle .claude/hooks/session-start.sh:

#!/usr/bin/env bash
# Runs on SessionStart via .claude/settings.json
# Detects active stacks and checks environment readiness.

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
DETECT_SCRIPT="$SCRIPT_DIR/../../scripts/detect-stack.sh"

if [ -x "$DETECT_SCRIPT" ] || [ -f "$DETECT_SCRIPT" ]; then
  stacks_json=$(bash "$DETECT_SCRIPT" 2>/dev/null || echo '{"stacks": []}')
  stacks_list=$(echo "$stacks_json" | grep -o '"[^"]*"' \
    | grep -v stacks | grep -v detected_at | tr -d '"' \
    | paste -sd', ' -)
  if [ -n "$stacks_list" ]; then
    echo "Detected stacks: $stacks_list"
  else
    echo "No specific stack detected. Check project files manually."
  fi
else
  echo "No specific stack detected. Check project files manually."
fi

# Check for missing .env
if [ -f .env.example ] && [ ! -f .env ]; then
  echo "Warning: .env.example exists but .env is missing. Copy and configure it."
fi

exit 0

Erstelle .claude/hooks/post-edit-check.sh:

#!/usr/bin/env bash
# Runs after Edit/Write tool use via .claude/settings.json
# Performs lightweight lint checks based on the edited file type.

INPUT=$(cat)
if command -v jq &>/dev/null; then
  FILE=$(echo "$INPUT" | jq -r '.file_path // empty' 2>/dev/null)
else
  FILE=$(echo "$INPUT" | grep -o '"file_path"[[:space:]]*:[[:space:]]*"[^"]*"' \
    | head -1 | sed 's/.*"file_path"[[:space:]]*:[[:space:]]*"//;s/"$//')
fi

if [ -z "$FILE" ]; then
  exit 0
fi

EXT="${FILE##*.}"

case "$EXT" in
  php)
    if command -v php &>/dev/null; then
      php -l "$FILE" 2>&1 || true
    fi
    ;;
  py)
    if command -v ruff &>/dev/null; then
      ruff check "$FILE" 2>&1 || true
    elif command -v python3 &>/dev/null; then
      python3 -m py_compile "$FILE" 2>&1 || true
    fi
    ;;
  ts|tsx|js|jsx)
    if command -v npx &>/dev/null; then
      npx eslint "$FILE" --no-error-on-unmatched-pattern 2>&1 || true
    fi
    ;;
  sql)
    echo "SQL file edited: $FILE -- review before executing."
    ;;
esac

exit 0

Mache beide Hook-Skripte ausführbar:

chmod +x .claude/hooks/session-start.sh .claude/hooks/post-edit-check.sh

Du solltest nun zwei Hook-Skripte und eine settings.json haben, die sie mit den SessionStart- und PostToolUse-Lifecycle-Events verknüpft.

Schritt 7: Das Stack-Erkennungsskript erstellen

Das Stack-Erkennungsskript durchsucht das Projektstammverzeichnis nach Markierungsdateien und gibt ein JSON-Objekt mit den erkannten Stacks aus. Der Session-Start-Hook ruft dieses Skript auf, um Claude sofortigen Projektkontext zu geben.

Erstelle scripts/detect-stack.sh:

#!/usr/bin/env bash
# Standalone stack detection script.
# Outputs detected stacks as JSON for use by other tools.

stacks=()

{ [ -f artisan ] || [ -f composer.json ]; } && stacks+=("laravel")
{ [ -f next.config.js ] || [ -f next.config.mjs ] || [ -f next.config.ts ]; } \
  && stacks+=("react-next")
[ -f package.json ] && grep -q '"react"' package.json 2>/dev/null \
  && stacks+=("react")
{ [ -f pyproject.toml ] || [ -f requirements.txt ]; } \
  && stacks+=("python-fastapi")
[ -f package.json ] && { [ -f server.js ] || [ -f app.js ]; } \
  && stacks+=("node-express")
{ [ -f Dockerfile ] || [ -f docker-compose.yml ] || [ -f compose.yml ]; } \
  && stacks+=("docker-devops")

# Check for SQL-heavy projects
sql_count=$(find . -maxdepth 3 -name "*.sql" 2>/dev/null | head -5 | wc -l)
[ "$sql_count" -gt 0 ] && stacks+=("sql")

# Output as JSON
json="["
for i in "${!stacks[@]}"; do
  [ "$i" -gt 0 ] && json+=","
  json+="\"${stacks[$i]}\""
done
json+="]"

echo "{\"stacks\": $json, \"detected_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}"

Mache es ausführbar:

chmod +x scripts/detect-stack.sh

So ordnet das Skript Markierungsdateien den Stack-Bezeichnern zu:

Stack-ID	Markierungsdateien	Erkennungslogik
laravel	artisan, composer.json	Eine der Dateien existiert
react-next	next.config.js, .mjs, .ts	Eine Konfigurationsdatei existiert
react	package.json mit "react"	React in den Abhängigkeiten
python-fastapi	pyproject.toml, requirements.txt	Eine der Dateien existiert
node-express	package.json + server.js/app.js	Package-Datei plus Einstiegspunkt
docker-devops	Dockerfile, docker-compose.yml, compose.yml	Eine Konfiguration existiert
sql	*.sql-Dateien innerhalb von 3 Ebenen	Mindestens eine SQL-Datei gefunden

Die Ausführung des Skripts erzeugt eine Ausgabe wie diese:

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

Du solltest nun ein funktionierendes Stack-Erkennungsskript haben, das sauberes JSON ausgibt.

Schritt 8: Prompt-Templates hinzufügen

Prompt-Templates sind wiederverwendbare Workflows, die in .claude/prompts/ gespeichert werden. Sie stehen bei Bedarf zur Verfügung, wenn du einen strukturierten Ansatz für eine häufige Aufgabe brauchst.

Erstelle .claude/prompts/bugfix.md:

# Bugfix Workflow

Use this prompt when diagnosing and fixing a bug.

## Steps

1. **Describe the bug**: What is the expected behavior vs. actual behavior?
2. **Reproduce**: Find or write a minimal reproduction. If tests exist,
   write a failing test first.
3. **Diagnose**: Trace the code path. Check logs, error messages, and recent
   changes. Narrow down to the root cause before proposing a fix.
4. **Fix**: Apply the smallest change that addresses the root cause.
   Do not refactor unrelated code.
5. **Verify**: Run the failing test (or the narrowest relevant test suite)
   to confirm the fix. Run lint and typecheck.
6. **Document**: Note what caused the bug, what the fix does, and any
   follow-up work needed.

## Checklist before committing
- [ ] Root cause identified (not just symptoms addressed)
- [ ] Fix is scoped to the bug (no unrelated changes)
- [ ] Test covers the failure case
- [ ] Existing tests still pass
- [ ] No regressions introduced

Erstelle drei weitere Prompt-Templates in .claude/prompts/:

• refactor.md — Ein strukturierter Refactoring-Workflow: Ziel identifizieren, Auswirkungen eingrenzen, inkrementelle Schritte planen, einen Schritt nach dem anderen ausführen, bei jedem Schritt Tests ausführen und die Motivation in der Commit-Nachricht dokumentieren.
• code-review.md — Eine Code-Review-Checkliste zu Sicherheit (Secrets, Injection, Authentifizierung), Korrektheit (Grenzfälle, Fehlerpfade), Performance (N+1, async, Paginierung), Lesbarkeit (Benennung, fokussierte Diffs) und Tests (Abdeckung, aussagekräftige Assertions). Bewerte Befunde als Kritisch, Warnung oder Vorschlag.
• onboarding.md — Ein Projekt-Onboarding-Workflow: Verzeichnisstruktur erkunden, Stack identifizieren, Einstiegspunkte finden, Build- und Run-Befehle dokumentieren, Architektur abbilden, nach Konventionen suchen und ein Zusammenfassungsdokument erstellen.

Du kannst jedes Prompt-Template während einer Claude Code Session mit /prompt-name oder durch Referenzierung mit @.claude/prompts/name.md aufrufen.

Du solltest nun vier Prompt-Templates haben, die die gängigsten Entwicklungsworkflows abdecken.

Schritt 9: Das Installationsskript erstellen

Das Installationsskript kopiert die gesamte Konfiguration in ein bestehendes Projekt. Das macht den Starter portabel über alle deine Repos hinweg.

Erstelle scripts/install-local.sh:

#!/usr/bin/env bash
# Install this Claude Code starter config into an existing project.
# Usage: ./scripts/install-local.sh [target-directory]

set -e

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
REPO_DIR="$(dirname "$SCRIPT_DIR")"
TARGET="${1:-.}"

# Resolve to absolute path
TARGET="$(cd "$TARGET" && pwd)"

echo "Claude Code Multi-Stack Starter Installer"
echo "==========================================="
echo ""
echo "Source: $REPO_DIR"
echo "Target: $TARGET"
echo ""

# Check if .claude/ already exists
if [ -d "$TARGET/.claude" ]; then
  echo "Warning: $TARGET/.claude/ already exists."
  read -rp "Overwrite existing config? (y/N): " confirm
  if [[ ! "$confirm" =~ ^[Yy]$ ]]; then
    echo "Aborted."
    exit 0
  fi
fi

# Copy .claude/ directory
echo "Copying .claude/ config..."
mkdir -p "$TARGET/.claude"
cp "$REPO_DIR/.claude/settings.json" "$TARGET/.claude/settings.json"
cp -r "$REPO_DIR/.claude/rules" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/agents" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/hooks" "$TARGET/.claude/"
cp -r "$REPO_DIR/.claude/prompts" "$TARGET/.claude/"

# Copy CLAUDE.md if it doesn't exist
if [ -f "$TARGET/CLAUDE.md" ]; then
  echo "CLAUDE.md already exists in target. Skipping (review manually)."
else
  cp "$REPO_DIR/CLAUDE.md" "$TARGET/CLAUDE.md"
  echo "Copied CLAUDE.md"
fi

# Make hook scripts executable
chmod +x "$TARGET/.claude/hooks/"*.sh 2>/dev/null || true

# Detect stacks
echo ""
echo "Detecting stacks in target project..."
cd "$TARGET"
stacks_output=$("$REPO_DIR/scripts/detect-stack.sh" 2>/dev/null \
  || echo '{"stacks": []}')
echo "$stacks_output"

# Summary
echo ""
echo "Installation complete."
echo ""
echo "Next steps:"
echo "  1. Review CLAUDE.md and adjust for your project"
echo "  2. Remove stack rules you don't need from .claude/rules/"
echo "  3. Remove agents you don't need from .claude/agents/"
echo "  4. Customize .claude/settings.json hooks"
echo "  5. Open the project in VS Code and start Claude Code"

Mache es ausführbar:

chmod +x scripts/install-local.sh

Um den Starter in ein bestehendes Projekt zu installieren:

./scripts/install-local.sh /path/to/your/project

Das Skript kopiert das .claude/-Verzeichnis, bewahrt eine bestehende CLAUDE.md, macht Hooks ausführbar und führt die Stack-Erkennung im Zielprojekt aus.

Du solltest nun ein funktionierendes Installationsskript haben, das die Konfiguration in jedes Projekt deployen kann.

Schritt 10: Das Setup testen

Wähle ein bestehendes Projekt, das mindestens einen der unterstützten Stacks verwendet. Installiere die Konfiguration mit dem Installationsskript oder durch manuelles Kopieren der Dateien. Prüfe dann, ob jede Komponente funktioniert.

Prüfe, ob unbedingte Regeln geladen werden. Starte eine neue Claude Code Session und frage Claude, welche aktiven Regeln es hat. Die vier unbedingten Regeln (common, testing, git, security) sollten vorhanden sein.

Prüfe, ob bedingte Regeln ausgelöst werden. Bitte Claude, eine Datei zu lesen oder zu bearbeiten, die einem der Stack-Muster entspricht. Öffne zum Beispiel eine .php-Datei in einem Laravel-Projekt. Die Laravel-Regeln sollten aktiviert werden. Öffne eine .tsx-Datei und die React-Regeln sollten stattdessen aktiviert werden.

Prüfe, ob Subagents verfügbar sind. Bitte Claude, die verfügbaren Agenten aufzulisten, oder versuche, eine Aufgabe an einen bestimmten Agenten wie laravel-architect zu delegieren.

Prüfe, ob der Session-Start-Hook läuft. Starte eine neue Session und prüfe, ob Claude erkannte Stacks meldet. Du solltest eine Ausgabe wie “Detected stacks: laravel, docker-devops” sehen.

Prüfe, ob der Post-Edit-Hook feuert. Bitte Claude, eine Datei zu bearbeiten, und prüfe, ob der Lint-Check automatisch nach der Bearbeitung läuft.

Wenn alles funktioniert, ist die Konfiguration für den täglichen Einsatz bereit.

Anpassung

Der Starter ist ein Fundament, kein fertiges Produkt. So passt du ihn an:

Nicht benötigte Stacks entfernen. Lösche Regel- und Agent-Dateien für Stacks, die du nicht verwendest. Ein reines Python-Team kann laravel.md, react-next.md, node-express.md und die zugehörigen Agenten entfernen.

Unbedingte Regeln anpassen. Passe common.md, testing.md, git.md und security.md an die Konventionen deines Teams an. Diese werden in jeder Session geladen, also halte sie schlank und relevant.

Neue Stacks hinzufügen. Kopiere eine bestehende bedingte Regeldatei, aktualisiere das paths-Frontmatter für die Dateimuster deines neuen Stacks und aktualisiere die Anleitungen. Um beispielsweise Rust-Unterstützung hinzuzufügen:

---
paths:
  - "**/*.rs"
  - "**/Cargo.toml"
---

Füge dann einen passenden Erkennungsblock in detect-stack.sh hinzu:

[ -f Cargo.toml ] && stacks+=("rust")

Und erstelle optional einen rust-systems.md-Agenten in .claude/agents/.

Hook-Timeouts anpassen. Wenn deine Lint-Tools langsam sind, erhöhe die Timeout-Werte in settings.json. Der Session-Start-Hook hat standardmäßig 30 Sekunden und der Post-Edit-Hook 60 Sekunden.

Häufige Setup-Probleme

Stack-Regeln werden in jeder Session geladen

Symptome: Claude referenziert Laravel-Regeln, wenn du Python-Dateien bearbeitest, oder alle Stack-Regeln erscheinen aktiv, unabhängig davon, woran du arbeitest.

Wahrscheinliche Ursache: Das paths-Frontmatter fehlt in der Stack-Regeldatei, oder die YAML-Syntax ist ungültig.

Lösung: Öffne die Regeldatei und prüfe, ob sie mit einem gültigen paths-Block zwischen ----Trennzeichen beginnt. Prüfe auf YAML-Syntaxfehler wie fehlende Anführungszeichen, falsche Einrückung oder ein fehlendes schließendes ---.

Hooks werden nicht ausgeführt

Symptome: Keine Stack-Erkennungsausgabe beim Session-Start. Kein Lint-Check nach Bearbeitungen.

Wahrscheinliche Ursache: Die Hook-Skripte sind nicht ausführbar, der Pfad in settings.json ist falsch, oder die Variable $CLAUDE_PROJECT_DIR wird nicht korrekt aufgelöst.

Lösung: Führe chmod +x .claude/hooks/*.sh aus. Prüfe, ob settings.json das korrekte Pfadformat mit $CLAUDE_PROJECT_DIR verwendet. Stelle sicher, dass das scripts-Verzeichnis existiert und detect-stack.sh enthält.

Stack nicht erkannt

Symptome: Der Session-Start-Hook meldet “No specific stack detected”, obwohl das Projekt eindeutig einen unterstützten Stack verwendet.

Wahrscheinliche Ursache: Die Markierungsdateien befinden sich nicht im Projektstammverzeichnis. In einem Monorepo könnte die Laravel-Datei artisan in backend/ statt im Root liegen.

Lösung: Verschiebe die Markierungsdateien ins Root, erstelle Symlinks, oder passe detect-stack.sh an, um gängige Monorepo-Layouts wie packages/, apps/ oder services/ zu prüfen.

Post-Edit-Hook meldet Fehler

Symptome: Lint-Fehler erscheinen nach jeder Bearbeitung, auch für nicht zusammenhängende Probleme.

Wahrscheinliche Ursache: Das Lint-Tool meldet bereits bestehende Probleme in der Datei, nicht durch die Bearbeitung verursachte Probleme.

Lösung: Behebe die bestehenden Lint-Probleme oder passe den Post-Edit-Hook an, um nur Fehler in den geänderten Zeilen zu melden. Als schnelle Umgehung kannst du auch bestimmte Linter-Checks in post-edit-check.sh auskommentieren.

CLAUDE.md ist zu detailliert

Symptome: Die CLAUDE.md-Datei wächst wieder an und verfehlt den Zweck des modularen Setups.

Wahrscheinliche Ursache: Stack-spezifische oder detaillierte Anleitungen werden zur CLAUDE.md hinzugefügt, statt in die entsprechende Regeldatei.

Lösung: Verschiebe detaillierte Anleitungen in die relevante .claude/rules/-Datei. CLAUDE.md sollte ein leichtgewichtiger Router bleiben: Projektübersicht, Stack-Hinweise, Standardverhalten und @-Imports. Alles andere gehört in eine Regeldatei.

Zusammenfassung

Du hast nun eine modulare Claude Code Konfiguration, die sich an den jeweiligen Stack anpasst. Unbedingte Regeln bieten konsistente grundlegende Orientierung. Bedingte Regeln laden nur, wenn sie relevant sind. Subagents bieten fokussierte Expertise. Hooks automatisieren Routineprüfungen. Und das Installationsskript macht das gesamte Setup portabel über Projekte hinweg.

Das Schlüssel-Prinzip ist einfach: Lade nur, was für die aktuelle Aufgabe wichtig ist. Das gibt Claude mehr Kontext für den Code, an dem es tatsächlich arbeitet, und gibt deinem Team eine wartbare Konfiguration, die mit dem Projekt skaliert.

Der vollständige Starter ist verfügbar unter InkByteStudio/claude-code-vscode-multistack-starter. Klone ihn, passe ihn an und entferne, was du nicht brauchst.

Für einen übergeordneten Blick darauf, warum dieser modulare Ansatz wichtig ist, lies den begleitenden Blog-Post: Why Most CLAUDE.md Files Are Too Big. Um zu verstehen, wie Claude Code in die breitere Landschaft der AI Coding Agents passt, lies AI Coding Agents in 2026: How MCP Is Changing Software Development und Building Custom MCP Servers. Für Teams, die über Sicherheit und Governance bei agentischer Entwicklung nachdenken, kombiniere dies mit Securing AI Coding Agent Workflows und the Agentic AI Security Playbook.