Claude Code

Der Starter gibt Claude Code Leitplanken statt einer umfangreichen Anweisungssammlung.

Aufteilung

Drei Orte, jeder mit einer eigenen Aufgabe (ADR 0017):

Ort	Aufgabe	Was nicht hineingehört
CLAUDE.md	was gilt	Abläufe, Befehlssammlungen, was im Code steht
.claude/skills/	wie etwas gemacht wird	Regeln, die schon in CLAUDE.md stehen
.claude/agents/	womit geprüft wird	Rollen ohne Kontext- oder Toolvorteil
project/	die Arbeitsgrundlage	Fakten, die aus project.config.ts hervorgehen

Die Grenzen von CLAUDE.md

Die Datei enthält ausschließlich stabile, projektweite Regeln — nummeriert, mit Verweis auf das ADR, das sie begründet. Sie liegt bei jedem Aufruf vollständig im Kontext; alles, was dort steht und nicht bei jeder Aufgabe gilt, kostet in jeder anderen Aufgabe Platz.

Nicht hinein gehören:

• Abläufe. „Erst dies, dann jenes" ist ein Skill — dort hat es Abschlusskriterien.
• Fakten aus dem Code. Welche Komponenten es gibt, sagt src/components/ui/.
• Befehlssammlungen. package.json ist die Wahrheit über die Skripte.
• Begründungen. Die stehen in docs/adr/. CLAUDE.md sagt, was gilt.

Ein Zeilenbudget hält die Datei bei dieser Aufgabe; tests/unit/claude-system.test.ts bricht ab, wenn sie darüber hinauswächst. Das ist kein Schönheitswunsch: Eine Regelsammlung, die zur Anleitung wird, widerspricht sich irgendwann — und niemand merkt es, weil niemand sie am Stück liest.

Die Skills

Zehn Stück unter .claude/skills/, je eine SKILL.md mit immer denselben sieben Abschnitten: Zweck · Eingaben · Ablauf · Erlaubte Änderungen · Validierung · Abschlusskriterien · wann nicht verwenden.

Die letzten drei tragen das Ganze. Die Validierung nennt den Befehl, der den Zustand belegt; die Abschlusskriterien enden immer auf pnpm verify; und „wann nicht verwenden" ist der Abschnitt, der einen Skill davon abhält, zur Universalantwort zu werden.

