Dépannage et FAQ

Si quelque chose ne fonctionne pas, commencez ici. La plupart des problèmes se résolvent en exécutant :

bash

planu doctor

Cette commande vérifie votre installation, vos fichiers de configuration et vos connexions avec les outils d'IA, puis vous indique exactement ce qu'il faut corriger.

Problèmes d'Installation

MCP non détecté après l'installation

Votre outil d'IA doit être complètement redémarré — pas seulement la fenêtre, mais tout le processus.

Claude Code :

bash

# Quittez Claude Code complètement, puis rouvrez-le
# Vérifiez que Planu apparaît dans la liste :
claude mcp list

Cursor / Windsurf / Zed : Fermez l'application depuis la barre des tâches ou le dock (pas seulement la fenêtre), puis rouvrez-la.

Toujours pas détecté ?

Exécutez planu doctor — il indiquera quels fichiers de configuration ont été écrits et si l'outil d'IA peut les voir.

Chemin incorrect du fichier de configuration

Planu écrit la configuration dans différents emplacements selon votre système d'exploitation et la portée (utilisateur ou projet).

Portée	Claude Code	Cursor	Windsurf
Utilisateur (macOS/Linux)	`~/.claude/claude.json`	`~/.cursor/mcp.json`	`~/.codeium/windsurf/mcp_config.json`
Utilisateur (Windows/WSL)	`%APPDATA%\Claude\claude.json`	`%APPDATA%\Cursor\mcp.json`	`%APPDATA%\Windsurf\mcp_config.json`
Projet	`.claude/claude.json`	`.cursor/mcp.json`	`.windsurf/mcp_config.json`

Comment vérifier quel fichier de configuration est actif

bash

planu doctor

La sortie inclut une section Config files montrant les chemins exacts qui ont été écrits et si l'outil d'IA peut les lire.

Pour Claude Code spécifiquement :

bash

claude mcp list
# La sortie attendue inclut :
# planu — planu serve

Erreurs de permissions lors de l'exécution de npx

Corriger les permissions npm sur macOS/Linux

Cela se produit quand le répertoire global de npm appartient à root. Corrigez sans sudo :

bash

# Option 1 : Utiliser un préfixe appartenant à l'utilisateur
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # ou ~/.bashrc
source ~/.zshrc

# Option 2 : Utiliser nvm (recommandé pour les développeurs)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Puis réinstallez Node.js via nvm

Après correction, vérifiez :

bash

planu install --global

N'utilisez jamais sudo avec npm

Exécuter sudo npm install -g masque les problèmes de permissions et crée des fichiers appartenant à root, ce qui cause davantage d'erreurs ensuite. Corrigez plutôt les permissions sous-jacentes.

"command not found: planu" après npm install -g

Le répertoire des binaires globaux de npm n'est pas dans votre PATH.

bash

# Trouvez où npm installe les binaires globaux :
npm config get prefix
# Sortie typique : /usr/local  →  les binaires sont dans /usr/local/bin

# Ajoutez au PATH si absent (macOS/Linux) :
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Vérifiez :
planu --version

Préférez npx à l'installation globale

Vous pouvez toujours utiliser planu <commande> sans installation globale. L'installateur utilise npx en interne, donc l'installation globale est optionnelle.

Connectivité avec les Outils d'IA

Claude Code n'affiche pas les outils Planu

