---
created: "2026-03-20 10:00"
type: resource
tags: [claude-code, AI-tools, methodology, best-practices, project-management, gsd]
source: "https://github.com/gsd-build/get-shit-done"
---

# GSD (Get Shit Done) 方法论与最佳实践

GSD 是一个面向 AI 编码 Agent 的**元提示、上下文工程和规格驱动开发框架**。36K+ GitHub stars，支持 Claude Code、OpenCode、Gemini CLI、Codex、Copilot、Antigravity 六种运行时。

> **命名空间**: 所有 GSD 命令以 `gsd:` 为前缀（如 `/gsd:plan-phase`），无需额外插件命名空间。

---

## 一、核心设计哲学

**"复杂性在系统中，不在你的工作流中。"** GSD 将上下文工程、XML 提示格式化、子 Agent 编排和状态管理隐藏在几个简单命令后面。

**五大设计原则**:

| 原则 | 说明 |
|------|------|
| **Fresh Context Per Agent** | 每个子 Agent 获得全新 200K token 上下文窗口，消除"上下文腐烂" |
| **Thin Orchestrators** | 工作流文件只做加载上下文、生成 Agent、收集结果、路由下一步 |
| **File-Based State** | 所有状态存在 `.planning/` 目录下的 Markdown 和 JSON 中，无数据库 |
| **Absent = Enabled** | 配置默认为 true，用户显式禁用而非启用 |
| **Defense in Depth** | 计划执行前验证、每任务原子提交、执行后验证、UAT 人类门控 |

**上下文腐烂模型**:

```
Claude 质量随上下文使用率变化:
  0-30%  → 峰值质量（GSD 编排器保持在此范围）
  30-50% → 良好质量
  50-70% → 开始赶工，质量下降
  70%+   → 幻觉风险显著增加
```

GSD 的核心竞争力: 为每个任务生成全新 200K 上下文窗口，从根本上避免上下文腐烂。

---

## 二、项目层级结构

```
Project (项目)
  └── Milestone (里程碑 v1.0, v2.0...)
       └── Phase (阶段 1, 2, 3...)
            └── Plan (计划 A, B, C...)
                 └── Task (任务 1, 2, 3...)
```

**核心文档**:

| 文档 | 位置 | 用途 |
|------|------|------|
| **PROJECT.md** | `.planning/` | 项目愿景、约束、关键决策 |
| **REQUIREMENTS.md** | `.planning/` | 带唯一 ID (REQ-XX) 的需求列表 |
| **ROADMAP.md** | `.planning/` | 阶段分解 + 状态追踪 + 需求可追溯 |
| **STATE.md** | `.planning/` | 活跃记忆: 当前位置、决策、阻塞、指标（<100行）|
| **CONTEXT.md** | 每阶段目录 | 用户在 discuss-phase 中做的决策 |
| **RESEARCH.md** | 每阶段目录 | 领域研究发现 |
| **PLAN.md** | 每计划目录 | XML 结构的原子任务列表（这是提示词，不是文档）|
| **SUMMARY.md** | 每计划目录 | 执行结果、文件变更、偏差记录 |
| **VERIFICATION.md** | 每阶段目录 | 目标回溯验证报告 |
| **config.json** | `.planning/` | 工作流配置（模式、粒度、模型、git 等）|

---

## 三、核心工作流

### 完整生命周期

```
/gsd:new-project              → 提问 → 研究 → 需求 → 路线图
  │
  ▼ (对每个阶段)
/gsd:discuss-phase N          → 捕获用户偏好 → CONTEXT.md
/gsd:plan-phase N             → 研究 → 计划 → 计划检查循环 → PLAN.md
/gsd:execute-phase N          → 波浪式并行执行 → 原子提交
/gsd:verify-work N            → 目标回溯验证 → VERIFICATION.md
/gsd:validate-phase N         → Nyquist 验证 → 补充测试
/gsd:ship N                   → 创建 PR
  │
  ▼ (所有阶段完成后)
/gsd:audit-milestone          → 审计里程碑完成度
/gsd:complete-milestone       → 归档、打 tag
/gsd:new-milestone            → 开始下一个版本
```

**自动推进**: `/gsd:next` 自动检测项目状态，运行下一个逻辑步骤。

**快速模式**: `/gsd:quick` 对临时任务提供 GSD 保证（原子提交、状态追踪）但跳过完整规划。可组合标志: `--discuss`, `--research`, `--full`。

### 例子 — 完整新项目流程

