# Claude Code Projektregeln — Next.js/React/TypeScript **Projekt:** `` **Stack:** Next.js 15+, React 19+, TypeScript, Tailwind CSS **Zuletzt aktualisiert:** `` --- ## 🎯 Verhaltens-Leitplanken (über allem) Diese 4 Prinzipien verhindern Over-Engineering, stille Annahmen und fehlende Verifikation. ### 1. Denken vor Coden ``` ✅ Annahmen EXPLIZIT aussprechen, nicht still voraussetzen ✅ Bei Mehrdeutigkeit: mehrere Interpretationen zeigen, nicht raten ✅ Bei Unklarheit: STOPPEN und fragen — keine Vermutungen ❌ NIEMALS still eine Interpretation wählen und loscoden ``` ### 2. Einfachheit zuerst ``` ✅ Minimaler Code der das Problem löst — nichts mehr ✅ Keine spekulativen Features für "könnte später nützlich sein" ✅ Keine Abstraktionen für Single-Use-Code ❌ NIEMALS ungefragte Flexibilität einbauen ``` ### 3. Chirurgische Änderungen ``` ✅ Nur anfassen was wirklich geändert werden muss ✅ Existierenden Stil matchen, nicht "verbessern" ❌ NIEMALS angrenzenden funktionierenden Code refactorn ``` ### 4. Ziel-getriebene Ausführung ``` ✅ Request in verifizierbare Erfolgskriterien umwandeln ❌ NIEMALS "sollte funktionieren" ohne Verifikation ``` --- ## 📐 Next.js/React Coding-Regeln ### REGEL 01 — Kein Stub-Code ```typescript // ❌ VERBOTEN export default function Component() { return null } // TODO // ✅ KORREKT — vollständig oder gar nicht export default function Component({ data }: Props) { if (!data) return return
{data.title}
} ``` ### REGEL 02 — Alle 4 UI-States abdecken ```typescript // Jede Komponente braucht: Loading + Error + Empty + Success if (isLoading) return if (error) return if (!data) return return
{data.content}
``` ### REGEL 03 — TypeScript ohne `any` ```typescript // ❌ type Props = { data: any } // ✅ type Props = { data: User | null } ``` ### REGEL 04 — Kein `console.log` in Produktion ```typescript // ❌ console.log(user) // ✅ logger.debug({ userId: user.id }) ``` ### REGEL 05 — API-Routes mit Validation + Error-Handling ```typescript export async function POST(request: Request) { try { const body = await request.json() const validated = schema.parse(body) // Zod/Yup const result = await service.create(validated) return Response.json(result, { status: 201 }) } catch (error) { if (error instanceof ZodError) { return Response.json({ error: error.errors }, { status: 400 }) } logger.error('POST /api/items failed', { error }) return Response.json({ error: 'Internal error' }, { status: 500 }) } } ``` ### REGEL 06 — Images optimieren ```typescript // ✅ Next.js Image-Component nutzen import Image from 'next/image' ... ``` ### REGEL 07 — Secrets nie committen ```bash # .gitignore muss enthalten .env .env.* ``` ### REGEL 08 — UTC für alle Timestamps ```typescript // ❌ new Date() // ✅ new Date().toISOString() oder date-fns/UTC ``` --- ## ✅ Definition of Done — React Component Eine Komponente/Feature ist NICHT fertig bis: ``` [ ] TypeScript ohne `any` — alle Props typisiert [ ] Alle 4 States implementiert (Loading/Error/Empty/Success) [ ] Kein `console.log` in produktiven Pfaden [ ] Mobile (375px) + Desktop (1280px) getestet [ ] `npm run build` → 0 Errors [ ] `npm run lint` → 0 Errors [ ] `npx tsc --noEmit` → 0 Errors [ ] Visuell im Browser geprüft — Screenshot oder Live-Link [ ] Analytics/Tracking nur nach User-Consent ``` --- ## ✅ Definition of Done — API Route ``` [ ] Request-Validation (Zod/Yup/etc.) [ ] Alle Error-Codes korrekt (400/401/403/404/500) [ ] Logging — Start/Success/Failure [ ] Tests: happy path + 400 + 500 [ ] `npm test` → alle Tests grün [ ] curl-Befehl gegen localhost → Response zeigen ``` --- ## 🚨 Kritische Verbote — IMMER gültig ``` ❌ NIEMALS `/init` ausführen (überschreibt CLAUDE.md) ❌ NIEMALS diese CLAUDE.md ohne explizite Anweisung ändern ❌ NIEMALS mehrere Features gleichzeitig implementieren ❌ NIEMALS weitermachen wenn Tests rot sind ❌ NIEMALS .env committen ❌ NIEMALS Code ohne vorherigen Test-Plan schreiben ❌ NIEMALS "es funktioniert" sagen ohne Beweis ❌ NIEMALS zur nächsten Aufgabe ohne Status-Update ``` --- ## 🔬 Proof-Protokoll (Pflicht vor "fertig") Beweis ist NICHT optional. Vor jedem "fertig" zeigen: ```bash # 1. Tests npm test # Ausgabe: X passed, 0 failed # 2. Build npm run build # Ausgabe: Build completed # 3. TypeScript npx tsc --noEmit # Ausgabe: 0 Errors # 4. Lint npm run lint # Ausgabe: 0 Errors # 5. Browser-Test # Screenshot oder curl-Output oder Live-URL ``` --- ## 🔐 Security-Basics ``` [ ] Alle Inputs validieren (Zod/Yup/etc.) [ ] CORS nicht wildcard in Produktion [ ] Rate-Limiting auf Auth-Endpoints [ ] Secrets aus .env, nie hardcoded [ ] Keine PII in Logs (E-Mails, Tokens, Passwörter) [ ] CSP/HSTS-Headers in Production (nginx/Middleware) ``` --- ## 📝 Arbeitsprotokoll — Kurzform ### Vor der Implementierung 1. Aufgabe in kleinste Einheit zerlegen (1 Component, 1 Route, 1 Feature) 2. Betroffene Dateien identifizieren 3. Test-Plan: Was ist Success? Was sind Fehlerfälle? 4. Bei Unklarheit: FRAGEN ### Implementierung 1. Eine Einheit auf einmal 2. Zuerst Test (wenn möglich), dann Code 3. Nach jeder Datei: mentaler DoD-Check ### Nach der Implementierung 1. Tests ausführen → Ausgabe zeigen 2. Build/Lint/TypeCheck → Ausgabe zeigen 3. Browser-Test → Screenshot oder Live-Link 4. ERST DANN "fertig" melden --- ## 📦 Standard-Befehle ```bash npm install # Dependencies installieren npm run dev # Dev-Server npm run build # Production-Build npm run start # Production-Server (nach Build) npm test # Tests ausführen npm run lint # ESLint npx tsc --noEmit # TypeScript-Check ``` --- ## 🎓 Self-Check vor jeder Antwort ``` [ ] Habe ich still eine Annahme getroffen? → Explizit machen [ ] Baue ich mehr als gefragt? → Zurückschneiden [ ] Ändere ich Code der nicht geändert werden muss? → Zurückdrehen [ ] Kann ich verifizieren ob es funktioniert? → Kriterium definieren [ ] Habe ich Beweis-Ausgaben gezeigt? → Nicht nur "sollte klappen" ``` --- **Anpassung erwünscht** — diese Vorlage ist ein Starter, kein Dogma. Ergänze projekt-spezifische Regeln (z.B. Monorepo-Konventionen, CI/CD-Gates, etc.).