Schluss mit unkontrolliertem Claude-Code: Eine Config steigert die Genauigkeit um 10 %

Wenn Sie mit Claude Code an einem bestehenden Projekt arbeiten, verwechselt es manchmal den Tech-Stack: In einem React-Projekt tauchen Vue-Muster auf, in der Doku steht TypeScript – generiert wird JavaScript. CLAUDE.md im Projektroot behebt genau dieses Kontext-Problem.

Bei einem Node-Backend habe ich es selbst erlebt: Claude schrieb Middleware im Express-Stil, obwohl das Projekt Koa nutzte – die Pipeline war kaputt. In Anthropic-Tests steigert eine saubere CLAUDE.md die Codierungsgenauigkeit typischerweise um 5–10 %. Die folgenden sieben Schreib-Tipps sind aus solchen Fehlern gewachsen – jedes mit kopierbaren Beispielen.

Was CLAUDE.md eigentlich ist

Kurz gesagt: CLAUDE.md ist eine Markdown-Datei im Projektroot, die Claude Code an Ihr Projekt heranführt – ähnlich wie .editorconfig oder README.md, aber gezielt für KI-gestütztes Coding.

Mechanismus: Beim Einsatz von Claude Code im Projekt wird die Datei gelesen. Die Doku spricht von automatischem Laden; in der Praxis hilft /init, damit die Config wirklich „angekommen“ ist. Inhalt landet im Kontext und prägt alle weiteren Vorschläge.

Hierarchische Konfiguration unterstützt Claude Code:

project-root/
├── CLAUDE.md              # global (gesamtes Projekt)
├── frontend/
│   └── .claude/
│       └── CLAUDE.md     # Frontend-spezifisch
└── backend/
    └── .claude/
        └── CLAUDE.md     # Backend-spezifisch

Im Root legen Sie allgemeine Regeln fest, in Teilmodulen überschreiben Sie sie – z. B. React im Frontend, Node im Backend.

Vier Grundprinzipien

Bevor Sie loslegen: diese vier Regeln. Ohne sie habe ich einmal 300+ Zeilen „Epik“ geschrieben – Claude wurde schlechter, nicht besser.

1. Kürze: Prinzip der 100 Zeilen

CLAUDE.md ist kein README. Lange Erklärungen helfen der KI hier wenig.

Alibaba Cloud - Top-Wahl für Entwickler, exklusiv 15 % Rabatt auf Lighthouse-Server

15 % Rabatt sichern →Anzeige

Warum kurz? Die Datei frisst Token. Je länger sie ist, desto weniger bleibt für Code-Analyse. Arize AI empfiehlt Configs unter 100 Zeilen.

❌ Schlecht (wiederholt und ausschweifend):

# Projektintro
Dies ist ein React-Frontend. Wir nutzen React für die UI.
React ist eine von Facebook entwickelte JavaScript-Bibliothek … (200 Zeilen React-Erklärung)
# Tech-Stack
Unser Stack umfasst:
- React – UI-Framework, Version 18.2 …
- TypeScript – für Typen …

✅ Gut (knapp, handlungsleitend):

# Tech-Stack
- React 18.2 (Hooks bevorzugt, keine Class-Komponenten)
- TypeScript (strict)
- TailwindCSS (utilities-first)
# Code-Stil
- Funktionskomponenten + eigene Hooks
- Props per Destructuring
- const bevorzugen, let vermeiden

Der zweite Block transportiert mehr Nutzen in weniger Zeichen.

2. Konkret: ausführbar statt vage

❌ Schlecht:

# Code-Stil
- Code sauber halten
- Best Practices befolgen
- auf Performance achten

Das lässt sich nicht prüfen.

✅ Gut:

# Code-Stil
- Funktionen max. 50 Zeilen, sonst aufteilen
- API-Aufrufe mit Fehlerbehandlung und Loading-State
- Listen mit key, ID statt Index
- keine verschachtelten Ternaries – if/else oder early return

3. Iterativ: Config lebt mit dem Projekt

Config einmal schreiben und monatelang ignorieren – klassischer Fehler. Stack wechselt (z. B. Vue 2 → 3), die Datei erwähnt noch Options API.

