GSD (Get Shit Done) - 完整学习教程

教程级别： 从零到一 预计学习时间： 6-8 小时 前置知识： 基本的命令行操作、Git 基础（clone、commit、branch）、Node.js 环境安装（Node >= 22）、至少一种 AI 编码工具的使用经验（推荐 Claude Code） 教程基于版本： GSD v1.35.0（稳定版）

环境搭建指南

系统要求

• 操作系统： macOS、Linux 或 Windows（WSL 推荐）
• 运行时/依赖版本：
• Node.js >= 22.0.0（推荐 Active LTS 版本）
• npm >= 8.0.0（随 Node.js 自动安装）
• Git >= 2.30
• Claude Code CLI（或其他支持的 AI 编码运行时：OpenCode、Gemini CLI、Codex、Copilot、Cursor 等）

安装步骤

GSD v1 的安装只需要一行命令：

# 在终端中运行以下命令
npx get-shit-done-cc@latest

安装程序会依次询问两个问题：

1. 运行时选择 -- 选择你使用的 AI 编码工具（如 Claude Code、OpenCode、Gemini CLI 等）
2. 安装位置 -- Global（所有项目生效，推荐新手）或 Local（仅当前项目）

对于新手，推荐选择 Claude Code + Global。

如果你使用 GSD v2（独立 TypeScript 应用），安装命令为：

# GSD v2 安装（需要 Node >= 22.0.0）
npm install -g gsd-pi

验证安装

安装完成后，打开 Claude Code 并运行以下命令验证：

# 在 Claude Code 中输入
/gsd:help

预期输出：

GSD Commands:
  /gsd:new-project      - Initialize a new project with full planning
  /gsd:discuss-phase N  - Capture implementation decisions
  /gsd:plan-phase N     - Research + plan + verify
  /gsd:execute-phase N  - Execute plans in parallel waves
  /gsd:verify-work N    - Manual user acceptance testing
  /gsd:quick            - Ad-hoc task with GSD guarantees
  /gsd:progress         - Where am I? What's next?
  /gsd:help             - Show all commands
  ...（更多命令列表）

如果看到帮助菜单，说明安装成功。

推荐配置：权限设置

GSD 会生成多个子代理并行执行命令，如果每次都要求手动批准会严重影响效率。推荐进行以下权限配置：

方式一：跳过权限检查（适合个人开发环境）

# 启动 Claude Code 时添加跳过权限标志
claude --dangerously-skip-permissions

方式二：细粒度权限配置（更安全）

# 编辑项目根目录下的 .claude/settings.json
# 如果文件不存在，手动创建目录和文件
mkdir -p .claude

{
  "permissions": {
    "allow": [
      "Bash(date:*)",
      "Bash(echo:*)",
      "Bash(cat:*)",
      "Bash(ls:*)",
      "Bash(mkdir:*)",
      "Bash(git add:*)",
      "Bash(git commit:*)",
      "Bash(git status:*)",
      "Bash(git log:*)",
      "Bash(git diff:*)"
    ]
  }
}

预期输出：

保存后，GSD 的子代理在执行上述命令时将不再请求权限确认。

练习题： 1. 运行 npx get-shit-done-cc@latest，选择你的运行时和安装位置，完成安装。 2. 在 Claude Code 中运行 /gsd:help，确认你看到了完整的命令列表。 3. 配置 .claude/settings.json 中的权限，使 GSD 子代理可以自动执行 git 操作。

第一部分：入门篇

1.1 理解上下文腐化（Context Rot）

概念讲解：

上下文腐化（Context Rot）是 GSD 要解决的核心问题。在使用 Claude Code 等 AI 编码工具时，AI 模型有一个固定的上下文窗口（Claude 为 200K token）。随着你在对话中累积代码、问题和回复，上下文窗口逐渐被填满。当利用率超过一定阈值时，模型输出的质量开始显著下降。

上下文利用率与输出质量的关系如下：

这就是为什么你的 AI 助手在会话开始时写出高质量代码，但几个小时后却开始犯低级错误。问题不在模型能力，而在于上下文窗口的"拥挤"导致模型无法准确检索和使用早期信息。

GSD 的解决方案： 为每个任务创建全新的、干净的上下文窗口，确保每次执行都在 0-30% 的最佳区间内运行。

练习题： 1. 回忆你使用 AI 编码工具时，是否遇到过"开始很好，后来变差"的情况？尝试描述当时的症状。 2. 思考：如果你的项目有 100 个文件，直接在一个 Claude Code 会话中完成所有开发，上下文窗口大约会在什么时候饱和？

1.2 上下文工程（Context Engineering）

概念讲解：

上下文工程（Context Engineering）是 GSD 的核心创新。它的核心思想是：主动管理 AI 代理上下文窗口中加载的内容、时机和方式。具体做法是将项目的所有关键状态外部化到一组结构化的 Markdown 文件中，这样每个新的 AI 会话都可以立即获取完整的项目上下文，无需在上下文窗口中累积历史对话。

GSD 创建的核心上下文文件包括：

• PROJECT.md -- 项目愿景，始终被加载到每个会话中
• REQUIREMENTS.md -- 范围内的 v1/v2 需求，带阶段可追溯性
• ROADMAP.md -- 目标和完成进度
• STATE.md -- 跨会话记忆：决策、阻塞项、当前位置
• CONTEXT.md -- 每个阶段的实现偏好和讨论结果

