CLAUDE.md: 7 kopierbare Vorlagen und wie du gute Verbotsregeln schreibst

„In die CLAUDE.md schreibe ich einfach meinen Tech-Stack, dann passt das schon, oder?”

Genau das dachte ich am Anfang auch. Astro, TypeScript, Tailwind – fertig, aufgeschrieben. Zufrieden habe ich Claude Code an die Arbeit gelassen, und dann passierte derselbe Fehler dreimal hintereinander. Tests wurden jedes Mal übersprungen. Es wurde nach Konfigurationsdateien gegriffen, die niemand anfassen sollte. Und mit einem fröhlichen „Erledigt!” wurde Code abgeliefert, bei dem der Build gar nicht durchlief.

Eine CLAUDE.md, die nur den Stack auflistet, ist wie ein neuer Kollege, dem du an Tag eins nur sagst „Wir sind ein Java-Laden” und ihn dann allein lässt. Er weiß jetzt, was benutzt wird – aber kein Stück, wie er sich verhalten soll.

In diesem Artikel lege ich dir sieben CLAUDE.md-Vorlagen hin, die ich genau so in echten Projekten verwende, alle zum Kopieren. Keine Stack-Beschreibungen, sondern voll auf „die Reihenfolge” und „was man nicht tun darf” zugeschnitten.

Das Wichtigste in Kürze

• Was in der CLAUDE.md wirklich wirkt, ist nicht der Tech-Stack, sondern zwei Dinge: die Arbeitsabläufe (Working Rules) und die Verbote (Do Not).
• Es gibt sieben Vorlagen nach Einsatzzweck: Solo-Entwicklung, Content-Site, API, Team, Legacy, Automatisierung und Monorepo. Wähl die eine, die deinem Repo am nächsten kommt, und füg sie ein.
• Bei jeder Vorlage ist es Pflicht, nach dem Einfügen drei eigene Do Not-Zeilen zu ergänzen. Genau das stoppt die Unfälle.
• „Je länger, desto besser” ist ein Irrglaube. Die CLAUDE.md ist kein Handbuch, sondern eine Betriebsdatei. Kurze Verhaltensregeln gewinnen.
• Wenn Claude Code denselben Fehler dreimal wiederholt, liegt es nicht an der KI, sondern an der Körnung deiner CLAUDE.md.

Diese Seite ist als „Katalog mit echten Mustern” gedacht und füllt die Lücke zwischen dem kompletten Einsteigerleitfaden für Claude Code und dem vollständigen Leitfaden zum Schreiben einer CLAUDE.md. Die Theorie liest du dort, hier nimmst du die fertigen Stücke mit.

Was eine gute CLAUDE.md unauffällig erledigt

Eine starke CLAUDE.md schreibt nichts Geniales. Sie räumt nur unauffällig drei „Klassiker-Unfälle” aus dem Weg:

• Die Bearbeitungsstelle stimmt, aber die projektspezifischen Konventionen werden ignoriert.
• Die Korrektur selbst klappt, aber die nötigen Tests oder Checks werden übersprungen.
• Es ist unklar, wo der eigene Zuständigkeitsbereich endet, also wuchert die Erkundung und frisst Zeit.

Um diese drei zu verhindern, brauchst du mindestens diese Punkte:

Punkt	Funktion	Wirkung
Tech-Stack und Hauptbefehle	Voraussetzungen angleichen	mittel
Rolle der Verzeichnisse	Suchbereich eingrenzen	mittel
Projektspezifische Regeln	Konventionen erzwingen	hoch
Arbeitsablauf (Reihenfolge)	Lücken bei Checks verhindern	hoch
Verbote (Do Not)	Unfälle stoppen	sehr hoch

Die oberen beiden sind Beiwerk, die unteren drei sind das, was zählt. Vor allem: In dem Moment, in dem du Arbeitsablauf und Verbote aufschreibst, wird Claude Code plötzlich ganz ruhig. „Wie gehe ich vor” und „was tu ich nicht” – am Ende ist das genau dasselbe wie das Handbuch, das du einem neuen Kollegen in die Hand drückst.

