GSD 新手入门指南：用 Claude Code 实现计划驱动的单智能体开发

GSD（Get Shit Done）是面向 Claude Code 单智能体开发场景的计划驱动式开发系统：它把一句模糊的想法逐步转化为层级化计划，再按阶段（phase）逐个执行，全程以状态文件跟踪进度、以原子提交固化每个改动。这篇指南基于仓库中的新手导览文档 get-shit-done/workflows/help/modes/default.md 展开，读完你可以掌握 GSD 的三条启动命令、常用命令速查、分级帮助体系与更新机制，并理解其 help 模式在仓库中是如何实现的。

GSD 是什么：面向 solo agentic 工作的计划驱动开发

GSD 的核心定位一句话即可概括：为 Claude Code 上的单人智能体工作提供 plan-driven development。它把"一个模糊想法"变成"一份层级化计划"，然后分阶段执行，过程中依靠状态跟踪与原子提交保证每一步都可回溯。

在仓库中，这段描述以 purpose 字段的形式写在帮助文档的头部（见 get-shit-done/workflows/help/modes/default.md），而完整命令参考则沉淀在同目录的 get-shit-done/workflows/help/modes/full.md 中。作为新手，你不必一次读完所有命令——GSD 设计了四层帮助体系，从 10 行速查到完整参考按需取用，本文后面会专门展开。

三步上手：从 0 到第一次执行

default.md 给出的启动路径只有三条命令，构成 GSD 最小可用闭环：

/gsd:new-project        # Greenfield: questioning → research → requirements → roadmap
/gsd:plan-phase 1       # Create a detailed plan for phase 1
/gsd:execute-phase 1    # Execute all plans in the phase

• /gsd:new-project：统一的项目初始化流程。它依次完成深度提问（理解你要构建什么）、可选的领域研究（并行派发 4 个研究型子智能体，分别调研 Stack / Features / Architecture / Pitfalls）、带 v1/v2/Out-of-Scope 边界划分的需求定义，以及带阶段拆解与成功标准的路线图生成。整个流程结束后会在 .planning/ 目录下落地 PROJECT.md（愿景与需求）、config.json（工作流模式）、research/（领域研究）、REQUIREMENTS.md（带 REQ-ID 的需求）、ROADMAP.md（映射到需求的阶段）与 STATE.md（项目记忆）。更完整的流程细节见 get-shit-done/workflows/new-project.md。
• /gsd:plan-phase 1：为阶段 1 生成可执行的 PLAN.md。它会将阶段拆解为具体、可操作的任务，并附带验证标准与成功度量，产物路径形如 .planning/phases/XX-phase-name/XX-YY-PLAN.md，一个阶段支持多份计划（XX-01、XX-02……）。
• /gsd:execute-phase 1：执行该阶段内的全部计划。它按计划 frontmatter 中的 wave 分组、按波次串行推进，同一波次内的计划可并行；阶段目标全部完成后会更新 REQUIREMENTS.md、ROADMAP.md、STATE.md。底层实现（含 wave 分组、worktree 隔离与 post-merge 构建测试门禁）见 get-shit-done/workflows/execute-phase.md。

已有代码库怎么办：先 map-codebase

default.md 特别提醒：如果是既有代码库，先运行 /gsd:map-codebase，让 GSD 先扎根在你的真实代码之上，再进行项目初始化。该命令会用并行的 Explore 智能体分析代码库，在 .planning/codebase/ 下生成 7 份聚焦文档（栈、架构、结构、约定、测试、集成、风险），支持 --fast（轻量评估）、--focus <area>（限定范围）与 --query <term>（检索 .planning/intel/ 中的代码情报索引）。

常用命令速查表（完整继承）

default.md 用一张表给出了新手最常用的 9 个命令，下面逐条展开，补充其在完整参考 get-shit-done/workflows/help/modes/full.md 中的关键行为：

命令	用途	关键行为与标志
/gsd:progress	我在哪、下一步做什么	显示可视化进度条与完成百分比；--next 自动推进到下一步；--forensic 追加 6 项完整性审计；--do "..." 充当智能路由器，把自由文本意图自动分派到最匹配的 GSD 命令
/gsd:quick	小规模临时任务，但保留 GSD 保证	只派生 planner + executor（默认跳过 researcher/checker/verifier），产物位于 .planning/quick/；--full 恢复完整质量流水线，--validate/--discuss/--research 可组合叠加
/gsd:fast "<task>"	微不足道的行内改动	不派生任何子智能体、不生成 PLAN/SUMMARY 文件，最多 3 个文件改动，超出则重定向到 /gsd:quick；改完原子提交并记录到 STATE.md
/gsd:discuss-phase <N>	在规划前捕获愿景与决策	支持 --chain（链式提问）、--analyze（深度假设分析）、--power（扩展问题集）、--assumptions（无交互暴露实现假设）、--batch[=N]（2-5 个相关问题批量问）
/gsd:debug "<symptom>"	持久化调试会话	通过自适应提问收集症状，在 .planning/debug/ 下以"证据→假设→验证"的科学方法排查；会话状态在 /clear 后依然存活，无参数重跑即可续接；--diagnose 只做一次性诊断
/gsd:capture	保存想法 / 待办 / 笔记 / seed / backlog	默认从对话上下文提取结构化 todo 存入 .planning/todos/pending/；--note 零摩擦笔记；--seed 带触发条件的远期想法；--backlog 放入 999.x 编号的停车场；--list [area] 列出并开始处理
/gsd:verify-work <N>	对已完成阶段做对话式 UAT	从 SUMMARY.md 提取可测试交付物，逐个以 yes/no 呈现，失败自动诊断并生成修复计划
/gsd:ship <N>	从已完成阶段发起 PR	推送分支、以 SUMMARY/VERIFICATION/REQUIREMENTS 生成 PR 正文、可选请求代码评审；前置条件：阶段已验证、gh CLI 已安装并认证
/gsd:help --full	完整参考	覆盖全部命令与标志，即 get-shit-done/workflows/help/modes/full.md 全文

