GSD — Get Shit Done 使用指南

GSD（Get Shit Done）是一套基于上下文工程的规格驱动开发系统，解决 AI 编程中的核心痛点——Context Rot：随着上下文窗口填满，AI 输出质量逐渐下降。

支持 Claude Code、Cursor、Gemini CLI、Codex 等多种运行时。

项目地址：github.com/gsd-build/get-shit-done · 官方文档：mintlify.wiki/gsd-build/get-shit-done

---

为什么需要 GSD

直接用 AI 写代码（Vibecoding）的问题众所周知：你描述需求，AI 生成代码，结果是无法规模化的不一致垃圾。GSD 通过四层机制解决这个问题：

• 上下文工程 — 自动为每个任务准备精确的上下文，而非把所有历史塞进窗口
• 结构化任务 — 每个任务都是 XML 格式，AI 理解更精准
• 多 Agent 编排 — 研究、规划、执行、验证由专门 Agent 分工完成
• 原子化提交 — 每个任务完成后立即提交，历史清晰可追溯

---

安装

npx get-shit-done-cc@latest

安装器会引导你选择运行时（Claude Code、Cursor、Gemini CLI、Codex 等，可多选）和作用范围（全局或本地）。安装完成后运行 /gsd:help 验证。

:::note 命令前缀 本文示例统一使用 /gsd:xxx 格式（Claude Code / Cursor / Gemini）。Codex 中将 /gsd: 替换为 $gsd- 即可，例如 /gsd:new-project → $gsd-new-project。 :::

GSD 设计为无摩擦自动化，推荐搭配 claude --dangerously-skip-permissions 使用。如果不想用该参数，可在 .claude/settings.json 中单独开放 GSD 所需权限。

---

核心工作流

GSD 的完整工作循环：初始化 → 讨论 → 规划 → 执行 → 验证 → 发布 → 下一里程碑

:::info 关键概念：Phase 与 Milestone Milestone（里程碑） 是大版本目标，Phase（阶段） 是把它拆解后的每个可独立交付的批次——例如 Phase 1 搭认证框架、Phase 2 做用户列表。每个 Phase 都有自己的完整小循环：讨论 → 规划 → 执行 → 验证，并生成对应的规划文件。

研究不是独立步骤，而是内嵌在初始化和规划中的子过程。 :::

第一步：初始化项目

/gsd:new-project

系统会自动完成：

1. 提问 — 彻底理解你的想法（目标、约束、技术偏好、边界情况）
2. 研究 — 并行 Agent 调查领域知识（可选但推荐）
3. 需求提炼 — 区分 v1、v2 和超出范围的内容
4. 路线图 — 将需求映射到开发阶段

你审批路线图，然后开始构建。

生成文件及其作用：

文件	作用
PROJECT.md	定义项目愿景、边界和长期方向
REQUIREMENTS.md	按 v1/v2 和范围切分需求
ROADMAP.md	把需求拆成阶段，逐步推进
STATE.md	记录当前状态、进展、阻塞点和下一步，持续更新
.planning/research/	存放并行调研结果，供后续规划引用

:::tip 已有代码库？ 先运行 /gsd:map-codebase 让 GSD 了解你的技术栈和惯例，再运行 new-project，规划会更精准。 :::

第二步：讨论阶段

/gsd:discuss-phase 1

路线图中每个阶段只有一两句话，不足以按你的想象构建。这一步在规划之前捕获你的偏好——系统会根据内容类型识别灰色地带并提问：

特性类型	询问内容
视觉功能	布局、密度、交互、空状态
API/CLI	响应格式、参数、错误处理
内容系统	结构、语调、深度、流程
组织任务	分组标准、命名、例外情况

生成文件：

• {phase_num}-CONTEXT.md — 把决策写成明确记录，供下游 Agent（研究、规划、执行）消费
• {phase_num}-DISCUSSION-LOG.md — 问答全过程的审计日志，仅供人工回溯参考，不被下游 Agent 读取

备注

使用 --auto 参数可跳过问答，让 GSD 自动选择推荐默认值。

