plan-phase 工作流深度解析

这是「GSD 全景代码解析」专题的第 15 篇。在本系列中，我们将逐层拆解 Get Shit Done (GSD) 这一 56K+ stars 的 Meta-Prompting 框架，从命令系统到工作流编排，从 Agent 设计到上下文工程，带你一览上下文驱动开发的工程全貌。

---

一、plan-phase 工作流概览

plan-phase.md 是 GSD 仓库中第二大的工作流文件（约 66KB），仅次于 execute-phase.md（69KB）。如果说 execute-phase 是 GSD 的"执行引擎"，那么 plan-phase 就是它的"战略大脑"。

plan-phase 的核心职责是将用户的想法（idea）或需求转化为可执行、可验证、可追踪的详细计划。这个过程不是简单的任务列表生成，而是一个涉及需求分析、技术研究、方案设计、风险评估和任务分解的完整工程流程。

flowchart TD
    A[用户输入 idea / 需求] --> B[Dream Extraction]
    B --> C{是否需要研究?}
    C -->|是| D[research-phase]
    C -->|否| E[需求结构化]
    D --> E
    E --> F[技术方案设计]
    F --> G[任务分解]
    G --> H[Chunked Planning]
    H --> I[计划验证]
    I --> J{验证通过?}
    J -->|否| K[计划修订]
    K --> H
    J -->|是| L[生成 ROADMAP.md]
    L --> M[创建 phases/ 目录]

---

二、规划阶段的完整流程

2.1 接收输入

plan-phase 的输入来源多样：

• 来自 /gsd-new-project：新项目的 Dream Extraction 结果
• 来自 /gsd-plan-phase：用户直接触发的规划命令
• 来自 /gsd-ultraplan-phase：大规模项目的分层规划
• 来自 /gsd-spike：技术调研后的规划细化

输入通常是一个自然语言描述的想法或需求，可能包含：项目目标、功能列表、技术偏好、约束条件等。

2.2 Dream Extraction（需求提取）

Dream Extraction 是 plan-phase 的第一步，其目标是从用户的模糊描述中提取出结构化需求。这个过程由 gsd-planner Agent 主导，采用多轮对话的方式：

sequenceDiagram
    participant User as 用户
    participant Planner as gsd-planner
    participant Researcher as gsd-phase-researcher
    participant Checker as gsd-plan-checker

    User->>Planner: 我有一个想法：做一个 AI 驱动的代码审查工具
    Planner->>User: 几个澄清问题：目标用户是谁？支持哪些语言？集成哪些平台？
    User->>Planner: 回答...
    Planner->>Researcher: 需要研究现有解决方案吗？
    Researcher->>Planner: 研究结果（可选）
    Planner->>Planner: 结构化需求
    Planner->>Checker: 验证计划完整性
    Checker->>Planner: 反馈（通过/需修订）

提取的维度通常包括：

维度	描述	示例
目标	项目要解决的核心问题	"自动化代码审查，减少人工审核时间"
用户	目标用户群体	"中小型开发团队的 Tech Lead"
功能	核心功能列表	"静态分析、模式匹配、AI 建议生成"
技术栈	偏好或约束的技术	"TypeScript + Node.js，支持 GitHub API"
约束	非功能性约束	"响应时间 < 2s，支持 10+ 种语言"
里程碑	关键交付节点	"MVP（2周）→ Beta（1月）→ GA（3月）"

2.3 研究阶段（可选）

当项目涉及新技术、新领域或复杂架构时，plan-phase 会调用 research-phase 进行深度研究：

• 技术可行性验证：评估技术方案的可行性
• 竞品分析：研究现有解决方案的优缺点
• 架构参考：收集类似项目的架构模式

研究成果以 references/ 文档的形式保存，供后续阶段引用。

2.4 技术方案设计

基于提取的需求和研究成果，Planner Agent 会设计技术方案：

1. 架构选型：单体 vs 微服务 vs Serverless
2. 数据模型：核心数据结构和关系
3. 接口设计：API 契约和协议
4. 依赖分析：第三方库和服务依赖

2.5 任务分解

技术方案确定后，Planner 将项目分解为可执行的任务单元：

