CLAUDE.md Startvorlage für Claude Code in bestehenden Projekten

CLAUDE.md spart die Wiederholung am Anfang jeder Sitzung

In einem bestehenden Repository braucht Claude Code mehr als eine allgemeine Aufgabenbeschreibung. Das Tool muss wissen, welcher Paketmanager gilt, wo die Anwendung liegt, welche Ordner generiert sind, welche Befehle riskant sind und woran eine fertige Änderung gemessen wird. Wenn diese Informationen nur im Chat stehen, beginnt die nächste Sitzung wieder kalt.

CLAUDE.md ist die kleinste sinnvolle Betriebsdatei dafür. Die offizielle Claude Code memory documentation beschreibt sie als persistente Anweisung, die beim Start einer Sitzung geladen wird. Wichtig ist die Grenze: Die Datei ist Kontext, keine harte Durchsetzung. Für echte Sperren brauchst du settings, Permissions, Hooks, CI und Repository-Regeln. Bei Secrets, Deployments und riskanten Befehlen lohnt zusätzlich die security documentation.

Harness bedeutet hier ein Arbeitsgerüst, das den Agenten auf Kurs hält. Du brauchst am Anfang kein langes Regelwerk. Du brauchst eine knappe Datei, die den nächsten wiederholten Fehler verhindert. Weitere Varianten stehen in den CLAUDE.md Templates und im Claude Code Permissions Guide.

Startvorlage zum Kopieren

Die erste Version sollte nur Informationen enthalten, die fast jede Sitzung braucht: Projektüberblick, Befehle, Arbeitsgrenzen, Qualitätsregeln und Definition of done.

# CLAUDE.md

## Project snapshot
- Product: content site and paid template store
- Stack: Astro, TypeScript, MDX, npm
- Main app: site/
- Source articles: site/src/content/blog*/
- Owner voice: practical, evidence-based, no hype

## Commands
- Install dependencies: cd site && npm install
- Start local dev server: cd site && npm run dev
- Build check: cd site && npm run build
- Search fast: rg "keyword" site/src
- Inspect git state: git status --short

## Working rules
- Read existing files before editing.
- Keep changes scoped to the requested slug or feature.
- Do not edit .env, dist, generated reports, or unrelated locale files.
- Preserve pubDate, category, tags, author, lang, and heroImage unless they are broken.
- Ask before destructive git operations, production deploys, or secret rotation.

## Article quality
- Japanese canonical articles should be 4000-6000 characters excluding code.
- Include at least three real use cases.
- Include concrete pitfalls and how to avoid them.
- Include runnable code or config examples, not pseudocode.
- Check official docs when the topic may have changed.

## Definition of done
- The requested files are edited.
- Code fences and JSON/YAML examples are valid.
- Links to internal pages and official docs are present.
- Verification commands have run or skipped checks are explained.
- Remaining risks are stated in the final message.

Speichere die Datei alsCLAUDE.mdim Repository-Root. Wenn schonAGENTS.mdexistiert, dupliziere die Regeln nicht. Lege ein kleinesCLAUDE.mdan, das die gemeinsame Datei importiert, und ergänze nur Claude-Code-spezifische Hinweise. Persönliche Vorlieben gehören inCLAUDE.local.md.

Erzwingbare Grenzen gehören in settings

