claude-workflow/dotfiles/CLAUDE.md

Globale CLAUDE.md

Sprache

Alle Texte, Kommentare und Kommunikation auf Deutsch. Technische Begriffe und Code-Bezeichner bleiben im Original.

Entwicklungsprinzipien

• Single Responsibility: Jede Datei, jede Funktion hat genau eine Aufgabe
• Keine toten Code-Pfade: Unbenutzte Imports, Variablen, Funktionen sofort entfernen
• Aussagekraeftige Namen: Sprechende Bezeichner statt handleClick, process
• Keine Magic Numbers: Konstanten mit Namen versehen
• DRY mit Augenmass: Shared Utilities nur bei echtem Mehrfachgebrauch
• Fail Fast: Fehlende/ungueltige Konfiguration muss beim Start eine Exception werfen
• Keine generischen try/except: Spezifische Exceptions fangen
• Logging statt print: logger verwenden
• Testpflicht: Kein Code ohne zugehoerigen Test
• Security by Default: Input-Validierung, Auth-Checks, sichere Defaults. Sicherheitskritische Pfade durch Tests absichern
• String-Eingaben trimmen: Alle String-Felder beim Anlegen/Update in Services/Schemas trimmen (leading/trailing Whitespace entfernen). Leerstrings werden zu None, wenn das Feld optional ist. Verhindert Sortier-/Vergleichs-/Suchfehler durch unsichtbare Zeichen
• Kleine Funktionen, keine Kommentare fuer Offensichtliches
• Keine systemveraendernden Scripts zum Testen ausfuehren: Scripts die Symlinks, Berechtigungen, Pakete oder Konfiguration aendern niemals "einfach so" ausfuehren. Stattdessen mit bash -n (Syntax) oder gezieltem grep/cat pruefen

Code-Konventionen

• Backend: Ruff, Type Hints, async, Pydantic-Schemas, Lifespan statt on_event
• Frontend: <script setup>, ESLint+Prettier, Mobile First, defineEmits camelCase / Template kebab-case
• DB: Jede Schema-Aenderung braucht eine Alembic-Migration
• Architektur: api/ → services/ + models/, nie umgekehrt. HTTPException nur in api/. Eager-Loading in der API-Schicht. Frontend: Props down, Events up
• Docker Compose: Jeder Service: TZ=Europe/Berlin, Logging 5 MB (json-file, max-size: 5m, max-file: 3), Watchtower-Label default deaktiviert

Pläne

Jeder Teilplan unter plans/ muss eine ### Schnellstart-Sektion direkt unter der Hauptüberschrift enthalten:

### Schnellstart

- **Branch:** `feat/kurzer-name`
- **Zuerst lesen:** (max. 8 Dateien, nummeriert, wichtigste zuerst)
  1. `pfad/zur/datei.py`
- **Implementieren:** Teilplan X
- **Nächster Schritt:** Teilplan Y (Titel)

Die Sektion wird beim Erstellen des Plans geschrieben, nicht nachträglich. /implement nutzt sie als Einstiegspunkt.

Agenten-Workflow

Nach jeder Story automatisch ausfuehren: test-runner → security-audit. Erst wenn beide ohne kritische Befunde durchlaufen, gilt die Story als abgeschlossen.

Pull Requests

PRs muessen jedes Akzeptanzkriterium einzeln als Checkbox auflisten und bestaetigen, wie es verifiziert wurde. Review-Feedback als separater Commit (nicht amenden).

Git-Workflow

Niemals direkt auf main committen. Alle Aenderungen ueber Feature-Branches und PRs.

• Kleinteilige Commits: Pro Commit nur ein einziges Thema. Nur die zum Thema gehörenden Dateien committen — keine thematisch gemischten Commits.
• Commit-Messages: Conventional Commits, deutsche Beschreibung
  • Subject: <type>: <Beschreibung> — max 72 Zeichen, kein Punkt am Ende
  • Typen: feat, fix, docs, refactor, test, chore, perf, ci, build, style
  • Body optional, durch Leerzeile getrennt — erklaert das Warum, nicht das Was

Fehlende Tools

Sobald die saubere Lösung ein Standard-CLI-Tool braucht, das fehlt: STOPP. Zuerst die Installation vorschlagen und auf den User warten — bevor irgendeine Alternative gebaut wird. Eine fehlende Abhängigkeit ist ein Stopp-Signal, keine Designfrage. Der User installiert lieber ein Tool, als dass komplizierte Eigenlösungen entstehen.

