GSD (Get Shit Done) 学习教程

一、环境准备

前置知识

学习 GSD 需要以下基础：

安装步骤

1. 确保 AI 运行时已安装

GSD 不是独立工具，它运行在 AI 编码运行时之上：

# 确认 Claude Code 已安装（最常用）
claude --version

# 或其他支持的运行时: Cursor, Windsurf, Gemini CLI, OpenCode 等

2. 安装 GSD

# 交互式安装（推荐）
npx get-shit-done-cc@latest

# 指定运行时安装
npx get-shit-done-cc@latest --runtime opencode

# 带 SDK 安装（用于 Headless/编程集成）
npx get-shit-done-cc@latest --sdk

安装器会自动： - 检测你的 AI 运行时 - 部署 44 个命令、46 个工作流、16+ Agent - 运行时特定的适配转换 - 创建备份和安装清单

3. 配置 API Key

# Anthropic（推荐用于 Claude Code）
export ANTHROPIC_API_KEY="sk-ant-..."

# 建议写入 shell 配置文件
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc

4. 设置全局默认（可选）

# 编辑全局默认配置
# ~/.gsd/defaults.json

环境验证

# 启动 Claude Code
claude

# 在 Claude Code 中输入 GSD 命令
> /gsd:status
# 如果看到 GSD 状态信息，说明安装成功

二、快速开始

Hello World

第一步: 创建新项目

在 Claude Code 中：

> /gsd:new-project

GSD 会创建 .planning/ 目录结构：

.planning/
├── PROJECT.md         # 项目描述
├── REQUIREMENTS.md    # 需求文档
├── ROADMAP.md         # 路线图
├── STATE.md           # 当前状态
├── PLAN.md            # 执行计划
├── SUMMARY.md         # 会话摘要
├── CONTEXT.md         # 当前上下文
├── research/          # 研究产出
├── todos/             # 任务追踪
├── threads/           # 对话线程
└── seeds/             # 未来动作触发器

第二步: 需求讨论

> /gsd:discuss-phase

GSD 会： 1. 启动 3-4 个并行研究 Agent 收集需求 2. 合成器合并研究发现 3. 生成精炼的 REQUIREMENTS.md

第三步: 制定计划

> /gsd:plan-phase

GSD 会： 1. Planner Agent 生成 XML 格式的执行计划 2. 3-4 个检查器在 10 个维度上验证计划 3. 生成 PLAN.md

第四步: 执行

> /gsd:execute-phase

GSD 会按依赖波次执行计划中的所有任务。

第五步: 验证和发布

> /gsd:verify-work
> /gsd:ship

Quick 模式（快速体验）

对于简单任务，不需要完整流程：

> /gsd:quick "创建一个 TODO CLI 工具，支持增删查改"

Quick 模式跳过讨论阶段，直接规划执行。

Fast 模式（速度预设）

> /gsd:fast "给设置页面添加暗黑模式"

Fast 模式是最快的工作流，适合明确的单一功能。

三、核心概念

概念图谱

GSD 核心概念
├── 工作流
│   ├── new-project — 项目初始化
│   ├── discuss-phase — 需求讨论
│   ├── plan-phase — 计划制定
│   ├── execute-phase — 任务执行
│   ├── verify-work — 验证
│   └── ship — 发布
│
├── 元提示
│   ├── XML 任务格式 — name/files/action/verify/done
│   ├── 44 个 Slash 命令
│   ├── 46 个工作流
│   └── 16+ 专用 Agent
│
├── 上下文工程
│   ├── .planning/ 文件系统
│   ├── 编排器 30-40% 上下文占用
│   ├── 子 Agent 各自 200K 全新上下文
│   └── 上下文监控（35% WARNING / 25% CRITICAL）
│
├── 执行模型
│   ├── Wave 执行 — 依赖感知并行
│   ├── 原子提交 — 每任务独立 Git commit
│   ├── 节点修复 — RETRY/DECOMPOSE/PRUNE
│   └── 最小权限 — Agent 只访问必要工具
│
├── 计划验证
│   ├── 10 维度检查
│   ├── Nyquist 合规
│   └── CLAUDE.md 合规
│
├── 模型配置
│   ├── quality — Opus/Opus/Sonnet
│   ├── balanced — Opus/Sonnet/Sonnet
│   ├── budget — Sonnet/Sonnet/Haiku
│   └── inherit — 使用运行时当前模型
│
└── Agent 角色
    ├── 研究员（3-4）— 收集需求
    ├── 合成器（1）— 合并发现
    ├── 规划师（1）— 生成计划
    ├── 检查器（3-4）— 验证计划
    ├── 执行器（1）— 编写代码
    ├── 验证器（1）— UAT 验证
    └── 其他（审计、调试、映射...）

