GSD Core 工作流怎么用

0030 秒速览：读完你能做什么

读完这一篇，你能做出三个判断：这套流程值不值得你付那份"仪式成本"；在五步里哪一步你必须亲自在场；以及为什么一份正经教程会反复叫你用 /clear 把聊天记录清空——而这个动作居然不会丢进度。

按你现在的处境，直接跳到对应那一节

先给一组量级

01它是什么，以及它不是什么

官方的一句话定义

仓库 README 的第一句是这么写的（原文）：

翻译成人话，这句话里有三个需要解释的词：

• 上下文工程（context engineering）：不是一个新学科，就是"决定每次喂给 AI 多少、哪些文字"这件事。喂得越杂，它越糊。
• 规格驱动开发（spec-driven development）：先写清楚"要做成什么样"（规格），再让 AI 动手写代码。这里的"规格"不是文档仪式，而是几个AI 会真的去读的文件。
• 阶段循环（phase loop）：把整个项目切成一块一块的"阶段"，每一块都要完整走完五步才能进入下一块。这是这篇的主线。

它的名字 GSD 是 "Git. Ship. Done." 的缩写——"提交、发布、收工"。仓库 README 页面顶部就是这么写的。

它到底是什么形态的东西？

这一点新手最容易搞混，所以直接说清楚：GSD 是一个 npm 包，装进你已经在用的 AI 编程工具里，给你加一批斜杠命令和一批"干活用的 AI 角色"。

它不是一个新的 AI 工具、不是一个新的聊天界面、更不是一个新的模型。你原来用 Claude Code，装完还是用 Claude Code；你原来用 Codex，装完还是 Codex。它只是往你那个工具里塞了东西。

它由三个部件组成

它容易被误当成什么

02它唯一要治的病：上下文腐烂

从一个你一定经历过的场景开始

早上你打开 AI 编程工具，让它改一个登录逻辑。它答得很准。你接着让它加个校验、顺手改下报错文案、再修一个测试。到了下午，你发现它开始忘事：明明上午说好"这个项目不许用某个库"，它刚刚又给你写上了；明明上午定下的函数命名风格，它现在换了一套。

你没换工具，也没换模型。变的只有一个东西：这个对话窗口里累积的文字量。

两个必须先建立的词

• token（词元）：AI 读文字不是按"字"读，是按 token 读。你可以粗略理解成"它眼里的一个文字块"——一个英文单词大约 1 个 token，一个汉字大约 1~2 个。它的收费、速度、容量都按这个单位算。
• 上下文窗口（context window）：AI 在一次回答里最多能"看见"的 token 总量。它是有限的——就像一张一次只能摊开这么大的桌面，你往上堆的材料越多，每份材料占到的注意力就越少。GSD 的文档里反复提到的"200K 窗口"，指的是 200,000 个 token 的容量。

官方给这个病起的名字

文档列了它腐烂时的四种典型症状，每一条都对得上你的体感：

为什么"让它记住更多"是错的解法

碰到上面这些症状，最自然的反应是：那我再强调一遍，或者换个记性更好的模型。GSD 的文档明确否掉了这条路，理由值得完整读一遍：

所以正确的解法方向不是"喂得更多"，而是"每一件重活，都换一个只带着必需材料的新 AI 来干"。

它实际怎么做到"换人"

GSD 把一次工作分成两种角色：

• 编排器（orchestrator）——就是你的主对话窗口。它几乎不碰源码：只负责派活、收回结果、更新状态、决定下一步。因为干得少，它自己的窗口涨得很慢。官方原话是 "The orchestrator — your main session — never touches source files."
• 子代理（subagent）——被派出去的临时工。每一个都从零开始，只拿到它这件任务需要的材料（项目摘要、阶段上下文、研究结论、以及它自己那份计划），干完把结果写进文件就结束。

于是"为什么教程叫我 /clear"就有答案了

/clear 是 Claude Code 里"清空当前对话记录"的命令。第一次看到教程让你在阶段之间反复清空，几乎所有人的反应都是：那不是把记忆洗掉了吗？

关键在这一点区分：需要留下来的东西，从来不在对话里，而在文件里。规划代理写下的计划、讨论阶段定下的决定、执行代理写的总结——全都落进了项目里的 .planning/ 目录。任何一个新开的代理都能直接去读这些文件，不需要读过你们的聊天记录。

一个类比，以及它在哪里失效

你可以把上下文窗口想成一张办公桌：桌面就这么大，你每处理一件事就往上摊一份材料。摊到某个程度，你要找的东西还在桌上，但已经被压在一堆纸下面——你不是没放，是找不到了。GSD 的做法是每处理一件大事，就换一张干净的桌子，只把这件事要用的那几份材料搬过去，干完把结论归档到柜子里。

03装上去

先说前置条件，这里官方文档自己打架

我把三处提到 Node 版本的地方都找出来了，它们是三个不同的数字：

还有第四处旁证：仓库根目录的 .nvmrc 文件写的是 24（这类文件的作用是"告诉版本管理工具该用哪个 Node"），以及维护者自己的测试文档 docs/TESTING-SUITES.md 里写着 "All lanes run on Node 24 — the engines.node floor (>=24.0.0)"。也就是说：他们自己开发用的是 24。

装：一条命令