Ab hier kommen die echten Muster. Kopier den Inhalt der Codeblöcke direkt in deine eigene CLAUDE.md.

1. Für Solo-Web-Apps

Wenn du allein einen kleinen Dienst betreibst, fang hiermit an.

# Project Overview

Customer-facing Astro site with a small Node API.

## Tech Stack

- Frontend: Astro 5 + TypeScript
- Styling: Tailwind CSS
- Backend: Node.js 22
- Tests: Vitest

## Key Directories

- `site/src/pages/` route entrypoints
- `site/src/components/` reusable UI
- `site/src/content/` blog and docs content
- `scripts/` operational scripts

## Common Commands

- Build: `cd site && npm run build`
- Test: `npm run test`
- Search content: `rg "keyword" site/src/content`

## Working Rules

- Prefer minimal diffs over wide refactors
- Keep copy changes aligned with existing brand tone
- When editing UI, verify mobile width before calling the task done

## Do Not

- Do not rename routes unless required
- Do not delete analytics or SEO fields
- Do not claim deploy success without checking the public URL

Was hier am meisten bringt, ist nicht die Stack-Beschreibung, sondern die letzten Zeilen von Working Rules und Do Not. „Sag nicht ‚fertig’, bevor du die Mobile-Breite geprüft hast” und „Sag nicht ‚Deploy erfolgreich’, bevor du die öffentliche URL gesehen hast”. Bevor ich diese zwei Zeilen drin hatte, ist mir mehrfach passiert, dass eine UI auf dem Desktop sauber aussah und auf dem Smartphone komplett aus dem Rahmen lief. Sobald du die Erfolgsbedingung in Worte fasst und festnagelst, verschwindet das.

2. Für Content-Sites mit Artikeln, PDFs und Produktstrecke

Dieser Blog selbst ist so ein Fall: Sobald eine Site eine Monetarisierungsstrecke hat, sind allgemeine Entwicklungsvorlagen viel zu schwach.

# Project Overview

Multilingual Claude Code content site with free PDF lead magnet, Gumroad products, and consultation funnel.

## Business Goal

- Priority 1: free PDF registration
- Priority 2: Gumroad product clicks and purchases
- Priority 3: consultation inquiries

## Content Rules

- Every new article must include internal links
- Every article must include free PDF, product, and consultation CTA paths
- Use the same slug across all locales when publishing multilingual posts

## Verification Workflow

1. Build the site
2. Deploy the site
3. Open the public URL
4. Check mobile layout
5. Confirm CTA destination links

## Do Not

- Do not publish only one locale when the article requires all locales
- Do not treat build success as release success
- Do not prioritize pageviews over conversion path quality

Der entscheidende Punkt steht in der letzten Zeile von Do Not: „Priorisiere die Qualität der Conversion-Strecke über Pageviews”. Schreibst du das nicht hin, driftet Claude Code in Richtung „Artikel, die viel gelesen werden” und produziert am laufenden Band Seiten mit blassen, halbherzigen CTAs. Allein dadurch, dass ich das Business-Ziel mit klarer Priorität nach ganz oben gesetzt habe, hat sich die Ausgaberichtung komplett gedreht.

3. Für Backend-APIs

Bei APIs, wo Konsistenz alles ist, erzwingst du „erst lesen, dann ändern” und „nach der Änderung in Worte fassen”.

# Project Overview

Internal TypeScript API for billing and account management.

## Tech Stack

- Node.js 22
- Fastify
- PostgreSQL + Prisma
- Zod
- Vitest

## Directory Map

- `src/routes/` HTTP handlers
- `src/services/` business logic
- `src/repositories/` DB access
- `src/lib/` shared utilities

## Required Workflow

1. Read the route or service first
2. Check for existing schema and tests
3. Make the smallest safe change
4. Run unit tests or type checks
5. Summarize risk in plain English

## Do Not

