GSD 入门实战指南：用 get-shit-done-cc 构建可靠的 AI 规格驱动开发工作流

2026-09-07 20:59:56作者：秋泉律Samson

导读：Get Shit Done（GSD，npm 包名 get-shit-done-cc）是一套轻量而强大的 meta-prompting、上下文工程与规格驱动开发（spec-driven development） 系统，为 Claude Code、OpenCode、Gemini CLI、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Cline 等 AI 编程工具提供统一的能力层。它要解决的核心痛点是 context rot（上下文腐化）——即当对话窗口被不断写入内容后，模型输出质量逐渐劣化的现象。读完本文，你将掌握 GSD 的完整安装/卸载方法、discuss → plan → execute → verify → ship 的六段式开发循环、ROADMAP.md 等上下文文件体系、模型 Profile 切换与安全加固配置，并能直接跑通第一个由 AI 独立交付的里程碑。

为什么会有 GSD：把「vibe coding」变成可靠交付

关联文档：README.pt-BR.md

「Vibe coding」近年来名声参差：你描述需求、AI 生成代码，但结果往往不一致，一上规模就崩。GSD 作者是独立开发者，其自述是「我不写代码——Claude Code 写」；市面上 BMAD、SpecKit、OpenSpec、Taskmaster 等规格驱动工具虽然不少，但大多自带 sprint 仪式、story points、stakeholder sync、retrospective 等「企业戏剧」，对独立开发者或小团队过重。

GSD 的设计哲学因此非常明确：复杂度在系统内部，而不是在你的工作流里。内部是上下文工程、XML prompt 格式化、子代理编排、状态管理；对外你只看到「几个简单好用的命令」。文档原文的精辟表述是：

背后做了：engenharia de contexto（上下文工程）、formatação XML de prompts（XML 化 prompt）、orquestração de subagentes（子代理编排）、gerenciamento de estado（状态管理）；
表面看到：alguns comandos que simplesmente funcionam（几个开箱即用的命令）。

这套系统同时给模型「干活所需的全部信息」与「验证结果所需的全部手段」，把 Claude Code 从「强大」变成「可靠」。

内置质量门（Quality Gates）

为了从机制上拦下真实开发中的高频问题，GSD 内置了多项自动化的质量闸门（README「Para quem é」一节）：

Schema drift 检测：ORM 层改动未同步迁移时会主动告警；
安全锚定：将验证绑定到威胁模型（threat model），而不是泛泛的「检查一下安全性」；
范围缩减检测：阻止 planner 在规划阶段悄悄丢弃需求，避免「实现看起来完成、实际短斤缺两」。

这些设计在后续命令（/gsd-plan-phase、/gsd-execute-phase、/gsd-audit-milestone）的执行路径中都会起作用。

v1.39 亮点速览

对应本文成稿时的仓库内容，v1.39 引入的能力在 RELEASE-v1.39.0-rc.7.md 中有完整记录，核心如下：

特性	说明
`--minimal` 安装 Profile（别名 `--core-only`）	只安装主循环所需的 6 个 skill（`new-project`、`discuss-phase`、`plan-phase`、`execute-phase`、`help`、`update`），不安装任何 `gsd-*` 子代理。冷启动 system prompt 开销从约 12k tokens 降到约 700 tokens（≥94% 缩减），适合 32K–128K 上下文的本地 LLM 与按 token 计费的 API
`/gsd-phase --edit`	就地编辑 `ROADMAP.md` 中既有阶段的任意字段而不改变编号与位置；`--force` 跳过确认 diff；`depends_on` 引用会做校验，写入时同步更新 `STATE.md`
合并后 Build & Test gate	`execute-phase` 的 5.6 步自动探测 `workflow.build_command` 构建命令，并回退到 Xcode（`.xcodeproj`）、Makefile、Justfile、Cargo、Go、Python、npm；Xcode/iOS 项目自动执行 `xcodebuild build` 与 `xcodebuild test`
按 runtime 的 review 模型	`review.models.<cli>` 允许 codex、gemini 等外部 review CLI 各自指定模型，独立于 planner/executor 的 profile
workstream 配置继承	设置 `GSD_WORKSTREAM` 后，先加载根 `.planning/config.json` 再与 workstream 配置深度合并，workstream 冲突时胜出；显式 `null` 可正确覆盖根值
Skill 合并 86 → 59	4 个新的聚合 skill（`capture`、`phase`、`config`、`workspace`）吸收 31 个微 skill；6 个父 skill 用 flags 吸收收尾/子操作，如 `update --sync/--reapply`、`sketch --wrap-up`、`spike --wrap-up`、`map-codebase --fast/--query`、`code-review --fix`、`progress --do/--next`

