整合 open-gsd/gsd-core 官方全部中文文档（教程、概念说明、操作指南）和 71 个 Skill 的完整分析。

目录

Part 1：入门 —— 两条路径

1.1 什么是 GSD

GSD = Git. Ship. Done.

GSD Core 是一套轻量级的 AI 编程 Agent 框架。核心理念：上下文工程 + 规格驱动开发。

它解决三个根本问题

问题 现象 GSD 的解决方案
上下文腐化 会话越长，AI 输出质量越静默下降 重度工作在新鲜上下文子 Agent 中运行，主会话保持精简
无共享记忆 每次 /clear 后从零开始，丢失之前决策 用结构化文件（STATE.md、CONTEXT.md）跨会话持久化
未验证输出 代码跑了但没人确认对不对 强制验证步骤，验证通过后才能发布

核心设计：阶段循环

1
讨论 → 规划 → 执行 → 验证 → 发布

每个阶段产出结构化文件，供下游 Agent 消费。每个步骤都为了防止上一步无法捕获的特定失败模式：

  • 讨论防止规划基于错误假设
  • 规划防止在根本性设计缺陷上执行
  • 验证防止发布偏离需求的代码

“一个阶段完成不是因为没有报错，而是因为构建的内容符合计划，计划的内容符合决策。”

路径 A：从零开始（绿地项目）

安装

1
npx @opengsd/gsd-core@latest

选择 Claude Code + 本地安装（将技能版本固定到该项目）。

启动

1
claude --dangerously-skip-permissions

⚠️ 仅在信任的项目目录中使用。

第 1 步：创建项目

1
/gsd-new-project

完整交互流程：

① 描述你想构建什么。越详细越好：

“构建一个 Node.js CLI 待办事项工具。三条命令：add 添加、list 列出（–all 查看全部）、done 标记完成。数据存本地 JSON。仅用标准库。”

② 回答澄清问题。GSD 追问以缩小范围。

③ 调研（小项目可跳过）。对于已有明确方案的项目，选”跳过调研”。

④ 工作流设置。选推荐默认值（写入 .planning/config.json）。

⑤ 路线图子 Agent 运行。展示提案后输入 Approve。

产出文件：

1
2
3
4
5
6
.planning/
├── PROJECT.md          # 项目上下文
├── REQUIREMENTS.md     # 范围需求
├── ROADMAP.md          # 阶段结构与依赖
├── STATE.md            # 项目当前位置与状态
└── config.json         # 工作流配置

第 2-6 步：阶段循环

对每个阶段重复此流程。每个阶段前 /clear 保持上下文清新。

讨论（Discuss）
1
/gsd-discuss-phase 1

在规划前捕获实现决策——用什么库、错误怎么处理、架构方式、边界情况。不是描述”构建什么”（那是需求的事），而是”如何构建”。

产出：{phase}-CONTEXT.md，含 ## Implementation Decisions。规划器和执行器都会读取。

规划（Plan）
1
/gsd-plan-phase 1

内部流程：

  1. 研究者子 Agent 调研生态（产出 RESEARCH.md）
  2. 规划器子 Agent 读取 CONTEXT.md + 调研结果，生成原子任务计划
  3. 计划检查器验证完整性、一致性和范围

产出 PLAN.md 文件，每个计划是有限的工作单元——含文件修改、具体变更和完成标准。计划按依赖排序为 wave，同 wave 内的执行器可以安全并行。

“规划步骤是歧义代价最高的时刻”——这里的歧义会在下游产生假设，多个执行器对同一关注点做不同假设则产生冲突。

执行（Execute）
1
/gsd-execute-phase 1

每个执行器获得一个全新的 200K-token 上下文窗口，只加载它需要的：项目摘要、阶段上下文、调研结果、它的 PLAN.md。不多不少。

执行器原子提交——每个完成的任务一个提交。一个 wave 完成后，协调器合并状态并推进到下一 wave。

新鲜上下文不是锦上添花。一个装载了 180K 累积会话历史的执行器性能会下降。干净的开始意味着完整的能力。

验证（Verify）
1
/gsd-verify-work 1

验证器 Agent 读取阶段目标、CONTEXT.md 决策、计划和执行摘要，检查构建内容是否匹配预期。产出 VERIFICATION.md。如有偏差，生成定向修复计划。