```bash
# Step 1: 初始化项目
/gsd:new-project
# Claude 以协作思考方式提问（不是需求收集）:
#   "你在构建什么？解决什么问题？"
#   "目标用户是谁？'完成'长什么样？"
#   "有技术栈偏好吗？"
# → 4 个研究 Agent 并行启动:
#   Researcher 1: 技术栈调研
#   Researcher 2: 功能特性调研
#   Researcher 3: 架构模式调研
#   Researcher 4: 常见陷阱调研
# → 合成器汇总为 SUMMARY.md
# → 生成 PROJECT.md, REQUIREMENTS.md, ROADMAP.md

# Step 2: 讨论第一阶段
/gsd:discuss-phase 1
# Claude 提问直到理解你的偏好:
#   "数据库用 PostgreSQL 还是 SQLite？"
#   "认证用 JWT 还是 Session？"
#   "需要邮件验证吗？"
# → 你的决策锁定在 CONTEXT.md 中（后续不可变）

# Step 3: 规划
/gsd:plan-phase 1
# → gsd-phase-researcher 调研实现方案 → RESEARCH.md
# → gsd-planner 生成 2-3 个 PLAN.md（每个 ≤50% 上下文预算）
# → gsd-plan-checker 目标回溯验证（最多 3 次迭代）:
#     "这些计划能实现阶段目标吗？"
#     "CONTEXT.md 中的决策都被尊重了吗？"
#     "每个 REQ-XX 都有对应任务吗？"

# Step 4: 执行
/gsd:execute-phase 1
# → 按依赖分组为波浪（wave）
# → Wave 1: Plan A + Plan B（独立，并行执行）
# → Wave 2: Plan C（依赖 A+B，等待完成后执行）
# → 每个任务: 原子 git 提交
# → 每个 executor 获得全新 200K 上下文

# Step 5: 验证
/gsd:verify-work 1
# → gsd-verifier 不信任 SUMMARY.md 的声称
# → 检查实际代码:
#     Exists: 文件在预期路径？
#     Substantive: 是真实实现还是桩代码？
#     Wired: 与系统其他部分连接了吗？
# → 生成 VERIFICATION.md（通过/差距/建议）

# Step 6: Nyquist 验证
/gsd:validate-phase 1
# → 扫描每个 REQ-XX 是否有对应自动化测试
# → COVERED / PARTIAL / MISSING 分类
# → gsd-nyquist-auditor 生成缺失的测试（只改测试文件，不改实现）

# Step 7: 发布
/gsd:ship 1
# → 创建 PR，附带验证报告
```

---

## 四、Agent 系统 (16 个)

每个 Agent 是 Markdown 文件 + YAML frontmatter（name, description, tools, color）。由瘦编排器生成，每个获得全新上下文窗口。

### Agent 清单

| Agent | 角色 | 并行度 |
|-------|------|--------|
| **gsd-project-researcher** | 项目级领域研究 | 4x 并行（栈/功能/架构/陷阱）|
| **gsd-research-synthesizer** | 合并 4 个研究输出为 SUMMARY.md | 在研究者之后串行 |
| **gsd-roadmapper** | 从需求创建阶段化路线图 | 串行 |
| **gsd-phase-researcher** | 调研特定阶段的实现方案 | 串行 |
| **gsd-planner** | 创建 PLAN.md（XML 任务结构）| 串行 |
| **gsd-plan-checker** | 执行前目标回溯验证（最多 3 次迭代）| 串行循环 |
| **gsd-executor** | 执行 PLAN.md，每任务原子提交 | 波浪内并行 |
| **gsd-verifier** | 执行后目标回溯验证 | 串行 |
| **gsd-debugger** | 科学方法 Bug 调查，跨会话持久状态 | 串行/交互 |
| **gsd-codebase-mapper** | 棕地分析 | 4x 并行（技术/架构/质量/关注点）|
| **gsd-integration-checker** | 跨阶段集成验证 | 串行 |
| **gsd-nyquist-auditor** | 为验证缺口生成测试，从不修改实现 | 串行 |
| **gsd-ui-researcher** | 生成 UI-SPEC.md 设计契约 | 串行 |
| **gsd-ui-checker** | 验证 UI-SPEC 完整性（6 维度）| 串行 |
| **gsd-ui-auditor** | 6 支柱视觉审计 | 串行 |
| **gsd-user-profiler** | 8 维度行为分析 | 串行 |

**关键模式**: 每个 Agent 接收 `<files_to_read>` 块，**必须**在任何操作前读取所有列出的文件。这是主要的上下文注入机制。

### 模型路由

| Agent | quality | balanced | budget |
|-------|---------|----------|--------|
| gsd-planner | Opus | Opus | Sonnet |
| gsd-executor | Opus | Sonnet | Sonnet |
| gsd-verifier | Sonnet | Sonnet | Haiku |
| gsd-debugger | Opus | Sonnet | Sonnet |
| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku |
| gsd-plan-checker | Sonnet | Sonnet | Haiku |
| gsd-phase-researcher | Sonnet | Sonnet | Haiku |