这些文件构成了项目的"外部大脑"。无论你开了多少个会话、换了多少个上下文窗口，AI 都可以通过读取这些文件立即恢复对项目的完整理解。

代码示例（查看 GSD 创建的上下文文件）：

# 进入你的 GSD 项目目录
cd my-project

# 查看 GSD 创建的规划目录结构
ls -la .planning/

预期输出：

total 32
drwxr-xr-x  10 user  staff   320 Apr 12 10:00 .
drwxr-xr-x   8 user  staff   256 Apr 12 10:00 ..
-rw-r--r--   1 user  staff  1204 Apr 12 10:00 PROJECT.md
-rw-r--r--   1 user  staff   890  Apr 12 10:00 REQUIREMENTS.md
-rw-r--r--   1 user  staff   670  Apr 12 10:00 ROADMAP.md
-rw-r--r--   1 user  staff   430  Apr 12 10:00 STATE.md
-rw-r--r--   1 user  staff   210  Apr 12 10:00 config.json
drwxr-xr-x   4 user  staff   128  Apr 12 10:00 research/
drwxr-xr-x   3 user  staff    96  Apr 12 10:00 phases/
drwxr-xr-x   2 user  staff    64  Apr 12 10:00 todos/

# 查看 PROJECT.md 的内容示例
cat .planning/PROJECT.md

预期输出（示例内容）：

# Project: Task Manager App

## Vision
A lightweight task management application with user authentication,
task CRUD operations, and a responsive web interface.

## Tech Stack
- Frontend: Next.js 14 + TypeScript + Tailwind CSS
- Backend: Next.js API Routes
- Database: SQLite via Prisma
- Auth: JWT with jose library

## Target Users
Solo developers who want a simple, self-hosted task tracker.

## Core Constraints
- Must work offline-first
- No external auth providers (self-contained)
- Mobile-responsive design

练习题： 1. 手动创建一个 .planning/ 目录，并编写一个简单的 PROJECT.md 文件，描述你自己的一个项目。 2. 思考：STATE.md 为什么需要记录"决策"和"阻塞项"？这些信息如何帮助新的 AI 会话恢复上下文？

1.3 元提示（Meta-Prompting）

概念讲解：

元提示（Meta-Prompting）是 GSD 的第二个核心概念。普通的提示告诉 AI"做什么"（如"写一个登录接口"），而元提示告诉 AI"如何组织和执行工作"。GSD 使用 XML 格式的任务计划来实现元提示，每个任务计划都包含精确的指令、约束条件和内置的验证步骤。

一个 XML 任务计划包含以下要素：

• name -- 任务名称，清晰描述目标
• files -- 需要创建或修改的文件列表
• action -- 具体执行步骤和约束条件
• verify -- 机械可验证的完成标准
• done -- 人类可读的完成条件描述

代码示例（XML 任务计划格式，基于官方文档 v1.35.0）：

<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.
    Hash passwords with bcrypt (cost factor 12).
  </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>

执行结果（当 AI 代理执行此任务后）：

# 验证任务是否成功完成
curl -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"secret123"}'

预期输出：

HTTP/1.1 200 OK
Set-Cookie: token=eyJhbGciOiJIUzI1NiIs...; HttpOnly; Path=/; Max-Age=86400
Content-Type: application/json

{"success":true,"user":{"email":"test@example.com"}}

练习题： 1. 为"创建用户注册接口"编写一个 XML 任务计划，包含 name、files、action、verify 和 done 五个要素。 2. 思考：为什么 <action> 中要明确指出"使用 jose 而非 jsonwebtoken"？这种精确的约束有什么好处？

1.4 工作层次结构：Milestone -> Slice -> Task

概念讲解：

GSD 使用三层工作层次结构来组织项目：

Milestone（里程碑） -> 可交付版本（4-10 个 Slice）
  Slice（切片）     -> 一个可演示的垂直功能（1-7 个 Task）
    Task（任务）    -> 一个上下文窗口大小的工作单元

• Milestone（里程碑）： 对应一个可交付的版本（如 v1.0）。包含 4-10 个阶段（Phase/Slice），代表一个完整的功能集合。
• Phase/Slice（阶段/切片）： 一个可演示的垂直功能（如"用户认证"）。包含 1-7 个任务，每个阶段产出独立的 XML 任务计划。
• Task（任务）： 最小的工作单元，必须能在一个 200K token 的上下文窗口内完成。GSD 的铁律是：一个任务必须能放入一个上下文窗口。如果不能，就是两个任务。

在 v1 中，Slice 被称为 Phase（阶段）。在 v2 中，术语统一为 Slice（切片），但概念相同。

代码示例（查看 ROADMAP.md 的结构）：

cat .planning/ROADMAP.md

预期输出（示例内容）：

# Roadmap: Task Manager App v1.0

## Phase 01: User Authentication
- Status: complete
- Goal: Email/password signup, login, logout with JWT
- Depends on: None

## Phase 02: Task CRUD
- Status: in-progress
- Goal: Create, read, update, delete tasks with status tracking
- Depends on: Phase 01

## Phase 03: Task Categories & Filtering
- Status: pending
- Goal: Categorize tasks, filter by status/category/date
- Depends on: Phase 02

## Phase 04: Responsive UI Polish
- Status: pending
- Goal: Mobile-responsive layout, empty states, loading indicators
- Depends on: Phase 03

