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.