快速开始：安装与验证

一条命令启动安装器

npx get-shit-done-cc@latest

安装器交互式地询问两个问题：

Runtime——要装进哪个 AI 编码工具：Claude Code、OpenCode、Gemini、Kilo、Codex、Copilot、Cursor、Windsurf、Antigravity、Augment、Trae、Cline，或全部（--all）；
Local——Global（作用到所有项目）还是 local（仅当前项目）。

npm 侧要求 Node.js ≥ 22（见仓库 package.json 的 engines 字段），安装产物会分发到各 runtime 的命令目录（commands/gsd/*.md 即为 skill 源码，见仓库 commands/gsd/ 目录）。

验证是否安装成功

Runtime	验证命令
Claude Code / Gemini / Copilot / Antigravity	`/gsd-help`
OpenCode / Kilo / Augment / Trae	`/gsd-help`
Codex	`$gsd-help`
Cline	GSD 通过 `.clinerules` 安装——检查 `.clinerules` 文件是否存在

[!NOTE] Claude Code 2.1.88+ 与 Codex 以 skills 形态安装（skills/gsd-*/SKILL.md），Cline 使用 .clinerules，其余 runtime 使用各自的命令目录。安装器会自动处理所有格式差异。

两种命令拼写形态

同一套 skill 会被分发到所有受支持的 runtime，但存在两种 slash 拼写（详见 docs/USER-GUIDE.md）：

连字符形态 /gsd-command-name：Claude Code、Copilot、OpenCode、Kilo、Cursor、Windsurf、Augment、Antigravity、Trae；
冒号形态 /gsd:command-name：仅 Gemini CLI 使用——Gemini 把所有插件命令放在插件 id 命名空间下，因此 --gemini 安装路径会把正文引用与命令文件重写为冒号形态。

安装器会在目标 runtime 的命令目录写入正确形态，无需手动选择；在 Gemini 终端跟读本文时，把 gsd 后的连字符换成冒号即可。

保持最新 & 非交互安装

重新运行 npx get-shit-done-cc@latest 即完成更新。在 Docker、CI、脚本里可使用非交互参数：

# Claude Code
npx get-shit-done-cc --claude --global
npx get-shit-done-cc --claude --local

# OpenCode
npx get-shit-done-cc --opencode --global

# Gemini CLI
npx get-shit-done-cc --gemini --global

# Kilo
npx get-shit-done-cc --kilo --global
npx get-shit-done-cc --kilo --local

# Codex
npx get-shit-done-cc --codex --global
npx get-shit-done-cc --codex --local

# Copilot
npx get-shit-done-cc --copilot --global
npx get-shit-done-cc --copilot --local

# Cursor
npx get-shit-done-cc --cursor --global
npx get-shit-done-cc --cursor --local

# Antigravity
npx get-shit-done-cc --antigravity --global
npx get-shit-done-cc --antigravity --local

# Augment
npx get-shit-done-cc --augment --global   # 安装到 ~/.augment/
npx get-shit-done-cc --augment --local    # 安装到 ./.augment/

# Trae
npx get-shit-done-cc --trae --global      # 安装到 ~/.trae/
npx get-shit-done-cc --trae --local       # 安装到 ./.trae/

# Cline
npx get-shit-done-cc --cline --global     # 安装到 ~/.cline/
npx get-shit-done-cc --cline --local      # 安装到 ./.clinerules

# 全部 runtime
npx get-shit-done-cc --all --global

参数速记：--global（-g）/ --local（-l）跳过 Local 问题；--claude、--opencode、--gemini、--kilo、--codex、--copilot、--cursor、--windsurf、--antigravity、--augment、--trae、--cline、--all 跳过 Runtime 问题。

推荐配合：无权限确认模式

claude --dangerously-skip-permissions