练习题： 1. 为一个"博客系统"项目设计一个简单的 3 阶段 ROADMAP，标注每个阶段的依赖关系。 2. 思考：为什么 GSD 建议一个任务不能超过一个上下文窗口的容量？如果一个任务太大会出现什么问题？

1.5 GSD 核心工作流：Discuss -> Plan -> Execute -> Verify

概念讲解：

GSD v1 的核心工作流是一个 6 步循环：

New Project -> Discuss Phase -> Plan Phase -> Execute Phase -> Verify Work -> Ship

这五个步骤对应了软件开发的五个关键环节：

1. Discuss（讨论） -- 捕获你对实现方式的具体偏好（如使用哪个库、什么架构模式）
2. Plan（规划） -- 研究技术方案，生成 XML 任务计划并验证
3. Execute（执行） -- 在独立的上下文窗口中并行执行任务
4. Verify（验证） -- 自动和手动验证执行结果是否符合预期
5. Ship（交付） -- 创建 PR、打标签、归档

每完成一个阶段，回到 Discuss 步骤开始下一个阶段，直到所有阶段完成。

代码示例（完整的一个阶段工作流）：

# 步骤 1: 初始化项目（仅第一次需要）
/gsd:new-project

# 步骤 2: 讨论第 1 阶段的实现偏好
/gsd:discuss-phase 1

# 步骤 3: 规划第 1 阶段（自动研究 + 生成计划 + 验证）
/gsd:plan-phase 1

# 步骤 4: 执行第 1 阶段（并行波浪式执行）
/gsd:execute-phase 1

# 步骤 5: 验证第 1 阶段的工作成果
/gsd:verify-work 1

# 步骤 6: 交付（创建 PR，可选）
/gsd:ship 1

预期输出（执行 /gsd:execute-phase 1 后的终端输出示例）：

GSD Execute Phase 1: User Authentication
==========================================
Analyzing plan dependencies...
Found 3 plans with 2 dependency levels.

Wave 1 (parallel):
  - Plan 01-01: Create user model and database schema
  - Plan 01-02: Setup JWT authentication utilities

Wave 2 (depends on Wave 1):
  - Plan 01-03: Create login and registration endpoints

Executing Wave 1...
  [Executor A] Fresh 200K context window created
  [Executor A] Plan 01-01: Processing...
  [Executor B] Fresh 200K context window created
  [Executor B] Plan 01-02: Processing...
  [Executor A] Plan 01-01: Complete. Committed as abc123f
  [Executor B] Plan 01-02: Complete. Committed as def456g

Executing Wave 2...
  [Executor C] Fresh 200K context window created
  [Executor C] Plan 01-03: Processing...
  [Executor C] Plan 01-03: Complete. Committed as hij789k

Phase 1 execution complete. 3 atomic commits created.
Run /gsd:verify-work 1 to validate results.

练习题： 1. 按照核心工作流，为一个小型项目（如待办事项应用）编写每个步骤你预期会做什么。不需要实际执行，只需要描述每个步骤的输入和输出。 2. 思考：为什么 Discuss 阶段在 Plan 之前？跳过 Discuss 直接 Plan 会有什么风险？

第二部分：进阶篇

2.1 波浪执行（Wave Execution）

详细讲解：

波浪执行（Wave Execution）是 GSD 在执行阶段的核心优化策略。当一个阶段包含多个任务计划时，GSD 会分析任务之间的依赖关系，将它们分组为多个"波浪"（Wave）：

• 同一波浪内的任务相互独立，可以并行执行
• 不同波浪之间存在依赖关系，必须按顺序串行执行
• 每个任务在一个全新的 200K token 上下文窗口中执行

这种策略最大化了并行度以提升效率，同时保证了依赖关系的正确性。垂直切片（如"用户功能端到端"）比水平分层（如"所有模型"，然后"所有 API"）的并行化效果更好。

代码示例（波浪执行的实际过程）：

# 假设你的阶段有 5 个任务计划，依赖关系如下：
# Plan 01 和 Plan 02 相互独立
# Plan 03 依赖 Plan 01
# Plan 04 依赖 Plan 02
# Plan 05 依赖 Plan 03 和 Plan 04
#
# 执行命令
/gsd:execute-phase 3

预期输出：

GSD Execute Phase 3: Orders & Checkout
=======================================
Analyzing 5 plans with dependency graph...

WAVE 1 (parallel):
  Plan 03-01: User Model    [no dependencies]
  Plan 03-02: Product Model [no dependencies]

WAVE 2 (parallel, depends on Wave 1):
  Plan 03-03: Orders API    [depends on 03-01]
  Plan 03-04: Cart API      [depends on 03-02]

WAVE 3 (depends on Wave 2):
  Plan 03-05: Checkout UI   [depends on 03-03, 03-04]

--- Executing Wave 1 ---
  [Sub-agent A] 200K context -> Plan 03-01 -> commit a1b2c3f
  [Sub-agent B] 200K context -> Plan 03-02 -> commit d4e5f6g

--- Executing Wave 2 ---
  [Sub-agent C] 200K context -> Plan 03-03 -> commit g7h8i9j
  [Sub-agent D] 200K context -> Plan 03-04 -> commit k0l1m2n

--- Executing Wave 3 ---
  [Sub-agent E] 200K context -> Plan 03-05 -> commit o3p4q5r

Phase 3 complete. 5 atomic commits in 3 waves.

