GSD 深度剖析：从架构到状态机，再到 57 个命令背后的设计GSD 深度剖析：从架构到状态机，再到 57 个命令背后的

GSD 深度剖析：从架构到状态机，再到 57 个命令背后的设计

0. 太长不读

GSD 第一眼很容易被看成一套 Prompt 框架，但真把仓库翻完，感觉会完全不一样。它做得很重，而且这个“重”不是堆概念，是真往工程系统那个方向走了。

它关心的也不是“让 Agent 回答更聪明”，而是把从想法到交付这条线搭起来：需求拆分、阶段规划、并行执行、验证、发 PR、跨会话恢复，都有对应的命令、workflow、agent 和状态文件。

我先把最核心的 4 个判断摆在前面：

把项目状态写进 .planning/，而不是赌模型一直记得住
把复杂流程拆成 command -> workflow -> subagent -> artifact 这条明确链路
把一部分确定性逻辑外化到 gsd-tools.cjs，不全靠 Prompt 硬扛
用 Wave 并行、原子提交和验证管线，把“能跑起来”推到“能稳定交付”

从本地仓库看，GSD v1.30.0 已经不是“小而美”的 skill 包了，更像一套完整的工程底盘：

57 个命令入口
56 个 workflow
18 个 agent
一层真正的 CLI
一整套 .planning/ 文件协议

压成一句话的话，我会这么写：

GSD 不是在给 Agent 补一点记忆，而是在给项目补一套能持续往前走的结构。

1. 它到底是什么

README 里的自我定义是：

A light-weight and powerful meta-prompting, context engineering and spec-driven development system

这句话很长，不过拆开就清楚了。

1.1 它不是单个 prompt，也不是几个 skill 的合集

GSD 当然有 Prompt，也有 agent，但它的骨架远不止这些。仓库里至少有这几层：