Skill	Wofür	Wann nicht
project-init	pnpm starter:init begleiten und das Ergebnis prüfen	in einem bereits initialisierten Projekt; für ein Upgrade
project-brief	project/*.md aus einem Kundengespräch füllen	zum Bauen; für Entscheidungen, die der Auftraggeber trifft
design-foundation	Design Tokens und Styleguide-Abdeckung, einmal je Projekt	für eine einzelne Seite; für einen Dark Mode (das braucht ein ADR)
import-assets	Bilder aufnehmen, benennen, ins Manifest eintragen	für public/-Dateien; um einen Alt-Text zu bestätigen
create-page	Eine Route vollständig anlegen	für Seiten mit Formular (erst create-form); für den Styleguide
create-form	Felder anlegen oder ändern, Vertrag erzeugen	um die Prüfreihenfolge im Handler zu ändern; ohne Backend
configure-seo	Metadaten, Schemata, Indexierung, Sitemap	für den Titel einer einzelnen Seite; für Mehrsprachigkeit
configure-tracking	Consent-Schicht, Consent Mode, Tag Manager	um Tags zu bauen; um eine Kategorie „auf Vorrat" anzubieten
configure-deployment	Zielsystem, Serverregeln, Header, CSP	um die erzeugte .htaccess anzufassen; für einen Rollback
release-audit	Vor dem Release die Definition of Done belegen	als Ersatz für pnpm verify währenddessen; um zu reparieren

Ein Skill verweist auf eine Regel, statt sie zu wiederholen. Eine umformulierte Regel ist auf Dauer eine widersprochene Regel — das ist beim Schreiben eines neuen Skills die wichtigste Zeile dieser Seite.

Die Review-Agents

Vier unter .claude/agents/, entlang der vier Bereiche, in denen dieses Repository etwas zusagt. Jeder bekommt ausschließlich lesende Werkzeuge: Ein Reviewer, der nebenbei repariert, verliert den Blick auf das, was er noch nicht geprüft hat.

• design-system-reviewer — Token statt Werte, vollständige Klassennamen, semantische Namen, Styleguide-Abdeckung in allen Varianten.
• seo-tracking-reviewer — Auszeichnung nur zu sichtbarem Inhalt, Routen-Policy als eine Quelle, kein Google-Request vor der Einwilligung, jede Kategorie mit Verbraucher.
• accessibility-performance-reviewer — Elementwahl nach Bedeutung, Label und aria-describedby, genau ein priorisiertes Bild, die Budgets als Gate.
• forms-security-reviewer — Prüfreihenfolge im Handler, Vertragsdrift zwischen Frontend und Backend, was im Log landet, Fristen für gespeicherten Zustand.

Einen repository-architect gibt es bewusst nicht: Das sind CLAUDE.md und die ADRs bereits. Ein Agent lohnt sich nur, wenn er einen Kontext- oder Toolvorteil mitbringt, der im Repository noch nicht steht.

Das Projektbriefing

Unter project/ liegen sieben Vorlagen mit Leitfragen — die Eingaben, aus denen die Skills arbeiten:

Datei	Beantwortet
brief.md	Ziel, Zielgruppe, Seiten, Material — und was es nicht wird
brand.md	vorhandenes Material, Anmutung, Farben, Typografie, Form
content-plan.md	Seitenliste, Navigation, je Seite Abschnitte und Bilder
seo-plan.md	Themen, Titel, Schemata, Routen ohne Index, Weiterleitungen
tracking-plan.md	ob überhaupt, was gemessen wird, Kategorien und ihre Verbraucher
forms-plan.md	Formulare, Felder, Empfänger, Schutz, Aufbewahrung
deployment.md	Ziel, Domain, Weiterleitungen, CSP, HSTS, wo die Geheimnisse liegen

brief.md wird von pnpm starter:init überschrieben und mit den Angaben der Initialisierung gefüllt. Die übrigen sechs füllt ein Mensch — oder der project-brief-Skill aus dem, was belegt ist.

Die Vorlagen enthalten Leitfragen, keine Beispielinhalte. Ein stehengebliebener Beispieltext wird beim nächsten Lesen für eine Antwort gehalten; eine leere Zeile nicht.

Der Design-Workflow

Claude Design soll nicht bei jeder Seite ein neues Designsystem erfinden. Der Weg ist deshalb festgelegt, und er läuft in dieser Reihenfolge:

Briefing
→ Asset- und Markenprüfung
→ visuelle Richtung
→ Design Tokens
→ Grundkomponenten
→ interner Styleguide
→ erste reale Seite
→ Review

Schritt	Womit	Ergebnis
Briefing	project-brief	project/brief.md, brand.md gefüllt
Asset- und Markenprüfung	import-assets	Logo und Bildmaterial im Manifest, Rechte geklärt
visuelle Richtung	Mensch	eine Entscheidung, festgehalten in brand.md
Design Tokens	design-foundation	src/styles/theme.css
Grundkomponenten	design-foundation	src/components/ui/ deckt die Richtung ab
interner Styleguide	design-foundation	jedes Primitive in allen Varianten, axe grün
erste reale Seite	create-page	eine Seite, die nur Vorhandenes benutzt
Review	die vier Agents	Befunde, getrennt nach Verstoß und Anmerkung

Die Reihenfolge ist der Punkt. Wer mit der ersten realen Seite anfängt, bekommt Tokens, die aus dieser einen Seite abgeleitet sind — und beim zweiten Entwurf ein zweites System daneben.

Die visuelle Richtung entscheidet ein Mensch. Die Schritte davor bereiten sie vor, die danach setzen sie um. Wie aus Referenzen belastbare Werte werden — messen statt raten, und was tun, wenn die Vorbilder einander widersprechen —, steht unter Von der Referenz zu den Tokens.

Memory und Learnings

Klein und kontrolliert. Was aus Code, ADR oder docs/ hervorgeht, wird nicht ein zweites Mal abgelegt — eine zweite Kopie veraltet, und dann widersprechen sich zwei Quellen ohne erkennbaren Vorrang.

Ein bestätigtes Learning gehört dorthin, wo es beim nächsten Mal ohnehin gelesen wird:

• Es ändert eine Regel → CLAUDE.md
• Es begründet eine Entscheidung, deren Umkehrung teuer wäre → ein ADR
• Es beschreibt einen Ablauf → der zuständige Skill
• Es betrifft nur dieses Kundenprojekt → project/

Spekulatives wird gar nicht gespeichert. Ein Learning ist bestätigt, wenn es einmal tatsächlich weh getan hat.

Was hier nicht passiert

• Kein Umbau bestehender Bereiche „bei der Gelegenheit". Wer beim Arbeiten etwas Fragwürdiges findet, benennt es, statt es nebenbei zu ändern.
• Keine neue Abhängigkeit ohne Begründung im Pull Request.
• Kein Skill, der eine Regel aus CLAUDE.md umformuliert.