验证不仅检查测试通过，还检查：

  • 需求覆盖：所有 REQ-ID 是否被解决？
  • 决策覆盖：CONTEXT.md 中记录的决策是否被实现？
  • 阶段目标对齐：整体上是否交付了应该交付的？
1
/gsd-validate-phase 1

补充：Nyquist 验证——回顾性审计验证缺口，自动生成测试。

发布（Ship）
1
/gsd-ship 1

自动生成 PR body（摘要、变更、需求解决、验证结果、关键决策），创建 GitHub PR。STATE.md 更新标记阶段完成。循环重置，准备下一阶段。

多阶段项目

对所有阶段重复讨论→规划→执行→验证→发布。完成后运行：

1
/gsd-progress --next

自动检测下一阶段引导执行。

路径 B：已有代码库接入（棕地项目）

教程用”为已有仓库添加 GET /health 端点”演示完整流程。

第 1 步：安装（同路径 A）

1
npx @opengsd/gsd-core@latest

第 2 步：启动棕地接入

1
/gsd-onboard

/gsd-onboard 避免嵌套交互命令，不覆盖已有 planning 文件。

如提示缺少代码库映射，按推荐执行：

1
/gsd-map-codebase

四个并行映射子 Agent（1-5 分钟）：

Agent 职责
技术映射器 技术栈、框架、依赖
架构映射器 模式、层次、数据流
质量映射器 规范、测试实践
关注点映射器 技术债务、风险领域

产出 .planning/codebase/ 下七份文件：

文件 内容
STACK.md 技术栈
ARCHITECTURE.md 架构模式
STRUCTURE.md 目录结构
CONVENTIONS.md 编码规范
TESTING.md 测试实践
INTEGRATIONS.md 集成点
CONCERNS.md 最值得读的文件——揭示可能影响计划的技术债务

第 3 步：初始化项目

/clear 后重新运行 /gsd-onboard。如果检测到 ADR、PRD 等已有文档，先接受 /gsd-ingest-docs。

然后运行 /gsd-new-project。

关键区别：因为已经读取了代码库映射，GSD Core 知道这是棕地项目。问题聚焦于**”你新增了什么”而非重新描述已有内容**。

项目初始化完成后，GSD 自动将现有能力映射到 PROJECT.md 的 Validated 部分。产出还包括 onboarding/SUMMARY.md。

第 4 步：讨论阶段

1
/gsd-discuss-phase 1

因已有代码库映射，每个问题都基于实际代码——例如：

  • “路由应该放在现有 src/routes/index.js 还是新建独立文件？”
  • “使用已有的 Express Router 模式还是引入新方式？”

第 5 步：规划阶段

1
/gsd-plan-phase 1

四个研究子 Agent 并行运行。规划器读取 CONTEXT.md、调研结果和代码库映射，生成符合仓库风格的任务计划。引用路径与讨论中指定的完全一致。

第 6 步：继续标准循环

1
2
3
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1

当代码结构发生重大变化时，重新运行 /gsd-map-codebase 保持映射时效性。

棕地接入核心收获

  • 安全：不覆盖已有文件，不嵌套交互命令
  • 高效：并行映射生成七份结构化文件只需 1-5 分钟
  • 精准：项目初始化只问增量，已有能力自动填充
  • 一致：规划器输出自动符合仓库的代码风格与架构

Part 2：理解 —— 核心概念

2.1 上下文工程：GSD 如何防止上下文腐化

问题

随着 AI 编程会话的持续，上下文窗口逐渐填满。”模型不会突然宕机，但回答的质量会静默下降。”早期指令、约定的架构、声明的约束被推到模型注意力范围的边缘。

这是 Transformer 注意力权重在有限窗口内分配相关性的根本属性——信号噪声比随噪声累积而恶化。

可以 /clear 重新开始，但这牺牲了连续性。

GSD 的结构性修复：新鲜上下文的子 Agent

核心洞察：大多数编码工作不应该在主上下文中。调研、规划、编码、验证是”独立且有界的任务”。每个任务交给一个专用子 Agent，在干净的、范围限定的上下文窗口中启动，然后向精简的编排器汇报。

编排器本身不直接修改源文件。它生成 Agent、收集结果、更新共享状态、路由工作。因为做的事情很少，它自己的上下文增长也很慢。每个子 Agent 在”不受会话积累历史负担”的情况下以完整能力运行。

两个互补原则

