目录 [−]

"Claude Code is powerful. GSD Core makes it reliable."
Claude Code 很强大。GSD Core 让它变得可靠。

——open-gsd/gsd-core README

第 12 章给了 Loop Engineering 一个很大的愿景：你不再提示 Agent，而是设计提示 Agent 的循环。但那一章停在原理层，讲的是五个原语加一个状态记忆。把这些原语落成一套能直接安装、有明确文件结构、带 67 个命令的工程系统，是另一回事。

GSD Core 就是这样一套系统。它不发明新的 Agent，也不取代 Claude Code，而是套在你已有的运行时上面，把讨论、规划、执行、验证、交付这五步，固化成每个里程碑都要重复一遍的流水线。它想回答的不是"Agent 能不能写代码"，这个早就不是问题了，而是一个更隐蔽的问题：为什么 Agent 在小任务上表现惊艳，一接手大项目就开始胡言乱语？

这个问题有名字，叫上下文腐化（Context Rot）。本章讲 GSD Core 怎么把对抗上下文腐化当成第一性原则，用阶段循环、子智能体、持久化工件这三样东西，把一个容易漂移的编码 Agent 变成靠得住的工程伙伴。

13.1 GSD 是什么：Git. Ship. Done.

GSD 是三个词的首字母，Git. Ship. Done.（提交、交付、完成）。项目全称 open-gsd/gsd-core，由 open-gsd 组织维护，以 npm 包 @opengsd/gsd-core 的形式发布，MIT 协议开源。

它给自己的定位是一句话：一套轻量级的元提示（meta-prompting）、上下文工程与规格驱动开发系统。这三个定语各有所指。meta-prompting 是说它不直接干活，而是组织 Agent 怎么干活；context engineering 是说它的核心目标是管理上下文；spec-driven 是说它继承了第 3 章的规格驱动思想。

GSD Core 最要紧的特征是跨运行时。它不绑定任何一个 Agent 产品，安装时会问你跑在哪个运行时上，再把命令和 Agent 定义适配过去。官方支持的运行时有 Claude Code、OpenCode、Gemini CLI、Kimi CLI、Kilo、Codex、Copilot、Cursor、Windsurf。安装就一行命令：

1

npx @opengsd/gsd-core@latest

安装器会问你选哪个运行时、装到全局还是本地，并处理命名空间转换：有的运行时用连字符 gsd-plan-phase，有的用冒号 gsd:plan-phase。官方明确不建议你直接从 agents/ 或 commands/ 目录手动拷文件，让安装器做转换才能保证跨运行时一致。

整个系统由 67 个斜杠命令驱动。这个数字写在 docs/INVENTORY.md 里，还有一个测试 command-count-sync.test.cjs 盯着它和实际命令数对得上。换句话说，这不是一个 prompt 模板，是一个有版本、有测试、有文档的工作流引擎。

这里要澄清一个小差异。项目站点 opengsd.net 的首屏把循环的第一步写成 Research，GitHub README 写的是 Discuss。两者指同一件事，动手之前先把事情想清楚。本章统一用 README 的五步说法：Discuss → Plan → Execute → Verify → Ship。

13.2 核心问题：上下文腐化

要理解 GSD Core 为什么长成这样，得先看清它在跟什么作斗争。

上下文腐化指的是：上下文窗口越填越满，AI 的输出质量也跟着往下走。一个 Agent 在对话开头思路清晰、引用准确；聊到第五十轮，它开始忘记早先的决定、混淆文件、把已经否决的方案又提一遍。窗口没满，但信噪比塌了。

GSD 的文档把多数 AI 编程方案在规模上的失败，归到三件事头上：

• 上下文膨胀悄悄拉低质量。研究、规划、执行的细节全堆在同一个会话里，越堆越多，模型越来越难分辨什么重要。
• 会话之间没有共享记忆。今天的会话结束，明天重开一个，昨天的决定、试过的弯路、定下的约定，全没了。Agent 每次都从零开始。
• 没有机制验证代码真的能跑。Agent 说"做完了"，可"做完了"是声称，不是证明。这正是第 12 章反复敲的那一点。

