Leitfaden zur Problemlösung

Dieser Leitfaden behandelt häufige Probleme und ihre Lösungen bei der Verwendung von Claude-Craft.

Inhaltsverzeichnis

Installationsprobleme
Agenten-Probleme
Befehlsprobleme
Konfigurationsprobleme
Werkzeugprobleme
Leistungsprobleme
Hilfe erhalten

Installationsprobleme

Befehle werden nach der Installation nicht erkannt

Symptome:

Slash-Befehle wie /symfony:check-compliance funktionieren nicht
Claude erkennt installierte Befehle nicht

Lösungen:

Claude Code neu starten

bash

# Claude Code vollständig beenden
exit

# Neu starten
claude

Installation überprüfen

bash

ls -la .claude/commands/
# Sollte Befehlsverzeichnisse anzeigen

Dateiformat des Befehls prüfen

bash

head -5 .claude/commands/symfony/check-compliance.md
# Sollte mit einem korrekten Markdown-Header beginnen

Dateien werden bei der Installation nicht gefunden

Symptome:

Fehler „Quelldatei nicht gefunden"
Fehlende Regeln oder Vorlagen

Lösungen:

Claude-Craft-Pfad überprüfen

bash

# Prüfen, ob man sich im claude-craft-Verzeichnis befindet
pwd
ls -la Dev/scripts/

Vorhandensein der Sprachdateien prüfen
bash
```
ls -la Dev/i18n/en/Symfony/rules/
```

Absoluten TARGET-Pfad verwenden

bash

# Statt
make install-symfony TARGET=./backend

# Verwenden
make install-symfony TARGET=/vollständiger/pfad/zum/backend

Fehler „Zugriff verweigert"

Symptome:

Installationsskripte können nicht ausgeführt werden
Schreibzugriff auf Zielverzeichnis nicht möglich

Lösungen:

Skripte ausführbar machen

bash

chmod +x Dev/scripts/*.sh
chmod +x Project/*.sh
chmod +x Infra/*.sh
chmod +x Tools/*/*.sh

Berechtigungen des Zielverzeichnisses prüfen

bash

ls -la ~/my-project/
# Sicherstellen, dass Schreibzugriff vorhanden ist

Mit entsprechendem Benutzer ausführen

bash

# sudo nur bei Notwendigkeit verwenden
# Verzeichnisbesitz prüfen
ls -la ~/my-project

Installation erstellt leeres Verzeichnis

Symptome:

.claude/-Verzeichnis erstellt, aber leer oder fehlende Dateien

Lösungen:

Fehler in der Ausgabe prüfen

bash

# Mit ausführlicher Ausgabe ausführen
make install-symfony TARGET=./backend 2>&1 | tee install.log

Quelle überprüfen
bash
```
ls -la Dev/i18n/en/Symfony/
```

Direktes Skript ausführen

bash

./Dev/scripts/install-symfony-rules.sh --lang=en ./backend

Agenten-Probleme

Agent nicht verfügbar

Symptome:

@api-designer oder andere Agenten antworten nicht
Fehler des Typs „Unbekannter Agent"

Lösungen:

Vorhandensein der Agent-Dateien prüfen

bash

ls -la .claude/agents/
# Sollte Agent-.md-Dateien auflisten

Dateiformat des Agenten prüfen

bash

head -20 .claude/agents/api-designer.md
# Sollte korrekte Frontmatter mit Name und Beschreibung haben

Agenten neu installieren

bash

make install-common TARGET=. OPTIONS="--force"

Agent gibt irrelevante Antworten

Symptome:

Agent befolgt seine spezialisierten Anweisungen nicht
Generische Antworten statt Expertenrat

Lösungen:

Mehr Kontext bereitstellen

markdown

@symfony-reviewer Überprüfe meine UserService-Implementierung

Kontext:
- Symfony 7 mit API Platform
- Clean Architecture
- DDD-Ansatz

Zu überprüfender Code:
[Code hier einfügen]

In der Anfrage spezifisch sein

markdown

# Statt
@database-architect Hilf mir mit meiner Datenbank

# Verwenden
@database-architect Entwirf das Schema für den User-Aggregat mit:
- User-Entity (id, email, password_hash)
- Role-Entity (Many-to-Many mit User)
- Permission-Entity (Many-to-Many mit Role)
- Audit-Trail für Benutzeränderungen

Projektkontextdatei prüfen

bash

cat .claude/references/<your-tech>/project-context.md
# Sicherstellen, dass das Projekt korrekt beschrieben wird

Agent widerspricht Projektregeln

Symptome:

Agent-Vorschläge widersprechen Projektkonventionen
Inkonsistenter Rat

Lösungen:

Projektkontext aktualisieren
- Spezifische Konventionen zu 00-project-context.md hinzufügen
- Team-Präferenzen und -Einschränkungen einschließen