第三步：规划阶段

/gsd:plan-phase 1

系统会：

1. 研究 — 结合 CONTEXT.md 的决策调查实现方案
2. 规划 — 创建 2-3 个原子任务计划（XML 结构）
3. 验证 — 对照需求检查计划，循环直到通过

每个计划足够小，可以在全新的上下文窗口中执行——零上下文污染，零质量退化。

生成文件：

• {phase_num}-RESEARCH.md — 实现路线、备选方案和注意事项
• {phase_num}-{N}-PLAN.md — 可执行、可验证、可提交的原子任务，是执行 Agent 的直接输入
• {phase_num}-VALIDATION.md — checker agent 对计划质量的验证结果（需求覆盖、依赖合理性、任务粒度）

Plan 示例：

<task type="auto">
  <name>实现管理员登录接口</name>
  <files>src/api/auth/login.ts</files>
  <action>校验邮箱密码，写入 session，失败返回 401</action>
  <verify>提交正确凭证返回 200</verify>
  <done>管理员可以成功登录后台</done>
</task>

第四步：执行阶段

/gsd:execute-phase 1

系统会：

1. 波次执行 — 无依赖的 Plan 并行跑，有依赖的顺序执行，最大化并行度
2. 独立上下文 — 每个 Plan 独占 20 万 token，无历史垃圾
3. 原子提交 — 每个任务完成后立即提交
4. 目标验证 — 检查代码库是否交付了阶段承诺的内容

WAVE 1（并行）          WAVE 2（并行）          WAVE 3
┌─────────┐ ┌─────────┐  ┌─────────┐ ┌─────────┐  ┌─────────┐
│ Plan 01 │ │ Plan 02 │→ │ Plan 03 │ │ Plan 04 │→ │ Plan 05 │
│ 用户模型 │ │ 商品模型 │  │ 订单API │ │ 购物车  │  │ 结账UI  │
└─────────┘ └─────────┘  └─────────┘ └─────────┘  └─────────┘

生成文件：

• {phase_num}-{N}-SUMMARY.md — 每个计划实际改了什么
• {phase_num}-VERIFICATION.md — 系统验证了什么、结果如何

第五步：验证阶段

/gsd:verify-work 1

自动验证只能检查代码和测试，这一步让你确认功能是否按预期运行：

1. 提取可测试的交付物 — 你现在应该能做什么
2. 逐一引导测试 — "你能用邮箱登录吗？"是/否，或描述问题
3. 自动诊断失败 — Debug Agent 找到根本原因
4. 创建修复计划 — 可直接重新执行

生成文件： {phase_num}-UAT.md — 验收结果的正式记录，失败项会驱动下一轮修复计划。

第六步：发布与推进

/gsd:ship 1               # 从验证过的工作创建 PR
/gsd:complete-milestone    # 归档里程碑，打版本标签
/gsd:new-milestone         # 开始下一个版本

前 5 步产出规划与执行文档，第 6 步把成果对外发布并切换到下一轮周期。也可以用 /gsd:next 让 GSD 自动判断下一步。

---

快速模式

/gsd:quick

不需要完整规划的临时任务使用快速模式——相同的 Agent 和质量，但跳过研究、计划检查、验证等步骤，独立存储在 .planning/quick/。

可组合的参数：

参数	效果
--discuss	规划前先收集灰色地带决策
--research	规划前先调查实现方案
--full	启用计划检查 + 执行后验证

---

场景速查

小功能或小修复（老项目）

/gsd:quick --research

需求边界清楚时不需要完整 Phase 流程。--research 让 GSD 先调查实现方案，减少直接开写的偏差。

中大型功能（老项目）

/gsd:map-codebase           # 先理解现有技术栈
/gsd:new-project            # 建立持久化上下文
/gsd:discuss-phase 1        # 捕获偏好
/gsd:plan-phase 1           # 研究 + 规划
/gsd:execute-phase 1        # 执行
/gsd:verify-work 1          # 验收

