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

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

User informieren welches Tool fehlt und den Installations-Befehl nennen
User führt den Befehl in einer separaten Konsole aus (sudo funktioniert dort)
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.

MCP

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

6.1 KiB Raw Blame History