针对这三个病根，GSD 立了三根支柱：

这三根支柱，分别对应后面三节要讲的三样东西：阶段循环、子智能体、持久化工件。

13.3 五步阶段循环：Discuss → Plan → Execute → Verify → Ship

GSD 把工作组织成里程碑（milestone），每个里程碑内部分成若干阶段（phase），每个阶段都走同一套五步循环。这里有一条铁律：每次只推进一个阶段。不许一边规划一边执行，也不许跳过验证直接交付。

1
2
3
4
5
6

里程碑 Milestone
  └── 阶段 Phase 01
        Discuss → Plan → Execute → Verify → Ship
  └── 阶段 Phase 02
        Discuss → Plan → Execute → Verify → Ship
  └── ...

这五步各有专属命令，下面逐一拆解。

13.3.1 Discuss——动手规划前先把实现决策定下来

命令：/gsd-discuss-phase <编号>。

这一步不是写正式规格，而是一次轻量对话，目的是在规划开始前把实现决策定下来，免得规划者带着错误假设往下走。

它有个模式值得一提，叫假设模式（Assumptions mode）。传统的"讨论"是面试式提问，一条条问你想怎么做。假设模式反过来：Agent 先读代码库，基于证据自己形成观点，只在真正拿不准的地方请你纠正。它扮演的是思考伙伴，不是问卷。背后是一个朴素的判断：大部分实现决策，代码本身已经给了答案，没必要再问人。

产出两个工件：CONTEXT.md，结构化的决策记录；<NN>-DISCUSSION-LOG.md，人能读的审计轨迹。

13.3.2 Plan——研究、分解，并验证计划装得进一个全新上下文窗口

命令：/gsd-plan-phase <编号>，可带 --research、--skip-research、--tdd、--mvp 等标志。

这一步是 GSD 子智能体编排最密集的地方。编排者（orchestrator）依次派出三个子智能体：研究员（researcher）拿到一个干净的 200k token 窗口，专做技术研究，产出 RESEARCH.md；规划者（planner）拿到研究输出和需求做任务分解，产出一个或多个 PLAN.md；计划检查者（plan-checker）审查计划，趁执行前把歧义抓出来。

这里有条核心约束：每个计划必须能装进一个全新的上下文窗口。这不是建议，是设计原则。如果一个计划大到一个执行器的 200k 窗口都装不下它需要的全部上下文，那它就是太大了，必须拆。这条约束直接决定了任务分解的粒度。

产出工件：RESEARCH.md、若干 PLAN.md、VALIDATION.md（受奈奎斯特采样思想启发的验证策略），可选的 PATTERNS.md（代码库类比映射，告诉执行器"项目里类似的东西是怎么写的"）。

13.3.3 Execute——以并行波次运行，每个执行器从干净上下文起步

命令：/gsd-execute-phase <编号>，可带 --wave N、--gaps-only、--tdd。

执行阶段把计划分成波次（wave）：彼此独立的计划在同一波里并行跑，有依赖关系的排到后面的波。每个计划对应一个执行器（executor）子智能体，每个执行器都从一个干净的 200k token 上下文起步，它只拿到自己这个计划需要的工件，不被别的计划的细节污染。

这就是"并行波次"的意思：不是无脑并发，而是按依赖图分层并发。PLAN.md 的 YAML frontmatter 里就写着 wave、dependencies、modified_files、requirements、must_haves 这些字段，编排者据此排波。

产出：代码、原子化的 git 提交，以及每个计划的 <NN>-<PP>-SUMMARY.md 执行记录。

13.3.4 Verify——宣告完成前先诊断并生成修复计划

命令：/gsd-verify-work [N]。

一个验证者（verifier）子智能体检查实际构建出来的东西，看它对不对得上最初的目标、决策和计划。它做两道覆盖度检查，需求覆盖和决策覆盖：你在 Discuss 阶段定下的每条决策，都被执行了吗？

