code-vorlage/CLAUDE.md

AI Coding Starter Kit

Next.js template with an AI-driven development workflow. Skills cover Requirements, Architecture, Frontend, Backend, QA and Deployment. Every phase writes its result into the feature spec, so state lives in files rather than in the conversation.

Tech Stack (binding for every new app)

Layer	Choice	Notes
Framework	Next.js 16, App Router	React 19, Server Components by default
Language	TypeScript, strict	@/* maps to src/*
Styling	Tailwind CSS v4	CSS-first config in src/app/globals.css. There is no tailwind.config.ts — theme tokens live in @theme inline.
Components	shadcn/ui (new-york)	6 pre-installed. Add more with npx shadcn@latest add <name> --yes. Never hand-write an equivalent.
Icons	lucide-react
Forms	react-hook-form + Zod	Zod schema is the single source of truth for a form's validation
Notifications	sonner	Mounted in layout.tsx. The deprecated shadcn toast is deliberately absent.
Theming	next-themes	attribute="class", dark mode via .dark
Auth	Better Auth + passkey plugin	Only when the project needs auth. Passkeys are the primary method — see .claude/rules/security.md.
Data layer	decided per project	The template ships none. /architecture picks and documents it.
Tests	Vitest (unit) + Playwright (E2E)	Vitest only scans src/, Playwright only tests/
Deployment	Docker Compose, self-hosted	App container only; TLS/routing via a reverse proxy on the host

Deliberately not part of this template: Supabase, Vercel, any preselected ORM or database. Do not reintroduce them without the user asking.

Project Structure

src/
  app/              Pages and route handlers (App Router)
    api/health/     Liveness probe used by Docker + update script
  components/
    ui/             shadcn/ui — NEVER recreate these by hand
  hooks/            Custom React hooks
  lib/utils.ts      cn() helper
features/           One spec per feature: PROJ-X-name.md
  INDEX.md          Status of every feature — read this first
docs/
  PRD.md            Product Requirements Document
  DEPLOYMENT.md     Docker Compose operations
tests/              Playwright E2E specs
scripts/update.sh   Pull, rebuild, restart, roll back on failure

Workflow

Step	Command	Produces
1	/init	PRD + feature map (once per project)
2	/write-spec	Full spec for one feature
3	/architecture	Tech design inside the spec
4	/frontend	UI components
5	/backend	APIs, data layer, auth
6	/qa	Test results inside the spec
7	/deploy	Live Docker Compose stack

/refine PROJ-X reopens an existing spec. /help reports where the project stands.

Conventions

• Feature IDs: PROJ-1, PROJ-2, … sequential, tracked in features/INDEX.md
• Commits: type(PROJ-X): description — feat, fix, refactor, test, docs, deploy, chore
• One feature per spec file — never combine independent functionality
• Spec language: German (PRD, specs, acceptance criteria). Code, comments and skill instructions stay English.
• Human-in-the-loop: every skill ends with a user approval checkpoint
• Tests: unit tests co-located (useThing.test.ts beside useThing.ts), E2E in tests/

Commands

npm run dev          # Dev server on :3000
npm run build        # Production build (standalone output)
npm run lint         # ESLint (flat config)
npm run typecheck    # tsc --noEmit
npm test             # Vitest
npm run test:e2e     # Playwright
npm run test:all     # Both
npm run docker:up    # Build and start the Compose stack
./scripts/update.sh  # Deploy latest commit on the server

Product Context

@docs/PRD.md

Feature Overview

@features/INDEX.md

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.