核心概念详解

1. 元提示（Meta-Prompting）

GSD 的核心理念：不直接让 AI 编码，而是生成 AI 可执行的结构化 Prompt。

XML 任务格式示例：

<task>
  <name>实现用户注册 API</name>
  <files>
    src/routes/auth.ts
    src/models/user.ts
    src/middleware/validation.ts
  </files>
  <action>
    1. 创建 User 模型，包含 email、password_hash、created_at 字段
    2. 实现注册路由 POST /api/auth/register
    3. 添加输入验证中间件
    4. 密码使用 bcrypt 加密
  </action>
  <verify>npm run test -- --grep "register"</verify>
  <done>注册 API 测试全部通过，包含成功注册、重复邮箱、输入验证三个测试用例</done>
</task>

5 个关键字段： - name: 任务名称，便于追踪 - files: 任务涉及的文件，防止意外修改 - action: 逐步操作指令 - verify: Shell 命令验证任务完成 - done: 完成条件描述

2. 上下文工程（Context Engineering）

GSD 解决的核心问题——上下文腐化（Context Rot）：

问题:
长会话 Agent → 上下文膨胀 → 信息混淆 → 输出质量下降

GSD 解决方案:
编排器（保持 30-40% 上下文占用）
  → 分派子任务到新 Agent（各自获得全新 200K 上下文）
  → 子 Agent 执行完毕返回结果
  → 编排器汇总继续下一个任务

上下文监控机制： - 编排器上下文剩余 35% → WARNING（自动提醒） - 编排器上下文剩余 25% → CRITICAL（强制压缩）

3. Agent 角色（最小权限）

每个 Agent 只能访问必要的工具：

4. Wave 执行

Plan A: 用户模型 ──┐
                    ├── Wave 1（并行执行）
Plan B: 数据库设计 ──┘
        │
        │ （A 和 B 完成后）
        ▼
Plan C: API 开发 ──── Wave 2
        │
        ▼
Plan D: 集成测试 ──── Wave 3

配置并行度：

{
  "parallelization": {
    "max_concurrent_agents": 3,
    "min_plans_for_parallel": 2,
    "task_level": false
  }
}

5. 节点修复

当任务失败时，GSD 自动尝试三种恢复策略：

任务失败
  │
  ├── RETRY（默认最多 2 次）
  │   └── 使用相同策略重试
  │
  ├── DECOMPOSE
  │   └── 将大任务分解为更小的子任务
  │
  └── PRUNE
      └── 跳过任务，记录缺口

术语表

四、功能详解

4.1 完整工作流（Spec-Driven Development）

新项目:

/gsd:new-project → /gsd:discuss-phase → /gsd:plan-phase → /gsd:execute-phase → /gsd:verify-work → /gsd:ship

存量代码:

/gsd:map-project → /gsd:discuss-phase → (继续上述流程)

快速修复:

/gsd:quick "修复登录超时问题"

速度模式:

/gsd:fast "给设置页面添加暗黑模式"

自由路由:

/gsd:do "重构认证模块"

恢复工作:

/gsd:status → /gsd:execute-phase

4.2 命令分类参考

4.3 讨论阶段详解

> /gsd:discuss-phase

执行过程： 1. 启动 3-4 个并行研究员 Agent 2. 每个 Agent 从不同角度研究需求： - Agent A: 功能需求分析 - Agent B: 技术可行性调研 - Agent C: 现有代码库分析 - Agent D: 最佳实践研究 3. 合成器 Agent 合并所有发现 4. 生成精炼的 REQUIREMENTS.md（带 REQ-* ID）

