get-shit-done（GSD）用户指南：Phase 工作流、命令、配置与故障恢复的完整实战手册

本篇技术指南以 get-shit-done（GSD，下称 GSD）的 pt-BR 用户指南 docs/pt-BR/USER-GUIDE.md 为骨架展开，讲解这套运行在 Claude Code 等 AI 编码终端上的 spec-driven 开发系统如何按"讨论 → 计划 → 执行 → 验证 → 发布"的阶段流水线组织项目。读完你将对 GSD 的分阶段推荐流程、UI 设计契约、Backlog/线程/Workstream 三大上下文机制、纵深安全模型、config.json 关键参数，以及从"Project already initialized"到非 Claude 运行时的常见故障恢复拥有一套可直接落地的实操方案。英文权威版本见 docs/USER-GUIDE.md，pt-BR 版定位为日常速用参考。

---

分阶段推荐工作流（Phase 工作流）

GSD 把一次开发拆成可独立验证的 phase（阶段），每个阶段按如下顺序推进：

1. /gsd-discuss-phase [N] — 在计划前锁定你的实现偏好
2. /gsd-ui-phase [N] — 为前端类阶段产出视觉设计契约
3. /gsd-plan-phase [N] — 研究 + 计划 + 校验
4. /gsd-execute-phase [N] — 以并行 wave（波次）执行
5. /gsd-verify-work [N] — 手动 UAT 并附自动诊断
6. /gsd-ship [N] — 生成 PR（可选）

全新项目从 /gsd-new-project 开始；想让 GSD 自动接管"下一步做什么"，运行：

/gsd-progress --next

/gsd-progress --next 会读取项目状态并自动路由：无项目时建议 /gsd-new-project、阶段待讨论时执行 /gsd-discuss-phase、待计划时执行 /gsd-plan-phase、待执行时执行 /gsd-execute-phase、待验证时执行 /gsd-verify-work、全部完成时建议 /gsd-complete-milestone（参见 docs/COMMANDS.md）。

端到端的效果

以文档中经典的"Express 中间件验证 webhook 签名"为例，各命令的产物构成一条清晰的证据链：

• /gsd-new-project 产出 .planning/ 下的 PROJECT.md、REQUIREMENTS.md（形如 REQ-001: 校验签名头）、ROADMAP.md（Phase 1 状态 pending）、STATE.md（会话记忆与当前位置）；
• /gsd-discuss-phase 1 只问"怎么做"——如"无效签名如何处理？""容差窗口按路由还是全局配置？"——并把结论写入 .planning/phases/01-core-middleware/CONTEXT.md 的 Implementation Decisions；
• /gsd-plan-phase 1 并行启动 4 个研究 agent（stack / features / architecture / pitfalls），由 planner 阅读 CONTEXT.md + 研究结论产出原子任务计划 01-01-PLAN.md、01-02-PLAN.md，每个计划带 XML 结构的 type="auto" 任务与可执行的 <verify> 命令（如 npm test -- --grep "validateSignature"），plan-checker 校验通过才落盘；
• /gsd-execute-phase 1 把相互独立的计划放入同一 wave 并行执行，依赖项则排入下一 wave；每个计划由全新 200k 上下文的 executor 执行并以原子提交落库，结束后由 verifier 对照阶段目标逐条核对 REQ 并写 VERIFICATION.md（PASS/FAIL）；
• /gsd-verify-work 1 把阶段目标抽取成可测试验收项逐条询问，任一失败即进入诊断流程——在英文权威版示例中，它能把 500 错误自动归因到 crypto.timingSafeEqual 对不同长度 buffer 抛出的 TypeError，并直接生成修复计划 01-03-PLAN.md；
• /gsd-ship 1 依据规划产物自动生成包含 Summary、Changes、Requirements Addressed、Verification、Key Decisions 等必需章节的 PR body。

多阶段项目只需把 1 换成 2、3……循环推进；全部完成后用 /gsd-audit-milestone 核对交付、/gsd-complete-milestone 归档并打 release tag。完整生命周期与执行波次协调图见 docs/USER-GUIDE.md。

常用 flag 速查

英文权威版汇总了贯穿上述流程的高频参数，可在命令后追加使用：

