From 9be3ae4937ce3276c5d96d2e88f94597c8ca490c Mon Sep 17 00:00:00 2001 From: root Date: Tue, 27 Jan 2026 11:24:27 +0100 Subject: [PATCH] Neues Troubleshooting-System: Skill und CLAUDE.md Erweiterung MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Neuer Skill: troubleshoot-host.md für standardisierten Workflow - CLAUDE.md erweitert um Host-Troubleshooting Sektion - Automatische Erkennung von ~/Nextcloud/hosts/ Verzeichnissen - Skills-Referenztabelle hinzugefügt Co-Authored-By: Claude Opus 4.5 --- CLAUDE.md | 42 ++++++++++ skills/troubleshoot-host.md | 161 ++++++++++++++++++++++++++++++++++++ 2 files changed, 203 insertions(+) create mode 100644 skills/troubleshoot-host.md diff --git a/CLAUDE.md b/CLAUDE.md index 04ecfd7..c39bcab 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -226,3 +226,45 @@ When a user requests to set up a new ongoing project: 5. **Commit initial documentation** This upfront investment minimizes questions in future sessions and enables faster, more informed development. + +--- + +## Host Troubleshooting + +### 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 +``` + +### Neuen Host dokumentieren + +1. Erstelle Verzeichnis: `mkdir -p ~/Nextcloud/hosts/[kunde]/[hostname]` +2. Kopiere Template: `cp ~/Nextcloud/hosts/_templates/copilot-instructions-template.md ./copilot-instructions.md` +3. Fülle während der Arbeit die relevanten Felder aus +4. Committe die Dokumentation + +### Skills-Referenz + +| Skill | Zweck | +|-------|-------| +| `/troubleshoot-host` | Strukturierter Troubleshooting-Workflow | +| `/session-end` | Session beenden, Commits erstellen | +| `/new-project` | Neues Projekt anlegen | diff --git a/skills/troubleshoot-host.md b/skills/troubleshoot-host.md new file mode 100644 index 0000000..8b9b492 --- /dev/null +++ b/skills/troubleshoot-host.md @@ -0,0 +1,161 @@ +--- +name: troubleshoot-host +description: Standardisierter Troubleshooting-Workflow für Host-Systeme in ~/Nextcloud/hosts/ +invocation: /troubleshoot-host +--- + +# Host Troubleshooting Skill + +Dieser Skill führt durch einen standardisierten Troubleshooting-Prozess für Systeme, die unter `~/Nextcloud/hosts/` dokumentiert sind. + +## Voraussetzungen + +- Du befindest dich in einem Host-Verzeichnis unter `~/Nextcloud/hosts/[kunde]/[hostname]/` +- Eine `copilot-instructions.md` existiert (oder wird erstellt) + +## Workflow + +### Phase 1: Kontext erfassen + +1. **Verzeichnis prüfen** + ```bash + pwd + ls -la + ``` + +2. **Dokumentation laden** + - Lies `copilot-instructions.md` falls vorhanden + - Falls nicht vorhanden: Frage ob Template verwendet werden soll + - Template-Pfad: `~/Nextcloud/hosts/_templates/copilot-instructions-template.md` + +3. **System-Typ identifizieren** + - Windows / Linux / Appliance + - Zugangsart (SSH, RDP, API, Web) + - Abhängigkeiten notieren + +### Phase 2: Problem analysieren + +Frage den User nach folgenden Informationen (falls nicht bereits bekannt): + +| Frage | Zweck | +|-------|-------| +| Was ist das Symptom? | Genaue Fehlerbeschreibung | +| Wann trat es auf? | Zeitliche Eingrenzung | +| Was hat sich geändert? | Mögliche Ursachen identifizieren | +| Wer/was ist betroffen? | Scope verstehen | +| Gibt es Fehlermeldungen? | Konkrete Anhaltspunkte | + +### Phase 3: Diagnose durchführen + +1. **Quick Reference nutzen** + - Führe die Basis-Checks aus der `copilot-instructions.md` durch + - Nutze die dokumentierten Befehle + +2. **Logs prüfen** + - Konsultiere die Log-Locations aus der Doku + - Suche nach Fehlern im relevanten Zeitraum + +3. **Abhängigkeiten prüfen** + - Sind verbundene Systeme erreichbar? + - Funktionieren die Schnittstellen? + +4. **Hypothesen bilden** + - Liste mögliche Ursachen auf + - Priorisiere nach Wahrscheinlichkeit + +### Phase 4: Lösung implementieren + +1. **Jeden Schritt dokumentieren** + - Was wurde versucht? + - Was war das Ergebnis? + +2. **Fix anwenden** + - Bei Unsicherheit: Backup/Snapshot zuerst + - Änderungen minimal halten + +3. **Verifizieren** + - Symptom behoben? + - Keine neuen Probleme? + - Betroffene User informiert? + +### Phase 5: Dokumentation aktualisieren + +**WICHTIG:** Nach erfolgreicher Lösung MUSS die Dokumentation aktualisiert werden! + +1. **Problem + Lösung eintragen** + + Füge in `copilot-instructions.md` unter "Bekannte Probleme & Lösungen" hinzu: + + ```markdown + ### [Problem-Titel] + + **Symptom:** [Genaue Beschreibung] + + **Ursache:** [Was das Problem verursacht hat] + + **Lösung:** + ```bash + [Befehle oder Schritte] + ``` + + **Datum:** [YYYY-MM-DD] | **Commit:** `[HASH]` + ``` + +2. **Weitere Erkenntnisse dokumentieren** + - Neue Pitfalls? + - Troubleshooting-Checkliste erweitern? + - Abhängigkeiten aktualisieren? + +3. **Git Commit** + ```bash + git add -A + git commit -m "Troubleshooting: [Kurzbeschreibung des Problems/Lösung]" + git push origin main # falls Remote vorhanden + ``` + +## Checkliste + +- [ ] Dokumentation gelesen +- [ ] Problem verstanden +- [ ] Diagnose durchgeführt +- [ ] Lösung implementiert +- [ ] Fix verifiziert +- [ ] Dokumentation aktualisiert +- [ ] Git commit erstellt + +## Tipps + +### Wenn keine Doku existiert + +1. Kopiere das Template: + ```bash + cp ~/Nextcloud/hosts/_templates/copilot-instructions-template.md ./copilot-instructions.md + ``` + +2. Fülle während des Troubleshootings die relevanten Felder aus + +3. Das Troubleshooting selbst liefert wertvolle Informationen für die Doku + +### Bei komplexen Problemen + +- Nutze die TodoWrite-Funktion um Schritte zu tracken +- Erstelle Hypothesen-Liste und arbeite sie systematisch ab +- Dokumentiere auch fehlgeschlagene Lösungsversuche (was NICHT funktioniert hat) + +### Remote-Zugriff + +Für SSH-Befehle auf dem Ziel-Host: +```bash +ssh user@host "befehl" +``` + +Für interaktive Sessions: +```bash +ssh user@host +# Dann Befehle ausführen +``` + +## Verwandte Skills + +- `/session-end` - Am Ende der Session für Commit-Reminder +- `/new-project` - Falls neues Host-Verzeichnis angelegt werden muss