4.4 计划阶段详解

> /gsd:plan-phase

执行过程： 1. Planner Agent 读取 REQUIREMENTS.md 2. 生成 XML 格式的执行计划（多个 Plan，每个包含多个 Task） 3. 3-4 个检查器 Agent 验证计划： - 需求覆盖检查 - 任务原子性检查 - 依赖排序检查 - ... (共 10 个维度) 4. 通过验证的计划写入 PLAN.md

4.5 执行阶段详解

> /gsd:execute-phase

执行过程： 1. 读取 PLAN.md 中的任务 2. 按依赖关系分 Wave 3. 每个 Wave 内的任务并行执行 4. 每个任务： - 编排器构建上下文 - 分派给执行器 Agent（全新 200K 上下文） - Agent 执行并返回结果 - 原子 Git 提交 - 失败则触发节点修复 5. 所有 Wave 完成后结束

4.6 模型配置详解

在 config.json 中设置：

{
  "model_profile": "balanced",
  "model_overrides": {
    "researcher": "claude-sonnet-4",
    "planner": "claude-opus-4",
    "executor": "claude-sonnet-4",
    "checker": "claude-sonnet-4",
    "reviewer": "gpt-4.1"
  }
}

4.7 工作流配置

{
  "workflow": {
    "skip_discuss": false,      // 跳过讨论阶段
    "skip_research": false,     // 跳过研究阶段
    "skip_verify": false,       // 跳过验证阶段
    "assumptions_mode": false,  // 假设模式（减少确认）
    "text_mode": false,         // 纯文本模式
    "ui_phase": false           // 启用 UI 设计阶段
  }
}

4.8 Git 配置

{
  "git": {
    "branching_strategy": "none",   // none | phase | milestone
    "branch_template": "gsd/{phase}",
    "atomic_commits": true,         // 每任务独立提交
    "auto_stage": false             // 自动暂存变更
  }
}

4.9 门禁配置

{
  "gates": {
    "regression_gate": true,    // 回归测试门禁
    "coverage_gate": true       // 需求覆盖率门禁
  }
}

五、多运行时支持

支持的运行时

运行时适配

安装器自动进行运行时特定的适配： - 工具名称映射（不同运行时工具名称可能不同） - 文件路径规范化 - Frontmatter 格式转换 - Hook 事件适配

六、进阶主题

6.1 存量代码开发（Brownfield）

# 第1步: 映射现有代码库
> /gsd:map-project

# GSD 会自动：
# - 分析项目结构
# - 生成 PROJECT.md
# - 建立代码库知识库

# 第2步: 继续正常流程
> /gsd:discuss-phase
> /gsd:plan-phase
> /gsd:execute-phase

6.2 多项目工作区

# 创建工作区
> /gsd:workspace

# 管理多个项目
> /gsd:workstream-list

6.3 开发者画像

# 分析开发者行为模式
> /gsd:profile-user

GSD 会分析你的编码习惯、偏好和风格，优化后续的代码生成。

6.4 种子机制（Seeds）

# 种下"种子"——未来某个条件触发时执行的动作
> /gsd:plant-seed

种子存放在 .planning/seeds/ 目录，当条件满足时自动触发。

6.5 Manager Dashboard

# 终端内的管理面板
> /gsd:manager

提供： - 状态总览 - 阶段导航 - 执行控制

注意: 这是终端内的交互式面板（TUI），不是 Web 界面。

6.6 Headless SDK（v1.30.0+）

# 安装时带 SDK
npx get-shit-done-cc@latest --sdk

# 在代码中使用

import { GSD } from '@gsd-build/sdk';

const gsd = new GSD({
  model_profile: 'balanced',
  runtime: 'claude-code'
});

await gsd.newProject('my-app');
await gsd.discuss('需求描述');
await gsd.plan();
await gsd.execute();
await gsd.verify();

6.7 安全注意事项

GSD v1.27+ 内置了多层安全防护：

七、常见问题

Q1: GSD 和 "GSD-2" 是什么关系？

