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

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

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.

Fehlende Tools

Wenn ein benötigtes CLI-Tool fehlt: nicht mit Workarounds (curl, rohe API-Calls) umgehen. Stattdessen:

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, Token: ~/.config/gitea/token (Datei mit chmod 600). Bot hat nur Collaborator-Rechte.

MCP

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