GSD 发布在 npm 上——npm 是 Node.js 的包仓库，相当于它自己的应用商店；包名是 @opengsd/gsd-core。下面的命令用的是 npx，意思是"把这个包下载下来并直接运行一次"，所以你不需要先安装任何东西。官方要求必须走安装器，不要手动拷贝文件：

# 通用形式：在任意目录运行，安装器会问你要装在哪个工具里
npx @opengsd/gsd-core@latest

也可以直接指定工具和作用范围（全局 = 所有项目可用；本地 = 只在这个项目里可用）：

# Claude Code，全局安装（技能落到 ~/.claude/）
npx @opengsd/gsd-core@latest --claude --global

# Claude Code，只装进当前项目（新手教程用的是这个）
npx @opengsd/gsd-core@latest --claude --local

# 装到别的配置目录（比如你在用预览版的 Claude Code）
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global

安装器会依次问你两件事：装进哪个工具、以及全局还是本地。装完记得重启你的 AI 工具——命令是启动时加载的，不重启敲 /gsd- 是找不到的。

支持哪些工具（这个数字官方给了三个版本）

这一处也是文档打架的地方，而且这次我找到了"唯一可执行的那份真相"——安装器源码里能选的运行时列表，正好 18 个：

那 18 个是：Claude Code、Antigravity、Augment、Cline、CodeBuddy、Codex、Copilot、Cursor、Hermes Agent、Kimi、Kimi Code、Kilo、OpenCode、pi、Qwen Code、Trae、Windsurf、ZCode。注意里面没有 Gemini CLI——安装器里写着它已被移除，理由是"Gemini CLI 于 2026-06-18 被 Google 下线，GSD 现在支持 Antigravity CLI"。如果你手上的旧文档（包括本仓的 zh-CN 官方文档）还写着 --gemini，那是过期内容。

几个值得单独知道的：

官方给了一句关键的兼容性说明（原文）："The hyphen and colon forms are runtime-specific spellings of the same command. Whichever runtime you're on, the installer writes the correct form into your runtime's command directory."——连字符形式和冒号形式是同一条命令在不同工具里的写法，安装器会自动写对，你不用记两套。

一个真实的坑：别去跟 @next

官方有一份 VERSIONING.md，说预发布版本用 next 这个 npm 标签发布，并给了 npx @opengsd/gsd-core@next 作为尝鲜写法。但我查 npm registry 的实际标签状态是这样的：

也就是说：@next 现在指向的是一个比正式版旧了将近两个月的候选版。你如果按文档去装 @next 想"尝鲜"，实际拿到的是退版本。这个 next 标签没跟着往前走——一条纯靠查 API 才能发现的事，散文文档里看不到。

安装器会依次问你什么

不带参数跑 npx @opengsd/gsd-core@latest 时，它按固定顺序问四件事（后两个只在特定条件下出现）：

1. 装进哪个运行时——列出 18 个选项加一个 "All"；可以多选，用 1,2,6 或 1 2 6 这种写法。直接回车默认选 Claude Code。
2. 装全局还是本地——默认全局。
3. （仅当检测到你已有状态栏时）要不要用 GSD 的状态栏替换它——默认保留你原来的。
4. （仅当状态栏最终不会安装时）要不要装一个"有新版本"的更新提示条——默认不装。

在非交互环境（比如 CI）里跑，它不提问，直接按"Claude Code + 全局"默认执行。

另外有一个省资源的选项值得知道：--minimal（或 --profile=<名字>）只装一个最小技能集——官方给的口径是核心档 8 个技能，标准档 15 个，而完整安装的"冷启动开销"按 docs/install-minimal-and-add-skills.md 的表格是 130 / 700 / 1,200 个 token 量级。如果你只是想先试试水，这条路能让你的 AI 工具每次启动少读一大段技能清单。但注意官方两处给的数字对不上：安装器自己的帮助文本写的是"从约 12k token 降到约 700"，和上面那张表不是一个口径。

装完怎么确认成功

# 1) 重启你的 AI 工具，然后敲任意一个 GSD 命令看认不认
/gsd-help

# 2) 想知道它到底装进来了什么、健康不健康
/gsd-health

# 3) 只有 Claude Code 有这条：检查有没有全局/本地打架
/gsd-surface

/gsd-health 是官方文档里明说的诊断入口，能查出"本地和全局都装了、到底哪个在生效"这类问题（它会以 W028 这个诊断编号报出来）。这个冲突在 Claude Code 上是真实存在的：官方解释过个人作用域会覆盖项目作用域、技能会覆盖同名命令，所以全局装的那份永远赢。

它到底往你机器上放了什么

以 1.13.0 的实际包体为准（我下载 tarball 数过）：

• 72 个命令文件放在 commands/gsd/ 下。顺带一提：官方新手教程里写的输出是 "✓ Installed 71 commands"，比实际少一个——教程那一行已经过期了，不用以为自己装漏了。
• 35 个代理定义（agents/gsd-*.md）。这个数字官方文档内部也不一致：docs/AGENTS.md 开头写"22 主力 + 12 专项 = 34 个"，同一份文件往下 12 行又写"Thirteen additional […] 权威名单是 35 个"。我按文件数了一遍，是 35——那个"34"是错的。
• 72 个技能目录、89 份工作流定义、31 个 hook 脚本（都是我在包体里数的）。

04第 0 步：立项，或者接手一个老仓库