Schnell bearbeiten mit #: In Claude Code öffnet # CLAUDE.md. Verhält sich die KI falsch, sofort eine Zeile ergänzen.

Beispiel: Claude nutzte axios, das Team aber fetch + Wrapper. Eine Zeile in CLAUDE.md:

Railway - Moderne Deployment-Plattform, ohne DevOps-Aufwand, in Minuten live

Jetzt starten →Anzeige

# HTTP
- einheitlich `src/utils/request.ts` (fetch-Wrapper)
- kein axios, kein rohes fetch

Danach blieb der Fehler weg.

4. Team: Versionskontrolle

CLAUDE.md gehört ins Git – wie .gitignore.

Die Datei ist Team-Konsens. Unterschiedliche lokale Versionen → unterschiedliche KI-Stile pro Entwickler.

# CLAUDE.md nicht in .gitignore
# ❌ falsch
*.md
# ✅ richtig
*.md
!CLAUDE.md
!README.md

Änderungen in Code Reviews mitprüfen.

"Config kurz und konkret – unter 100 Zeilen ideal. Jede Regel muss ausführbar und prüfbar sein."

Fünf Pflichtmodule

Ohne diese Bausteine bringt CLAUDE.md wenig.

1. Tech-Stack

Frameworks, Libraries, Versionen – Pflicht.

# Tech-Stack
**Frontend**
- Next.js 14 (App Router)
- React 18 (Server Components bevorzugt)
- TypeScript 5.2
- Tailwind CSS 3.4
**Backend**
- Node.js 20 LTS
- Express 4.18
- Prisma ORM
- PostgreSQL 15

Ohne Version riskiert Claude veraltete APIs (z. B. Next.js 13 vs. 14).

2. Projektstruktur

# Projektstruktur
src/
├── app/              # Next.js-Routen
├── components/
│   ├── ui/          # Basis (Button, Input)
│   └── features/    # Business (UserCard, OrderList)
├── lib/
├── services/        # API-Schicht
└── types/
# Dateinamen
- Komponenten: PascalCase (UserProfile.tsx)
- Utils: camelCase (formatDate.ts)
- Konstanten: UPPER_SNAKE_CASE (API_BASE_URL)

3. Befehle

# Dev-Befehle
npm run dev          # Dev-Server (localhost:3000)
npm run build
npm run test
npm run lint
npm run type-check
# Datenbank
npx prisma studio
npx prisma migrate dev

4. Code-Stil

# Code-Regeln
## React
- Funktionskomponenten + Hooks, keine Class-Komponenten
- Props-Typen als interface über der Komponente
- Reihenfolge: Props → Komponente → Export
## State
- lokal: useState/useReducer
- Server: TanStack Query
- global: Zustand (Context vermeiden)
## Fehler
- API: try-catch
- Nutzer: Toast
- Dev: console.error, Prod: Sentry

5. Workflow und Grenzen

# Workflow
- Feature: Typen → Komponente → Tests
- Bugfix: Repro-Test → Fix → Tests grün
# Grenzen
- ❌ `/prisma/schema.prisma` nicht ändern (Team-Review)
- ❌ keine neuen Dependencies ohne Abstimmung
- ❌ `/lib/auth/*` nicht anfassen
- ✅ `/components` und `/app` für Business-Code

Sieben Tipps mit großer Wirkung

Tipp 1: SHOULD/MUST für Priorität

# Priorität
**MUST**
- MUST TypeScript strict
- MUST Fehlerbehandlung an APIs
**SHOULD**
- SHOULD Komponenten < 200 Zeilen
- SHOULD wiederholte Logik als Hook
**COULD**
- COULD JSDoc

Tipp 2: /init nutzen

Nach Config-Änderungen /init – wie ein Kontext-Refresh.

Sie: /init
Claude: Projekt-Config geladen, Stack: React 18 + TypeScript …

Tipp 3: Beispielcode statt Prosa

❌ Nur Text: „API mit Typen, Fehler, Loading“

✅ Mit Muster:

Vultr - Hochleistungs-NVMe-Cloud-Server mit 32 Standorten weltweit, Docker per Klick

Preise ansehen →Anzeige