安装器：bin/install.js
命令入口：commands/gsd/*.md
工作流编排：get-shit-done/workflows/*.md
运行时工具：get-shit-done/bin/gsd-tools.cjs
agent 定义：agents/*.md
模板与参考资料：get-shit-done/templates/、references/
文档系统：docs/

所以它不是“读一段总 prompt，然后模型自由发挥”。更像一套把 Prompt、状态文件、CLI 和多 Agent 协作绑在一起的东西。

1.2 它也不是传统意义上的“企业流程工具”

GSD 的 README 里有一句很出名的话，大意就是：别搞企业表演，直接把事做完。

这不是句口号，它躲的就是这些坑：

Jira 那种流程很重、产出却很虚
规范很多，但模型真正执行时还是乱掉
每轮会话都像重开新项目，根本没有持续性

所以它的取向挺明确：流程可以重，但必须服务交付，不能只服务管理感。

1.3 它卖点不只是“记忆”，而是“项目化”

很多人看到 GSD，会先记住一个词：Context Rot。

没错，它确实在解决上下文腐化。但如果只把它理解成“记忆增强”，还是看窄了。

我更愿意把它看成：它想把 Agent 开发从“临场发挥”拉回“项目推进”。

这里的差别很大：

不是我这轮想到什么，就让模型做什么
而是当前项目在哪个阶段、已有哪份计划、哪些任务完成、有哪些阻塞、下一步该跑什么，系统都能回答

这已经不是单纯的 Prompt 工程了。

2. 从仓库结构看整体架构

基于当前本地仓库，GSD 的核心结构可以先粗看成这样：

get-shit-done/
├── bin/                         # 安装器
├── commands/gsd/               # 57 个命令入口
├── agents/                     # 18 个 agent 定义
├── get-shit-done/
│   ├── bin/gsd-tools.cjs       # CLI 工具层
│   ├── workflows/              # 56 个工作流
│   ├── templates/              # PROJECT/STATE/PLAN/UAT 等模板
│   ├── references/             # 参考规则与说明
│   └── commands/gsd/           # 某些 runtime 的命令适配
├── hooks/
├── sdk/
└── docs/

如果按运行时来理解，它更像下面这个结构：

flowchart TD
    A["用户输入 /gsd:command"] --> B["Command Layer"]
    B --> C["Workflow Layer"]
    C --> D["Subagents"]
    C --> E["gsd-tools.cjs"]
    D --> E
    E --> F[".planning/ 状态文件"]
    F --> C
    F --> D

这里关键的不是文件多，而是分层很清楚。

2.1 Command 层负责“入口体验”

用户面对的是 /gsd:new-project、/gsd:plan-phase、/gsd:execute-phase 这些命令。入口很短，记忆负担不大。

2.2 Workflow 层负责“流程编排”

复杂逻辑都在 workflow 里：什么时候问用户、什么时候拉 research、什么时候派 agent、什么时候进入验证循环。

2.3 CLI 层负责“确定性逻辑”

gsd-tools.cjs 很关键。状态解析、roadmap 更新、plan 索引、提交、frontmatter 处理、UAT 渲染、健康检查，这些都不再塞进 Prompt 里赌模型表现，而是交给 Node 工具。

2.4 `.planning/` 是系统的持久状态层

这也是 GSD 和很多 skill-first 框架最大的分叉点。它不是让模型“记住项目”，而是把项目状态写到磁盘上。

3. 第一层：命令层为什么这么多

第一次看 GSD，最容易被震到的就是命令数量。

当前本地仓库里，commands/gsd/ 有 57 个命令，常见的有：

/gsd:new-project
/gsd:discuss-phase
/gsd:plan-phase
/gsd:execute-phase
/gsd:verify-work
/gsd:ship
/gsd:next
/gsd:quick
/gsd:fast
/gsd:map-codebase
/gsd:pause-work
/gsd:resume-work
/gsd:thread
/gsd:workstreams

如果只从“少即是多”的角度看，你可能会觉得它有点过了。但读完仓库再回头看，这反而是它的强点。

3.1 它不是想让你背命令，而是想把常见路径都做成显式入口

在很多系统里，流程都藏在一条大 prompt 里。你得自己记得：

现在该调研了
现在该规划了
现在该验收了
现在该发 PR 了

GSD 的做法是把这些节点变成显式命令。这样好处很现实：

用户知道系统支持什么
模型也知道“现在处在什么流程节点”
文档、状态、命令名三者是一致的

3.2 它还有一类非常实用的“流程快捷键”

GSD 有个地方我挺喜欢，它不是只做完整流程，也给了很多短路径：

/gsd:next：自动判断下一步
/gsd:quick：轻量任务但保留 GSD 的结构化保障
/gsd:fast：更直接的快速执行
/gsd:forensics：对失败流程做事后排查

这意味着它不是只有一条大主链，而是围绕主链做了很多旁路和补丁口。

4. 第二层：`.planning/` 才是 GSD 的核心

如果只挑一个最能代表 GSD 的设计，我会选 .planning/。

因为这套系统很多看起来“聪明”的地方，最后都落在这里。

4.1 它不是会话记忆，而是文件状态机

GSD 的核心状态文件大致是：

PROJECT.md
REQUIREMENTS.md
ROADMAP.md
STATE.md
config.json
phases/
research/
threads/
seeds/
HANDOFF.json

这些不是“顺手生成的文档”，而是整个系统真正依赖的运行层。

可以画成这样：

flowchart LR
    A["PROJECT.md"] --> P["Planner / Executor / Verifier"]
    B["REQUIREMENTS.md"] --> P
    C["ROADMAP.md"] --> O["Orchestrators"]
    D["STATE.md"] --> O
    D --> P
    E["CONTEXT.md / RESEARCH.md"] --> P
    F["PLAN.md"] --> X["Executors"]
    G["SUMMARY.md / VERIFICATION.md / UAT.md"] --> D
    G --> C

这条链说明一件事：GSD 的上下文不是一次性喂进去的，而是被拆成不同层级的工件，然后按阶段传播。

4.2 `STATE.md` 不是装饰，它真的是“活的”

文档里直接把 STATE.md 叫作项目的 living memory。我觉得这个说法不过分。

它承载的东西包括：

当前 phase
当前进度
已做决策
blockers
metrics
当前 focus
human actions pending

更重要的是，它不是只靠模型读写。gsd-tools.cjs 里有一整套 state 子命令去更新它。

4.3 它甚至考虑了并发写状态的竞态问题

GSD 文档里有个细节很能说明它不是“Prompt 玩具”。

并行执行时，多个 executor 可能同时更新 STATE.md。为了解决这个问题，系统用了基于 lockfile 的互斥写入，STATE.md.lock 配合原子创建和超时检测，避免最后一个写入者把前一个 agent 的状态覆盖掉。

这一层一旦出现，性质就变了：

这不是“写得更严谨一点的 workflow”
这是在认真处理多 Agent 并发下的共享状态一致性

4.4 它天然跨 Session

GSD 还有一套 session continuity 设计：

/gsd:pause-work
/gsd:resume-work
/gsd:progress
continue-here.md
HANDOFF.json

这套设计的重点不在“存一份总结”，而在于让上下文重置之后还能接着做，不至于又从头问一遍“我们现在做到哪了”。

这点在真实使用里非常重要。

5. 主链路：GSD 是怎么把 idea 变成代码的

GSD 的主流程其实很清楚：

flowchart TD
    A["/gsd:new-project"] --> B["/gsd:discuss-phase"]
    B --> C["/gsd:plan-phase"]
    C --> D["/gsd:execute-phase"]
    D --> E["/gsd:verify-work"]
    E --> F["/gsd:ship"]
    F --> G["/gsd:complete-milestone / new-milestone"]

看起来像经典的 spec-driven development，但它做了不少自己的取舍。

5.1 `new-project`：先把项目定义出来

/gsd:new-project 不是只建几个文件，它会跑一整套初始化流程：

问题澄清
可选研究
要求提炼
roadmap 生成

最后产出的是：

PROJECT.md
REQUIREMENTS.md
ROADMAP.md
STATE.md
config.json
research 目录

这一步很值钱。很多 Agent 项目一开始只有一句想法，后面全靠会话里边聊边修。GSD 的做法是先把项目底稿立住，后面所有阶段都接着这套东西往下走。

5.2 `discuss-phase`：不是再聊一遍，而是锁定这阶段的实现偏好

README 对这一步解释得很对：Roadmap 里的 phase 通常只有一两句话，直接拿去实现根本不够。

所以 discuss-phase 的职责不是重复需求，而是把这一阶段的偏好、边界、灰区决策收成 CONTEXT.md。

原因很简单，后面的 researcher 和 planner 都会读这个文件。

5.3 `plan-phase`：研究、规划、校验一起做

plan-phase 是 GSD 里我最喜欢的步骤之一，因为它不是“生成计划”这么简单。

它通常会串起三种 agent：

gsd-phase-researcher
gsd-planner
gsd-plan-checker

主线大概是：

如果需要，先 research
生成多个可执行的 PLAN.md
用 checker 做校验循环
最多重试 3 轮

这里的重点是：计划不是一份建议稿，而是准备直接喂给 executor 的执行工件。

5.4 `execute-phase`：Wave 并行是 GSD 最像“系统”的地方

到了执行阶段，GSD 和很多 Agent 框架的差异会非常明显。

它不是简单地“一次开几个 agent”。它会先分析 plan 之间的依赖关系，然后分 wave：

flowchart LR
    A["Wave 1: Plan 01 / Plan 02"] --> B["Wave 2: Plan 03 / Plan 04"]
    B --> C["Wave 3: Plan 05"]

同一 wave 内可以并行，不同 wave 按依赖顺序推进。

这个设计很朴素，但非常有效。它至少解决了三个问题：

哪些任务能并行，不靠执行者临场判断
有依赖的计划不会提前跑
orchestrator 能保持很瘦，只做分组、派发、收集

5.5 `verify-work`：把 UAT 也结构化了

很多系统做到自动验证就停了，但 GSD 还往前走了一步：把用户验收也纳进流程。

verify-work 会：

读取 SUMMARY.md
提取可测试 deliverables
自动生成 UAT.md
一次只让用户验证一个点
把反馈继续写回状态

这里有个判断我很认同：

先告诉用户“应该看到什么”，再问“现实是不是这样”

这比让用户自己发散描述 bug 要高效得多。

6. 上下文工程：GSD 怎么对抗 Context Rot

GSD 的 README 和文档里反复强调上下文工程。这不是宣传语，确实是它整套设计的重心。

6.1 它把上下文分层了

GSD 不会把所有东西一次性塞给一个 agent，而是按层级传播：

项目层：PROJECT.md
范围层：REQUIREMENTS.md
路线层：ROADMAP.md
状态层：STATE.md
阶段层：CONTEXT.md、RESEARCH.md
执行层：PLAN.md
结果层：SUMMARY.md、VERIFICATION.md、UAT.md

这比“整个仓库 + 一大段说明”要可靠得多。

6.2 `map-codebase` 是很被低估的一步

如果你是在已有项目里用 GSD，/gsd:map-codebase 非常重要。

它会并行派出 4 个 mapper agent，直接写出一组结构化文档：

STACK.md
INTEGRATIONS.md
ARCHITECTURE.md
STRUCTURE.md
CONVENTIONS.md
TESTING.md
CONCERNS.md

这里的设计很有意思：

agent 直接把文档写到 .planning/codebase/
orchestrator 只接收确认和摘要
不把大量分析结果重新倒回主会话

这能看出来，GSD 已经很在意“上下文回传成本”这件事。

6.3 XML 计划格式不是形式主义

GSD 的 PLAN.md 里大量使用结构化字段和 XML 风格片段，比如：

<task type="auto">
<verify>
<done>
<acceptance_criteria>

这不是为了看起来高级，而是为了让 executor 更少猜测。

当一个计划同时明确：

要改什么
要看哪些文件
怎么验证
完成标准是什么

那执行者就不太容易在主观理解上跑偏。

7. 多 Agent 编排：GSD 不是“多开几个 Agent”

GSD 的多 Agent 设计，核心并不在数量，而在职责划分和上下文隔离。

7.1 orchestrator 很克制

无论是 new-project、plan-phase 还是 execute-phase，GSD 文档里一直在强调一件事：

orchestrator coordinates, not executes

这句话很关键。它的意思是：

orchestrator 负责发现任务、分组、派发、收集结果
真正的重活交给 fresh subagent

这样做的直接收益是：主会话不会被所有实现细节塞满。

7.2 每个 executor 都拿 fresh context

GSD 文档里直接写了 fresh 200K context window。这也解释了它为什么特别依赖“每个 plan 都足够原子”，这样 executor 不需要继承前面所有执行历史。

这也是为什么它非常强调：

计划要小
计划要独立
同一 phase 的 plan 要能做依赖分析

如果 plan 写不好，Wave 并行就跑不起来。

7.3 并行安全做得很细

GSD 对并行执行时的坑，处理得比我预想中细得多。

比如：

并行 agent 默认 git commit --no-verify，避免 pre-commit hook 互相抢锁
orchestrator 在 wave 结束后统一做 hook 校验
STATE.md 写入有锁
如果某些 runtime 的 subagent completion signal 不可靠，就退回顺序执行或 spot-check

这些都不是“写几句 Prompt 提醒一下”能解决的。

8. `gsd-tools.cjs`：它把多少 Prompt 逻辑挪成了工具

如果说 .planning/ 是 GSD 的状态层，那 gsd-tools.cjs 就是那台把状态真正跑起来的引擎。

这个文件开头那一长串 usage，已经很说明问题了。它集中处理的东西包括：

state 读写
roadmap 解析和更新
requirements 标记完成
phase-plan-index
progress
frontmatter CRUD
verify 系列检查
template fill
audit-uat
init <workflow>

8.1 这层的价值，不在“更快”，而在“更稳”

很多 workflow 里都能看到这样的调用：

node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init plan-phase "$PHASE"

这一步会把当前 workflow 需要的上下文一次性整理出来，形成标准 JSON，然后再交给 orchestrator 使用。

这就有两个直接好处：

Prompt 不用自己再现场解析一堆文件
同一个 workflow 在不同 runtime 下更容易保持一致行为

8.2 它还把一部分“操作系统活”做掉了

除了运行时工具，bin/install.js 也挺有代表性。

它处理的不只是安装文件复制，而是：

多 runtime 安装目标
Codex / Gemini / Claude / Cursor / Copilot / Windsurf / Antigravity 适配
sandbox 策略
配置目录解析
hooks 和 instructions 写入

这说明 GSD 不是“先写一套 Prompt，再顺手发个 npm 包”。它一开始就把跨平台落地当成正式问题来做。

9. 10 个最值得看的命令 / 工作流

这一节我不打算把 57 个命令逐个列完，那样没什么阅读价值。更有意思的是，哪些命令最能体现 GSD 的系统设计。

9.1 `new-project`

这是整个系统的起点。它决定的不是“项目名叫什么”，而是后面所有 artifact 的初始质量。

9.2 `discuss-phase`

它让 phase 不只是 roadmap 里的一个标题，而是有清晰偏好和边界的实现上下文。

9.3 `plan-phase`

这是 GSD 把“研究、规划、校验”揉成一个动作的地方，也是执行质量的分水岭。

9.4 `execute-phase`

如果只看一个 workflow，我会推荐看这个。Wave 分组、并行执行、atomic commit、summary 生成，全在这里。

9.5 `verify-work`

它把 UAT 也结构化了，不让“验证”停留在自动测试通过这一步。

9.6 `next`

/gsd:next 特别像一个小型路由器。它会读 STATE.md、ROADMAP.md 和 phase 目录，然后直接决定下一步该跑哪个命令。

这类命令的意义不是省几次输入，而是减少流程犹豫。

9.7 `map-codebase`

对于已有项目，这一步很值。它把“读代码库熟悉环境”做成了结构化资产，而不是一次性的探索结果。

9.8 `quick` 和 `fast`

这两个命令说明 GSD 不是死板系统。它知道不是每件事都值得完整走 phase 流程，所以保留了轻量模式。

9.9 `pause-work / resume-work / progress`

这是 GSD 跨会话体验的关键。没有这组命令，.planning/ 只是一堆文件；有了它们，系统才真正有连续性。

9.10 `thread / plant-seed / workstreams`

这三个命令特别能体现 GSD 的野心。

thread：给跨会话但不属于某个 phase 的问题一个轻量容器
plant-seed：把未来想法带着触发条件存起来，等下一个 milestone 自动浮出
workstreams：在同一代码库里隔离多条并行规划状态，避免互相踩

严格说，这已经不只是“开发流程工具”了，而是在做项目操作层。

10. 大家都知道它是做“记忆”和“流程”的，我反而更想强调这几个强处

如果只说 GSD 能抗 Context Rot，这篇文章其实不用写这么长。更让我在意的，是下面这些地方。

10.1 它把“会话”升级成了“工程”

很多 AI 编程工具，本质还是一轮轮会话。GSD 在做的事，是把会话外面的工程骨架补齐：

状态
路线图
阶段边界
执行记录
验证记录
handoff

这套东西一旦立住，项目就不再完全依赖“这轮会话状态好不好”。

10.2 它真的在做 runtime 兼容，而不是 README 兼容

README 里支持的 runtime 很多，但更难的是让这些 runtime 真的能用。

从安装器和 workflow 文本里能看出来，GSD 认真处理了：

Claude Code 的 Task
Copilot completion signal 不可靠时的退化路径
Codex 的 skills-first 安装方式
全局 / 本地配置目录差异

这类工作很琐碎，但决定了一个框架能不能真的落地。

10.3 它对“失败”有补救链路

很多框架在 happy path 上都很好看，一出问题就散了。GSD 这边至少留了一整套补救命令和状态层：

forensics
diagnose-issues
debug
verify-work
pause-work / resume-work

这说明它不是只为演示场景设计的，作者确实在想“出事之后怎么办”。

10.4 它的设计已经开始朝“多项目 / 多工作流 / 多阶段并发”走了

workstreams、manager、threads、seeds 这些能力说明，GSD 想处理的已经不只是单线程 feature delivery。

它开始碰的是更难的问题：

多条规划状态怎么隔离
未来想法怎么不丢
长期项目怎么不被当前 phase 吞掉

这部分未必每个人都用得上，但很能说明它的上限。

11. 这套系统最强的地方

11.1 它把“计划”真的变成了执行介质

很多系统也写 plan，但最后 plan 只是供人类看看。GSD 里的 PLAN.md 不是，它就是给 executor 吃的。

这会倒逼前面的计划写得更具体，也让后面的执行更少漂移。

11.2 它把多 Agent 变成了一条受控流水线

不是每个系统都能把多 Agent 做得很稳。GSD 能跑起来，是因为它先把：

状态
依赖
分工
验证

这些东西补齐了。

11.3 它很适合长期项目

如果你做的是一个能持续几周、几个月推进的项目，GSD 的价值会越来越明显。因为它不只是帮你写当前任务，而是在帮你维持整个项目的推进结构。

12. 它的代价和局限

说完优点，也得说代价。GSD 绝对不是没有成本的。

12.1 它真的偏重

57 个命令、56 个 workflow、18 个 agent，再加一套 .planning/ 状态层，这不可能是轻系统。

如果你只是想改一个小脚本，这套东西很可能显得过于正式。

12.2 它要求你接受“文档就是运行面”

很多开发者天然抗拒再多一层 Markdown 工件。GSD 恰恰相反，它把 Markdown 工件变成了运行协议。

你如果不愿意维护这些东西，系统优势就发挥不出来。

12.3 它对计划质量要求很高

Wave 并行好不好用，取决于：

phase 切得对不对
plan 原子性够不够
依赖分析准不准

这些前置工作没做好，多 Agent 反而会放大混乱。

12.4 它更像系统产品，不像一把小刀

这不是批评，只是得先说清楚：GSD 不会像一个小 skill 那样“装上就几乎没存在感”。

它是有存在感的，也确实会改变你的工作方式。

13. 什么时候最适合用 GSD

我会更推荐在下面这些场景里用它：

你在做一个会持续推进的产品，而不是一次性脚本
你很在意跨会话连续性，不想每次都重新热身
你希望 Agent 的工作能被拆成 phase、plan、summary、verification 这些清晰工件
你愿意用 Git 和文件工件换稳定性
你想把多 Agent 协作真正工程化

不那么适合的场景也很清楚：

只是随手试个 idea
团队根本不愿意维护 .planning/
你更偏好极简 skill-first，而不是状态驱动系统
你现在的核心诉求只是“回答更聪明”，不是“项目更可控”

14. 总结：GSD 不是给 Agent 加外挂，而是在给项目加底盘

看完仓库以后，我对 GSD 的印象很明确：它最值得学的地方，不是某个命令，也不是某个 agent prompt，而是它背后的系统判断。

可以压成 5 条：

项目状态不能只活在会话里
流程节点应该有显式命令入口
多 Agent 协作必须建立在工件和依赖分析上
确定性逻辑能外化就外化
验证、验收、恢复、补救都要纳入主系统

如果只用一句话概括：

GSD 做的不是“让 Agent 更会写代码”，而是“让一个项目在 Agent 参与下还能持续、有序、可恢复地往前走”。

也正因为这样，我觉得它值得认真研究。它碰到的已经不是 Prompt 怎么写，而是一个更硬的问题：

当 AI 真的开始参与长期软件开发时，项目本身该用什么结构来承载它。

参考资料

GSD 仓库：gsd-build/get-shit-done — GitHub
README.md
package.json
bin/install.js
get-shit-done/bin/gsd-tools.cjs
get-shit-done/workflows/new-project.md
get-shit-done/workflows/plan-phase.md
get-shit-done/workflows/execute-phase.md
get-shit-done/workflows/execute-plan.md
get-shit-done/workflows/verify-work.md
get-shit-done/workflows/map-codebase.md
get-shit-done/workflows/next.md
docs/ARCHITECTURE.md
docs/USER-GUIDE.md
docs/FEATURES.md
Tw93《你不知道的 Agent：原理、架构与工程实践》— 原文

GSD 深度剖析：从架构到状态机，再到 57 个命令背后的设计