- Do not bypass Zod validation
- Do not edit migrations casually
- Do not touch billing logic without tests

Mein Lieblingsstück hier ist die eine Zeile Summarize risk in plain English – „Fass das Risiko in normalen Worten zusammen”. Mit der hört Claude Code nicht bei „Erledigt” auf, sondern formuliert von sich aus den Wirkungsbereich, etwa: „Diese Änderung liegt nah an der Grenze der Billing-Logik, sie könnte also den monatlichen Batch-Lauf beeinflussen.” Der erste Schritt im Review wird dadurch schlagartig leichter.

4. Für die Team-Entwicklung

Was im Team wirklich wehtut, ist weniger fehlende Produktivität als schwer zu reviewende Diffs. Dem kommst du zuvor.

# Team Workflow

- Work on the current branch only
- Do not revert changes you did not make
- Call out uncertainty before making broad edits
- Prefer review-friendly patches over large rewrites

## Pull Request Expectations

- Mention user-facing behavior changes
- Mention test coverage gaps
- Flag security, permissions, and deploy risks first

## Approval Boundaries

- Ask before deploy commands
- Ask before editing CI, infra, or secrets-related files
- Ask before changing lockfiles unless required

Do not revert changes you did not make – „Nimm keine Änderungen zurück, die du nicht selbst gemacht hast” – wirkt unscheinbar, bringt aber viel. KIs versuchen gern, „nebenbei” benachbarten Code „aufzuräumen”, und rollen dabei die bewusste Formulierung eines anderen zurück. Wie du Genehmigungsgrenzen sauber ziehst, habe ich im Leitfaden zu Genehmigungen und Sandbox ausführlich beschrieben – für den Team-Betrieb lohnt sich das dazu.

5. Für Legacy-Code

Beim Umbau alten Codes ist nicht „schön” die Tugend, sondern „nichts kaputt machen”.

# Legacy Repo Notes

- This codebase has inconsistent patterns
- Prefer compatibility over elegance
- Preserve behavior unless the task explicitly allows change

## Investigation First

1. Explain current behavior
2. Locate the smallest responsible file set
3. Identify risks before editing

## Do Not

- Do not rename public methods casually
- Do not introduce new frameworks
- Do not rewrite files only to match modern style

Prefer compatibility over elegance – „Kompatibilität vor Eleganz”. Bei Legacy-Projekten ist das oft das Allerwichtigste. Lässt du Claude Code freie Hand, kommt es gut gemeint mit „Ich schreibe das mal in den modernen Stil um” – und genau das ist bei Legacy das Einfallstor für Unfälle. Mit Do not rewrite files only to match modern style im Verbotsteil deckelst du diese gute Absicht.

6. Für Automatisierungs- und Betriebsskripte

E-Mail-Versand, Deployments, Schreibzugriffe auf externe APIs – wenn du Skripte mit Seiteneffekten anfassen lässt, ist das hier der erste Kandidat.

# Automation Rules

- Dry-run whenever the script supports it
- Log intended side effects before executing
- Prefer idempotent operations
- Keep secrets out of logs and generated files

## Required Checks

- Confirm environment variables used
- Confirm target environment
- Confirm output path or destination service

## Do Not

- Do not send emails, deploy, or publish without explicit approval
- Do not delete generated assets unless cleanup is requested

Log intended side effects before executing – „Schreib vor der Ausführung auf, was du anzurichten gedenkst” – ist das Sicherheitsventil. Lässt du erst ankündigen „Ich versende jetzt 120 Mails an die Produktion”, kann ein Mensch noch „Stopp” rufen. Zusammen mit Dry-run whenever the script supports it schiebst du vor jede unumkehrbare Aktion zuverlässig einen Puffer.

7. Für Monorepos

Wenn mehrere Apps und geteilte Pakete zusammenwohnen, schreibst du zuerst auf, „welches Paket wofür verantwortlich ist”.

# Monorepo Map