Flag	命令	适用场景
--auto	/gsd-new-project	跳过交互提问，直接从 PRD 文件摄取
--research	/gsd-quick	给临时任务附加研究 agent
--validate	/gsd-quick	附加计划校验与执行后验证
--chain	/gsd-discuss-phase	不中断地自动串联 discuss → plan → execute
--skip-research	/gsd-plan-phase	领域已熟悉时跳过研究 agent
--draft	/gsd-ship	以 Draft PR 而非待评审 PR 创建

Nyquist Validation（验证前置映射）

在 plan-phase 研究阶段，GSD 可以把每条需求映射到自动化测试命令，在任何代码写出之前就规划好反馈机制；产出 {phase}-VALIDATION.md 作为该阶段的反馈契约。为此 plan-checker 会以"第 8 个校验维度"强制约束：任务的计划若缺少自动化验证命令将不被批准。对快速原型等不需要测试基建的阶段，可关闭：

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

对在 Nyquist 上线前就已执行的旧阶段，可用 /gsd-validate-phase N 做追溯性审计补覆盖；auditor 只允许改动测试文件与 VALIDATION.md，绝不修改实现代码。

基于假设的讨论模式（Assumptions mode）

将 workflow.discuss_mode 设为 "assumptions" 后，/gsd-discuss-phase 的行为反转：GSD 先读取你的代码库与既有约定，生成一份结构化的实现假设清单（技术选型、模式、文件位置），只要求你纠正错误或补充遗漏，而非开放式的逐一提问。适合已经熟悉自己代码库的开发者、模式已固化的项目，以及希望压缩讨论时间的快速迭代场景。两种模式的完整对照见 docs/workflow-discuss-mode.md。

---

UI 设计契约（UI Contract）

AI 生成的前端风格不统一，往往不是因为模型能力不足，而是执行前缺少共享的设计契约——五个组件分别用不同的间距刻度、色彩约定写出来，自然得到五种观感。GSD 用两条命令把设计决策前置和收尾：

命令	说明
/gsd-ui-phase [N]	为前端阶段生成设计契约 UI-SPEC.md
/gsd-ui-review [N]	对已实现 UI 做 6 支柱的追溯性视觉审计

推荐时机：/gsd-ui-phase 在 /gsd-discuss-phase 之后、/gsd-plan-phase 之前运行；/gsd-ui-review 在 /gsd-execute-phase 或 /gsd-verify-work 之后运行。

/gsd-ui-phase 的流程会读取 CONTEXT.md/RESEARCH.md/REQUIREMENTS.md 既有决策，探测设计系统现状（shadcn components.json、Tailwind 配置、既有 tokens），只询问尚未回答的设计契约问题，最终把 {phase}-UI-SPEC.md 写入阶段目录并对照 6 个维度（文案、视觉、色彩、字体、间距、registry 安全）自校验。遇到 React/Next.js/Vite 项目且尚无 components.json 时，UI researcher 会提议初始化 shadcn：访问 ui.shadcn.com/create 生成 preset 字符串，用 npx shadcn init --preset {paste} 落地——preset 会把整个设计系统（颜色、圆角、字体）编码为首等规划产物，跨阶段与 milestone 可复现。对第三方 shadcn registry，安全门要求先用 npx shadcn view {component} 检查、npx shadcn diff {component} 与官方对比后再安装。

/gsd-ui-review 则对 6 大支柱按 1–4 分评分，输出 {phase}-UI-REVIEW.md 与优先级最高的 3 项修复建议，并会通过 Playwright CLI 截图存档到 .planning/ui-reviews/（自动生成 .gitignore 避免二进制入库，/gsd-complete-milestone 时清理）。它独立于 GSD 项目运行：即便没有 UI-SPEC.md，也会按抽象的 6 支柱标准审计。

相关配置项

配置项	默认值	控制内容
workflow.ui_phase	true	是否为前端阶段生成 UI 设计契约
workflow.ui_safety_gate	true	是否在 plan-phase 提示前端阶段先运行 /gsd-ui-phase

两者遵循 GSD 通用的"缺省即启用（absent=enabled）"模式，可通过 /gsd-settings 关闭。

---

Backlog 与线程（上下文组织机制）

Backlog 停车场（999.x 编号）

不适合进入活跃序列的灵感会以 999.x 编号进入 backlog，从而与当前 phase 序列隔离。例如：

/gsd-capture --backlog "GraphQL 数据访问层"
/gsd-capture --backlog "移动端响应式适配"