注意事项： - 任务粒度是关键：如果一个任务太大，无法在一个上下文窗口内完成，执行会失败或产出不完整的代码。确保每个 XML 任务计划的 action 部分足够聚焦。 - 并行执行的构建冲突：如果多个子代理同时触发构建工具（如 pre-commit hooks），可能出现锁争用。GSD v1.26+ 自动处理此问题——并行代理使用 --no-verify 提交，编排器在每个波浪结束后统一运行 hooks。如果使用旧版本，需要手动配置。 - 依赖声明必须准确：如果依赖关系声明错误（遗漏或多余），会导致执行顺序不当或并行度降低。在 Plan 阶段仔细审查依赖声明。

练习题： 1. 假设你有一个电商项目，包含以下任务：商品模型、用户模型、购物车 API、订单 API、结账 UI。请画出这些任务的依赖关系图，并标注哪些可以在同一波浪中并行执行。 2. 思考：为什么垂直切片（按功能）比水平分层（按技术层）的并行化效果更好？

2.2 原子 Git 提交（Atomic Git Commits）

详细讲解：

原子 Git 提交（Atomic Git Commits）是 GSD 的另一个核心实践。每个任务完成后，GSD 立即生成一个独立的、精确描述变更内容的 Git 提交。这意味着：

• 每个提交只包含一个任务的变更
• 提交消息精确描述了变更内容
• 支持 git bisect 精确定位故障任务
• 每个任务可以独立回滚
• 为 AI 在未来会话中提供清晰的项目历史

GSD 使用结构化的提交消息格式：<type>(<phase>): <description>

代码示例（查看 GSD 生成的 Git 历史）：

# 查看 GSD 执行后的 Git 提交历史
git log --oneline --graph

预期输出：

* o3p4q5r feat(03-05): implement checkout page with payment integration
* k0l1m2n feat(03-04): create cart API with add/remove/clear endpoints
* g7h8i9j feat(03-03): add orders API with status tracking
* d4e5f6g feat(03-02): create product model with Prisma schema
* a1b2c3f feat(03-01): add user model with authentication fields
* z9y8x7w docs(03): complete phase 3 planning and research
* ...

代码示例（回滚特定任务的提交）：

# 如果发现 Plan 03-03 有问题，可以精确回滚该任务
git revert g7h8i9j

# 或者使用 GSD 的安全回滚命令
/gsd:undo --plan 03-03

预期输出：

Revert "feat(03-03): add orders API with status tracking"

This reverts commit g7h8i9j, undoing the orders API implementation.
The revert is safe and only affects files changed in that commit.

注意事项： - 不要手动修改 GSD 的提交：GSD 的状态管理依赖提交历史的完整性。如果手动 amend 或 rebase GSD 的提交，可能导致状态不一致。 - 提交消息是上下文的一部分：GSD 在后续会话中会读取提交历史来恢复上下文。模糊或不准确的提交消息会降低恢复质量。 - 不要合并提交：保持每个任务的提交独立。如果需要合并，在 milestone 完成时使用 squash merge。

练习题： 1. 在你的项目中运行 git log --oneline，检查 GSD 生成的提交消息是否遵循了结构化格式。 2. 思考：原子提交如何帮助 git bisect 定位引入 bug 的具体任务？

2.3 模型配置与成本控制

详细讲解：

GSD 支持为不同类型的代理配置不同的 Claude 模型，以平衡质量和成本。GSD 预定义了四种模型配置文件（Model Profile）：

每个代理的角色说明：

• gsd-planner -- 规划代理，决定架构和任务拆分，使用最强模型
• gsd-executor -- 执行代理，编写代码，使用中等模型
• gsd-phase-researcher -- 研究代理，调查技术方案，使用轻量模型
• gsd-verifier -- 验证代理，检查执行结果，使用中等模型
• gsd-plan-checker -- 计划检查代理，验证计划的完整性

代码示例（切换模型配置）：

# 查看当前配置
/gsd:settings

预期输出（部分）：

Current Settings:
  mode: interactive
  granularity: standard
  model_profile: balanced

Agent Model Assignments:
  gsd-planner:            opus
  gsd-roadmapper:         sonnet
  gsd-executor:           sonnet
  gsd-phase-researcher:   sonnet
  gsd-verifier:           sonnet
  gsd-plan-checker:       sonnet

# 切换到 budget 模式以降低成本
/gsd:set-profile budget

预期输出：

Model profile updated to: budget
  gsd-planner:            sonnet
  gsd-roadmapper:         sonnet
  gsd-executor:           sonnet
  gsd-phase-researcher:   haiku
  gsd-verifier:           haiku
  gsd-plan-checker:       haiku

注意事项： - Token 消耗较高：GSD 的多代理编排意味着每个任务都需要独立的上下文窗口。多位用户报告了 4:1 的开销比——每写 1 个 token 的代码，需要 4 个 token 用于编排。推荐使用 Max 计划（$100-200/月）以获得充足的配额。 - budget 模式可能降低质量：使用 Haiku 模型进行研究和验证可能在复杂项目中遗漏细节。对于关键路径上的阶段，建议临时切换回 balanced 或 quality 模式。 - 非 Anthropic 提供商使用 inherit 模式：如果你通过 OpenRouter、本地模型等方式使用 Claude Code，设置为 inherit 模式可以避免意外的 API 成本。

练习题： 1. 使用 /gsd:settings 查看你当前的模型配置，然后尝试切换到 budget 模式，观察各代理模型的变化。 2. 思考：在什么情况下你应该临时切换到 quality 模式？给出一个具体的场景。

