Solución de Problemas y Preguntas Frecuentes

Si algo no funciona, empieza aquí. La mayoría de los problemas se resuelven ejecutando:

planu doctor

Este comando verifica tu instalación, archivos de configuración y conexiones con herramientas de IA, y luego te indica exactamente qué corregir.

---

Problemas de Instalación

El MCP no se detecta después de la instalación

Tu herramienta de IA necesita reiniciarse completamente — no solo la ventana, sino todo el proceso.

Claude Code:

# Cierra Claude Code completamente y vuelve a abrirlo
# Verifica que Planu aparezca en la lista:
claude mcp list

Cursor / Windsurf / Zed: Cierra la aplicación desde la barra de tareas o el dock (no solo la ventana), luego vuelve a abrirla.

¿Sigue sin detectarse?

Ejecuta planu doctor — mostrará qué archivos de configuración se escribieron y si la herramienta de IA puede verlos.

---

Ruta incorrecta del archivo de configuración

Planu escribe la configuración en ubicaciones distintas según tu sistema operativo y el alcance (usuario o proyecto).

Alcance	Claude Code	Cursor	Windsurf
Usuario (macOS/Linux)	~/.claude/claude.json	~/.cursor/mcp.json	~/.codeium/windsurf/mcp_config.json
Usuario (Windows/WSL)	%APPDATA%\Claude\claude.json	%APPDATA%\Cursor\mcp.json	%APPDATA%\Windsurf\mcp_config.json
Proyecto	.claude/claude.json	.cursor/mcp.json	.windsurf/mcp_config.json

Cómo verificar qué archivo de configuración está activo

planu doctor

El resultado incluye una sección Config files con las rutas exactas que se escribieron y si la herramienta de IA puede leerlos.

Para Claude Code específicamente:

claude mcp list
# La salida esperada incluye:
# planu — planu serve

---

Errores de permisos al ejecutar npx

Corregir permisos de npm en macOS/Linux

Esto ocurre cuando el directorio global de npm es propiedad de root. Corrígelo sin usar sudo:

# Opción 1: Usar un prefijo propio del usuario
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # o ~/.bashrc
source ~/.zshrc

# Opción 2: Usar nvm (recomendado para desarrolladores)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Luego reinstala Node.js mediante nvm

Después de corregirlo, verifica:

planu install --global

Nunca uses sudo con npm

Ejecutar sudo npm install -g enmascara problemas de permisos y crea archivos propiedad de root, lo que genera más errores después. Corrige los permisos subyacentes en su lugar.

---

"command not found: planu" después de npm install -g

El directorio de binarios globales de npm no está en tu PATH.

# Encuentra dónde npm instala los binarios globales:
npm config get prefix
# Salida típica: /usr/local  →  los binarios están en /usr/local/bin

# Agrégalo al PATH si falta (macOS/Linux):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verifica:
planu --version

Prefiere npx sobre la instalación global

Siempre puedes usar planu <comando> sin instalar globalmente. El instalador usa npx internamente, por lo que la instalación global es opcional.

---

Conectividad con Herramientas de IA

Claude Code no muestra las herramientas de Planu

1. Ejecuta planu doctor para verificar que la configuración se escribió correctamente
2. Ejecuta claude mcp list — Planu debe aparecer en el resultado
3. Inicia una nueva conversación y escribe: list my planu tools
4. Si Claude Code pide permiso, apruébalo (o configura la aprobación automática — ver Primeros Pasos)

claude mcp list
# Resultado esperado:
# planu    planu serve    [active]

Las herramientas MCP son por conversación

Las herramientas se cargan cuando comienza una conversación. Si instalaste Planu mientras una conversación estaba abierta, inicia una nueva.

---

Cursor / Windsurf no reconocen el MCP después de la instalación

Verificar manualmente el archivo de configuración

Cursor — verifica ~/.cursor/mcp.json:

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

Windsurf — verifica ~/.codeium/windsurf/mcp_config.json (misma estructura).

Si el archivo es correcto pero la herramienta no aparece:

1. Cierra la aplicación completamente
2. Vuelve a abrirla
3. Espera ~10 segundos para que el servidor MCP inicie
4. Abre un nuevo chat y escribe un comando de Planu

---

Error "Tool not found" en Claude

Esto significa que Claude no está conectado al servidor MCP de Planu en la conversación actual.

# Vuelve a verificar la instalación:
planu doctor

# Agrégalo nuevamente si es necesario:
claude mcp add planu -- npx -y @planu/cli@latest