# API-Muster
Referenz:
\`\`\`typescript
// src/services/user.ts
export async function getUser(id: string): Promise<User> {
  try {
    const response = await fetch(`/api/users/${id}`);
    if (!response.ok) throw new Error('Failed to fetch user');
    return await response.json();
  } catch (error) {
    console.error('getUser error:', error);
    throw error;
  }
}
\`\`\`
Alle API-Funktionen: typisierter Return, try-catch, Log

Tipp 4: Schichten im Monorepo

monorepo-root/
├── CLAUDE.md
├── apps/
│   ├── web/.claude/CLAUDE.md
│   └── mobile/.claude/CLAUDE.md
└── packages/shared/.claude/CLAUDE.md

Root: pnpm, tsconfig, Conventional Commits. apps/web: Next.js + Tailwind + Zustand.

Tipp 5: ❌ und ✅ vergleichen

# State-Updates
❌ state direkt mutieren
✅ immutable: setUser(prev => ({...prev, age: 31}))

Tipp 6: Typische Fehler dokumentieren

# ⚠️ Häufige Fehler
## 1. useEffect ohne Cleanup
❌:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
}, []);
\`\`\`
✅:
\`\`\`typescript
useEffect(() => {
  const timer = setInterval(() => {/* ... */}, 1000);
  return () => clearInterval(timer);
}, []);
\`\`\`
## 2. fehlende Dependencies
ESLint-Warnung nicht blind deaktivieren – Deps ergänzen oder useCallback/useMemo

Tipp 7: Links zu Detail-Docs

# Detail-Dokumentation
- [API-Richtlinien](./docs/api-guidelines.md)
- [Komponenten-Guide](./docs/component-guide.md)
- [Tests](./docs/testing.md)

Fünf häufige Fallstricke

1. Zu lang – README + API-Doku reinpacken → Token-Verlust. Lösung: 100 Zeilen, nur Coding-relevantes.
2. Nie aktualisieren – Lösung: nach Refactors anpassen, PR-Review.
3. Nicht versionieren – Lösung: ins Git, nicht ignorieren.
4. Vage Regeln – „Best Practices“ hilft nicht. Lösung: prüfbare Sätze.
5. Secrets – keine Keys in CLAUDE.md.

❌ falsch
DATABASE_URL=postgresql://admin:password123@localhost:5432/mydb
✅ richtig
- DATABASE_URL: aus .env.local, Format siehe .env.example
- API_KEY: aus Umgebungsvariable, Test-Key vom Team anfragen

Drei Praxisbeispiele

Fall 1: React-Frontend (E-Commerce)

# E-Commerce-Frontend
## Tech-Stack
- Next.js 14.0 (App Router)
- React 18.2, TypeScript 5.2, Tailwind 3.4
- Zustand, TanStack Query
## Struktur
src/app, src/components/ui|features, lib, services
## Regeln
- Funktionskomponenten + Hooks
- API: try-catch
## Befehle
npm run dev | build | lint
## Grenzen
- /lib/auth/* nicht ändern
- keine neuen Pakete ohne Team

Effekt: Komponenten-Struktur nahe am manuellen Code.

Fall 2: Node.js-API

Express, Prisma, PostgreSQL, Zod; Schichten routes/controllers/services; Controller-Beispiel mit Zod-Parse und Logging in CLAUDE.md; npm run dev, npx prisma studio.

Effekt: Neue Endpunkte mit Validierung und Fehlerbehandlung.

Fall 3: Monorepo

Root-CLAUDE.md: pnpm workspaces, strict TS, ESLint+Prettier, pnpm install, pnpm run lint, pnpm --filter web dev. Unter apps/web und apps/api jeweils eigene .claude/CLAUDE.md mit Ports 3000/4000 – Claude passt React vs. Express automatisch an.

Fazit

Drei Merksätze: kurz (≤100 Zeilen), konkret (prüfbar), aktuell (mit dem Projekt mitwachsen).

Eine gute CLAUDE.md kann die KI-Produktivität spürbar heben – starten Sie mit Tech-Stack, erweitern Sie bei jedem wiederkehrenden Fehler um eine Zeile. Nach großen Upgrades nicht vergessen: Die Datei ist kein Einmal-Setup, sondern Teil Ihrer Projekt-DNA.