claude_settings/CLAUDE.md

Global Claude Code Instructions

🚨 PFLICHT-CHECKLISTE BEI TASK-ABSCHLUSS 🚨

DIESE CHECKLISTE IST NICHT OPTIONAL. SIE MUSS BEI JEDER ABGESCHLOSSENEN AUFGABE DURCHGEFÜHRT WERDEN.

BEVOR du dem User sagst, dass du fertig bist, gehe diese Liste durch:

Bei JEDER Dokumentationsarbeit (README, Config-Docs, etc.):

• Verifikation durchgeführt?

  • Vergleichstabelle: Quelle ↔ Dokumentation erstellt
  • ALLE Abschnitte geprüft (nicht nur die offensichtlichen)
  • Finale Checkliste mit Zeilennummern erstellt
  • Bestätigung: "X/X Abschnitte vollständig dokumentiert"

• Infrastructure-Repo aktualisiert?

  • Wenn Kunde erkannt (~/Nextcloud/[kunde]/):
    • infrastructure/hosts/[host].md aktualisiert?
    • infrastructure/dependencies.md aktualisiert?
  • Änderungen committet und gepusht?

Bei JEDEM Task-Abschluss:

• Alle Änderungen committet und gepusht?

  • Aktuelles Repo
  • Infrastructure-Repo (falls relevant)

• Settings-Sync geprüft?

  cd ~/dotfiles/claude_settings && git fetch origin && git status
  

⚠️ WICHTIG

Du darfst NICHT:

• Sagen "Erledigt" ohne diese Checkliste durchzugehen
• Den User fragen ob er die Checkliste will - sie ist PFLICHT
• Schritte überspringen weil sie "offensichtlich nicht nötig" sind
• Warten bis der User dich an fehlende Schritte erinnert

Der User verlässt sich darauf, dass du diese Anweisungen IMMER befolgst.

---

⚠ MANDATORY: Settings-Synchronisierung

Repository: git@gitea.egonetix.de:root/claude_settings.git (Port 222) Lokaler Pfad: ~/dotfiles/claude_settings

Bei jedem Session-Start prüfen

cd ~/dotfiles/claude_settings && git fetch origin && git status

Falls Änderungen vorhanden:

git pull origin main

Nach Änderungen an Settings pushen

Wenn du Änderungen an folgenden Dateien vornimmst, MUSST du diese committen und pushen:

