Solução de Problemas e Perguntas Frequentes

Se algo não está funcionando, comece aqui. A maioria dos problemas é resolvida executando:

bash

planu doctor

Este comando verifica sua instalação, arquivos de configuração e conexões com ferramentas de IA, e então indica exatamente o que corrigir.

Problemas de Instalação

MCP não detectado após a instalação

Sua ferramenta de IA precisa ser completamente reiniciada — não apenas a janela, mas todo o processo.

Claude Code:

bash

# Feche o Claude Code completamente e reabra
# Verifique se o Planu aparece na lista:
claude mcp list

Cursor / Windsurf / Zed: Feche o aplicativo pela barra de tarefas ou dock (não apenas a janela), depois reabra.

Ainda não detectado?

Execute planu doctor — ele mostrará quais arquivos de configuração foram gravados e se a ferramenta de IA consegue vê-los.

Caminho incorreto do arquivo de configuração

O Planu grava a configuração em locais diferentes dependendo do seu sistema operacional e do escopo (usuário ou projeto).

Escopo	Claude Code	Cursor	Windsurf
Usuário (macOS/Linux)	`~/.claude/claude.json`	`~/.cursor/mcp.json`	`~/.codeium/windsurf/mcp_config.json`
Usuário (Windows/WSL)	`%APPDATA%\Claude\claude.json`	`%APPDATA%\Cursor\mcp.json`	`%APPDATA%\Windsurf\mcp_config.json`
Projeto	`.claude/claude.json`	`.cursor/mcp.json`	`.windsurf/mcp_config.json`

Como verificar qual arquivo de configuração está ativo

bash

planu doctor

O resultado inclui uma seção Config files com os caminhos exatos que foram gravados e se a ferramenta de IA consegue lê-los.

Para o Claude Code especificamente:

bash

claude mcp list
# A saída esperada inclui:
# planu — planu serve

Erros de permissão ao executar npx

Corrigir permissões do npm no macOS/Linux

Isso acontece quando o diretório global do npm é de propriedade do root. Corrija sem usar sudo:

bash

# Opção 1: Usar um prefixo de propriedade do usuário
mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc  # ou ~/.bashrc
source ~/.zshrc

# Opção 2: Usar nvm (recomendado para desenvolvedores)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
# Depois reinstale o Node.js via nvm

Após corrigir, verifique:

bash

planu install --global

Nunca use sudo com npm

Executar sudo npm install -g mascara problemas de permissão e cria arquivos de propriedade do root, o que gera mais erros depois. Corrija as permissões subjacentes.

"command not found: planu" após npm install -g

O diretório de binários globais do npm não está no seu PATH.

bash

# Encontre onde o npm instala binários globais:
npm config get prefix
# Saída típica: /usr/local  →  binários estão em /usr/local/bin

# Adicione ao PATH se estiver ausente (macOS/Linux):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verifique:
planu --version

Prefira npx em vez da instalação global

Você sempre pode usar planu <comando> sem instalar globalmente. O instalador usa npx internamente, então a instalação global é opcional.

Conectividade com Ferramentas de IA

Claude Code não mostra as ferramentas do Planu

Execute planu doctor para verificar se a configuração foi gravada corretamente
Execute claude mcp list — o Planu deve aparecer no resultado
Inicie uma nova conversa e digite: list my planu tools
Se o Claude Code solicitar permissão, aprove (ou configure aprovação automática — veja Primeiros Passos)

bash

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

As ferramentas MCP são por conversa

As ferramentas carregam quando uma conversa começa. Se instalou o Planu com uma conversa aberta, inicie uma nova.

Cursor / Windsurf não reconhecem o MCP após a instalação

Verificar manualmente o arquivo de configuração

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

json

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

Windsurf — verifique ~/.codeium/windsurf/mcp_config.json (mesma estrutura).

Se o arquivo estiver correto mas a ferramenta não aparecer:

Feche o aplicativo completamente
Reabra
Aguarde ~10 segundos para o servidor MCP iniciar
Abra um novo chat e digite um comando do Planu

Erro "Tool not found" no Claude

Isso significa que o Claude não está conectado ao servidor MCP do Planu na conversa atual.

bash

# Verifique novamente a instalação:
planu doctor

# Adicione novamente se necessário:
claude mcp add planu -- npx -y @planu/cli@latest

Depois inicie uma nova conversa — as conexões MCP são estabelecidas no início de cada conversa.

Como verificar a instalação

bash

planu doctor

Saída 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 com o Fluxo de Specs

`validate` sempre falha mesmo após implementar

A ferramenta validate verifica se seu código corresponde aos critérios de aceitação da spec. Alguns motivos comuns para falhar:

Os critérios são muito vagos — execute check_readiness para melhorá-los antes de implementar
Caminho de projeto incorreto — certifique-se de passar o diretório fonte correto
Spec e código genuinamente não correspondem — verifique quais critérios estão falhando e implemente as partes ausentes

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

O que fazer quando validate continua falhando

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

Isso lista cada critério com seu status de cobertura. Concentre-se nos não cobertos. Se um critério está atendido mas ainda falha, pode estar redigido de uma forma que o validador não consegue detectar — use reconcile_spec para atualizar a redação para corresponder à implementação real.

