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
  

• Kontinuierliche Verbesserung: Erkenntnisse für globale Anweisungen?

  • Prüfe: Gab es in dieser Session Erkenntnisse, Patterns oder Pitfalls, die auch in zukünftigen Sessions (projektübergreifend) nützlich wären?
  • Kandidaten sind:
    • Neue Workflow-Patterns (z.B. "immer erst X prüfen bevor Y")
    • API-/Tool-Eigenheiten die wiederholt auftreten
    • Fehler die durch bessere Anweisungen vermeidbar wären
    • Neue Host-Typen oder Zugangs-Patterns (z.B. "pfSense → immer root")
    • Dokumentations-Strukturen die sich bewährt haben
  • Falls ja: Dem User vorschlagen, welche Punkte in CLAUDE.md aufgenommen werden sollten
  • Falls nein: Kurz bestätigen: "Keine neuen globalen Erkenntnisse aus dieser Session"
  • Wichtig: Nicht selbst entscheiden — dem User die Erkenntnisse vorlegen und ihn entscheiden lassen

⚠️ 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.

Wiki-Prinzip: Verlinkte Dokumentation (PFLICHT)

JEDE Erwähnung eines Hosts, Dienstes oder Systems in der Dokumentation MUSS als Markdown-Link auf dessen Dokumentation verweisen.

Dies gilt für ALLE Dokumentation - nicht nur Netzwerk, sondern auch Host-Dateien, Dependencies, Hardware, README, etc.

Regeln

1. Host-Referenzen → Link auf hosts/[hostname].md

   • Aus hosts/-Dateien: relativer Pfad [srvdocker02](srvdocker02.md)
   • Aus Root-Dateien: [srvdocker02](hosts/srvdocker02.md)
   • Aus Unterverzeichnissen: [srvdocker02](../hosts/srvdocker02.md)

2. Hardware-Referenzen → Link auf hardware/[gerät].md

   • [HPE Switch](hardware/hpe-switch.md) oder relativ [HPE Switch](../hardware/hpe-switch.md)