backlog 项同样拥有完整 phase 目录，因此随时可用 /gsd-discuss-phase 999.1 深挖，或 /gsd-plan-phase 999.1 正式开工；用 /gsd-review-backlog 统一评审并选择 Promote（提升到活跃序列）、Keep（继续滞留）或 Remove（删除）。存储于 ROADMAP.md 的 backlog 区段。

Seeds（带触发条件的未来想法）

Seed 记录"WHY 与 WHEN"——当对应里程碑到来时自动浮现：

/gsd-capture --seed "WebSocket 基建就绪后加入实时协作"

/gsd-new-milestone 会扫描全部 seeds 并呈现匹配项。存储于 .planning/seeds/SEED-NNN-slug.md。

持久化线程（Threads）

线程是跨越多个会话、但不归属任何特定 phase 的轻量上下文，比 /gsd-pause-work 更轻——不携带 phase 状态与计划上下文：

/gsd-thread                      # 列出所有线程
/gsd-thread fix-deploy-key-auth  # 续写既有线程
/gsd-thread "调查 TCP 超时问题"   # 新建线程

每个线程文件包含 Goal、Context、References、Next Steps 区段；成熟后可提升为 phase（/gsd-phase）或 backlog 项（/gsd-capture --backlog）。存储于 .planning/threads/{slug}.md。

---

Workstreams（无状态冲突的并行工作）

Workstream 让你在多个关注域（如后端 API 与前端看板）上并行工作而不互相踩踏：共享同一代码库与 git 历史，但各自隔离 .planning/ 规划产物。当你切换 workstream 时，GSD 会整体切换当前规划上下文，使 /gsd-progress、/gsd-discuss-phase、/gsd-plan-phase 等命令作用于该 workstream 的状态；运行时暴露稳定会话 ID 时，活跃上下文还带会话作用域，防止一个终端改写另一个实例的 STATE.md。

命令	作用
/gsd-workstreams create <name>	创建隔离规划状态的 workstream
/gsd-workstreams switch <name>	切换到另一 workstream
/gsd-workstreams list	列出全部 workstream 与当前活跃者
/gsd-workstreams complete <name>	结束并归档 workstream

子命令还有 status <name>、progress（跨 workstream 进度总览）、resume <name>。它比 /gsd-workspace --new（创建独立仓库 worktree）更轻量。

---

安全模型：纵深防御

GSD 生成的 markdown 会成为 LLM 系统提示词，因此任何流入规划产物的用户可控文本都是间接 prompt injection 的潜在载体。当前版本的防御纵深包括四层：

• 路径遍历防护：所有用户提供的文件路径（--text-file、--prd）被校验必须解析在项目目录内，并处理 macOS /var → /private/var 符号链接问题；
• Prompt injection 检测：用户文本进入规划产物前扫描已知注入模式（角色覆盖、指令绕过、系统标签注入等）；
• 运行时 hooks：hooks/gsd-prompt-guard.js 监听对 .planning/ 的 Write/Edit 工具调用并扫描注入模式（常驻、仅告警不阻断——源码注释明确说明阻断会妨碍合法工作流操作）；hooks/gsd-workflow-guard.js 对工作流上下文之外的文件编辑给出告警（通过 hooks.workflow_guard 选装）。此外 hooks/gsd-context-monitor.js 等会话级 guard 会在上下文占用越过阈值时介入提示；
• CI 扫描器：tests/prompt-injection-scan.test.cjs 随测试套件扫描全部 agent、workflow 与 command 文件是否存在内嵌注入向量。

在 Claude Code 侧，对敏感文件请使用 deny list 兜底。

包合法性门禁（Package Legitimacy Gate）

针对 AI 编码工具幻觉包名、攻击者抢先注册恶意同名包的 slopsquatting 攻击面，GSD 在 research → plan → execute 全链路加了门禁：推荐外部包时逐一运行 slopcheck install <pkg> --json，并把 ## Package Legitimacy Audit 审计表写进 RESEARCH.md。裁决分三档：

裁决	含义	GSD 动作
[OK]	通过全部合法性检查	放行，不插检查点
[SUS]	可疑信号（过新、下载量低、无源码仓等）	审计表标注，planner 在安装任务前插入 checkpoint:human-verify
[SLOP]	高置信幻觉或攻击者注册包	从 RESEARCH.md 移除，绝不进入 planner

WebSearch 来源的包一律标注 [ASSUMED]（仅证明"存在"不等于"可信"），与 [SUS] 同等待遇。执行阶段若安装失败，executor 会浮出检查点并停止，绝不静默替换为近似名——因为"静默替换相似名"正是 slopsquatting 扩散的路径。若 slopcheck 不可用（research 时会尝试 pip install slopcheck），则所有包自动降级为 [ASSUMED] 并全部门禁，不会硬失败。