map-codebase 让 GSD 理解架构和惯例，new-project 建立 PROJECT.md、ROADMAP.md 等持久化上下文，后续 Phase 流程适合长期迭代。

全新项目

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

新项目最需要先定义清楚目标、范围和阶段拆分，后续每个阶段都有清晰上下文，不容易越做越乱。

自动推进

/gsd:next

GSD 读取当前状态，自动判断下一步命令。配合 workflow.auto_advance: true 可实现 discuss → plan → execute 全自动串联。

验收失败后修复

/gsd:verify-work 1          # 把问题沉淀到 UAT.md
/gsd:plan-phase 1           # 围绕失败项生成修复计划
/gsd:execute-phase 1        # 带着明确目标修复

发布与结束

/gsd:ship 1                 # 生成 PR
/gsd:complete-milestone      # 归档并打版本标签
/gsd:new-milestone           # 进入下一轮

---

分支管理

GSD 通过 git.branching_strategy 配置自动管理分支，无需手动 git checkout。

三种分支策略

策略	行为	适用场景
none（默认）	所有工作在当前分支，不创建新分支	个人项目、快速原型
phase	每个 Phase 自动创建独立分支	推荐，中大型项目
milestone	每个 Milestone 创建一个分支，所有 Phase 共用	小型项目、变更不多

Phase 策略下的分支流转

配置 branching_strategy: "phase" 后，GSD 在 execute-phase 时自动创建 phase 分支——discuss 和 plan 阶段仍在当前分支（通常是 main）上进行，因为它们只生成 .planning/ 文档，不涉及代码变更：

main ── discuss → plan ──┬── gsd/phase-1-auth ──→ execute → verify → ship → merge PR
                         │
main ── discuss → plan ──┼── gsd/phase-2-catalog ──→ execute → verify → ship → merge PR
                         │
main ── discuss → plan ──└── gsd/phase-3-cart ──→ execute → verify → ship → merge PR

日常操作流程：

/gsd:discuss-phase 1         # 在 main 上生成 CONTEXT.md
/gsd:plan-phase 1            # 在 main 上生成 RESEARCH.md 和 PLAN.md
/gsd:execute-phase 1         # 自动创建 gsd/phase-1-xxx 并切换，代码变更提交到 phase 分支
/gsd:verify-work 1           # 在 phase 分支上验收
/gsd:ship 1                  # push + 创建 PR，合并回 main
/gsd:discuss-phase 2         # 回到 main，开始下一个 Phase

为什么推荐 Phase 策略

• 回滚安全 — Phase 2 出问题可以单独 revert，不影响已 merge 的 Phase 1
• Review 可控 — 每个 Phase 对应一个 PR，diff 范围清晰
• 并行友好 — 无依赖的 Phase 可以从同一基点创建分支、并行开发、独立合入

none 的风险是所有提交堆在一个分支上，无法按功能发 PR 或回滚。milestone 的问题是一个 Milestone 包含多个 Phase，全部堆在一个分支上导致 PR 巨大、review 困难。

干净的 PR 分支

GSD 的 .planning/ 提交会混在代码提交里，reviewer 不需要看这些规划文件。发 PR 前用 /gsd:pr-branch 创建一个过滤掉所有 .planning/ 提交的干净分支：

/gsd:pr-branch               # 生成只含代码变更的分支
/gsd:ship 1                  # 基于干净分支创建 PR

并行工作流

当需要同时推进多条独立工作线时，有两种隔离机制：

• Workstream（逻辑隔离） — 在同一仓库内创建并行工作流，共享代码但独立管理 GSD 状态

/gsd:workstreams create feature-x    # 创建工作流
/gsd:workstreams switch feature-x    # 切换到另一个工作流
/gsd:workstreams list                # 查看所有工作流状态

• Workspace（物理隔离） — 用 git worktree 创建独立工作目录，适合多仓库协作或高风险实验

/gsd:new-workspace --name experiment   # 创建隔离工作区
/gsd:list-workspaces                   # 查看所有工作区

---

命令速查

主流程

