CLAUDE.md-Konventionen
Die Datei CLAUDE.md enthält die Anweisungen, die Claude Code beim Starten einer Sitzung in deinem Projekt automatisch liest. Sie dient als Onboarding-Handbuch für die KI: Sie erklärt, welchen Stack du verwendest, wie der Code organisiert ist, welche Konventionen gelten und wie externe Tools wie Almirant angebunden werden.
Eine gut konfigurierte CLAUDE.md macht den Unterschied zwischen einer KI, die generischen Code erzeugt, und einer, die die Architektur, Muster und Konventionen deines Teams einhält.
Wo die Datei abgelegt wird
Lege CLAUDE.md im Stammverzeichnis deines Repositorys ab:
tu-proyecto/
CLAUDE.md # <-- hier
.claude/
skills/
settings.json
src/
package.json
Claude Code sucht beim Öffnen des Projekts automatisch nach dieser Datei. Es ist keine zusätzliche Konfiguration erforderlich.
Wenn du mit einem Monorepo arbeitest, kannst du eine CLAUDE.md im Stammverzeichnis und weitere in Unterverzeichnissen haben. Claude Code führt sie alle zusammen.
Was du bei der Verwendung von Almirant einbinden solltest
1. MCP-Konfiguration
Am wichtigsten ist, dass Claude Code weiß, wie es sich mit Almirant verbindet. Nimm die MCP-Serverkonfiguration mit URL und API Key auf.
## MCP - Almirant
Dieses Projekt ist zur Aufgabenverwaltung mit Almirant verbunden.
Konfiguration in `.claude/settings.json` oder `.mcp.json`:
\```json
{
"mcpServers": {
"almirant": {
"type": "http",
"url": "http://localhost:3001/mcp?projectId=<tu-project-uuid>",
"headers": {
"Authorization": "Bearer <tu-api-key>"
}
}
}
}
\```
Verwende die MCP-Tools, um Work Items, Boards und Sprints zu lesen und zu aktualisieren.
Verweise auf den Speicherort der MCP-Konfiguration, aber füge den API Key niemals direkt in CLAUDE.md ein. Verwende .claude/settings.json (die in .gitignore stehen sollte) oder Umgebungsvariablen.
2. Projektbeschreibung
Gib allgemeinen Kontext dazu, was das Projekt ist und welche Technologien es verwendet.
## Projektbeschreibung
B2B-E-Commerce-Webanwendung, erstellt mit:
- **Frontend**: Next.js 15 + React 19 + TypeScript + Tailwind CSS
- **Backend**: Bun + Elysia + Drizzle ORM
- **Datenbank**: PostgreSQL 16
- **Authentifizierung**: Better-Auth mit Google OAuth
- **Tests**: Vitest + Playwright
3. Repository-Struktur
Erkläre, wie der Code organisiert ist, damit die KI effizient navigieren kann.
## Struktur
\```
src/
domains/ # Module nach Domäne (DDD)
users/
domain/ # Typen und Schnittstellen
application/ # Hooks und Anwendungsfälle
presentation/ # Komponenten und Container
orders/
products/
components/ui/ # Gemeinsame Komponenten (shadcn/ui)
lib/ # Hilfsfunktionen, API-Client, Authentifizierung
\```
4. Code-Konventionen
Definiere die Regeln, die Claude Code beim Generieren von Code befolgen soll.
## Konventionen
- **Dateien**: kebab-case (`user-service.ts`, `order-form.tsx`)
- **Komponenten**: PascalCase (`UserProfile`, `OrderList`)
- **Hooks**: camelCase mit Präfix `use` (`useUserProfile`, `useOrderList`)
- **Keine Klassen**: Functional Programming verwenden. Reine Funktionen, Custom Hooks, funktionale Objekte
- **Typen**: In `domain/types.ts`, nicht innerhalb von .tsx-Komponenten
- **.tsx-Komponenten**: Nur präsentational. Kein useState, useEffect oder Geschäftslogik
- **Logik**: In Custom Hooks innerhalb von `application/hooks/`
5. Projektbefehle
Nimm die Befehle auf, die Claude Code gegebenenfalls ausführen muss.
## Befehle
\```bash
bun run dev # Entwicklungsserver
bun run build # Produktions-Build
bun run lint # Linter
bun run test # Tests
bun run type-check # Typprüfung
bun run db:generate # Migration generieren
bun run db:migrate # Migrationen anwenden
\```
6. Code-Muster
Dokumentiere spezifische Muster, die die KI nachbilden soll.
## Muster
### API-Aufrufe mit React Query
Alle API-Aufrufe verwenden React Query mit strukturierten Query Keys:
\```typescript
export const userKeys = {
all: ['users'] as const,
list: (filters: UserFilters) => [...userKeys.all, 'list', filters] as const,
detail: (id: string) => [...userKeys.all, 'detail', id] as const,
};
export const useUsers = (filters: UserFilters) => {
return useQuery({
queryKey: userKeys.list(filters),
queryFn: () => usersApi.getAll(filters),
});
};
\```
### Mutations mit Invalidierung
\```typescript
export const useCreateUser = () => {
const queryClient = useQueryClient();
return useMutation({
mutationFn: usersApi.create,
onSuccess: () => {
queryClient.invalidateQueries({ queryKey: userKeys.all });
},
});
};
\```
7. Projektspezifische Regeln
Nimm Einschränkungen oder Geschäftsregeln auf, die die KI einhalten muss.
## Regeln
- **NIEMALS** SQL direkt ausführen. Drizzle ORM + Migrationen verwenden
- **NIEMALS** .env-Dateien oder Zugangsdaten committen
- **NIEMALS** Dateien in `migrations/meta/` ändern
- Work Items haben KEINE Spalte `status` -- der Status wird aus der Board-Spalte abgeleitet
- Work Items verwenden zum Archivieren `archived_at` (Timestamp) anstelle eines Boolean-Werts
- Die Authentifizierung verwendet Cookies `better-auth.session_token`
Vollständiges Beispiel
# CLAUDE.md
## Projekt
B2B-E-Commerce für den Vertrieb von Industrieprodukten.
**Stack**: Next.js 15 + React 19 + TypeScript + Tailwind CSS 4 + Elysia + Drizzle ORM + PostgreSQL 16
## MCP - Almirant
Aufgabenverwaltung über MCP. Konfiguration in `.mcp.json`.
MCP-Tools verwenden, um Work Items vor der Implementierung zu lesen und
den Status nach Abschluss zu aktualisieren.
## Struktur
\```
src/
domains/ # DDD-Module
catalog/ # Produkte und Kategorien
orders/ # Bestellungen und Abrechnung
customers/ # B2B-Kunden
components/ui/ # shadcn/ui
lib/ # API-Client, Authentifizierung, Hilfsfunktionen
\```
## Konventionen
- Dateien in kebab-case
- Komponenten: nur präsentational (keine Hooks in .tsx)
- Logik: Custom Hooks in application/hooks/
- Typen: in domain/types.ts
- Keine Klassen: nur Funktionen, Hooks, Schnittstellen
## Befehle
\```bash
bun run dev # Entwicklungsserver (Port 3000)
bun run build # Produktions-Build
bun run lint # ESLint
bun run test # Vitest
bun run db:generate # Migration generieren
bun run db:migrate # Migrationen anwenden
\```
## Muster
### React Query
Query Keys nach Domäne strukturiert.
Mutations invalidieren zugehörige Queries bei onSuccess.
### API Client
Module in lib/api/client.ts:
- catalogApi.getProducts(filters)
- ordersApi.create(data)
- customersApi.getById(id)
## Regeln
- NIEMALS direktes SQL, immer Drizzle + Migrationen
- NIEMALS .env committen
- Bestellungen erfordern vor der Bestätigung eine Bestandsprüfung
- Preise werden serverseitig berechnet, dem Frontend niemals vertrauen
Fortgeschrittene Tipps
Nach Zielgruppe gliedern
Wenn in deinem Team unterschiedliche Profile arbeiten (Frontend, Backend, DevOps), kannst du Abschnitte mit klaren Überschriften verwenden, damit jede Skill oder jeder Ablauf weiß, wo relevante Informationen zu finden sind.
Aktuell halten
Behandle CLAUDE.md als lebendige Dokumentation. Aktualisiere die Datei, wenn du ein Muster, eine Konvention oder die Projektstruktur änderst. Eine veraltete Anweisung kann dazu führen, dass die KI inkonsistenten Code erzeugt.
Das Offensichtliche nicht duplizieren
Du musst nicht dokumentieren, wie React oder TypeScript funktionieren. Konzentriere dich auf die Besonderheiten deines Projekts: interne Konventionen, eigene Muster und geschäftliche Einschränkungen.
Mit dem Team validieren
Wie die Skills wird auch CLAUDE.md mit Git versioniert. Prüfe sie bei bedeutenden Änderungen im Code Review, damit sichergestellt ist, dass das gesamte Team auf dem gleichen Stand ist.
Nimm niemals Zugangsdaten, API Keys, Tokens oder Produktions-URLs direkt in CLAUDE.md auf. Diese Datei wird mit Git versioniert und ist für das gesamte Team sichtbar. Verwende Umgebungsvariablen oder Konfigurationsdateien in .gitignore.