五步循环是"每个阶段"的循环。在进入循环之前，你得先有一个项目——有路线图、有需求清单。这一步是两种走法二选一：

全新项目：它会问你什么

第一个问题永远是"What do you want to build?"——你想做什么。接着是一轮澄清提问，然后是工作流设置（研究开关、粒度、模型档位等）。最后它会给你一份路线图（roadmap）请你批准，长这样：

Proposed Roadmap
1 phase | 4 requirements mapped | All v1 requirements covered ✓

| # | Phase    | Goal                                   | Requirements    |
|---|----------|----------------------------------------|-----------------|
| 1 | Core CLI | add / list / done commands, todos.json | CLI-01 … CLI-04 |

两个词要解释：

• 阶段（phase）：路线图上的一行，也就是"一次可以研究清楚、规划得动、执行得完、验证得了"的工作量。上面这份路线图只有一个阶段。
• 需求编号（REQ-ID）：像 CLI-01 这样的稳定编号，一块一块对应到阶段。它的用处是可追溯——执行完能对账"这四条需求是不是都做了"。这个对账不是靠人肉，是规划检查器和验证器真去读的。

接手老仓库：它为什么不能一步到位

/gsd-onboard 的设计是"不嵌套、不覆盖"：它把三件事串起来但分开跑——《先摸清代码库》（/gsd-map-codebase）、《可选地把已有文档吃进来》（/gsd-ingest-docs）、《初始化项目》（/gsd-new-project），并且不会静默覆盖你已有的规划文件。文档里明说初始化前必须有一份完整的代码库地图，就算你加了 --fast 让它先做轻量映射，也仍然要在项目初始化之前补全。

它跑完会在 .planning/onboarding/SUMMARY.md 留一份接手记录，里面写着"该跑的下一步是哪个命令"。

里程碑又是另一个层级

你会在文档里反复看到 milestone（里程碑）这个词，它跟阶段不是一回事：

简单说：路线图从上往下是"里程碑 → 阶段"，而你日常打交道的是阶段。大多数时间你根本不需要想起里程碑。

05五步循环总览

这是一张你在官方文档里会看到很多次的流程图。它的完整形态其实有六格——中间那格是可选的前端设计环节：

Discuss →（UI design，可选）→ Plan → Execute → Verify → Ship

五步对照表

耗时一列来自官方新手教程，属于"小而简单的项目"的量级，当成下限看——真实项目里研究和执行都可能明显更长。

这张表就是全部心智模型

每一步之间都清空一次

官方文档把这条列为"长会话里上下文退化的处理办法"，并且写得很直接：

原因已经在 02 讲透了：进度在 .planning/，不在对话里。清空之后用 /gsd-progress 或 /gsd-resume-work 就能把状态读回来。

06Discuss：把"怎么做"写下来

为什么这一步不能省

路线图里的阶段描述只说了要达成什么结果（比如"命令行能加、能列、能勾掉待办"），但没说走哪条路达成：用哪个库、错误怎么处理、边界情况怎么表现、某个功能放在全局还是每一处各写一遍。

如果不讨论，这些决定就由规划代理自己拍板。官方对这个风险的描述很到位（原文）：

它实际问出来的问题长什么样

官方教程里的真实片段（为一个待办清单程序讨论）：

> How should done items be stored — mark them in place or move them?
  Mark them in place with a "done" flag.
> Should `todo list` show completed items by default?
  No, hide them unless --all is passed.
> What if todos.json doesn't exist yet?
  Create it silently on first add.

注意这三个问题的形状：它们都不是"你要什么功能"，而是"这个功能具体怎么表现"。这种问法正是这一步的价值——它在你还没花一分执行成本的时候，把分岔路口一个个堵上。

产物：两个文件

常用的几个开关

07Plan：拆成能互不打架的小计划

这一步是整条流程里最厚的一步，因为它内部其实跑了三个不同角色，顺序执行：

一份计划长什么样

每份 PLAN.md 开头是一段叫 frontmatter 的元数据（夹在两行 --- 之间、机器读的结构化字段；.planning/ 里几乎所有文件都有）。官方给的例子：

---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
  - src/components/PostFeed.tsx
  - src/components/PostCard.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]

must_haves:
  truths:
    - "User can scroll through posts from followed accounts"
    - "Each post shows author avatar, name, timestamp, and content"
  artifacts:
    - path: "src/components/PostFeed.tsx"
      provides: "Scrollable post list"
      min_lines: 40
---

文件名的编号规则是"阶段号-计划号-类型"：03-02-PLAN.md 读作"第三阶段、第二份计划"。阶段号是两位补零的。

四个必须理解的字段

计划检查器查什么

它按"维度"编号检查，官方 docs/AGENTS.md 列了这些（节选最影响你日常的几条）：

常用的开关

/gsd-plan-phase 1                    # 研究 + 规划 + 复查一个阶段（最常用）
/gsd-plan-phase 3 --skip-research      # 领域很熟，跳过研究
/gsd-plan-phase 1 --mvp              # 按"垂直切片"来排计划（默认就是这个，见下）
/gsd-plan-phase 1 --tdd              # 让每个加行为的小任务都从"先写一个失败的测试"开始
/gsd-plan-phase 1 --gaps             # 补缺口模式：读验证报告，只规划没做到的部分
/gsd-plan-phase --research-phase 4    # 只做研究，写完 RESEARCH.md 就退出，不进入规划
/gsd-plan-phase --auto               # 跳过所有交互确认