Ein Satz wie “nicht pushen” inCLAUDE.mdist nützlich, aber er blockiert nichts. Kritische Grenzen müssen in Settings, CI, Branch Protection oder Deployment-Freigaben liegen.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit(site/src/content/blog/**)",
      "Bash(rg:*)",
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(node:*)"
    ],
    "deny": [
      "Bash(git reset:*)",
      "Bash(git checkout --:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)",
      "Edit(reports/**)"
    ]
  }
}

Für persönliche Sicherheit nutzt du.claude/settings.local.json, für Team-Defaults.claude/settings.json. Prüfe vor dem Einsatz die aktuelle offizielle settings page. CLAUDE.md beschreibt Absicht und Kontext; settings setzen die ausführbaren Grenzen.

Drei praktische Use Cases

Use Case	Was in CLAUDE.md steht	Ergebnis
Lokalisierte Artikelpflege	Ziel-Slug, Locale-Liste, zu erhaltende Frontmatter-Felder, Mindestlänge, CTA, Checks	Weniger fehlende Sprachen, englische Reste, kaputte Links und falsche Daten
Kleiner SaaS-Bugfix	editierbare Ordner, Testbefehl, Freigabe vor Datenbankänderung, Logging-Regeln	Weniger Neben-Refactoring und riskante Migrationen
Team-Code-Review	Severity, Datei, Zeile, Auswirkung, Reproduktion, fehlender Test	Review-Kommentare werden umsetzbar

Bei lokalisierten Inhalten reicht es nicht, dass alle Dateien vorhanden sind. Oft bleibt ein englischer Text in einer anderen Sprache stehen. Wenn Verzeichnisse, Linkpfade und Description-Limit klar sind, arbeitet Claude Code von Anfang an gruppiert.

Bei SaaS-Fixes zählt der Scope. Ein kleiner UI-Fehler sollte nicht Auth, Billing oder Migrationen anfassen. Schreibe konkrete Regeln: zuerst lesen, kleinste Fläche ändern, passenden Test ausführen, Datenbankänderungen vorher fragen.

Beim Review entscheidet das Ausgabeformat über den Nutzen. Bitte um Severity, Pfad, Zeile, Nutzerwirkung, Reproduktion und Testlücke. Für automatisierte Läufe hilft die offizielle CLI reference.

Typische Fallstricke

Der erste Fallstrick ist Länge. Eine Datei mit 300 Zeilen wirkt gründlich, verbraucht aber Kontext und wird schlechter beachtet. Halte nur Regeln fest, die regelmäßig gelten. Spezifische Regeln für einzelne Pfade gehören in path-scoped rules oder separate Dokumente.

Der zweite Fallstrick sind Secrets. API Keys, Kundennamen, private Dashboard-URLs und unveröffentlichte Umsatzzahlen gehören nicht inCLAUDE.md. Schreibe nur die Handhabung: Secrets liegen in Environment Variables, werden nicht ausgegeben und sensible Dateien werden nur nach Nachfrage geöffnet.

Der dritte Fallstrick sind veraltete Befehle. Wenn das Projekt von Yarn zu npm, von Jest zu Vitest oder von Next.js zu Astro wechselt, mussCLAUDE.mddirekt mitgeändert werden. Alte Befehle erzeugen selbstsichere, aber falsche Arbeit.

Der vierte Fallstrick ist fehlende Nachweisbarkeit. Eine Anweisung kann Checks verlangen, aber nicht beweisen. Lass am Ende Befehle, Ergebnisse, geänderte Dateien, geprüfte Links und Restrisiken nennen.

Einführung ohne Bürokratie

Starte mit dieser Vorlage und teste sie an drei kleinen Aufgaben: Content-Edit, UI-Textänderung und Review. Danach ergänzt du nur Regeln, die einen echten Fehler verhindert hätten. Harte Grenzen wandern in settings, CI, Branch Protection oder Deployment-Freigabe.

Bei kommerziellen Seiten gehören CTAs zur Qualität. Produktseiten, Kauf-Links, Training-Seiten und Beratungsformulare dürfen bei Text- oder Layoutänderungen nicht verschwinden. Baue diese Prüfung in die Definition of done ein.

Für wiederverwendbare Prompts, Templates und Checklisten nutze ClaudeCodeLab products. Wenn dein Team Permissions, Review Gates, Schulung und ein repository-spezifischesCLAUDE.mdbraucht, ist Claude Code training and consultation der nächste Schritt. Die beste Vorlage ist nicht die längste, sondern diejenige, die den nächsten wiederholten Fehler verhindert.