# 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:

```markdown
### 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:

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.

## MCP

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