08Execute：一波一波并行地写

你敲下 /gsd-execute-phase 1 之后，编排器会：

官方教程里给的执行输出长这样——注意每一行对应一份计划：

Wave 1 (parallel):
  [Executor A] → 01-01-PLAN.md (read/write helpers)   ✓ committed
  [Executor B] → 01-02-PLAN.md (CLI commands)          ✓ committed

[Verifier] Checking codebase against phase goals...
  CLI-01 todo add   ✓   CLI-03 todo done  ✓
  CLI-02 todo list  ✓   CLI-04 --all flag ✓
  Status: PASS

产物：每个计划一份总结

执行代理干完会写一份 01-01-SUMMARY.md，内容是：做了什么、跟计划有哪些偏离、以及对着验收标准做的自检。这里"偏离"是明写出来的——计划执行中遇到意外而改道是正常的，悄悄改道才不正常。

还有一个细节值得知道：如果计划里带了成本预估，总结里会记下实际花了多少（actuals 字段：token 数、任务数、提交数）。这些实际值会被收集起来做校准，让后续的预估越来越准。

另一个必须知道的机制：人机确认点（checkpoint）。有些任务不是 AI 能自己做完的——需要你登录某个网站、手动去某个后台拿一个密钥、或者做一个只有你能拍板的决定。这类任务会被标成 checkpoint，执行到这里它会停下来等你。官方文档里给了三类确认点的分布比例：要你核对结果的约占 90%，要你做决定的约占 9%，要你亲手去做某个动作的约占 1%。GSD 的输出格式统一成这样：

### CHECKPOINT: Verification Required

Progress: 5/8 tasks complete
Task: Responsive dashboard layout

How to verify:
  1. Visit: http://localhost:3000/dashboard

---

**→ YOUR ACTION: Type "approved" or describe issues**

09Verify：写完了 ≠ 能用了

这一步存在的理由，官方一句话说清了（原文）：

这里其实是两层验证，别搞混

自动那一层不只查"需求有没有覆盖"，还查"你在 Discuss 里定下的决定有没有真被落实"。官方对此的措辞很硬："A phase is not done because execution finished without errors. It is done because what was built is what was planned, and what was planned is what was decided."——阶段完成不是"执行没报错"，而是"建出来的就是规划要的，规划要的就是你定的"。

人工验收是怎么进行的

它读这个阶段所有 SUMMARY.md，把里面用户能看见的交付物变成一条条检查项，一次只给你一条：

### CHECKPOINT: Verification Required

**Test 1: Add a to-do**

Running `node todo.js add "buy milk"` creates a pending item without errors.

---

**Type `pass` or describe what's wrong.**

符合就打 pass；不符合就把差异描述出来。答案记进 01-UAT.md，然后它给下一条。如果有检查失败，它先诊断根因、写一份修复计划，然后你重新跑 /gsd-execute-phase 1 再验一次——而不是让你自己瞎改。

一个值得单独讲的诚实设计

验证代理有一条规则，我觉得是整套系统里最能说明"这作者是真在解决问题"的一处：

10Ship：开出 PR，然后重复

/gsd-ship 1

它会把这一阶段攒下来的东西——需求、决定、验证证据——组装成一个拉取请求（PR，也就是"请把我的分支合进主干"的正式请求），正文是自动生成的，固定五段结构：

官方给的回显示例：

Pull request created: https://github.com/your-org/your-repo/pull/1
Title: Phase 01: core-cli

然后就是重复

多阶段项目就是把这个五步对每个阶段各跑一遍。如果你不确定下一个该干什么：

/gsd-progress --next       # 让它读状态、判断下一步，并直接执行
/gsd-progress              # 只告诉你现在在哪、下一步是什么

整个项目的一个里程碑走完之后，还有两条收尾命令：/gsd-audit-milestone（横向检查需求覆盖、找出没写完只留了个空壳的代码）和 /gsd-complete-milestone（归档、打标签）。

两件按需开启的事，别等到踩了才知道

把规划文件藏起来（但要知道代价）

.planning/ 默认是会进 git 的。如果你想让它不进仓库，官方给了两个键，它们是回答两个不同问题的：

官方把这条讲得很清楚，我直接把它当成一个"必须提前知道"的坑列在这里——"本地保留规划"和"并行执行"在这套设计里是互斥的，这是很多人事后才发现的事。

按阶段类型换模型省点钱

默认档位是 balanced（均衡）。想按环节分别指定模型，在 .planning/config.json 里加一个 models 块：

{
  "model_profile": "balanced",
  "models": {
    "planning": "opus",
    "discuss": "opus",
    "research": "sonnet",
    "execution": "opus",
    "verification": "sonnet",
    "completion": "sonnet"
  }
}

要给某个具体代理开小灶，再加一个 model_overrides，它的优先级高于 models：

{
  "models": { "research": "sonnet" },
  "model_overrides": {
    "gsd-codebase-mapper": "haiku"
  }
}

{
  "enabledMcpjsonServers": ["context7"],
  "disabledMcpjsonServers": ["playwright", "mac-tools"]
}

11最小例子：一遍完整走查（todo CLI）