Luego inicia una nueva conversación — las conexiones MCP se establecen al inicio de cada conversación.

---

Cómo verificar la instalación

planu doctor

Salida esperada:

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

---

Problemas con el Flujo de Specs

validate siempre falla incluso después de implementar

La herramienta validate verifica si tu código coincide con los criterios de aceptación de la spec. Algunas razones comunes por las que falla:

1. Los criterios son demasiado vagos — ejecuta check_readiness para mejorarlos antes de implementar
2. Ruta de proyecto incorrecta — asegúrate de pasar el directorio fuente correcto
3. La spec y el código genuinamente no coinciden — verifica cuáles criterios fallan e implementa las partes faltantes

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

Qué hacer cuando validate sigue fallando

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

Esto lista cada criterio con su estado de cobertura. Concéntrate en los no cubiertos. Si un criterio se cumple pero sigue fallando, puede estar redactado de una manera que el validador no puede detectar — usa reconcile_spec para actualizar la redacción y que coincida con la implementación real.

---

Drift detectado incorrectamente (falso positivo)

detect_drift compara tu código actual con lo que describe la spec. Los falsos positivos ocurren cuando:

• La spec fue escrita con detalles de implementación muy específicos que cambiaron (pero el comportamiento es el mismo)
• Refactorizaste código sin actualizar la spec

Si el drift es intencional (la spec necesita actualizarse para coincidir con la implementación real):

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

reconcile_spec te guía por cada cambio y pide tu aprobación por cambio antes de actualizar la spec.

El drift no siempre es malo

Drift significa "el plan y el código no coinciden." A veces el código es correcto y el plan está desactualizado — ahí es cuando se reconcilia. A veces el código es el que está mal — ahí es cuando se corrige el código.

---

La spec no es encontrada por las herramientas

Las herramientas identifican las specs por ID (p. ej., SPEC-003) dentro de un proyecto. Si una spec no se encuentra:

# Verifica el ID del proyecto para el directorio actual:
planu status

# Lista todas las specs del proyecto:
# Prompt: "List all specs in project [id]"

Causas comunes:

• Usar el ID de proyecto incorrecto (Planu usa un hash de la ruta del proyecto)
• La spec fue creada en un directorio distinto al actual

---

create_spec tarda demasiado en proyectos grandes

En proyectos muy grandes (millones de archivos), el escaneo inicial puede tardar más de lo esperado.

Limita el alcance del escaneo:

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

También puedes ejecutar el escaneo una vez para almacenar los resultados en caché:

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

Las llamadas posteriores a create_spec en el mismo proyecto usarán el escaneo en caché.

---

Rendimiento

Primera respuesta lenta (arranque en frío)

La primera respuesta en una nueva conversación es más lenta porque:

1. npx descarga la versión más reciente de @planu/cli (algunos segundos)
2. El servidor MCP se inicializa y carga los datos de tu proyecto

Este costo es único por conversación. Las llamadas de herramientas posteriores son rápidas.

Reducir el tiempo de arranque en frío

Usa --prefer-online (ya incluido en la configuración predeterminada) para almacenar el paquete en caché localmente. Después de la primera ejecución, npx reutiliza la versión en caché y solo verifica actualizaciones.

---

El escaneo de proyectos grandes tarda demasiado

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

También puedes excluir directorios listándolos:

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

---

Cómo limitar el alcance del escaneo

Pasa restricciones de ruta explícitas al crear specs o al escanear:

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

Planu respeta estos límites y no analizará archivos fuera de la ruta especificada.

---

Obtener Ayuda

Si ninguno de los pasos anteriores resolvió tu problema, recopila información de diagnóstico primero:

planu doctor

Copia el resultado completo e inclúyelo en tu reporte de bug.

Qué incluir en un reporte de bug

• Resultado completo de planu doctor
• El comando o prompt que desencadenó el problema
• El mensaje de error exacto o el comportamiento inesperado
• Tu sistema operativo y versión de Node.js: node --version
• Tu herramienta de IA y versión (p. ej., Claude Code 1.x, Cursor 0.4x)

Reportar un problema

Pide a tu agente Planu instalado que use submit_feedback con el resultado de planu doctor y una descripción de lo esperado frente a lo ocurrido. Si Planu no inicia, usa el canal público de Discord.

Soporte de la comunidad

Busca en los issues existentes antes de abrir uno nuevo — es posible que tu problema ya tenga solución o una alternativa temporal.