发现问题，它不止报告，还会派调试子智能体去诊断根因，并生成修复计划。这是 GSD 验证步骤最有牙齿的地方：验证的产出不是一句"还有 bug"，而是一份能直接执行的修复方案。产出工件：VERIFICATION.md（验证报告）、UAT.md（用户验收测试结果）。

13.3.5 Ship——创建 PR、归档阶段、推进下一阶段

命令：/gsd-ship，可带 --draft 创建草稿 PR。

最后一步：创建拉取请求、归档本阶段的所有工件、更新 STATE.md 把这个阶段标记为完成，然后对下一个阶段重复整套流程。

把五步连起来看，它和第 5 章 gstack 的 Sprint（Think → Plan → Build → Review → Test → Ship）、第 8 章 Goal Workflow 的 /prd → /goal → /review-it → /ship-it 是同一个谱系。GSD 的独特之处不在循环的形状，在它对每一步上下文的洁癖，这是下一节的事。

13.4 子智能体如何保持上下文整洁

GSD 把对抗上下文腐化的关键机制叫瘦编排者（Thin Orchestrator）模式。

主会话，也就是你直接对话的那个编排者，刻意保持精简。它只做四件事：加载上下文、派生专门的子智能体、收集结果、更新共享状态。它不自己做繁重研究，不自己写大段代码，不让执行细节堆进自己的窗口。

所有重活下放给子智能体，而每个子智能体都拿到一个干净的、最多 200k token 的上下文窗口，外加它这份活儿要用的工件，仅此而已。研究员只看研究要用的东西，执行器只看自己那个计划。任务和任务之间物理隔离，一个 Agent 的上下文不可能污染另一个。

这套设计的三条原则，GSD 文档总结得很干净。第一条，每个 Agent 一份新上下文（Fresh Context Per Agent），用来消除上下文腐化。第二条，瘦编排者（Thin Orchestrators），让主会话不囤积细节。第三条，文件化状态（File-Based State），让状态落盘，可持久、可检视。

回头看第 12 章会发现，这正是 12.3.5 讲的 maker-checker 分离的工业级落地：写代码的执行器和验证工作的验证者不是同一个上下文，甚至可以不是同一个模型。第 12 章把这个分离称作循环里最有用的结构性设计，GSD 把它从一个有用的设计，变成了贯穿整个工作流的强制纪律。