官方新手教程选的例子是一个命令行工具（CLI）——就是那种在终端里敲一条命令、它打印一行结果的程序。这个待办工具只用 Node 内置库、没有任何外部依赖，目的是让你把注意力全放在流程上，而不是工具链上。下面是它完整的八步，命令都是可以照抄的。

前置检查

node --version      # 官方教程写"要 ≥ 22"；但包的 engines 字段要求 ≥ 24（见第 03 节）
npm --version       # ≥ 10
git --version
gh --version && gh auth status   # gh 是 GitHub 的命令行工具；没登录先跑 gh auth login

# 没有空仓库的话，用 gh 建一个并克隆下来
gh repo create gsd-todo-tutorial --private --clone
cd gsd-todo-tutorial
git remote get-url origin

第 1 步 · 装

npx @opengsd/gsd-core@latest --claude --local
# 装完重启 Claude Code

第 2 步 · 打开你的 AI 工具

claude

第 3 步 · 立项

/gsd-new-project

第一个问题永远是"你想做什么"，粘这段：

A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
No external dependencies — Node built-ins only.

然后回答澄清问题；被问到"每个阶段规划前要不要先研究"时选 No（这个项目小、领域熟，研究只会多花 token 和时间）；工作流设置取推荐默认值；等大约一分钟的路线图；最后打 Approve。

第 4 步 · 清空，然后讨论阶段 1

/clear
/gsd-discuss-phase 1

它会问你怎么实现，比如"已完成的项目是原地标记还是挪走"。答完去看 .planning/phases/01-core-cli/01-CONTEXT.md，找 ## Implementation Decisions——那里应该是你刚才说的话。

第 5 步 · 规划阶段 1

/gsd-plan-phase 1

被问"规划前要不要研究"时选 Skip research。然后规划代理把 01-CONTEXT.md 变成几份小计划，计划检查器逐份复查后存盘：

.planning/phases/01-core-cli/
  01-01-PLAN.md       ← 任务：todos.json 的读写辅助函数
  01-02-PLAN.md       ← 任务：add / list / done 三个命令

打开 01-01-PLAN.md 看 <task> 块：任务名、涉及文件、动作步骤、一条 <verify> 命令、以及"什么算做完"。那条验证命令不是装饰——执行代理写完代码会真的跑它。

第 6 步 · 执行阶段 1

/gsd-execute-phase 1

它把计划分组进波次，每份计划开一个全新的 200k 上下文执行代理，每个任务一次提交。跑完之后——这是你第一次看见真的东西：

node todo.js add "buy milk"
node todo.js add "write tests"
node todo.js list        # → 两条都在
node todo.js done 1
node todo.js list        # → 只剩 "write tests"

第一条勾掉之后从默认列表里消失了——说明第 4 步里你定的那条决定（"默认不显示已完成"）真的被执行了。执行的产出：

.planning/phases/01-core-cli/
  01-01-SUMMARY.md    ← 执行代理 A 建了什么、提交了什么
  01-02-SUMMARY.md    ← 执行代理 B 建了什么、提交了什么
  01-VERIFICATION.md  ← 需求覆盖结果：PASS

第 7 步 · 验证

/gsd-verify-work 1

它会一条一条问你，比如"跑 node todo.js add "buy milk" 是不是能正常加进去"。符合就打 pass；不符合就描述差异，它会诊断、写修复计划，你再回到第 6 步重跑。

第 8 步 · 发出去

/gsd-ship 1

PR 开出来，正文五段齐全。一个阶段从想法到 PR，到此走完。多阶段项目就重复第 4–8 步。

12.planning/ 地图：我该看哪个文件

这是整套系统里最实用的一节。因为一旦你开始用 GSD，项目里会多出一堆文件，而"我到底该打开哪一个"是最高频的问题。

目录长什么样

.planning/
├── PROJECT.md            # 项目身份：这是什么、给谁用、核心价值
├── ROADMAP.md            # 路线图：里程碑 + 阶段 + 每个阶段的目标与成功判据
├── REQUIREMENTS.md       # 需求清单：每条一个编号（AUTH-01 这样）
├── STATE.md              # 状态：项目现在走到哪了（目标：100 行以内）
├── config.json           # 你在这台项目上的工作流配置
├── state.json            # 同一个状态的机器可读版（给外部工具读的合同文件）
├── codebase/             # 代码库地图（老仓库接手时生成）
├── onboarding/
│   └── SUMMARY.md        # 接手记录：下一步该跑什么命令
└── phases/
    └── 01-core-cli/                    # 每个阶段一个目录
        ├── 01-CONTEXT.md               # 你定的实现决定（Discuss 产物）
        ├── 01-DISCUSSION-LOG.md        # 讨论全程记录（给人看的）
        ├── 01-RESEARCH.md              # 研究结论（Plan 产物）
        ├── 01-VALIDATION.md            # 测试覆盖策略
        ├── 01-PATTERNS.md              # 新文件对应的老文件范本
        ├── 01-01-PLAN.md               # 第 1 份计划
        ├── 01-01-SUMMARY.md            # 第 1 份计划的执行记录
        ├── 01-VERIFICATION.md          # 阶段目标的验证报告
        ├── 01-UAT.md                   # 人工验收的问答记录
        └── .continue-here.md           # 暂停后的续做说明