- `apps/web/` customer app
- `apps/admin/` internal admin tool
- `packages/ui/` shared UI
- `packages/config/` lint and tsconfig presets

## Ownership Rules

- Web UI work should stay inside `apps/web/` unless the task clearly needs a shared component change
- Shared package edits require checking downstream usage
- Avoid version or config churn unless necessary

## Verification

- Run the narrowest relevant build or test command first
- Describe cross-package impact before editing shared code

Allein durch die Ownership Rules gehen Unfälle bei übergreifenden Änderungen deutlich zurück. Was eine kleine Korrektur in apps/web/ sein sollte, greift plötzlich in eine geteilte Komponente in packages/ui/ ein und reißt am Ende auch noch apps/admin/ mit ins Verderben – das ist der typische Monorepo-Unfall. Lass den Zuständigkeitsbereich zuerst deklarieren und füg den einen Satz hinzu: „Erkläre die Auswirkung auf nachgelagerte Pakete, bevor du geteilten Code anfasst.”

Welche Vorlage solltest du nehmen?

Bei sieben Stück verliert man leicht den Überblick, deshalb die Auswahl jeweils in einer Zeile:

• UI oder Produkt im Mittelpunkt → Solo-App-Vorlage
• Artikel-, PDF- und Gumroad-Strecke vorhanden → Content-Site-Vorlage
• Konsistenz ist alles → API-Vorlage
• Hohe Abstimmungskosten → Team- oder Monorepo-Vorlage
• Hohe Unfallkosten → Legacy- oder Automatisierungs-Vorlage

Du musst nicht alle sieben mischen. Im Gegenteil: Beim Mischen wird die Datei lang und verliert an Wirkung. Nimm eine als Fundament und ergänze nur die Regeln, die in deinem Projekt das Verhalten wirklich ändern. Das ist der richtige Weg.

Vier Fehler, die man mit der CLAUDE.md gern macht

Ich teile die Minen, in die ich selbst getreten bin, einfach direkt mit dir.

Fehler 1: Schreiben wie ein Firmen-Wiki. „Je länger die Erklärung, desto besser” war ein kompletter Irrtum. Die CLAUDE.md ist kein Handbuch, sondern eine Betriebsdatei. Kurze Verhaltensregeln wirken um ein Vielfaches stärker als lange Hintergrunderklärungen. Man vergisst leicht die Grundannahme: Das liest keine Person, sondern eine KI.

Fehler 2: Nur Befehle aufschreiben, aber keinen Ablauf. Nur npm run test hinzuschreiben ist viel schwächer als Wenn du Billing anfasst, lauf immer die Tests. Ein Befehl teilt nur die „Existenz” mit. Ein Ablauf sagt auch, „wann er zu benutzen ist”.

Fehler 3: Keine Verbote. Das ist am ärgerlichsten verschenkt. Fass die .env nicht an, Sag nicht ‚Deploy erfolgreich' ohne geprüfte öffentliche URL, Mach kein force push. Ein einziger Satz verhindert einen nächtlichen Unfall. Der Do Not-Abschnitt ist keine Deko, sondern eine Versicherung.

Fehler 4: Nie aktualisieren. Wenn Claude Code denselben Fehler dreimal wiederholt, liegt es meist nicht an der KI, sondern die Körnung auf Seite der CLAUDE.md reicht nicht. Dann nicht schimpfen, sondern eine Regelzeile nachtragen. Die CLAUDE.md ist nicht mit dem Schreiben fertig – sie ist eine Datei, die du großziehst.

Häufige Fragen

F: Wohin im Projekt gehört die CLAUDE.md? A: Leg sie im Wurzelverzeichnis des Repos unter dem Namen CLAUDE.md ab, dann liest Claude Code sie automatisch ein. In einem Monorepo kannst du sie auch direkt in jedem Paket ablegen; die nähere hat Vorrang. Für die tatsächliche Ablage und die Prüfung, ob sie wirkt, brauchst du nur diese zwei Befehle.