graph TD
    A[项目目标] --> B[史诗 Epic 1]
    A --> C[史诗 Epic 2]
    A --> D[史诗 Epic 3]
    B --> B1[任务 Task 1.1]
    B --> B2[任务 Task 1.2]
    C --> C1[任务 Task 2.1]
    C --> C2[任务 Task 2.2]
    C --> C3[任务 Task 2.3]
    D --> D1[任务 Task 3.1]

每个任务包含：

• 标题：简洁描述
• 描述：详细说明
• 验收标准：完成定义
• 依赖：前置任务
• 估计：工作量评估
• 分配给：负责执行的 Agent

---

三、Chunked Planning 策略

3.1 为什么需要分块规划

对于大型项目，一次性生成完整的详细计划会面临两个核心问题：

1. 上下文溢出：Planner 的上下文窗口有限（通常 200K tokens），无法容纳整个项目的详细计划
2. 计划僵化：一次性制定的计划在执行过程中很难调整，缺乏灵活性

Chunked Planning 通过分层规划 + 增量细化解决这两个问题。

3.2 三层规划模型

GSD 采用三层规划模型：

flowchart TB
    subgraph L1["L1: 战略层"]
        A1[项目愿景]
        A2[核心目标]
        A3[成功标准]
    end
    subgraph L2["L2: 战术层"]
        B1[里程碑规划]
        B2[史诗列表]
        B3[依赖关系图]
    end
    subgraph L3["L3: 执行层"]
        C1[详细任务]
        C2[验收标准]
        C3[技术方案]
    end
    L1 --> L2
    L2 --> L3