2.4 项目状态管理与会话恢复

详细讲解：

GSD 的一个关键能力是跨会话的状态持久化。当你关闭 Claude Code 会话后重新打开，GSD 可以通过读取磁盘上的状态文件恢复项目上下文。这依赖于 .planning/ 目录中的几个关键文件：

• STATE.md -- 记录当前位置、决策、阻塞项
• HANDOFF.json -- 结构化的会话交接数据（由 /gsd:pause-work 生成）
• ROADMAP.md -- 各阶段的完成状态

GSD 提供了多个命令来管理项目状态：

代码示例（会话恢复流程）：

# 场景：你昨天在 Phase 2 的规划阶段停止了工作
# 今天打开新的 Claude Code 会话

# 步骤 1: 查看当前进度
/gsd:progress

预期输出：

Project: Task Manager App v1.0
Milestone: v1.0 (4 phases)

Phase 01: User Authentication    [COMPLETE] ✓
Phase 02: Task CRUD              [IN PROGRESS]
  - Discuss: DONE
  - Plan: DONE (3 plans created)
  - Execute: IN PROGRESS (Wave 1 of 2 complete)
  - Verify: PENDING
Phase 03: Task Categories        [PENDING]
Phase 04: Responsive UI          [PENDING]

Next step: /gsd:execute-phase 2 (continue Wave 2)

# 步骤 2: 恢复完整上下文
/gsd:resume-work

预期输出：

Resuming work from last session...
Reading STATE.md... OK
Reading HANDOFF.json... OK
Reading ROADMAP.md... OK

Session restored:
  - Last activity: Phase 02 execution (Wave 1 complete)
  - Completed plans: 02-01 (task model), 02-02 (CRUD API)
  - Remaining plans: 02-03 (task status tracking)
  - Decisions made: Using Prisma for ORM, REST API pattern
  - Blockers: None

Ready to continue. Run /gsd:execute-phase 2 to resume.

注意事项： - 在阶段之间清理上下文：在完成一个阶段后，使用 /clear 命令清空 Claude Code 的上下文窗口。GSD 的设计基于干净上下文，在主会话中累积过多内容会降低质量。 - 不要手动编辑 STATE.md：STATE.md 由 GSD 自动维护。手动编辑可能导致状态不一致。如果 STATE.md 出了问题，使用 node gsd-tools.cjs state sync 重建。 - 每次结束会话时使用 pause-work：养成在结束工作前运行 /gsd:pause-work 的习惯。这会生成 HANDOFF.json 文件，使下次恢复更加精确。

练习题： 1. 模拟一个会话恢复场景：运行 /gsd:pause-work，然后关闭并重新打开 Claude Code，再运行 /gsd:resume-work，检查恢复的上下文是否完整。 2. 思考：为什么 GSD 要将状态持久化到磁盘文件而不是依赖上下文窗口中的历史对话？

第三部分：高级篇

3.1 已有代码库的棕地项目（Brownfield）工作流

详细讲解：

GSD 不仅适用于全新项目（绿地项目），也支持在已有代码库上工作（棕地项目）。对于棕地项目，GSD 提供了 /gsd:map-codebase 命令，通过 4 个并行代理分析现有代码库：

• Stack Mapper -- 识别技术栈，生成 codebase/STACK.md
• Arch Mapper -- 分析架构模式，生成 codebase/ARCHITECTURE.md
• Convention Mapper -- 提取编码约定，生成 codebase/CONVENTIONS.md
• Concern Mapper -- 标记关注点，生成 codebase/CONCERNS.md

映射完成后，再运行 /gsd:new-project，GSD 会基于已有代码的上下文来提问，重点关注你要"添加什么"而非"构建什么"。

代码示例（棕地项目启动流程）：

# 步骤 1: 映射现有代码库
/gsd:map-codebase

# 步骤 2: 初始化 GSD（问题会聚焦于你要添加的内容）
/gsd:new-project

# 步骤 3: 正常的工作流程
/gsd:discuss-phase 1
/gsd:plan-phase 1
/gsd:execute-phase 1

预期输出（/gsd:map-codebase 执行后）：

GSD Codebase Mapping
=====================
Spawning 4 parallel analysis agents...

[Stack Mapper]   Detected: Next.js 14, TypeScript, Prisma, Tailwind CSS
[Arch Mapper]    Pattern: App Router, Server Components, API Routes
[Convention Map] Found: ESLint config, Prettier, path aliases (@/)
[Concern Map]    Flagged: No error boundary, missing test coverage

Generated files:
  .planning/codebase/STACK.md        (tech stack inventory)
  .planning/codebase/ARCHITECTURE.md  (architectural patterns)
  .planning/codebase/CONVENTIONS.md   (coding standards)
  .planning/codebase/CONCERNS.md      (risk areas)

Run /gsd:new-project to initialize GSD on this codebase.

3.2 Quick 模式与自治模式

详细讲解：

并非所有任务都需要完整的工作流。GSD 提供了两种轻量模式：

Quick 模式（/gsd:quick）： 适用于小型任务（bug 修复、配置更改、小型重构），保留 GSD 的核心保证（原子提交、状态追踪）但跳过研究和规划的开销。

自治模式（/gsd:autonomous）： 自动运行剩余的所有阶段，实现"走开，回来看到完成的项目"。适合已经完成初始规划、只需执行剩余阶段的场景。

代码示例（Quick 模式）：