In Anfragen explizit sein

markdown

@api-designer Endpunkt gemäß unseren RESTful-Konventionen entwerfen
(Siehe 00-project-context.md für unsere API-Standards)

Befehlsprobleme

Befehl nicht gefunden

Symptome:

/symfony:generate-crud gibt „Unbekannter Befehl" zurück
Befehlsvorschläge erscheinen nicht

Lösungen:

Befehlsverzeichnis prüfen

bash

ls .claude/commands/symfony/
# Sollte generate-crud.md enthalten

Namespace überprüfen

bash

# Befehle haben das Format: /{namespace}:{befehl}
# Verfügbare Namespaces:
ls .claude/commands/
# common/, symfony/, flutter/, python/, react/, reactnative/, docker/

Verfügbare Befehle auflisten
bash
```
# In Claude Code eingeben:
/help
```

Ausführungsfehler bei Befehlen

Symptome:

Befehl startet, schlägt aber fehl
Unerwartete Ausgabe oder Fehler

Lösungen:

Voraussetzungen prüfen
- Manche Befehle benötigen bestimmte Werkzeuge
- Erforderliche Abhängigkeiten auf Vorhandensein prüfen

Befehlsdatei überprüfen

bash

cat .claude/commands/symfony/generate-crud.md
# Verstehen, was der Befehl erwartet

Erforderliche Parameter bereitstellen

bash

# Statt
/symfony:generate-crud

# Verwenden
/symfony:generate-crud User --with-api --with-tests

Befehlsausgabe ist falsch

Symptome:

Generierter Code entspricht nicht dem Projektstil
Falsche Technologiemuster verwendet

Lösungen:

Projektkontext aktualisieren

bash

# .claude/references/<your-tech>/project-context.md bearbeiten
# Spezifische Muster und Konventionen hinzufügen

Vorlagen anpassen

bash

# Vorlagen in .claude/templates/ bearbeiten
# An den Projektstil anpassen

Konfigurationsprobleme

YAML-Konfiguration ungültig

Symptome:

make config-validate schlägt fehl
Syntaxfehler in der Konfiguration

Lösungen:

YAML-Syntax prüfen

bash

# YAML validieren
yq e '.' claude-projects.yaml

Häufige YAML-Fehler:

yaml

# Falsch: inkonsistente Einrückung
projects:
  - name: "project"
    path: "/path"  # 2 Leerzeichen
     technologies: ["symfony"]  # 3 Leerzeichen – FEHLER!

# Korrekt: konsistente Einrückung
projects:
  - name: "project"
    path: "/path"
    technologies: ["symfony"]

Mit Werkzeug validieren

bash

make config-validate CONFIG=claude-projects.yaml

Projekt in Konfiguration nicht gefunden

Symptome:

„Projekt nicht gefunden" bei der Installation
Projekt wird nicht aufgelistet

Lösungen:

Schreibweise des Projektnamens prüfen

bash

# Projekte auflisten
make config-list CONFIG=claude-projects.yaml

# Namen beachten Groß-/Kleinschreibung

Pfad zur Konfigurationsdatei überprüfen

bash

# Standard sucht nach claude-projects.yaml im aktuellen Verzeichnis
# Explizit angeben:
make config-install CONFIG=/pfad/zur/config.yaml PROJECT=meinprojekt

Konfiguration wird nicht angewendet

Symptome:

Änderungen an der Konfiguration wirken sich nicht aus
Alte Einstellungen bleiben erhalten

Lösungen:

Mit force neu installieren

bash

make config-install CONFIG=claude-projects.yaml PROJECT=meinprojekt OPTIONS="--force"

Konflikte prüfen

bash

# Vorhandene Installation entfernen
rm -rf /pfad/zum/projekt/.claude

# Neu installieren
make config-install CONFIG=claude-projects.yaml PROJECT=meinprojekt

Werkzeugprobleme

StatusLine wird nicht angezeigt

Symptome:

Statusleiste leer oder standardmäßig
Benutzerdefinierte Statusleiste wird nicht angezeigt

Lösungen:

Überprüfen, ob Skript installiert ist

bash

ls -la ~/.claude/statusline.sh
# Sollte vorhanden und ausführbar sein

settings.json prüfen

bash

cat ~/.claude/settings.json | jq '.statusLine'
# Sollte anzeigen:
# {
#   "type": "command",
#   "command": "~/.claude/statusline.sh"
# }

Skript manuell testen

bash

echo '{"model":{"display_name":"Test","id":"claude-opus"}}' | ~/.claude/statusline.sh
# Sollte formatierte Statusleiste ausgeben

Auf jq prüfen

bash

which jq
# Bei fehlendem jq installieren: brew install jq / apt install jq

MultiAccount-Profilprobleme

Symptome:

