规划类命令详解 - 和平哥的学习笔记

这是「GSD 全景代码解析」专题的第 9 篇。在上一篇（第 08 篇）中，我们系统梳理了 GSD 的命令系统全景图，理解了命令的分类体系、解析路由和上下文注入机制。从本篇开始，我们将逐类深入每个命令家族的设计哲学与实战用法。首先登场的是规划类命令——GSD 工作流中最核心、使用频率最高的命令群，它们承担着将模糊需求转化为可执行计划的关键使命。

一、规划类命令概览

GSD 的规划类命令构成了一个分层递进、相互协作的规划体系。从快速草图到超级规划，从研究探查到规范定型，每个命令都对应规划光谱上的一个特定阶段：

命令	定位	适用场景	输出物
`/gsd-sketch`	快速草图	想法萌芽期，快速验证思路	Sketch 文档
`/gsd-spike`	技术调研	不确定技术可行性时	Spike 报告
`/gsd-research-phase`	深度研究	需要系统性收集信息	Research 文档
`/gsd-plan-phase`	核心规划	标准项目的完整规划	Plan 文件 + Session 序列
`/gsd-spec-phase`	规范定型	需要精确技术规范时	SPEC.md
`/gsd-ultraplan-phase`	超级规划	大规模、长周期项目	多级规划树

这六个命令并非互斥，而是可以组合使用。例如，一个大型项目可能先走 /gsd-spike 验证关键技术，再进入 /gsd-research-phase 收集领域知识，最后通过 /gsd-ultraplan-phase 建立完整的规划体系。

flowchart LR
    A[想法/需求] --> B{"规模与清晰度"}
    B -->|模糊小想法| C[/gsd-sketch/]
    B -->|技术不确定| D[/gsd-spike/]
    B -->|信息不足| E[/gsd-research-phase/]
    B -->|标准项目| F[/gsd-plan-phase/]
    B -->|需要精确规范| G[/gsd-spec-phase/]
    B -->|大型复杂项目| H[/gsd-ultraplan-phase/]
    C --> I[可执行计划]
    D --> I
    E --> I
    F --> I
    G --> I
    H --> I

二、`/gsd-plan-phase`：核心规划命令

/gsd-plan-phase 是 GSD 使用频率最高的规划命令，也是整个工作流的心脏。它负责将 .planning/ 目录中的高层目标（ROADMAP.md、REQUIREMENTS.md）转化为具体可执行的 Session 序列。

2.1 规划阶段的完整流程

执行 /gsd-plan-phase 时，GSD 会按照以下固定流程工作：

flowchart TD
    A[/gsd-plan-phase] --> B[读取 .planning/ 上下文]
    B --> C[解析 REQUIREMENTS.md]
    B --> D[解析 ROADMAP.md]
    B --> E[解析 PROJECT.md]
    C --> F[需求分析与优先级排序]
    D --> G[确定当前 Phase]
    E --> H[提取约束与资源]
    F --> I[生成 Chunked Plan]
    G --> I
    H --> I
    I --> J[写入 .planning/sessions/]
    J --> K[输出下一步指令]

关键设计原则：plan-phase 是只读上层、写入下层的。它读取 .planning/ 根目录的战略文件，但只在 .planning/sessions/ 目录中创建和修改执行计划，绝不回写 ROADMAP 或 REQUIREMENTS。这种单向依赖确保了战略层与执行层的清晰分离。

2.2 需求分析 → 研究 → 计划生成的链路

plan-phase 内部遵循一个三段式链路：

阶段一：需求分析（Requirements Analysis）

GSD 会扫描 REQUIREMENTS.md 中的功能需求（FR）和非功能需求（NFR），提取以下信息：

优先级分布（P0/P1/P2 的比例）
需求间的依赖关系（哪些 FR 必须先于其他 FR 实现）
验收标准中的量化指标（性能、安全、可用性）

阶段二：上下文研究（Contextual Research）

根据项目的技术栈配置（config.json 中的 techStack），GSD 会进行轻量级研究：

检查已存在的 sessions/ 目录中是否有相关研究记录
评估当前代码库的状态（如已有模块、接口定义）
识别潜在的技术风险点

阶段三：计划生成（Plan Generation）

综合前两阶段的结果，生成结构化的 Session 计划：