`inherit` 配置文件用于非 Anthropic 供应商（OpenRouter、本地模型）。

### 例子 — Plan 作为 Prompt

PLAN.md 不是文档——它**就是** prompt。XML 结构直接指导 executor:

```xml
<!-- .planning/phases/01-auth/plans/A/PLAN.md -->
---
phase: 1
plan: A
goal: "Implement user registration with email verification"
requirements: [REQ-01, REQ-02]
depends_on: []
---

<task id="1" type="auto">
  <action>
    Create User model with fields: id, email, passwordHash, verified, createdAt.
    Use Prisma schema. Add unique constraint on email.
  </action>
  <verify>
    Run: npx prisma validate
    Check: prisma/schema.prisma contains User model with all fields
  </verify>
  <done>prisma/schema.prisma updated with User model</done>
</task>

<task id="2" type="auto" depends="1">
  <action>
    Create POST /api/auth/register endpoint.
    Validate input with zod schema (email format, password min 8 chars).
    Hash password with bcrypt (12 rounds).
    Send verification email via SendGrid.
    Return 201 with user ID.
  </action>
  <verify>
    Run: npm test -- --grep "register"
    Check: tests pass, endpoint returns 201 for valid input
  </verify>
  <done>src/routes/auth/register.ts created and tested</done>
</task>

<task id="3" type="human-verify" depends="2">
  <action>
    User confirms: registration endpoint works via manual test
  </action>
  <done>User verified registration flow works end-to-end</done>
</task>
```

---

## 五、五大核心方法论

### 1. Dream Extraction（梦想提取）

项目初始化使用"协作思考"而非"需求收集"。

```
传统方式:
  产品经理: "请列出你的需求"
  开发者: "我需要用户认证、支付..."

GSD 方式:
  Claude: "你在构建什么？解决什么真实问题？"
  开发者: "我想让自由职业者更容易管理发票..."
  Claude: "当你说'更容易'——现在最痛苦的部分是什么？"
  开发者: "手动追踪哪些发票已付款、哪些逾期"
  Claude: "所以核心价值是自动追踪支付状态。
           '完成'对你来说长什么样？"
  → 从模糊想法中提取出具体的、可执行的需求
```

**原则**: "你是思考伙伴，不是采访者。" 系统探测模糊性、让抽象变具体。

### 2. Goal-Backward Verification（目标回溯验证）

GSD 的核心验证哲学: **"任务完成 ≠ 目标达成"**。从应该交付的东西开始，反向验证它是否真实存在。

**四级验证**:

```
Level 1 - Exists:     文件在预期路径？
Level 2 - Substantive: 是真实实现还是桩代码/占位符？
Level 3 - Wired:      与系统其他部分连接了？（import 被使用、API 被调用、数据流通）
Level 4 - Functional:  实际调用时能工作？（通常需要人类验证）
```

**桩代码检测模式**:

```
React 组件:
  ❌ return <div>TODO</div>
  ❌ return <Placeholder />
  ✓ return <form onSubmit={handleSubmit}>...</form>

API 路由:
  ❌ res.json({ message: "not implemented" })
  ❌ throw new Error("TODO")
  ✓ const user = await db.user.create(...)

数据库 Schema:
  ❌ 只有 id 和 createdAt 字段
  ✓ 包含所有业务字段 + 索引 + 约束
```

**应用层级**:

| 阶段 | 验证者 | 问的问题 |
|------|--------|---------|
| 执行前 | gsd-plan-checker | 计划能**交付**目标吗？|
| 执行后 | gsd-verifier | 执行**达成**了目标吗？|
| 跨阶段 | gsd-integration-checker | 阶段之间**连接**正确吗？|
| 最终 | 人类 UAT | 它真的**能用**吗？|

### 例子 — 验证报告

```markdown
# VERIFICATION.md — Phase 1: User Authentication

## Goal
Users can register, login, and access protected routes.

## Observable Truths (从用户角度)
1. New user can register with email + password
2. Registered user can login and receive JWT
3. Protected routes reject unauthenticated requests
4. Protected routes accept valid JWT

## Verification Results

| Truth | Exists | Substantive | Wired | Status |
|-------|--------|-------------|-------|--------|
| Registration | ✅ POST /auth/register | ✅ Real bcrypt + DB write | ✅ Called from signup form | PASS |
| Login | ✅ POST /auth/login | ✅ Password compare + JWT sign | ✅ Called from login form | PASS |
| Route protection | ✅ authMiddleware.ts | ✅ JWT verify + user lookup | ⚠️ Not applied to /api/admin/* | GAP |
| JWT validation | ✅ Token generation | ✅ RS256 signing | ✅ Middleware uses it | PASS |

## Gaps
1. **GAP-01**: authMiddleware not applied to admin routes
   - Severity: HIGH
   - Fix: Add middleware to admin router in src/routes/admin/index.ts

## Verdict: PARTIAL PASS (3/4 truths verified, 1 gap)
```