Drift detectado incorretamente (falso positivo)

detect_drift compara seu código atual com o que a spec descreve. Falsos positivos acontecem quando:

A spec foi escrita com detalhes de implementação muito específicos que mudaram (mas o comportamento é o mesmo)
Você refatorou o código sem atualizar a spec

Se o drift for intencional (a spec precisa ser atualizada para corresponder à implementação real):

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

reconcile_spec guia você por cada mudança e pede aprovação por mudança antes de atualizar a spec.

Drift nem sempre é ruim

Drift significa "o plano e o código discordam." Às vezes o código está certo e o plano está desatualizado — é aí que você reconcilia. Às vezes o código está errado — é aí que você corrige o código.

Spec não encontrada pelas ferramentas

As ferramentas identificam specs por ID (ex.: SPEC-003) dentro de um projeto. Se uma spec não for encontrada:

bash

# Verifique o ID do projeto para o diretório atual:
planu status

# Liste todas as specs do projeto:
# Prompt: "List all specs in project [id]"

Causas comuns:

Usar o ID de projeto incorreto (o Planu usa um hash do caminho do projeto)
A spec foi criada em um diretório diferente do atual

`create_spec` demora muito em projetos grandes

Em projetos muito grandes (milhões de arquivos), o escaneamento inicial pode demorar mais que o esperado.

Limite o escopo do escaneamento:

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

Você também pode pré-executar o escaneamento uma vez para armazenar em cache os resultados:

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

Chamadas subsequentes a create_spec no mesmo projeto usarão o escaneamento em cache.

Desempenho

Primeira resposta lenta (cold start)

A primeira resposta em uma nova conversa é mais lenta porque:

npx baixa a versão mais recente do @planu/cli (alguns segundos)
O servidor MCP inicializa e carrega os dados do seu projeto

Este custo ocorre uma vez por conversa. Chamadas de ferramentas subsequentes são rápidas.

Reduzir o tempo de cold start

Use --prefer-online (já incluído na configuração padrão) para armazenar o pacote em cache localmente. Após a primeira execução, o npx reutiliza a versão em cache e só verifica atualizações.

Escaneamento de projetos grandes demora muito

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

Você também pode excluir diretórios listando-os:

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

Como limitar o escopo do escaneamento

Passe restrições de caminho explícitas ao criar specs ou escanear:

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

O Planu respeita esses limites e não analisará arquivos fora do caminho especificado.

Obtendo Ajuda

Se nenhuma das etapas acima resolveu seu problema, colete informações de diagnóstico primeiro:

bash

planu doctor

Copie o resultado completo e inclua no seu relatório de bug.

O que incluir em um relatório de bug

Resultado completo de planu doctor
O comando ou prompt que desencadeou o problema
A mensagem de erro exata ou o comportamento inesperado
Seu sistema operacional e versão do Node.js: node --version
Sua ferramenta de IA e versão (ex.: Claude Code 1.x, Cursor 0.4x)

Reportar um problema

Peça ao agente Planu instalado para usar submit_feedback com a saída de planu doctor e uma descrição do esperado versus o ocorrido. Se o Planu não iniciar, use o canal público do Discord.

Suporte da comunidade

Pesquise nas issues existentes antes de abrir uma nova — seu problema pode já ter solução ou uma alternativa temporária.

Solução de Problemas e Perguntas Frequentes ​

Problemas de Instalação ​

MCP não detectado após a instalação ​

Caminho incorreto do arquivo de configuração ​

Erros de permissão ao executar npx ​

"command not found: planu" após npm install -g ​

Conectividade com Ferramentas de IA ​

Claude Code não mostra as ferramentas do Planu ​

Cursor / Windsurf não reconhecem o MCP após a instalação ​

Erro "Tool not found" no Claude ​

Como verificar a instalação ​

Problemas com o Fluxo de Specs ​

validate sempre falha mesmo após implementar ​

Drift detectado incorretamente (falso positivo) ​

Spec não encontrada pelas ferramentas ​

create_spec demora muito em projetos grandes ​

Desempenho ​

Primeira resposta lenta (cold start) ​

Escaneamento de projetos grandes demora muito ​

Como limitar o escopo do escaneamento ​

Obtendo Ajuda ​

O que incluir em um relatório de bug ​

Reportar um problema ​

Solução de Problemas e Perguntas Frequentes

Problemas de Instalação

MCP não detectado após a instalação

Caminho incorreto do arquivo de configuração

Erros de permissão ao executar npx

"command not found: planu" após npm install -g

Conectividade com Ferramentas de IA

Claude Code não mostra as ferramentas do Planu

Cursor / Windsurf não reconhecem o MCP após a instalação

Erro "Tool not found" no Claude

Como verificar a instalação

Problemas com o Fluxo de Specs

`validate` sempre falha mesmo após implementar

Drift detectado incorretamente (falso positivo)

Spec não encontrada pelas ferramentas

`create_spec` demora muito em projetos grandes

Desempenho

Primeira resposta lenta (cold start)

Escaneamento de projetos grandes demora muito

Como limitar o escopo do escaneamento

Obtendo Ajuda

O que incluir em um relatório de bug

Reportar um problema