Planner 与 Plan-Checker

这是「GSD 全景代码解析」专题的第 23 篇。在前面的章节中，我们系统梳理了 GSD 的命令系统、工作流编排和规划体系。从本篇开始，我们将进入Agent 系统章节，逐层拆解 GSD 中各个 Agent 的设计哲学、角色定义和协作机制。首先登场的是 GSD 最大的 Agent 定义——gsd-planner.md（46KB），以及它的"质量守门人"gsd-plan-checker。

---

一、gsd-planner.md 概览

gsd-planner.md 是 GSD 仓库中体积最大的 Agent 定义文件，约 46KB。这一体量本身就说明了规划在 GSD 体系中的核心地位——规划 Agent 是整个框架的"战略大脑"，它需要将模糊的人类意图转化为精确、可执行、可验证的工程计划。

在 GSD 的 Agent 谱系中，planner 不是简单的"任务列表生成器"。它是一个具备完整软件工程思维的架构师角色：

flowchart TB
    subgraph "gsd-planner 能力矩阵"
        A1["需求工程"]
        A2["技术架构"]
        A3["任务分解"]
        A4["风险评估"]
        A5["资源估算"]
        A6["依赖管理"]
    end
    subgraph "输出物"
        B1[ROADMAP.md]
        B2["phases/*.md"]
        B3["技术方案文档"]
        B4["风险登记册"]
    end
    A1 --> B1
    A2 --> B3
    A3 --> B2
    A4 --> B4
    A5 --> B1
    A6 --> B2

与其他 Agent 相比，planner 的独特之处在于它同时承担创造性思维和系统性验证的双重职责：既要产出创新的技术方案，又要确保方案在工程上的可执行性。

---

二、Agent 的角色定义和工作方式

2.1 角色定位：架构师 + 项目经理

gsd-planner.md 在 frontmatter 中明确定义了 Agent 的角色：

---
agent: gsd-planner
role: Strategic Planning Architect
model_tier: reasoning  # 必须使用思考类模型
collaborators:
  - gsd-phase-researcher
  - gsd-plan-checker
  - gsd-spec-writer
context_budget:
  max_tokens: 200000
  reserve_for_checker: 15000
---

这个角色定义包含三个关键信息：

1. model_tier: reasoning：planner 被强制要求使用推理类模型，这与 GSD 其他 Agent（如 executor 可以使用 fast 模型）形成鲜明对比
2. context_budget 管理：planner 拥有最高的上下文预算（200K tokens），但会为 plan-checker 预留 15K tokens 的验证空间
3. 协作者网络：planner 不是孤立的，它明确知道自己可以与 researcher、checker、spec-writer 协作

2.2 工作模式：多轮对话 + 结构化输出

planner 的工作方式遵循一个固定的五阶段循环：

