a9a7a328e6
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD across contents and paths, upstream package/repo coordinates -> @golem15/msd-core and golem15com/msd-core. Deep links into upstream history, sibling upstream packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is. Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line, package/plugin identity, regenerated lockfile, install-tree fixtures, derived registries and benchmark baseline; migration checksum baseline re-locked (MSD keeps its own install state, so no install had applied the old sums); sort-order and regex-escaped expectations in tests adjusted.
11 KiB
Como recuperar e solucionar problemas
Objetivo: Identificar e corrigir problemas comuns — desde contexto perdido e estado corrompido até falhas de instalação e erros de permissão — usando uma estrutura de receitas condicionais.
Pré-requisitos: MSD Core está instalado. Para problemas específicos de instalação, consulte Instalar no seu ambiente de execução.
Problemas de contexto e sessão
Se você perdeu o controle de onde está
/msd-progress
Lê todos os arquivos de estado e informa exatamente onde você está e o que fazer a seguir.
Para avançar automaticamente para o próximo passo correto:
/msd-progress --next
Se você está iniciando uma nova sessão e precisa restaurar o contexto
/msd-resume-work
Restaura o contexto completo da sua sessão a partir do último handoff, incluindo a fase atual, decisões de planejamento e onde o trabalho foi interrompido.
Se a qualidade está caindo durante uma sessão longa
Limpe sua janela de contexto entre comandos principais:
/clear
Em seguida, restaure o estado:
/msd-resume-work
O MSD foi projetado em torno de contextos frescos. Cada subagente já recebe uma janela limpa de 200k. A sessão principal se degrada com o tempo — limpá-la e retomar é o remédio correto, não continuar forçando.
Se você quer salvar o contexto antes de parar
/msd-pause-work
Cria .planning/HANDOFF.json com sua posição atual. Adicione --report para também gravar um resumo pós-sessão em .planning/reports/:
/msd-pause-work --report
Problemas de integridade do planejamento
Se a integridade de .planning/ está incerta
/msd-health
Relata o status entre erros, avisos e notas informativas:
| Status | Significado |
|---|---|
HEALTHY |
Todos os artefatos esperados estão presentes e bem formados |
DEGRADED |
Avisos que devem ser tratados, mas o trabalho pode continuar |
BROKEN |
Erros críticos que bloquearão a execução |
Problemas comuns que podem ser reparados automaticamente (erros E004, E005; avisos W003, W008):
/msd-health --repair
Isso recria o STATE.md ausente, redefine um config.json corrompido para os padrões e adiciona quaisquer chaves de configuração ausentes. Não vai sobrescrever PROJECT.md ou ROADMAP.md.
Se STATE.md referencia uma fase que não existe
Isso gera o aviso W002. Use a CLI de estado para diagnosticar e reparar:
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state validate
Visualize o que uma sincronização mudaria sem gravar:
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync --verify
Aplique a sincronização:
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync
Esses comandos reconstroem o STATE.md a partir do estado real do projeto em disco. Substituem a edição manual do STATE.md.
Se você vê "Project already initialised"
.planning/PROJECT.md já existe. /msd-new-project é uma verificação de segurança. Se você realmente quer começar do zero, delete o diretório .planning/ primeiro:
rm -rf .planning/
Em seguida, execute novamente /msd-new-project.
Se a utilização da janela de contexto está alta
/msd-health --context
Verifica a proteção de utilização da janela de contexto. Emite aviso em 60%, crítico em 70%. Se você estiver acima do limite de aviso, execute /clear seguido de /msd-resume-work antes de iniciar o próximo comando principal.
Problemas de execução
Se um executor recebe "Permission denied" em comandos Bash
Os subagentes msd-executor do MSD precisam de acesso Bash com permissão de escrita. Adicione os padrões necessários em ~/.claude/settings.json sob permissions.allow. No mínimo:
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git checkout:*)"
Para padrões específicos de stack (Rails, Python, Node, Rust), consulte a tabela completa em docs/USER-GUIDE.md em "Executor Subagent Gets Permission denied".
Alternativa por projeto: adicione o mesmo bloco em .claude/settings.local.json na raiz do seu projeto.
Se a execução falha ou produz stubs
Verifique se o plano é ambicioso demais. Os planos devem ter no máximo duas ou três tarefas. Se as tarefas forem muito grandes, elas excedem o que uma única janela de contexto consegue produzir de forma confiável. Replaneje a fase com escopo menor:
/msd-plan-phase 1
Para diagnóstico sistemático do que deu errado, consulte Depurar uma execução com falha.
Se a execução paralela causa erros de bloqueio de build ou falhas no hook de pré-commit
Isso é causado por múltiplos agentes acionando ferramentas de build simultaneamente. O MSD lida com isso automaticamente desde a v1.26. Se você estiver em uma versão mais antiga, ou ainda vendo contenção, desative a execução paralela:
/msd-settings
Defina parallelization.enabled como false.
Se um subagente parece ter falhado, mas commits foram feitos
Verifique o log do git antes de concluir que algo quebrou:
git log --oneline -10
Um bug de classificação conhecido do Claude Code pode reportar falha enquanto o trabalho foi concluído com sucesso. Os orquestradores do MSD verificam a saída real, mas se você vir uma discrepância, os commits são a fonte da verdade.
Problemas de plano e fase
Se os planos parecem errados ou desalinhados com sua intenção
Execute /msd-discuss-phase N antes de planejar. A maioria dos problemas de qualidade do plano vem de suposições que o CONTEXT.md teria prevenido:
/msd-discuss-phase 1
Para ver quais suposições o MSD está fazendo atualmente sem iniciar uma sessão completa:
/msd-discuss-phase 3 --assumptions
Se você precisa mudar algo após a execução
Não execute novamente /msd-execute-phase. Use /msd-quick para correções direcionadas:
/msd-quick "Fix the login button not responding on mobile Safari"
Ou use /msd-verify-work N para identificar e corrigir problemas sistematicamente por meio de UAT.
Se um comando parece congelado em "Spawning…"
Aguarde. Os subagentes do MSD são executados em uma janela de contexto separada. O trabalho deles é invisível para a sessão pai enquanto está em andamento. A nota de atividade na linha de spawn confirma que isso é esperado. Agentes de pesquisa e planejamento rotineiramente levam de 1 a 5 minutos; agentes de verificação podem levar mais tempo em fases grandes.
Não interrompa a sessão. Encerrá-la descarta o trabalho em andamento do subagente.
Se já passou mais de 10 minutos, verifique se a tarefa do agente ainda aparece como ativa na barra lateral do Claude Code.
Problemas de estado do fluxo de trabalho
Se o fluxo de trabalho parece corrompido ou o estado está inconsistente
/msd-forensics
Ou com uma descrição:
/msd-forensics "Phase 3 execution stalled after wave 1"
/msd-forensics executa uma investigação post-mortem: anomalias no histórico do git, integridade dos artefatos, consistência do STATE.md, trabalho não commitado e worktrees órfãs. Grava um relatório em .planning/forensics/ e apresenta etapas de remediação recomendadas. É somente leitura e nunca modifica os arquivos do seu projeto.
Se você precisa reverter uma fase ou plano
/msd-undo --phase 03 # Reverte todos os commits da fase 3
/msd-undo --plan 03-02 # Reverte os commits do plano 02 da fase 3
/msd-undo --last 5 # Escolhe interativamente entre os 5 commits MSD mais recentes
/msd-undo verifica as fases dependentes antes de reverter e sempre apresenta uma confirmação.
Problemas de instalação e atualização
Se o MSD não é reconhecido após a instalação
Reinicie seu ambiente de execução. O MSD instala comandos slash no diretório de comandos do seu ambiente de execução (por exemplo, ~/.claude/commands/msd/). A maioria dos ambientes de execução descobre novos comandos apenas na inicialização.
Se o problema persistir, verifique a instalação:
npx @golem15/msd-core@latest --claude --local
Para caminhos de instalação específicos do ambiente de execução e solução de problemas, consulte Instalar no seu ambiente de execução.
Se uma atualização sobrescreveu suas alterações locais
Desde a v1.17, o instalador faz backup dos arquivos modificados localmente em msd-local-patches/. Reaplique suas alterações:
/msd-update --reapply
Se você não consegue atualizar via npm
Se npx @golem15/msd-core falhar devido a interrupções do npm ou restrições de rede, consulte docs/manual-update.md para um procedimento de atualização manual passo a passo que funciona sem acesso ao npm.
Para atualizações de rotina, consulte Atualizar o MSD.
Problemas de custo
Se os custos do modelo estão muito altos
Mude para o perfil de orçamento:
/msd-config --profile budget
Desative os agentes de pesquisa e verificação de plano via configurações se o domínio for familiar:
/msd-settings
Audite também quais servidores MCP estão habilitados. Cada servidor MCP habilitado injeta seu esquema de ferramentas em cada turno. Ferramentas específicas de navegador e plataforma podem custar mais de 20k tokens cada. Desabilite os que a fase atual não precisa em .claude/settings.json:
{
"disabledMcpjsonServers": ["playwright", "mac-tools"]
}
Referência rápida de recuperação
| Problema | Solução |
|---|---|
| Contexto perdido ou nova sessão | /msd-resume-work ou /msd-progress |
| Não sabe qual é o próximo passo | /msd-progress --next |
| Fase deu errado | /msd-undo --phase NN, depois replaneje |
| Algo quebrou | /msd-debug "descrição" (adicione --diagnose para análise sem correções) |
| STATE.md fora de sincronia | state validate depois state sync |
Integridade de .planning/ incerta |
/msd-health, depois /msd-health --repair |
| Estado do fluxo de trabalho parece corrompido | /msd-forensics |
| Correção direcionada rápida | /msd-quick |
| Plano não corresponde à sua visão | /msd-discuss-phase N depois replaneje |
| Custos elevados | /msd-config --profile budget e /msd-settings para desativar agentes |
| Atualização quebrou alterações locais | /msd-update --reapply |
| Quer resumo da sessão | /msd-pause-work --report |
| Erros de build por execução paralela | Atualize o MSD ou defina parallelization.enabled: false |