claude-workflow/dotfiles/CLAUDE.md

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.

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:

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

MCP

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