msd-core/docs/pt-BR/USER-GUIDE.md

Guia do Usuário do GSD

Referência detalhada de workflows, troubleshooting e configuração. Para setup rápido, veja o README.

---

Sumário

• Fluxo de trabalho
• Contrato de UI
• Backlog e Threads
• Workstreams
• Segurança
• Referência de comandos
• Configuração
• Exemplos de uso
• Troubleshooting
• Recuperação rápida

---

Fluxo de trabalho

Fluxo recomendado por fase:

1. /gsd-discuss-phase [N] — trava preferências de implementação
2. /gsd-ui-phase [N] — contrato visual para fases frontend
3. /gsd-plan-phase [N] — pesquisa + plano + validação
4. /gsd-execute-phase [N] — execução em ondas paralelas
5. /gsd-verify-work [N] — UAT manual com diagnóstico
6. /gsd-ship [N] — cria PR (opcional)

Para iniciar projeto novo:

/gsd-new-project

Para seguir automaticamente o próximo passo:

/gsd-next

Nyquist Validation

Durante plan-phase, o GSD pode mapear requisitos para comandos de teste automáticos antes da implementação. Isso gera {phase}-VALIDATION.md e aumenta a confiabilidade de verificação pós-execução.

Desativar:

{
  "workflow": {
    "nyquist_validation": false
  }
}

Modo de discussão por suposições

Com workflow.discuss_mode: "assumptions", o GSD analisa o código antes de perguntar, apresenta suposições estruturadas e pede apenas correções.

---

Contrato de UI

Comandos

Comando	Descrição
/gsd-ui-phase [N]	Gera contrato de design UI-SPEC.md para a fase
/gsd-ui-review [N]	Auditoria visual retroativa em 6 pilares

Quando usar

• Rode /gsd-ui-phase depois de /gsd-discuss-phase e antes de /gsd-plan-phase.
• Rode /gsd-ui-review após execução/validação para avaliar qualidade visual e consistência.

Configurações relacionadas

Setting	Padrão	O que controla
workflow.ui_phase	true	Gera contratos de UI para fases frontend
workflow.ui_safety_gate	true	Ativa gate de segurança para componentes de registry

---

Backlog e Threads

Backlog (999.x)

Ideias fora da sequência ativa vão para backlog:

/gsd-capture --backlog "Camada GraphQL"
/gsd-capture --backlog "Responsividade mobile"

Promover/revisar:

/gsd-review-backlog

Seeds

Seeds guardam ideias futuras com condição de gatilho:

/gsd-capture --seed "Adicionar colaboração real-time quando infra de WebSocket estiver pronta"

Threads persistentes

Threads são contexto leve entre sessões:

/gsd-thread
/gsd-thread fix-deploy-key-auth
/gsd-thread "Investigar timeout TCP"

---

Workstreams

Workstreams permitem trabalho paralelo sem colisão de estado de planejamento.

Comando	Função
/gsd-workstreams create <name>	Cria workstream isolado
/gsd-workstreams switch <name>	Troca workstream ativo
/gsd-workstreams list	Lista workstreams
/gsd-workstreams complete <name>	Finaliza e arquiva workstream

workstreams compartilham o mesmo código/git, mas isolam artefatos de .planning/.

---

Segurança

O GSD aplica defesa em profundidade:

• prevenção de path traversal em entradas de arquivo
• detecção de prompt injection em texto do usuário
• hooks de proteção para escrita em .planning/
• scanner CI para padrões de injeção em agentes/workflows/comandos

Para arquivos sensíveis, use deny list no Claude Code.

---

Referência de comandos

Fluxo principal

Comando	Quando usar
/gsd-new-project	Início de projeto
/gsd-discuss-phase [N]	Definir preferências antes do plano
/gsd-plan-phase [N]	Criar e validar planos
/gsd-execute-phase [N]	Executar planos em ondas
/gsd-verify-work [N]	UAT manual
/gsd-ship [N]	Gerar PR da fase
/gsd-next	Próximo passo automático

Gestão e utilidades

Comando	Quando usar
/gsd-progress	Ver status atual
/gsd-resume-work	Retomar sessão
/gsd-pause-work	Pausar com handoff
/gsd-session-report	Resumo da sessão
/gsd-quick	Tarefa ad-hoc com garantias GSD
/gsd-debug [desc]	Debug sistemático
/gsd-forensics	Diagnóstico de workflow quebrado
/gsd-settings	Ajustar workflow/modelos
/gsd-config --profile <profile>	Troca rápida de perfil

Para lista completa e flags avançadas, consulte Command Reference.

---

Configuração

Arquivo de configuração: .planning/config.json

Núcleo

Setting	Opções	Padrão
mode	interactive, yolo	interactive
granularity	coarse, standard, fine	standard
model_profile	quality, balanced, budget, inherit	balanced

Workflow

Setting	Padrão
workflow.research	true
workflow.plan_check	true
workflow.verifier	true
workflow.nyquist_validation	true
workflow.ui_phase	true
workflow.ui_safety_gate	true

Perfis de modelo

Perfil	Uso recomendado
quality	trabalho crítico, maior qualidade
balanced	padrão recomendado
budget	reduzir custo de tokens
inherit	seguir modelo da sessão/runtime

Detalhes completos: Configuration Reference.

---

Exemplos de uso

Projeto novo

claude --dangerously-skip-permissions
/gsd-new-project
/gsd-discuss-phase 1
/gsd-ui-phase 1
/gsd-plan-phase 1
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1

Código já existente

/gsd-map-codebase
/gsd-new-project

Correção rápida

/gsd-quick
> "Corrigir botão de login no mobile Safari"

Preparação para release

/gsd-audit-milestone
/gsd-complete-milestone

---

Troubleshooting

"Project already initialized"

.planning/PROJECT.md já existe. Apague .planning/ se quiser reiniciar do zero.

Sessão longa degradando contexto

Use /clear entre etapas grandes e retome com /gsd-resume-work ou /gsd-progress.

Plano desalinhado

Rode /gsd-discuss-phase [N] antes do plano e valide suposições com /gsd-list-phase-assumptions [N].

Execução falhou ou saiu com stubs

Replaneje com escopo menor (tarefas menores por plano).

Custo alto

Use perfil budget:

/gsd-config --profile budget

Runtime não-Claude (Codex/OpenCode/Gemini/Kilo)

Use resolve_model_ids: "omit" para deixar o runtime resolver modelos padrão.

---

Recuperação rápida

Problema	Solução
Perdeu contexto	/gsd-resume-work ou /gsd-progress
Fase deu errado	git revert + replanejar
Precisa alterar escopo	/gsd-phase, /gsd-phase --insert, /gsd-phase --remove
Bug em workflow	/gsd-forensics
Correção pontual	/gsd-quick
Custo alto	/gsd-config --profile budget
Não sabe próximo passo	/gsd-next

---

Estrutura de arquivos do projeto

.planning/
  PROJECT.md
  REQUIREMENTS.md
  ROADMAP.md
  STATE.md
  config.json
  MILESTONES.md
  HANDOFF.json
  research/
  reports/
  todos/
  debug/
  codebase/
  phases/
    XX-phase-name/
      XX-YY-PLAN.md
      XX-YY-SUMMARY.md
      CONTEXT.md
      RESEARCH.md
      VERIFICATION.md
      XX-UI-SPEC.md
      XX-UI-REVIEW.md
  ui-reviews/

Note

Esta é a versão pt-BR do guia para uso diário. Para detalhes técnicos exatos e cobertura completa de parâmetros avançados, consulte também o guia original em inglês.