sequenceDiagram
    participant User as "用户/命令"
    participant Planner as gsd-planner
    participant Context as ".planning/ 上下文"
    participant Checker as gsd-plan-checker

    User->>Planner: 触发规划（idea / ROADMAP / 需求变更）
    Planner->>Context: 读取 PROJECT.md + REQUIREMENTS.md
    Planner->>Planner: 阶段1：需求解构
    Planner->>Planner: 阶段2：技术方案设计
    Planner->>Context: 读取 references/（如存在）
    Planner->>Planner: 阶段3：任务分解
    Planner->>Planner: 阶段4：Chunked Plan 组装
    Planner->>Checker: 提交计划验证
    Checker->>Planner: 验证报告（通过/缺陷列表）
    alt 验证失败
        Planner->>Planner: 阶段5：计划修订
        Planner->>Checker: 重新提交验证
    end
    Planner->>Context: 写入 ROADMAP.md + phases/*.md
    Planner->>User: 返回规划摘要

2.3 上下文注入策略

planner 的 46KB 定义中，很大一部分是上下文注入规则。GSD 采用 XML 格式化的结构化 prompt，确保 planner 在接收上下文时不会"迷失"：

<planner_context>
  <project>
    <name>{project_name}</name>
    <tech_stack>{tech_stack}</tech_stack>
    <constraints>{constraints}</constraints>
  </project>
  <requirements>
    <functional>{fr_list}</functional>
    <non_functional>{nfr_list}</non_functional>
  </requirements>
  <existing_state>
    <roadmap>{current_roadmap}</roadmap>
    <completed_phases>{completed}</completed_phases>
    <active_phase>{active}</active_phase>
  </existing_state>
  <references>
    <research_docs>{research_summaries}</research_docs>
    <spike_reports>{spike_findings}</spike_findings>
  </references>
</planner_context>

这种 XML 结构化注入的好处是：

• 语义明确：每个标签有明确含义，减少模型理解偏差
• 层级清晰：项目 → 需求 → 状态 → 参考文档，层次分明
• 易于裁剪：可以根据上下文预算，选择性注入某些标签内容

---

三、需求分解策略

3.1 从模糊想法到结构化需求

planner 的第一步是需求解构（Requirement Deconstruction）。GSD 不假设用户输入是结构化的——它可能是一句话、一段描述，甚至是一系列零散的想法。

planner 采用五维需求提取框架：

维度	提取目标	输出格式
功能需求（FR）	系统必须做什么	FR-001 ~ FR-NNN，带优先级 P0/P1/P2
非功能需求（NFR）	系统必须做到什么程度	NFR-001 ~ NFR-NNN，带量化指标
约束条件	不可逾越的边界	技术约束、时间约束、预算约束
假设前提	规划成立的基础	ASSUME-001，需在执行中验证
风险因素	可能导致计划失败的因素	RISK-001，带概率和影响评估

flowchart LR
    A["用户输入"] --> B{结构化程度?}
    B -->|"自然语言描述"| C["Dream Extraction"]
    B -->|"部分结构化"| D["补全与规范化"]
    B -->|"完全结构化"| E["直接解析"]
    C --> F["五维需求框架"]
    D --> F
    E --> F
    F --> G["FR 列表"]
    F --> H["NFR 列表"]
    F --> I["约束/假设/风险"]

3.2 需求依赖图构建

提取需求后，planner 会构建需求依赖图（Requirement Dependency Graph）：

flowchart TD
    FR001["FR-001: 用户注册"] --> FR002["FR-002: 用户登录"]
    FR001 --> FR003["FR-003: 邮箱验证"]
    FR002 --> FR004["FR-004: 密码重置"]
    FR002 --> FR005["FR-005: JWT Token 颁发"]
    FR005 --> FR006["FR-006: API 鉴权中间件"]
    FR006 --> FR007["FR-007: 受保护资源访问"]

    NFR001["NFR-001: 响应时间 < 200ms"] -.-> FR002
    NFR002["NFR-002: 密码 bcrypt 加密"] -.-> FR001

依赖图的构建遵循三条规则：

1. 功能依赖：A 功能必须在 B 功能之前实现（如必须先注册才能登录）
2. 数据依赖：A 功能产生的数据是 B 功能的输入（如必须先设计 Schema 才能写 Repository）
3. 技术依赖：A 技术是 B 技术的基础（如必须先配置数据库连接才能写 Migration）

3.3 需求优先级动态评估

planner 不是静态地分配 P0/P1/P2，而是基于四象限动态评估：

quadrantChart
    title 需求优先级四象限
    x-axis 低业务价值 --> 高业务价值
    y-axis 低技术风险 --> 高技术风险
    quadrant-1 高风险高价值：重点攻坚
    quadrant-2 低风险高价值：快速交付
    quadrant-3 低风险低价值：延后或裁剪
    quadrant-4 高风险低价值：Spike 验证或放弃
    "FR-001 用户注册": [0.8, 0.2]
    "FR-010 实时协作": [0.9, 0.8]
    "FR-015 深色模式": [0.3, 0.1]
    "FR-020 区块链存证": [0.4, 0.9]

这种动态评估让 planner 能够在资源有限时做出更合理的取舍，而不是机械地按照用户声明的优先级执行。

---

四、技术方案设计

4.1 架构决策记录（ADR）

planner 在技术方案设计阶段会生成架构决策记录（Architecture Decision Records）。这些记录不是形式化的文档，而是嵌入在 plan 中的思考轨迹：

## ADR-001: 数据库选型

**上下文**：项目需要支持高并发读写，数据关系复杂。

**考虑方案**：
- PostgreSQL + Redis：关系型 + 缓存，成熟稳定
- MongoDB：灵活 Schema，适合快速迭代
- TiDB：分布式 NewSQL，水平扩展

**决策**：PostgreSQL + Redis

**理由**：
1. 数据关系复杂（用户-订单-支付-物流），关系型数据库更适合
2. 团队已有 PostgreSQL 运维经验
3. ACID 事务对金融相关操作是硬性要求

**风险**：单节点 PostgreSQL 可能成为瓶颈，需在 Phase 3 评估读写分离

每个 ADR 包含五个要素：上下文、考虑方案、决策、理由、风险。这种结构化的决策记录使得 plan-checker 可以回溯验证每个技术选择的合理性。

4.2 技术栈一致性检查

planner 在设计技术方案时，必须遵守 PROJECT.md 中声明的技术栈约束：

flowchart LR
    A["PROJECT.md
tech_stack"] --> B{planner 技术方案}
    B -->|"一致"| C["继续规划"]
    B -->|"偏离"| D{是否有理由?}
    D -->|"有（性能/兼容性/生态）"| E["生成 ADR 说明偏离原因"]
    D -->|"无"| F["回退到声明技术栈"]
    E --> C
    F --> C

如果 planner 建议使用未声明的技术（例如在 React 项目中引入 Vue），它必须提供充分的 ADR 论证。plan-checker 会在验证阶段重点检查这些偏离项。

4.3 与 references/ 文档的协作

当项目目录中存在 references/ 文件夹时，planner 会将其视为权威信息源。

sequenceDiagram
    participant Planner as gsd-planner
    participant Refs as references/*.md
    participant Plan as "生成的 Plan"

    Planner->>Refs: 扫描 references/ 目录
    Planner->>Refs: 读取相关研究文档
    Refs->>Planner: 技术选型建议、竞品分析、架构参考
    Planner->>Planner: 将研究发现融入技术方案
    Planner->>Plan: 在 Plan 中引用 references
    Plan->>Plan: 标注 ["REF: research-auth-20260420"]

引用格式采用 [REF: filename] 标记，例如：

## 认证方案

采用 OAuth 2.0 + JWT 的混合认证模式 [REF: research-auth-protocols-20260420]。

根据研究文档的对比分析：
- Session 方案：适合传统服务端渲染，但不符合本项目 SPA 架构 [REF: research-auth-20260420#section-3]
- 纯 JWT：无状态，适合微服务，但注销和续期较复杂
- OAuth 2.0 + JWT：支持第三方登录，同时保持无状态优势

这种引用机制的好处是：

• 可追溯：每个技术决策都有信息来源
• 可更新：当 references 更新时，plan-checker 可以标记需要重新评估的 plan
• 可验证：reviewer 可以对照原始研究验证决策是否合理

---

五、任务分解和计划生成

5.1 分层分解模型

planner 的任务分解采用四阶分层模型：

层级	粒度	时间跨度	负责人	存储位置
Epic	子系统/业务域	2-4 周	架构师	ROADMAP.md
Milestone	可交付功能集	3-7 天	技术 Lead	ROADMAP.md
Task	单次开发单元	2-4 小时	开发者/Agent	phases/*.md
Sub-task	最小执行单元	15-30 分钟	开发者/Agent	phases/*.md

flowchart TD
    A["项目目标"] --> B1["Epic: 用户系统"]
    A --> B2["Epic: 订单系统"]
    A --> B3["Epic: 支付系统"]

    B1 --> C1["Milestone: 注册登录"]
    B1 --> C2["Milestone: 用户管理"]
    B2 --> C3["Milestone: 购物车"]
    B2 --> C4["Milestone: 订单流转"]

    C1 --> D1["Task: API 设计"]
    C1 --> D2["Task: 密码安全实现"]
    C1 --> D3["Task: 前端登录页"]

    D2 --> E1["Sub-task: bcrypt 集成"]
    D2 --> E2["Sub-task: 密码强度校验"]
    D2 --> E3["Sub-task: 加盐策略实现"]

5.2 任务元数据规范

每个 Task 必须包含完整的元数据：

---
task_id: T-001
epic: 用户系统
milestone: 注册登录
title: 实现用户注册 API
priority: P0
estimated_effort: 2h
assigned_to: gsd-executor
acceptance_criteria:
  - 接受 email + password 输入
  - 密码使用 bcrypt 哈希（cost >= 12）
  - 返回 201 和用户信息（不含密码）
  - 邮箱重复时返回 409
dependencies: []
references:
  - research-auth-20260420
  - SPEC-user-auth.md
---

这个元数据结构有五个设计意图：

1. task_id：全局唯一标识，便于在 STATE.md 中追踪状态
2. acceptance_criteria：明确的完成定义，消除"做完了吗"的歧义
3. estimated_effort：工作量估算，用于上下文预算规划
4. assigned_to：指定执行 Agent，实现 Agent 间的任务路由
5. references：关联参考资料和 SPEC，确保执行时有据可依

5.3 Chunked Planning 的内部实现

planner 的 46KB 定义中，约 12KB 专门描述 Chunked Planning 算法。这是 GSD 规划系统的核心创新之一。

Chunked Planning 的本质是将一个大规划问题分解为多个独立的子规划问题，每个子问题在独立的上下文窗口中解决：

flowchart LR
    A["完整需求"] --> B{按 Chunk 拆分}
    B --> C1["Chunk 1: 基础设施"]
    B --> C2["Chunk 2: 数据层"]
    B --> C3["Chunk 3: 业务层"]
    B --> C4["Chunk 4: 接口层"]

    C1 --> D1["上下文窗口 1"]
    C2 --> D2["上下文窗口 2"]
    C3 --> D3["上下文窗口 3"]
    C4 --> D4["上下文窗口 4"]

    D1 --> E1["子计划 1"]
    D2 --> E2["子计划 2"]
    D3 --> E3["子计划 3"]
    D4 --> E4["子计划 4"]

    E1 --> F["Stitch Point 接口定义"]
    E2 --> F
    E3 --> F
    E4 --> F
    F --> G["完整计划组装"]

Chunk 间的"缝合点"（Stitch Point） 是关键设计：

## Chunk 1 输出接口

```typescript
// Chunk 1 完成后，以下接口必须可用
interface IDatabaseConnection {
  connect(): Promise<void>;
  query(sql: string, params: any[]): Promise<any[]>;
  transaction(fn: (trx: ITransaction) => Promise<void>): Promise<void>;
}

Chunk 2 输入假设

// Chunk 2 假设以下接口已存在
interface IDatabaseConnection {
  connect(): Promise<void>;
  query(sql: string, params: any[]): Promise<any[]>;
  transaction(fn: (trx: ITransaction) => Promise<void>): Promise<void>;
}

planner 在生成每个 Chunk 时，只向当前上下文注入：
- 上游 Chunk 的**输出接口定义**（而非实现细节）
- 全局约束（技术栈、编码规范、安全要求）
- 本 Chunk 对应的需求子集

这种"接口驱动"的 Chunk 间通信，使得各 Chunk 可以独立演进，同时保证最终组装后的计划是**一致且连贯**的。

---

## 六、gsd-plan-checker 深度解析

### 6.1 职责定位

如果说 planner 是"创造者"，那么 `gsd-plan-checker` 就是"质检员"。它的职责不是生成计划，而是**以批判性视角审查计划的质量**。

plan-checker 的核心设计哲学是：**任何由 AI 生成的计划都必须经过独立验证**，就像人类架构师的设计需要 Code Review 一样。

<pre class="mermaid">flowchart TB
    subgraph "gsd-plan-checker 验证维度"
        V1["完整性检查"]
        V2["一致性检查"]
        V3["可行性检查"]
        V4["可追踪性检查"]
        V5["依赖合理性检查"]
        V6["上下文预算检查"]
    end
    subgraph "输出"
        R1["通过"]
        R2["缺陷报告<br/>含严重等级和修复建议"]
    end
    V1 --> R2
    V2 --> R2
    V3 --> R2
    V4 --> R2
    V5 --> R2
    V6 --> R2
    V1 -.-> R1
    V2 -.-> R1
    V3 -.-> R1
    V4 -.-> R1
    V5 -.-> R1
    V6 -.-> R1</pre>

### 6.2 验证检查项详解

#### 6.2.1 完整性检查（Completeness）

完整性检查确保计划**覆盖所有需求**，没有遗漏：

<pre class="mermaid">flowchart LR
    A[REQUIREMENTS.md] --> B{每个 FR/NFR}
    B -->|"有对应 Task"| C["标记覆盖"]
    B -->|"无对应 Task"| D["记录遗漏"]
    C --> E["覆盖率统计"]
    D --> E
    E --> F{覆盖率 >= 95%?}
    F -->|"是"| G["通过"]
    F -->|"否"| H["失败：需求遗漏"]</pre>

检查规则：
- 每个 FR 必须至少有一个 Task 直接对应
- 每个 NFR 必须有相应的验收标准或验证 Task
- 约束条件必须在 Plan 中有体现（如"使用 TypeScript"必须反映在技术栈选择中）

#### 6.2.2 一致性检查（Consistency）

一致性检查确保计划**内部没有矛盾**：

| 检查类型 | 示例 |
|---------|------|
| **技术栈一致** | Task A 使用 Prisma，Task B 使用 TypeORM → 冲突 |
| **命名一致** | 一个模块在 Task 1 中叫 `UserService`，在 Task 2 中叫 `UsersService` → 需统一 |
| **接口一致** | Chunk 1 输出接口与 Chunk 2 输入假设不匹配 → 需修正 |
| **标准一致** | Task A 要求密码 8 位，Task B 要求密码 6 位 → 冲突 |

#### 6.2.3 可行性检查（Feasibility）

可行性检查评估计划**在现实中能否执行**：

<pre class="mermaid">flowchart TD
    A["计划可行性检查"] --> B["技术可行性"]
    A --> C["资源可行性"]
    A --> D["时间可行性"]

    B --> B1["所需工具在 allowed-tools 列表中?"]
    B --> B2["技术方案符合当前生态成熟度?"]

    C --> C1["分配的 Agent 具备相应能力?"]
    C --> C2["上下文预算足够覆盖所有 Task?"]

    D --> D1["工作量估计是否合理?"]
    D --> D2["里程碑时间是否有缓冲?"]</pre>

plan-checker 使用**经验规则库**进行可行性评估：
- 单个 Task 的工作量不应超过 4 小时（否则应进一步拆分）
- 两个连续 Task 之间应预留 10% 的缓冲时间
- 如果计划涉及未在 `allowed-tools` 中的工具，标记为高风险

#### 6.2.4 可追踪性检查（Traceability）

可追踪性检查确保每个 Task 都有**明确的完成标准和验收方式**：

```markdown
## 可追踪性检查清单

- [ ] 每个 Task 都有 acceptance_criteria
- [ ] 每个 acceptance_criteria 都是可验证的（避免"良好"、"优化"等模糊词）
- [ ] 每个 Task 都有 task_id，便于在 STATE.md 中追踪
- [ ] 每个 Task 都关联了对应的 FR/NFR
- [ ] 高风险 Task 有回滚策略

6.2.5 依赖合理性检查

依赖检查的核心是检测循环依赖和过度耦合：

flowchart TD
    A["构建依赖图"] --> B["检测循环依赖"]
    B -->|"发现循环"| C["标记失败：循环依赖"]
    B -->|"无循环"| D["检测依赖深度"]
    D --> E{最长依赖链 > 5?}
    E -->|"是"| F["警告：依赖链过长，建议解耦"]
    E -->|"否"| G["通过"]

plan-checker 还会检查"隐式依赖"——两个 Task 虽然没有显式声明依赖关系，但修改其中一个会影响另一个。这类依赖通常通过接口变更分析发现。

6.2.6 上下文预算检查

这是 GSD 特有的检查项——评估执行计划所需的总 token 消耗是否在预算范围内：

## 上下文预算估算

| 项目 | 估算 Tokens | 说明 |
|------|------------|------|
| PROJECT.md | 2,000 | 固定开销 |
| REQUIREMENTS.md | 3,500 | 固定开销 |
| ROADMAP.md | 1,500 | 固定开销 |
| 当前 Phase Plan | 8,000 | 每个 Phase 约 8K |
| 代码上下文 | 15,000 | 平均加载的文件 |
| 工具调用结果 | 5,000 | 预估工具返回 |
| **总计** | **35,000** | **预算上限：150,000** |

**结论**：预算充足，当前计划可执行。

如果估算超出预算，plan-checker 会建议进一步拆分 Chunk 或采用更粗粒度的规划。

---

七、Planner 与 Plan-Checker 的协作循环

7.1 验证-修订循环

planner 和 plan-checker 的协作是一个闭环质量控制系统：

sequenceDiagram
    participant P as gsd-planner
    participant C as gsd-plan-checker
    participant Plan as "计划文档"

    P->>Plan: 生成初始计划
    P->>C: 提交验证请求
    C->>C: 执行六维检查
    C->>P: 返回验证报告

    alt 全部通过
        C->>Plan: 标记 "checker-approved"
    else 发现缺陷
        C->>P: 返回缺陷列表（含严重等级）
        P->>P: 分析缺陷根因
        P->>P: 针对性修订
        P->>C: 重新提交验证
        C->>C: 执行增量检查
        C->>P: 返回结果
    end

7.2 严重等级与处理策略

plan-checker 发现的缺陷按严重等级分类：

等级	标识	说明	处理策略
CRITICAL	🔴	计划存在根本性缺陷，执行将导致失败	必须修复，否则拒绝输出
HIGH	🟠	重大风险，可能导致严重返工	强烈建议修复
MEDIUM	🟡	中等问题，影响执行效率	建议修复，可接受风险
LOW	🟢	小问题，不影响核心目标	可记录为技术债
INFO	🔵	改进建议	供 planner 参考

修订循环上限：GSD 规定修订循环最多执行 3 次。如果 3 次后仍有 CRITICAL 或 HIGH 缺陷，planner 会降级为粗粒度规划，将详细规划推迟到执行阶段。

flowchart LR
    A["生成计划"] --> B{第1次验证}
    B -->|"通过"| C["输出计划"]
    B -->|"失败"| D["修订"]
    D --> E{第2次验证}
    E -->|"通过"| C
    E -->|"失败"| F["修订"]
    F --> G{第3次验证}
    G -->|"通过"| C
    G -->|"失败"| H["降级为粗粒度规划"]
    H --> I["详细规划推迟到执行阶段"]

7.3 增量验证优化

为了节省 token 和时间，plan-checker 支持增量验证：

• 第 1 次验证：全量六维检查
• 第 2 次及以后：只检查被修改的部分及其直接影响范围

例如，如果 planner 修订了 Chunk 3 的接口定义，plan-checker 只需验证：

1. Chunk 3 内部的完整性
2. Chunk 3 与 Chunk 2 的缝合点一致性
3. Chunk 3 与 Chunk 4 的缝合点一致性

其他未修改的 Chunk 可以直接复用上一次验证结果。

---

八、Planner 与 plan-phase 工作流的关系

8.1 职责边界

在 GSD 的体系结构中，planner 是 Agent，plan-phase 是工作流。它们的关系类似于"演员"和"剧本"：

flowchart TB
    subgraph "plan-phase 工作流（剧本）"
        W1["定义输入输出格式"]
        W2["编排 Agent 调用顺序"]
        W3["管理状态转换"]
        W4["处理异常和边界情况"]
    end
    subgraph "gsd-planner Agent（演员）"
        A1["理解需求"]
        A2["设计技术方案"]
        A3["生成计划内容"]
        A4["与 checker 协作"]
    end
    W1 --> A1
    W2 --> A2
    W3 --> A3
    W4 --> A4

具体边界划分：

职责	plan-phase（工作流）	gsd-planner（Agent）
读取哪些文件	决定	执行
调用哪个 Agent	编排	被调用
计划内容质量	不直接负责	核心职责
验证机制	定义流程	参与执行
输出格式规范	定义模板	填充内容
错误处理策略	定义回退逻辑	报告错误

8.2 数据流

flowchart LR
    A["用户命令"] --> B["plan-phase 工作流"]
    B --> C["读取 .planning/ 上下文"]
    C --> D["注入 planner prompt"]
    D --> E["gsd-planner Agent"]
    E --> F["生成计划内容"]
    F --> G["注入 checker prompt"]
    G --> H[gsd-plan-checker]
    H --> I{验证结果?}
    I -->|"通过"| J["写入 ROADMAP.md + phases/*.md"]
    I -->|"失败"| K["返回修订指令"]
    K --> E
    J --> L["更新 STATE.md"]

plan-phase 负责"流程管理"：什么时候调用 planner、什么时候调用 checker、验证失败后怎么办、最终结果写入哪里。planner 和 checker 则专注于"内容生产"和"内容质检"。

8.3 多 Agent 协作全景

在完整的规划流程中，planner 不是唯一工作的 Agent：

sequenceDiagram
    participant Workflow as "plan-phase 工作流"
    participant Planner as gsd-planner
    participant Researcher as gsd-phase-researcher
    participant Checker as gsd-plan-checker
    participant SpecWriter as gsd-spec-writer

    Workflow->>Planner: 触发规划
    Planner->>Workflow: 请求研究支持
    Workflow->>Researcher: 调用研究 Agent
    Researcher->>Workflow: 返回研究成果
    Workflow->>Planner: 注入研究上下文
    Planner->>Planner: 生成初始计划
    Planner->>Workflow: 提交计划
    Workflow->>Checker: 调用验证
    Checker->>Workflow: 返回缺陷报告
    Workflow->>Planner: 请求修订
    Planner->>Planner: 修订计划
    Workflow->>Checker: 重新验证
    Checker->>Workflow: 验证通过
    Workflow->>SpecWriter: 生成 SPEC（可选）
    SpecWriter->>Workflow: 返回 SPEC.md
    Workflow->>Workflow: 输出最终计划

---

九、模型选择：为什么 planner 需要思考类模型

9.1 规划任务的认知复杂度

规划是软件工程中最需要深度推理的环节。与代码生成（可以将大问题分解为局部模式匹配）不同，规划要求模型具备以下能力：

quadrantChart
    title 不同任务类型的认知需求
    x-axis 低模式匹配 --> 高模式匹配
    y-axis 低全局推理 --> 高全局推理
    quadrant-1 高推理高模式：代码重构
    quadrant-2 低推理高模式：代码补全
    quadrant-3 低推理低模式：文本格式化
    quadrant-4 高推理低模式：架构规划
    "代码补全": [0.9, 0.1]
    "单元测试生成": [0.8, 0.3]
    "代码审查": [0.7, 0.5]
    "Bug 修复": [0.6, 0.4]
    "架构规划": [0.2, 0.9]
    "需求分析": [0.3, 0.85]
    "任务分解": [0.4, 0.8]

架构规划（以及需求分析、任务分解）处于"高全局推理、低模式匹配"象限，这正是**思考类模型（Reasoning Model）**的优势领域。

9.2 快速模型 vs 思考类模型的对比

维度	快速模型（如 GPT-4o-mini）	思考类模型（如 Claude 3.7 Sonnet / o3）
推理深度	浅层，适合单步任务	深层，适合多步因果链
上下文保持	容易在长文本中丢失关键约束	能在大上下文窗口中保持全局一致性
架构设计	倾向于选择最常见的方案	能权衡多种方案，给出非显而易见的创新
风险评估	容易忽略边缘情况	能系统性地识别潜在风险
依赖分析	可能遗漏间接依赖	能构建完整的依赖传递闭包
响应速度	快（秒级）	慢（分钟级）
成本	低	高（5-10x）

9.3 GSD 的模型分层策略

GSD 利用不同模型的特性差异，实现了成本-质量的动态平衡：

flowchart LR
    A["规划阶段"] -->|"使用"| B["思考类模型
Claude 3.7 Sonnet / o3
Gemini 2.5 Pro"]
    B --> C["生成计划"]
    C --> D["执行阶段"]
    D -->|"简单 Task"| E["快速模型
GPT-4o-mini / Haiku"]
    D -->|"复杂 Task"| F["标准模型
GPT-4o / Sonnet"]
    D -->|"需要深度推理"| G["思考类模型"]

核心原则：

• 规划一次性，执行多次：投入高成本模型做规划是值得的，因为一个好的计划能降低后续执行的返工成本
• 错误成本不对称：规划错误的代价（方向错误、架构缺陷）远大于执行错误的代价（单个 Task 失败可以重试）
• 上下文利用率：规划需要处理大量上下文（需求、约束、参考文档），思考类模型的大上下文窗口利用率更高

9.4 planner 的 prompt 设计对模型的要求

planner 的 46KB 定义中包含大量需要深度理解才能正确执行的指令：

## 任务分解规则

1. **独立性原则**：每个 Task 应该是"可独立验证"的——即完成该 Task 后，
   存在一个明确的验收标准可以判断它是否正确完成，而不需要等待其他 Task。

2. **最小耦合原则**：Task 之间的依赖应尽可能少。如果两个 Task 必须共享
   大量上下文，考虑将它们合并为一个 Task。

3. **渐进复杂度原则**：早期 Phase 的 Task 应该比后期 Phase 的 Task 更简单。
   这允许团队在项目的"蜜月期"建立信心，同时降低早期失败的风险。

4. **风险前置原则**：高风险的 Task 应该安排在早期 Phase。如果技术方案
   不可行，越早发现越好。

这些规则不是简单的模板填充，而是需要模型进行价值判断和权衡的。例如"最小耦合原则"与"渐进复杂度原则"在某些情况下可能冲突——早期 Phase 拆得太细会增加耦合，此时模型需要判断哪个原则优先。这种判断正是思考类模型的强项。

---

十、小结

gsd-planner.md（46KB）和 gsd-plan-checker 共同构成了 GSD 规划体系的"双引擎"：

组件	角色	核心能力	输出
gsd-planner	创造者	需求解构、架构设计、任务分解、Chunked Planning	ROADMAP.md + phases/*.md
gsd-plan-checker	质检员	完整性、一致性、可行性、可追踪性、依赖、预算检查	验证报告

它们的设计亮点包括：

1. 分层的职责分离：planner 专注内容生产，checker 专注质量验证，形成创造性思维与批判性思维的互补
2. 结构化的上下文工程：XML 格式化注入、五维需求框架、ADR 决策记录，确保规划过程可追踪、可验证
3. Chunked Planning 算法：通过接口驱动的分块规划，解决大模型上下文溢出和计划僵化问题
4. 闭环质量控制系统：验证-修订循环 + 增量验证优化，确保输出计划的质量
5. 模型分层策略：规划阶段使用思考类模型，充分利用其深度推理能力，降低后续执行风险

GSD 的 46KB planner 定义不是"过度设计"，而是对规划这一复杂认知任务的尊重。在软件工程中，规划质量决定一切——正如 GSD 的核心理念所言："Plan slow, execute fast. A good plan is half the battle won."

---

下一篇预告： 第 24 篇《Executor 与 Debugger》——深入解析 GSD 执行层的核心 Agent：gsd-executor 如何将 plan 转化为代码、gsd-debugger 如何处理执行失败和异常、以及执行-调试循环如何确保每个 Task 高质量完成。如果说 planner 是"运筹帷幄的将军"，那么 executor 和 debugger 就是"冲锋陷阵的士兵和随军军医"——它们共同构成了 GSD 从计划到交付的最后一公里。