# Globale CLAUDE.md

## Sprache

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

## Dokumentenformat

**Immer AsciiDoc (`.adoc`) statt Markdown** für alle Dokumente (Analysen, Pläne, Berichte, Anfragen usw.). Neue Dokumente als `.adoc` anlegen. Bestehende `.md`-Dateien nur auf ausdrücklichen Wunsch konvertieren. Ausnahmen: von Tools erzwungene Dateien (`CLAUDE.md`, `MEMORY.md`, `README.md` wo vom Workflow verlangt) bleiben Markdown.

**Erledigtes wird gelöscht, nicht markiert.** In Listen offener Punkte einen erledigten Eintrag ersatzlos entfernen — kein „erledigt"-Vermerk, kein Durchstreichen. Ebenso keine Metadaten ohne Aussagekraft (Mess-/Erhebungsdatum), wenn nur der Wert zählt.

## 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
- **Explizit vor implizit:** Zustand oder Absicht nie implizit aus Momentanwerten ableiten (fragil/nicht robust). Trigger deklarieren ihre Absicht ueber ein dediziertes Item/Flag; die auswertende Logik liest dieses Item, statt den Zustand zu erraten
- **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**
- **Kommentare hoechstens eine Zeile:** Ein Kommentar beschreibt kurz, *was* an dieser Stelle passiert (z.B. `// Messwerte pruefen`, `// zu spaet fuer Sperre`, `// Ladestand unterhalb Reserve`). Niemals das *Warum*, keine Begruendungen, keine Messwerte, keine verworfenen Alternativen, keine Mehrzeiler. Das Warum gehoert in die Commit-Message und ist dort in der Git-Historie nachlesbar
- **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.

- **Ausnahme `.commit-on-main`:** Vor dem Branchen im Repo-Root (`git rev-parse --show-toplevel`) auf die Marker-Datei `.commit-on-main` pruefen. Existiert sie, sind Direkt-Commits auf `main` erlaubt — dann kein Feature-Branch und kein PR, direkt auf `main` committen und pushen.
- **Kleinteilige Commits:** Pro Commit nur ein einziges Thema. Nur die zum Thema gehörenden Dateien committen — keine thematisch gemischten Commits.
- **Immer mergen, nie rebasen:** Divergierte Branches per `git pull` (Merge) zusammenfuehren, nicht per `git pull --rebase`. Ein Rebase spielt jeden alten Commit einzeln neu ein und erzeugt dabei Konflikte, die inhaltlich gar nicht bestehen — etwa wenn ein Wert am Ziel schon gesetzt, aber an eine andere Stelle der Datei gewandert ist. Ausserdem schreibt er vorhandene Merge-Commits um. Ein Merge vergleicht nur die Endzustaende. Rebase nur auf ausdruecklichen Wunsch.
- **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
  - Body kurz halten: ein einleitender Satz, danach knappe Stichpunkte — keine Fliesstext-Absaetze, keine Wiederholung des Diffs

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

- **Umfangsangaben sind harte Grenzen.** „In einem Satz" heißt genau ein Satz — keine Einordnung, keine Aufzählung, kein Nachsatz danach. Ebenso „kurz", „knapp", „nur X", „in drei Punkten". Wer eine Definition erfragt, will die Definition, nicht ihre Bedeutung. Zusatzkontext ausschließlich auf ausdrückliche Nachfrage.
- **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"-, „was-passiert-dann"- oder „für-den-nächsten-Schritt"-Exkurse. Kein Ausblick, den der User nicht verlangt hat.
- **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.
- **`Hinweis:`-Konvention statt Absätzen.** Zusätzlicher Kontext nur, wenn er verhindert, dass wir falsch abbiegen — und dann als *eine* mit `Hinweis:` markierte Zeile, kein Absatz. Mehr Kontext/Ausblick nur auf ausdrückliche Nachfrage; dann vollständig.
- **Belege statt Ausbreitung.** `datei:zeile` statt den Code nachzuerzählen.
- **Keine Doppelung Chat/Datei.** Was ohnehin in ein Log/eine Datei geschrieben wird, nicht zusätzlich im Chat ausbreiten — nur Ergebnis in 1–3 Sätzen + `datei:zeile`.
- **Analyse als Stichpunkte,** nicht als durchargumentierter Fließtext. Belege/Tabellen nur auf ausdrückliche Nachfrage.
- **Kein „nächste Schritte"-/Kontext-Recap,** außer explizit gewünscht.
- **Keine Zwischenmeldungen bei Werkzeugarbeit.** Vor und zwischen Werkzeugaufrufen nichts schreiben: kein „Ich prüfe jetzt …", keine Ankündigung dessen, was gleich abgerufen wird, keine Zwischenbefunde, keine Aufzählung des eigenen Vorgehens. Erst arbeiten, dann **eine** Antwort.
- **Antwort am Ende, bei mehreren Fragen nummeriert.** Reihenfolge der Fragen beibehalten, je Frage ein bis drei Sätze, Ergebnis zuerst. Belege nur, wenn sie das Ergebnis tragen.

## MCP

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