# 快速修复一个 bug
/gsd:quick
# 然后输入描述
> "Fix the login button not responding on mobile Safari"

预期输出：

GSD Quick Mode
===============
Task: Fix the login button not responding on mobile Safari

Analyzing codebase for related files...
Found: src/components/LoginButton.tsx, src/hooks/useAuth.ts

Spawning executor agent (fresh 200K context)...
  - Reading relevant files...
  - Diagnosing issue: touch event not handled on Safari
  - Applying fix: adding touchstart event listener

Committed as: x7y8z9w fix: add touchstart handler for Safari compatibility

Done. Run /gsd:verify-work to validate.

Quick 模式支持可选标志：

• --discuss -- 先收集你的偏好
• --research -- 执行前调查方案
• --full -- 添加计划检查和执行后验证

标志可组合使用：

/gsd:quick --discuss --research --full
> "Add dark mode toggle to settings page"

代码示例（自治模式）：

# 从第 2 阶段开始自动运行到第 4 阶段
/gsd:autonomous --from 2 --to 4

预期输出：

GSD Autonomous Mode
====================
Running phases 2 through 4 autonomously...

[Phase 02] Discussing... Planning... Executing... Verifying... ✓
[Phase 03] Discussing... Planning... Executing... Verifying... ✓
[Phase 04] Discussing... Planning... Executing... Verifying... ✓

All 3 phases completed autonomously.
  Total commits: 12
  Total tokens: ~890K
  Estimated cost: $4.20

Run /gsd:audit-milestone to verify everything.

注意事项： - 自治模式的风险：自治模式跳过人工交互，如果初始规划有误，错误会累积到后续阶段。建议在手动完成前 1-2 个阶段、确认规划质量后再使用自治模式。 - Quick 模式不适合大型任务：如果一个任务需要修改 5 个以上文件或涉及架构决策，应该使用完整工作流。 - 使用 /gsd:next 替代自治模式：如果你不确定下一步该做什么，/gsd:next 会自动检测当前状态并建议下一步操作。

3.3 性能优化与最佳实践

详细讲解：

在使用 GSD 时，以下优化策略可以帮助你获得最佳体验：

优化策略 1：在阶段之间清理上下文窗口

# 完成一个阶段后，清理上下文
/gsd:execute-phase 1
/clear                    # 清空 Claude Code 上下文窗口
/gsd:discuss-phase 2     # 在干净的上下文中继续

说明：GSD 的设计基于干净上下文。主会话中累积过多内容会触发上下文腐化，与不使用 GSD 一样。每个阶段之间使用 /clear 是保持质量的关键。

优化策略 2：使用细粒度阶段提升并行度

# 粗粒度（3 个阶段，并行度低）
# Phase 1: All models + All APIs
# Phase 2: All UI
# Phase 3: Testing

# 细粒度（6 个阶段，并行度高）
# Phase 1: User model + Auth API
# Phase 2: Task model + CRUD API
# Phase 3: User UI (login/register)
# Phase 4: Task UI (list/create/edit)
# Phase 5: Filtering & Search
# Phase 6: Polish & Testing

# 在 /gsd:new-project 时选择细粒度
# 或在 /gsd:settings 中设置

说明：将大阶段拆分为小的垂直切片可以增加波浪执行的并行度，减少总执行时间。GSD 的 granularity 设置控制自动切片的粗细程度。

优化策略 3：根据项目阶段调整模型配置

# 原型阶段：快速迭代，降低成本
/gsd:set-profile budget

# 核心功能开发：平衡质量和成本
/gsd:set-profile balanced

# 生产发布前的关键阶段：最大化质量
/gsd:set-profile quality

最佳实践总结：

1. 项目开始前准备详细描述：在运行 /gsd:new-project 之前，准备好项目的目标、目标用户、核心功能、技术约束和偏好。描述越详细，GSD 需要的后续追问越少。
2. 不要跳过 Discuss 阶段：Discuss 阶段花费 5-10 分钟，但可以节省后续数小时的来回修改。
3. 棕地项目先 map-codebase：在已有代码库上使用 GSD 时，先运行 /gsd:map-codebase，避免 AI 与现有代码模式冲突。
4. 使用 /gsd:next 而非猜测：不确定下一步时，运行 /gsd:next，它会自动检测状态并建议正确的下一步。
5. 定期运行 /gsd:progress：在长时间工作后，检查进度确保没有偏离计划。
6. 捕获灵感而非中断当前工作：使用 /gsd:add-todo 记录突发的想法，而不是中断当前阶段去处理它。

第四部分：实战项目

项目需求

构建一个"个人书签管理器"Web 应用，包含以下功能：

• 用户注册和登录（邮箱/密码）
• 添加、编辑、删除书签（URL、标题、标签）
• 按标签和日期筛选书签
• 搜索书签（标题和 URL）
• 响应式 Web 界面（支持桌面和移动端）

项目设计

技术栈： - 前端：Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui - 后端：Next.js API Routes - 数据库：SQLite via Prisma ORM - 认证：JWT（使用 jose 库）

架构： - App Router 模式（Next.js 14） - Server Components 用于数据展示 - API Routes 用于 CRUD 操作 - JWT httpOnly Cookie 用于认证

GSD 阶段划分： - Phase 01: 项目初始化 + 用户认证 - Phase 02: 书签 CRUD + 数据库模型 - Phase 03: 搜索和筛选功能 - Phase 04: UI 优化和响应式设计

