From a536d357431c62726a7916584106c398ea767692 Mon Sep 17 00:00:00 2001 From: root Date: Tue, 27 Jan 2026 13:00:30 +0100 Subject: [PATCH] Infrastruktur-Dokumentation: Neue Kunden-Organisation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CLAUDE.md: Host-Troubleshooting → Infrastruktur-Dokumentationssystem - session-start.sh: Erkennt ~/Nextcloud/[kunde]/[repo]/ Struktur - Legacy-Support für ~/Nextcloud/hosts/ mit Migrations-Hinweis Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 114 +++++---- hooks/session-start.sh | 97 +++++--- plans/elegant-zooming-porcupine.md | 373 +++++++++++++++++++++++++++++ plans/quirky-snacking-bunny.md | 269 +++++++++++++++++++++ 4 files changed, 772 insertions(+), 81 deletions(-) create mode 100644 plans/elegant-zooming-porcupine.md create mode 100644 plans/quirky-snacking-bunny.md diff --git a/CLAUDE.md b/CLAUDE.md index 39e5140..207b463 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -229,74 +229,104 @@ This upfront investment minimizes questions in future sessions and enables faste --- -## Host Troubleshooting +## Infrastruktur-Dokumentationssystem -### Automatische Host-Setup (Hook-gesteuert) +### Organisation pro Kunde -Der Session-Start Hook erkennt automatisch Host-Verzeichnisse unter `~/Nextcloud/hosts/`. +Gitea-Struktur: +``` +├── Vinos/ ← Organisation für Kunde "vinos" +│ ├── infrastructure.git ← Landkarte für vinos +│ ├── zabbix.git ← System-Repo +│ └── [weitere].git ← Dienst-/System-Repos +│ +└── Egonetix/ ← Organisation für Kunde "egonetix" + ├── infrastructure.git ← Landkarte für egonetix + └── [weitere].git +``` -**Wenn du `` in der Hook-Ausgabe siehst:** +Lokale Struktur: +``` +~/Nextcloud/ +├── vinos/ ← Kunde vinos +│ ├── infrastructure/ ← Landkarte (dependencies.md, hosts/) +│ ├── zabbix/ ← System-Repo +│ └── [weitere]/ ← Dienst-/System-Repos +│ +└── egonetix/ ← Kunde egonetix + ├── infrastructure/ + └── [weitere]/ +``` + +### Repo-Typen + +| Repo-Typ | Gitea-Ort | Inhalt | +|----------|-----------|--------| +| **Infrastructure** | `[Kunde]/infrastructure.git` | Landkarte, Abhängigkeiten, Host-Übersichten | +| **System-Repo** | `[Kunde]/[system].git` | README, Konfig-Dateien, Troubleshooting | +| **Dienst-Repo** | `[Kunde]/[dienst].git` | docker-compose.yml, Code, Workflows | + +### Automatische Erkennung (Hook-gesteuert) + +Der Session-Start Hook erkennt Kunden-Verzeichnisse unter `~/Nextcloud/[kunde]/`. + +**Wenn du `` in der Hook-Ausgabe siehst:** 1. **Frage den User:** - > "Ich habe erkannt, dass für diesen Host noch Setup erforderlich ist. Soll ich das automatisch durchführen?" - > - Git-Repository initialisieren (falls fehlend) - > - Template für Dokumentation kopieren (falls fehlend) + > "Ich habe erkannt, dass für dieses Repo noch Setup erforderlich ist. Soll ich das automatisch durchführen?" 2. **Bei Zustimmung - führe alle fehlenden Schritte aus:** ```bash # Git initialisieren (falls nicht vorhanden) git init + git branch -M main - # Template kopieren (falls nicht vorhanden) - cp ~/Nextcloud/hosts/_templates/copilot-instructions-template.md ./copilot-instructions.md + # Template aus infrastructure/_templates/ kopieren ``` -3. **Dann interaktiv ausfüllen:** - - Frage nach den wichtigsten Infos (IP, Typ, Funktion, Zugang) - - Ersetze die Platzhalter im Template - - Lösche den Template-Hinweis-Block am Anfang - -4. **Initial Commit erstellen:** +3. **Repo auf Gitea erstellen (API):** ```bash - git add copilot-instructions.md - git commit -m "Initial: Host-Dokumentation angelegt" + curl -X POST -H "Authorization: token $GITEA_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{"name":"repo-name","description":"..."}' \ + https://gitea.egonetix.de/api/v1/orgs/[Kunde]/repos ``` -### Automatische Erkennung +4. **Remote hinzufügen und pushen:** + ```bash + git remote add origin ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git + git push -u origin main + ``` -Wenn du in einem Verzeichnis unter `~/Nextcloud/hosts/` arbeitest: - -1. **Lade die lokale Dokumentation** - - Lies `copilot-instructions.md` falls vorhanden - - Verstehe den System-Typ und Kontext - -2. **Bei Troubleshooting-Aufgaben** - - Nutze den Skill `/troubleshoot-host` für strukturiertes Vorgehen - - Dokumentiere Lösungen in der `copilot-instructions.md` - -### Verzeichnisstruktur +### Gitea Remote-Konfiguration +**URL-Format:** ``` -~/Nextcloud/hosts/ -├── [kunde]/ # z.B. vinos, egonetix -│ └── [hostname]/ # z.B. srv-monitor02, srv-db12 -│ └── copilot-instructions.md -└── _templates/ - └── copilot-instructions-template.md # Master-Template +ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git ``` -### Workflow: Neuen Host anlegen +**Beispiele:** +| Kunde | Repo | Remote URL | +|-------|------|------------| +| Vinos | infrastructure | `ssh://git@gitea.egonetix.de:222/Vinos/infrastructure.git` | +| Vinos | zabbix | `ssh://git@gitea.egonetix.de:222/Vinos/zabbix.git` | +| Egonetix | infrastructure | `ssh://git@gitea.egonetix.de:222/Egonetix/infrastructure.git` | + +**Wichtig:** Das Repo muss auf Gitea ZUERST erstellt werden (API oder Web-UI). + +### Workflow: Neues System-/Dienst-Repo anlegen -Der User legt nur den Ordner an: ```bash -mkdir -p ~/Nextcloud/hosts/[kunde]/[hostname] -cd ~/Nextcloud/hosts/[kunde]/[hostname] -claude # Startet Claude Code +cd ~/Nextcloud/[kunde] +git init [repo-name] +cd [repo-name] +# Template aus ../infrastructure/_templates/ kopieren +# Repo auf Gitea erstellen +# git remote add origin ... +# git push -u origin main ``` -Claude erkennt automatisch das fehlende Template und bietet Setup an. - ### Skills-Referenz | Skill | Zweck | diff --git a/hooks/session-start.sh b/hooks/session-start.sh index bfbc89e..73199c1 100755 --- a/hooks/session-start.sh +++ b/hooks/session-start.sh @@ -21,57 +21,76 @@ if [ -d "$REPO_DIR/.git" ]; then fi fi -# === TEIL 2: Host-Verzeichnis Erkennung === +# === TEIL 2: Kunden-/Repo-Verzeichnis Erkennung === cd "$ORIGINAL_DIR" 2>/dev/null || exit 0 +# Bekannte Kunden-Verzeichnisse +KUNDEN_BASE="$HOME/Nextcloud" +KNOWN_KUNDEN="vinos egonetix" + +# Prüfe ob wir in einem Kunden-Verzeichnis sind (~/Nextcloud/[kunde]/[repo]/) +for KUNDE in $KNOWN_KUNDEN; do + KUNDE_PATH="$KUNDEN_BASE/$KUNDE" + if [[ "$ORIGINAL_DIR" == "$KUNDE_PATH"/* ]]; then + # Extrahiere Repo-Name + REL_PATH="${ORIGINAL_DIR#$KUNDE_PATH/}" + REPO_NAME=$(echo "$REL_PATH" | cut -d'/' -f1) + + if [[ -n "$REPO_NAME" ]]; then + echo "=== KUNDEN-REPO ERKANNT ===" + echo "Kunde: $KUNDE" + echo "Repo: $REPO_NAME" + echo "" + + # Prüfe ob README.md vorhanden + if [[ -f "README.md" ]]; then + echo "README.md vorhanden - lies sie für Kontext." + elif [[ -f "copilot-instructions.md" ]]; then + echo "copilot-instructions.md vorhanden - lies sie für Kontext." + else + # Prüfe auf Setup-Anforderungen + NEEDS_SETUP=false + NEEDS_GIT=false + + if [[ ! -d ".git" ]]; then + NEEDS_GIT=true + NEEDS_SETUP=true + fi + + if [[ "$NEEDS_SETUP" == "true" ]]; then + echo "" + if [[ "$NEEDS_GIT" == "true" ]]; then + echo "- Kein Git-Repository vorhanden → git init erforderlich" + fi + echo "- Keine README.md vorhanden" + echo " Template: $KUNDEN_BASE/$KUNDE/infrastructure/_templates/" + echo "" + echo "Frage den User ob das Setup automatisch durchgeführt werden soll." + echo "" + fi + fi + echo "" + fi + break + fi +done + +# Legacy: Prüfe auch ~/Nextcloud/hosts/ für Übergangszeit HOSTS_BASE="$HOME/Nextcloud/hosts" -TEMPLATE_PATH="$HOSTS_BASE/_templates/copilot-instructions-template.md" - -# Prüfe ob wir in einem Host-Verzeichnis sind (~/Nextcloud/hosts/[kunde]/[hostname]/) if [[ "$ORIGINAL_DIR" == "$HOSTS_BASE"/* ]]; then - # Extrahiere relativen Pfad REL_PATH="${ORIGINAL_DIR#$HOSTS_BASE/}" - - # Prüfe ob es ein Host-Verzeichnis ist (mindestens 2 Ebenen tief, nicht _templates) if [[ "$REL_PATH" == *"/"* ]] && [[ "$REL_PATH" != "_templates"* ]]; then KUNDE=$(echo "$REL_PATH" | cut -d'/' -f1) HOSTNAME=$(echo "$REL_PATH" | cut -d'/' -f2) - if [[ -n "$KUNDE" ]] && [[ -n "$HOSTNAME" ]]; then - echo "=== HOST-VERZEICHNIS ERKANNT ===" + echo "=== LEGACY HOST-VERZEICHNIS ERKANNT ===" echo "Kunde: $KUNDE" echo "Host: $HOSTNAME" echo "" - - # Sammle Setup-Anforderungen - NEEDS_SETUP=false - NEEDS_GIT=false - NEEDS_TEMPLATE=false - - if [[ ! -d ".git" ]]; then - NEEDS_GIT=true - NEEDS_SETUP=true - fi - - if [[ ! -f "copilot-instructions.md" ]]; then - NEEDS_TEMPLATE=true - NEEDS_SETUP=true - fi - - if [[ "$NEEDS_SETUP" == "true" ]]; then - echo "" - if [[ "$NEEDS_GIT" == "true" ]]; then - echo "- Kein Git-Repository vorhanden → git init erforderlich" - fi - if [[ "$NEEDS_TEMPLATE" == "true" ]]; then - echo "- Keine copilot-instructions.md → Template kopieren" - echo " Template: $TEMPLATE_PATH" - fi - echo "" - echo "Frage den User ob das Setup automatisch durchgeführt werden soll." - echo "" - echo "" - else + echo "HINWEIS: Die Host-Struktur wurde migriert zu ~/Nextcloud/[kunde]/[repo]/" + echo "Dieses Verzeichnis sollte nach ~/Nextcloud/$KUNDE/ migriert werden." + echo "" + if [[ -f "copilot-instructions.md" ]]; then echo "copilot-instructions.md vorhanden - lies sie für Kontext." echo "" fi diff --git a/plans/elegant-zooming-porcupine.md b/plans/elegant-zooming-porcupine.md new file mode 100644 index 0000000..8d53eb7 --- /dev/null +++ b/plans/elegant-zooming-porcupine.md @@ -0,0 +1,373 @@ +# Plan: Infrastruktur-Dokumentationssystem + +## Ziel + +Ein wachsendes Dokumentationssystem das: +1. **Alle Verbindungen** zwischen Diensten, Hosts und Hardware aufzeigt +2. **Impact-Analyse** ermöglicht ("Was geht kaputt wenn ich X ändere?") +3. **Änderungshistorie** bietet (Git-Log = Changelog) +4. **Troubleshooting** unterstützt + +--- + +## Architektur: Organisation pro Kunde + +``` +Gitea-Struktur: +├── vinos/ ← Organisation für Kunde "vinos" +│ ├── infrastructure.git ← Landkarte für vinos +│ ├── zabbix.git ← System-Repo +│ ├── pmg-mailgw.git ← System-Repo +│ └── n8n.git ← Dienst-Repo +│ +└── egonetix/ ← Organisation für Kunde "egonetix" + ├── infrastructure.git ← Landkarte für egonetix + ├── pfsense.git + └── traefik.git +``` + +``` +Lokal: +~/Nextcloud/ +├── vinos/ ← Kunde vinos +│ ├── infrastructure/ ← Landkarte +│ ├── zabbix/ ← System-Repo +│ ├── pmg-mailgw/ ← System-Repo +│ └── n8n/ ← Dienst-Repo +│ +└── egonetix/ ← Kunde egonetix + ├── infrastructure/ + ├── pfsense/ + └── traefik/ +``` + +| Repo-Typ | Gitea-Ort | Inhalt | +|----------|-----------|--------| +| **Infrastructure** | `[kunde]/infrastructure.git` | Landkarte, Abhängigkeiten für diesen Kunden | +| **System-Repo** | `[kunde]/[system].git` | Konfig-Dateien, README, Troubleshooting | +| **Dienst-Repo** | `[kunde]/[dienst].git` | docker-compose.yml, Code, Workflows | + +**Vorteile:** +- Klare Kunden-Trennung +- Jeder Kunde hat eigene Infrastruktur-Doku +- Repos sind nach Kunde gruppiert auf Gitea +- Zugriffsrechte pro Organisation möglich + +--- + +## 1. Infrastructure-Repo (NEU) - SCHLANK + +**Speicherort:** `~/Nextcloud/infrastructure/` → `ssh://git@gitea.egonetix.de:222/root/infrastructure.git` + +**Prinzip:** Nur Landkarte und Links - KEINE Konfig-Dateien! + +``` +infrastructure/ +├── README.md ← Einstieg + Gesamtübersicht +├── hosts/ +│ ├── srvdocker02.md ← Übersicht + Links zu Dienst-Repos +│ ├── srv-monitor02.md ← Übersicht + Link zu systems/zabbix.git +│ └── pmg01.md ← Übersicht + Link zu systems/pmg-mailgw.git +├── netzwerk/ +│ ├── vlans.md +│ └── dns.md +├── hardware/ +│ ├── switches.md +│ ├── firewalls.md +│ └── storage.md +└── dependencies.md ← HERZSTÜCK: Mermaid-Diagramme +``` + +**Beispiel hosts/pmg01.md:** +```markdown +# PMG01 - Proxmox Mail Gateway + +| IP | Funktion | Repo | +|----|----------|------| +| 10.0.0.50 | Mail-Gateway | [systems/pmg-mailgw](https://gitea.egonetix.de/systems/pmg-mailgw) | + +## Abhängigkeiten +- **Betrifft:** mailsrv1, mailsrv2 +- **Benötigt:** DNS, Internet + +→ Details und Konfig: siehe [Repo](https://gitea.egonetix.de/systems/pmg-mailgw) +``` + +### dependencies.md Beispiel: + +```markdown +# Abhängigkeiten + +## Mail-System +​```mermaid +graph LR + Internet --> pmg01[PMG Mailgateway] + pmg01 --> mailsrv1[Mailserver 1] + pmg01 --> mailsrv2[Mailserver 2] + mailsrv1 --> storage[(NAS01)] + mailsrv2 --> storage +​``` + +**Impact:** Änderung an PMG betrifft beide Mailserver! + +## Monitoring +​```mermaid +graph TD + zabbix[Zabbix] -.überwacht.-> pmg01 + zabbix -.überwacht.-> srvdocker02 + zabbix -.überwacht.-> pfsense + zabbix --> postgres[(PostgreSQL)] +​``` +``` + +--- + +## 2. Dienst-Repos (Docker) - BEHALTEN + +**Beispiel:** n8n, trading-bot, traefik + +**Struktur:** +``` +n8n/ +├── docker-compose.yml +├── Dockerfile (optional) +├── .env.example +├── README.md ← Deployment, Zugang, Quick Reference +├── scripts/ +└── config/ +``` + +**Git-Log = Changelog:** +``` +a3f2b1c Webhook-URL geändert (betrifft: Telegram-Bot) +e7d4a9f PostgreSQL auf Version 15 aktualisiert +``` + +--- + +## 3. System-Repos (Appliances/VMs) - NEU + +**Für:** PMG, pfSense, Mailserver, Zabbix-Server, etc. + +**Struktur:** +``` +pmg-mailgw/ +├── README.md ← Zugang, IP, Quick Reference +├── config/ ← Konfig-Dateien direkt (Git = Backup!) +│ ├── cluster.conf +│ ├── relay_domains +│ └── main.cf +├── dependencies.md ← "betrifft: mailsrv1, mailsrv2" +└── troubleshooting.md ← Bekannte Probleme & Lösungen +``` + +**Workflow bei Änderungen:** +1. Änderung am System durchführen +2. Konfig-Dateien ins Repo kopieren +3. `git commit -m "Relay-Domain hinzugefügt (betrifft: mailsrv1, mailsrv2)"` +4. Bei Problem: `git log` → sofort sichtbar was sich geändert hat + +--- + +## Was wird aus dem bisherigen Setup? + +| Alt | Neu | +|-----|-----| +| `~/Nextcloud/hosts/` | → `~/Nextcloud/infrastructure/` | +| `~/Nextcloud/hosts/_templates/` | → Templates pro Repo-Typ | +| Host-Repos (vinos_srv-monitor02) | → System-Repos oder nur im Infrastructure-Repo | +| Dienst-Repos (n8n) | Bleiben wie sie sind | + +--- + +## Dateien zu erstellen/ändern + +### Schritt 1: Gitea-Organisationen anlegen + +``` +https://gitea.egonetix.de/org/create +- "vinos" anlegen +- "egonetix" anlegen +``` + +### Schritt 2: Lokale Verzeichnisstruktur + +```bash +mkdir -p ~/Nextcloud/vinos +mkdir -p ~/Nextcloud/egonetix +``` + +### Schritt 3: Infrastructure-Repo für vinos + +```bash +cd ~/Nextcloud/vinos +git init infrastructure +cd infrastructure +``` + +| Datei | Beschreibung | +|-------|--------------| +| `README.md` | Einstiegspunkt für vinos | +| `dependencies.md` | Mermaid-Diagramme (Mail-System, Monitoring, etc.) | +| `hosts/` | Host-Übersichten (kurz, mit Links zu Repos) | +| `netzwerk/` | VLANs, DNS, Firewall-Regeln | +| `hardware/` | Switches, Storage, Server-Hardware | +| `_templates/` | Templates für neue Hosts/Systeme | + +Remote: `ssh://git@gitea.egonetix.de:222/vinos/infrastructure.git` + +### Schritt 4: Zabbix System-Repo (Migration) + +```bash +cd ~/Nextcloud/vinos +git init zabbix +cd zabbix +``` + +| Datei | Beschreibung | +|-------|--------------| +| `README.md` | Zugang, Quick Reference (migriert von srv-monitor02) | +| `config/` | Relevante Konfig-Dateien | +| `troubleshooting.md` | Bekannte Probleme & Lösungen | +| `dependencies.md` | "Überwacht: alle Hosts" | + +Remote: `ssh://git@gitea.egonetix.de:222/vinos/zabbix.git` + +### Schritt 5: Claude-Settings aktualisieren + +| Datei | Änderung | +|-------|----------| +| `~/.claude/CLAUDE.md` | Neue Struktur mit Kunden-Organisationen | +| `session-start.sh` Hook | `~/Nextcloud/[kunde]/` erkennen | +| `troubleshoot.md` Skill | Anpassen auf neue Struktur | +| NEU: `new-repo.md` Skill | Neues System-/Dienst-Repo für Kunden anlegen | + +### Schritt 6: Aufräumen + +| Datei | Aktion | +|-------|--------| +| `~/Nextcloud/hosts/` | Löschen nach Migration | +| `root/vinos_srv-monitor02.git` | Optional: Archivieren (kann auch bleiben) | + +**Nicht jetzt:** Bestehende Repos (n8n, etc.) bleiben unter `root/` - Migration zu egonetix später + +--- + +## Templates + +### Template: Dienst (Docker) + +```markdown +# [DIENST-NAME] + +## Quick Start +​```bash +docker-compose up -d +​``` + +## Zugang +- URL: https://[domain] +- Port: [port] + +## Abhängigkeiten +- Benötigt: [PostgreSQL, Redis, etc.] +- Wird genutzt von: [andere Dienste] + +## Konfiguration +[Wichtige Umgebungsvariablen, Volumes] + +## Troubleshooting +[Häufige Probleme] +``` + +### Template: System (Appliance/VM) + +```markdown +# [SYSTEM-NAME] + +## System Overview +| Eigenschaft | Wert | +|-------------|------| +| **Host** | [hostname] | +| **IP** | [ip] | +| **Typ** | [Proxmox/VMware/Bare-Metal] | +| **OS** | [Debian/FreeBSD/etc.] | +| **Zugang** | [SSH/Web-UI] | + +## Abhängigkeiten +**Dieses System betrifft:** +- [system1] +- [system2] + +**Dieses System benötigt:** +- [dependency1] + +## Konfig-Dateien +| Datei | Beschreibung | +|-------|--------------| +| config/[file] | [was es tut] | + +## Wichtige Befehle +​```bash +# [Beschreibung] +[befehl] +​``` + +## Troubleshooting +[Bekannte Probleme & Lösungen] +``` + +--- + +## Verifikation + +1. [ ] Gitea-Organisation "vinos" existiert +2. [ ] `vinos/infrastructure.git` angelegt und gepusht +3. [ ] `vinos/zabbix.git` angelegt (Inhalt von srv-monitor02) +4. [ ] Mindestens ein Mermaid-Diagramm in `vinos/infrastructure/dependencies.md` +5. [ ] Claude in `~/Nextcloud/vinos/zabbix/` starten → Lädt README +6. [ ] `~/Nextcloud/hosts/` gelöscht +7. [ ] CLAUDE.md und Hooks aktualisiert für neue Struktur + +**Später:** egonetix Organisation + Migration bestehender Repos + +--- + +## Entscheidungen (geklärt) + +| Frage | Entscheidung | +|-------|--------------| +| Kunden-Trennung | Organisation pro Kunde (`vinos/`, `egonetix/`) | +| Infrastructure-Repo | Schlank - nur Landkarte, keine Configs (pro Kunde) | +| Namenskonvention | `[kunde]/[name].git` (z.B. `vinos/zabbix.git`) | +| srv-monitor02 | Migrieren → `vinos/zabbix.git` | +| Hardware | Im jeweiligen Kunden-Infrastructure-Repo | + +--- + +## Migration + +### Jetzt: + +1. **Gitea-Organisationen anlegen** + - `vinos` Organisation erstellen + - `egonetix` Organisation erstellen (für später) + +2. **vinos Infrastructure-Repo anlegen** + - Neues Repo: `vinos/infrastructure.git` + - Basis-Struktur mit hosts/, dependencies.md, etc. + +3. **vinos/zabbix.git anlegen** (migriert von srv-monitor02) + - Inhalt von `vinos_srv-monitor02` übernehmen + - Altes Repo kann bleiben oder archiviert werden + +4. **Lokale Struktur** + - `~/Nextcloud/vinos/infrastructure/` + - `~/Nextcloud/vinos/zabbix/` + - `~/Nextcloud/hosts/` entfernen + +### Später (nicht Teil dieses Plans): + +- Bestehende Repos unter `root/` (n8n, etc.) → gehören zu egonetix +- Migration in `egonetix/` Organisation wenn Zeit ist +- Diese Repos bleiben erstmal wo sie sind diff --git a/plans/quirky-snacking-bunny.md b/plans/quirky-snacking-bunny.md new file mode 100644 index 0000000..330dcba --- /dev/null +++ b/plans/quirky-snacking-bunny.md @@ -0,0 +1,269 @@ +# Workflow-Plan: Multi-Machine Development Tracking + +## Problem +- 4+ Maschinen mit verschiedenen Projekten +- Verliert Überblick "Wo war ich? Was war der Stand?" +- Gitea = Haupt-Tracking (gitea.egonetix.de:222) + +## Inspiriert von Boris Cherny (Claude Code Creator) + +Quelle: [YouTube Video](https://www.youtube.com/watch?v=B-UXpneKw6M) | [Medium Summary](https://medium.com/@joe.njenga/boris-cherny-claude-code-creator-shares-these-22-tips-youre-probably-using-it-wrong-1b570aedefbe) + +**Key Takeaways eingebaut:** +1. **Learnings dokumentieren** → WORKLOG.md enthält "Learnings" Sektion für Fehler/Erkenntnisse +2. **Plan Mode First** → `/session-start` aktiviert Plan Mode für strukturierte Arbeit +3. **Verification Loops** → Skills enthalten Verifikationsschritte +4. **Separate Checkouts** → Doku für parallele Sessions auf gleicher Maschine + +--- + +## Lösung: "Session Context" Workflow mit Gitea + +### Kernprinzip +Jedes Projekt hat eine **WORKLOG.md** die: +- Bei Session-Start automatisch angezeigt wird +- Den aktuellen Stand + nächste Schritte + Entscheidungen dokumentiert +- Mit Gitea Issues verlinkt ist +- Bei Session-Ende aktualisiert und committet wird + +--- + +## Komponenten + +### 1. WORKLOG.md pro Projekt + +```markdown +# Worklog: [Projektname] + +## Current State +**Zuletzt:** 2025-01-26 auf `n2095` (Desktop) +**Branch:** feature/new-thing +**Issue:** [#42 - API Implementation](https://gitea.egonetix.de/user/repo/issues/42) +**Status:** In Progress - API fertig, Frontend fehlt + +## Next Steps +- [ ] Frontend-Komponente für User-Liste +- [ ] Tests für API-Endpoints +- [ ] Dokumentation aktualisieren + +## Key Decisions +- **2025-01-26:** REST statt GraphQL wegen einfacherer Integration +- **2025-01-25:** PostgreSQL statt SQLite für Multi-User + +## Learnings (für Claude) + +- **2025-01-26:** API-Routen MÜSSEN mit /api/ prefix beginnen, sonst Konflikt mit Frontend-Routes +- **2025-01-25:** TypeScript strict mode aktivieren BEVOR Code geschrieben wird + +## Session History +### 2025-01-26 | n2095 | Commits: `a3f2b1c`, `e7d4a9f` +- API-Endpoints implementiert +- Database-Schema angepasst +- Issue #42 kommentiert + +### 2025-01-25 | laptop | Commits: `b2c3d4e` +- Projekt-Setup +- Erste Analyse +``` + +### 2. Tea CLI für Gitea + +Installation und Konfiguration der offiziellen Gitea CLI: + +```bash +# Installation +sudo curl -fsSL https://dl.gitea.io/tea/0.9.2/tea-0.9.2-linux-amd64 -o /usr/local/bin/tea +sudo chmod +x /usr/local/bin/tea + +# Login (einmalig pro Maschine) +tea login add --url https://gitea.egonetix.de --token +``` + +Ermöglicht: +- `tea issues` - Issues auflisten +- `tea issues create` - Issue erstellen +- `tea comment` - Issue kommentieren +- `tea pr` - Pull Requests + +### 3. Session-Start Hook + +`~/dotfiles/claude_settings/hooks/session-start.sh` (erweitert): + +```bash +#!/bin/bash +# Zeigt WORKLOG.md wenn vorhanden +if [[ -f "WORKLOG.md" ]]; then + echo "=== PROJECT CONTEXT ===" + # Zeige Current State und Next Steps + sed -n '/## Current State/,/## Next Steps/p' WORKLOG.md + sed -n '/## Next Steps/,/## Key Decisions/p' WORKLOG.md | head -10 + echo "" + + # Letzte 3 Commits + echo "=== RECENT COMMITS ===" + git log --oneline -3 2>/dev/null + echo "" + + # Gitea Issues (wenn tea konfiguriert) + if command -v tea &>/dev/null; then + echo "=== OPEN ISSUES ===" + tea issues --state open --limit 5 2>/dev/null || echo "(Gitea nicht erreichbar)" + fi +fi +``` + +### 4. Skill: `/session-end` + +Strukturiertes Session-Ende: + +1. Sammelt aus Konversation was gemacht wurde +2. Fragt nach nächsten Schritten +3. Fragt nach wichtigen Entscheidungen +4. Updated WORKLOG.md: + - Current State + - Next Steps + - Neuer Session History Eintrag +5. Committet WORKLOG.md +6. Optional: Kommentiert verknüpftes Gitea Issue + +### 5. Skill: `/session-start` (manuell) + +Für expliziten Session-Start: +1. Zeigt WORKLOG.md Kontext +2. Zeigt offene Gitea Issues +3. Fragt "Woran willst du arbeiten?" +4. Aktualisiert "Current State" in WORKLOG.md + +### 6. Skill: `/new-project` + +Für neue Projekte: +1. `git init` wenn nötig +2. Erstellt WORKLOG.md aus Template +3. Erstellt copilot-instructions.md aus Template +4. Optional: Erstellt Gitea Issue für das Projekt +5. Initial Commit + +--- + +## Implementation Steps + +### Phase 1: Grundlagen +| # | Was | Dateien | +|---|-----|---------| +| 1 | Tea CLI installieren | System | +| 2 | Tea Login konfigurieren | `~/.config/tea/config.yml` | +| 3 | WORKLOG.md Template erstellen | `~/dotfiles/claude_settings/templates/WORKLOG.md` | +| 4 | Session-Start Hook erweitern | `~/dotfiles/claude_settings/hooks/session-start.sh` | + +### Phase 2: Skills +| # | Was | Dateien | +|---|-----|---------| +| 5 | Skill `/session-end` erstellen | `~/dotfiles/claude_settings/skills/session-end.md` | +| 6 | Skill `/session-start` erstellen | `~/dotfiles/claude_settings/skills/session-start.md` | +| 7 | Skill `/new-project` erstellen | `~/dotfiles/claude_settings/skills/new-project.md` | + +### Phase 3: Rollout +| # | Was | +|---|-----| +| 8 | WORKLOG.md für 2-3 aktive Projekte anlegen | +| 9 | Workflow auf anderen Maschinen einrichten (Settings-Repo pullen) | + +--- + +## Beispiel-Workflow + +``` +=== MONTAG, DESKTOP === + +$ cd ~/projects/smart-home +$ claude + +[Hook Output:] +=== PROJECT CONTEXT === +**Zuletzt:** 2025-01-24 auf laptop +**Issue:** #12 - MQTT Integration +**Status:** MQTT-Subscription halb fertig + +## Next Steps +- [ ] Sensor-Subscriptions implementieren +- [ ] Error-Handling + +=== RECENT COMMITS === +a3f2b1c MQTT: Basic connection working +b2c3d4e Initial MQTT setup + +=== OPEN ISSUES === +#12 MQTT Integration (in progress) +#15 Add temperature dashboard + +Du: "weiter mit den subscriptions" +... arbeiten ... + +Du: "/session-end" + +Claude: Ich sehe du hast heute: +- Sensor-Subscriptions implementiert (commits e7d4a9f, f8g9h0i) +- Error-Handling hinzugefügt + +Was sind die nächsten Schritte? + +Du: "tests und dann das dashboard aus issue 15" + +Claude: Wichtige Entscheidungen heute? + +Du: "ja, wir nutzen QoS level 1 für reliability" + +[WORKLOG.md wird aktualisiert] +[Commit: "worklog: session 2025-01-27"] +[Issue #12 kommentiert: "Progress: Subscriptions + Error handling done"] +``` + +--- + +## Bonus: Parallele Sessions (Boris Cherny Style) + +Wenn du mehrere Claude-Sessions auf EINER Maschine für das GLEICHE Projekt brauchst: + +```bash +# Separate Checkouts statt Branches/Worktrees +cd ~/projects +git clone git@gitea.egonetix.de:user/repo.git repo-session1 +git clone git@gitea.egonetix.de:user/repo.git repo-session2 + +# Jede Session in eigenem Checkout +# Terminal 1: cd ~/projects/repo-session1 && claude +# Terminal 2: cd ~/projects/repo-session2 && claude +``` + +Vorteile: +- Keine Merge-Konflikte während der Arbeit +- Volle Isolation +- Am Ende: Cherry-Pick oder PR mergen + +--- + +## Verification + +Nach Implementation testen: + +1. **Tea CLI:** `tea issues` in einem Gitea-Repo ausführen +2. **Hook:** Neues Terminal in Projekt mit WORKLOG.md öffnen → Kontext wird angezeigt +3. **Skills:** `/session-end` ausführen → WORKLOG.md wird korrekt aktualisiert +4. **Cross-Machine:** Settings auf anderer Maschine pullen, gleicher Workflow funktioniert +5. **Learnings Test:** Füge einen Fehler zu Learnings hinzu, starte neue Session → Claude sollte ihn berücksichtigen + +--- + +## Dateien-Übersicht + +``` +~/dotfiles/claude_settings/ +├── templates/ +│ └── WORKLOG.md # NEU: Template +├── hooks/ +│ └── session-start.sh # ERWEITERN: WORKLOG + Gitea anzeigen +└── skills/ + ├── session-end.md # NEU: Session beenden + ├── session-start.md # NEU: Session starten (manuell) + └── new-project.md # NEU: Projekt anlegen +```