Plan 详细指南

概述

spec:brainstorm 定义 WHAT（做什么），spec:plan 定义 HOW（怎么做），spec:work 执行计划。

输入： 需求文档（来自 Brainstorm） 输出： 实施计划（docs/plans/YYYY-MM-DD-NNN-<type>-<name>-plan.md）

Plan 阶段不做：不写代码、不跑测试、不做运行时探索。如果答案取决于改代码看结果，那属于 spec:work。

Plan 执行流程

启动 Plan

bash

# 从需求文档启动
/spec:plan docs/brainstorms/2026-03-30-auth-requirements.md

# 或直接描述需求
/spec:plan "用户认证功能"

计划深度分类

Plan 启动后，AI 会先评估工作复杂度：

深度	适用场景	计划结构
Lightweight	小范围、低模糊度	2-4 个 Implementation Units，省略可选章节
Standard	常规功能或有限重构	3-6 个 Units，完整核心模板
Deep	跨模块、高风险、高模糊度	4-8 个 Units，分阶段交付，含备选方案和风险分析

执行阶段

Phase 0: 溯源与范围评估

查找上游需求文档 — 搜索 docs/brainstorms/*-requirements.md，找到相关文档后以其为主要输入
继承 Brainstorm 决策 — 携带问题框架、需求/验收标准、范围边界、关键决策
无需求文档时的处理 — 模糊度低则直接规划，模糊度高则建议先运行 spec:brainstorm
恢复已有计划 — 如果 docs/plans/ 中有相关计划，可更新或重建

Phase 1: 上下文收集

并行启动研究代理：

代理	职责
`repo-research-analyst`	技术栈、架构模式、实现模式
`learnings-researcher`	搜索 `docs/solutions/` 中的历史经验

高风险场景（安全、支付、外部 API、数据迁移）额外启动：

代理	职责
`best-practices-researcher`	外部最佳实践
`framework-docs-researcher`	框架官方文档

Standard/Deep 计划还会运行 spec-flow-analyzer 分析用户流完整性。

Phase 2: 解决规划问题

将所有待决问题分为两类：

在规划时解决 — 可从代码库、文档或用户选择中得出答案
推迟到实施时 — 依赖代码变更、运行时行为或执行时发现

Phase 3: 结构化计划

将工作拆解为 Implementation Units（实施单元）——每个单元是可独立提交的逻辑工作块。

Phase 4: 写入文件

计划写入 docs/plans/YYYY-MM-DD-NNN-<type>-<name>-plan.md。

Phase 5: 置信度检查与深化

写入文件后，AI 自动评估计划质量：

对每个章节评分（需求追溯、上下文研究、技术决策、实施单元等）
识别薄弱章节
针对性派发研究代理补充
更新计划（不重写，只强化）

计划文档结构

Frontmatter

yaml

---
title: "feat: 用户认证功能"
type: feat
status: active
date: 2026-03-30
origin: docs/brainstorms/2026-03-30-auth-requirements.md
deepened: 2026-03-30  # 置信度检查后自动添加
---

核心章节

章节	说明	适用深度
Overview	变更内容和原因	全部
Problem Frame	用户/业务问题和上下文	全部
Requirements Trace	R1/R2... 追溯到需求文档	全部
Scope Boundaries	明确的不做事项	全部
Context & Research	相关代码模式、历史经验、外部参考	全部
Key Technical Decisions	决策 + 理由	Standard+
Open Questions	分"规划时已解决"和"推迟到实施时"	全部
High-Level Technical Design	伪代码、Mermaid 图、数据流（可选）	Standard+
Implementation Units	具体工作块（见下方详细说明）	全部
System-Wide Impact	交互图、错误传播、状态风险、API 一致性	Deep
Risks & Dependencies	风险 + 缓解措施表	Standard+

Implementation Unit 结构

每个实施单元包含：

- [ ] Unit 1: [名称]

  Goal:           这个单元要达成什么
  Requirements:   对应 R1, R2
  Dependencies:   依赖的 Unit 或外部条件
  Files:
    - Create: path/to/new_file
    - Modify: path/to/existing_file
    - Test:   path/to/test_file
  Approach:       关键设计或排序决策
  Execution note: [可选] 测试优先/特征测试优先/外部委托
  Patterns:       遵循的现有代码模式
  Test scenarios:
    - Happy path:  正常输入 → 预期输出
    - Edge case:   边界值、空输入、并发访问
    - Error path:  无效输入、下游故障、超时
    - Integration: 跨层行为
  Verification:   如何判断单元完成

Execution Note 是轻量信号，告诉 spec:work 采用非默认执行策略：

Execution Note	含义
`test-first`	先写失败测试，再写实现
`characterization-first`	先给遗留代码加特征测试，再修改
`external-delegate`	委托给外部执行器

Deferred to Implementation — 明确推迟的问题，如：

具体方法名/辅助函数命名
最终 SQL 查询细节
依赖实际测试结果的运行时行为
可能不必要的重构

计划完成后

AI 会提供以下选项：

在编辑器中打开 — 人工审阅计划
运行 document-review — 派发 7 个文档审查代理审查计划质量
Start /spec:work — 直接进入实施阶段
Start /spec:work in another session — 在新会话中执行
Create Issue — 创建 GitHub Issue 跟踪

Deep 计划或高风险场景建议先运行 document-review，7 个文档审查代理从产品、安全、可行性等维度审查计划质量。

最佳实践

风险评估矩阵

✅ 需求文档优先 — 有 Brainstorm 产出物时以其为主要输入，不重新定义行为
✅ 决策而非代码 — 记录方案、边界、文件、依赖、风险，不预写实现代码
✅ 研究先行 — 先探索代码库和历史经验，再确定方案
✅ 按大小裁剪 — 小工作用精简模板，大工作用完整模板
✅ 区分规划时和实施时未知 — 明确哪些问题推迟到 Work 阶段解决
✅ 测试场景要具体 — 每个场景有明确的输入和预期输出

常见错误

❌ 在 Plan 中写代码 → ✅ Plan 只做决策，实现留给 spec:work
❌ 忽略需求文档 → ✅ 优先使用 Brainstorm 产出物作为输入
❌ 所有工作不分级 → ✅ 评估 Lightweight/Standard/Deep，按深度裁剪计划
❌ Implementation Unit 过大 → ✅ 每个 Unit 应是可独立提交的小工作块
❌ 测试场景只写"测试登录" → ✅ 列出具体的 Happy/Edge/Error/Integration 场景

下一步

Work 详细指南 — 了解如何执行实施计划
Review 详细指南 — 了解实施后的质量评审
工作流概览 — 查看完整工作流

Plan 详细指南 ​

概述 ​

启动 Plan ​

计划深度分类 ​

执行阶段 ​

Phase 0: 溯源与范围评估 ​

Phase 1: 上下文收集 ​

Phase 2: 解决规划问题 ​

Phase 3: 结构化计划 ​

Phase 4: 写入文件 ​

Phase 5: 置信度检查与深化 ​

计划文档结构 ​

Frontmatter ​

核心章节 ​

Implementation Unit 结构 ​

计划完成后 ​

最佳实践 ​

常见错误 ​

下一步 ​