### 3. Nyquist Validation（奈奎斯特验证）

命名来自信号处理的**奈奎斯特采样定理**: 要忠实重建信号，采样率需要 2x 以上。类比: 要忠实验证实现，每个需求都需要对应的自动化测试反馈。

```
原则: AI 生成器越自主，验证、可追溯性和回滚的投资就越大

需求 REQ-01 → 必须有自动化测试覆盖
需求 REQ-02 → 必须有自动化测试覆盖
...
```

**缺口分类**:

| 分类 | 含义 |
|------|------|
| COVERED | 测试存在、覆盖行为、运行通过 |
| PARTIAL | 测试存在但失败或不完整 |
| MISSING | 没有找到测试 |

**例子 — Nyquist 验证报告**:

```markdown
# VALIDATION.md — Phase 1

## Coverage Matrix

| Requirement | Test File | Status | Notes |
|-------------|-----------|--------|-------|
| REQ-01: User registration | tests/auth/register.test.ts | COVERED | 5 test cases |
| REQ-02: Email verification | tests/auth/verify-email.test.ts | COVERED | 3 test cases |
| REQ-03: Login flow | tests/auth/login.test.ts | COVERED | 4 test cases |
| REQ-04: Password reset | — | MISSING | No test file found |
| REQ-05: Rate limiting | tests/middleware/rate-limit.test.ts | PARTIAL | Only tests 429 status, not cooldown |

## Actions Taken
- Generated: tests/auth/password-reset.test.ts (4 test cases for REQ-04)
- Extended: tests/middleware/rate-limit.test.ts (added cooldown verification for REQ-05)

## Result: 5/5 COVERED (was 3/5 before audit)
```

**关键约束**: gsd-nyquist-auditor **从不修改实现代码** — 只创建/修改测试文件和 VALIDATION.md。实现 Bug 被上报而非修复。

### 4. Wave Execution（波浪式执行）

计划按依赖关系分组为"波浪"，波浪内并行执行，波浪间串行。

```
Phase 1 有 4 个计划:
  Plan A: 数据库 Schema     (无依赖)
  Plan B: API 框架          (无依赖)
  Plan C: 认证路由          (依赖 A + B)
  Plan D: 前端登录页        (依赖 C)

执行:
  Wave 1: [Plan A, Plan B]  ← 并行（2 个独立 executor，各自全新 200K 上下文）
  Wave 2: [Plan C]          ← 等 Wave 1 完成后执行
  Wave 3: [Plan D]          ← 等 Wave 2 完成后执行

编排器上下文使用: 仅 30-40%（瘦编排器模式）
执行器上下文使用: 每个 0-50%（全新窗口，最佳质量区间）
```

**并行安全**: 并行执行器使用 `--no-verify` 避免 pre-commit hook 锁竞争。编排器在每个波浪完成后统一运行 hooks。

**STATE.md 文件锁**: 使用 `O_EXCL` 原子创建 `STATE.md.lock` 防止并行写入竞争。

### 5. Checkpoint System（检查点系统）

形式化的人机交互点:

| 类型 | 频率 | 含义 |
|------|------|------|
| **human-verify** | 90% | Claude 自动化完成，人类确认结果可用 |
| **decision** | ~8% | 用户在选项中做选择，Claude 实施 |
| **human-action** | ~2% | 需要人类判断的事（认证、视觉检查、秘钥配置）|

**黄金法则**: "如果 Claude 能运行，Claude 就运行。" 检查点只用于验证和决策。

**Auto-mode**: 自动跳过 human-verify 和 decision 检查点，但**永不**跳过 human-action。

### 例子 — 检查点交互

```
# executor 遇到 human-verify 检查点:
┌────────────────────────────────────────┐
│ CHECKPOINT: human-verify               │
│                                        │
│ Task 3 of Plan A completed.            │
│ Created: src/routes/auth/register.ts   │
│                                        │
│ Please verify:                         │
│ 1. POST /api/auth/register returns 201 │
│ 2. User appears in database            │
│ 3. Verification email received         │
│                                        │
│ [Continue] [Fix Issues] [Skip]         │
└────────────────────────────────────────┘

# executor 遇到 decision 检查点:
┌────────────────────────────────────────┐
│ CHECKPOINT: decision                   │
│                                        │
│ JWT token expiry strategy:             │
│ A) Short-lived (15min) + refresh token │
│ B) Long-lived (7 days), no refresh     │
│ C) Session-based, no JWT               │
│                                        │
│ Your choice: [A/B/C]                   │
└────────────────────────────────────────┘

# executor 遇到 human-action 检查点:
┌────────────────────────────────────────┐
│ CHECKPOINT: human-action               │
│                                        │
│ I need you to:                         │
│ 1. Create a SendGrid account           │
│ 2. Generate an API key                 │
│ 3. Set SENDGRID_API_KEY in .env        │
│                                        │
│ [Done, continue]                       │
└────────────────────────────────────────┘
```