Exécutez planu doctor pour vérifier que la configuration a été correctement écrite
Exécutez claude mcp list — Planu doit apparaître dans la sortie
Démarrez une nouvelle conversation et tapez : list my planu tools
Si Claude Code demande une permission, approuvez-la (ou configurez l'approbation automatique — voir Démarrage)

bash

claude mcp list
# Sortie attendue :
# planu    planu serve    [active]

Les outils MCP sont par conversation

Les outils se chargent au démarrage d'une conversation. Si vous avez installé Planu pendant une conversation ouverte, démarrez-en une nouvelle.

Cursor / Windsurf ne reconnaissent pas le MCP après l'installation

Vérifier manuellement le fichier de configuration

Cursor — vérifiez ~/.cursor/mcp.json :

json

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

Windsurf — vérifiez ~/.codeium/windsurf/mcp_config.json (même structure).

Si le fichier est correct mais que l'outil n'apparaît toujours pas :

Fermez l'application complètement
Rouvrez-la
Attendez ~10 secondes pour que le serveur MCP démarre
Ouvrez un nouveau chat et saisissez une commande Planu

Erreur "Tool not found" dans Claude

Cela signifie que Claude n'est pas connecté au serveur MCP de Planu dans la conversation actuelle.

bash

# Vérifiez à nouveau l'installation :
planu doctor

# Ajoutez à nouveau si nécessaire :
claude mcp add planu -- npx -y @planu/cli@latest

Puis démarrez une nouvelle conversation — les connexions MCP sont établies au début de chaque conversation.

Comment vérifier l'installation

bash

planu doctor

Sortie attendue :

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

Problèmes de Flux de Travail des Specs

`validate` échoue toujours même après l'implémentation

L'outil validate vérifie si votre code correspond aux critères d'acceptation de la spec. Quelques raisons courantes d'échec :

Les critères sont trop vagues — exécutez check_readiness pour les améliorer avant d'implémenter
Chemin de projet incorrect — assurez-vous de passer le bon répertoire source
La spec et le code sont réellement désalignés — vérifiez quels critères échouent et implémentez les parties manquantes

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

Que faire quand validate continue d'échouer

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

Cela liste chaque critère avec son statut de couverture. Concentrez-vous sur ceux non couverts. Si un critère est satisfait mais échoue toujours, il est peut-être rédigé d'une façon que le validateur ne peut pas détecter — utilisez reconcile_spec pour mettre à jour la formulation afin qu'elle corresponde à l'implémentation réelle.

Drift détecté incorrectement (faux positif)

detect_drift compare votre code actuel avec ce que la spec décrit. Les faux positifs surviennent quand :

La spec a été rédigée avec des détails d'implémentation très spécifiques qui ont changé (mais le comportement est le même)
Vous avez refactorisé le code sans mettre à jour la spec

Si le drift est intentionnel (la spec doit être mise à jour pour correspondre à l'implémentation réelle) :

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

reconcile_spec vous guide à travers chaque changement et demande une approbation par changement avant de mettre à jour la spec.

Le drift n'est pas toujours négatif

Drift signifie "le plan et le code ne concordent pas." Parfois le code est correct et le plan est obsolète — c'est le moment de réconcilier. Parfois le code est incorrect — c'est le moment de corriger le code.

Spec non trouvée par les outils

Les outils identifient les specs par ID (ex. : SPEC-003) au sein d'un projet. Si une spec n'est pas trouvée :

bash

# Vérifiez l'ID du projet pour le répertoire actuel :
planu status

# Listez toutes les specs du projet :
# Prompt: "List all specs in project [id]"

Causes courantes :

Utiliser le mauvais ID de projet (Planu utilise un hash du chemin du projet)
La spec a été créée dans un répertoire différent de celui où vous vous trouvez

`create_spec` expire sur les grands projets

Sur les très grands projets (des millions de fichiers), le scan initial peut prendre plus de temps que prévu.

Limitez la portée du scan :

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

Vous pouvez également pré-exécuter le scan une fois pour mettre les résultats en cache :

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

Les appels suivants à create_spec sur le même projet utiliseront le scan mis en cache.

Performance

Première réponse lente (démarrage à froid)

La première réponse dans une nouvelle conversation est plus lente parce que :

npx télécharge la dernière version de @planu/cli (quelques secondes)
Le serveur MCP s'initialise et charge les données de votre projet

Ce coût est unique par conversation. Les appels d'outils suivants sont rapides.

Réduire le temps de démarrage à froid

Utilisez --prefer-online (déjà inclus dans la configuration par défaut) pour mettre le paquet en cache localement. Après la première exécution, npx réutilise la version mise en cache et vérifie seulement les mises à jour.

Le scan de grands projets prend trop de temps

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

Vous pouvez également exclure des répertoires en les listant :

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

Comment limiter la portée du scan

Passez des restrictions de chemin explicites lors de la création de specs ou du scan :

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

Planu respecte ces limites et n'analysera pas les fichiers en dehors du chemin spécifié.

Obtenir de l'Aide

Si aucune des étapes ci-dessus n'a résolu votre problème, collectez d'abord les informations de diagnostic :

bash

planu doctor

Copiez la sortie complète et incluez-la dans votre rapport de bug.

Que inclure dans un rapport de bug

Sortie complète de planu doctor
La commande ou le prompt qui a déclenché le problème
Le message d'erreur exact ou le comportement inattendu
Votre système d'exploitation et version de Node.js : node --version
Votre outil d'IA et sa version (ex. : Claude Code 1.x, Cursor 0.4x)

Signaler un problème

Demandez à votre agent Planu installé d’utiliser submit_feedback avec la sortie de planu doctor et une description du résultat attendu et observé. Si Planu ne démarre pas, utilisez le canal Discord public.

Support communautaire

Recherchez dans les issues existantes avant d'en ouvrir une nouvelle — votre problème a peut-être déjà une solution ou une solution de contournement.

Dépannage et FAQ ​

Problèmes d'Installation ​

MCP non détecté après l'installation ​

Chemin incorrect du fichier de configuration ​

Erreurs de permissions lors de l'exécution de npx ​

"command not found: planu" après npm install -g ​

Connectivité avec les Outils d'IA ​

Claude Code n'affiche pas les outils Planu ​

Cursor / Windsurf ne reconnaissent pas le MCP après l'installation ​

Erreur "Tool not found" dans Claude ​

Comment vérifier l'installation ​

Problèmes de Flux de Travail des Specs ​

validate échoue toujours même après l'implémentation ​

Drift détecté incorrectement (faux positif) ​

Spec non trouvée par les outils ​

create_spec expire sur les grands projets ​

Performance ​

Première réponse lente (démarrage à froid) ​

Le scan de grands projets prend trop de temps ​

Comment limiter la portée du scan ​

Obtenir de l'Aide ​

Que inclure dans un rapport de bug ​

Signaler un problème ​

Dépannage et FAQ

Problèmes d'Installation

MCP non détecté après l'installation

Chemin incorrect du fichier de configuration

Erreurs de permissions lors de l'exécution de npx

"command not found: planu" après npm install -g

Connectivité avec les Outils d'IA

Claude Code n'affiche pas les outils Planu

Cursor / Windsurf ne reconnaissent pas le MCP après l'installation

Erreur "Tool not found" dans Claude

Comment vérifier l'installation

Problèmes de Flux de Travail des Specs

`validate` échoue toujours même après l'implémentation

Drift détecté incorrectement (faux positif)

Spec non trouvée par les outils

`create_spec` expire sur les grands projets

Performance

Première réponse lente (démarrage à froid)

Le scan de grands projets prend trop de temps

Comment limiter la portée du scan

Obtenir de l'Aide

Que inclure dans un rapport de bug

Signaler un problème