913 lines
33 KiB
Markdown
913 lines
33 KiB
Markdown
---
|
||
created: "2026-03-20 10:00"
|
||
type: resource
|
||
tags: [resource, 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
|
||
|
||
### Resources
|
||
- [[Everything Claude Code 完整指南]]
|
||
- [[Everything Claude Code 用法速查]]
|
||
- [[Everything Claude Code 方法论与最佳实践]]
|
||
|
||
### Zettelkasten
|
||
- [[上下文腐烂与全新窗口隔离]]
|
||
- [[目标回溯验证vs正向任务检查]]
|
||
- [[Plans as Prompts设计模式]]
|