---

## 六、状态管理与会话持续性

### STATE.md — 项目短期记忆

```markdown
# Project State

**Phase:** 2 of 5
**Plan:** B of 3
**Status:** executing
**Velocity:** 1.2 plans/hour
**Last Session:** 2026-03-20 09:30

## Recent Decisions
- REQ-03: Use JWT with refresh tokens (user choice)
- Database: PostgreSQL via Prisma (CONTEXT.md)

## Blockers
- None

## Pending Todos
- [ ] Add rate limiting to payment endpoints
- [ ] Review admin panel permissions
```

### 会话暂停/恢复

```bash
# 暂停工作（保存完整状态）
/gsd:pause-work
# → 生成 HANDOFF.json (机器可读):
#    {
#      "current_task": "Plan B, Task 2",
#      "completed": ["Plan A (all tasks)", "Plan B Task 1"],
#      "remaining": ["Plan B Task 2-3", "Plan C"],
#      "decisions": [...],
#      "blockers": [],
#      "uncommitted_files": ["src/api/payment.ts"]
#    }
# → 生成 .continue-here.md (人类可读):
#    "你在做 Phase 2 Plan B 的第 2 个任务..."

# 恢复工作（在新会话中）
/gsd:resume-work
# → 读 HANDOFF.json → 重建上下文 → 从断点继续
# → 如果 HANDOFF.json 丢失 → 回退到 .continue-here.md
# → 如果都丢失 → 从 artifacts 重建
```

### 上下文监控 Hook

```
Context Monitor（PostToolUse hook）:
  ≤35% 剩余 → WARNING: "请准备收尾当前任务"
  ≤25% 剩余 → CRITICAL: "立即保存状态，执行 /gsd:pause-work"
  防抖: 每 5 次工具调用之间最多 1 次警告
  严重度升级时绕过防抖
```

---

## 七、Git 集成

**核心原则**: "提交结果，不是过程。"

| 事件 | 提交？ |
|------|--------|
| 项目初始化（brief + roadmap）| YES |
| PLAN.md / RESEARCH.md 创建 | NO（中间产物）|
| 每个任务完成 | YES（原子提交）|
| 计划完成（元数据更新）| YES |
| 暂停/恢复 | YES（WIP）|

**提交格式**: `{type}({phase}-{plan}): {description}`

```
feat(1-A): add User model with Prisma schema
feat(1-A): implement POST /auth/register endpoint
test(1-A): add registration flow tests
feat(1-B): add JWT authentication middleware
fix(1-C): apply auth middleware to admin routes
```

**分支策略**:

| 策略 | 说明 | 适用场景 |
|------|------|---------|
| `none` | 提交到当前分支（默认）| 个人项目 |
| `phase` | 每阶段一个分支 | 需要阶段级 PR 审查 |
| `milestone` | 每里程碑一个分支 | 需要版本级 PR 审查 |

---

## 八、配置系统

### config.json 完整配置

```json
{
  "mode": "interactive",          // interactive | yolo
  "granularity": "standard",      // coarse | standard | fine
  "model_profile": "balanced",    // quality | balanced | budget | inherit
  "workflow": {
    "research": true,             // 执行前研究
    "plan_check": true,           // 计划质量验证
    "verifier": true,             // 执行后验证
    "auto_advance": false,        // 自动推进到下一阶段
    "nyquist_validation": true    // 奈奎斯特测试验证
  },
  "planning": {
    "commit_docs": true,          // 提交规划文档
    "search_gitignored": false    // 搜索 gitignored 文件
  },
  "parallelization": {
    "enabled": true,
    "plan_level": true,           // 计划级并行
    "task_level": false,          // 任务级并行（默认关闭）
    "max_concurrent_agents": 3,
    "min_plans_for_parallel": 2
  },
  "gates": {
    "confirm_project": true,      // 确认项目初始化
    "confirm_phases": true,       // 确认阶段划分
    "confirm_roadmap": true,      // 确认路线图
    "confirm_plan": true,         // 确认计划
    "execute_next_plan": true     // 确认执行下一计划
  },
  "safety": {
    "always_confirm_destructive": true,
    "always_confirm_external_services": true
  },
  "git": {
    "branching_strategy": "none"  // none | phase | milestone
  }
}
```