3. Dienst-/System-Referenzen → Link auf zugehörige Doku

   • Externe Repos: [Zabbix](https://gitea.egonetix.de/Egonetix/zabbix)
   • Interne Doku: [Keycloak SSO](keycloak-sso.md)

4. Mermaid-Diagramme: Hier sind keine Markdown-Links möglich. Stattdessen MUSS nach jedem Diagramm eine Referenz-Tabelle stehen mit Links zu den referenzierten Hosts/Diensten.

5. Tabellen: Host-/Dienstnamen in Tabellenzellen als Link formatieren.

6. Organisationsübergreifende Referenzen → Hosts/Dienste, die zu einer anderen Kunden-Organisation gehören, werden auf deren Gitea-Repo verlinkt.

   • Prinzip: Die kanonische Doku eines Hosts lebt in der Organisation, zu der er gehört. Andere Organisationen verweisen per Gitea-URL darauf.
   • Aus Egonetix auf Vinos-Host: [gw-nu-wan01](https://gitea.egonetix.de/Vinos/infrastructure/src/branch/main/hosts/gw-nu-wan01.md)
   • Aus Vinos auf Egonetix-Host: [srvhost04](https://gitea.egonetix.de/Egonetix/infrastructure/src/branch/main/hosts/srvhost04.md)
   • Lokaler Stub: Im eigenen Repo kann eine Stub-Datei existieren, die auf die kanonische Doku verweist (z.B. wenn der Host in der eigenen Infrastruktur referenziert wird). Der Stub muss klar als "Gehört zu Organisation X" markiert sein.
   • Wann: Immer wenn ein Host in der Doku einer anderen Organisation auftaucht (VPN-Gegenstellen, gemeinsame Dienste, Abhängigkeiten über Organisationsgrenzen).

Ausnahmen

• Derselbe Host innerhalb seiner eigenen Dokumentation (kein Self-Link)
• Hosts in der "Entdeckte aber nicht gescannte Hosts"-Liste (keine Doku vorhanden)
• Inline-Code-Blöcke (Befehle, Konfigurationen)

Beispiel

Falsch:

srvdocker02 benötigt srvdc01 für DNS.
PBS auf Hetzner Storage Box (1TB)

Richtig:

[srvdocker02](srvdocker02.md) benötigt [srvdc01](srvdc01.md) für DNS.
PBS auf Hetzner Storage Box (1TB) - siehe [srvhost04 Storage](srvhost04.md#hardware--storage)

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

PFLICHT: Monitoring-Abgleich bei Infrastruktur-Änderungen

Wenn sich an einem Host Hardware, Software oder Dienste ändern, MUSS geprüft werden ob das Monitoring noch passt.

Dies gilt bei:

• Neuem Host/Dienst/Container hinzugefügt
• Host neuinstalliert oder migriert
• Dienst entfernt oder ersetzt
• Hardware-Änderung (Disk, RAM, Netz)
• Template-Wechsel in Zabbix

Prüf-Fragen:

Frage	Aktion wenn Ja
Wird dieser Host/Dienst überwacht?	Prüfen ob Items/Trigger noch aktuell sind
Wird er NICHT überwacht, sollte er aber?	→ Onboarding-Entscheidung treffen (siehe Zabbix copilot-instructions.md)
Wurden Dienste entfernt?	Phantom-Triggers/Items prüfen und ggf. löschen
Wurden neue Dienste hinzugefügt?	Template/Items ergänzen oder bewusst ausschließen
Hat sich die Rolle des Hosts geändert?	Host Groups, Service-Baum, Dependencies in Zabbix aktualisieren

Dokumentieren in:

• hosts/[host].md → Abschnitt "Monitoring" oder "Wiederkehrende Probleme"
• Zabbix README.md → "Nicht überwacht" Liste aktualisieren
• Zabbix copilot-instructions.md → Host-IDs Tabelle bei neuen Hosts

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.

Parallele Agenten-Nutzung (PFLICHT)

Claude MUSS eigenständig entscheiden, wie viele Agenten parallel gestartet werden, um Aufgaben schneller zu erledigen.

• Bis zu 10 oder mehr parallele Agenten sind erlaubt
• Claude entscheidet selbst, wie viele Agenten sinnvoll sind
• Unabhängige Teilaufgaben MÜSSEN parallel bearbeitet werden
• Dies gilt für: Host-Scans, Dokumentations-Updates, Verifikation, Recherche

Beispiele:

• 10 Host-Dateien aktualisieren → 10 Agenten parallel
• 5 unabhängige Recherche-Aufgaben → 5 Agenten parallel
• Scan + Dokumentation + Commit → sequentiell (abhängig)

Ausnahmen

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

Zabbix-Probleme beheben: Pflicht-Workflow

BEVOR Zabbix-Probleme behoben werden, MUSS immer zuerst ein Plan erstellt und dem User vorgelegt werden.

Phase A: Analyse (parallel, ohne User-Interaktion)

1. Alle offenen Probleme via API abfragen (problem.get)
2. Trigger-zu-Host-Mapping erstellen (trigger.get mit selectHosts)
3. Aktuelle Item-Werte prüfen (item.get — ist das Problem echt oder stale?)
4. Trigger-Expressions lesen (für korrekte Macro-Namen)

Phase B: Klassifizieren und Liste erstellen

Jedes Problem in eine Kategorie einordnen:

Kategorie	Beschreibung	Aktion
STALE	Trigger disabled, Event offen	manual_close setzen + Event schließen
THRESHOLD	Wert normal, Schwellwert zu niedrig	Host-Macro erstellen/anpassen
ECHT	Tatsächliches Problem	SSH-Intervention oder manuelle Aktion
TEMPLATE-NOISE	Trigger passt nicht zum Host-Typ	Trigger disablen oder Macro-Filter

Phase C: Nummerierte Liste dem User vorlegen

PFLICHT: Dem User eine nummerierte, nach Priorität sortierte Liste präsentieren:

# | Host | Problem | Kategorie | Geplante Aktion
1 | srvhost04 | Disk 95% | ECHT | SSH: Cleanup LXC 101
2 | srvdocker02 | Agent down | ECHT | SSH: Service starten
3 | gw-st01 | /mnt/share_new | STALE | API: FS-Macro + Event schließen
...

Der User entscheidet:

• Welche Punkte bearbeitet werden
• In welcher Reihenfolge
• Ob SSH-Aktionen gewünscht sind

Phase D: Punkt für Punkt abarbeiten

• Nur nach User-Freigabe ausführen
• Parallele Agenten für unabhängige API-Fixes
• Nach jedem Punkt: Ergebnis melden
• Ergebnis-Verifikation via problem.get

Phase E: Rolling Documentation aktualisieren (PFLICHT)

Nach JEDER Zabbix-Problem-Session:

1. Host-Dateien aktualisieren (infrastructure/hosts/[host].md):

   • Abschnitt "Wiederkehrende Probleme" anlegen/ergänzen
   • Datum, Problem, Lösung, ob wiederkehrend
   • Beispiel:

     ## Wiederkehrende Probleme
     
     | Datum | Problem | Lösung | Wiederkehrend |
     |-------|---------|--------|---------------|
     | 2026-01-29 | Memory >90% | Macro {$MEMORY.UTIL.MAX}=95 | Ja (normal für Workload) |
     | 2026-01-29 | Swap <50% free | Macro {$SWAP.PFREE.MIN.WARN}=10 | Ja (normal) |
     

2. Zabbix copilot-instructions.md aktualisieren:

   • Neue Pitfalls dokumentieren
   • Macro-Namen-Korrekturen festhalten
   • Patterns für zukünftige Problemlösung

3. dependencies.md prüfen — Falls neue Abhängigkeiten entdeckt

Wichtige Pitfalls

• Macro-Namen exakt prüfen! Trigger-Expression lesen, nicht raten. Beispiel: {$PVE.MEMORY.PUSE.MAX.WARN} ≠ {$PVE.MEM.PUSE.MAX.WARN}
• LLD-Trigger: Discovered Triggers können nicht direkt manual_close gesetzt werden. Stattdessen: Template Trigger-Prototyp updaten → LLD re-run (task.create type 6)
• Event schließen: Erst manual_close=1 auf Trigger setzen, dann event.acknowledge action=1
• curl | jq kann leere Ausgabe liefern: Immer erst in Datei speichern, dann lesen
• NIEMALS /etc/hosts editieren! DNS-Probleme werden IMMER auf dem zuständigen DNS-Server gelöst, nie auf dem Client. Keine Ausnahmen.
• Split-Horizon-DNS bei UCS: Wenn ein UCS-DC eine lokale Zone für eine öffentliche Domain hostet (z.B. egonetix.de), werden externe DNS-Einträge (z.B. auf INWX) nie erreicht — der DC antwortet autoritativ mit NXDOMAIN. Fix: Eintrag in der lokalen UCS-Zone per udm dns/host_record create anlegen. Bei jedem neuen externen Host prüfen ob ein lokaler DNS-Eintrag nötig ist.
• Proxmox VM-ID-Wechsel: Wenn VMs umgezogen/neu erstellt werden, ALLE Zabbix-Referenzen prüfen: LLD-Items, Trigger, Actions, Scripts. Phantom-Items für alte VMIDs per item.delete entfernen.
• LXC-Container Swap-Monitoring: Auf LXC-Containern (Proxmox) Swap-Triggers generell disablen — Container haben keinen eigenen Swap und reporten den Host-Swap über /proc/swaps. Bei neuen LXC-Hosts immer prüfen.
• FreeBSD Agent-Spikes: pfSense/FreeBSD Zabbix-Agent kann kurzzeitig falsche Werte liefern (Uptime, Disk, Swap). Trigger mit min(,5m) statt last() härten um Einzelspitzen zu ignorieren.

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)