Files

root d755e5d92f Pitfall: systemd-resolved resolvectl domain überschreibt DHCP-Einstellungen

Search-Domains vs Routing-Domains (~) Unterschied dokumentiert.
WLAN-Reconnect setzt Änderungen zurück.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2026-01-30 09:35:31 +01:00

34 KiB

Raw Blame History

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?
    - Für JEDEN Host auf dem gearbeitet wurde (auch indirekt, z.B. Reverse Proxy, DNS-Server)
  - infrastructure/dependencies.md aktualisiert?
    - Mermaid-Diagramme: Neue Verbindungen/Abhängigkeiten eingezeichnet?
    - Referenz-Tabellen: Neue Hosts ergänzt?
    - Impact-Analyse: Neue Ausfallszenarien?
  - infrastructure/netzwerk/domains.md aktualisiert?
    - Neue Subdomains eingetragen?
    - DNS-Änderungen reflektiert?
- Ä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:

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

Step 2: For Ongoing Projects

Read existing copilot-instructions.md and PROJECT_OVERVIEW.md to understand the system
Scan the codebase/system to gather context and minimize follow-up questions
Update documentation if the current work affects architecture, patterns, entities, or conventions
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:

Connect and explore the system to understand what exists
Scan broadly — gather device lists, integrations, file structures, configurations
Create documentation based on findings:
- copilot-instructions.md for development guidelines and patterns
- PROJECT_OVERVIEW.md for system inventory (if complex)
Initialize git if not present
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:

Frage den User:

"Ich habe erkannt, dass für dieses Repo noch Setup erforderlich ist. Soll ich das automatisch durchführen?"

Bei Zustimmung - führe alle fehlenden Schritte aus:

# Git initialisieren (falls nicht vorhanden)
git init
git branch -M main

# Template aus infrastructure/_templates/ kopieren

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

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:

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

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

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

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)
Hardware-Referenzen → Link auf hardware/[gerät].md
- [HPE Switch](hardware/hpe-switch.md) oder relativ [HPE Switch](../hardware/hpe-switch.md)
Dienst-/System-Referenzen → Link auf zugehörige Doku
- Externe Repos: [Zabbix](https://gitea.egonetix.de/Egonetix/zabbix)
- Interne Doku: [Keycloak SSO](keycloak-sso.md)
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.
Tabellen: Host-/Dienstnamen in Tabellenzellen als Link formatieren.
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

Prüfe: Existiert infrastructure/hosts/[hostname].md?
Falls nein oder unvollständig: Vollständigen Scan durchführen
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:

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

Effizienz

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

Indirekt betroffene Hosts dokumentieren (PFLICHT)

Wenn du auf Host A arbeitest und dabei Host B konfigurierst (z.B. per SSH, API, DNS), gilt die Rolling-Documentation-Pflicht auch für Host B.

Dies ist eine häufige Fehlerquelle: Man dokumentiert nur den "Ziel-Host" der Aufgabe, vergisst aber die Hosts, auf denen man nebenbei Änderungen vorgenommen hat.

Beispiele:

Aufgabe auf Host A	Nebenarbeit auf Host B	Doku-Pflicht
ActiveSync auf srvmail01 einrichten	nginx-Config auf srvrevproxy02 anlegen	srvrevproxy02.md aktualisieren
Neue Subdomain für srvmail01	DNS-Record auf srvdc01 anlegen	srvdc01.md prüfen, domains.md ergänzen
Zertifikat für Dienst X	certbot auf srvrevproxy02 ausführen	srvrevproxy02.md aktualisieren
Spam-Learning einrichten	IMAP-Zugriff auf srvmail01 aktivieren	Abhängigkeit in dependencies.md ergänzen

Regel: Nach jeder SSH-Session auf einem Host fragen: "Habe ich die Doku dieses Hosts aktualisiert?"

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)

Alle offenen Probleme via API abfragen (problem.get)
Trigger-zu-Host-Mapping erstellen (trigger.get mit selectHosts)
Aktuelle Item-Werte prüfen (item.get — ist das Problem echt oder stale?)
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:

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

Zabbix copilot-instructions.md aktualisieren:
- Neue Pitfalls dokumentieren
- Macro-Namen-Korrekturen festhalten
- Patterns für zukünftige Problemlösung
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.
systemd-resolved: Vorsicht mit resolvectl domain: Das Setzen von DNS-Domains per resolvectl domain überschreibt DHCP-gelieferte Einstellungen komplett. Search-Domains (ohne ~) ermöglichen Kurzname-Auflösung (srvdocker02 → srvdocker02.egonetix.lan). Routing-Domains (mit ~) routen nur Queries an bestimmte DNS-Server, erlauben aber keine Kurzname-Auflösung. Beides mischen: resolvectl domain wlp0s20f3 egonetix.lan "~egonetix.de". Wichtig: Nach einem WLAN-Reconnect werden resolvectl-Änderungen von NetworkManager/DHCP wieder überschrieben — für permanente Änderungen die NetworkManager-Verbindung konfigurieren.
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)

34 KiB Raw Blame History

Global Claude Code Instructions

🚨 PFLICHT-CHECKLISTE BEI TASK-ABSCHLUSS 🚨

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

Bei JEDEM Task-Abschluss:

⚠️ WICHTIG

⚠ MANDATORY: Settings-Synchronisierung

Bei jedem Session-Start prüfen

Nach Änderungen an Settings pushen

Copilot Instructions Skill

Mandatory Workflow

Step 1: Determine Project Type

Step 2: For Ongoing Projects

Document Structure

copilot-instructions.md (Development Guidelines)

PROJECT_OVERVIEW.md (System Reference)

Content Guidelines

Git Commit Convention

Referencing Git Commits

When to Update copilot-instructions.md

New Project Onboarding

Infrastruktur-Dokumentationssystem

Ziel und Vision

Organisation pro Kunde

Repo-Typen

Automatische Erkennung (Hook-gesteuert)

Gitea Remote-Konfiguration

Gitea Tooling

Workflow: Neues System-/Dienst-Repo anlegen

Dokumentations-Verifikation (PFLICHT)

Schritt 1: Erstvergleich

Schritt 2: Fehlende Inhalte ergänzen

Schritt 3: Erneute Verifikation (PFLICHT)

Wiki-Prinzip: Verlinkte Dokumentation (PFLICHT)

Regeln

Ausnahmen

Beispiel

Rolling Documentation: Opportunistisches Host-Scanning

Auslöser

Workflow bei Host-Zugriff

Scan-Checkliste nach Host-Typ

PFLICHT: Abhängigkeiten dokumentieren

PFLICHT: Monitoring-Abgleich bei Infrastruktur-Änderungen

Beispiel

Rekursive Host-Entdeckung (WICHTIG!)

Effizienz

Indirekt betroffene Hosts dokumentieren (PFLICHT)

Parallele Agenten-Nutzung (PFLICHT)

Ausnahmen

Zabbix-Probleme beheben: Pflicht-Workflow

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

Phase B: Klassifizieren und Liste erstellen

Phase C: Nummerierte Liste dem User vorlegen

Phase D: Punkt für Punkt abarbeiten

Phase E: Rolling Documentation aktualisieren (PFLICHT)

Wichtige Pitfalls

Skills-Referenz

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

Architektur

Wann CRA vorschlagen

Kommando-Referenz

MCP-Server Integration

Wichtige Hinweise

34 KiB

Raw Blame History