117 lines
6.8 KiB
Markdown
117 lines
6.8 KiB
Markdown
# 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.
|
||
|
||
## Antwort-Stil (Prägnanz)
|
||
|
||
Der User ist Informatiker/Techniker und will präzise Kommunikation mit den wesentlichen Fakten — nichts Ungefragtes.
|
||
|
||
- **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"-Exkurse. Höchstens *eine* knappe Schlusszeile als Angebot.
|
||
- **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.
|
||
- **Belege statt Ausbreitung.** `datei:zeile` statt den Code nachzuerzählen.
|
||
|
||
## MCP
|
||
|
||
Bei Frameworks/Bibliotheken immer Context-7-Dokumentation abrufen (resolve-library-id / query-docs).
|