Profilwechsel nicht möglich
Profil wird nicht erkannt

Lösungen:

Profile auflisten
bash
```
./claude-accounts.sh list
```

Profilverzeichnis prüfen

bash

ls -la ~/.claude-profiles/
# Sollte Profilverzeichnisse enthalten

Profil-Modus-Datei überprüfen

bash

cat ~/.claude-profiles/meinprofil/.mode
# Sollte "shared" oder "isolated" enthalten

Problematisches Profil neu erstellen

bash

./claude-accounts.sh remove meinprofil
./claude-accounts.sh add meinprofil --mode=shared

ProjectConfig-yq-Fehler

Symptome:

„yq: Befehl nicht gefunden"
YAML-Parsing-Fehler

Lösungen:

yq installieren

bash

# macOS
brew install yq

# Linux
sudo snap install yq
# oder
sudo wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/local/bin/yq
sudo chmod +x /usr/local/bin/yq

yq-Version überprüfen

bash

yq --version
# Sollte v4.x sein (mikefarah/yq, nicht kislyuk/yq)

Hook-Probleme

Hook wird nicht ausgelöst

Symptome:

PreToolUse/PostToolUse-Hooks werden nicht ausgeführt
Keine Ausgabe von Hook-Befehlen

Lösungen:

Hook-Konfiguration in settings.json überprüfen
bash
```
cat .claude/settings.json | jq '.hooks'
```

Matcher-Syntax prüfen

json

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{"type": "command", "command": "echo test"}]
    }]
  }
}

Der matcher muss exakt mit dem Werkzeugnamen übereinstimmen (z. B. Bash, Edit, Write).

Hook-Befehl unabhängig testen

bash

# Den Hook-Befehl manuell ausführen, um zu prüfen, ob er funktioniert
bash -c 'echo test'

PreCompact-Hook blockiert

Symptome:

Kontextkomprimierung findet nicht wie erwartet statt
Komprimierung scheint blockiert

Lösung: PreCompact-Hooks (v2.1.105+) können die Komprimierung mit Exit-Code 2 blockieren. Die eigenen Hooks prüfen:

bash

cat .claude/settings.json | jq '.hooks.PreCompact'
# Sicherstellen, dass Hook-Skripte nicht versehentlich Exit-Code 2 zurückgeben

Sandbox-Fehler

Symptome:

Fehler „Sandbox nicht verfügbar"
Berechtigungsprobleme bei Unterprozessen

Lösungen:

Claude Code-Version prüfen (Sandboxing erfordert v2.1.98+)
bash
```
claude --version
```

Unter Linux PID-Namespace-Unterstützung prüfen

bash

# Prüfen, ob unshare verfügbar ist
which unshare

Strenge Sandbox bei Bedarf deaktivieren (aus Sicherheitsgründen nicht empfohlen)
- sandbox.failIfUnavailable aus den Einstellungen entfernen, falls es hinzugefügt wurde

Sicherheitsbezogene Hook-Fehler

Bei Verwendung von MCP-Servern mit Hooks sicherstellen, dass Claude Code v2.1.97+ verwendet wird, um bekannte CVEs zu vermeiden:

CVE-2025-59536: Command-Injection über MCP-Eingaben in der Hook-Pipeline
CVE-2026-35020: Bypass durch zusammengesetzte Befehle
CVE-2026-35022: Umgebungsvariablen-Präfix-Injektion

Leistungsprobleme

Langsame Befehlsausführung

Symptome:

Befehle brauchen lange zum Antworten
StatusLine wird langsam aktualisiert

Lösungen:

Cache-Einstellungen prüfen

bash

# In ~/.claude/statusline.conf
SESSION_CACHE_TTL=60   # Reduzieren, wenn zu langsam
WEEKLY_CACHE_TTL=300   # Reduzieren, wenn zu langsam

Caches leeren
bash
```
rm /tmp/.ccusage_*
```
Netzwerk prüfen
- Manche Funktionen benötigen Netzwerkzugang (ccusage)
- Langsames Netzwerk = langsame Aktualisierungen

Hohe Kontextfensterauslastung

Symptome:

Kontextanzeige zeigt schnell hohen Prozentsatz
Warnungen „Kontextlimit erreicht"

Lösungen:

/context für Optimierungsvorschläge verwenden (v2.1.74+)
bash
```
/context
```

Aufwandsniveau für einfache Aufgaben anpassen (v2.1.72+)

bash

/effort low    # Einfache Suchen
/effort medium # Standardarbeit

Proaktiv bei ca. 70 % Auslastung komprimieren
bash
```
/compact
```
/clear zwischen nicht zusammenhängenden Aufgaben verwenden

Wichtige Erkenntnisse vor der Komprimierung speichern

bash

/memory "Wichtig: Auth verwendet JWT RS256 mit 15 Min. Ablaufzeit"