---

命令参考

斜杠命令两种拼写：连字符 vs 冒号

GSD 向所有受支持运行时派发同一套 skills，但斜杠命令存在两种拼写：

• 连字符形式 /gsd-command-name — 用于 Claude Code、Copilot、OpenCode、Kilo、Cursor、Windsurf、Augment、Antigravity、Trae；
• 冒号形式 /gsd:command-name — 仅用于 Gemini CLI（Gemini 把每个插件的命令都置于插件 ID 命名空间下，安装器会在 --gemini 安装时改写命令文件）。

安装器会为每个目标运行时写入正确形式，你无需手动选择；在 Gemini 终端阅读本指南时，把 gsd 后的连字符换成冒号即可。

主流程命令

命令	使用时机
/gsd-new-project	项目启动（前提：无 .planning/PROJECT.md）
/gsd-discuss-phase [N]	计划前锁定实现偏好
/gsd-plan-phase [N]	创建并校验计划
/gsd-execute-phase [N]	按 wave 执行计划
/gsd-verify-work [N]	手动 UAT
/gsd-ship [N]	生成阶段 PR（需 gh CLI 已认证）
/gsd-progress --next	自动执行下一步

管理与工具命令

命令	使用时机
/gsd-progress	查看当前状态
/gsd-resume-work	恢复会话（如上下文已重置）
/gsd-pause-work	暂停并生成 handoff
/gsd-pause-work --report	输出会话总结报告
/gsd-quick	带 GSD 质量保证的临时任务
/gsd-debug [desc]	系统化调试（含 list/status/continue 子命令与 --diagnose）
/gsd-forensics	对损坏工作流做事后诊断
/gsd-settings	调整 workflow 开关与模型档位
/gsd-config --profile <profile>	快速切换模型档位

/gsd-quick 的粒度 flag 可组合：--discuss --research --validate 等价于 --full。完整命令清单与全部高级 flag 见 docs/COMMANDS.md，已发布命令的权威名录见 docs/INVENTORY.md。

命名空间路由（v1.40 起的 v1 级入口）

为控制提示词 token 占用，GSD 提供 6 个命名空间路由器作为分层路由的入口（约 120 tokens 的 6 个路由器 vs 摊平 86 个 skill 约 2150 tokens）：/gsd-workflow（阶段流水线）、/gsd-project（项目生命周期）、/gsd-quality（质量门）、/gsd-context（代码库智能）、/gsd-manage（管理）、/gsd-ideate（探索与捕获）。命名空间是增量的——所有既有具体命令（如 /gsd-plan-phase、/gsd-code-review --fix）仍可直接调用。

---

配置：.planning/config.json

配置文件为 .planning/config.json，由 /gsd-new-project 创建、/gsd-settings 或 /gsd-config 更新。

核心项

配置项	可选值	默认值	说明
mode	interactive、yolo	interactive	yolo 自动批准决策；interactive 每步确认
granularity	coarse、standard、fine	standard	控制阶段数量：coarse 3–5、standard 5–8、fine 8–12
model_profile	quality、balanced、budget、adaptive、inherit	balanced	各 agent 的模型档位

Workflow 开关

配置项	默认值
workflow.research	true
workflow.plan_check	true
workflow.verifier	true
workflow.nyquist_validation	true
workflow.ui_phase	true
workflow.ui_safety_gate	true

完整 schema 还包含 planning、ship.pr_body_sections、hooks、review.default_reviewers、git（分支模板）、parallelization、safety、intel.enabled、claude_md_path 等区块，见 docs/CONFIGURATION.md。注意所有 workflow 开关遵循 absent=enabled 模式。

模型档位（Model Profiles）

档位	推荐用途
quality	关键工作，追求更高质量
balanced	默认推荐
budget	降低 token 成本
inherit	跟随会话/运行时当前模型

在完整 schema 中，各档位的具体映射为：quality 全部决策用 Opus、验证用 Sonnet；balanced 仅计划用 Opus、其余用 Sonnet（默认）；budget 代码编写用 Sonnet、研究/验证用 Haiku；inherit 全部 agent 跟随会话模型（适合 OpenCode/Kilo 的 /model 动态切换，或通过 OpenRouter、本地模型等非 Anthropic 供应商使用 Claude Code 时防止意外 API 成本）。