规格驱动开发：每个阶段在执行之前生成结构化产物——CONTEXT.md、RESEARCH.md、PLAN.md 带明确完成标准。当执行器 Agent 接触文件时，它有精确的规格，而不是对漫长对话的重新解读。

元提示工程：Agent 定义是精心设计的提示，编码在 workflows/ 和 agents/ 文件中。关于范围界定、验证、升级的累积知识”嵌入系统自身的提示”，不需要每次会话重新解释。

为什么需要 .planning/

上下文工程要求知识在上下文重置后存活。GSD 把每个有意义的输出写为 .planning/ 下的 Markdown 或 JSON。这意味着：

  • 崩溃不丢失工作
  • 任何 Agent 可以直接读取先前产物
  • 你可以编辑或 git-commit 规划输出
  • STATE.md 是主干——Agent 不依赖记忆，依赖文件

权衡

阶段循环引入开销和延迟——生成多个干净上下文 Agent 比在单上下文中直接编辑慢。对于微不足道的改动（重命名变量、修笔误），它是大材小用。GSD 提供 /gsd-quick 和 /gsd-fast 处理这些情况。

经验法则：如果任务可以在一个简短提示中完整描述并单个 Agent 回合完成，跳过阶段循环。如果需要调研、接触不熟悉的文件、依赖未决定的决策——阶段循环保护你。

2.2 阶段循环原理

里程碑 vs 阶段

  • 里程碑问：”这个版本的产品能做什么，不能做什么？”——有意义的可交付增量，含名称、版本号、需求集
  • 阶段问：”下一个我们可以研究、规划、执行和验证的有边界的事情是什么？”——里程碑内的工作单元

里程碑边界落在自然的产品边界——一个可部署的 API、一个可用的 UI 流程。阶段边界落在一次循环内可以安全执行的工作负载限制。

什么构成好的阶段范围

这是最常见的摩擦点：

太大 刚好 太小
“构建认证系统” “添加 HMAC-SHA256 签名验证中间件” 修一个 README 拼写（用 /gsd-quick）
规划器无法分解 目标一句话说清 计划文件只有几行
后续 wave 被阻塞 调研有边界 开销主导执行
验证变成审计 可以并行化为少量不重叠计划 阶段几分钟完成
写了大量代码后才发现设计错误 有清晰可测试的完成定义

“When in doubt, split.” ——更小的阶段完成更快，验证更自信，设计决策出错时更容易纠正。

循环状态管理

循环跨越多个会话和上下文重置。.planning/ 目录使之可能：

  • CONTEXT.md 在规划时可用，即使数小时后
  • PLAN.md 在执行时可用，即使跨重启
  • VERIFICATION.md 在审查阶段时可用
  • STATE.md 在所有之上做导航层：记录活跃里程碑、当前阶段、已完成计划、待处理任务

2.3 日常入口

1
/gsd-next

智能入口，检测项目状态后自动路由。支持状态包括：

状态 路由
no-project 引导创建
paused 恢复工作
blocked 展示阻塞项
verify-failed 引导修复
needs-first-phase 开始讨论
planning 继续规划
executing 继续执行
verify-pending 引导验证
complete 展示总结 
1
/gsd-resume-work

恢复工作（功能更强的版本）：加载 STATE.md → 检查未完成工作（HANDOFF.json/.continue-here/中断的 Agent）→ 按优先级确定下一步 → 自动路由。

1
/gsd-pause-work

暂停：生成 .planning/HANDOFF.json（结构化）+ .continue-here.md（可读），gsd-resume-work 可无缝恢复。

Part 3：进阶 —— 高级用法

3.1 自治模式

1
/gsd-autonomous

无需人工干预自动运行所有剩余阶段。

每个阶段自动执行：Smart Discuss（智能跳过已有 CONTEXT.md）→ Plan（可选 --converge）→ Execute → Code Review + Fix → Verify → Ship。

全部完成后自动运行生命周期：审计→完成里程碑→清理。

安全门始终在线：

  • 执行前仍然运行计划检查器
  • 验证返回 human_needed 或 gaps_found 时仍然暂停
  • 唯一区别：passed 自动推进无需在阶段间确认
  • 包审查门（checkpoint:human-verify 的任务会暂停）

过滤：

  • --from N / --to N — 阶段范围
  • --only N — 单个阶段
  • --interactive — 讨论保持交互，规划和执行后台运行

