GSD 原理与实战：用 Claude Code 真正做出产品
2026年5月14日
开场：你也有过这样的经历吧？
你打开 Claude Code，兴奋地开始写一个新项目。功能一个个实现了，代码跑起来了。然后你输入 /clear——或者第二天重新打开终端——AI 完全忘了昨天做了什么。
你不得不重新解释项目背景、重新描述架构决策、重新告诉它「这个目录不要动」。每次对话都像第一天上班的新人。
GSD（Get Shit Done） 解决的就是这个问题。它是一套运行在 Claude Code 上的项目管理框架，把项目状态从 AI 的短期记忆搬到磁盘上，让 AI 辅助开发变成可复现、可中断、可恢复的工程实践。
本教程会带你从原理理解到实战操作，最终能用 GSD 独立管理一个完整项目。
第1章 GSD 是什么
1.1 一个真实场景：当 Claude Code 遇上真实项目
假设你要做一个博客系统。用普通 Claude Code 的方式：
- 第一轮对话：搭了项目骨架，写了几个文件
- 第二轮对话：忘了上次的决策，重写了路由方案
- 第三轮对话：又忘了，开始改数据库 schema
每轮对话都是孤立的。没有计划、没有记录、没有验证。写到哪算哪。
GSD 的方式完全不同：它在项目里创建一个 .planning/ 目录，所有项目状态——需求、路线图、阶段计划、执行记录——都持久化在磁盘上。无论你重启多少次 Claude Code，GSD 都能从 .planning/STATE.md 恢复完整上下文。
1.2 GSD 的核心定位
GSD 不是一个代码生成器，而是一个元提示词（meta-prompt）+ 规格驱动开发框架。换句话说：
- 代码由 Claude Code 写
- 该写什么、怎么写、写完怎么验证由 GSD 管
它充当的是「AI 项目经理」的角色：帮你把模糊的想法拆成可执行的阶段，把大任务分给多个专精 Agent，最后验证交付物是否满足原始需求。
1.3 GSD 能帮你做什么
用一句话概括：GSD 让 Claude Code 从「一次性灵感」变成「可复现的工程」。
具体来说：
- 项目状态持久化：上下文不再随对话丢失
- 结构化工作流：从想法到交付有明确路径
- 多 Agent 并行：研究、规划、执行、验证由不同 Agent 分工完成
- 验证驱动开发：每个阶段都有验收标准，不是「改完就完」
- 断点续行：随时暂停和恢复工作，不丢上下文
本章小结：GSD 是 Claude Code 的项目管理层，解决 AI 辅助开发的连续性问题。它不替代 Claude Code 写代码，而是告诉 Claude Code 该写什么、怎么验证。
第2章 核心原理
GSD 的设计建立在五个核心原理上。理解这些原理，你就理解了 GSD 为什么这么设计，以及什么时候该用它、什么时候不该。
2.1 规格驱动开发（Spec-Driven Development）
传统开发中，需求文档写完就束之高阁，代码和需求逐渐脱节。GSD 的做法是：需求是活的假设，直到被交付验证才锁定。
具体机制：
- 已验证需求（Validated）：已经交付并确认有价值的需求，锁定不再改
- 活跃需求（Active）：当前阶段正在构建的需求，是「假设」状态
- 需求从 Active 到 Validated 的过程，就是从「我们认为需要」到「用户确认需要」的过程
这避免了一个常见问题：花三周做一个最终没人用的功能。
2.2 阶段化推进（Phase-Based Progression）
GSD 把项目拆成多个阶段（Phase），每个阶段有明确目标和验收标准。阶段之间有严格的依赖关系——前一个阶段没验证，后一个阶段不能开始。
一个里程碑（Milestone）包含多个阶段：
Milestone v1.0
├── Phase 1: 基础架构（数据库、API 骨架）
├── Phase 2: 核心功能（用户系统、文章 CRUD）
├── Phase 3: 增强功能（评论、搜索、标签）
└── Phase 4: 部署上线（CI/CD、监控）
这种拆法的好处：每次交付都是可验证的增量，不是一次性的大爆炸发布。
2.3 原子化操作（Atomic Operations）
GSD 中的每个任务都会产生一个独立的产物——一个 commit、一个 PLAN.md、一个 SUMMARY.md。这意味着：
- 任何操作失败都不会影响已完成的工作
- 你可以精确地追溯「谁在什么时候做了什么决定」
- 工作产物独立于 AI 的记忆存在
2.4 多 Agent 协作（Multi-Agent Orchestration）
GSD 最独特的设计：它不是让一个 Claude Agent 做所有事，而是启动18 个专精 Agent 分工协作。就像一个研发团队：
| 角色 | Agent | 干什么 |
|---|---|---|
| 项目经理 | gsd-planner | 把阶段目标拆成可执行计划 |
| 研究员 | gsd-phase-researcher | 调研技术方案 |
| 执行者 | gsd-executor | 按计划写代码、提交 |
| 质检员 | gsd-verifier | 验证交付物是否达标 |
| 调试员 | gsd-debugger | 系统化排查问题 |
这些 Agent 通过**波次（Wave）**机制并行执行。Wave 1 的 Agent 先跑（无依赖的任务），完成后 Wave 2 接上（依赖 Wave 1 结果的任务）。
2.5 状态持久化（State Persistence）
这是 GSD 解决 Claude Code 最大痛点的方式。所有项目状态存储在 .planning/ 目录：
.planning/
├── PROJECT.md # 项目愿景
├── REQUIREMENTS.md # 需求列表（带 REQ-ID）
├── ROADMAP.md # 阶段路线图
├── STATE.md # 当前状态（上下文恢复用）
├── config.json # 工作流配置
├── phases/ # 各阶段的计划和记录
├── research/ # 调研产出
└── todos/ # 待办事项
你输入 /clear 清空对话后，GSD 读取这些文件就能恢复完整上下文。项目状态不再依赖 AI 的记忆。
本章小结：GSD 的五个原理——规格驱动、阶段推进、原子操作、多 Agent 协作、状态持久化——共同解决了 AI 辅助开发的连续性、可验证性和可恢复性问题。
第3章 项目生命周期
3.1 完整路径：从想法到交付
一个 GSD 项目的完整生命周期：
想法 → 提问 → 调研 → 需求 → 路线图 → 规划 → 执行 → 验证 → 交付
每一步对应一个 GSD 命令：
| 步骤 | 命令 | 产出 |
|---|---|---|
| 启动项目 | /gsd:new-project | PROJECT.md, REQUIREMENTS.md, ROADMAP.md |
| 规划阶段 | /gsd:plan-phase 1 | PLAN.md |
| 执行阶段 | /gsd:execute-phase 1 | 代码 + SUMMARY.md |
| 验证交付 | /gsd:verify-work 1 | 验收报告 |
| 提交 PR | /gsd:ship 1 | Pull Request |
| 完成里程碑 | /gsd:complete-milestone 1.0.0 | 归档 + Git Tag |
3.2 第一步：/gsd:new-project 启动项目
这是整个旅程的起点。运行 /gsd:new-project 后，GSD 会经历四个阶段：
- 提问（Questioning）：GSD 问你一系列问题来理解项目意图——做什么、给谁用、有什么约束
- 调研（Research）：GSD 启动多个 research Agent 并行调研技术栈、竞品、架构方案
- 需求（Requirements）：基于调研结果，生成带 REQ-ID 的需求文档
- 路线图（Roadmap）：把需求拆成多个阶段，定义每个阶段的目标和验收标准
产出的文件结构：
.planning/
├── PROJECT.md # 项目愿景和背景
├── REQUIREMENTS.md # 需求列表
├── ROADMAP.md # 阶段路线图
├── STATE.md # 当前状态
└── research/
├── STACK.md # 技术栈调研
├── FEATURES.md # 功能调研
├── ARCHITECTURE.md # 架构方案
└── SUMMARY.md # 调研总结
3.3 如果是已有项目：/gsd:map-codebase
对于不是从零开始的项目，用 /gsd:map-codebase 扫描现有代码库。它会生成 7 份聚焦文档：技术栈、架构、目录结构、编码规范、测试策略、集成点、潜在问题。
这让你能在 GSD 框架下接手和管理已有项目。
本章小结：GSD 的项目生命周期分为启动（new-project 或 map-codebase）、规划、执行、验证、交付五个阶段。每一步都有明确命令和产出文件。
第4章 阶段执行引擎
4.1 Plan-Execute-Verify 循环
GSD 的核心执行单元是一个三步循环：
Plan（规划）→ Execute（执行）→ Verify（验证）
这三个步骤分别由不同的 Agent 完成，确保「规划的不执行、执行的不验证」——就像现实中的研发团队分工。
4.2 规划阶段：/gsd:plan-phase
运行 /gsd:plan-phase 1 后：
- GSD 读取 ROADMAP.md 中 Phase 1 的描述
- 启动 gsd-planner Agent，把阶段目标拆成具体的执行计划
- 启动 gsd-plan-checker Agent，检查计划质量——依赖是否合理、任务粒度是否合适
- 产出 PLAN.md 文件
一个 PLAN.md 包含：
- 任务列表：每个任务有明确的输入、输出、验收标准
- 依赖关系：哪些任务必须先完成，哪些可以并行
- 波次分组：Wave 1（无依赖）、Wave 2（依赖 Wave 1）……
4.3 执行阶段：/gsd:execute-phase
这是最核心的命令。运行 /gsd:execute-phase 1 后：
- GSD 读取该阶段的所有 PLAN.md
- 按波次启动 gsd-executor Agent
- Wave 1 的任务并行执行（多个 Agent 同时工作）
- Wave 1 完成后，Wave 2 开始
- 每个任务完成后自动 commit
执行模式选择：
| 模式 | 命令 | 特点 |
|---|---|---|
| 并行（默认） | /gsd:execute-phase 1 | 多 Agent 同时执行，最快 |
| 顺序 | /gsd:execute-phase 1 --interactive | 逐步执行，每步确认 |
| 指定波次 | /gsd:execute-phase 1 --wave 2 | 只执行某个波次 |
4.4 验证阶段：/gsd:verify-work
执行完成后，运行 /gsd:verify-work 1：
- gsd-verifier Agent 检查：产出文件是否存在、功能是否符合需求、测试是否通过
- 生成验证报告
- 如果发现问题，标记需要修复的项
验证不只是「能跑就行」。GSD 的验证标准包括：
- 功能是否实现
- 代码质量是否达标
- 是否有遗漏的边界情况
- 是否与原始需求一致
4.5 暂停与恢复
工作中途需要暂停？用 /gsd:pause-work 创建上下文交接文档。回来时用 /gsd:resume-work 恢复完整状态。
或者更简单——直接用 /gsd:progress，GSD 会读取 .planning/ 目录告诉你「你现在在哪、下一步该做什么」。
本章小结：GSD 的执行引擎是 Plan → Execute → Verify 循环，由不同 Agent 分工完成。支持并行、顺序、指定波次三种执行模式，以及随时暂停和恢复。
第5章 多 Agent 协作
5.1 为什么需要多个 Agent？
一个 Claude Agent 做所有事的问题：
- 上下文污染：调研信息、规划细节、代码实现挤在一个上下文窗口里，互相干扰
- 角色混淆：同一个人既当架构师又当码农，容易做出妥协决策
- 无法并行：一个 Agent 只能串行工作
GSD 的解决方案：每个职责由一个专精 Agent 负责，通过文件系统传递信息。
5.2 Agent 职责一览
GSD 有 18 个专精 Agent，分为几个类别：
研究类
- gsd-project-researcher：项目级技术调研（技术栈选型、竞品分析）
- gsd-phase-researcher：阶段级技术调研（具体技术方案）
- gsd-research-synthesizer：综合多个研究 Agent 的发现
规划类
- gsd-planner：创建详细执行计划
- gsd-plan-checker：检查计划质量
- gsd-roadmapper：创建阶段路线图
- gsd-assumptions-analyzer：分析阶段假设
执行类
- gsd-executor：按计划执行任务、写代码、提交
- gsd-debugger：系统化排查问题
验证类
- gsd-verifier：验证交付物是否达标
- gsd-integration-checker：跨阶段集成检查
- gsd-nyquist-auditor：验证覆盖率审计
UI 专项
- gsd-ui-researcher：UI/UX 方案调研
- gsd-ui-checker：UI 实现质量检查
- gsd-ui-auditor：UI 设计一致性审计
5.3 协作机制：通过文件通信
Agent 之间不直接对话——它们通过 .planning/ 目录下的文件通信：
gsd-phase-researcher → research/STACK.md → gsd-planner 读取 → PLAN.md → gsd-executor 读取 → 代码
这种设计的好处：
- 解耦：Agent 之间不互相依赖运行时状态
- 可审计：所有决策都有文件记录
- 可恢复：任何 Agent 都可以从文件恢复完整上下文
5.4 波次执行（Wave-Based Execution）
当一个阶段有多个计划时，GSD 按依赖关系分组为波次：
Wave 1: [计划A, 计划B, 计划C] → 并行执行
↓ 完成
Wave 2: [计划D（依赖A）, 计划E（依赖B）] → 并行执行
↓ 完成
Wave 3: [计划F（依赖D和E）] → 执行
就像建筑工地：地基（Wave 1）和材料采购（Wave 1）可以同时进行，框架搭建（Wave 2）要等地基完成，装修（Wave 3）要等框架完成。
本章小结：GSD 用 18 个专精 Agent 替代单一 Agent，通过文件系统通信，按波次并行执行。这让 AI 开发从「一个人干所有事」变成「团队协作」。
第6章 配置与模式选择
6.1 两种工作模式
GSD 提供两种截然不同的工作模式：
Interactive 模式——适合学习和关键项目：
- 每个重大决策都暂停等你确认
- 适合第一次用 GSD、或做高风险改动
- 更慢，但更有掌控感
YOLO 模式——适合熟练用户和低风险任务：
- 自动批准大部分决策
- 只在关键节点停下
- 更快，但需要信任 GSD 的判断
6.2 Model Profile：成本与质量的权衡
GSD 的 18 个 Agent 都需要调用 Claude 模型。不同模型的成本和质量差异很大：
| Profile | 规划用什么 | 执行用什么 | 验证用什么 | 适用场景 |
|---|---|---|---|---|
| Quality | Opus | Opus | Opus | 关键项目，不差钱 |
| Balanced（默认） | Opus | Sonnet | Sonnet | 大多数场景 |
| Budget | Sonnet | Haiku | Haiku | 预算有限，快速迭代 |
| Inherit | 当前会话模型 | 当前会话模型 | 当前会话模型 | 简单任务 |
实际建议：默认用 Balanced。核心模块用 Quality，实验性功能用 Budget。
6.3 配置文件详解
GSD 的配置存储在 .planning/config.json：
{
"mode": "yolo",
"granularity": "standard",
"parallelization": true,
"model_profile": "balanced",
"workflow": {
"research": true,
"plan_check": true,
"verifier": true,
"nyquist_validation": true,
"auto_advance": false
}
}关键配置项：
- mode：yolo 或 interactive
- granularity：coarse（粗粒度，大任务）/ standard / fine（细粒度，小任务）
- parallelization：是否启用并行执行
- workflow.research：规划前是否自动调研
- workflow.plan_check：是否启用计划质量检查
- workflow.verifier：执行后是否自动验证
6.4 Hooks：工作流守护
GSD 提供 5 个 Hooks 来守护工作流：
- workflow-guard：当你在 GSD 项目中直接编辑文件而不通过 GSD 命令时，温柔提醒你用
/gsd:quick或/gsd:fast - prompt-guard：验证 GSD 命令调用是否合法
- check-update：检查 GSD 版本更新
- statusline：在状态栏显示 GSD 当前状态
- context-monitor：监控上下文使用量
本章小结：GSD 的配置决定了工作模式（Interactive/YOLO）、成本策略（Model Profile）和自动化程度（workflow toggles）。根据项目阶段和风险级别灵活调整。
第7章 实战演练
7.1 场景设定
我们要做一个「个人读书笔记」Web 应用：
- 功能：添加/编辑/删除读书笔记，按书名和标签搜索
- 技术栈：待定（让 GSD 调研）
- 交付标准：能部署运行、有基本 UI
7.2 Step 1：启动项目
/gsd:new-project
GSD 会问你一系列问题。回答要点：
- 项目名称：book-notes
- 项目描述：个人读书笔记 Web 应用
- 用户：自己，偶尔分享给朋友
- 技术偏好：无，让 GSD 推荐
- 交付时间：不急，质量优先
GSD 完成调研后会生成：
.planning/PROJECT.md：项目愿景.planning/REQUIREMENTS.md：需求列表.planning/ROADMAP.md：阶段路线图（比如 Phase 1 基础架构、Phase 2 核心功能……）
7.3 Step 2：查看路线图
/gsd:progress
GSD 会告诉你当前状态和下一步建议。假设路线图是：
- Phase 1：基础架构（项目初始化、数据库设计、API 骨架）
- Phase 2：笔记 CRUD（增删改查）
- Phase 3：搜索和标签
- Phase 4：UI 美化和部署
7.4 Step 3：规划 Phase 1
/gsd:plan-phase 1
GSD 启动 gsd-planner，读取 Phase 1 的描述，生成多个执行计划。然后 gsd-plan-checker 检查计划质量。
产出：.planning/phases/01-foundation/01-01-PLAN.md 等文件。
7.5 Step 4：执行 Phase 1
/gsd:execute-phase 1
GSD 按波次启动 gsd-executor Agent。Wave 1 可能是：初始化项目、创建数据库 schema。Wave 2 可能是：实现 API 路由（依赖数据库 schema）。
每个任务完成后自动 commit。全部完成后生成 SUMMARY.md。
7.6 Step 5：验证
/gsd:verify-work 1
gsd-verifier 检查：项目能启动吗？数据库能连接吗？API 能响应吗？全部通过后标记 Phase 1 完成。
7.7 Step 6：继续后续阶段
重复 Step 3-5 依次执行 Phase 2、3、4。
7.8 Step 7：交付
/gsd:ship 1
为 Phase 1 创建 PR。所有阶段完成后：
/gsd:complete-milestone 1.0.0
归档里程碑，打 Git Tag，准备下一轮迭代。
7.9 快捷路径：/gsd:quick 和 /gsd:fast
不是所有任务都需要完整流程。对于小任务：
/gsd:fast "给按钮加个 loading 状态"：3 个文件以内的小改动，直接执行，不创建规划文件/gsd:quick "重构用户模块的错误处理"：中等任务，创建轻量规划，有计划检查和验证/gsd:quick --full "添加国际化支持"：完整流程（含调研、计划检查、验证）
本章小结：通过一个读书笔记应用的实战，演示了 GSD 从启动到交付的完整流程。小任务用
/gsd:quick或/gsd:fast简化。
第8章 常用命令速查
8.1 按场景找命令
刚开始一个项目？
| 你的情况 | 命令 | 说明 |
|---|---|---|
| 全新项目 | /gsd:new-project | 完整启动流程 |
| 已有代码库 | /gsd:map-codebase | 扫描并理解现有项目 |
| 有个模糊想法 | /gsd:plant-seed <想法> | 记录想法，以后再启动 |
正在开发中？
| 你的情况 | 命令 | 说明 |
|---|---|---|
| 要规划下一阶段 | /gsd:plan-phase N | 创建执行计划 |
| 要开始执行 | /gsd:execute-phase N | 并行执行计划 |
| 只想执行某个波次 | /gsd:execute-phase N --wave 2 | 指定波次 |
| 想逐步执行 | /gsd:execute-phase N --interactive | 逐步确认 |
| 不知道该干嘛 | /gsd:progress | 查看状态和下一步 |
| 中途要暂停 | /gsd:pause-work | 保存上下文 |
| 回来继续 | /gsd:resume-work | 恢复上下文 |
完成了一部分？
| 你的情况 | 命令 | 说明 |
|---|---|---|
| 要验证成果 | /gsd:verify-work N | 验收检查 |
| 要提交 PR | /gsd:ship N | 创建 PR |
| 要做 UAT | /gsd:verify-work N | 对话式验收 |
| 要检查所有 UAT | /gsd:audit-uat | 全局 UAT 审计 |
小任务？
| 你的情况 | 命令 | 说明 |
|---|---|---|
| 改几个文件 | /gsd:fast <描述> | 极简执行（≤3 文件） |
| 中等任务 | /gsd:quick <描述> | 轻量规划+执行 |
| 完整小流程 | /gsd:quick --full <描述> | 含调研和验证 |
| 不确定用哪个 | /gsd:do <描述> | 智能路由 |
项目管理？
| 你的情况 | 命令 | 说明 |
|---|---|---|
| 加一个新阶段 | /gsd:add-phase <描述> | 追加到末尾 |
| 插入紧急任务 | /gsd:insert-phase N <描述> | 插入为 N.1 阶段 |
| 开始新里程碑 | /gsd:new-milestone <名称> | 开始下一版本 |
| 完成里程碑 | /gsd:complete-milestone <版本> | 归档并打 Tag |
| 记个想法 | /gsd:note <文字> | 零摩擦记录 |
| 配置工作流 | /gsd:settings | 交互式配置 |
8.2 快速决策树
你想做什么？
├── 新项目 → /gsd:new-project
├── 已有项目想用 GSD → /gsd:map-codebase
├── 规划阶段 → /gsd:plan-phase N
├── 执行阶段 → /gsd:execute-phase N
├── 验证阶段 → /gsd:verify-work N
├── 小改动（≤3文件）→ /gsd:fast
├── 中等任务 → /gsd:quick
├── 不知道 → /gsd:do
├── 查看进度 → /gsd:progress
└── 配置调整 → /gsd:settings
本章小结：按「刚开始」「开发中」「完成部分」「小任务」「项目管理」五个场景分类速查常用命令。决策树帮你快速找到正确的命令。
第9章 练习与自检
9.1 用 GSD 启动一个小项目
用 /gsd:new-project 初始化一个 TODO 命令行应用。观察 GSD 的提问流程、调研过程和产出文件。
检查点：
.planning/目录是否创建？- PROJECT.md、REQUIREMENTS.md、ROADMAP.md 是否生成？
- 路线图的阶段划分是否合理？
9.2 用 /gsd:quick 完成一个功能
在刚才的项目中，用 /gsd:quick "添加按优先级排序功能" 完成一个小功能。感受 quick 模式和完整流程的区别。
检查点：
- 是否创建了轻量规划文件？
- 代码是否自动 commit？
- 是否有 SUMMARY.md？
9.3 暂停和恢复
在执行过程中用 /gsd:pause-work 暂停。然后用 /clear 清空对话，再用 /gsd:resume-work 恢复。
检查点：
- 暂停时是否生成了上下文交接文档？
- 恢复后 GSD 是否知道「我该继续做什么」？
9.4 自检清单
完成以上练习后，用这个清单检查你的理解程度：
| 能力 | 掌握？ |
|---|---|
| 能说清楚 GSD 解决什么问题 | ☐ |
能用 /gsd:new-project 启动项目 | ☐ |
能用 /gsd:plan-phase 和 /gsd:execute-phase 管理阶段 | ☐ |
能用 /gsd:verify-work 验证交付物 | ☐ |
| 理解 Interactive 和 YOLO 模式的区别 | ☐ |
知道什么时候用 /gsd:quick vs /gsd:fast | ☐ |
能用 /gsd:progress 查看项目状态 | ☐ |
能用 /gsd:pause-work 和 /gsd:resume-work 断点续行 | ☐ |
延伸阅读
- GSD 官方仓库：https://github.com/anthropics/claude-code（GSD 作为 Claude Code skill 运行）
- 运行
/gsd:help查看完整命令参考 - 运行
/gsd:settings探索配置选项 - 运行
/gsd:join-discord加入 GSD 社区