CLAUDE.md Best Practices: praktische Vorlage für echte Projekte

CLAUDE.md verhindert, dass Architektur, Befehle und Projektregeln in jeder Sitzung neu erklärt werden müssen. Es ist aber keine Sicherheitsrichtlinie und kein Ablageort für jede Dokumentation.

Teamregeln sollten kurz und prüfbar sein; persönliche Hinweise bleiben lokal; harte Einschränkungen gehören in permissions und hooks. Dieser Artikel erklärt, was in CLAUDE.md gehört und was besser außerhalb bleibt, praktisch genug für Einsteiger.

Ziel ist eine kopierbare Vorlage, die ein Team später prüfen kann, ohne daraus ein Handbuchmonster zu machen.

Core idea: CLAUDE.md is guidance, not enforcement

Teamregeln sollten kurz und prüfbar sein; persönliche Hinweise bleiben lokal; harte Einschränkungen gehören in permissions und hooks. Laut offizieller Dokumentation ist CLAUDE.md Kontextführung, Auto memory lokale Lernnotizen, settings konfigurieren den Client und hooks führen Befehle bei Ereignissen aus.

Mechanism	Role	Best for
CLAUDE.md	Human-written persistent guidance	Conventions, architecture, verification commands
Auto memory	Claude’s local learned notes	Debugging insights, preferences, repeated discoveries
settings / permissions	Client configuration and permission rules	Allow, deny, extra directories
hooks	Commands run at lifecycle events	Blocking risky actions, verification, formatting

Where to place CLAUDE.md files

Claude Code liest CLAUDE.md und CLAUDE.local.md vom Arbeitsverzeichnis nach oben. Root-Regeln sind beim Start da; verschachtelte Regeln kommen dazu, wenn passende Dateien gelesen werden.

repo/
  CLAUDE.md                 # shared project guidance
  CLAUDE.local.md           # personal, gitignored
  .claude/
    rules/
      api.md                # path-scoped rule
  packages/admin/CLAUDE.md  # loaded when this subtree is read

What to keep in always-loaded memory

Speichern Sie Build-Befehle, Tests, Architekturgrenzen, Namensregeln, verbotene Muster und Review-Gates. Secrets, lange Logs, Meetings, einmalige Pläne und große Research-Notizen bleiben draußen.

• Keep build, test, lint, type-check, and release verification commands.
• Keep edit boundaries, non-edit boundaries, naming rules, and review gates.
• Do not keep secrets, long meeting notes, historical logs, or one-off task instructions.
• Do not paste entire official docs. Keep the URL and the decision rule.

Copy-paste CLAUDE.md template

Die folgende Vorlage bleibt kurz, damit der Kontext nicht schwer wird. Passen Sie sie an und schreiben Sie prüfbare Regeln.

# Project Instructions

## Project map
- App: Next.js 15 + TypeScript
- API: src/app/api/**
- DB: Prisma schema in prisma/schema.prisma
- Tests: Vitest for units, Playwright for critical browser flows

## Commands
- Install: npm ci
- Type check: npm run typecheck
- Unit tests: npm test
- Lint: npm run lint
- Build: npm run build

## Change rules
- Prefer small edits that follow existing patterns.
- Do not change auth, billing, or migrations without explicit task scope.
- When editing API handlers, update validation and tests in the same pass.
- Before final response, report commands run and any skipped verification.

## Review checklist
- No secrets in code, logs, fixtures, or screenshots.
- Error paths are tested, not only the happy path.
- Public copy and docs use the same terminology as the UI.

Use imports and .claude/rules carefully

@path-Imports organisieren, sparen aber keine Tokens. Importierter Inhalt landet ebenfalls im Kontext. In großen Projekten löschen Sie Altes und verschieben Pfadregeln nach .claude/rules/.

# CLAUDE.md

Read the short project overview in @docs/project-map.md.
Do not import long meeting notes here.

## Compact Instructions
- Preserve current objective, files changed, tests run, and unresolved risks.
- Drop raw command output unless it explains a failure.

---
paths:
  - "src/api/**/*.ts"
---

# API rules
- Validate request bodies with Zod.
- Return typed error responses.
- Add or update tests for every changed handler.

Three practical use cases

1. Besonders wertvoll ist das für Onboarding, Bugfixes und Content-Produktion mit klarer interner Verlinkung. Beim Onboarding zählen Projektkarte und Prüfkommandos mehr als lange Erklärungen.
2. Bei Bugs helfen Reproduktionsbefehl, Log-Ort und kleinster Test.
3. Für Content gehören Ton, interne Links und Quality Gates in CLAUDE.md; lange Notizen in Obsidian oder docs.

Failure cases and pitfalls

1. Typische Fehler sind komplette README-Imports, vage Regeln und Security nur in CLAUDE.md. Behalten Sie nur dauerhaft nötige Regeln.
2. Ersetzen Sie “mach es sauber” durch konkrete Befehle und Dateigrenzen.
3. Harte Sicherheit braucht permissions und PreToolUse hooks; CLAUDE.md allein reicht nicht.

Team maintenance rule

Aktualisieren Sie CLAUDE.md nur bei wiederholtem Fehler, wiederholtem Review-Kommentar oder geänderten Befehlen und Architekturgrenzen.

# quick review before changing CLAUDE.md
rg -n "TODO|deprecated|temporary|secret|password|token" CLAUDE.md .claude/rules
git diff -- CLAUDE.md .claude/rules

Next step and monetization path

Für den Gesamtprozess kombiniere dies mit Obsidian, Token-Optimierung und der Beratungsseite. Der Gesamtworkflow passt zu Obsidian, Token-Optimierung und der Beratungsseite. Related articles: Obsidian workflow, productivity tips, permissions guide, and consultation page.

What was verified

Diese Aktualisierung folgt den offiziellen Seiten memory, context window, settings und commands. Official references: memory, context window, settings, and commands.