层级	粒度	规划时机	存储位置
L1 战略层	项目级	项目启动时	PROJECT.md
L2 战术层	里程碑级	每个里程碑前	ROADMAP.md
L3 执行层	任务级	每个 Wave 前	phases/*.md

3.3 块的划分策略

Chunk 的划分遵循以下原则：

1. 功能内聚：每个 Chunk 包含一组相关的功能
2. 依赖最小化：Chunk 之间的依赖尽可能少
3. 可独立验证：每个 Chunk 可以独立测试和验证
4. 上下文适配：Chunk 的详细程度适配当前上下文窗口

flowchart LR
    A[完整项目计划] --> B[Chunk 1: 核心框架]
    A --> C[Chunk 2: 用户认证]
    A --> D[Chunk 3: 数据存储]
    A --> E[Chunk 4: API 层]
    A --> F[Chunk 5: 前端界面]
    A --> G[Chunk 6: 部署运维]
    B --> H[Wave 1.1]
    B --> I[Wave 1.2]
    C --> J[Wave 2.1]

3.4 增量细化机制

plan-phase 不是一次性完成所有规划，而是随着项目推进逐步细化：

sequenceDiagram
    participant P1 as plan-phase (L1)
    participant P2 as plan-phase (L2)
    participant P3 as plan-phase (L3)
    participant E as execute-phase

    P1->>P1: 生成战略层规划
    P1->>P2: 触发第一个里程碑的战术规划
    P2->>P3: 触发第一个 Chunk 的执行规划
    P3->>E: 交付详细任务列表
    E->>E: 执行 Wave 1
    E->>P3: 反馈执行结果
    P3->>P3: 调整后续任务
    P3->>E: 继续执行 Wave 2

---

四、与 gsd-planner Agent 的协作

4.1 Planner 的职责边界

gsd-planner.md（46KB）是 GSD 最大的 Agent 定义文件之一。Planner Agent 的核心职责包括：

• 需求分析：将模糊需求转化为结构化规格
• 技术设计：制定技术方案和架构决策
• 任务分解：将项目拆分为可执行单元
• 风险评估：识别潜在风险并制定缓解策略
• 计划验证：确保计划的完整性和可执行性

4.2 模型选择策略

plan-phase 对模型的要求较高，通常需要：

• 强推理能力：能够进行复杂的需求分析和架构设计
• 长上下文：能够处理大量的需求文档和参考资料
• 结构化输出：能够生成格式化的计划文档

因此，plan-phase 通常配置使用思考类模型（如 Claude 3.7 Sonnet、o3、Gemini 2.5 Pro），而非快速响应模型。

4.3 Planner 与 Plan-Checker 的协作

plan-phase 内置了验证机制——gsd-plan-checker Agent 会对生成的计划进行质量检查：

检查项	说明
完整性	是否覆盖所有需求
一致性	任务之间是否有冲突
可行性	技术方案是否可行
可追踪性	每个任务是否有明确的验收标准
依赖合理性	依赖关系是否有循环

如果检查失败，plan-phase 会触发修订循环，直到计划通过验证。

---

五、计划输出格式

5.1 ROADMAP.md

plan-phase 的核心输出是更新 ROADMAP.md，它包含：

# ROADMAP

## 里程碑

### v0.1.0 MVP (2周)
- [ ] 核心框架搭建
- [ ] 基础认证系统
- [ ] 首屏界面

### v0.2.0 Beta (1月)
- [ ] 数据持久化
- [ ] API 完善
- [ ] 测试覆盖

## 当前阶段
Phase 1: 核心框架

## 已完成的阶段
- Phase 0: 项目初始化 ✅

5.2 phases/ 目录结构

每个 Chunk 对应一个 phases/*.md 文件：

.planning/
├── phases/
│   ├── phase-01-core-framework.md
│   ├── phase-02-auth-system.md
│   ├── phase-03-data-layer.md
│   └── ...

每个 phase 文件包含：

• 阶段目标
• 任务列表（带验收标准）
• 依赖关系
• 风险和对策
• 预计完成时间

5.3 计划的可执行性检查

plan-phase 在输出计划前会进行可执行性检查：

1. 工具可用性：计划中涉及的 Tools 是否在 allowed-tools 列表中
2. Agent 能力：分配的 Agent 是否具备执行任务的能力
3. 上下文预算：计划的总 token 消耗是否在预算范围内
4. 时间合理性：工作量估计是否现实

---

六、规划失败的处理策略

6.1 常见失败场景

场景	原因	处理策略
需求过于模糊	用户输入不清晰	返回澄清问题，要求补充信息
技术不可行	方案存在根本性障碍	提出替代方案
上下文溢出	计划过大无法容纳	采用更粗粒度的 Chunked Planning
依赖循环	任务之间存在循环依赖	打破循环，重新排序
计划检查失败	plan-checker 发现缺陷	触发修订循环

6.2 修订循环

当计划验证失败时，plan-phase 不会直接放弃，而是进入修订循环：

flowchart LR
    A[生成计划] --> B[plan-checker 验证]
    B -->|失败| C[分析失败原因]
    C --> D[针对性修订]
    D --> B
    B -->|通过| E[输出最终计划]

修订循环最多执行 3 次，如果仍无法通过验证，则降级为粗粒度规划，将详细规划推迟到执行阶段。

---

七、与 execute-phase 的衔接

plan-phase 和 execute-phase 的衔接是 GSD 核心数据流的关键节点：

flowchart LR
    A[plan-phase] -->|ROADMAP.md + phases/*.md| B[execute-phase]
    B -->|执行结果 + STATE.md| C[verify-work]
    C -->|验证报告| D{通过?}
    D -->|是| E[更新 STATE.md]
    D -->|否| F[修订计划]
    F --> A

这种设计体现了 GSD 的Spec-Driven Development理念：

1. 计划即规范：ROADMAP.md 和 phases/*.md 构成了项目的"活规范"
2. 执行即验证：execute-phase 严格按照计划执行，偏差会被记录
3. 反馈闭环：执行结果反馈到计划，形成持续改进的循环

---

八、小结

plan-phase 是 GSD 框架的"战略大脑"，它将模糊的想法转化为可执行的计划。其核心设计亮点包括：

1. Chunked Planning：通过分层规划解决上下文溢出和计划僵化问题
2. 内置验证：plan-checker 确保计划的质量和可执行性
3. 渐进式细化：随着项目推进逐步细化计划，而非一次性制定完美计划
4. 与执行无缝衔接：ROADMAP.md 和 phases/*.md 直接驱动 execute-phase

plan-phase 的 66KB 不是"臃肿"，而是必要的复杂度——规划是软件开发中最需要深度思考的阶段，一个完善的规划流程能够显著降低后续执行阶段的风险和返工。

---

下一篇预告： 第 16 篇《new-project 与初始化工作流》——深度解析 new-project 工作流（44KB）的完整流程，包括 Dream Extraction、需求提取、项目结构初始化和 .planning/ 目录生成。