knowledge-base/4 - Resources/GSD 方法论与最佳实践.md

created, type, tags, source

created	type	tags	source
2026-03-20 10:00	resource	claude-code AI-tools methodology best-practices project-management gsd	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。

例子 — 完整新项目流程

# 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:

<!-- .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	它真的能用吗？

例子 — 验证报告

# 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 验证报告:

# 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 — 项目短期记忆

# 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

会话暂停/恢复

# 暂停工作（保存完整状态）
/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 完整配置

{
  "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 加支付功能

# 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 调试工作流

/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（跨会话保留）

例子: 快速任务

# 小改动不需要完整工作流
/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 方法论与最佳实践