# Session Plan: Phase 1 - Foundation

## Session 1.1: Project Scaffolding
- **Goal**: Initialize project structure with configured tech stack
- **Requirements**: FR-001 (partial)
- **Estimated Effort**: 30 min
- **Dependencies**: None
- **Deliverables**: 
  - package.json / Cargo.toml / go.mod
  - Basic directory structure
  - CI pipeline skeleton

## Session 1.2: Database Schema Design
- **Goal**: Design and implement core data models
- **Requirements**: FR-002, NFR-001
- **Estimated Effort**: 45 min
- **Dependencies**: Session 1.1
- **Deliverables**:
  - Entity Relationship Diagram
  - Migration files
  - Repository layer interfaces

2.3 Chunked Planning（分块规划）策略

Chunked Planning 是 plan-phase 最核心的算法创新。它解决了大模型在生成长篇计划时容易出现的上下文漂移和细节不一致问题。

核心思想：将大规模规划拆分为多个独立的 Chunk，每个 Chunk 在独立的上下文窗口中生成，最后通过"缝合点"（Stitch Points）将它们串联成完整计划。

flowchart LR
    subgraph "Chunk 1: 基础设施"
        A1[项目脚手架]
        A2[CI/CD 配置]
        A3[开发环境]
    end
    subgraph "Chunk 2: 数据层"
        B1[Schema 设计]
        B2[Migration]
        B3[Repository]
    end
    subgraph "Chunk 3: 业务层"
        C1[领域模型]
        C2[服务接口]
        C3[核心逻辑]
    end
    subgraph "Chunk 4: 接口层"
        D1[API 路由]
        D2[鉴权中间件]
        D3[DTO 校验]
    end
    A1 --> A2 --> A3
    A3 -.->|Stitch Point| B1
    B1 --> B2 --> B3
    B3 -.->|Stitch Point| C1
    C1 --> C2 --> C3
    C3 -.->|Stitch Point| D1
    D1 --> D2 --> D3

Chunk 的划分策略：

按架构分层：如数据层、业务层、接口层，每层一个 Chunk
按业务领域：如用户模块、订单模块、支付模块，每个领域一个 Chunk
按风险等级：高风险部分单独 Chunk，便于早期验证

每个 Chunk 生成时，GSD 会向其上下文注入：

上游 Chunk 的输出接口定义（而非完整实现）
全局约束（如技术栈、编码规范）
本 Chunk 对应的需求子集

这种"接口驱动"的 Chunk 间通信方式，使得各 Chunk 可以独立演进而不相互污染。

三、`/gsd-research-phase`：研究阶段

/gsd-research-phase 是 GSD 的深度研究模式。与 plan-phase 中轻量级的上下文研究不同，research-phase 专门用于系统性收集、整理和分析信息，为后续决策提供坚实基础。

3.1 深度研究模式

当执行 /gsd-research-phase 时，GSD 会进入研究模式，其工作方式有显著不同：

更宽的上下文窗口：研究模式会分配更多的 token 预算给信息收集
多源信息融合：允许 AI 同时检索代码库、文档、网络资源（如果配置允许）
结构化输出：所有研究成果必须写入 .planning/sessions/ 下的研究型 Session 文件

典型的研究 Session 结构：

# Research Session: Payment Gateway Integration

## Research Questions
1. Which payment providers support our target markets (CN, US, EU)?
2. What are the PCI-DSS compliance requirements?
3. How do Stripe, PayPal, and Adyen compare on API design?

## Findings

### Finding 1: Provider Coverage
- Stripe: 46 countries, best API docs, highest fees (2.9% + 30¢)
- PayPal: 200+ countries, mature but legacy API
- Adyen: unified platform, complex integration, lower fees at scale

### Finding 2: PCI-DSS Scope
- Using hosted fields / iframe: SAQ-A (simplest)
- Custom form with tokenization: SAQ-A-EP
- Full card data handling: SAQ-D (most complex, avoid)

## Recommendation
Use Stripe with hosted fields for MVP (SAQ-A compliance).
Re-evaluate Adyen when monthly volume exceeds $100K.

