Fehlerbehebung und FAQ

Wenn etwas nicht funktioniert, beginne hier. Die meisten Probleme lassen sich durch Ausführen dieses Befehls lösen:

planu doctor

Dieser Befehl überprüft deine Installation, Konfigurationsdateien und KI-Tool-Verbindungen und teilt dir dann genau mit, was behoben werden muss.

---

Installationsprobleme

MCP nach der Installation nicht erkannt

Dein KI-Tool muss vollständig neu gestartet werden — nicht nur das Fenster, sondern der gesamte Prozess.

Claude Code:

# Beende Claude Code vollständig und öffne es erneut
# Überprüfe, ob Planu in der Liste erscheint:
claude mcp list

Cursor / Windsurf / Zed: Schließe die Anwendung über die Taskleiste oder das Dock (nicht nur das Fenster), dann öffne sie erneut.

Immer noch nicht erkannt?

Führe planu doctor aus — es zeigt, welche Konfigurationsdateien geschrieben wurden und ob das KI-Tool sie sehen kann.

---

Falscher Konfigurationsdateipfad

Planu schreibt die Konfiguration je nach Betriebssystem und Geltungsbereich (Benutzer oder Projekt) an verschiedene Orte.

Geltungsbereich	Claude Code	Cursor	Windsurf
Benutzer (macOS/Linux)	~/.claude/claude.json	~/.cursor/mcp.json	~/.codeium/windsurf/mcp_config.json
Benutzer (Windows/WSL)	%APPDATA%\Claude\claude.json	%APPDATA%\Cursor\mcp.json	%APPDATA%\Windsurf\mcp_config.json
Projekt	.claude/claude.json	.cursor/mcp.json	.windsurf/mcp_config.json

Wie prüft man, welche Konfigurationsdatei aktiv ist

planu doctor

Die Ausgabe enthält einen Abschnitt Config files mit den genauen Pfaden, die geschrieben wurden, und ob das KI-Tool sie lesen kann.

Speziell für Claude Code:

claude mcp list
# Die erwartete Ausgabe enthält:
# planu — planu serve

---

Berechtigungsfehler beim Ausführen von npx

npm-Berechtigungen unter macOS/Linux beheben

Dies passiert, wenn das globale npm-Verzeichnis root gehört. Behebe es ohne sudo:

# Option 1: Ein benutzereigenes Präfix verwenden
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # oder ~/.bashrc
source ~/.zshrc

# Option 2: nvm verwenden (für Entwickler empfohlen)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Dann Node.js über nvm neu installieren

Überprüfe nach der Behebung:

planu install --global

Verwende niemals sudo mit npm

Das Ausführen von sudo npm install -g maskiert Berechtigungsprobleme und erstellt root-eigene Dateien, was später zu weiteren Fehlern führt. Behebe stattdessen die zugrunde liegenden Berechtigungen.

---

"command not found: planu" nach npm install -g

Das globale npm-Binärverzeichnis ist nicht in deinem PATH.

# Finde heraus, wo npm globale Binärdateien installiert:
npm config get prefix
# Typische Ausgabe: /usr/local  →  Binärdateien sind in /usr/local/bin

# Zum PATH hinzufügen, falls fehlend (macOS/Linux):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Überprüfen:
planu --version

Bevorzuge npx gegenüber der globalen Installation

Du kannst immer planu <befehl> verwenden, ohne global zu installieren. Der Installer verwendet intern npx, daher ist die globale Installation optional.

---

KI-Tool-Konnektivität

Claude Code zeigt keine Planu-Tools

1. Führe planu doctor aus, um zu überprüfen, ob die Konfiguration korrekt geschrieben wurde
2. Führe claude mcp list aus — Planu muss in der Ausgabe erscheinen
3. Starte eine neue Unterhaltung und tippe: list my planu tools
4. Wenn Claude Code nach Genehmigung fragt, genehmige sie (oder richte automatische Genehmigung ein — siehe Erste Schritte)

claude mcp list
# Erwartete Ausgabe:
# planu    planu serve    [active]

MCP-Tools sind konversationsbezogen

Tools werden geladen, wenn eine Unterhaltung beginnt. Wenn du Planu installiert hast, während eine Unterhaltung offen war, starte eine neue.

---

Cursor / Windsurf erkennen das MCP nach der Installation nicht

Konfigurationsdatei manuell überprüfen

Cursor — prüfe ~/.cursor/mcp.json:

{
  "mcpServers": {
    "planu": {
      "command": "planu",
      "args": ["serve"]
    }
  }
}

Windsurf — prüfe ~/.codeium/windsurf/mcp_config.json (gleiche Struktur).

Wenn die Datei korrekt ist, das Tool aber immer noch nicht erscheint:

1. Schließe die Anwendung vollständig
2. Öffne sie erneut
3. Warte ~10 Sekunden, bis der MCP-Server startet
4. Öffne einen neuen Chat und gib einen Planu-Befehl ein

---

Fehler "Tool not found" in Claude

Das bedeutet, dass Claude in der aktuellen Unterhaltung nicht mit dem Planu-MCP-Server verbunden ist.

# Installation erneut überprüfen:
planu doctor

# Bei Bedarf erneut hinzufügen:
claude mcp add planu -- npx -y @planu/cli@latest

Dann starte eine neue Unterhaltung — MCP-Verbindungen werden zu Beginn jeder Unterhaltung hergestellt.

---

Wie du die Installation überprüfst

planu doctor

Erwartete Ausgabe:

Planu Doctor v0.89.0
====================
Node.js:     24.x     OK
npx:         10.x     OK
Config:
  Claude Code  ~/.claude/claude.json     found
  Cursor       ~/.cursor/mcp.json        found
License:     Pro — user@email.com
Status:      All checks passed

---