# Einfach im Wurzelverzeichnis ablegen. Claude Code liest sie beim Start automatisch ein
cat > CLAUDE.md <<'EOF'
# Project
(die Vorlage von oben hier einfügen)
EOF

# Prüfen, ob sie wirkt: lass dir die Regeln zurückgeben
claude -p "Nenne drei Do-Not-Regeln aus der CLAUDE.md dieses Projekts"

Die genauen Ablageregeln findest du in der offiziellen Claude Code Dokumentation.

F: Wirkt es auch, wenn ich auf Deutsch schreibe? A: Ja. Ich schreibe Verbote und Abläufe durchaus auch auf Deutsch. Allerdings lassen sich die Vorlagen selbst auf Englisch leichter mit internationalen Teammitgliedern und mit Beispielen angleichen, deshalb sind sie in diesem Artikel auf Englisch gehalten. Solange der Inhalt ankommt, ist beides kein Problem.

F: Lange oder kurze CLAUDE.md – was ist besser? A: Die kurze. Faustregel: Sie sollte auf einen Bildschirm passen. Wenn sie länger wird, ist das das Signal, den Stoff in ein eigenes Dokument auszulagern. In der CLAUDE.md bleibt nur, „was das Verhalten ändert”.

F: Was ergänze ich als Erstes, nachdem ich die Vorlage eingefügt habe? A: Drei Do Not-Zeilen für dein Projekt. Je eine Zeile für „Dateien, deren Anfassen Ärger macht”, „Aktionen, deren Ausführung Ärger macht” und „Lügen, die Ärger machen” (z. B. eine Erfolgsmeldung ohne Prüfung). Das ist die Ergänzung mit dem höchsten Ertrag.

F: Wie unterscheiden sich CLAUDE.md und Permissions (Rechteeinstellungen)? A: Die CLAUDE.md ist „Bitte und Leitlinie”, die Permissions sind eine „durchsetzbare Erlaubnisliste”. Wenn du Verbote wirklich erzwingen willst, setzt du beide zusammen ein. Wie man Rechte aufteilt, streife ich auch im kompletten Einsteigerleitfaden für Claude Code.

Was bei mir tatsächlich herauskam

Als in meiner CLAUDE.md nur der Tech-Stack stand, war ich bei jeder Ausgabe von Claude Code nervös. „Läuft es diesmal wohl ordentlich die Tests?”

Nachdem ich Working Rules und Do Not ergänzt hatte, war diese Unruhe so gut wie weg. Vor allem die eine Zeile „Sag nicht ‚Deploy erfolgreich’, bevor du die öffentliche URL gesehen hast” schlägt sich klar in Zahlen nieder. Vorher kam es ein paarmal im Monat vor, dass nach „Deploy erledigt” in Wahrheit ein 404 stand; seit der Zeile ist das auf null gesunken.

Das Fazit ist schlicht: Die CLAUDE.md ist keine Datei, um die KI klüger zu machen, sondern eine Datei, um die KI keine Unfälle bauen zu lassen. Drei Verbote zu ergänzen wirkt gefühlt zehnmal so stark wie noch eine Stack-Zeile. Füg zuerst die eine Vorlage ein, die deinem Repo am nächsten kommt, und schreib einfach drei Do Not-Zeilen dazu.

Wer die Designphilosophie hinter der CLAUDE.md noch tiefer durchdringen will, liest den vollständigen Leitfaden zum Schreiben einer CLAUDE.md; wer das ganze „Gerüst” verstehen will, um Arbeit sicher an die KI abzugeben, den Leitfaden zum Harness Engineering. Wenn du Vorlagensammlung und Konfigurationsbeispiele griffbereit haben willst, helfen das kostenlose Claude Code Quick Reference Cheatsheet und der bis zu Hooks und Permissions reichende The Complete Claude Code Setup & Configuration Guide. Wer einmal alle Materialien durchsehen möchte, schaut in die Materialübersicht; wer die Standardisierung bis ins Team gemeinsam durchziehen will, geht zur Beratung.