**配置层级**: 项目 `.planning/config.json` > 全局 `~/.gsd/defaults.json` > 内置默认值

---

## 九、命令速查（37+ 个）

### 核心工作流

| 命令 | 用途 |
|------|------|
| `/gsd:new-project` | 初始化新项目（提问 → 研究 → 需求 → 路线图）|
| `/gsd:discuss-phase N` | 讨论阶段偏好（→ CONTEXT.md）|
| `/gsd:plan-phase N` | 规划阶段（研究 → 计划 → 验证循环）|
| `/gsd:execute-phase N` | 波浪式并行执行所有计划 |
| `/gsd:verify-work N` | 目标回溯验证 |
| `/gsd:validate-phase N` | Nyquist 测试覆盖验证 |
| `/gsd:ship N` | 创建 PR |
| `/gsd:next` | 自动推进到下一步 |
| `/gsd:quick "描述"` | 快速任务（跳过完整规划）|
| `/gsd:autonomous` | 自主运行所有剩余阶段 |

### 阶段管理

| 命令 | 用途 |
|------|------|
| `/gsd:add-phase "描述"` | 添加新阶段到路线图末尾 |
| `/gsd:insert-phase N "描述"` | 在 N 后插入小数阶段（如 2.1）|
| `/gsd:remove-phase N` | 移除阶段并重新编号 |
| `/gsd:list-phase-assumptions N` | 列出 Claude 对阶段的假设 |

### 里程碑管理

| 命令 | 用途 |
|------|------|
| `/gsd:audit-milestone` | 审计里程碑完成度 |
| `/gsd:complete-milestone` | 归档里程碑，打 tag |
| `/gsd:new-milestone` | 开始新版本 |
| `/gsd:plan-milestone-gaps` | 为审计发现的缺口创建补充阶段 |

### 会话与导航

| 命令 | 用途 |
|------|------|
| `/gsd:pause-work` | 暂停并保存完整状态 |
| `/gsd:resume-work` | 从断点恢复 |
| `/gsd:progress` | 查看当前进度 |
| `/gsd:stats` | 显示项目统计 |
| `/gsd:session-report` | 生成会话报告（token、工作摘要）|

### 分析与调试

| 命令 | 用途 |
|------|------|
| `/gsd:map-codebase` | 分析现有代码库（棕地项目必用）|
| `/gsd:debug` | 科学方法 Bug 调查 |
| `/gsd:health` | 项目健康检查 |

### 杂项

| 命令 | 用途 |
|------|------|
| `/gsd:settings` | 配置 GSD |
| `/gsd:set-profile` | 切换模型配置文件 |
| `/gsd:add-todo` | 捕获想法为 todo |
| `/gsd:check-todos` | 查看待办事项 |
| `/gsd:note` | 零摩擦笔记捕获 |
| `/gsd:do "文本"` | 路由自由文本到正确的 GSD 命令 |
| `/gsd:help` | 显示帮助 |
| `/gsd:update` | 更新 GSD 框架 |

---

## 十、社区最佳实践

### 开始之前

1. **准备详细的项目描述**: 包括目标、用户、核心功能、约束、技术栈偏好。模糊描述会触发过多追问。
2. **棕地项目必须先跑 `/gsd:map-codebase`**: 避免与现有模式冲突。
3. **预算充足**: Max plan ($100-200/月) 是常规使用的推荐。GSD 的多 Agent 架构消耗 token 较高。

### 工作中

4. **永远不要跳过 `/gsd:discuss-phase`**: 花 5-10 分钟在这里可以节省数小时。大多数计划质量问题源于 Claude 在 CONTEXT.md 中缺少用户决策。
5. **计划保持 2-3 个任务**: 每个适配 ~50% 的全新上下文窗口。更大的任务超出单个上下文窗口能可靠产出的范围。
6. **小任务用 `/gsd:quick`**: 完整工作流对修错别字、改颜色等小事是大材小用。
7. **用 `/gsd:add-todo` 捕获灵感**: 而不是打断当前工作。
8. **用 `/gsd:progress` 检查位置**: 随时了解当前在哪、下一步做什么。
9. **阶段间清理上下文**: 保持编排器在 30-40% 使用率的最佳区间。

### 验证

10. **启用 Nyquist 验证**: 在代码写之前就映射测试覆盖到每个需求，确保秒级反馈循环。
11. **不要信任 SUMMARY.md**: 验证器会检查实际代码而非声称。
12. **视觉规格优于纯文本规格**: 带热点的屏幕截图 mockup 比纯文字描述产出更好的结果。