不适用场景：

  • 仍有未解决的设计决策 → 先手动讨论或加 --interactive
  • 需要精细控制单个阶段 → 用标准命令
  • 阶段涉及新颖或高风险工作 → 手动执行
  • 阶段中部分执行 → 用 gsd-execute-phase 先完成

中断恢复：/gsd-autonomous --from <未完成的阶段号>。GSD 自动跳过已完成阶段。

3.2 跨 AI 审查

1
/gsd-review --phase 3

多个外部 AI CLI 对计划进行独立同行审查。支持 Gemini CLI、Codex CLI、Claude、Cursor、Ollama、LM Studio 等。

产出 REVIEWS.md：

  • 每个审查者的独立审查（含严重性分类）
  • 共识摘要（多审查者共同发现聚合）
  • 分歧部分（审查者意见不一致的领域）

整合反馈：

1
/gsd-plan-phase 3 --reviews    # 让规划器读取审查输出调整计划

自动迭代（推荐）：

1
/gsd-plan-review-convergence 3

运行 规划→审查→重规划→重审查，最多三轮，HIGH 问题清零时提前停止。支持 --codex、--gemini 指定审查者，--all 跑全部，--max-cycles 5 提高上限。

3.3 工作空间隔离

1
2
3
/gsd-workspace create <name>
/gsd-workspace list
/gsd-workspace remove <name>

适合同时维护多个版本或实验性分支。

3.4 并行工作流

1
2
3
/gsd-workstreams create <name>
/gsd-workstreams list
/gsd-workstreams switch <name>

适用于多人协作或同时推进多个独立任务。

3.5 AI 功能开发

1
/gsd-ai-integration-phase

为 AI 系统阶段生成 AI-SPEC.md 设计契约。内部：

  1. 框架选择（交互式决策矩阵，评分推荐）
  2. 评估策略（故障模式识别、评估维度选择、评分标准）
  3. 领域调研（业务领域和真实应用上下文）
  4. AI 框架指导（最佳实践、语法、核心模式、常见陷阱）

3.6 探索与原型

在正式进入阶段循环之前：

1
2
3
4
/gsd-explore     # 苏格拉底式构思
/gsd-sketch      # 抛弃式 HTML mockup
/gsd-spike       # 体验式技术验证（写代码跑跑看）
/gsd-capture     # 捕获灵感、任务、笔记

3.7 快速任务

对于不适合完整阶段循环的小事：

1
2
/gsd-fast      # 内联快速（无子 Agent，有原子提交）
/gsd-quick     # 更轻的快速（跳过可选 Agent）

3.8 调试

1
/gsd-debug <问题描述>

系统化调试，跨上下文重置保持状态。会话持久化在 .planning/debug/{slug}.md。

1
/gsd-forensics

对失败的 GSD 工作流做死后调查——诊断出错位置和原因。

3.9 MemPalace 知识管理

1
2
/gsd-mempalace-recall     # 规划前从知识库调用决策、模式
/gsd-mempalace-capture    # 完成后归档阶段产物

跨项目、跨会话积累经验的长期知识库。

3.10 配置定制

1
/gsd-config

可配置：

  • 工作流开关：skip_discuss、tdd_mode
  • 审查深度：code_review_depth（quick/standard/deep）
  • 默认审查者：review.default_reviewers
  • 模型配置：不同任务用不同模型

Part 4：精通 —— 最佳实践

① 上下文管理是核心纪律

  • **每个阶段前 /clear**，防止上下文腐化
  • /gsd-execute-phase 为每个执行器提供 200K 干净上下文
  • 编排器本身轻量运行，上下文增长缓慢

② STATE.md 是你最好的朋友

  • 每次会话开始：/gsd-next 或 /gsd-resume-work
  • 出问题时直接打开 .planning/STATE.md 看当前状态
  • Agent 不依赖记忆，依赖文件

③ 阶段范围的艺术

  • 目标能一句话说清，不太小也不太大
  • 调研有边界，不依赖其他阶段先完成
  • 执行能并行化为少量不重叠计划
  • 有清晰可测的完成定义
  • 拿不准就拆

④ 善用自治模式

  • 小型单阶段 → /gsd-autonomous --only 1 一阶段到底
  • 大型多阶段 → /gsd-autonomous 自动跑全部
  • 关键阶段 → 加 --interactive 保留讨论审核
  • 中断后 → --from N 从断点恢复

