7.8 KiB
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:
/gsd-discuss-phase [N]— trava preferências de implementação/gsd-ui-phase [N]— contrato visual para fases frontend/gsd-plan-phase [N]— pesquisa + plano + validação/gsd-execute-phase [N]— execução em ondas paralelas/gsd-verify-work [N]— UAT manual com diagnóstico/gsd-ship [N]— cria PR (opcional)
Para iniciar projeto novo:
/gsd-new-project
Para seguir automaticamente o próximo passo:
/gsd-progress --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-phasedepois de/gsd-discuss-phasee antes de/gsd-plan-phase. - Rode
/gsd-ui-reviewapó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-add-backlog "Camada GraphQL"
/gsd-add-backlog "Responsividade mobile"
Promover/revisar:
/gsd-review-backlog
Seeds
Seeds guardam ideias futuras com condição de gatilho:
/gsd-plant-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-progress --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-set-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-set-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-add-phase, /gsd-insert-phase, /gsd-remove-phase |
| Bug em workflow | /gsd-forensics |
| Correção pontual | /gsd-quick |
| Custo alto | /gsd-set-profile budget |
| Não sabe próximo passo | /gsd-progress --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.