再进一步：GSD 的四层帮助体系

default.md 的"Want more?"一节展示了一个精心设计的分级帮助体系——同样的命令参考，按需提供四种粒度：

/gsd:help --brief         # 10-line refresher of top commands
/gsd:help --full          # complete reference
/gsd:help <topic>         # one section only — see topics below
/gsd:help --brief <topic> # compact scoped lookup — signature + one-line summary

• --brief：约 10 行的顶部命令速查，适合老用户快速唤起记忆（对应 get-shit-done/workflows/help/modes/brief.md）。
• 无参数（默认）：即本篇文章所依托的一页式新手导览（get-shit-done/workflows/help/modes/default.md）。
• --full：完整命令参考，包含全部命令、标志、.planning/ 目录结构、工作流模式与规划配置（get-shit-done/workflows/help/modes/full.md）。
• <topic> / --brief <topic>：只输出匹配章节；--brief <topic> 进一步压缩为"签名 + 一行摘要"的紧凑查表。

默认导览列出 14 个可查主题：workflow · planning · execute · quick · debug · capture · ship · config · milestones · spike · sketch · review · audit · progress。每个主题输出前都会带一行已解析路由的前缀（**Topic:** <alias> → <heading> *(scope: full | compact)*），让你清楚看到自己命中了哪一节；未知主题则会回显可识别的主题列表。

help 路由机制在仓库中如何实现

分级帮助不是硬编码在单文件里，而是一套可维护的懒加载路由：

• 入口契约在 commands/gsd/help.md：它声明了参数提示 [--brief | --full | <topic> | --brief <topic>]，并把自己的执行上下文指向工作流 get-shit-done/workflows/help.md。
• 路由决策在 get-shit-done/workflows/help.md：其中 progressive_disclosure 块声明了"模式文件懒加载"策略——根据 $ARGUMENTS 只读取一个匹配的模式文件，然后原样输出其 <reference> 正文。规则包括：--brief/-b 单独出现读 brief.md；--full/-f/--all 单独出现读 full.md；参数为空读 default.md；--brief <topic> 走 topic.md 的紧凑作用域；其余裸主题或 --full <topic> 走 topic.md 的完整作用域。多个标志同时出现时还定义了优先级（如 --brief 与 --full 互斥时偏好 --full）。
• 主题抽取在 get-shit-done/workflows/help/modes/topic.md：内置一张"主题别名 → 章节标题"的解析表（如 init/new-project → ### Project Initialization，progress/route → ### Progress Tracking 加 ### Smart Router），并定义了 5a/5b/5c 三种抽取规则，处理单节、多节拼接与子块三种情况；紧凑作用域只取签名行与紧跟的一行摘要。

这一设计的价值在于：模式文件之间通过"渐进式披露"（progressive disclosure）互不冗余，参考内容单点维护，而调用侧无论怎么组合参数，都能得到确定性的路由结果。

更新 GSD

GSD 迭代很快，导览文档建议周期性更新，直接运行：

npx get-shit-done-cc@latest

仓库内还提供了更完善的 /gsd:update 命令（见完整参考）：它会对比已安装版本与最新版本、展示你错过的版本变更日志、高亮破坏性变更，并在安装前确认，比裸跑 npx 更安全；--sync 负责同步受管技能，--reapply 可在更新后重新应用本地修改。

从导览到流水线：三条命令背后的状态与产物

最后把视角拉高：default.md 的"三步上手"本质上是 GSD 主流水线的最小切片。从完整参考与工作流源码可以确认，每一步都在 .planning/ 目录留下可审计的痕迹：

.planning/
├── PROJECT.md            # 项目愿景与需求（Validated / Active / Out of Scope + Key Decisions）
├── ROADMAP.md            # 当前阶段拆解与依赖
├── STATE.md              # 项目记忆与上下文（会话续接的权威来源）
├── config.json           # 工作流模式与门禁（interactive / yolo）
├── requirements/         # 带 REQ-ID 的需求（v1/v2/out-of-scope 分级）
├── research/             # 领域研究（new-project 阶段可选）
├── codebase/             # 代码库地图（brownfield 项目）
└── phases/
    ├── 01-foundation/
    │   ├── 01-01-PLAN.md
    │   └── 01-01-SUMMARY.md

流水线的每一次推进都遵守"规划文档 + 原子提交"的纪律：plan-phase 生成 PLAN.md，execute-phase 让每个任务的改动独立提交、完成计划后回写 SUMMARY.md，最终统一更新 REQUIREMENTS/ROADMAP/STATE（worktree 并行模式下由编排者统一写入共享文件，避免 last-merge-wins 覆盖）。这也解释了导览中"state tracking and atomic commits"的承诺——它不是口号，而是落在每个阶段产物与 git 历史中的硬约束。

对新手而言，记住这条主线就够用了：new-project 建立计划骨架 → plan-phase 把阶段细化为可执行任务 → execute-phase 分批执行并回写状态；期间任何时候迷路了，/gsd:progress 会告诉你"我在哪、下一步做什么"。更深的机制探索可以从 get-shit-done/workflows/new-project.md、get-shit-done/workflows/plan-phase.md 和 get-shit-done/workflows/execute-phase.md 三份工作流源码继续深入。