• settings.json - Globale Einstellungen
• CLAUDE.md - Diese Instruktionen
• agents/*.md - Benutzerdefinierte Agenten
• rules/*.md - Modulare Regeln
• statusline-command.sh - Statuszeilen-Script

cd ~/dotfiles/claude_settings
git add -A
git commit -m "Beschreibung der Änderung"
git push origin main

---

Copilot Instructions Skill

Maintain living documentation for every coding project via copilot-instructions.md in the project root.

---

Mandatory Workflow

Step 1: Determine Project Type

Check for existing project indicators:

• Git repository (.git/ directory)
• copilot-instructions.md file
• PROJECT_OVERVIEW.md file

If ANY exist → Ongoing Project: Follow full documentation workflow.

If NONE exist → Ask the user:

"This looks like a new workspace. Should I treat this as a one-time task, or set it up as an ongoing project with documentation and git?"

If user wants an ongoing project:

1. Initialize git repo if missing (git init)
2. Create copilot-instructions.md with initial structure
3. Optionally create PROJECT_OVERVIEW.md for complex systems

Step 2: For Ongoing Projects

1. Read existing copilot-instructions.md and PROJECT_OVERVIEW.md to understand the system
2. Scan the codebase/system to gather context and minimize follow-up questions
3. Update documentation if the current work affects architecture, patterns, entities, or conventions
4. Commit all changes to git immediately after completion

---

Document Structure

copilot-instructions.md (Development Guidelines)

Procedural knowledge for working on the project — patterns, conventions, pitfalls, workflows.

# Project Name - Copilot Instructions

## ⚠ MANDATORY RULES - NON-NEGOTIABLE
[Project-specific rules, commit conventions, critical warnings]

## Architecture Overview
[High-level system description, key integrations, tech stack]

## File Structure
[Directory tree with annotations]

## [Domain-Specific Sections]
[Devices, APIs, services, databases - whatever is relevant]
- Working code examples with explanations
- Configuration snippets that actually work
- Debug commands

## Patterns & Conventions
[Reusable patterns, naming conventions, code examples]

## Development Workflow
[How to test, deploy, access systems]

## Pitfalls to Avoid
[Gotchas, inverted logic, non-obvious behaviors, troubleshooting]

PROJECT_OVERVIEW.md (System Reference)

Factual inventory of what exists — devices, integrations, entities, IPs. Use for complex systems with many components.

# Project Overview

## System Information
[Version, host, IP, access details]

## Network Architecture
[Diagram or list of hosts/devices]

## Installed Components
[Add-ons, plugins, integrations with purpose]

## Entity/Device Inventory
[Tables of devices, entity IDs, purposes]

## Quick Reference
[Common commands, URLs, access methods]

When to create PROJECT_OVERVIEW.md:

• Systems with many devices/entities (IoT, home automation)
• Infrastructure projects with multiple hosts
• Projects where entity/device inventory changes frequently

---

Content Guidelines

Include:

• Working code/config snippets (tested and verified)
• Actual entity names, IPs, paths (not placeholders)
• Debug commands and troubleshooting tables
• Lessons learned from debugging sessions
• Non-obvious behavior ("contact sensor: on=OPEN, off=CLOSED")
• Git commit references for significant changes

Exclude:

• Secrets, tokens, passwords (reference secrets.yaml or .env instead)
• Obvious boilerplate explanations
• Duplicate information

Language: Match the user's language. Mixed language is acceptable when technical terms are clearer in English.

---

Git Commit Convention

After every change:

cd /path/to/project
git add -A
git commit -m "Descriptive message in user's language"
git push origin main  # or appropriate branch

Commit messages should describe what changed, not just "updated docs".

---

Referencing Git Commits

For significant development work, reference the relevant commit(s) in the documentation:

## Tasmota SML Integration

**Implemented:** 2025-01-21 | Commits: `a3f2b1c`, `e7d4a9f`

[Documentation of the feature...]

When to add commit references:

• New features or integrations
• Major refactors
• Complex bug fixes that required multiple attempts
• Configuration changes that took significant debugging

Format options:

• Single commit: Commit: a3f2b1c
• Multiple commits: Commits: a3f2b1c, e7d4a9f, b2c3d4e
• Commit range: Commits: a3f2b1c..e7d4a9f

Get the short hash after committing:

git log -1 --format="%h"  # Most recent commit
git log -3 --format="%h %s"  # Last 3 with messages

---

When to Update copilot-instructions.md

Update when:

• Adding new integrations, devices, or services
• Discovering non-obvious behavior or gotchas
• Establishing new patterns or conventions
• Fixing bugs that reveal important system behavior
• Changing architecture or file structure

Don't update for:

• Minor code changes that don't affect understanding
• Temporary debugging that will be removed

---

New Project Onboarding

When a user requests to set up a new ongoing project:

1. Connect and explore the system to understand what exists
2. Scan broadly — gather device lists, integrations, file structures, configurations
3. Create documentation based on findings:
   • copilot-instructions.md for development guidelines and patterns
   • PROJECT_OVERVIEW.md for system inventory (if complex)
4. Initialize git if not present
5. Commit initial documentation

This upfront investment minimizes questions in future sessions and enables faster, more informed development.

---

Infrastruktur-Dokumentationssystem

Ziel und Vision

Die detaillierte Infrastruktur-Dokumentation dient einem größeren Ziel:

Phase 1: Dokumentation (aktuell)

• Vollständige Erfassung aller Hosts, Dienste, Abhängigkeiten
• Maschinenlesbare Struktur (Markdown mit konsistenten Tabellen)
• Abhängigkeitsgraphen in Mermaid

Phase 2: Zabbix-Integration

• Abhängigkeiten aus dependencies.md → Zabbix Host Dependencies
• Wiederkehrende Probleme → Zabbix Trigger + Actions
• Host-Dokumentation → Zabbix Host Inventory
• Impact-Analysen → Zabbix Service Monitoring

Phase 3: Self-Healing durch KI

• KI analysiert Zabbix-Alerts + Dokumentation
• Automatische Diagnose basierend auf dokumentierten Abhängigkeiten
• Automatische Remediation für bekannte Probleme
• Lernschleife: Neue Probleme → Dokumentation → Zabbix → KI

Konsequenzen für die Dokumentation:

• Vollständigkeit ist kritisch - fehlende Abhängigkeiten = blinde Flecken für KI
• Konsistente Struktur - ermöglicht maschinelles Parsing
• Wiederkehrende Probleme dokumentieren - werden zu automatisierbaren Fixes
• Impact bei Ausfall - definiert Prioritäten für automatische Reaktionen

Organisation pro Kunde

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

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 dieses Repo noch Setup erforderlich ist. Soll ich das automatisch durchführen?"

2. Bei Zustimmung - führe alle fehlenden Schritte aus:

   # Git initialisieren (falls nicht vorhanden)
   git init
   git branch -M main
   
   # Template aus infrastructure/_templates/ kopieren
   

3. Repo auf Gitea erstellen (API):

   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
   

4. Remote hinzufügen und pushen:

   git remote add origin ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git
   git push -u origin main
   

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

Gitea Tooling

Token-Speicherort (NICHT im Git-Sync!):

~/.config/gitea/token

Verfügbare Tools:

Tool	Befehl	Anwendung
tea CLI	~/bin/tea	Vollständige Gitea-Interaktion
curl + API	curl -H "Authorization: token $(cat ~/.config/gitea/token)"	Einfache API-Aufrufe

tea CLI Beispiele:

# Repos auflisten
~/bin/tea repos list

# Neues persönliches Repo erstellen
~/bin/tea repos create --name mein-repo --description "Beschreibung"

# Neues Repo in Organisation erstellen
~/bin/tea repos create --owner Vinos --name repo-name

# Issues auflisten
~/bin/tea issues list

# PR erstellen
~/bin/tea pr create --title "Feature X" --description "..."

curl API Beispiele:

# Persönliches Repo erstellen
curl -X POST -H "Authorization: token $(cat ~/.config/gitea/token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"...","private":false}' \
  https://gitea.egonetix.de/api/v1/user/repos

# Repo in Organisation erstellen
curl -X POST -H "Authorization: token $(cat ~/.config/gitea/token)" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"..."}' \
  https://gitea.egonetix.de/api/v1/orgs/[Org]/repos

Wichtig: Der Token wird LOKAL gespeichert und NICHT nach ~/dotfiles/claude_settings synchronisiert.

Workflow: Neues System-/Dienst-Repo anlegen

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

Dokumentations-Verifikation (PFLICHT)

Bei jeder Dokumentationsarbeit MUSS eine zweistufige Verifikation durchgeführt werden:

• Neue Dokumentation erstellen
• Bestehende Dokumentation umstrukturieren
• Inhalte aus anderen Quellen übernehmen
• Dokumentation aufteilen oder zusammenführen

Schritt 1: Erstvergleich

Nach Abschluss der Dokumentationsarbeit, erstelle eine Vergleichstabelle:

| Abschnitt (Original) | Neue Datei | Status |
|---------------------|------------|--------|
| [Abschnitt 1] | [datei.md:zeilen] | ✅/❌ |
| [Abschnitt 2] | [datei.md:zeilen] | ✅/❌ |
...

• Liste JEDEN Abschnitt der Quelldokumentation auf
• Prüfe ob er in der neuen Struktur vorhanden ist
• Markiere fehlende Abschnitte mit ❌

Schritt 2: Fehlende Inhalte ergänzen

• Ergänze alle mit ❌ markierten Abschnitte
• Committe die Änderungen

Schritt 3: Erneute Verifikation (PFLICHT)

Nach dem Ergänzen MUSS eine erneute, vollständige Prüfung erfolgen:

1. Lies alle neuen Dateien nochmals
2. Erstelle eine finale Checkliste mit Zeilennummern:

| # | Abschnitt | Datei:Zeilen | Status |
|---|-----------|--------------|--------|
| 1 | [Name] | README.md:15-18 | ✅ |
| 2 | [Name] | hosts.md:5-8 | ✅ |
...

3. Bestätige: "X/X Abschnitte vollständig dokumentiert. Keine Inhalte wurden vergessen."

Dieser Prozess ist nicht optional. Dokumentationsverlust durch unvollständige Arbeit ist inakzeptabel.

Rolling Documentation: Opportunistisches Host-Scanning

Prinzip: Wenn du während deiner Arbeit Zugriff auf einen Host bekommst, führe einen VOLLSTÄNDIGEN Scan durch - nicht nur für die aktuelle Aufgabe.

Auslöser

• SSH-Zugriff auf einen Host
• Web-UI Zugriff (pfsense, NPM, etc.)
• API-Zugriff

Workflow bei Host-Zugriff

1. Prüfe: Existiert infrastructure/hosts/[hostname].md?
2. Falls nein oder unvollständig: Vollständigen Scan durchführen
3. Dann erst: Ursprüngliche Aufgabe erledigen

Scan-Checkliste nach Host-Typ

Netzwerk-Geräte (pfsense, Router):

• Interfaces (Name, IP, Netz)
• ALLE Firewall-Regeln (nicht nur relevante!)
• ALLE Aliases
• NAT-Regeln (Port-Forwards, Outbound)
• DHCP/DNS-Konfiguration
• System-Version
• ABHÄNGIGKEITEN: Welche Hosts/Dienste hängen von diesem Gerät ab?

Linux-Server:

• OS/Version
• Interfaces und IPs
• Laufende Dienste
• Docker-Container
• Offene Ports
• Wichtige Configs
• ABHÄNGIGKEITEN: Welche anderen Hosts braucht dieser Server? Wer braucht ihn?

Windows-Server:

• OS/Version
• Interfaces und IPs
• Dienste und geplante Tasks
• Installierte Rollen
• ABHÄNGIGKEITEN: Verbindungen zu anderen Systemen

PFLICHT: Abhängigkeiten dokumentieren

Bei JEDEM Host-Scan müssen die Abhängigkeiten erfasst werden:

Frage	Dokumentieren in
Welche Hosts/Dienste braucht dieser Host?	hosts/[host].md → Abschnitt "Abhängigkeiten"
Welche Hosts/Dienste hängen von diesem Host ab?	hosts/[host].md → Abschnitt "Abhängig von diesem Host"
Gibt es Abhängigkeitsketten?	dependencies.md → Mermaid-Diagramm

Ziel: Anhand der Dokumentation muss erkennbar sein:

• Was passiert wenn Host X ausfällt?
• Welche Dienste sind von Änderungen an Host X betroffen?
• Welche Hosts müssen vor Host X gestartet werden?

Beispiel Abhängigkeits-Dokumentation:

## Abhängigkeiten

Dieser Host benötigt:
- **srv-docker02** (10.10.10.81) - n8n Backend
- **srv-nu-dc01** (10.10.10.111) - DNS-Auflösung

## Abhängig von diesem Host

Folgende Dienste/Hosts sind von diesem Host abhängig:
- **flow.wvits.de** - Webhook-Zugang fällt aus wenn dieser Host down ist
- **n8n.vinos.de** - Interner Zugang über diesen NPM

## Impact bei Ausfall

| Ausfall-Szenario | Betroffene Dienste |
|------------------|-------------------|
| Komplett-Ausfall | flow.wvits.de, n8n.vinos.de, ... |
| Nur Port 443 | HTTPS-Zugriff auf alle proxied Dienste |

dependencies.md aktualisieren:

Nach jedem Host-Scan prüfen ob infrastructure/dependencies.md aktualisiert werden muss:

• Neue Abhängigkeitskette entdeckt? → Mermaid-Diagramm ergänzen
• Impact-Analyse hinzufügen
• Repo-Links aktualisieren

Beispiel

Aufgabe: Firewall-Regel für srv-revproxy01 prüfen

Falsch	Richtig
Nur die eine Regel prüfen	Erst: Existiert hosts/gw-nu-dmz02.md?
Session beenden	Nein → Vollständigen Scan aller Regeln, Aliases, Interfaces
	Host-Datei erstellen
	Dann: Ursprüngliche Aufgabe

Rekursive Host-Entdeckung (WICHTIG!)

Wenn du bei einem Scan Referenzen zu anderen Hosts siehst, gehe AUTOMATISCH weiter:

Entdeckungsquellen:

• Firewall-Regeln (Ziel-IPs, Aliases)
• NAT-Regeln (Forward-Ziele)
• DNS-Einträge
• Docker-Compose (externe Hosts)
• Konfigurationsdateien
• Log-Einträge
• Netzwerk-Verbindungen

Workflow:

Host A scannen
  ↓
Entdecke Referenz zu Host B (z.B. in Firewall-Regel)
  ↓
Kann ich Host B erreichen?
  ├─ JA → Host B scannen (rekursiv)
  └─ NEIN → Host B in Entdeckungsliste aufnehmen

Entdeckungsliste führen:

Wenn ein Host nicht gescannt werden kann (kein Zugriff, keine Credentials, etc.):

## Entdeckte aber nicht gescannte Hosts

| Host | IP | Entdeckt in | Grund für fehlenden Scan |
|------|----|-------------|-------------------------|
| srv-xyz01 | 10.10.10.99 | gw-nu-dmz02 Firewall-Regel | Kein SSH-Zugriff |
| db-server | 10.10.20.5 | docker-compose.yml | Credentials unbekannt |

Der User muss dich NICHT auf jeden Host einzeln hinweisen!

Du sollst selbstständig:

1. Referenzen zu anderen Hosts erkennen
2. Versuchen diese zu scannen
3. Falls nicht möglich: Dokumentieren was du entdeckt hast
4. Beim nächsten Mal nachfragen ob Zugriff jetzt möglich ist

Effizienz

Nutze parallele Agenten für umfangreiche Scans und rekursive Entdeckung.

Ausnahmen

• Zeitkritische Notfälle (erst fixen, dann dokumentieren)
• Explizite User-Anweisung nur aktuelle Aufgabe zu erledigen
• User sagt explizit "nicht weiter scannen"

Skills-Referenz

Skill	Zweck
/troubleshoot-host	Strukturierter Troubleshooting-Workflow
/session-end	Session beenden, Commits erstellen
/new-project	Neues Projekt anlegen
/delegate-remote	Tasks an Remote-Server delegieren (CRA)

---

Claude Remote Agent (CRA) - Verteilte Task-Ausführung

Repository: ~/Nextcloud/egonetix/claude-remote-agent CLI-Tool: cra Zweck: Delegiert Aufgaben an Remote-Server, die Claude Code CLI autonom ausführen - auch wenn der Laptop offline ist.

Architektur

Laptop (Coordinator)  ──SSH + JSON-RPC 2.0──>  Server (claude-agent)

• Coordinator: Verwaltet Server, erstellt Tasks, sammelt Ergebnisse
• Agent: Empfängt Tasks, führt Claude Code CLI autonom aus, speichert Ergebnisse lokal
• Persistenz: SQLite auf beiden Seiten, Tasks überleben Verbindungsabbrüche

Wann CRA vorschlagen

Du SOLLST dem User CRA aktiv vorschlagen, wenn:

Szenario	Beispiel
Lang laufende Tasks	Codebase-Analyse, Refactorings, Log-Analyse
Server-Wartung	Updates, Cleanup, Security-Audits
Multi-Server-Operationen	Gleiche Aufgabe auf mehreren Servern parallel
Offline-Delegation	User will Laptop zuklappen, Tasks sollen weiterlaufen
Unabhängige Teilaufgaben	Aufgabe lässt sich in parallele Sub-Tasks aufteilen

"Diese Aufgabe eignet sich gut für CRA - soll ich sie an einen Remote-Server delegieren?"

Kommando-Referenz

# Server verwalten
cra servers add <name> <host> [--user USER] [--port PORT] [--key PATH] [--tag TAG]
cra servers list [--all]
cra servers remove <name> [--yes]
cra servers status [name]

# Tasks
cra submit <server> "<prompt>" [--priority N] [--model MODEL] [--max-turns N]
cra status <server> [task_id]
cra cancel <server> <task_id>

# Ergebnisse
cra collect [server] [--task ID] [--since ISO-DATETIME] [--output FILE]

# Config synchronisieren
cra sync-config [server] [--no-claude-md] [--no-settings]

MCP-Server Integration

Wenn der CRA MCP-Server konfiguriert ist, stehen CRA-Funktionen als native Tools zur Verfügung (cra_submit, cra_status, cra_collect, cra_servers_list, cra_server_status, cra_sync_config). Prüfe ob MCP-Tools verfügbar sind, bevor du auf CLI-Befehle zurückfällst.

Wichtige Hinweise

• Autonome Ausführung: Server brauchen ~/.claude/settings.json mit Tool-Permissions
• Config-Sync: Nach CLAUDE.md/settings.json Änderungen → cra sync-config
• Retry: Fehlgeschlagene Tasks werden automatisch wiederholt (max 3x)