---

## 十一、常见陷阱

| 陷阱 | 影响 | 解决方案 |
|------|------|---------|
| 小改动用完整工作流 | 浪费时间和 token | 用 `/gsd:quick` |
| 跳过 discuss-phase | 计划基于 Claude 的假设而非你的决策 | 始终先 `/gsd:discuss-phase` |
| 计划任务过多 | 超出单个上下文窗口能力 | 限制 2-3 任务/计划 |
| Token 预算耗尽 | 工作中断 | 预算 Max plan；小任务用 quick |
| 棕地项目不扫描 | 与现有代码模式冲突 | 先跑 `/gsd:map-codebase` |
| 上下文累积不清理 | 违背 GSD 核心优势 | 阶段间确保全新上下文 |
| 执行失败后重跑整个阶段 | 浪费。修复应更精准 | 用 `/gsd:quick` 修复或 `/gsd:verify-work` 定位 |
| CLAUDE.md 冲突 | GSD 规则未正确加载 | 手动确保 GSD 规则存在于 CLAUDE.md |

---

## 十二、GSD 独特创新

| 创新 | 说明 |
|------|------|
| **Plans as Prompts** | PLAN.md 不是文档变成 prompt，它**就是** prompt。XML 结构直接指导执行 |
| **Dream Extraction** | "协作思考"代替"需求收集"，从模糊想法提取可执行需求 |
| **Nyquist Validation** | 借鉴信号处理定理，每个需求必须有自动化测试反馈 |
| **Goal-Backward Verification** | 从用户可观察的结果反向推导验证（非正向检查任务完成度）|
| **Context Bridge Architecture** | statusline hook 写指标到临时文件，context monitor 读取。解耦的桥接允许跨 hook 通信 |
| **Deviation Handling** | 执行器自动处理计划偏差，适应而非失败 |
| **gsd-tools.cjs** | Node.js CLI 工具（15 模块，100+ 命令），分离确定性逻辑和 AI 推理 |
| **User Profiling** | 8 维度行为分析，个性化工作流响应 |
| **Quick Mode Composable Flags** | `--discuss`, `--research`, `--full` 自由组合临时任务的规划深度 |
| **Multi-Runtime Abstraction** | 安装时转换支持 6 种 AI 运行时（工具名、hook 事件、Agent 前言、路径约定）|

---

## 十三、实战例子

### 例子: 棕地项目 — 给现有 SaaS 加支付功能

```bash
# Step 0: 扫描现有代码库
/gsd:map-codebase
# → 4 个并行 mapper 分析:
#   tech: Next.js 14 + Prisma + PostgreSQL + Tailwind
#   arch: App Router, server components, API routes in /api/
#   quality: 72% test coverage, ESLint + Prettier configured
#   concerns: No rate limiting, N+1 queries in /api/users

# Step 1: 初始化项目（GSD 会读取 codebase 分析）
/gsd:new-project
# → "你在给现有 SaaS 加什么功能？"
# → "支付处理: Stripe 订阅 + 一次性付款"
# → 生成 ROADMAP.md:
#   Phase 1: Stripe 集成基础（webhook + 客户同步）
#   Phase 2: 订阅管理（创建/升级/降级/取消）
#   Phase 3: 一次性付款（checkout session）
#   Phase 4: 账单历史 + 发票 UI

# Step 2: 讨论 Phase 1
/gsd:discuss-phase 1
# → "Stripe API version: 2024-12-18 还是 latest?"
# → "Webhook 签名验证: 同步还是异步?"
# → "失败重试策略: 指数退避还是固定间隔?"
# → 决策锁定到 CONTEXT.md

# Step 3: 规划
/gsd:plan-phase 1
# → RESEARCH.md: Stripe Next.js 集成最佳实践
# → Plan A: Stripe SDK setup + webhook endpoint
# → Plan B: Customer sync (User ↔ Stripe Customer)
# → Plan-checker 验证:
#     ✓ CONTEXT.md 决策被尊重
#     ✓ REQ-01 到 REQ-04 都有对应任务
#     ✓ 每个 plan ≤ 50% 上下文预算

# Step 4: 执行
/gsd:execute-phase 1
# Wave 1: [Plan A, Plan B] 并行
#   Executor A (全新 200K context):
#     Task 1: npm install stripe → commit
#     Task 2: POST /api/webhooks/stripe → commit
#     Task 3: human-verify: 测试 webhook 签名
#   Executor B (全新 200K context):
#     Task 1: Prisma schema add stripeCustomerId → commit
#     Task 2: Customer sync service → commit

# Step 5: 验证
/gsd:verify-work 1
# → Exists: ✅ webhook endpoint, customer sync service
# → Substantive: ✅ Real Stripe API calls, not mocks
# → Wired: ⚠️ webhook handler dispatches events but
#           subscription.updated handler is empty stub
# → GAP-01: subscription.updated handler needs implementation
#           (will be covered in Phase 2)

# Step 6: Nyquist 验证
/gsd:validate-phase 1
# → REQ-01 (Stripe setup): COVERED — test/stripe/setup.test.ts
# → REQ-02 (Webhook verify): COVERED — test/api/webhook.test.ts
# → REQ-03 (Customer sync): PARTIAL — test exists but no edge cases
# → REQ-04 (Error handling): MISSING
# → Auditor generates: test/stripe/error-handling.test.ts
# → Auditor extends: test/stripe/customer-sync.test.ts
```

