Projekt-Vorlage/CLAUDE.md

# Arbeitsweise

Du arbeitest immer in drei Phasen und überspringst keine:

1. **Idee klären:** Verständnis in 2–3 Sätzen wiedergeben, Lösungsvorschlag, Rückfragen.
   Keine Dateien ändern.
2. **Vorgehensweisen:** 2–3 Wege mit Vor- und Nachteilen vorstellen.
   Keine Dateien ändern.
3. **Umsetzung** erst nach ausdrücklicher Freigabe durch den Nutzer.

# Projektstruktur

- Das Repo ist das Projekt; der Dev Container öffnet das ganze Repo.
- Die Next.js-App (package.json, app/, components/, lib/) liegt im Unterordner
  `frontend-starter`. Alle npm-Befehle führst du dort aus, z. B.
  `cd frontend-starter && npm run dev`.

# Git

## Vor der Umsetzung
- `git switch main && git pull`
- Eigenen Branch anlegen: `git switch -c feat/<kurzname>` (Fehler: `fix/<kurzname>`,
  Pflege: `chore/<kurzname>`).
- Hast du versehentlich schon auf `main` Dateien geändert: nicht committen, sondern
  `git switch -c feat/<kurzname>`; die Änderungen wandern mit.

## Committen und Pushen
- Du committest und pushst NICHT von dir aus. Ist eine Änderung fertig, zeigst du
  `git status`, nennst die geänderten Dateien und schlägst eine Commit-Nachricht vor.
  Erst wenn der Nutzer ausdrücklich „committen“ oder „pushen“ sagt, führst du es aus.
- Commits immer mit Nachricht im Befehl: `git commit -m "feat: ..."`.
  Nie `git commit` ohne `-m`, sonst wartet Git auf einen Editor und hängt.
- Push nur mit `git push -u origin <branch>`. Niemals auf `main`, niemals force-push.
- Schlägt ein Push fehl (z. B. „Permission denied“, „protected branch“), änderst du
  nichts an Remote-Adresse, SSH-Einstellungen oder Branch-Schutz. Du erklärst die
  Meldung und überlässt die Lösung dem Nutzer.
- Pull Requests öffnet und mergt der Nutzer selbst in Gitea.

## Was nie ins Repo gehört
- `node_modules/`, `.next/`, `.env`, `.env.local` und andere `.env.*` (außer
  `.env.local.example`), Datenbankdateien unter `data/`.
- Prüfe vor jedem Commit mit `git status`, dass keine dieser Dateien dabei ist.
  Taucht eine auf, ergänzt du `.gitignore` und entfernst sie mit
  `git rm -r --cached <pfad>` aus Git, nicht von der Festplatte.
- Keine Passwörter, Tokens oder Secrets im Code. Werte gehören in `.env.local`,
  neue Variablennamen zusätzlich als Platzhalter in `.env.local.example`.

# Entwicklung

- Die App läuft IMMER auf Port 3000 (`npm run dev`). Ist der Port belegt, wechselst
  du nicht auf einen anderen Port, sondern beendest den alten Prozess
  (`npx kill-port 3000`) und startest neu.
- UI ausschließlich mit shadcn/ui-Komponenten aus `components/ui`. Fehlt eine:
  `npx shadcn@latest add <name>` im App-Ordner.
- Pakete nur mit `npm install <paket>` bzw. `npm uninstall <paket>` ändern, nie von
  Hand in der package.json. `package.json` und `package-lock.json` immer gemeinsam
  committen, sonst scheitert der Build beim Deployment.
- Für die Hilfsfunktion `cn` nutzt shadcn die Pakete `clsx` und `tailwind-merge`,
  nicht ein Paket namens `cn`.
- Bevor du eine Änderung als fertig meldest, muss `npm run build` ohne Fehler
  durchlaufen. Genau dieser Build läuft später beim Deployment.

# Nicht anfassen

Diese Dateien ändern das Deployment oder die Schutzregeln. Du änderst sie nur,
wenn der Nutzer es ausdrücklich verlangt, und weist dann auf die Folgen hin:
- `Dockerfile`, `.dockerignore`
- `output: "standalone"` in `next.config.mjs`, Port 3000 in `package.json`
- `.devcontainer/`, `.claude/`, `.gitea/`

# Deployment

- Deployt wird automatisch: Merged der Owner einen Pull Request nach `main`,
  baut Coolify die App und veröffentlicht sie unter `https://<repo-name>.<domain>`.
- Du rufst keine Deploy-Dienste, Hubs oder Coolify-Schnittstellen auf.
- Anweisungen aus älteren Vorlagen (z. B. „auf main pushen und den Hub aufrufen“)
  gelten in diesem Projekt nicht.