命名规则是死的，认识了就能一眼认出文件属于谁：阶段级是 阶段号-名字.md（三位一体：03-CONTEXT.md）；计划级是 阶段号-计划号-名字.md（03-02-PLAN.md）。号都是两位、补零。

谁写、谁读、你什么时候该看

STATE.md 里面到底长什么样

它是整个系统的"导航层"。官方给的结构示例（节选）：

---
gsd_state_version: '1.0'
milestone: v2.0
status: executing
active_phase: "4.5"
next_action: execute-phase
progress:
  total_phases: 17
  completed_phases: 10
  total_plans: 84
  completed_plans: 47
  percent: 59
---

两个细节值得知道，因为它们解释了"为什么有些规矩看起来莫名其妙"：

• 它被刻意控制在小体量——官方给的目标是不超过 100 行。它是状态的摘要，不是历史档案。
• 它是机器解析的，所以格式敏感。官方明说解析用的是正则而不是完整的 YAML 解析器（YAML 是一种给人写、给机器读的缩进式数据格式，.planning/ 里那些夹在 --- 之间的字段就是它）——因此：--- 必须是文件第一个字符（前面连注释都不能有）；progress: 块里不能插注释，插了进度条就会消失；next_phases 优先写成单行流式数组。

真出了问题也不用怕，有修复命令：

node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state validate      # 检测漂移
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync --verify  # 预览要改什么
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync           # 按磁盘现状重建

13命令速查表

1.13.0 一共随包发布 72 个命令。你不需要记住它们——需要的是知道有哪几类，以及最常用的那十来条。

核心循环（这五条就是全部主干）

/gsd-new-project                  # 立项：全新项目
/gsd-onboard                      # 立项：已有代码的老仓库
/gsd-discuss-phase 1              # ① 讨论怎么做
/gsd-plan-phase 1                 # ② 研究 + 规划 + 复查
/gsd-execute-phase 1              # ③ 分波并行执行
/gsd-verify-work 1                # ④ 人工验收
/gsd-ship 1                       # ⑤ 开 PR

按场景查

另一个省 token 的入口：命名空间

命令多了之后有个副作用：技能清单本身也占 token，而且每一轮都要重新发一遍。1.13.0 里加了 6 个"命名空间路由"命令来缓解这件事——官方给的数字是：6 个路由大约 120 token，而把 86 个技能平铺列出来大约 2,150 token。

/gsd-workflow     # 阶段流水线：discuss / plan / execute / verify / phase / progress / next
/gsd-project      # 项目生命周期：里程碑、审计、总结
/gsd-quality      # 质量闸门：评审、调试、审计、安全、评估、界面
/gsd-context      # 代码库情报：地图、图谱、文档、经验
/gsd-manage       # 管理：配置、工作区、线程、更新、发布
/gsd-ideate       # 探索与记录：探索、草图、探针、规格、速记

官方明说这几个路由是附加的：每一条具体命令都仍然可以直接敲，不会因为加了路由就失效。

档位预设：速度 vs 质量

如果你不想一个个调，官方给了一张三档预设表，直接照场景选：

14常见坑与排错

八类常见故障的分诊表

三件我核对过、但文档没说清的"版本陷阱"

两处"某个机制说自己会保护你、但做得没那么全"的地方

这两条与使用无关，但与你能不能相信它的告警有关，所以我单独摆出来。

另外三处我数出来的小出入（都不影响使用，但说明文档别全信）