完整实现步骤

以下是使用 GSD 从零构建此项目的完整流程，涵盖上下文工程、元提示、波浪执行和原子 Git 提交四个核心知识点。

步骤 1：项目初始化

# 创建 Next.js 项目
npx create-next-app@latest bookmark-manager \
  --typescript --tailwind --eslint --app --src-dir

# 进入项目目录
cd bookmark-manager

# 启动 Claude Code（跳过权限以支持子代理）
claude --dangerously-skip-permissions

# 在 Claude Code 中初始化 GSD
/gsd:new-project

预期输出（/gsd:new-project 交互过程）：

GSD New Project
================
I'll help you set up your project. Let me ask a few questions.

Q: What are you building?
A: A personal bookmark manager web app. Users can save, organize,
   search and filter bookmarks by tags and date.

Q: Who are the target users?
A: Individual users who want a self-hosted bookmark manager.

Q: What's your tech stack?
A: Next.js 14, TypeScript, Tailwind CSS, shadcn/ui, Prisma, SQLite, JWT

Q: What's in scope for v1?
A: User auth, bookmark CRUD, tag-based filtering, search, responsive UI

Q: What's out of scope for v1?
A: Social features, browser extension, import/export, API for third-party

[Research Phase] Spawning 4 parallel research agents...
  - Stack researcher: Investigating Next.js 14 + Prisma best practices
  - Features researcher: Analyzing bookmark manager feature patterns
  - Architecture researcher: Designing auth + CRUD architecture
  - Pitfalls researcher: Identifying common Next.js/Prisma issues

[Requirements Phase] Scoped 12 requirements across 4 phases.
[Roadmap Phase] Created 4-phase roadmap.

Files created:
  .planning/PROJECT.md
  .planning/REQUIREMENTS.md
  .planning/ROADMAP.md
  .planning/STATE.md
  .planning/config.json
  .planning/research/

Review the roadmap and approve to continue.

步骤 2：讨论第一阶段的实现偏好

/gsd:discuss-phase 1

预期输出：

GSD Discuss Phase 1: User Authentication
=========================================

I've identified these gray areas for Phase 1:

Q: Password hashing - bcrypt vs argon2?
A: bcrypt with cost factor 12

Q: Session management - JWT in httpOnly cookie vs session storage?
A: httpOnly cookie with 24-hour expiry

Q: Registration flow - email confirmation required?
A: No, simple signup for v1

Q: Password validation rules?
A: Minimum 8 characters, at least one number

Preferences saved to .planning/phases/01-user-auth/CONTEXT.md

步骤 3：规划第一阶段

/gsd:plan-phase 1

预期输出：

GSD Plan Phase 1: User Authentication
======================================

[Research] Investigating auth patterns for Next.js 14 + Prisma...

Generating plans...

Plan 01-01: User Model and Database Schema
  Files: prisma/schema.prisma, prisma/seed.ts
  Verify: npx prisma generate succeeds

Plan 01-02: Authentication Utilities
  Files: src/lib/auth.ts, src/lib/db.ts
  Verify: JWT sign/verify functions work correctly

Plan 01-03: Registration and Login Endpoints
  Files: src/app/api/auth/register/route.ts,
         src/app/api/auth/login/route.ts,
         src/app/api/auth/logout/route.ts
  Verify: curl registration returns 201,
          curl login returns 200 + Set-Cookie

[Plan Checker] All 3 plans verified against requirements. ✓

Plans saved to .planning/phases/01-user-auth/

步骤 4：执行第一阶段（波浪执行）

/gsd:execute-phase 1

预期输出：

GSD Execute Phase 1: User Authentication
=========================================
Analyzing dependencies among 3 plans...

WAVE 1 (parallel):
  Plan 01-01: User Model and Database Schema
  Plan 01-02: Authentication Utilities

WAVE 2 (depends on Wave 1):
  Plan 01-03: Registration and Login Endpoints

--- Wave 1 ---
  [Sub-agent A] Fresh 200K context -> Plan 01-01
  [Sub-agent B] Fresh 200K context -> Plan 01-02

  Plan 01-01: ✓ Complete (commit abc123f)
  Plan 01-02: ✓ Complete (commit def456g)

--- Wave 2 ---
  [Sub-agent C] Fresh 200K context -> Plan 01-03

  Plan 01-03: ✓ Complete (commit hij789k)

Phase 1 executed. 3 commits created.
Run /gsd:verify-work 1 to validate.

步骤 5：验证并继续

# 验证第一阶段
/gsd:verify-work 1

# 清理上下文
/clear

# 继续后续阶段
/gsd:discuss-phase 2
/gsd:plan-phase 2
/gsd:execute-phase 2
/gsd:verify-work 2
/clear

/gsd:discuss-phase 3
/gsd:plan-phase 3
/gsd:execute-phase 3
/gsd:verify-work 3
/clear

/gsd:discuss-phase 4
/gsd:plan-phase 4
/gsd:execute-phase 4
/gsd:verify-work 4

# 完成里程碑
/gsd:audit-milestone
/gsd:complete-milestone

代码解析

以上实战项目综合运用了以下知识点：

1. 上下文工程（Context Engineering）：在 /gsd:new-project 中，GSD 创建了 PROJECT.md、REQUIREMENTS.md、ROADMAP.md 和 STATE.md 等文件。每次执行 /clear 后，GSD 的子代理通过读取这些文件获取完整的项目上下文，无需依赖历史对话。这确保了从 Phase 01 到 Phase 04 的每个阶段都在干净、完整的上下文中执行。