⑤ 跨 AI 审查提升质量

  • 免费覆盖：--gemini + --agy（都用 Google 凭据）
  • 零 API 成本：配置 Ollama 本地 + --ollama
  • 发布前最大化覆盖：--all + convergence
  • 快速迭代：选单个 CLI，如 --gemini

⑥ 棕地项目用好代码库映射

  • /gsd-onboard → /gsd-map-codebase → /gsd-new-project
  • CONCERNS.md 是最值得读的文件
  • 结构大改时重新 /gsd-map-codebase

⑦ GSD 与其他框架协同

框架 何时用
GSD 总指挥——掌控整个项目生命周期
Superpowers 在 GSD 阶段内确保流程纪律（TDD、验证）
mattpocock 在 GSD 阶段内执行具体工程任务
Gstack 需要浏览器自动化、设计系统、部署监控时

Part 5：完整命令速查表

初始化（4）

命令 说明
/gsd-new-project 新建绿地项目
/gsd-onboard 已有代码库接入（棕地）
/gsd-new-milestone "名称" 已有项目添加里程碑
/gsd-ingest-docs 从已有 ADR/PRD/SPEC 引导

导航（5）

命令 说明
/gsd-next 智能入口（检测状态，自动路由）
/gsd-progress 查看/推进进度
/gsd-resume-work 恢复上一会话
/gsd-pause-work 暂停并创建交接文件
/gsd-help [topic] 帮助

阶段循环（7）

命令 说明
/gsd-spec-phase N 前置明确阶段交付内容
/gsd-discuss-phase N 讨论 → CONTEXT.md
/gsd-plan-phase N 规划 → PLAN.md
/gsd-execute-phase N 执行 → SUMMARY.md
/gsd-verify-work N UAT 验证 → UAT.md
/gsd-validate-phase N Nyquist 验证缺口
/gsd-ship N 发布 → PR

质量门（5）

命令 说明
/gsd-code-review N [--fix] 代码审查
/gsd-secure-phase N 安全威胁验证
/gsd-ui-review UI 视觉审计
/gsd-eval-review AI 评估覆盖
/gsd-audit-uat 跨阶段 UAT 审计

自治与快速（4）

命令 说明
/gsd-autonomous [--from N] [--to N] [--interactive] 自治运行
/gsd-fast 快速内联任务
/gsd-quick 快速任务（更轻）
/gsd-mvp-phase 垂直 MVP 切片

AI 与审查（3）

命令 说明
/gsd-ai-integration-phase AI 设计契约
/gsd-review --phase N 跨 AI 同行审查
/gsd-plan-review-convergence N 跨 AI 计划收敛

调试（2）

命令 说明
/gsd-debug 系统化调试（跨上下文保持状态）
/gsd-forensics 失败工作流死后调查

探索（4）

命令 说明
/gsd-explore 苏格拉底式构思
/gsd-sketch 抛弃式 HTML mockup
/gsd-spike 体验式技术验证
/gsd-capture 捕获想法

工作空间（3）

命令 说明
/gsd-workspace 隔离工作空间
/gsd-workstreams 并行工作流
/gsd-manager 总控仪表盘

知识（3）

命令 说明
/gsd-extract-learnings 提取经验
/gsd-mempalace-recall 从知识库调用
/gsd-mempalace-capture 归档到知识库

统计与分析（4）

命令 说明
/gsd-stats 项目统计
/gsd-graphify 知识图谱
/gsd-map-codebase 代码库映射
/gsd-health 健康诊断

维护（10+）

命令 说明
/gsd-config 配置
/gsd-update 更新 GSD
`/gsd-phase [–insert –remove
/gsd-review-backlog 审查积压
/gsd-inbox Issue/PR 审查
/gsd-pr-branch 干净审查分支
/gsd-undo 安全回滚
/gsd-complete-milestone 完成里程碑
/gsd-cleanup 清理归档
/gsd-add-tests 补充测试
/gsd-audit-fix 自治审计修复
/gsd-milestone-summary 里程碑总结
/gsd-docs-update 更新文档
/gsd-thread 持久化上下文线程
/gsd-profile-user 用户画像
/gsd-surface 技能展示管理
/gsd-ultraplan-phase [BETA] 云端规划
/gsd-import 导入外部计划