支撑这套编排的，是一个叫 gsd-tools.cjs 的 CLI 工具。它是 GSD 工作流操作的功能后端，把配置解析、模型解析、阶段查找、git 提交、摘要验证、状态管理、模板操作这些重复逻辑集中起来，替掉了散落在各个命令文件里的内联 bash。工作流文件（workflows/*.md）的典型套路是：用 gsd-tools.cjs init <workflow> 加载上下文，解析该用哪个模型，派生 agents/*.md 里定义的专门 Agent，收集结果，再用 gsd-tools.cjs state update 更新状态。

模型这件事 GSD 也做了精细化。它提供模型档位（model profiles），即 quality、balanced、budget、adaptive、inherit 五种预设策略，给不同的 Agent 分配不同的 Claude 模型。比如 quality 档给 gsd-planner 用 opus，budget 档给同一个 planner 用 sonnet。你还能按阶段类型（planning / research / execution）配模型，或者对单个 Agent 做覆盖。解析优先级是：单 Agent 覆盖大于阶段类型，阶段类型大于全局档位，全局档位大于运行时默认。这让"贵模型做规划、便宜模型做执行"这种成本意识的分工，变成一行配置，和第 14 章 improve 的思路殊途同归。

13.5 持久化工件：STATE.md 与 CONTEXT.md

第 12 章 12.3.6 那句话在这里落了地：Agent 会忘记，仓库不会。GSD 用一整套落盘的结构化工件，补上"会话间无共享记忆"这个病根。

所有工件都活在项目根目录的 .planning/ 文件夹里，它是项目状态的唯一真相来源。目录结构大致是这样：

1
2
3
4
5
6
7
8
9
10
11
12
13
14

.planning/
├── STATE.md                      # 项目的活档案 / 导航层
├── codebase/                     # 代码库地图（onboarding 时生成）
│   ├── STACK.md
│   ├── ARCHITECTURE.md
│   └── CONVENTIONS.md
├── phases/
│   └── <NN>-<slug>/              # 每个阶段一个目录
│       ├── CONTEXT.md            # Discuss 阶段的决策记录
│       ├── RESEARCH.md           # Plan 阶段的研究
│       ├── <NN>-<PP>-PLAN.md     # 可执行的工作单元
│       ├── VERIFICATION.md       # Verify 阶段的报告
│       └── ...
└── quick/                        # /gsd-quick 的临时任务

两个核心工件值得细看。

先是 STATE.md，项目的活档案、中央导航层。它记录当前里程碑、活跃阶段、已完成和待办的计划、进度指标、累积的决策，还有会话连续性笔记。所有工作流启动时先读 STATE.md，做完重要动作后写回。它就是第 12 章说的那根脊柱：明天早上的运行从今天停下的地方接着走，不是从零开始。gsd-tools.cjs 甚至提供 state get <section> 让你按小节查它。

再是 CONTEXT.md，Discuss 阶段捕获的实现决策。它包含阶段边界、带 D-NN 编号的锁定决策、规范文档引用、已有代码洞见、具体的灵感来源、推迟的想法。它被研究员、规划者、执行器共同消费，这意味着你在讨论阶段定的每条决策，会一路流到执行器手里，而且因为带着 D-NN 编号，验证阶段能逐条核对"决策覆盖"。

此外还有 PLAN.md（带 YAML frontmatter 的可执行工作单元）、RESEARCH.md、VALIDATION.md 等等，每种都有明确的 schema。这套工件体系的意义在于：知识不再活在某次对话的上下文窗口里，而是活在文件系统里，谁都能读，下次运行接着来。这就是"文件化状态"原则的全部价值。

13.6 上手与既有代码库的接入

全新项目用 /gsd-new-project 启动。但更现实的场景，是把 GSD 接到一个已经存在的代码库（brownfield）上，这条路径值得单独说。

第一步，让 GSD 读懂你的代码。命令 /gsd-map-codebase 会派出四个并行的 mapper 子智能体（技术栈 mapper、架构 mapper 等），分析代码库，在 .planning/codebase/ 下产出 STACK.md、ARCHITECTURE.md、CONVENTIONS.md 等结构化地图。

第二步，/gsd-new-project 聚焦于"你要加什么"，而不是重新发明已有的东西，它会从现有代码里抽取并验证需求。

第三步，进入正常的 Discuss → Plan 循环。此时代码库地图会喂给 /gsd-discuss-phase 和 /gsd-plan-phase，确保计划顺着既有的约定和结构走，而不是另起炉灶。

除了完整的五步循环，GSD 还留了轻量入口。/gsd-quick 用于小而临时的任务：它保留 GSD 的保证（原子提交、STATE.md 追踪），但默认跳过研究、讨论、计划检查、验证这些可选环节，只派 gsd-planner（quick 模式）和 gsd-executor。需要时可以用标志逐级把质量管线加回来，--discuss 加轻量讨论，--validate 加计划检查和验证，--full 开完整管线，--research 加聚焦研究。quick 任务存在 .planning/quick/，并更新 STATE.md 里的 "Quick Tasks Completed" 表。

这种"完整循环加快速通道"的双轨设计，对应的是真实开发里"大功能走流程、小修补抄近道"的常态。但就算抄近道，原子提交和状态追踪也不丢。

13.7 产品矩阵：从框架到独立 Harness

GSD 不止 gsd-core 一个产品。看清整个矩阵，才能看清它在第 10 章 Harness Engineering 谱系里的位置。

gsd-core 是本章主角，套在现有运行时上的工作流引擎。它本身不是 Harness，是给别人的 Harness 加一层可靠性。

gsd-pi 是一个 terminal-native 的独立自主 Agent，带 TUI 和 Web UI、worktree 隔离的 git、多模型路由，安装 npm install -g @opengsd/gsd-pi@latest。这才是一个完整的、独立的 Harness，对应第 10 章。

gsd-browser 是基于 CDP（Chrome DevTools Protocol）的浏览器自动化，提供 MCP server 模式和带版本的元素引用，标准动作流是 navigate → snapshot → act → assert → export，支持人工接管（human takeover），安装 npm install -g @opengsd/gsd-browser@latest。它给 GSD 的验证步骤提供了"行为级证据"：不是猜代码对不对，而是真的在浏览器里跑一遍、断言、留痕。

此外还有两个规划中的产品。gsd-workbench 是桌面端的本地工作区，管计划、backlog、证据、交付交接；gsd-cloud 是托管服务，提供跨设备的项目状态和团队可见性。

这个矩阵透露了 GSD 的野心：gsd-core 让任何运行时变可靠，gsd-pi 提供一个自带可靠性的运行时，gsd-browser 给验证装上眼睛，workbench 和 cloud 把单机循环扩展到团队。

13.8 与全书方法论的对接

GSD Core 几乎是前几章方法论的一次集大成，把分散的原则拧成了一套能直接安装的工程系统。

跟第 3 章 SDD 的关系最直接：GSD 本质就是规格驱动，但它把规格嵌进了阶段循环。CONTEXT.md 是讨论阶段的规格，PLAN.md 是执行阶段的规格，验证阶段逐条核对规格覆盖。规格不再是开头写一次的文档，而是贯穿循环的活合约。

跟第 5 章 gstack 同为"想、划、做、审、交"谱系，但 GSD 更偏执于上下文隔离。gstack 用角色覆盖来保证质量，GSD 用"每个 Agent 一份新上下文"来保证质量。跟第 8 章 Goal Workflow 高度同构，/prd → /goal → /review-it → /ship-it 几乎可以和 Discuss → Plan → Execute → Verify → Ship 对位，GSD 可以看作 Goal Workflow 加了一套强制的文件化状态和子智能体编排。

跟第 10 章 Harness Engineering，gsd-pi 是一个完整的独立 Harness，gsd-core 则是"给别人的 Harness 加可靠性层"的另一种工程实践。

最深的一层是跟第 12 章 Loop Engineering 的对接。GSD 是 12.3 那"五个原语加状态记忆"的一次工业级落地：子智能体加持久化工件加独立验证门禁，再配上 worktree 隔离和模型路由。第 12 章讲的是循环的原理，GSD 给了你一个能直接 npx 装上的循环。

最后是跟第 14 章 improve、第 15 章 Compound Engineering 的关系，三者都信"规划重于执行"。improve 把成本分工压到极致，强模型审计、弱模型执行；Compound Engineering 在末端加了知识复利；GSD 则把重心放在跨会话的上下文工程和验证证据上。

13.9 本章小结

GSD Core 把一个容易被忽视的工程真相摆到了中心：AI 编程在规模上的失败，大多不是模型不够聪明，而是上下文管理不善。它给这个真相起了名字，叫上下文腐化，再用三样东西系统性地反击它。

第一样是阶段循环（Discuss → Plan → Execute → Verify → Ship），每次只推进一个阶段，把工作切成上下文窗口装得下的块。第二样是子智能体加瘦编排者，每个 Agent 一份干净的 200k 上下文，主会话不囤积细节，maker 和 checker 物理隔离。第三样是持久化工件（STATE.md、CONTEXT.md、PLAN.md 等），把状态落盘到 .planning/，让知识跨越会话边界存续。

它最聪明的定位是：不取代你的 Agent，而是让你的 Agent 变可靠。同一个 Claude Code，套上 GSD Core，就从一个聊到第五十轮开始漂移的对话伙伴，变成一个有计划、可恢复、有验证证据的工程流水线。这也正是它那句标语的全部意思：Claude Code 很强大，GSD Core 让它变得可靠。