GSD2 - 完整学习教程
GSD2 - 完整学习教程
教程级别： 从零到一 预计学习时间： 3-4 小时 前置知识： 命令行基本操作（cd、ls、npm、git）、了解 AI 编码代理的基本概念（知道什么是 LLM、API 密钥）、Git 基础操作（commit、branch、merge）、对软件项目结构有基本概念
环境搭建指南
系统要求
- 操作系统：macOS / Linux / Windows（WSL2）
- Node.js：18.x 及以上
- npm：9.x 及以上
- Git：2.x 及以上（需要 worktree 支持）
- AI 模型 API 密钥：至少一个提供商（推荐 Anthropic Claude）
- 磁盘空间：约 200MB（Node.js 模块 + 项目文件）
安装步骤
第一步：检查前置依赖
# 检查 Node.js 版本
node --version
# 需要 v18.x 及以上
# 检查 npm 版本
npm --version
# 需要 9.x 及以上
# 检查 Git 版本（需要 worktree 支持）
git --version
# 需要 2.x 及以上
第二步：安装 GSD2 CLI
# 全局安装 GSD2 CLI
npm install -g gsd-pi@latest
# 验证安装
gsd --version
# 预期输出: 2.71.x（或更高版本）
第三步：配置 AI 模型提供商
# GSD2 支持 20+ 模型提供商
# 推荐：Anthropic Claude（最常用，质量最高）
# 设置 Anthropic API 密钥
export ANTHROPIC_API_KEY="your-anthropic-api-key"
# 可选：设置其他提供商密钥（用于回退或多模型策略）
export OPENAI_API_KEY="your-openai-api-key"
export GOOGLE_API_KEY="your-google-api-key"
# 持久化环境变量（添加到 shell 配置文件）
echo 'export ANTHROPIC_API_KEY="your-key"' >> ~/.zshrc
source ~/.zshrc
第四步：验证完整安装
# 创建一个测试项目
mkdir ~/gsd2-test && cd ~/gsd2-test
git init
# 初始化 GSD2
gsd init
# 查看生成的配置
ls -la .gsd/
# 预期输出:
# .gsd/
# ├── config.yaml # GSD2 配置文件
# ├── STATE.md # 全局状态文件
# └── ...
# 查看 GSD2 帮助
gsd --help
# 显示所有可用命令
基于 GSD2 GitHub README 安装指南
第一部分：入门篇
1.1 第一次使用：Step 模式逐步执行
概念讲解：
GSD2 有两种执行模式：Step 模式（逐步执行，每步暂停等待审查）和 Auto 模式（全自动状态机）。对于初次使用者，建议从 Step 模式开始，逐步理解 GSD2 的工作流程。
GSD2 的核心工作流程是：
1. 初始化：gsd init 创建项目配置和 .gsd/ 目录
2. 规划：GSD2 分析你的项目描述，生成里程碑、切片和任务的分解
3. 执行：每个任务在全新的 200K token 上下文中执行
4. 验证：每个任务完成后进行验证
5. 合并：变更合并回主分支
代码示例：
# 基于 GSD2 GitHub README 和 dev.to 入门指南
# 创建项目目录
mkdir ~/my-first-gsd-project && cd ~/my-first-gsd-project
git init
# 初始化 GSD2
gsd init
# GSD2 会提示输入项目描述
# 输入项目描述（示例）
# "Build a simple REST API with Express.js that has:
# - User registration and login with JWT authentication
# - CRUD operations for a 'todos' resource
# - SQLite database with proper migrations
# - Input validation and error handling
# - Basic unit tests for all endpoints"
执行结果：
# GSD2 Step 模式的典型执行过程（模拟输出）
$ gsd init
✓ Initialized GSD2 in /Users/you/my-first-gsd-project
✓ Created .gsd/ directory
✓ Generated config.yaml
$ gsd start --mode step
[Planning Phase]
Analyzing project description...
Generating project specification...
Milestone 1: Foundation & Database
Slice 1.1: Project Setup
Task 1.1.1: Initialize Express.js project with TypeScript
Task 1.1.2: Set up SQLite database and migration system
Slice 1.2: User Authentication
Task 1.2.1: Create User model and database schema
Task 1.2.2: Implement JWT authentication middleware
Task 1.2.3: Build registration and login endpoints
Milestone 2: Todo CRUD & Validation
Slice 2.1: Todo Resource
Task 2.1.1: Create Todo model and schema
Task 2.1.2: Implement CRUD endpoints with validation
Slice 2.2: Testing
Task 2.2.1: Write unit tests for auth endpoints
Task 2.2.2: Write unit tests for todo endpoints
Execute Task 1.1.1? [Y/n] Y
[Task 1.1.1: Initialize Express.js project]
Creating fresh context (200K tokens)...
Loading artifacts: project spec, roadmap excerpt...
Executing...
✓ Task completed
Files created:
- package.json
- tsconfig.json
- src/index.ts
- src/app.ts
Verify and continue to next task? [Y/n] Y
以上输出为模拟结果，基于 GSD2 GitHub README 的工作流程描述和 dev.to 入门指南。
练习题： 1. 修改项目描述，尝试生成不同复杂度的项目（如只有一个简单的 TODO API），观察 GSD2 如何调整任务分解。 2. 在 Step 模式中，审查每个任务的输出后再继续，感受 GSD2 的逐步控制能力。
1.2 理解三级分解：里程碑、切片和任务
概念讲解：
GSD2 将项目分解为三个层级：里程碑（Milestone）→ 切片（Slice）→ 任务（Task）。这是 GSD2 最核心的组织结构。
- 里程碑：项目的重大阶段，可独立验证，运行在独立的 Git worktree 中
- 切片：里程碑内的功能分组，提供上下文边界
- 任务：最小可执行单元，每个任务适配一个 200K token 上下文窗口（铁律）
理解这个结构对于有效使用 GSD2 至关重要，因为它决定了 GSD2 如何分配工作、管理上下文和组织代码变更。
代码示例：
# 基于 GSD2 GitHub README
# 查看当前项目的分解结构
cd ~/my-first-gsd-project
cat .gsd/ROADMAP.md
# 查看当前状态
cat .gsd/STATE.md
# 显示当前活跃的里程碑、正在执行的切片和任务状态
# 查看特定里程碑的详情
ls .gsd/milestones/
# 每个里程碑目录包含该里程碑下的所有切片和任务文件
执行结果：
# .gsd/ROADMAP.md 的典型内容（模拟输出）
# Project Roadmap
## Milestone 1: Foundation & Database
- Status: IN_PROGRESS
- Branch: milestone/M001
### Slice 1.1: Project Setup
- Status: COMPLETED
- Tasks:
- [DONE] Task 1.1.1: Initialize Express.js project
- [DONE] Task 1.1.2: Set up SQLite database
### Slice 1.2: User Authentication
- Status: IN_PROGRESS
- Tasks:
- [DONE] Task 1.2.1: User model and schema
- [ACTIVE] Task 1.2.2: JWT authentication middleware
- [PENDING] Task 1.2.3: Registration and login endpoints
## Milestone 2: Todo CRUD & Validation
- Status: PENDING
...
以上输出为模拟结果，基于 GSD2 的规格文件结构。
注意事项： - 每个里程碑运行在独立的 Git worktree 中，互不干扰 - 任务是 GSD2 执行的最小单元，不可再分 - 如果一个任务太大无法适配一个上下文窗口，GSD2 会在规划阶段自动将其进一步拆分
练习题：
1. 手动查看 .gsd/ 目录下的所有文件，理解 GSD2 如何持久化项目状态。
2. 尝试创建一个更复杂的项目描述，观察 GSD2 如何调整里程碑和切片的划分。
第二部分：进阶篇
2.1 使用 Auto 模式实现全自动开发
概念讲解：
Auto 模式是 GSD2 的核心能力——完整的全自动状态机。系统从规划到执行、验证、合并、重新规划，全部自主完成。你需要做的是写一个清晰的项目描述，然后让 GSD2 自主完成整个开发过程。
Auto 模式的状态机流程：planning → ready → executing → verifying → merging → replanning，循环直到所有里程碑完成。系统内置卡住检测、超时监督和自适应重新规划，确保长时间运行的可靠性。
代码示例：
# 基于 GSD2 GitHub README 和 dev.to 入门指南
# 创建一个新项目
mkdir ~/auto-demo && cd ~/auto-demo
git init
# 初始化 GSD2
gsd init
# 以 Auto 模式启动（全自动执行）
gsd start --mode auto
# GSD2 将自主完成以下步骤：
# 1. 分析项目描述
# 2. 生成里程碑/切片/任务分解
# 3. 逐任务执行（每个任务全新上下文）
# 4. 自动验证每个任务
# 5. 合并到主分支
# 6. 自适应重新规划
# 7. 循环直到完成
执行结果：
# Auto 模式的典型输出（模拟输出）
$ gsd start --mode auto
[GSD2 Auto Mode v2.71]
Project: Express.js REST API
[Phase: Planning]
Analyzing project description... ✓
Generating milestones... ✓
→ Milestone 1: Foundation (3 slices, 7 tasks)
→ Milestone 2: Features (2 slices, 5 tasks)
Generating ROADMAP.md... ✓
[Phase: Execution]
Starting Milestone 1 in worktree milestone/M001...
Task 1.1.1: Initialize project [executing]
Context: 200K tokens, 12K artifacts loaded
... ✓ completed (verified)
Task 1.1.2: Database setup [executing]
Context: 200K tokens, 15K artifacts loaded
... ✓ completed (verified)
Task 1.2.1: User model [executing]
Context: 200K tokens, 18K artifacts loaded
... ✓ completed (verified)
...
[Phase: Merging Milestone 1]
Squash merging milestone/M001 → main... ✓
Worktree cleaned up.
[Phase: Replanning]
Reviewing execution results... ✓
Adjusting Milestone 2 plan... ✓
[Phase: Execution]
Starting Milestone 2 in worktree milestone/M002...
...
[Complete]
All milestones completed.
Total tasks: 12
Total cost: $8.45
Duration: 47 minutes
以上输出为模拟结果，基于 GSD2 GitHub README 的 Auto 模式描述。
注意事项： - Auto 模式启动后不需要人工干预，但建议在初次使用时关注前几个任务的输出质量 - 如果发现某个任务输出质量不佳，可以 Ctrl+C 中断，然后用 Step 模式继续 - 确保在启动 Auto 模式前配置好足够的 API 密钥余额 - Auto 模式的 token 消耗约是直接使用 Claude Code 的 4 倍，注意控制成本
练习题：
1. 用 Auto 模式运行一个简单项目（5-10 个文件），观察完整的自动执行过程。
2. 在 Auto 模式运行过程中，手动检查 .gsd/STATE.md 的变化，理解状态机的推进。
2.2 配置每阶段模型选择和 Token 优化
概念讲解：
GSD2 最大的成本优化杠杆是为不同阶段选择不同的 AI 模型。研究阶段可以用较便宜的模型，执行阶段使用最强模型。配合 token 优化配置（budget/balanced/quality），可以精细控制成本和质量之间的平衡。
这是 GSD2 区别于直接使用 Claude Code 的关键优势之一——不是所有任务都需要最贵的模型。
代码示例：
# 基于 GSD2 GitHub README
# 编辑 GSD2 配置文件
cat .gsd/config.yaml
# .gsd/config.yaml 的典型配置
# 模型选择策略
models:
# 规划阶段：使用中等能力模型
planning:
primary: "claude-sonnet-4-20250514"
fallback: "gpt-4o"
# 研究阶段：使用较便宜的模型
research:
primary: "gpt-4o"
fallback: "claude-3.5-sonnet"
# 执行阶段：使用最强模型
execution:
primary: "claude-sonnet-4-20250514"
# 验证阶段：使用中等能力模型
verification:
primary: "claude-sonnet-4-20250514"
fallback: "gpt-4o"
# Token 优化配置
# budget: 40-60% 节省（跳过研究，最小验证）
# balanced: 10-20% 节省（标准流程，部分压缩）
# quality: 0% 节省（完整研究+验证）
token_profile: "balanced"
# 成本控制
max_cost_per_milestone: 15.00 # 每个里程碑最大成本（美元）
# 应用配置后启动
gsd start --mode auto
# 运行完成后查看成本报告
gsd status --cost
执行结果：
# 成本报告（模拟输出）
$ gsd status --cost
Cost Report
===========
Milestone 1: $4.23
- Research: $0.45 (gpt-4o)
- Planning: $0.38 (claude-sonnet)
- Execution: $2.85 (claude-sonnet)
- Verification: $0.55 (claude-sonnet)
Milestone 2: $3.78
- Research: $0.32 (gpt-4o)
- Planning: $0.28 (claude-sonnet)
- Execution: $2.65 (claude-sonnet)
- Verification: $0.53 (claude-sonnet)
Total: $8.01
Token usage: 1.2M input, 180K output
Savings vs. quality profile: ~22% (balanced)
以上输出为模拟结果，基于 GSD2 的成本追踪功能描述。
注意事项：
- budget 配置虽然节省最多，但跳过研究阶段可能导致执行代理对项目背景理解不足
- 研究阶段使用较便宜的模型（如 gpt-4o）通常够用，因为研究不需要代码生成能力
- 执行阶段建议始终使用最强模型，这是代码质量的关键保障
- 设置 max_cost_per_milestone 可以防止单个里程碑的成本失控
练习题： 1. 分别使用 budget 和 quality 配置运行同一项目，对比成本和代码质量差异。 2. 尝试将研究阶段的模型换成更便宜的选项（如 claude-3.5-sonnet），观察对整体质量的影响。
2.3 理解崩溃恢复和 Worktree 隔离
概念讲解：
GSD2 的崩溃恢复能力是它区别于直接使用 Claude Code 的关键优势之一。当系统崩溃或中断后，GSD2 能从上一个检查点精确恢复继续执行，而不需要从头开始。
这得益于 GSD2 的两个核心设计：
1. 文件持久化状态：所有状态存储在 .gsd/STATE.md，不依赖内存
2. Git Worktree 隔离：每个里程碑在独立 worktree 中运行，失败可干净回滚
代码示例：
# 基于 GSD2 GitHub README
# 模拟崩溃恢复场景
cd ~/auto-demo
# 假设 Auto 模式在执行中崩溃（Ctrl+C 或网络中断）
# 查看当前状态
cat .gsd/STATE.md
# 显示最后完成的状态
# 重新启动 GSD2（它将自动恢复）
gsd start --mode auto
# GSD2 会：
# 1. 读取 STATE.md 找到最后的安全检查点
# 2. 进行会话取证分析不完整的工作
# 3. 从断点继续执行
# 查看所有里程碑的 worktree
git worktree list
# 显示所有活跃的 worktree
# /path/to/project abc1234 [main]
# /path/to/project/.gsd/worktrees/M001 def5678 [milestone/M001]
# 手动回滚某个里程碑（如果需要）
git worktree remove .gsd/worktrees/M001 --force
git branch -D milestone/M001
# 里程碑 M001 的所有变更被丢弃，主分支不受影响
执行结果：
# 崩溃恢复的典型输出（模拟输出）
$ gsd start --mode auto
[GSD2 Auto Mode v2.71]
Detected previous session (crashed or interrupted)
Performing session forensics...
Last completed task: Task 1.2.1
Incomplete task: Task 1.2.2 (partial changes detected)
Safe resume point: Task 1.2.2 (re-execute)
Resuming from Task 1.2.2...
Reverting partial changes in worktree milestone/M001...
Starting fresh context for Task 1.2.2...
Task 1.2.2: JWT authentication middleware [executing]
Context: 200K tokens, 18K artifacts loaded
... ✓ completed (verified)
Continuing from Task 1.2.3...
...
以上输出为模拟结果，基于 GSD2 的崩溃恢复机制描述。
注意事项：
- 不要手动修改 .gsd/STATE.md，除非你完全理解其格式
- 如果崩溃发生在 Git 操作中（如 merge），可能需要手动清理 worktree 状态
- 无头模式下的自动重启使用指数退避：5s → 10s → 30s 上限
- 提供商错误（如 API 限流）会自动等待后重试：速率限制 60s，服务器错误 30s
练习题：
1. 在 Auto 模式执行过程中故意 Ctrl+C 中断，然后重新启动，验证恢复能力。
2. 查看 .gsd/ 目录下的文件结构，理解状态持久化的方式。
第三部分：高级篇
3.1 Headless 模式和 CI/CD 集成
概念讲解：
GSD2 的 Headless 模式支持非交互式运行，返回 JSON 格式的状态、下一步操作和成本明细。这使得 GSD2 可以集成到 CI/CD 流水线中，实现自动化代码生成和验证。
Headless 模式不启动交互式界面，而是通过命令行参数控制执行，输出结构化 JSON 供下游工具消费。
代码示例：
# 基于 GSD2 GitHub README docs/commands.md
# Headless 模式执行单个任务
gsd start --mode headless --task-next
# 输出 JSON 格式的状态报告
{
"status": "task_completed",
"task": {
"id": "1.2.2",
"name": "JWT authentication middleware",
"milestone": "M001",
"slice": "S1.2"
},
"next_action": {
"type": "execute_task",
"task_id": "1.2.3",
"task_name": "Registration and login endpoints"
},
"cost": {
"input_tokens": 45000,
"output_tokens": 8500,
"estimated_cost_usd": 0.42
},
"files_changed": [
"src/middleware/auth.ts",
"src/utils/jwt.ts"
],
"verification": {
"status": "passed",
"tests_run": 5,
"tests_passed": 5
}
}
# CI/CD 集成示例（GitHub Actions）
# 在 .github/workflows/gsd.yml 中配置
# .github/workflows/gsd.yml
name: GSD2 Auto Development
on:
issues:
types: [labeled]
jobs:
develop:
if: contains(github.event.label.name, 'gsd-auto')
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
- name: Install GSD2
run: npm install -g gsd-pi@latest
- name: Run GSD2 Headless
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
gsd start --mode headless --max-cost 10.00
- name: Create Pull Request
uses: peter-evans/create-pull-request@v6
with:
title: "GSD2: Automated development"
body: "Auto-generated by GSD2"
注意事项：
- Headless 模式下没有人工干预，确保项目描述足够清晰
- 设置 --max-cost 参数防止成本失控
- 建议在 CI 中先运行 Step 模式的第一个任务验证质量，再切换到 Headless
3.2 MCP Server 模式
概念讲解：
GSD2 可以作为 MCP（Model Context Protocol）服务器运行，暴露工具接口供外部 AI 客户端调用。这使得其他 AI 工具（如 Claude Code、Cursor 等）可以直接调用 GSD2 的能力。
代码示例：
# 基于 GSD2 GitHub README docs/commands.md
# 启动 MCP Server 模式
gsd --mode mcp
# GSD2 将通过 MCP 协议暴露以下工具：
# - gsd_init: 初始化项目
# - gsd_plan: 执行规划
# - gsd_execute: 执行任务
# - gsd_verify: 验证任务
# - gsd_status: 查询状态
# - gsd_cost: 查询成本
# 在 Claude Code 中使用 MCP 模式
# 在 Claude Code 的 MCP 配置中添加 GSD2 作为 MCP 服务器
注意事项： - MCP Server 模式适合需要将 GSD2 能力集成到其他工具链的场景 - 对于大多数用户，直接使用 CLI 的 Step 或 Auto 模式更为简单
3.3 最佳实践与避坑指南
最佳实践：
-
写清晰详细的项目描述：GSD2 的输出质量直接取决于输入的项目描述质量。描述应包含：技术栈、功能需求、非功能性需求（性能、安全）、项目结构偏好。模糊的描述会导致模糊的代码。
-
从 Step 模式开始：初次使用 GSD2 时，先用 Step 模式运行几个任务，确认输出质量满足预期后再切换到 Auto 模式。这避免了 Auto 模式下低质量输出持续累积。
-
使用 balanced 配置作为起点：budget 配置节省成本但可能牺牲质量，quality 配置成本较高。balanced 是大多数项目的最佳平衡点。
-
设置成本上限：始终设置
max_cost_per_milestone，防止单个里程碑的成本失控。特别是在 Auto 模式下，没有成本上限可能导致意外的高额账单。 -
利用 Git Worktree 隔离：不同里程碑在独立 worktree 中执行。如果某个里程碑方向错误，可以直接丢弃整个 worktree 而不影响主分支。这比在单分支上回滚更干净。
常见陷阱（来自 dev.to 社区反馈）：
- Token 消耗是直接使用 Claude Code 的 4 倍：GSD2 的每任务全新上下文带来了质量优势，但重复加载上下文工件的成本不可忽视。对小型项目不划算。
- Pro 计划可能不够：长时间 Auto 模式运行可能消耗大量 API 额度。建议使用按量计费的 API 而非订阅计划。
- 模糊的项目描述导致问题：如果项目描述过于模糊，GSD2 的规划可能偏离预期，导致后续所有任务都在错误方向上工作。
第四部分：实战项目
项目需求
使用 GSD2 自动开发一个"个人博客系统"，综合运用以下知识点： 1. Step 模式逐步执行（知识点 1.1）：从初始化到逐步执行 2. 三级分解理解（知识点 1.2）：理解 GSD2 的项目分解 3. Auto 模式全自动开发（知识点 2.1）：全自动完成剩余开发 4. 模型选择和 Token 优化（知识点 2.2）：配置成本优化策略 5. 崩溃恢复（知识点 2.3）：验证恢复能力
功能要求： - Next.js 14 前端（App Router + TypeScript） - Markdown 文件作为内容源（无数据库） - 文章列表页、文章详情页、关于页面 - 响应式设计（Tailwind CSS） - SEO 优化（meta 标签、Open Graph） - RSS 订阅功能
项目设计
personal-blog/
│
├── .gsd/
│ ├── config.yaml # GSD2 配置
│ ├── STATE.md # 全局状态
│ ├── PROJECT.md # 项目规格
│ ├── REQUIREMENTS.md # 需求规格
│ ├── ROADMAP.md # 路线图
│ └── milestones/ # 里程碑文件
│
├── src/
│ ├── app/
│ │ ├── layout.tsx # 根布局
│ │ ├── page.tsx # 首页（文章列表）
│ │ ├── posts/
│ │ │ └── [slug]/
│ │ │ └── page.tsx # 文章详情
│ │ ├── about/
│ │ │ └── page.tsx # 关于页面
│ │ └── feed.xml/
│ │ └── route.ts # RSS 路由
│ ├── components/
│ │ ├── Header.tsx
│ │ ├── Footer.tsx
│ │ ├── PostCard.tsx
│ │ └── SEO.tsx
│ └── lib/
│ ├── markdown.ts # Markdown 解析
│ └── rss.ts # RSS 生成
│
├── content/
│ └── posts/ # Markdown 文章
│ ├── hello-world.md
│ └── getting-started.md
│
└── public/ # 静态资源
完整实施步骤
第一步：初始化项目
#!/bin/bash
# 基于 GSD2 GitHub README
# 创建项目
mkdir ~/personal-blog && cd ~/personal-blog
git init
# 安装 GSD2（如果尚未安装）
npm install -g gsd-pi@latest
# 初始化 GSD2
gsd init
第二步：编写项目描述
Build a personal blog system with the following specifications:
## Tech Stack
- Next.js 14 (App Router, TypeScript)
- Tailwind CSS for styling
- Markdown files as content source (gray-matter + remark)
- No database required
## Features
1. Home page: List of recent blog posts with title, date, excerpt, and reading time
2. Post detail page: Full article with Markdown rendering, code syntax highlighting
3. About page: Static content about the author
4. RSS feed: XML feed at /feed.xml for RSS subscribers
5. SEO: Meta tags, Open Graph tags, structured data for each post
6. Responsive design: Mobile-first, works on all screen sizes
## Content Structure
- Blog posts stored as Markdown files in /content/posts/
- Each post has frontmatter: title, date, excerpt, tags
- Code blocks with syntax highlighting (using rehype-highlight)
## Non-Functional Requirements
- Static site generation (SSG) for all pages
- Lighthouse score > 90 for all categories
- Zero runtime dependencies for content (all build-time)
- Accessible (WCAG 2.1 AA compliance)
第三步：配置模型选择和 Token 优化
# .gsd/config.yaml
models:
research:
primary: "gpt-4o"
fallback: "claude-3.5-sonnet"
planning:
primary: "claude-sonnet-4-20250514"
fallback: "gpt-4o"
execution:
primary: "claude-sonnet-4-20250514"
verification:
primary: "claude-sonnet-4-20250514"
fallback: "gpt-4o"
token_profile: "balanced"
max_cost_per_milestone: 10.00
第四步：先用 Step 模式验证质量，再切 Auto 模式
# 基于 dev.to 入门指南的推荐工作流
# 第一步：用 Step 模式执行前两个任务，验证质量
gsd start --mode step
# 审查 Task 1.1.1 和 Task 1.1.2 的输出
# 确认代码风格和架构方向正确
# 第二步：质量满意后，切换到 Auto 模式
gsd start --mode auto
# GSD2 自动从 STATE.md 读取进度，继续执行
# 第三步：运行中故意中断（Ctrl+C），验证崩溃恢复
# 重新启动
gsd start --mode auto
# 观察是否正确恢复
# 第四步：完成后验证
cd ~/personal-blog
npm run build
# 预期: Build succeeded
npm run dev
# 在浏览器中检查所有页面
代码解析
知识点运用说明：
-
Step 模式逐步执行（1.1 节）：先用 Step 模式执行前几个任务，审查代码风格和架构方向。这避免了 Auto 模式下低质量输出持续累积的风险。
-
三级分解理解（1.2 节）：博客系统被分解为两个里程碑——M1（基础框架 + 布局）和 M2（功能实现 + SEO）。每个里程碑在独立 worktree 中运行。
-
Auto 模式全自动开发（2.1 节）：质量验证通过后切换到 Auto 模式，让 GSD2 自主完成剩余任务。状态机自动管理规划→执行→验证→合并→重新规划的循环。
-
模型选择和 Token 优化（2.2 节）：研究阶段使用 gpt-4o（便宜），执行阶段使用 claude-sonnet（最强），balanced 配置在成本和质量间取得平衡。设置 $10/里程碑的成本上限。
-
崩溃恢复（2.3 节）：故意中断并重启，验证 GSD2 能从断点精确恢复。文件持久化状态和会话取证确保不丢失进度。
扩展挑战
-
添加评论系统：在项目描述中增加评论功能（使用 GitHub Issues 作为后端），观察 GSD2 如何处理与外部 API 集成的新需求。
-
国际化支持：在 CLAUDE.md 中添加 i18n 约束（中英文双语支持），观察 GSD2 如何在后续任务中遵守这些约束。
-
部署到 Vercel：使用 GSD2 Headless 模式配合 GitHub Actions，实现 push 后自动部署。
第五部分：常见问题与排查指南
常见错误及解决方案
| 错误信息 | 原因 | 解决方案 |
|---|---|---|
ANTHROPIC_API_KEY not set |
Anthropic API 密钥未配置 | 在 ~/.zshrc 中设置 export ANTHROPIC_API_KEY="..."，然后 source ~/.zshrc |
gsd: command not found |
GSD2 未正确安装或不在 PATH 中 | 运行 npm install -g gsd-pi@latest，检查 npm 全局 bin 目录是否在 PATH 中 |
Git worktree creation failed |
Git 版本过旧或仓库状态不干净 | 更新 Git 到 2.x+；确保没有未提交的变更（git stash 或 git commit） |
Rate limit exceeded (429) |
API 调用频率超出限制 | GSD2 会自动等待 60s 后重试。如果持续发生，考虑降低并发或更换模型提供商 |
Context window exceeded |
任务过大，超出 200K token 限制 | GSD2 应在规划阶段自动拆分。如果仍然发生，简化项目描述或将大里程碑拆分为更小的 |
Milestone merge conflict |
主分支和 worktree 分支有冲突 | 手动解决冲突后重新合并。或丢弃 worktree 重新开始该里程碑 |
STATE.md corrupted |
状态文件被意外修改 | 检查 .gsd/STATE.md 的格式。如果无法修复，可能需要重新 gsd init（会丢失进度） |
Budget exceeded |
里程碑成本超出设置的上限 | 检查 max_cost_per_milestone 设置。考虑增大预算或切换到 budget token 配置 |
Stuck in loop (A→B→A→B) |
卡住检测已触发但无法自动解决 | 手动 Ctrl+C 中断，查看 .gsd/ 中的任务状态。可能需要调整项目描述或手动完成该任务 |
基于 GSD2 GitHub README 和 dev.to 入门指南的常见问题
调试技巧
-
利用 STATE.md 追踪进度：
.gsd/STATE.md记录了完整的执行状态。当 Auto 模式出现问题时，首先查看此文件了解系统当前处于状态机的哪个阶段。 -
检查 Worktree 中的代码：每个里程碑在独立 worktree 中执行。直接进入
.gsd/worktrees/M001/查看生成的代码，可以在合并到主分支前发现问题。 -
成本报告分析：使用
gsd status --cost查看详细的成本分解。如果某个阶段成本异常高，可能是任务过大或模型选择不当。针对性调整 token 配置或模型选择。
第六部分：学习路线推荐
官方文档推荐阅读顺序
- GitHub README 快速入门 — 安装、初始化、基本命令
- 地址：https://github.com/gsd-build/gsd-2#readme
-
重点：Step 模式和 Auto 模式的使用方式、命令参考
-
docs/auto-mode.md — Auto 模式状态机的完整文档
- 地址：https://github.com/gsd-build/gsd-2/blob/main/docs/auto-mode.md
-
重点：状态机管道、崩溃恢复、超时监督、卡住检测
-
docs/commands.md — 完整命令参考
- 地址：https://github.com/gsd-build/gsd-2/blob/main/docs/commands.md
-
重点：Headless 模式、MCP Server 模式、状态管理命令
-
config.yaml 配置说明 — 模型选择和 Token 优化
- 地址：https://github.com/gsd-build/gsd-2#configuration
- 重点：每阶段模型选择、token 优化配置、成本控制
推荐进阶资源
- dev.to - GSD2 A Beginner's Guide to Spec-Driven AI Coding
- https://dev.to/nikolay_bailey/gsd2-a-beginners-guide-to-spec-driven-ai-coding-4h5k
-
完整的入门教程，包含工作流程、常见陷阱和与其他框架的对比
-
Medium - Superpowers, GSD, and gstack Framework Comparison
-
框架对比分析，帮助理解 GSD2 在 AI 编码工具生态中的定位
-
Menon Lab - Solving Context Rot
- 深度技术分析，包含 SWE-AF 基准测试和多框架对比
进阶方向建议
完成本教程后，建议按以下方向深入学习：
-
GSD2 高级配置：深入学习每阶段模型选择的最优策略、Reactive Execution 的 DAG 调度、自定义扩展和子代理的使用。这能帮助你根据项目特点精细调优 GSD2 的行为。
-
CI/CD 集成：学习 Headless 模式和 MCP Server 模式的高级用法，将 GSD2 集成到团队的开发流程中。实现从需求到代码的全自动化。
-
与其他 AI 编码框架的对比实践：在同一个项目上分别使用 GSD2、BMAD 和 Superpowers，对比输出质量、成本和开发体验。这能帮助你为不同项目选择最合适的工具。
信息来源与版本说明
- 教程基于版本： GSD2 v2.71（npm 包 gsd-pi）
- 信息获取日期： 2026-04-13
- 信息来源列表：
- GitHub 仓库 gsd-build/gsd-2 — 源码、README、架构文档、命令参考
- GitHub API - gsd-build/gsd-2 — 项目元数据
- dev.to - GSD2 A Beginner's Guide to Spec-Driven AI Coding — 完整教程、常见陷阱
- Medium - Superpowers, GSD, and gstack Comparison — 框架对比
- Menon Lab - Solving Context Rot — 技术深度分析