这是 GSD 预设的用法——反复批准 50 次 date 与 git commit 会杀死生产力。如果你在 Docker/容器内安装，需要先指定配置目录再执行：

CLAUDE_CONFIG_DIR=/home/youruser/.claude npx get-shit-done-cc --global

此外，从源码安装或无 npm 环境时，可参考仓库 docs/manual-update.md。

核心工作流：六段式开发循环

关联文档：README.pt-BR.md「Como funciona」；逐命令细节见 docs/USER-GUIDE.md。

如果你已经有一份现有代码，官方建议先跑 /gsd-map-codebase 让 GSD 分析 stack、架构、约定与风险，再进入下述循环。

1. 初始化项目：`/gsd-new-project`

系统依次执行四件事：提问直到理解目标 → 用并行子代理调研领域 → 抽取需求（v1、v2、范围外）→ 按阶段组装 roadmap。产出文件全部写入 .planning/：

PROJECT.md——项目愿景；
REQUIREMENTS.md——需求清单（如 REQ-001: 校验签名头）；
ROADMAP.md——分阶段方向与状态；
STATE.md——跨会话记忆；
.planning/research/——调研结论。

/gsd-new-project [--auto] 可跳过交互式提问，直接从 PRD 文件批量注入需求。

2. 讨论阶段偏好：`/gsd-discuss-phase [N]`

在真正规划之前先锁定「你希望怎么建」，而不只是「建什么」——比如错误处理策略、配置粒度、库选型约束。产出 {phase_num}-CONTEXT.md（阶段目录下），成为后续 planner 的硬输入。

3. 规划阶段：`/gsd-plan-phase [N]`

并行调研不同实现路径；
产出 2–3 个原子化 XML 计划；
对照需求校验（范围缩减检测在此生效）。

产出 {phase_num}-RESEARCH.md 与若干 {phase_num}-{N}-PLAN.md。--skip-research 可跳过调研；--reviews 打开额外校验。

4. 执行阶段：`/gsd-execute-phase <N>`

把计划按**波次（waves）**执行：相互独立的计划并行，有依赖的顺序执行；
每个计划开一个全新 200k 上下文的执行器（从源码与文档推断，仓库为每个 plan 配置独立执行上下文，见 get-shit-done/workflows/execute-phase.md）；
每个任务生成原子 commit，便于 git bisect、回滚与追溯；
对照目标校验，产出 {phase_num}-{N}-SUMMARY.md 与 {phase_num}-VERIFICATION.md。

v1.39 起执行阶段末尾还内置 build & test gate（见上文亮点表）。

5. 人工验证：`/gsd-verify-work [N]`

面向人的手动 UAT：从阶段目标中抽取可验证交付物，逐项提问确认（如「合法签名请求返回 200 吗？」）。回答失败时 GSD 进入诊断——定位根因、生成修复计划，再回到 /gsd-execute-phase 应用。产出 {phase_num}-UAT.md。

6. 多阶段循环与里程碑收尾

/gsd-discuss-phase 2
/gsd-plan-phase 2
/gsd-execute-phase 2
/gsd-verify-work 2
/gsd-ship 2              # 为已验证阶段创建 PR（--draft 生成草稿 PR）
/gsd-complete-milestone  # 归档、打 release tag
/gsd-new-milestone       # 开启下一里程碑

也可以把推进权交给 GSD：/gsd-progress --next 自动定位并执行下一步。临时小任务则走 /gsd-quick，它不触发完整规划周期，但保留 GSD 的执行保证：--full 打开全部步骤、--validate 只打开验证阶段、--research 为临时任务附加调研代理、--discuss 附加讨论阶段。

提示：phase 目录默认形如 .planning/phases/01-core-middleware/，可用 project_code（如 "ABC" 生成 ABC-01-setup/）与 phase_naming 自定义前缀。

为什么它有效：三大工程支柱

支柱一：上下文工程（Context Engineering）

每一类信息都被隔离到专门文件，形成清晰的「记忆分层」，对抗 context rot：

文件	职责
`PROJECT.md`	项目愿景
`research/`	生态知识、调研结论
`REQUIREMENTS.md`	v1/v2 范围
`ROADMAP.md`	方向与进度
`STATE.md`	跨会话记忆（当前位置）
`PLAN.md`	原子任务 + XML 结构
`SUMMARY.md`	每任务改了什么
`todos/`	之后要做的事
`threads/`	持久化上下文
`seeds/`	下一里程碑的想法种子