命令	用途
/gsd:new-project	初始化项目：提问 → 研究 → 需求 → 路线图
/gsd:discuss-phase [N]	规划前捕获实现决策
/gsd:plan-phase [N]	研究 + 规划 + 验证
/gsd:execute-phase <N>	波次并行执行所有计划
/gsd:verify-work [N]	用户验收测试
/gsd:ship [N]	创建 PR
/gsd:next	自动推进到下一步
/gsd:complete-milestone	归档里程碑，打标签
/gsd:new-milestone	开始下一个版本

阶段管理

命令	用途
/gsd:add-phase	追加阶段到路线图
/gsd:insert-phase [N]	在阶段间插入紧急任务
/gsd:remove-phase [N]	移除未来阶段并重新编号
/gsd:progress	查看当前进度和下一步

代码质量

命令	用途
/gsd:review	跨 AI 同行评审当前阶段
/gsd:audit-milestone	验证里程碑是否达成定义
/gsd:audit-uat	审计验证债务——找出缺少 UAT 的阶段

会话管理

命令	用途
/gsd:pause-work	中途停止时创建上下文交接
/gsd:resume-work	从上次会话恢复
/gsd:session-report	生成会话摘要

工具类

命令	用途
/gsd:quick	快速执行临时任务
/gsd:fast <text>	内联执行简单任务，完全跳过规划
/gsd:debug [desc]	系统化调试，持久化状态
/gsd:health [--repair]	验证 .planning/ 目录完整性
/gsd:stats	显示项目统计
/gsd:settings	配置模型和工作流

---

配置

GSD 将项目配置存储在 .planning/config.json，可通过 /gsd:settings 交互式修改，也可以直接编辑 JSON 文件。全局默认值存储在 ~/.gsd/defaults.json，新项目初始化时自动合并。

核心设置

设置	选项	默认	说明
mode	interactive / yolo	interactive	自动审批 vs 每步确认
granularity	coarse / standard / fine	standard	阶段粒度——范围拆分细化程度
model_profile	quality / balanced / budget / inherit	balanced	模型配置，详见下方
phase_naming	sequential / custom	sequential	阶段编号方式
context_window	数字	200000	上下文窗口大小（token 数）

模型配置

model_profile 定义不同环节使用的模型等级。以下为 Claude 运行时的默认映射，非 Claude 运行时设置 resolve_model_ids: "omit" 后由运行时自行决定模型：

配置	规划	执行	验证
quality	Opus	Opus	Sonnet
balanced（默认）	Opus	Sonnet	Sonnet
budget	Sonnet	Sonnet	Haiku
inherit	继承	继承	继承

切换配置：

/gsd:set-profile budget

如需更细粒度控制，可用 model_overrides 按 Agent 类型单独指定模型。模型 ID 取决于运行时——Claude 运行时用 Claude 模型 ID，其他运行时用各自支持的模型 ID：

{
  "model_overrides": {
    "gsd-executor": "claude-sonnet-4-20250514",
    "gsd-planner": "claude-opus-4-20250514"
  }
}

resolve_model_ids 控制模型别名（Opus/Sonnet/Haiku）的解析行为：

值	行为	适用场景
false（默认）	原样传递别名	Claude Code 运行时
true	映射为完整 Claude 模型 ID	避免别名导致 API 404
"omit"	返回空串，让运行时用自己的默认模型	Cursor、Gemini CLI、Codex 等非 Claude 运行时

非 Claude 运行时安装时会自动设为 "omit"，无需手动配置。

工作流 Agent 开关