## References
- [Stripe Docs: PCI Compliance](https://stripe.com/docs/security)
- [Adyen Integration Guide](https://docs.adyen.com/online-payments)

3.2 与 plan-phase 的协作关系

research-phase 和 plan-phase 是上下游协作关系：

sequenceDiagram
    participant U as User
    participant R as /gsd-research-phase
    participant P as /gsd-plan-phase
    participant S as Sessions/

    U ->> R: 提出研究主题
    R ->> S: 生成 Research Session
    R ->> U: 返回研究发现与建议
    U ->> P: 执行规划
    P ->> S: 读取现有 Sessions
    P ->> P: 识别 Research Session
    P ->> P: 将研究发现注入规划上下文
    P ->> S: 生成 Plan Sessions
    P ->> U: 返回可执行计划

关键机制：plan-phase 在生成计划前，会主动扫描 sessions/ 目录中标记为 type: research 的 Session，并将其核心发现自动注入规划上下文。这意味着：

先执行 research-phase，再执行 plan-phase，可以获得信息更充分的计划
研究 Session 可以被多个 plan-phase 调用复用
研究结论随时间可能过时，GSD 会提示用户确认研究 Session 的时效性

3.3 研究成果的组织方式

研究成果以 Research Session 的形式存储在 .planning/sessions/ 中，命名规范为 research-{topic}-{timestamp}.md：

.planning/sessions/
├── research-payment-gateway-20260423.md
├── research-auth-protocols-20260420.md
├── plan-phase-1-foundation.md
└── plan-phase-2-core-features.md

每个 Research Session 的 frontmatter 中标记了 type: research，便于 GSD 和其他工具识别：

---
session_id: research-payment-gateway-20260423
type: research
topic: Payment Gateway Integration
status: completed
validity: 90d  # 研究结论的有效期，超过后 plan-phase 会提示重新研究
---

四、`/gsd-spec-phase`：规范阶段

/gsd-spec-phase 负责将模糊的需求和规划转化为精确、可验证的技术规范（Specification）。如果说 plan-phase 回答"做什么"，那么 spec-phase 回答"具体怎么做、做到什么程度"。

4.1 生成技术规范

执行 /gsd-spec-phase 时，GSD 会读取当前 Phase 的 Plan Sessions，为每个关键接口、模块或算法生成详细的 SPEC 文档：

# SPEC: User Authentication API

## Overview
定义用户认证系统的 API 接口，包括注册、登录、Token 刷新和登出。

## Interface Definition

### POST /api/v1/auth/register
**Request Body:**
```json
{
  "email": "string, required, email format",
  "password": "string, required, min 8 chars, must contain uppercase + number",
  "username": "string, optional, 3-20 chars, alphanumeric + underscore"
}
```

**Response 201:**
```json
{
  "user_id": "uuid",
  "email": "string",
  "username": "string",
  "created_at": "ISO 8601 datetime"
}
```

**Response 400:**
```json
{
  "error": "VALIDATION_ERROR",
  "details": ["email: invalid format", "password: too weak"]
}
```

## Business Rules
1. 邮箱必须全局唯一，不区分大小写
2. 密码必须使用 bcrypt 哈希，cost factor ≥ 12
3. 注册成功后发送验证邮件，24 小时内有效

## Error Codes
| Code | HTTP Status | Description |
|------|-------------|-------------|
| EMAIL_EXISTS | 409 | 邮箱已被注册 |
| USERNAME_TAKEN | 409 | 用户名已被使用 |
| VALIDATION_ERROR | 400 | 请求参数不符合规范 |

SPEC 文档的核心特征：

接口精确：包含完整的请求/响应格式、字段类型、约束条件
错误完整：列出所有可能的错误场景及其返回格式
业务规则明确：将隐含的业务逻辑显式文档化
可测试：每个 SPEC 条目都对应可编写的测试用例

4.2 规范与实现的衔接

SPEC 文档不是孤立的，它与实现阶段通过以下机制衔接：

flowchart LR
    A[REQUIREMENTS.md] --> B[/gsd-spec-phase/]
    C[Plan Sessions] --> B
    B --> D[SPEC.md]
    D --> E{"实现方式"}
    E -->|AI 自动生成| F[/gsd-session/]
    E -->|人工编码| G[Developer]
    F --> H[Implementation]
    G --> H
    H --> I[Test Cases]
    D --> I

衔接机制：

Session 注入：执行 /gsd-session 时，GSD 会自动查找与当前任务相关的 SPEC 段落，将其注入 Session 上下文
验收映射：SPEC 中的每个接口定义直接映射到测试用例的输入/预期输出
变更追踪：当 SPEC 发生变更时，GSD 会标记受影响的 Sessions，提示重新执行

五、`/gsd-ultraplan-phase`：超级规划

/gsd-ultraplan-phase 是 GSD 为大规模、长周期、多团队协作项目设计的超级规划命令。它在 plan-phase 的基础上引入了多级规划结构，解决标准规划在面对复杂项目时的"计划爆炸"问题。

5.1 大规模项目的规划策略

当项目满足以下任一条件时，应考虑使用 ultraplan-phase：

预估总工期超过 3 个月
涉及 3 个以上子系统或微服务
需要 2 个以上开发者或 AI Agent 协作
存在外部依赖（第三方 API、硬件采购、合规审批）

ultraplan-phase 的核心策略是分层解耦：将庞大的计划拆分为多个层级，每一层只关注本层的决策，细节委托给下层。

5.2 多层级规划（史诗 → 里程碑 → 任务）

ultraplan-phase 生成的是一个三级规划树：

flowchart TD
    subgraph "Level 1: Epics"
        E1[Epic: 用户系统]
        E2[Epic: 订单系统]
        E3[Epic: 支付系统]
    end
    subgraph "Level 2: Milestones"
        M11[M1: 注册登录]
        M12[M2: 用户管理]
        M21[M1: 购物车]
        M22[M2: 订单流转]
        M31[M1: 支付接入]
        M32[M2: 对账系统]
    end
    subgraph "Level 3: Tasks / Sessions"
        T111[Session: API 设计]
        T112[Session: 密码安全]
        T121[Session: 用户列表]
        T122[Session: 权限控制]
    end
    E1 --> M11
    E1 --> M12
    E2 --> M21
    E2 --> M22
    E3 --> M31
    E3 --> M32
    M11 --> T111
    M11 --> T112
    M12 --> T121
    M12 --> T122

三级结构定义：

层级	粒度	时间跨度	负责人	GSD 输出
Epic	子系统/业务域	4-8 周	架构师/Lead	Epic 文档
Milestone	可交付功能集	1-2 周	开发者/Agent	Milestone Plan
Task/Session	单次可执行单元	15-60 min	开发者/Agent	Session 文件

规划树的存储结构：

.planning/
├── ultraplan/
│   ├── epics/
│   │   ├── epic-user-system.md
│   │   ├── epic-order-system.md
│   │   └── epic-payment-system.md
│   ├── milestones/
│   │   ├── m-user-auth.md
│   │   ├── m-user-management.md
│   │   ├── m-shopping-cart.md
│   │   └── ...
│   └── dependencies.md  # 跨 Epic/Milestone 的依赖关系图
└── sessions/  # 具体 Session 计划仍存于此

依赖管理：ultraplan-phase 会生成一个全局 dependencies.md，显式记录跨层级的依赖关系：

# Cross-Milestone Dependencies

## Hard Dependencies (Blocking)
- m-user-auth must complete before m-shopping-cart
- m-payment-gateway must complete before m-order-checkout

## Soft Dependencies (Non-blocking, but recommended)
- m-user-management before m-admin-dashboard
- m-inventory-sync before m-order-fulfillment

## External Dependencies
- Third-party API approval: estimated 2 weeks
- SSL certificate procurement: estimated 3 days

六、`/gsd-spike`：技术调研

/gsd-spike 源自敏捷开发中的 Spike 概念，专门用于快速验证技术可行性。当团队面对"这个技术方案是否可行？""这个库能否满足我们的需求？"这类问题时，Spike 是最合适的工具。

6.1 Spike 的概念（来自敏捷开发）

在敏捷方法论中，Spike 是一种时间盒定（time-boxed）的研究活动，目的是降低技术风险，而非交付生产代码。GSD 将这一概念融入命令系统：

时间盒：默认 30-60 分钟，必须在限定时间内得出结论
可丢弃：Spike 的产出代码不一定进入主分支
决策导向：最终输出是"做/不做/换方案"的明确建议

6.2 技术可行性验证

执行 /gsd-spike 的典型场景：

User: /gsd-spike "Can we use WebRTC for real-time collaboration in our
      note-taking app? Concerns: browser compatibility, signaling server
      complexity, and NAT traversal reliability."

GSD 会启动一个 Spike Session，执行以下验证：

快速原型：在隔离目录中搭建最小可运行的 WebRTC 原型
兼容性测试：验证目标浏览器（Chrome、Firefox、Safari、Edge）的支持情况
复杂度评估：估算 signaling 服务器的实现工作量
风险识别：列出 NAT traversal 的已知问题（如企业防火墙、对称 NAT）

6.3 Spike 报告的生成

Spike 结束后，GSD 生成一份结构化的 Spike Report：

# Spike Report: WebRTC Real-Time Collaboration

## Objective
验证 WebRTC 在笔记应用实时协作场景中的可行性。

## Time Box
45 minutes

## Findings

### Finding 1: Browser Compatibility ✅
- Chrome: Full support ( tested v124 )
- Firefox: Full support ( tested v125 )
- Safari: Supported with adapter.js polyfill
- Edge: Chromium-based, same as Chrome

### Finding 2: Signaling Complexity ⚠️
- Minimal signaling server: ~200 lines Node.js + Socket.io
- Production-grade: need presence, reconnection, error handling → ~2-3 days

### Finding 3: NAT Traversal ❌
- 80% success rate with public STUN servers
- Corporate networks with symmetric NAT: requires TURN server
- TURN server adds ~$50-100/month operational cost

## Recommendation
**PROCEED WITH CAUTION**

Use WebRTC for MVP, but:
1. Integrate adapter.js for Safari compatibility
2. Budget 2 days for robust signaling server
3. Plan TURN server fallback for enterprise users
4. Consider Yjs (CRDT library) as alternative if conflict resolution is complex

## Code Artifacts
- `spike-webrtc-basic/`: Minimal working prototype
- `spike-webrtc-signaling/`: Signaling server skeleton

Spike Report 的 Recommendation 字段采用标准化的决策格式：

GO：技术可行，建议采用
PROCEED WITH CAUTION：可行但存在已知风险，需 mitigation plan
NO-GO：技术不可行或成本过高，建议替代方案
NEED MORE DATA：当前信息不足以决策，需要补充研究

七、`/gsd-sketch`：草图设计

/gsd-sketch 是规划体系中最轻量、最快速的命令。它对应创意萌芽期——当你只有一个模糊的想法，甚至不确定是否值得立项时，sketch 帮助你在几分钟内将想法结构化。

7.1 快速原型设计

sketch 的设计理念是"低摩擦启动"：不需要完整的项目上下文，不需要 .planning/ 目录，甚至不需要 Git 仓库。你可以在任意目录执行：

User: /gsd-sketch "A browser extension that summarizes web pages using
      local LLM, with privacy as the #1 priority"

GSD 会立即生成一个 Sketch 文档，包含：

One-liner：一句话描述核心创意
Problem Statement：解决什么问题
Target User：谁会使用它
Core Loop：用户的核心使用路径
Key Assumptions：这个创意成立的前提假设（待验证）
Open Questions：需要进一步研究的疑问
Next Steps：建议的后续动作（如 /gsd-spike、/gsd-research-phase）

# Sketch: Local LLM Page Summarizer (Browser Extension)

## One-liner
一个浏览器扩展，使用本地运行的 LLM 对网页内容进行隐私安全的摘要生成。

## Problem Statement
用户需要在不泄露浏览数据给第三方的情况下，快速理解长网页的核心内容。

## Target User
- 隐私敏感的技术从业者
- 企业内部有数据合规要求的员工
- 离线环境工作者

## Core Loop
1. 用户点击扩展图标
2. 扩展提取当前页面正文
3. 本地 LLM（通过 Ollama / llama.cpp）生成摘要
4. 摘要以侧边栏形式展示
5. 用户可导出或复制摘要

## Key Assumptions (to validate)
- [ ] 本地 LLM（7B 参数）的摘要质量足够可用
- [ ] 浏览器扩展可以足够高效地提取正文
- [ ] 用户愿意为隐私付出本地运行的性能开销

## Open Questions
1. 支持哪些本地 LLM 运行时？（Ollama、LM Studio、llama.cpp）
2. 如何处理多语言网页？
3. 扩展商店审核对 AI 功能有无特殊要求？

## Next Steps
- `/gsd-spike "local LLM summarization quality with 7B models"`
- `/gsd-research-phase "browser extension manifest v3 AI integration"`

7.2 与规划流程的衔接

Sketch 不是孤立文档，它是规划流程的入口漏斗：

flowchart LR
    A[想法] --> B[/gsd-sketch/]
    B --> C{评估结果}
    C -->|值得深入| D[/gsd-spike/]
    C -->|信息不足| E[/gsd-research-phase/]
    C -->|直接启动| F[/gsd-new-project/]
    D --> G{验证通过?}
    G -->|是| F
    G -->|否| H[放弃或 pivot]
    E --> F
    F --> I[/gsd-plan-phase/]

Sketch 文档可以保存在任意位置（如 ~/sketches/），当决定正式立项时，GSD 可以读取 Sketch 并将其内容自动导入到 /gsd-new-project 的 Dream Extraction 流程中，避免重复输入。

八、规划类命令的选择指南

面对六个规划命令，如何快速做出选择？以下是基于项目特征的决策矩阵：

8.1 按项目阶段选择

项目阶段	推荐命令	原因
想法萌芽	`/gsd-sketch`	最低启动成本，快速结构化
技术选型前	`/gsd-spike`	验证关键技术可行性
立项初期	`/gsd-research-phase`	系统性收集领域知识
常规迭代	`/gsd-plan-phase`	标准规划流程，覆盖大多数场景
接口设计前	`/gsd-spec-phase`	精确规范，减少实现返工
大型项目启动	`/gsd-ultraplan-phase`	多级规划，管理复杂性

8.2 按问题类型选择

你的问题	推荐命令
"这个想法靠谱吗？"	`/gsd-sketch`
"这个技术方案可行吗？"	`/gsd-spike`
"市面上有哪些方案？怎么选？"	`/gsd-research-phase`
"这个功能怎么实现？分几步？"	`/gsd-plan-phase`
"这个 API 具体怎么设计？"	`/gsd-spec-phase`
"这个项目太大了，怎么拆？"	`/gsd-ultraplan-phase`

8.3 组合使用建议

小型项目（1-2 周）：

/gsd-sketch → /gsd-new-project → /gsd-plan-phase → /gsd-session...

中型项目（1-2 月）：

/gsd-sketch → /gsd-spike → /gsd-new-project → /gsd-research-phase
→ /gsd-plan-phase → /gsd-spec-phase → /gsd-session...

大型项目（3 月+）：

/gsd-sketch → /gsd-spike → /gsd-research-phase → /gsd-new-project
→ /gsd-ultraplan-phase → /gsd-spec-phase → /gsd-plan-phase → /gsd-session...

重要原则：规划不是一次性活动。在项目的任何阶段，如果发现信息不足、技术方案有变或需求发生漂移，都可以随时回到上游命令重新执行。GSD 的规划体系支持渐进明细（Progressive Elaboration），而非瀑布式的 rigid 计划。

九、小结

规划类命令是 GSD 工作流中最丰富、最精细的命令群。从 /gsd-sketch 的灵感捕捉，到 /gsd-ultraplan-phase 的宏大叙事，六个命令覆盖了一个项目从"有想法"到"可执行"的全光谱：

/gsd-sketch：最低成本的想法验证
/gsd-spike：技术风险的快速探查
/gsd-research-phase：系统性的信息收集
/gsd-plan-phase：标准项目的核心规划引擎，含 Chunked Planning
/gsd-spec-phase：精确规范的定义与传递
/gsd-ultraplan-phase：大规模项目的多级规划管理

理解每个命令的定位和协作关系，是发挥 GSD 最大效能的关键。规划的质量直接决定了后续执行的流畅度——正如 GSD 的设计哲学所言："Spend twice the time planning, spend half the time debugging."

📌 下一篇预告：第 10 篇《执行与验证类命令》将深入解析 /gsd-session、 /gsd-execute、 /gsd-verify、 /gsd-review 等执行层命令，揭示 GSD 如何将规划转化为代码、如何确保执行质量、以及如何在每个 Session 结束时进行有效的复盘与验证。如果说规划类命令是"运筹帷幄"，那么执行与验证类命令就是"决胜千里"——它们共同构成了 GSD 从想法到交付的完整闭环。