没有独立的 "GSD-2" 产品。"GSD-2" 是社区对当前成熟版本的俗称，用来区分早期简化版。GitHub 上只有一个仓库 gsd-build/get-shit-done，当前版本 v1.30.0。

Q2: GSD 和 Claude Code 是什么关系？

GSD 不是 Claude Code 的替代品，而是增强框架。GSD 以 Prompt 文件的形式运行在 Claude Code 内部，通过 Slash 命令（/gsd:xxx）调用。GSD 为 Claude Code 添加了结构化工作流、多 Agent 编排、上下文工程等能力。

Q3: GSD 支持哪些 AI 运行时？

支持 8+ 运行时: Claude Code（主要）、OpenCode、Gemini CLI、Codex、Copilot、Antigravity、Windsurf、Cursor CLI。

Q4: /gsd:quick 和 /gsd:fast 有什么区别？

• /gsd:quick — 跳过讨论阶段，直接规划和执行。适合中等复杂度的任务
• /gsd:fast — 最快模式，适合明确的单一功能。跳过更多步骤

Q5: 如何选择模型配置？

• quality: 关键项目、首次开发、质量要求极高
• balanced: 日常开发（推荐默认）
• budget: 成本敏感、探索阶段
• inherit: 使用当前运行时的模型设置

Q6: 上下文腐化是什么？

上下文腐化（Context Rot）是指 AI Agent 在长会话中，随着上下文窗口逐渐填满，输出质量逐渐下降的现象。GSD 通过让编排器保持低上下文占用（30-40%），并将实际工作分派给获得全新 200K 上下文的子 Agent 来解决。

Q7: 计划检查的 10 个维度是什么？

1. 需求覆盖 — 每个 REQ-* 都被覆盖
2. 任务原子性 — 每个任务自包含
3. 依赖排序 — 无循环依赖
4. 文件范围 — 无意外文件修改
5. 验证命令 — 每个任务有测试
6. 上下文适配 — 任务在上下文窗口内可完成
7. 间隙检测 — 任务间无遗漏步骤
8. Nyquist 合规 — 测试覆盖率映射到需求
9. 跨计划数据契约 — 计划间通信正确
10. CLAUDE.md 合规 — 遵循项目约定

Q8: 多人团队如何使用？

• .planning/ 目录提交到 Git，团队共享状态
• 利用 Git 分支策略（phase 或 milestone 模式）
• 不同开发者可以在不同阶段并行工作
• 使用 /gsd:workspace 管理多项目

八、参考资料

官方资源

• GitHub 仓库: https://github.com/gsd-build/get-shit-done
• npm 安装包: https://www.npmjs.com/package/get-shit-done-cc
• GSD SDK: https://www.npmjs.com/package/@gsd-build/sdk

社区资源

• YouTube: "I Created GSD For Claude Code" (TÂCHES TEACHES, 45K views)
• YouTube: "GSD 2 vs Claude Code: A New AI King?" (Chase AI, 41K views)
• YouTube: "GSD Is the Missing Piece For Claude Code" (AI LABS, 39K views)
• Reddit: r/ClaudeCode GSD 相关讨论

竞品参考

• PAUL: 灵活的 AI 编码工作流框架
• SEED: AI 开发辅助工具
• Ralph Loops: GSD 的前身框架
• Superpowers: Claude Code 增强框架

学习路线图

第1天: 基础入门
├── 安装 GSD
├── 了解 GSD 和 Claude Code 的关系
├── 尝试 /gsd:quick "简单任务"
└── 理解 .planning/ 目录结构

第2-3天: 核心工作流
├── 学习完整工作流: discuss → plan → execute → verify → ship
├── 理解元提示和 XML 任务格式
├── 掌握模型配置（quality/balanced/budget）
└── 实践一个中等规模的项目

第4-5天: 进阶功能
├── 学习 Wave 执行和并行配置
├── 理解上下文工程和防腐化机制
├── 掌握节点修复（RETRY/DECOMPOSE/PRUNE）
└── 了解 10 维度计划检查

第6-7天: 工作流定制
├── 存量代码开发（/gsd:map-project）
├── 配置工作流开关（skip_discuss 等）
├── 尝试多运行时支持
└── 探索 Headless SDK 集成