非 Claude 运行时（Codex / OpenCode / Gemini CLI / Kilo）

面向非 Claude 运行时安装 GSD 时，安装器会自动在 ~/.gsd/defaults.json 写入 resolve_model_ids: "omit"，指示 GSD 跳过 Anthropic 模型 ID 解析、为所有 agent 返回空模型参数，从而让每个 agent 使用运行时自身配置的模型——默认场景无需任何额外设置（见 docs/CONFIGURATION.md 的运行时感知档位章节）。若手动配置非 Claude 运行时，只需在 .planning/config.json 中添加：

{
  "resolve_model_ids": "omit"
}

---

使用示例

全新项目（完整周期）

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          # 手动 UAT
/gsd-ship 1                 # 依据已验证产物生成 PR
/gsd-ui-review 1            # 视觉审计（前端阶段）
/gsd-progress --next        # 自动识别并执行下一步
# ...
/gsd-audit-milestone        # 核对全部交付
/gsd-complete-milestone     # 归档、打 tag

从既有文档启动新项目

/gsd-new-project --auto @prd.md   # 自动完成研究/需求/路线图
/gsd-discuss-phase 1               # 之后走正常流程

已有代码库（Brownfield）

/gsd-map-codebase           # 并行 agent 分析现状，产出 .planning/codebase/ 文档
/gsd-new-project            # 提问聚焦于你"新增"什么

快速修复

/gsd-quick
> "修复移动端 Safari 上登录按钮无响应的问题"

Release 准备

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

---

Troubleshooting（故障排查）

症状	处理方式
"Project already initialized"	.planning/PROJECT.md 已存在。如需彻底重启，删除 .planning/ 后再初始化
长会话导致上下文劣化	在大的步骤之间使用 /clear，随后用 /gsd-resume-work 或 /gsd-progress 恢复
计划与预期脱节	在计划前先跑 /gsd-discuss-phase [N]；用 /gsd-discuss-phase --assumptions [N] 校验假设
执行失败或留下 stubs	以更小范围重排计划（每个计划放更小的任务）
token 成本过高	切换 budget 档位
非 Claude 运行时（Codex/OpenCode/Gemini/Kilo）	使用 resolve_model_ids: "omit" 让运行时自行解析默认模型

关于执行失败还有一个补充恢复路径：若需要回滚，GSD 提供 /gsd-undo（基于 phase manifest 的安全 revert，含依赖检查与确认门，支持 --last N/--phase NN/--plan NN-MM）；流程彻底卡死时可先用 /gsd-forensics "问题描述" 生成 forensics/report-{timestamp}.md 诊断根因，再决定重放或回滚。

---

快速恢复速查表

问题	解决方案
丢失上下文	/gsd-resume-work 或 /gsd-progress
阶段执行出问题	git revert + 重新计划
需要调整范围	/gsd-phase、/gsd-phase --insert、/gsd-phase --remove
工作流有 bug	/gsd-forensics
单点修复	/gsd-quick
成本过高	/gsd-config --profile budget
不知道下一步	/gsd-progress --next

/gsd-phase 家族负责对 ROADMAP.md 做 CRUD：无 flag 时在里程碑末尾追加新整数阶段，--insert <N> 把紧急工作插入为小数阶段（如 3.1），--remove <N> 删除未来阶段并重排后续编号，--edit <N> 就地编辑（配合 --force 可改进行中或已完成阶段）。

---

项目文件结构

以 .planning/ 为中心的规划产物结构如下：

.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/

其中 STATE.md 是 GSD 的会话记忆与当前位置，每次执行后自动更新；HANDOFF.json 支撑 /gsd-pause-work//gsd-resume-work 的会话接力；phases/ 下的每个阶段目录是讨论、研究与验证证据的完整归档，也是 /gsd-ship 生成 PR body、/gsd-milestone-summary 生成团队交接文档的数据来源。

---

说明：pt-BR 版指南定位为日常使用速查，英文权威版 docs/USER-GUIDE.md 与 docs/COMMANDS.md、docs/CONFIGURATION.md 提供更完整的参数与流程覆盖；快速安装请见 README.pt-BR.md。从 GitHub/Linear/Jira issue 直接驱动 GSD 的配方可参考 docs/issue-driven-orchestration.md，自定义 PR body 章节可参考 docs/ship-pr-body-sections.md。