### 例子: Bug 调试工作流

```bash
/gsd:debug
# → "描述你遇到的问题"
# → "用户点击'升级订阅'后页面白屏"

# gsd-debugger 使用科学方法:
# 1. 假设: React 渲染错误（未捕获的异常）
#    测试: 检查浏览器控制台
#    结果: TypeError: Cannot read property 'id' of undefined
#    → 假设部分确认

# 2. 假设: subscription 对象在某些条件下为 null
#    测试: grep subscription 使用处
#    结果: src/components/UpgradeModal.tsx:45
#          const planId = subscription.currentPlan.id  ← 无空值检查
#    → 根因确认

# 3. 修复:
#    if (!subscription?.currentPlan) {
#      return <LoadingState />;
#    }

# 4. 验证:
#    → 添加回归测试
#    → 原子提交: fix(2-A): handle null subscription in UpgradeModal

# 调试状态持久化到 DEBUG.md（跨会话保留）
```

### 例子: 快速任务

```bash
# 小改动不需要完整工作流
/gsd:quick "把登录按钮颜色从蓝色改成品牌紫色 #7C3AED"
# → 直接执行，原子提交
# → 跳过: research, plan-check, verification
# → 保留: 状态追踪, git commit

# 需要一点研究的快速任务
/gsd:quick --research "添加 dark mode 支持"
# → 研究: Tailwind dark mode 最佳实践
# → 执行: 添加 dark: 变体
# → 原子提交

# 需要讨论的快速任务
/gsd:quick --discuss "重构用户表添加团队支持"
# → 讨论: "多对多还是多对一？"
# → 执行: Schema migration + model update
# → 原子提交
```

---

## 十四、与其他框架对比

| 维度 | GSD | ECC | BMAD | SpecKit | Plain Plan Mode |
|------|-----|-----|------|---------|-----------------|
| 定位 | 规格驱动开发 | Agent harness 优化 | 敏捷团队模拟 | 开发者工具包 | 内置功能 |
| Stars | 36K+ | 50K+ | ~5K | 72.7K | N/A |
| 核心优势 | 上下文隔离（全新窗口/任务）| 持续学习 + Hook 驱动 | 完整敏捷流程 | 灵活可定制 | 零开销 |
| Token 成本 | 高（多 Agent 生成）| 中-高 | 高 | 低 | 最低 |
| 适合场景 | 复杂多阶段项目 | 日常重度开发 | 企业敏捷团队 | GitHub 生态用户 | 简单任务 |
| 学习曲线 | 中等（1小时上手）| 陡峭 | 陡峭 | 平缓 | 无 |
| 验证体系 | 目标回溯 + Nyquist | Verification Loop | Scrum review | 手动 | 无 |
| 上下文管理 | 激进隔离（全新窗口）| 策略性压缩 | 无特殊处理 | 无特殊处理 | 自动压缩 |
| 会话持续性 | HANDOFF.json + STATE.md | Memory 系统 | 无 | 无 | 无 |

**选择建议**:

- **GSD**: 构建完整产品、多阶段项目、需要严格验证
- **ECC**: 日常编码、持续改进、多语言多项目
- **两者结合**: GSD 做项目管理和规划，ECC 做代码质量和学习（你当前的配置）
- **Plain Plan Mode**: 单文件修改、简单 Bug 修复

---

## 十五、关键数据

- GitHub Stars: 36K+
- 版本: v1.26.0
- Agents: 16 个
- 命令: 37+ 个
- 工作流: 44 个
- 模板: 50+ 个
- gsd-tools 命令: 100+
- 活跃 Discord: 1,200+ 成员
- 支持运行时: 6 种（Claude Code, OpenCode, Gemini CLI, Codex, Copilot, Antigravity）
- 许可: 开源

---

## Related

- [[Everything Claude Code 完整指南]]
- [[Everything Claude Code 用法速查]]
- [[Everything Claude Code 方法论与最佳实践]]