设置	默认	说明
workflow.research	true	每个阶段规划前进行领域研究
workflow.plan_check	true	执行前验证计划能否达成阶段目标
workflow.verifier	true	执行后确认必要交付物已完成
workflow.auto_advance	false	自动串联 discuss → plan → execute
workflow.discuss_mode	discuss	discuss（问答）或 assumptions（代码库分析）
workflow.skip_discuss	false	自主流程中跳过 discuss 阶段
workflow.nyquist_validation	true	规划中做验证/测试覆盖相关研究
workflow.ui_phase	true	为前端阶段生成 UI-SPEC 设计合约
workflow.ui_safety_gate	true	规划前端阶段前提示先运行 UI phase
workflow.text_mode	false	用纯文本编号列表代替交互菜单
workflow.research_before_questions	false	初始化/讨论时在提问前先做 Web 研究
workflow.node_repair	true	执行出错时是否尝试自动修复
workflow.node_repair_budget	2	每个任务的自动修复次数上限

:::caution 内部字段说明 workflow._auto_chain_active 是内部临时状态位，用于 --auto / --chain 自动串联链路，不属于日常手动配置项。除非在排查自动串联异常，否则不建议手动修改。 :::

单次覆盖（不修改配置文件）：

/gsd:plan-phase --skip-research
/gsd:plan-phase --skip-verify

规划与 Git

规划文档：

设置	默认	说明
planning.commit_docs	true	是否将 .planning/ 文档纳入 Git 提交（若被 gitignore 则自动关闭）
planning.search_gitignored	false	搜索时是否包含被 gitignore 的文件
planning.sub_repos	[]	子仓库路径列表，用于 monorepo 场景

Git 分支策略：

设置	默认	说明
git.branching_strategy	none	none / phase / milestone
git.phase_branch_template	gsd/phase-{phase}-{slug}	Phase 分支命名模板，支持 {phase} 和 {slug} 变量
git.milestone_branch_template	gsd/{milestone}-{slug}	Milestone 分支命名模板
git.quick_branch_template	null	Quick 任务分支模板，null 表示不创建分支

并行执行

parallelization 支持布尔值或对象两种写法。布尔值 true 等同于使用默认参数开启并行：

{
  "parallelization": {
    "enabled": true,
    "plan_level": true,
    "task_level": false,
    "skip_checkpoints": true,
    "max_concurrent_agents": 3,
    "min_plans_for_parallel": 2
  }
}

设置	默认	说明
enabled	true	总开关
plan_level	true	同一 Wave 内的 Plan 是否并行执行
task_level	false	单个 Plan 内的 Task 是否并行执行
skip_checkpoints	true	并行执行时跳过中间检查点
max_concurrent_agents	3	最大并发 Agent 数
min_plans_for_parallel	2	触发并行执行的最少 Plan 数

交互门控

gates 控制工作流中各确认步骤是否需要人工审批。mode: "yolo" 会跳过大部分门控，mode: "interactive" 下门控默认全部开启：

设置	默认	说明
gates.confirm_project	true	确认项目定义
gates.confirm_phases	true	确认阶段划分
gates.confirm_roadmap	true	确认路线图
gates.confirm_breakdown	true	确认任务分解
gates.confirm_plan	true	确认执行计划
gates.execute_next_plan	true	执行下一个 Plan 前确认
gates.issues_review	true	确认问题审查
gates.confirm_transition	true	确认阶段切换

安全与钩子

设置	默认	说明
safety.always_confirm_destructive	true	破坏性操作（如删除文件）前强制确认
safety.always_confirm_external_services	true	调用外部服务前强制确认
hooks.context_warnings	true	上下文接近满载时发出提醒

外部搜索 API

GSD 会在初始化时自动探测 API Key 是否可用，也可手动开关：

设置	默认	说明
brave_search	自动探测	基于 BRAVE_API_KEY 环境变量或 ~/.gsd/brave_api_key 文件
firecrawl	自动探测	基于 FIRECRAWL_API_KEY 环境变量或 ~/.gsd/firecrawl_api_key 文件
exa_search	自动探测	基于 EXA_API_KEY 环境变量或 ~/.gsd/exa_api_key 文件

Agent 技能注入

agent_skills 允许为特定 Agent 类型注入额外技能文件，值为字符串或字符串数组，指向项目内包含 SKILL.md 的目录相对路径：

{
  "agent_skills": {
    "gsd-executor": "skills/my-custom-executor-skill",
    "gsd-planner": ["skills/domain-knowledge", "skills/coding-standards"]
  }
}

