root/claude_settings
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Infrastruktur-Dokumentation: Neue Kunden-Organisation

Browse Source 
- 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 <noreply@anthropic.com>
This commit is contained in:
root
2026-01-27 13:00:30 +01:00
parent 92b276a422
commit a536d35743
4 changed files with 772 additions and 81 deletions
Download Patch File Download Diff File Expand all files Collapse all files

124
CLAUDE.md
View File

@@ -229,73 +229,103 @@ 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 `<HOST_SETUP_REQUIRED>` 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 `<REPO_SETUP_REQUIRED>` 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
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
```
~/Nextcloud/hosts/
├── [kunde]/ # z.B. vinos, egonetix
│ └── [hostname]/ # z.B. srv-monitor02, srv-db12
│ └── copilot-instructions.md
└── _templates/
└── copilot-instructions-template.md # Master-Template
```
### Workflow: Neuen Host anlegen
Der User legt nur den Ordner an:
4. **Remote hinzufügen und pushen:**
```bash
mkdir -p ~/Nextcloud/hosts/[kunde]/[hostname]
cd ~/Nextcloud/hosts/[kunde]/[hostname]
claude # Startet Claude Code
git remote add origin ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git
git push -u origin main
```
Claude erkennt automatisch das fehlende Template und bietet Setup an.
### Gitea Remote-Konfiguration
**URL-Format:**
```
ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git
```
**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
```bash
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
```
### Skills-Referenz

77
hooks/session-start.sh
View File

@@ -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
HOSTS_BASE="$HOME/Nextcloud/hosts"
TEMPLATE_PATH="$HOSTS_BASE/_templates/copilot-instructions-template.md"
# Bekannte Kunden-Verzeichnisse
KUNDEN_BASE="$HOME/Nextcloud"
KNOWN_KUNDEN="vinos egonetix"
# 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 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)
# 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 ==="
if [[ -n "$REPO_NAME" ]]; then
echo "=== KUNDEN-REPO ERKANNT ==="
echo "Kunde: $KUNDE"
echo "Host: $HOSTNAME"
echo "Repo: $REPO_NAME"
echo ""
# Sammle Setup-Anforderungen
# 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
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 "<HOST_SETUP_REQUIRED>"
echo "<REPO_SETUP_REQUIRED>"
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 "- 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 "</HOST_SETUP_REQUIRED>"
echo "</REPO_SETUP_REQUIRED>"
fi
fi
echo ""
else
fi
break
fi
done
# Legacy: Prüfe auch ~/Nextcloud/hosts/ für Übergangszeit
HOSTS_BASE="$HOME/Nextcloud/hosts"
if [[ "$ORIGINAL_DIR" == "$HOSTS_BASE"/* ]]; then
REL_PATH="${ORIGINAL_DIR#$HOSTS_BASE/}"
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 "=== LEGACY HOST-VERZEICHNIS ERKANNT ==="
echo "Kunde: $KUNDE"
echo "Host: $HOSTNAME"
echo ""
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

373
plans/elegant-zooming-porcupine.md Normal file
View File

@@ -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

269
plans/quirky-snacking-bunny.md Normal file
View File

@@ -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)
<!-- Fehler und Erkenntnisse damit Claude sich verbessert -->
- **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 <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
```