Spec-Workflow-Probleme

validate schlägt immer fehl, auch nach der Implementierung

Das Tool validate prüft, ob dein Code den Akzeptanzkriterien der Spec entspricht. Häufige Gründe für Fehler:

1. Die Kriterien sind zu vage — führe check_readiness aus, um sie vor der Implementierung zu verbessern
2. Falscher Projektpfad — stelle sicher, dass du das korrekte Quellverzeichnis übergibst
3. Spec und Code stimmen tatsächlich nicht überein — prüfe, welche Kriterien fehlschlagen, und implementiere die fehlenden Teile

Prompt: "Validate spec SPEC-003 against the code at /path/to/src"

Was tun, wenn validate weiterhin fehlschlägt

Prompt: "Show me which criteria are failing for spec SPEC-003"

Dies listet jedes Kriterium mit seinem Abdeckungsstatus auf. Konzentriere dich auf die nicht abgedeckten. Wenn ein Kriterium erfüllt ist, aber trotzdem fehlschlägt, ist es möglicherweise so formuliert, dass der Validator es nicht erkennen kann — verwende reconcile_spec, um die Formulierung an die tatsächliche Implementierung anzupassen.

---

Drift fälschlicherweise erkannt (falsches Positiv)

detect_drift vergleicht deinen aktuellen Code mit dem, was die Spec beschreibt. Falsch-Positive treten auf, wenn:

• Die Spec mit sehr spezifischen Implementierungsdetails geschrieben wurde, die sich geändert haben (aber das Verhalten ist gleich)
• Du Code refaktoriert hast, ohne die Spec zu aktualisieren

Wenn der Drift beabsichtigt ist (die Spec muss aktualisiert werden, um der tatsächlichen Implementierung zu entsprechen):

Prompt: "Reconcile spec SPEC-003 with the implementation changes in project [id]"

reconcile_spec führt dich durch jede Änderung und bittet um Genehmigung pro Änderung, bevor die Spec aktualisiert wird.

Drift ist nicht immer schlecht

Drift bedeutet "Plan und Code stimmen nicht überein." Manchmal ist der Code richtig und der Plan veraltet — dann wird abgeglichen. Manchmal ist der Code falsch — dann wird der Code korrigiert.

---

Spec von Tools nicht gefunden

Tools identifizieren Specs anhand der ID (z. B. SPEC-003) innerhalb eines Projekts. Wenn eine Spec nicht gefunden wird:

# Prüfe die Projekt-ID für das aktuelle Verzeichnis:
planu status

# Liste alle Specs des Projekts auf:
# Prompt: "List all specs in project [id]"

Häufige Ursachen:

• Verwendung der falschen Projekt-ID (Planu verwendet einen Hash des Projektpfads)
• Die Spec wurde in einem anderen Verzeichnis als dem aktuellen erstellt

---

create_spec läuft bei großen Projekten ab

Bei sehr großen Projekten (Millionen von Dateien) kann der initiale Scan länger als erwartet dauern.

Scan-Bereich einschränken:

Prompt: "Create a spec for [feature] in project [id], scan only the src/ directory"

Du kannst den Scan auch einmal vorab ausführen, um Ergebnisse zu cachen:

Prompt: "Scan project [id] at path /path/to/project, limit to src/"

Nachfolgende create_spec-Aufrufe für dasselbe Projekt verwenden den gecachten Scan.

---

Leistung

Erste Antwort langsam (Kaltstart)

Die erste Antwort in einer neuen Unterhaltung ist langsamer, weil:

1. npx die neueste Version von @planu/cli herunterlädt (ein paar Sekunden)
2. Der MCP-Server initialisiert sich und lädt die Daten deines Projekts

Diese Kosten fallen einmal pro Unterhaltung an. Nachfolgende Tool-Aufrufe sind schnell.

Kaltstartzeit reduzieren

Verwende --prefer-online (bereits in der Standardkonfiguration enthalten), um das Paket lokal zu cachen. Nach dem ersten Ausführen verwendet npx die gecachte Version erneut und prüft nur auf Updates.

---

Scan großer Projekte dauert zu lange

Prompt: "Scan project [id] at /path/to/project, limit scan to src/ and tests/"

Du kannst Verzeichnisse auch ausschließen, indem du sie auflistest:

Prompt: "Scan project [id], exclude node_modules, dist, .git, and vendor directories"

---

Wie du den Scan-Bereich einschränkst

Übergebe beim Erstellen von Specs oder beim Scannen explizite Pfadbeschränkungen:

Prompt: "Create a spec for payment processing, scanning only src/payments/ in project [id]"

Planu respektiert diese Grenzen und analysiert keine Dateien außerhalb des angegebenen Pfads.

---

Hilfe erhalten

Wenn keiner der oben genannten Schritte dein Problem gelöst hat, sammle zuerst Diagnoseinformationen:

planu doctor

Kopiere die vollständige Ausgabe und füge sie in deinen Bug-Report ein.

Was in einen Bug-Report gehört

• Vollständige Ausgabe von planu doctor
• Der Befehl oder Prompt, der das Problem ausgelöst hat
• Die genaue Fehlermeldung oder das unerwartete Verhalten
• Dein Betriebssystem und deine Node.js-Version: node --version
• Dein KI-Tool und seine Version (z. B. Claude Code 1.x, Cursor 0.4x)

Ein Problem melden

Bitte deinen installierten Planu-Agenten, submit_feedback mit der Ausgabe von planu doctor und einer Beschreibung von Erwartung und Ergebnis zu verwenden. Falls Planu nicht startet, nutze den öffentlichen Discord-Support.

Community-Support

Durchsuche bestehende Issues, bevor du ein neues öffnest — dein Problem hat möglicherweise bereits eine Lösung oder einen Workaround.