每个 executor 只读当前任务所需的文件，而不是把整段历史灌进窗口，这正是 GSD 缓解 context rot 的核心机制；仓库另有 docs/context-monitor.md 描述上下文窗口监控的架构。

支柱二：XML 化 prompt 格式

任务计划用结构化 XML 描述，把「做什么、动哪些文件、怎么做、怎么验证、算完的标准」五要素写死：

<task type="auto">
  <name>Create login endpoint</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>
    Use jose for JWT (not jsonwebtoken - CommonJS issues).
    Validate credentials against users table.
    Return httpOnly cookie on success.
  </action>
  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
  <done>Valid credentials return cookie, invalid return 401</done>
</task>

字段含义：name 任务名；files 计划改动的文件清单；action 实现指引（可内嵌技术约束，如选型与已知坑）；verify 可执行的验证命令；done 明确的完成判据。这种格式让计划可解析、可校验，也让执行器有据可依。

支柱三：多代理编排与原子提交

一个轻量编排器按需调度专业子代理（research / planning / execute / verification / review…）。仓库 agents/ 目录以 gsd-*.md 形式存放了 30+ 个角色定义，例如 gsd-executor（执行）、gsd-verifier（验证）、gsd-code-reviewer（评审）、gsd-security-auditor（安全审计）、gsd-ui-auditor（UI 审查）、gsd-assumptions-analyzer（假设分析）等。每个任务独立 commit，让 git bisect、回滚、审计都成为平凡操作。

命令全景

各命令的实现均可在仓库 commands/gsd/ 目录找到对应 *.md 源文件。

主循环命令

命令	作用
`/gsd-new-project [--auto]`	初始化完整项目
`/gsd-discuss-phase [N] [--auto] [--analyze] [--chain]`	在规划前锁定决策（`--chain` 自动串联 plan+execute）
`/gsd-plan-phase [N] [--auto] [--reviews]`	调研 + 计划 + 校验
`/gsd-execute-phase <N>`	按并行波次执行计划
`/gsd-verify-work [N]`	人工 UAT
`/gsd-ship [N] [--draft]`	为已验证阶段创建 PR（PR body 默认含 `Summary`、`Changes`、`Requirements Addressed`、`Verification`、`Key Decisions` 等必需区块）
`/gsd-progress --next`	自动推进到下一步
`/gsd-fast <text>`	无需规划的琐碎任务
`/gsd-complete-milestone`	收尾里程碑并标记 release
`/gsd-new-milestone [name]`	开启下一里程碑

质量与工具命令

命令	作用
`/gsd-review`	多 AI 交叉 peer review
`/gsd-pr-branch`	为 PR 创建干净分支
`/gsd-settings`	配置 profiles 与 agents
`/gsd-config --profile <profile>`	切换 model profile（quality / balanced / budget / inherit）
`/gsd-quick [--full] [--discuss] [--research] [--validate]`	带 GSD 保证的快速执行
`/gsd-health [--repair]`	检查并修复 `.planning/`

完整命令与 flag 清单见 docs/COMMANDS.md，或用 /gsd-help。

配置与模型 Profile

项目级配置集中在 .planning/config.json（初始化项目时生成，之后用 /gsd-settings 修改）。完整 schema 见仓库 docs/CONFIGURATION.md。

两个最常用的开关

配置	选项	默认	控制
`mode`	`yolo`、`interactive`	`interactive`	自动批准 vs 每步确认
`granularity`	`coarse`、`standard`、`fine`	`standard`	阶段粒度（coarse≈3–5 阶段、standard≈5–8、fine≈8–12）

历史备注：granularity 在 v1.22.3 前叫 depth，旧配置会自动迁移。

模型 Profile

Profile	规划	执行	验证
`quality`	Opus	Opus	Sonnet
`balanced`	Opus	Sonnet	Sonnet
`budget`	Sonnet	Sonnet	Haiku
`inherit`	Inherit	Inherit	Inherit

快速切换：

/gsd-config --profile budget

更进阶的配置还包括（见 docs/CONFIGURATION.md）：