Kein Ausweichen auf curl/rohe API-Calls, nachgebaute Login-Flows, HTML-/Token- Parsing oder mehrstufige Eigenkonstruktionen — auch nicht „nur kurz zum Testen". Solche Konstrukte gar nicht erst anfangen; das fehlende Tool ist immer der erste Lösungsweg.

1. User informieren welches Tool fehlt und den Installations-Befehl nennen
2. User führt den Befehl in einer separaten Konsole aus (sudo funktioniert dort)
3. Tool danach in bootstrap.sh aufnehmen, damit es auf allen Maschinen automatisch installiert wird

Gitea-Integration

• Instanz: https://gitea.troeger-net.org
• Bot-User claude-code, nur Collaborator-Rechte
• Token: ~/.config/gitea/token (Datei mit chmod 600)
• MCP-Server gitea muss aktiv sein (Binary: ~/go/bin/gitea-mcp, Wrapper: ~/.claude/gitea-mcp-wrapper.sh)

Wissen persistieren

Bei User-Korrekturen oder neuen Erkenntnissen zuerst klassifizieren, dann am richtigen Ort ablegen:

Art der Information	Ziel	Beispiel
Arbeitsregel für ein Repo	CLAUDE.md im Repo	"Keine Default-Werte in Configs"
Arbeitsregel für alle Repos	Globale CLAUDE.md	"Logging statt print"
Workaround für einen Bug	WORKAROUNDS.md im Repo, Verweis aus CLAUDE.md	"Log auf OFF wegen Bug X"
User-Profil, Rolle, Präferenzen	Memory (user-Typ)	"Bevorzugt knappe Antworten"
Projektstatus, Deadlines, Entscheidungen	Memory (project-Typ)	"Merge-Freeze ab 05.03."
Externe Referenzen	Memory (reference-Typ)	"Bugs in Linear INGEST"

Niemals Arbeitsregeln im Memory-System ablegen. Memory ist für Kontext, nicht für Regeln. Wenn eine User-Korrektur eine wiederkehrende Arbeitsregel beschreibt → CLAUDE.md. Immer.

Erläuterungs-Stil

Wenn der User um eine Erklärung auf architektonischer, logischer, konzeptioneller, abstrakter oder prinzipieller Ebene bittet (oder Varianten wie "vom Konzept her", "rein architektonisch"):

• Den Mechanismus der zugrundeliegenden Technik in Fachsprache erklären (Framework-Konzepte, Lifecycle, Semantik) — keine Alltagsmetaphern (Bibliothekar, Postbote, Restaurant).
• Das Prinzip generisch darlegen, nicht am konkreten Code festmachen. Am Ende kurz auf die Anwendung im Projekt zurückbeziehen.
• Technische Begriffe (z.B. "detached entity", "managed", "flush", "snapshot", "dirty check") frei verwenden, kurz einführen falls neu im Kontext, aber nicht durch Umschreibungen ersetzen.

Im Zweifel lieber technischer als metaphorischer. Der User hat solides Fachwissen über die Domäne (z.B. relationale Datenbanken, HTTP, Linux) und möchte framework-/tool-spezifische Konzepte tatsächlich verstehen, nicht durch Metaphern davor abgeschirmt werden.

Antwort-Stil (Prägnanz)

Der User ist Informatiker/Techniker und will präzise Kommunikation mit den wesentlichen Fakten — nichts Ungefragtes.

• Antwort zuerst, keine Herleitung. Ergebnis in 1–3 Sätzen; den Weg dahin nur auf Nachfrage.
• Nur das Gefragte. Keine ungefragten Optionen, Empfehlungen, Mockups, „wo es hakt"-Exkurse. Höchstens eine knappe Schlusszeile als Angebot.
• Umfang an die konkrete Frage koppeln. „Kann man X?" → ja/nein + Grund. Ein Artefakt (Diagramm, Tabelle, Umbau) nur liefern, wenn es explizit verlangt wurde — dann aber vollständig und nicht um ungefragte Zusätze erweitert.
• Belege statt Ausbreitung. datei:zeile statt den Code nachzuerzählen.

MCP

Bei Frameworks/Bibliotheken immer Context-7-Dokumentation abrufen (resolve-library-id / query-docs).