• 官方教程说装了 71 个命令，实际包体里是 72 个。（方法：下载 npm 上的 gsd-core-1.13.0.tgz，数 package/commands/gsd/*.md）多出来的那个是 /gsd-inbox——它随包发布，但在官方那份 2,400 行的命令参考里根本没有条目，只在清单文件里出现。顺带一提，命令参考里恰好有 71 条 /gsd- 标题，所以"71"很可能就是照着参考文档数出来的。
• 官方库存清单说"35 个代理每个都有一份 .compact.md 精简版"，实际只有 29 份。缺的正好是 6 个核心代理：planner、executor、verifier、plan-checker、phase-researcher、debugger。缺它们很可能是故意的（干活的主力不能被精简掉），但文档那句话写的是"每个都有"。（方法：ls agents/gsd-*.md 与 ls agents/gsd-*.compact.md 各数一遍）
• 代理总数在同一份文档里从 33 一路变到 35。docs/AGENTS.md 开头写"22 主力 + 12 专项 = 34 个"，同一份文件往下 12 行写"Thirteen additional……权威名单是 35 个"，更下面又写回"Twelve additional agents"；docs/CONFIGURATION.md 与 configure-model-profiles.md 里则写着"全部 33 个随包代理"。按文件数是 35。

15什么时候别用它（含它自己承认的安全边界）

官方自己给的"别用"判据

这部分特别值得读，因为它是作者自己写下来的，不是外人挑刺：

文档还点名了三种明确不该用的情形：改变量名、修错别字、补一个漏掉的 import——这些用 /gsd-quick，或者干脆别用 GSD。/gsd-quick-batch 里也写了类似的话：这个命令不支持 --discuss 和 --full，会直接报用法错误。

代价是真实的，官方没藏

它自己的总结是这样的（原文）："The overhead is real, but it is front-loaded — paid in minutes of planning rather than hours of rework."——开销是真的，但它是前置的：用几分钟的规划，换掉几小时的重做。

安全边界：它公开承认了什么做不到

这一节是我最想让读者看到的部分。GSD 有一份写得很扎实的安全模型，而且它明确列出了自己防不住什么——这在工具文档里很少见。

它做了哪几层防护

它明说自己防不住什么

node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" config-set security.injection_blocking true

还有一件事要自己判断：--dangerously-skip-permissions

官方教程为了减少练习时的打断，用了这个跳过所有文件读写确认的参数，并且配了一段警告。这段话值得原样理解一遍（原文）：

翻译过来：子代理会大量读写文件，跳过确认意味着你对这些读写不再有逐次的否决机会。在空目录里做练习可以，在你放着真实代码和密钥的仓库里，先读安全模型，再决定。

三处"宣传语比行为文档更响"的地方

我不想只挑好话说。下面这三条都能在仓库里同时找到两边原话，你可以自己核。

公平地说：第 ② 条的两句话并不真的矛盾——GSD 确实大幅降低了上下文腐烂的发生率，而"无法验证语义正确性"说的是另一件事（它没法保证 AI 写的东西逻辑对不对）。但把这两句话放在一起看，你就能明白它替你挡掉的是"流程性错误"，不是"判断性错误"。这恰好是本文反复强调"Verify 那一步你得亲自在场"的原因。

另外，维护者对这个项目主动划了边界：仓库里有一个 .out-of-scope/ 目录，17 个文件，每份都是一个写明理由的"这个我们不做"记录。其中一条值得引：

如果要用自动模式，先看官方列的四条"别用"

/gsd-autonomous 能一路把剩下的阶段跑完（它会连着把 讨论 → 规划 → 执行 做掉，最后还会自动走里程碑的审计与归档）。但官方明确列了四种不该用它的情形，我原样翻译过来：

1. 这个阶段的设计决定还没定下来——自动模式下的讨论会替你做出选择，"你可能并不同意"。
2. 你需要对这个阶段做精细控制。
3. 这个阶段有新颖或高风险的工作——那就留在环路里，手动执行。
4. 你正处在一个阶段的中途、只执行了一半——它不会接着跑一个执行了一半的波次。

官方还补了一句关键的：自动模式与手动执行唯一的区别是"验证通过之后会自动往前推进"——各道安全闸门照常触发，需要决定的地方照样停下来问你。所以它不是"无人驾驶"，是"你不用手动敲下一步"。

什么人适合用，什么人不适合

16术语对照表

这些词在正文里都解释过，这里做成一张能回头查的表。第三列是它在 GSD 里为什么重要 / 别拿它当什么用——不是简单翻译。

17参考来源与证据边界

本文关于 GSD 的所有陈述，来自下面这些一手材料。抓取与核对日期：2026-09-13。我按"读到什么程度"分层列出，并说明每份材料在本文里承担哪一部分。

A. 逐字读了原文的官方文档（本文主要依据）

• README.md（128 行）——第 01 节的定位原话、"五步循环"的官方表述、支持的运行时、Why it works。
• docs/explanation/the-phase-loop.md（129 行）——第 05–10 节的骨架：五步各自"为什么存在"、里程碑与阶段的区别、什么样的阶段范围算好、"猜得有理却是错的"那段原话。
• docs/explanation/context-engineering.md（133 行）——第 02 节整节的依据：上下文腐烂的定义与四种症状、为什么"重述无用"、编排器与子代理的分工、开销/延迟/仪式感三条代价、"能一条短提示说完就别用它"的判据原话。
• docs/tutorials/your-first-project.md（570 行）——第 11 节整节：八步走查、每步的真实输出、"71 commands" 那一行、耗时表、Node 22+ 徽章、五个排错条目。
• docs/COMMANDS.md（2,405 行，读了核心流程段与速查相关段）——第 06–10、13 节的命令语法、参数表、耗时之外的所有开关；命名空间路由的 120 vs 2,150 token 数字；三档预设的来源之一。
• docs/USER-GUIDE.md（1,140 行）——完整生命周期命令串（第 10 节）、三种输出的读法、STATE.md 不同步的处理命令、按阶段类型换模型的 JSON 样例、省钱的顺序、MCP 那段。
• docs/reference/planning-artifacts.md（296 行）——第 12 节的目录树与"谁写谁读"表：每个文件的用途、生产者、消费者，命名规则。
• docs/reference/state-md.md（257 行）——第 12 节的 STATE.md 结构示例、100 行目标、正则解析的三条格式约束、## Current Position 覆盖语义与"加粗行会静默胜出"的警告。
• docs/reference/plan-md.md（读了开头 120 行）——第 07 节的 PLAN.md frontmatter 示例、字段含义、编号规则、must_haves 与成本预估。
• docs/how-to/install-on-your-runtime.md（599 行，读了安装与 Claude Code 段）——第 03 节的安装命令、Node 18+ 的说法、hook 事件表、全局/本地作用域冲突的解释。
• docs/CONFIGURATION.md（2,377 行，读了规划/私有化相关段）——第 10 节 commit_docs 与 pr_strict 的取舍原表。
• docs/explanation/security-model.md（读了 Trade-offs and limits 一段）——第 15 节安全边界的四个缺口全部出自这里。
• docs/AGENTS.md + docs/INVENTORY.md——35 个代理的名册与分工；同时是"34 vs 35"不一致的证据来源。
• VERSIONING.md、CHANGELOG.md（读了版本标题清单与最新一版）——next 标签的定义、版本历史（21 个版本，最高 1.13.0）。

B. 我自己算出来 / 数出来的（这些是本文独有的部分）

• 命令数 72、代理数 35、技能目录 72、工作流 89、hook 脚本 31——直接在克隆下来的仓库与下载的 npm 包体里数文件（ls + wc -l）。官方教程的 71 与本文的 72 不同，是这个差异本身成了文中的一条发现。
• npm 时间线——直接查 registry.npmjs.org/@opengsd/gsd-core：38 个版本、首次发布 2026-05-30、最新 1.13.0（2026-09-06）、dist-tags 为 {latest: 1.13.0, next: 1.7.0-rc.6}。53 天 7 个次版本是我按日期差算的。
• 包体核对——下载 gsd-core-1.13.0.tgz（4.55 MB）实测：commands/gsd/ 下 72 个 .md；package.json 的 engines 是 {node: ">=24.0.0", npm: ">=10.0.0"}；被标为 "v1.42.1" 的包合法性闸门文件 gsd-core/bin/lib/package-legitimacy.cjs 确实在包里。这一步是为了区分"文档在描述未发布的功能"和"文档的版本标记不对"——结论是后者。
• GitHub 仓库元数据（api.github.com/repos/open-gsd/gsd-core，2026-09-13 查询）：9,386 stars、674 forks、125 open issues、创建于 2026-05-22、最后推送 2026-09-12、MIT 许可。npm 下载量来自 api.npmjs.org/downloads/point/…：上月 41,591、上周 9,526。
• 克隆仓库的定位：git clone --depth 1 得到 commit a0270a79452f94360d7c4acda81038d51a4df7a1（2026-09-12，一个合并提交），共 3,568 个受版本控制的文件；.changeset/ 下有 85 个未发布条目。这三个数（commit、日期、85）共同支撑了第 14 节"main ≠ 你装到的版本"那条判断。
• "29 份 .compact.md"——ls agents/gsd-*.compact.md | wc -l 得 29，并逐个比对找出缺的 6 个是哪些代理。
• 版本号撞车的根因——在 docs/RELEASE-NOTES-LEGACY.md 里找到：项目原名 get-shit-done-cc，版本发到 1.42.3（canary 到 1.50.0-canary.1），改名后版本号从 1.0.0 重新开始，归档文件自己写着"旧的 1.x 数字会与当前撞车"。这条解释了本文第 14 节整段。
• 上下文告警阈值的三方不一致——35%/25%（运行时监控 hook）、60%/70%（/gsd-health --context）、50–70%/70%+（执行阶段的上下文闸），三处各自的出处不同，换算后前两者差 5 个百分点。
• 发版记录里的复制粘贴——按版本正文逐条比对得出：1.8.0 的 175 条里 173 条与 1.7.0 逐字相同（98.9%）；1.5.0 整段包含 1.4.1 的全部条目；同一修复同时挂在两个版本下。以及 .changeset/ 里 84 条待发布记录（73% 是缺陷修复）。
• 守卫超时修复的落点不一致——更新日志说六个阻断型守卫的超时从 5 秒提到 120 秒，代码里确有 BLOCKING_GUARD_TIMEOUT_S = 120，但同版本的 hooks/hooks.json 插件清单里仍然是 "timeout": 5。

C. 由四个并行研究任务逐行核对、并附了行号引用的文档

出于效率考虑，几份超长参考文档（COMMANDS.md 2,405 行、CONFIGURATION.md 2,377 行等）我拆成四份逐行核对的阅读任务并行处理，要求每条结论都带 文件:行号。上面 B 组里的多数交叉核对、以及第 13–15 节里带具体数字的陈述，都来自这批带行号的报告；其中的关键矛盾（Node 三个版本、命令 71 vs 72、代理 33/34/35、版本世系）我另外用独立的命令亲自复核过一遍（数文件、下载 npm 包、查 registry / GitHub API）。

D. 我明确没有读、因此本文不引用其内容的材料

docs/FEATURES.md（4,408 行）、docs/ARCHITECTURE.md（1,044 行）、docs/CLI-TOOLS.md、docs/INVENTORY.md 的完整 797 行、docs/adr/ 下 50 多份架构决策记录、src/ 下 235 个源码文件（只在核对规划目录解析、安装器版本检查、守卫超时常量时读了片段）、tests/ 下约 956 个测试文件、docs/prd/ 与 docs/adr/ 的大部分内容，以及 docs/zh-CN/、ja-JP/、ko-KR/、pt-BR/ 四套翻译文档。

这一点值得明说：我没有逐行读源码去验证文档描述的每一条行为是否属实。本文的定位是"文档说该怎么用"，不是"代码实际怎么跑"。凡涉及"它内部如何实现"，本文一律以官方文档的表述为准并标明出处；凡是与代码/包体对得上的（版本、计数、默认值、开关名），我才标成"我数过/我核过"。

99一句话总结

最后留一个只有你能回答的问题，它是检验这篇有没有讲透的唯一标准：想一件你最近用 AI 干过的活，然后判断——它该走五步循环，还是该用 /gsd-quick，还是压根不该用 GSD？如果你能说出理由（而不是感觉），这篇就到位了。