按阶段类型指定模型 models.<phase_type>：可选 planning、discuss、research、execution、verification、completion 六槽位，取值 opus/sonnet/haiku/inherit，优先级介于 model_overrides（更高）与 model_profile（更低）之间，可实现「规划用 Opus、其余用 Sonnet」；
runtime-aware profiles runtime 与 model_profile_overrides.<runtime>.<tier>：把 profile 档位解析为各 runtime 原生模型 ID（v1.39 起）；按 (runtime, tier) 覆盖映射，值可为模型 ID 或 { model, reasoning_effort }；
review 模型 review.models.<cli>：为 codex / gemini / opencode 等 review CLI 单独指派模型，例如 "codex exec --model gpt-5"、"gemini -m gemini-2.5-pro"；
工作流开关 workflow.*：如 research（规划前调研）、plan_check（计划校验）、verifier（执行后验证）、use_worktrees、tdd_mode、security_enforcement 等；
git 策略 git.branching_strategy（none 等）、create_tag、phase_branch_template（默认 gsd/phase-{phase}-{slug}）；
响应语言 response_language：设为 "pt"/"ko"/"ja" 等即让所有派生代理跨阶段使用一致语言（仓库 README.zh-CN.md、README.ko-KR.md 等即体现这种多语言生态）。

安全设计

内置加固

GSD 出厂自带多项防护，且仓库根目录 hooks/ 中存放了对应实现，例如 gsd-prompt-guard.js（prompt 注入防护）、gsd-read-guard.js / gsd-read-injection-scanner.js（读取注入扫描）、gsd-workflow-guard.js、gsd-validate-commit.sh（提交校验）等：

path traversal 防护；
prompt injection 检测；
shell 参数校验；
JSON 解析安全；
面向 CI 的注入扫描器（prompt-injection-scan.sh 等）。

敏感文件保护

把敏感模式加入 Claude Code 的 deny 名单：

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

排障与卸载

命令装了却没出现？

重启 runtime；
检查文件是否装到了正确的目录（如 Cline 检查 .clinerules 是否存在）。

命令行为不符合预期？

运行 /gsd-help；
用 npx get-shit-done-cc@latest 重装。

Docker/容器环境？

安装前先设置 CLAUDE_CONFIG_DIR（见上文安装一节），确保配置落盘到可写目录。

卸载（global 与 local 分别处理）：

# Global
npx get-shit-done-cc --claude --global --uninstall
npx get-shit-done-cc --opencode --global --uninstall
npx get-shit-done-cc --gemini --global --uninstall
npx get-shit-done-cc --kilo --global --uninstall
npx get-shit-done-cc --codex --global --uninstall
npx get-shit-done-cc --copilot --global --uninstall
npx get-shit-done-cc --cursor --global --uninstall
npx get-shit-done-cc --antigravity --global --uninstall
npx get-shit-done-cc --augment --global --uninstall
npx get-shit-done-cc --trae --global --uninstall
npx get-shit-done-cc --cline --global --uninstall

# Local（当前项目）
npx get-shit-done-cc --claude --local --uninstall
npx get-shit-done-cc --opencode --local --uninstall
npx get-shit-done-cc --gemini --local --uninstall
npx get-shit-done-cc --kilo --local --uninstall
npx get-shit-done-cc --codex --local --uninstall
npx get-shit-done-cc --copilot --local --uninstall
npx get-shit-done-cc --cursor --local --uninstall
npx get-shit-done-cc --antigravity --local --uninstall
npx get-shit-done-cc --augment --local --uninstall
npx get-shit-done-cc --trae --local --uninstall
npx get-shit-done-cc --cline --local --uninstall

深入阅读

想继续深挖，仓库里按主题组织的文档是最佳入口：

docs/README.md / docs/pt-BR/USER-GUIDE.md——葡萄牙语文档总索引与完整用户指南；
docs/USER-GUIDE.md——含端到端 Walkthrough、workflow 图与恢复速查的英文完整指南；
docs/COMMANDS.md——全部命令/flag 参考；
docs/CONFIGURATION.md——完整配置 schema 与模型 Profile 参考；
docs/ARCHITECTURE.md——系统架构与内部设计；
agents/——各专业子代理的角色定义源码；
get-shit-done/templates/ 与 get-shit-done/workflows/——ROADMAP.md、STATE.md 等文档模板与各阶段工作流实现。