推荐配置

以下是经过实践验证的推荐配置，兼顾效率和质量：

{
  "mode": "yolo",
  "granularity": "standard",
  "model_profile": "balanced",
  "workflow": {
    "research": true,
    "plan_check": true,
    "verifier": true,
    "auto_advance": true,
    "discuss_mode": "discuss",
    "nyquist_validation": true,
    "ui_phase": true,
    "node_repair": true,
    "node_repair_budget": 3
  },
  "planning": {
    "commit_docs": true,
    "search_gitignored": false
  },
  "git": {
    "branching_strategy": "phase",
    "phase_branch_template": "gsd/phase-{phase}-{slug}",
    "milestone_branch_template": "gsd/{milestone}-{slug}"
  },
  "parallelization": {
    "enabled": true,
    "max_concurrent_agents": 3,
    "min_plans_for_parallel": 2
  },
  "gates": {
    "confirm_roadmap": true,
    "confirm_plan": false,
    "execute_next_plan": false,
    "confirm_transition": false
  },
  "safety": {
    "always_confirm_destructive": true,
    "always_confirm_external_services": true
  },
  "hooks": {
    "context_warnings": true
  }
}

推荐理由：

• mode: "yolo" — GSD 的核心价值是自动化，interactive 模式频繁打断流程。用 yolo 让 Agent 自主推进，把审批精力留给真正需要的环节
• workflow.auto_advance: true — 配合 yolo 模式，discuss → plan → execute 自动串联，一个命令走完整个阶段
• workflow.node_repair_budget: 3 — 默认 2 次修复预算偏保守，3 次能覆盖大多数可自愈问题
• git.branching_strategy: "phase" — 每个阶段独立分支，出问题可以单独回滚，比 none 安全得多
• gates.confirm_roadmap: true — 路线图是最高层决策，值得人工确认
• gates.confirm_plan: false 和 execute_next_plan: false — 有 plan_check 和 verifier 兜底，每个 Plan 再手动确认是多余摩擦
• planning.commit_docs: true — 规划文档纳入 Git，方便团队协作和回溯决策历史

:::tip 部分设置只能手动编辑 gates、safety、model_overrides、context_window、agent_skills 等高级字段不在 /gsd:settings 的交互菜单中，需要直接编辑 .planning/config.json 文件。 :::

---

上下文工程：GSD 为何有效

GSD 管理的核心文件：

文件	作用
PROJECT.md	项目愿景，始终加载
REQUIREMENTS.md	带阶段可追溯性的 v1/v2 需求范围
ROADMAP.md	目标路径和完成状态
STATE.md	跨会话的决策、阻塞点、当前位置
PLAN.md	带 XML 结构的原子任务
SUMMARY.md	执行记录，已提交到历史
research/	技术栈、功能、架构、风险的领域知识
todos/	捕获的想法和后续任务
threads/	跨会话的持久上下文线程

每个文件都有大小限制，基于 Claude 质量退化的临界点设计——保持在限制内，获得持续卓越的输出。

---

安全性

GSD v1.27 起内置纵深防御安全机制：

• 路径遍历防护 — 所有用户提供的文件路径在使用前验证
• 提示词注入检测 — 扫描用户提供文本中的注入模式
• PreToolUse 提示词守卫钩子 — 扫描写入 .planning/ 的内容中的注入向量
• 安全 JSON 解析 — 格式错误的参数在污染状态前被捕获

:::caution 保护敏感文件 在 .claude/settings.json 的 deny 列表中添加敏感文件，防止 Claude 读取：

{
  "permissions": {
    "deny": ["Read(.env)", "Read(.env.*)", "Read(**/*.pem)", "Read(**/*.key)"]
  }
}

:::

---

卸载

# 全局安装
npx get-shit-done-cc --cursor --global --uninstall

# 本地安装
npx get-shit-done-cc --cursor --local --uninstall

卸载会移除所有 GSD 命令、Agent、钩子和设置，同时保留你的其他配置。