mirror of
https://github.com/glittercowboy/get-shit-done
synced 2026-04-25 17:25:23 +02:00
22 KiB
22 KiB
GSD 用户指南
工作流、故障排除和配置的详细参考。快速入门设置请参阅 README。
目录
工作流图解
完整项目生命周期
┌──────────────────────────────────────────────────┐
│ 新建项目 │
│ /gsd-new-project │
│ 提问 -> 研究 -> 需求 -> 路线图 │
└─────────────────────────┬────────────────────────┘
│
┌──────────────▼─────────────┐
│ 每个阶段: │
│ │
│ ┌────────────────────┐ │
│ │ /gsd-discuss-phase │ │ <- 锁定偏好
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-plan-phase │ │ <- 研究 + 规划 + 验证
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-execute-phase │ │ <- 并行执行
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-verify-work │ │ <- 手动 UAT
│ └──────────┬─────────┘ │
│ │ │
│ 下一阶段?────────────┘
│ │ 否
└─────────────┼──────────────┘
│
┌───────────────▼──────────────┐
│ /gsd-audit-milestone │
│ /gsd-complete-milestone │
└───────────────┬──────────────┘
│
另一个里程碑?
│ │
是 否 -> 完成!
│
┌───────▼──────────────┐
│ /gsd-new-milestone │
└──────────────────────┘
规划代理协调
/gsd-plan-phase N
│
├── 阶段研究员 (x4 并行)
│ ├── 技术栈研究员
│ ├── 功能研究员
│ ├── 架构研究员
│ └── 陷阱研究员
│ │
│ ┌──────▼──────┐
│ │ RESEARCH.md │
│ └──────┬──────┘
│ │
│ ┌──────▼──────┐
│ │ 规划者 │ <- 读取 PROJECT.md, REQUIREMENTS.md,
│ │ │ CONTEXT.md, RESEARCH.md
│ └──────┬──────┘
│ │
│ ┌──────▼───────────┐ ┌────────┐
│ │ 计划检查器 │────>│ 通过? │
│ └──────────────────┘ └───┬────┘
│ │
│ 是 │ 否
│ │ │ │
│ │ └───┘ (循环，最多 3 次)
│ │
│ ┌─────▼──────┐
│ │ PLAN 文件 │
│ └────────────┘
└── 完成
验证架构 (Nyquist 层)
在 plan-phase 研究期间，GSD 现在在任何代码编写之前将自动化测试覆盖率映射到每个阶段需求。这确保当 Claude 的执行者提交任务时，反馈机制已经存在可以在几秒钟内验证它。
研究员检测你现有的测试基础设施，将每个需求映射到特定的测试命令，并识别在实现开始之前必须创建的任何测试脚手架（波次 0 任务）。
计划检查器将其强制作为第 8 个验证维度：缺少自动化验证命令的计划将不会被批准。
输出： {阶段}-VALIDATION.md —— 阶段的反馈契约。
禁用： 在 /gsd-settings 中设置 workflow.nyquist_validation: false，用于测试基础设施不是重点的快速原型阶段。
追溯验证 (/gsd-validate-phase)
对于在 Nyquist 验证存在之前执行的阶段，或只有传统测试套件的现有代码库，追溯审计并填补覆盖缺口：
/gsd-validate-phase N
|
+-- 检测状态 (VALIDATION.md 存在? SUMMARY.md 存在?)
|
+-- 发现: 扫描实现，将需求映射到测试
|
+-- 分析缺口: 哪些需求缺少自动化验证?
|
+-- 呈现缺口计划供审批
|
+-- 生成审计器: 生成测试，运行，调试（最多 3 次尝试）
|
+-- 更新 VALIDATION.md
|
+-- COMPLIANT -> 所有需求都有自动化检查
+-- PARTIAL -> 部分缺口升级为仅手动
审计器从不修改实现代码 —— 只修改测试文件和 VALIDATION.md。如果测试发现实现 bug，它会标记为升级让你处理。
何时使用： 在启用了 Nyquist 之前规划的阶段执行后，或在 /gsd-audit-milestone 发现 Nyquist 合规缺口后。
执行波次协调
/gsd-execute-phase N
│
├── 分析计划依赖
│
├── 波次 1 (独立计划):
│ ├── 执行者 A (全新 200K 上下文) -> 提交
│ └── 执行者 B (全新 200K 上下文) -> 提交
│
├── 波次 2 (依赖波次 1):
│ └── 执行者 C (全新 200K 上下文) -> 提交
│
└── 验证器
└── 根据阶段目标检查代码库
│
├── 通过 -> VERIFICATION.md (成功)
└── 失败 -> 问题记录到 /gsd-verify-work
现有代码库工作流
/gsd-map-codebase
│
├── 技术栈映射器 -> codebase/STACK.md
├── 架构映射器 -> codebase/ARCHITECTURE.md
├── 约定映射器 -> codebase/CONVENTIONS.md
└── 关注点映射器 -> codebase/CONCERNS.md
│
┌───────▼──────────┐
│ /gsd-new-project │ <- 问题聚焦于你正在添加的内容
└──────────────────┘
命令参考
核心工作流
| 命令 | 用途 | 何时使用 |
|---|---|---|
/gsd-new-project |
完整项目初始化：提问、研究、需求、路线图 | 新项目开始时 |
/gsd-new-project --auto @idea.md |
从文档自动初始化 | 有现成的 PRD 或想法文档 |
/gsd-discuss-phase [N] [--chain] [--power] |
捕获实现决策（--chain 自动链式，--power 文件批量输入） |
规划前，塑造构建方式 |
/gsd-plan-phase [N] |
研究 + 规划 + 验证 | 执行阶段前 |
/gsd-execute-phase <N> |
在并行波次中执行所有计划 | 规划完成后 |
/gsd-verify-work [N] |
带自动诊断的手动 UAT | 执行完成后 |
/gsd-audit-milestone |
验证里程碑达到其完成定义 | 完成里程碑前 |
/gsd-complete-milestone |
归档里程碑，标记发布 | 所有阶段已验证 |
/gsd-new-milestone [name] |
开始下一个版本周期 | 完成里程碑后 |
导航
| 命令 | 用途 | 何时使用 |
|---|---|---|
/gsd-progress |
显示状态和下一步 | 任何时候 -- "我在哪?" |
/gsd-resume-work |
从上次会话恢复完整上下文 | 开始新会话 |
/gsd-pause-work |
保存上下文交接 | 阶段中途停止 |
/gsd-help |
显示所有命令 | 快速参考 |
/gsd-update |
更新 GSD 并预览变更日志 | 检查新版本 |
/gsd-join-discord |
打开 Discord 社区邀请 | 问题或社区 |
阶段管理
| 命令 | 用途 | 何时使用 |
|---|---|---|
/gsd-add-phase |
向路线图追加新阶段 | 初始规划后范围增长 |
/gsd-insert-phase [N] |
插入紧急工作（小数编号） | 里程碑中途紧急修复 |
/gsd-remove-phase [N] |
删除未来阶段并重新编号 | 移除某个功能 |
/gsd-list-phase-assumptions [N] |
预览 Claude 的预期方法 | 规划前，验证方向 |
/gsd-plan-milestone-gaps |
为审计缺口创建阶段 | 审计发现缺失项后 |
/gsd-research-phase [N] |
仅深度生态研究 | 复杂或不熟悉的领域 |
/gsd-autonomous [--from N] [--to N] [--only N] |
自主执行剩余阶段（--to N 到阶段 N 停止） |
批量自动处理 |
/gsd-analyze-dependencies |
检测阶段间依赖关系 | /gsd-manager 前分析 |
状态管理
| 命令 | 用途 | 何时使用 |
|---|---|---|
state validate |
检测 STATE.md 与文件系统之间的偏差 | STATE.md 看起来不对时 |
state sync |
从磁盘上的实际项目状态重建 STATE.md | 验证发现偏差后 |
state sync --verify |
干运行：显示提议的更改但不写入 | sync 前预览 |
state planned-phase --phase N --plans N |
记录 plan-phase 完成后的状态转换 | plan-phase 后 |
现有代码库和工具
| 命令 | 用途 | 何时使用 |
|---|---|---|
/gsd-map-codebase |
分析现有代码库 | 在现有代码上运行 /gsd-new-project 之前 |
/gsd-quick |
带 GSD 保证的临时任务 | Bug 修复、小功能、配置更改 |
/gsd-debug [desc] [--diagnose] |
带持久状态的系统化调试（--diagnose 仅诊断） |
出问题时 |
/gsd-add-todo [desc] |
捕获想法留待后用 | 会话期间想到什么 |
/gsd-check-todos |
列出待处理事项 | 查看捕获的想法 |
/gsd-settings |
配置工作流开关和模型配置 | 更改模型、切换代理 |
/gsd-set-profile <profile> |
快速切换配置 | 更改成本/质量权衡 |
/gsd-reapply-patches |
更新后恢复本地修改 | 如果你有本地编辑，在 /gsd-update 后 |
配置参考
GSD 在 .planning/config.json 中存储项目设置。在 /gsd-new-project 期间配置或稍后用 /gsd-settings 更新。
完整 config.json 模式
{
"mode": "interactive",
"granularity": "standard",
"model_profile": "balanced",
"planning": {
"commit_docs": true,
"search_gitignored": false
},
"workflow": {
"research": true,
"plan_check": true,
"verifier": true,
"nyquist_validation": true
},
"git": {
"branching_strategy": "none",
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}"
}
}
核心设置
| 设置 | 选项 | 默认值 | 控制内容 |
|---|---|---|---|
mode |
interactive, yolo |
interactive |
yolo 自动批准决策；interactive 每步确认 |
granularity |
coarse, standard, fine |
standard |
阶段粒度：范围切分多细（3-5、5-8 或 8-12 个阶段） |
model_profile |
quality, balanced, budget |
balanced |
每个代理的模型层级（见下表） |
规划设置
| 设置 | 选项 | 默认值 | 控制内容 |
|---|---|---|---|
planning.commit_docs |
true, false |
true |
.planning/ 文件是否提交到 git |
planning.search_gitignored |
true, false |
false |
在广泛搜索中添加 --no-ignore 以包含 .planning/ |
注意： 如果
.planning/在.gitignore中，无论配置值如何，commit_docs自动为false。
工作流开关
| 设置 | 选项 | 默认值 | 控制内容 |
|---|---|---|---|
workflow.research |
true, false |
true |
规划前的领域调查 |
workflow.plan_check |
true, false |
true |
计划验证循环（最多 3 次迭代） |
workflow.verifier |
true, false |
true |
根据阶段目标的执行后验证 |
workflow.nyquist_validation |
true, false |
true |
plan-phase 期间的验证架构研究；第 8 个计划检查维度 |
在熟悉的领域或需要节省 token 时禁用这些以加速阶段。
Git 分支
| 设置 | 选项 | 默认值 | 控制内容 |
|---|---|---|---|
git.branching_strategy |
none, phase, milestone |
none |
何时以及如何创建分支 |
git.phase_branch_template |
模板字符串 | gsd/phase-{phase}-{slug} |
阶段策略的分支名 |
git.milestone_branch_template |
模板字符串 | gsd/{milestone}-{slug} |
里程碑策略的分支名 |
分支策略说明：
| 策略 | 创建分支 | 范围 | 适用于 |
|---|---|---|---|
none |
从不 | N/A | 独立开发、简单项目 |
phase |
每次 execute-phase |
每个阶段一个分支 | 每阶段代码审查、细粒度回滚 |
milestone |
第一次 execute-phase |
所有阶段共享一个分支 | 发布分支、每个版本一个 PR |
模板变量： {phase} = 零填充数字（如 "03"），{slug} = 小写连字符名称，{milestone} = 版本（如 "v1.0"）。
模型配置（每个代理分解）
| 代理 | quality |
balanced |
budget |
|---|---|---|---|
| gsd-planner | Opus | Opus | Sonnet |
| gsd-roadmapper | Opus | Sonnet | Sonnet |
| gsd-executor | Opus | Sonnet | Sonnet |
| gsd-phase-researcher | Opus | Sonnet | Haiku |
| gsd-project-researcher | Opus | Sonnet | Haiku |
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku |
| gsd-debugger | Opus | Sonnet | Sonnet |
| gsd-codebase-mapper | Sonnet | Haiku | Haiku |
| gsd-verifier | Sonnet | Sonnet | Haiku |
| gsd-plan-checker | Sonnet | Sonnet | Haiku |
| gsd-integration-checker | Sonnet | Sonnet | Haiku |
配置理念：
- quality —— 所有决策代理使用 Opus，只读验证使用 Sonnet。有配额可用且工作关键时使用。
- balanced —— 仅规划（架构决策发生的地方）使用 Opus，其他全部使用 Sonnet。这是默认，有充分理由。
- budget —— 编写代码的使用 Sonnet，研究和验证使用 Haiku。大量工作或不太关键的阶段使用。
使用示例
新项目（完整周期）
claude --dangerously-skip-permissions
/gsd-new-project # 回答问题，配置，批准路线图
/clear
/gsd-discuss-phase 1 # 锁定你的偏好
/gsd-plan-phase 1 # 研究 + 规划 + 验证
/gsd-execute-phase 1 # 并行执行
/gsd-verify-work 1 # 手动 UAT
/clear
/gsd-discuss-phase 2 # 对每个阶段重复
...
/gsd-audit-milestone # 检查所有内容已发布
/gsd-complete-milestone # 归档，标记，完成
从现有文档创建新项目
/gsd-new-project --auto @prd.md # 从你的文档自动运行研究/需求/路线图
/clear
/gsd-discuss-phase 1 # 从这里开始正常流程
现有代码库
/gsd-map-codebase # 分析现有内容（并行代理）
/gsd-new-project # 问题聚焦于你正在添加的内容
# （从这里开始正常阶段工作流）
快速 Bug 修复
/gsd-quick
> "修复移动端 Safari 上登录按钮无响应的问题"
中断后恢复
/gsd-progress # 查看你停在哪和接下来做什么
# 或
/gsd-resume-work # 从上次会话完整恢复上下文
准备发布
/gsd-audit-milestone # 检查需求覆盖率，检测存根
/gsd-plan-milestone-gaps # 如果审计发现缺口，创建阶段来填补
/gsd-complete-milestone # 归档，标记，完成
速度与质量预设
| 场景 | 模式 | 粒度 | 配置 | 研究 | 计划检查 | 验证器 |
|---|---|---|---|---|---|---|
| 原型开发 | yolo |
coarse |
budget |
关 | 关 | 关 |
| 正常开发 | interactive |
standard |
balanced |
开 | 开 | 开 |
| 生产环境 | interactive |
fine |
quality |
开 | 开 | 开 |
里程碑中途范围变更
/gsd-add-phase # 向路线图追加新阶段
# 或
/gsd-insert-phase 3 # 在阶段 3 和 4 之间插入紧急工作
# 或
/gsd-remove-phase 7 # 移除阶段 7 并重新编号
故障排除
"项目已初始化"
你运行了 /gsd-new-project 但 .planning/PROJECT.md 已存在。这是安全检查。如果你想重新开始，先删除 .planning/ 目录。
长会话期间上下文退化
在主要命令之间清除上下文窗口：Claude Code 中的 /clear。GSD 设计围绕全新上下文 —— 每个子代理获得干净的 200K 窗口。如果主会话质量下降，清除并使用 /gsd-resume-work 或 /gsd-progress 恢复状态。
计划看起来错误或不一致
在规划前运行 /gsd-discuss-phase [N]。大多数计划质量问题来自 Claude 做出了 CONTEXT.md 本可以防止的假设。你也可以运行 /gsd-list-phase-assumptions [N] 在提交计划前查看 Claude 打算做什么。
执行失败或产生存根
检查计划是否太雄心勃勃。计划最多应有 2-3 个任务。如果任务太大，它们超出了单个上下文窗口可以可靠产生的内容。用更小的范围重新规划。
忘记你在哪里
运行 /gsd-progress。它读取所有状态文件，准确告诉你位置和下一步。
执行后需要更改某些内容
不要重新运行 /gsd-execute-phase。使用 /gsd-quick 进行针对性修复，或用 /gsd-verify-work 通过 UAT 系统识别和修复问题。
STATE.md 不同步
如果 STATE.md 显示不正确的阶段状态或位置，使用状态一致性命令：
node gsd-tools.cjs state validate # 检测 STATE.md 与文件系统之间的偏差
node gsd-tools.cjs state sync --verify # 预览 sync 将更改的内容
node gsd-tools.cjs state sync # 从磁盘重建 STATE.md
这些命令是 v1.32 新增的，替代了手动编辑 STATE.md。
研究门控（Research Gate）
/gsd-plan-phase 在规划开始前会检查 RESEARCH.md 是否存在未解决的开放问题。如果存在未解决的问题，规划将被阻止，系统会显示需要解决的具体问题。这防止了基于不完整信息构建计划。
模型成本太高
切换到 budget 配置：/gsd-set-profile budget。如果领域对你（或 Claude）熟悉，通过 /gsd-settings 禁用研究和计划检查代理。
处理敏感/私有项目
在 /gsd-new-project 期间或通过 /gsd-settings 设置 commit_docs: false。将 .planning/ 添加到 .gitignore。规划工件保留在本地，从不接触 git。
GSD 更新覆盖了我的本地更改
从 v1.17 开始，安装程序将本地修改的文件备份到 gsd-local-patches/。运行 /gsd-reapply-patches 将你的更改合并回来。
子代理似乎失败但工作已完成
存在 Claude Code 分类 bug 的已知解决方法。GSD 的编排器（execute-phase、quick）在报告失败前抽查实际输出。如果你看到失败消息但提交已创建，检查 git log —— 工作可能已成功。
恢复快速参考
| 问题 | 解决方案 |
|---|---|
| 丢失上下文 / 新会话 | /gsd-resume-work 或 /gsd-progress |
| 阶段出错 | git revert 阶段提交，然后重新规划 |
| 需要更改范围 | /gsd-add-phase、/gsd-insert-phase 或 /gsd-remove-phase |
| 里程碑审计发现缺口 | /gsd-plan-milestone-gaps |
| 出问题了 | /gsd-debug "描述" |
| STATE.md 不同步 | state validate 然后 state sync |
| 快速针对性修复 | /gsd-quick |
| 计划与你的愿景不符 | /gsd-discuss-phase [N] 然后重新规划 |
| 成本过高 | /gsd-set-profile budget 和 /gsd-settings 关闭代理 |
| 更新破坏了本地更改 | /gsd-reapply-patches |
项目文件结构
供参考，这是 GSD 在你的项目中创建的内容：
.planning/
PROJECT.md # 项目愿景和上下文（始终加载）
REQUIREMENTS.md # 界定 v1/v2 需求及 ID
ROADMAP.md # 带状态跟踪的阶段分解
STATE.md # 决策、阻塞项、会话记忆
config.json # 工作流配置
MILESTONES.md # 已完成里程碑归档
research/ # 来自 /gsd-new-project 的领域研究
todos/
pending/ # 等待处理的捕获想法
done/ # 已完成的待办事项
debug/ # 活跃调试会话
resolved/ # 已归档的调试会话
codebase/ # 现有代码库映射（来自 /gsd-map-codebase）
phases/
XX-phase-name/
XX-YY-PLAN.md # 原子执行计划
XX-YY-SUMMARY.md # 执行结果和决策
CONTEXT.md # 你的实现偏好
RESEARCH.md # 生态研究发现
VERIFICATION.md # 执行后验证结果