2. 元提示（Meta-Prompting）：在 /gsd:plan-phase 中，GSD 生成了 XML 格式的任务计划。每个计划包含精确的文件路径、约束条件（如"使用 jose 而非 jsonwebtoken"）和可验证的完成标准（如"curl login returns 200 + Set-Cookie"）。这些结构化的元提示确保 AI 代理不会猜测或做出假设。

3. 波浪执行（Wave Execution）：在 /gsd:execute-phase 1 中，GSD 分析了 3 个计划的依赖关系，将无依赖的 Plan 01-01 和 Plan 01-02 放入 Wave 1 并行执行，将依赖前两者的 Plan 01-03 放入 Wave 2。这最大化了执行效率。

4. 原子 Git 提交（Atomic Git Commits）：每个计划完成后生成独立的提交（abc123f、def456g、hij789k），每个提交只包含一个任务的变更。如果 Plan 01-03 的认证端点有问题，可以通过 git revert hij789k 精确回滚，不影响其他任务。

扩展挑战

1. 添加浏览器扩展集成：在完成 Web 应用后，规划一个新的 Milestone（v1.1），包含浏览器扩展功能。使用 /gsd:new-milestone 开始规划，并设计 Chrome Extension 的上下文文件和任务计划。
2. 实现导入/导出功能：使用 /gsd:quick --research 快速调研书签导入/导出的技术方案（如 Chrome Bookmarks HTML 格式解析），然后实现完整功能。
3. 添加 API Key 认证：为第三方集成添加 API Key 认证机制。使用 /gsd:insert-phase 3 在搜索功能和 UI 优化之间插入新阶段，设计 API Key 的生成、验证和权限控制。

第五部分：常见问题与排查指南

常见错误及解决方案

调试技巧

1. 使用 /gsd:forensics 诊断工作流故障：当工作流以不明确的方式失败时（如计划引用不存在的文件、执行产出意外结果、状态似乎损坏），运行 /gsd:forensics 生成诊断报告。它会检查 Git 历史异常、规划文件完整性和状态一致性，输出到 .planning/forensics/ 目录。

2. 使用 /gsd:debug 进行系统性调试：当项目出现 bug 时，使用 /gsd:debug "描述问题" 启动结构化调试会话。GSD 会创建持久化的调试状态（.planning/debug/），跨会话追踪问题。添加 --diagnose 标志可以仅分析不修复。

3. 检查上下文利用率：如果输出质量下降，首先检查当前会话的上下文利用率。GSD 的 hooks 默认启用上下文警告（hooks.context_warnings: true），当利用率超过阈值时会提醒你。解决方法是使用 /clear 清空上下文，然后通过 /gsd:resume-work 恢复。

第六部分：学习路线推荐

官方文档推荐阅读顺序

1. README 快速入门 -- 重点：安装命令、核心工作流的 6 个步骤。这是最快上手的方式。

2. 来源：GitHub README

3. USER-GUIDE.md 命令参考 -- 重点：完整的命令列表、配置参考、故障排除。当你需要查找特定命令的用法时回来查阅。

4. 来源：docs/USER-GUIDE.md

5. CHANGELOG.md -- 重点：了解每个版本的新增功能和修复。特别是在遇到问题时，检查是否为已知问题。

6. 来源：CHANGELOG.md

7. CONTRIBUTING.md -- 重点：如果你打算为 GSD 贡献代码或自定义扩展，了解贡献指南和代码规范。

8. 来源：CONTRIBUTING.md

9. GSD v2 文档（如适用） -- 重点：v2 的架构文档、ADR（架构决策记录）、开发者文档。适用于需要深度定制或理解内部机制的高级用户。

10. 来源：gsd-build/gsd-2 docs/

推荐进阶资源

• GSD 交互式教程 - ccforeveryone.com -- 一个交互式的在线课程，通过实际操作教授 GSD 框架的核心概念。适合喜欢动手实践的学习者。

• "I Created GSD For Claude Code. This Is How I Use It." - YouTube -- GSD 创建者 Lex Christopherson 的深度演示视频，展示了他本人如何使用 GSD 框架。提供了第一手的使用哲学和实践技巧。

• Beating context rot in Claude Code with GSD - The New Stack -- 技术媒体对 GSD 如何解决上下文腐化问题的深度分析文章，包含技术原理讲解和实际案例分析。

• GSD Discord 社区 -- 活跃的社区讨论，可以通过 /gsd:join-discord 命令加入。社区中有大量经验分享、工作流技巧和问题解答。

• GSD 官方网站 - gsd.build -- 官方网站包含最新的功能介绍、案例研究和版本更新信息。

信息来源与版本说明

• 教程基于版本： GSD v1.35.0（稳定版），参考了 v2（gsd-pi，截至 v2.71.0）的部分信息
• 信息获取日期： 2026-04-12
• 代码示例来源： XML 任务计划格式和命令示例基于官方文档 v1.35.0（USER-GUIDE.md）；初学者指南参考了 dev.to 文章
• 信息来源列表：
• GitHub - gsd-build/get-shit-done (v1)
• USER-GUIDE.md
• npm - get-shit-done-cc
• dev.to - The Complete Beginner's Guide to GSD
• Medium - GET SH*T DONE: Meta-prompting and Spec-driven Development
• GSD 交互式教程 - ccforeveryone.com