RTK für 55–65 % Token-Einsparung einrichten
bash
```
/common:setup-rtk
```

Agenten für komplexe Aufgaben verwenden

markdown

# Statt die gesamte Codebasis einzufügen
@research-assistant Alle authentifizierungsbezogenen Dateien in src/ finden

Hilfe erhalten

Dokumentation prüfen

Haupt-Docs: Verzeichnis docs/
Agenten-Referenz: docs/AGENTS.md
Befehls-Referenz: docs/COMMANDS.md
Technologie-Leitfaden: docs/TECHNOLOGIES.md

Versionsinformationen abrufen

bash

# Installationsskripte
./Dev/scripts/install-symfony-rules.sh --version

# Werkzeuge
./Tools/MultiAccount/claude-accounts.sh --version
./Tools/ProjectConfig/claude-projects.sh --version

Fehler melden

Bei Auftreten von Bugs:

Informationen sammeln:
- Claude-Craft-Version
- Betriebssystem
- Reproduktionsschritte
- Fehlermeldungen
Vorhandene Issues auf GitHub prüfen
Neues Issue mit Details erstellen

Um Hilfe bitten

markdown

@research-assistant Ich habe Probleme mit [Problem beschreiben]

Umgebung:
- Betriebssystem: [Ihr OS]
- Claude-Craft-Version: [Version]
- Technologie: [symfony/flutter/etc.]

Was ich versucht habe:
1. [Schritt 1]
2. [Schritt 2]

Fehlermeldung:
[Fehler einfügen]

Schnellkorrekturen-Checkliste

Wenn etwas nicht funktioniert:

[ ] Claude Code neu starten
[ ] Installation überprüfen (ls .claude/)
[ ] Dateiberechtigungen prüfen
[ ] Konfiguration validieren
[ ] Caches leeren
[ ] Abhängigkeiten prüfen (jq, yq)
[ ] Neuinstallation mit --force versuchen
[ ] Dokumentation prüfen
[ ] Um Hilfe bitten

← Werkzeug-Referenz | Backlog-Management →

Leitfaden zur Problemlösung ​

Inhaltsverzeichnis ​

Installationsprobleme ​

Befehle werden nach der Installation nicht erkannt ​

Dateien werden bei der Installation nicht gefunden ​

Fehler „Zugriff verweigert" ​

Installation erstellt leeres Verzeichnis ​

Agenten-Probleme ​

Agent nicht verfügbar ​

Agent gibt irrelevante Antworten ​

Agent widerspricht Projektregeln ​

Befehlsprobleme ​

Befehl nicht gefunden ​

Ausführungsfehler bei Befehlen ​

Befehlsausgabe ist falsch ​

Konfigurationsprobleme ​

YAML-Konfiguration ungültig ​

Projekt in Konfiguration nicht gefunden ​

Konfiguration wird nicht angewendet ​

Werkzeugprobleme ​

StatusLine wird nicht angezeigt ​

MultiAccount-Profilprobleme ​

ProjectConfig-yq-Fehler ​

Hook-Probleme ​

Hook wird nicht ausgelöst ​

PreCompact-Hook blockiert ​

Sandbox-Fehler ​

Sicherheitsbezogene Hook-Fehler ​

Leistungsprobleme ​

Langsame Befehlsausführung ​

Hohe Kontextfensterauslastung ​

Hilfe erhalten ​

Dokumentation prüfen ​

Versionsinformationen abrufen ​

Fehler melden ​

Um Hilfe bitten ​

Schnellkorrekturen-Checkliste ​

Leitfaden zur Problemlösung

Inhaltsverzeichnis

Installationsprobleme

Befehle werden nach der Installation nicht erkannt

Dateien werden bei der Installation nicht gefunden

Fehler „Zugriff verweigert"

Installation erstellt leeres Verzeichnis

Agenten-Probleme

Agent nicht verfügbar

Agent gibt irrelevante Antworten

Agent widerspricht Projektregeln

Befehlsprobleme

Befehl nicht gefunden

Ausführungsfehler bei Befehlen

Befehlsausgabe ist falsch

Konfigurationsprobleme

YAML-Konfiguration ungültig

Projekt in Konfiguration nicht gefunden

Konfiguration wird nicht angewendet

Werkzeugprobleme

StatusLine wird nicht angezeigt

MultiAccount-Profilprobleme

ProjectConfig-yq-Fehler

Hook-Probleme

Hook wird nicht ausgelöst

PreCompact-Hook blockiert

Sandbox-Fehler

Sicherheitsbezogene Hook-Fehler

Leistungsprobleme

Langsame Befehlsausführung

Hohe Kontextfensterauslastung

Hilfe erhalten

Dokumentation prüfen

Versionsinformationen abrufen

Fehler melden

Um Hilfe bitten

Schnellkorrekturen-Checkliste