ce:plan

创建技术计划

注意：当前年份是 2026 年。 在为计划标注日期和搜索最新文档时，请以此为准。

ce:brainstorm 定义要构建什么。ce:plan 定义如何构建。ce:work 执行计划。先前的头脑风暴可作为有用背景，但绝非必需——ce:plan 可以基于任何输入开展工作：需求文档、Bug 报告、功能想法或粗略描述。

直接调用时，始终制定计划。 绝不要将直接调用归类为“非规划任务”并中止工作流。如果输入不清楚，请提出澄清问题，或使用规划引导（阶段 0.4）建立足够的背景，但务必始终留在规划工作流中。

此工作流会生成一份持久的实施计划。它不会编写代码、运行测试或从执行时的结果中学习。如果答案取决于修改代码并观察结果，那就属于 ce:work，而不是这里。

交互方式

如果平台提供提问工具，请使用该工具向用户提问。向用户提问时，如果平台提供阻塞式提问工具，优先使用该工具（Claude Code 中的 AskUserQuestion、Codex 中的 request_user_input、Gemini 中的 ask_user）。否则，在聊天中列出编号选项，并等待用户回复后再继续。

一次只问一个问题。如果有自然的选项，优先采用简洁的单选题。

功能描述

<feature_description> #$ARGUMENTS </feature_description>

如果上方的功能描述为空，请询问用户：“您想规划什么？请描述您考虑的任务、目标或项目。”然后等待用户回复，再继续。

如果提供了输入，但内容不清楚或不够具体，请勿中止——提出一两个澄清问题，或继续使用阶段 0.4 的规划引导来建立足够的背景。目标始终是帮助用户制定计划，而不是退出工作流。

重要：计划文档中的所有文件引用都必须使用相对于仓库的路径（例如 src/models/user.rb），不得使用绝对路径（例如 /Users/name/Code/project/src/models/user.rb）。这适用于所有位置——实施单元文件列表、模式引用、源文档链接和正文提及。绝对路径会导致计划无法在不同机器、工作树和团队成员之间移植。

核心原则

1. 以需求为准——如果 ce:brainstorm 生成了需求文档，规划时应以此为基础，而不是重新定义行为。
2. 确定决策，而非编写代码——记录方案、边界、文件、依赖项、风险和测试场景。不要预先编写实现代码或编排 Shell 命令。如果伪代码草图或 DSL 语法有助于评审者验证方向，可以用它们表达高层技术设计，但必须明确说明它们仅提供方向性指导，而非实现规范。
3. 先研究，再组织结构——定稿计划前，应视需要探索代码库、内部经验和外部指导。
4. 产物大小适当——小型工作采用精简计划，大型工作采用更完整的结构。无论深度如何，理念都保持一致。
5. 将规划与执行阶段的探索分开——在此处解决规划阶段的问题。明确将执行阶段的未知事项留待实施时处理。
6. 确保计划可移植——计划应可作为持续更新的文档、评审材料或 Issue 正文使用，不要嵌入特定工具的执行指令。
7. 必要时简要说明执行方式——如果请求、源文档或仓库背景明确表明应采用测试优先、特征刻画优先或其他非默认执行方式，请在计划中简要注明。不要把计划变成逐步执行编排。

计划质量标准

每份计划都应包含：

• 清晰的问题界定和范围边界
• 可追溯到请求或源文档的具体需求
• 所提工作的相对于仓库的文件路径（绝不能使用绝对路径——请参阅 Planning Rules）
• 对包含功能实现的单元明确列出测试文件路径
• 附有理由的决策，而不只是任务
• 可遵循的现有模式或代码参考
• 为每个包含功能实现的单元列出测试场景，具体到实施者无需自行设想测试覆盖范围
• 明确的依赖关系和执行顺序

当实施者无需计划替其编写代码，也能有信心地开始工作时，计划就准备就绪了。

工作流

阶段 0：恢复、来源与范围

0.1 适时恢复现有计划工作

如果用户提到了现有计划文件，或 docs/plans/ 中有明显匹配的近期计划：

• 阅读该文件
• 确认是原地更新还是创建新计划
• 如果选择更新，保留已完成的复选框，只修改仍然相关的部分

深化意图： 在提及计划时，“深化”（或“进一步深化”）一词是触发深化快速路径的主要信号。用户说“深化计划”“进一步完善我的计划”“进行一轮深化审查”或类似表述时，目标文档是 docs/plans/ 中的计划，而非需求文档。根据用户提供的路径、关键词或上下文确定对应计划。如果提供了路径，请确认该文件确实是计划文档。如果无法明确匹配，请先向用户确认。

单独出现“加强”“信心”“差距”和“严谨性”等词语，并不足以触发深化。这些词也会出现在普通编辑请求中（例如“加强图表部分”“测试场景还有差距”），不应因此启动全面深化审查。只有当请求明确针对整个计划，且未指出要修改的具体章节或内容领域时，才将其视为深化意图；即便如此，也应优先向用户确认，再进入深化流程。

确定计划后，如果计划看起来已完整（包含所有主要章节、已定义实施单元，且 status: active）：

• 如果计划没有 YAML frontmatter（非软件计划使用简单的 # Title 标题和 Created: 日期，而非 frontmatter），应改为使用 references/universal-planning.md 进行编辑或深化，而不是进入第 5.3 阶段。非软件计划不使用软件置信度检查。
• 否则，直接进入第 5.3 阶段（置信度检查与深化），并采用交互模式。这样可以避免重新运行完整的计划流程，并让用户自行决定整合哪些发现。

普通编辑请求（例如“更新测试场景”“添加新的实施单元”“加强风险章节”）不应触发快速路径，而应遵循标准恢复流程。

如果计划已有 deepened: YYYY-MM-DD frontmatter 字段，且用户未明确要求再次深化，快速路径仍会执行相同的置信度差距评估——不会强制进行深化。

0.1b 判定任务领域

如果任务涉及构建、修改或架构设计软件（提及代码、仓库、API、数据库，或要求构建、修改、部署），继续进入第 0.2 阶段。

如果任务属于非软件领域，并描述了值得规划的多步骤目标，请阅读 references/universal-planning.md 并遵循其中的工作流。跳过所有后续阶段。

如果确实存在歧义（例如只说“规划一次迁移”，没有其他上下文），请在确定流程前询问用户。

对于其他所有情况（快速问题、错误信息、事实查询），仅在自动选用此流程时，直接作答，不执行任何规划流程。用户直接调用此流程时，应将输入视为规划请求——如有需要，请提出澄清问题，但不要退出工作流。

0.2 查找上游需求文档

提出规划问题之前，先在 docs/brainstorms/ 中搜索匹配 *-requirements.md 的文件。

相关性标准： 满足以下条件的需求文档即为相关文档：

• 主题与功能描述在语义上相符
• 创建时间在最近 30 天内（可酌情判断并覆盖此标准，前提是文档显然仍然相关或已明显过时）
• 似乎涵盖相同的用户问题或范围

如果有多个源文档符合条件，请在平台提供阻塞式提问工具时使用该工具询问要采用哪份文档（参见“交互方式”）。否则，请在聊天中列出编号选项，并等待用户回复后再继续。

0.3 将源文档作为主要输入

如果存在相关需求文档：

1. 仔细阅读文档
2. 宣布将以该文档作为规划的源文档
3. 继承以下所有内容：
   • 问题框架
   • 需求和成功标准
   • 范围边界
   • 关键决策及其理由
   • 依赖项或假设
   • 未决问题，并保留其属于阻塞问题还是延期处理的问题
4. 将源文档作为规划和调研的主要输入
5. 在计划中通过 (see origin: <source-path>) 引用重要的继承决策
6. 不得默默省略源文档内容——如果源文档讨论了某项内容，计划就必须提及，即使只是一笔带过。定稿前，逐节检查源文档，确认没有遗漏。

如果不存在相关需求文档，可以直接根据用户请求制定计划。

0.4 规划准备（无需求文档或输入不明确）

如果不存在相关需求文档，或输入需要更明确的结构：

• 判断该请求是否已足够清晰，可以直接进行技术规划；如果是，则继续到阶段 0.5
• 如果歧义主要涉及产品定位、用户行为或范围定义，建议使用 ce:brainstorm，但始终也要提供继续在此处规划的选项
• 如果用户想在此处继续（或已明确表示希望制定计划），则执行以下规划准备流程

规划准备应明确：

• 问题框架
• 预期行为
• 范围边界及明显的非目标
• 成功标准
• 阻塞问题或假设

此准备流程应保持简短。它旨在保留直接开始的便利性，而非取代完整的头脑风暴。

如果准备流程发现仍有重大的产品问题未解决：

• 再次建议使用 ce:brainstorm
• 如果用户仍想继续，则必须先明确假设，再进行后续工作

如果准备流程发现其他工作流更适合满足用户需求：

• 症状明确但根因未知（用户描述了故障行为，但尚未找出原因）——宣布规划前需要先进行调查，并加载 ce:debug 技能。规划需要明确要解决的问题；调试则用于查明问题所在。清楚说明流程切换：“规划前需要先进行调查——切换到 ce:debug 以查找根因。”
• 任务明确且可直接执行（根因已知、修复显而易见，无需架构决策）——除继续规划外，也可建议将 ce:work 作为更快捷的替代方案。由用户决定。

0.5 在规划前对未解决问题进行分类

如果源文档包含 Resolve Before Planning 或类似的阻塞问题：

• 在继续之前逐一审查
• 仅当问题确实属于技术、架构或研究问题时，才将其重新归类为由规划负责的工作
• 如果问题会改变产品行为、范围或成功标准，则将其保留为阻塞项

如果仍有真正的产品阻塞项：

• 明确指出这些问题
• 使用平台的阻塞问题工具（如有，参见交互方式）询问用户是否要：
  1. 恢复 ce:brainstorm 以解决这些问题
  2. 将其转化为明确的假设或决策，然后继续
• 在真正的阻塞项解决之前，不要继续规划

0.6 评估计划深度

将工作归入以下某种计划深度：

• 轻量 - 规模小、边界明确、模糊性低
• 标准 - 常规功能或范围明确的重构，有一些技术决策需要记录
• 深入 - 涉及多个方面、具有战略性、高风险或实现工作高度模糊

如果无法确定深度，提出一个有针对性的问题，然后继续。

阶段 1：收集上下文

1.1 本地调研（始终执行）

准备一到两段简洁的规划上下文摘要，作为输入传递给调研 Agent：

• 如果存在源文档，概述该文档中的问题背景、需求和关键决策
• 否则直接使用功能描述

并行运行以下 Agent：

• Task compound-engineering:research:repo-research-analyst（范围：技术、架构、模式。{规划上下文摘要}）
• Task compound-engineering:research:learnings-researcher（规划上下文摘要） 收集：
• 技术栈和版本（用于第 1.2 节，以便做出更准确的外部调研决策）
• 应遵循的架构模式和惯例
• 实现模式、相关文件、模块和测试
• 对计划有实质影响的 AGENTS.md 指引；仅在存在 CLAUDE.md 时将其用作兼容性回退
• 来自 docs/solutions/ 的组织经验

Slack 上下文（选择启用）——绝不自动派发。按条件处理：

• 有可用工具 + 用户已提出请求：将规划上下文摘要传递给 compound-engineering:research:slack-researcher，与其他阶段 1.1 Agent 并行运行。如果源文档包含 Slack 上下文部分，请原样传递，以便调研人员聚焦于信息缺口。将调研结果纳入汇总。
• 有可用工具 + 用户未提出请求：在输出中注明：“检测到 Slack 工具。你可以随时让我搜索 Slack 中的组织上下文，也可以在下次提示中将其纳入。”
• 没有可用工具 + 用户已提出请求：在输出中注明：“用户请求了 Slack 上下文，但当前没有可用的 Slack 工具。请安装并验证 Slack 插件，以启用组织上下文搜索。”

1.1b 检测执行方式信号

判断计划是否应带有轻量级的执行方式信号。

留意以下信号：

• 用户明确要求采用 TDD、测试优先或特征化优先的工作方式
• 源文档要求测试优先实现，或要求对旧代码进行探索性加固
• 本地调研表明目标区域属于旧代码、测试覆盖薄弱或历来脆弱，因此在改变行为前应先补充特征化测试覆盖

如果信号明确，在相关实现单元中默默沿用该方式。

仅当该方式会实质性改变执行顺序或风险，且无法负责任地推断时，才询问用户。

1.2 判断是否需要外部调研

根据源文档、用户提供的信号和本地发现，判断外部调研是否有帮助。

读懂言外之意。 留意迄今为止的对话信号：

• 用户熟悉程度 — 他们是否指出了具体文件或模式？他们很可能熟悉这个代码库。
• 用户意图 — 他们想要快速完成，还是彻底研究？是探索还是执行？
• 主题风险 — 无论用户提供什么信号，安全、支付和外部 API 都需要更加谨慎。
• 不确定程度 — 方案是否明确，还是仍未确定？

利用 repo-research-analyst 的技术背景信息：

repo-research-analyst 的输出包含结构化的技术与基础设施摘要。使用它来更准确地判断是否需要外部调研：

• 如果检测到了具体框架和版本（例如 Rails 7.2、Next.js 14、Go 1.22），将这些精确标识传给 framework-docs-researcher，以便其获取对应版本的文档
• 如果功能涉及扫描发现已在代码库中成熟应用的技术层（例如，规划新的后台任务时，已有 Sidekiq 任务），倾向于跳过外部调研——本地模式可能已经足够
• 如果功能涉及扫描发现尚未应用或应用很少的技术层（例如，规划新的 gRPC 服务时，没有现有的 proto 文件），倾向于进行外部调研——没有可供遵循的本地模式
• 如果扫描检测到了部署基础设施（Docker、K8s、无服务器），在传给下游 Agent 的规划上下文中注明，以便他们考虑部署限制
• 如果扫描检测到的是单体仓库，并将范围限定在某项特定服务，应将该服务的技术背景信息传给下游调研 Agent，而非所有服务的汇总信息。如果扫描仅呈现了工作区映射而未限定范围，则在开始调研前，先根据功能描述确定相关服务

以下情况一律优先考虑外部调研：

• 主题风险高：安全、支付、隐私、外部 API、迁移、合规
• 代码库缺乏相关的本地模式——所需模式的直接示例少于 3 个
• 本地存在相邻领域的模式，但没有完全对应的模式——例如，代码库有 HTTP 客户端，但没有 Webhook 接收器；或有后台任务，但没有事件驱动的发布/订阅。出现此信号说明团队熟悉该技术层，但可能不了解特定领域的陷阱。此时，应围绕具体领域的缺口来制定外部调研查询，而不是泛泛地询问相关技术
• 用户正在探索不熟悉的领域
• 技术扫描发现代码库中相关技术层尚未应用或应用很少

以下情况跳过外部调研：

• 代码库已有成熟的本地模式——存在多个直接示例（而非相邻领域的示例），近期有更新，并遵循当前惯例
• 用户已经清楚预期方案
• 额外的外部信息几乎没有实际价值
• 技术扫描发现相关技术层已有成熟应用，且有现成示例可供参考

继续之前，简要说明决定。示例：

• “你的代码库已有成熟的相关模式。我会跳过外部调研，继续进行。”
• “这涉及支付处理，因此我会先调研当前最佳实践。”

1.3 外部调研（按需）

如果步骤 1.2 表明外部调研有帮助，则并行运行以下 Agent：

• Task compound-engineering:research:best-practices-researcher(planning context summary)
• Task compound-engineering:research:framework-docs-researcher(planning context summary)

1.4 整合研究结果

总结：

• 相关的代码库模式和文件路径
• 相关的组织经验
• 如果已收集，Slack 对话中的组织背景（与此功能相关的先前讨论、决策或领域知识）
• 如果已收集，外部参考资料和最佳实践
• 相关的问题、PR 或先例
• 任何会对计划产生实质影响的约束

1.4b 研究发现外部契约界面后重新分类深度

如果当前分类为 轻量级，且阶段 1 研究发现工作涉及以下任一外部契约界面，则重新分类为 标准：

• 外部系统、CI 或其他代码库会使用的环境变量
• 导出的公共 API、CLI 标志或命令行界面契约
• CI/CD 配置文件（.github/workflows/、Dockerfile、部署脚本）
• 下游使用方导入的共享类型或接口
• 外部 URL 引用或其他系统链接到的文档

这样可以确保执行流程分析（阶段 1.5），并在置信度检查（阶段 5.3）中应用关键部分加分。简要宣布重新分类：“重新分类为标准——此变更涉及具有外部使用方的［环境变量／导出的 API／CI 配置］。”

1.5 流程和边界情况分析（按需执行）

对于 标准 或 深入 计划，或者用户流程是否完整仍不明确时，运行：

• Task compound-engineering:workflow:spec-flow-analyzer（规划上下文摘要、研究发现）

使用输出以：

• 找出缺失的边界情况、状态转换或交接缺口
• 完善需求追踪或验证策略
• 仅添加能实质改进计划的流程细节

阶段 2：解决规划问题

根据以下内容建立规划问题清单：

• 起始文档中待解决的问题
• 在代码库或外部研究中发现的缺口
• 制定实用计划所需的技术决策

对于每个问题，判断应当：

• 在规划期间解决——答案可从代码库上下文、文档或用户选择中得知
• 留待实现期间解决——答案取决于代码变更、运行时行为或执行时的发现

仅当答案会实质影响架构、范围、顺序或风险，且无法负责任地推断时，才询问用户。如有可用的阻塞式提问工具，请使用平台提供的工具（参见交互方式）。

不要在此阶段运行测试、构建应用或探查运行时行为。目标是制定可靠的计划，而非部分执行。

阶段 3：构建计划

3.1 标题和文件命名

• 拟定清晰且便于搜索的标题，使用常见格式，例如 feat: Add user authentication 或 fix: Prevent checkout double-submit
• 确定计划类型：feat、fix 或 refactor
• 按照代码库约定构建文件名：docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
  • 如果 docs/plans/ 不存在，则创建它
  • 检查已有文件中今天日期对应的文件，以确定下一个序号（补零至 3 位，从 001 开始）
  • 描述性名称保持简洁（3-5 个单词），并使用 kebab-case
  • 示例：2026-01-15-001-feat-user-authentication-flow-plan.md、2026-02-03-002-fix-checkout-race-condition-plan.md
  • 避免：缺少序号、使用“new-feature”这类含糊名称、无效字符（冒号、空格）

3.2 利益相关方和影响分析

对于 标准 或 深入 计划，简要考虑此变更会影响哪些人——最终用户、开发人员、运维人员、其他团队——以及这些影响应如何塑造计划。对于跨领域工作，在“系统范围影响”部分注明受影响方。

3.3 将工作拆分为实施单元

将工作拆分为逻辑清晰的实施单元。每个单元应代表一项有意义的变更，实施者通常可以将其作为一个原子提交完成。

好的单元应：

• 聚焦于一个组件、行为或集成接缝
• 通常涉及一小组相关文件
• 按依赖关系排序
• 具体到可以直接执行，无需预先编写代码
• 使用复选框语法标记，以便跟踪进度

避免：

• 耗时 2-5 分钟的微小步骤
• 涉及多个互不相关事项的单元
• 过于笼统、导致实施者仍需自行制定计划的单元

3.4 高层技术设计（可选）

在详细说明实施单元之前，判断概述是否有助于审核者验证预期方案。本节阐明解决方案的整体形态——各部分如何协同，而不规定具体实现。

适合添加的情况：

工作涉及……	最适合的概述形式
DSL 或 API 表面设计	伪代码语法或契约草图
多组件集成	Mermaid 时序图或组件图
数据管道或转换	数据流草图
状态复杂的生命周期	状态图
复杂的分支逻辑	流程图
模式/标志组合或多输入行为	决策矩阵（输入 -> 结果）
形态不明显的单组件工作	伪代码草图

适合跳过的情况：

• 模式成熟的工作，通过文字和文件路径就能完整说明
• 简单的 CRUD 或遵循惯例的变更
• 方案显而易见的轻量计划

选择适合这项工作的表达形式。不要在图表更清晰时默认使用伪代码，反之亦然。

为每个草图加上说明："这展示了预期方案，仅为审核提供方向性指导，并非实现规范。实施 Agent 应将其视为背景信息，而不是需要复现的代码。"

草图应简洁——足以验证方向即可，不要详尽到能直接复制粘贴到生产环境。

3.4b 输出结构（可选）

对于会创建新目录结构（新插件、服务、软件包或模块）的绿地计划，请添加 ## Output Structure 章节，并用文件树展示预期布局。这样审核者可以先了解整体结构，再查看各单元的详细信息。

适合添加的情况：

• 计划会在新的目录层级中创建 3 个或更多文件
• 目录布局本身是一项重要的设计决策

适合跳过的情况：

• 计划仅修改现有文件
• 计划在现有目录中创建 1-2 个文件——各单元的文件列表已足够

文件树用于声明范围，展示预期的输出形态。它并非限制——如果实施过程中发现更合适的布局，实施者可以调整结构。各单元中的 **Files:** 章节仍是每个单元要创建或修改的文件的权威说明。

3.5 定义每个实现单元

每个单元都应包含：

• 目标——此单元要完成什么
• 需求——此单元推进哪些需求或成功标准
• 依赖项——必须先具备什么
• 文件——相对于仓库的文件路径，列出要创建、修改或测试的文件（切勿使用绝对路径）
• 方案——关键决策、数据流、组件边界或集成说明
• 执行说明——可选，仅当此单元适合采用非默认的执行方式时填写，例如先写测试或先进行特征分析
• 技术设计——可选；当此单元的方案不易理解、仅靠文字说明会产生歧义时，可提供伪代码或图示。明确指出这是方向性指导，而非实现规范
• 遵循的模式——应参照的现有代码或惯例
• 测试场景——列出实现者应编写的具体测试用例，其规模应与单元的复杂度和风险相称。考虑下方每个类别，并纳入适用于此单元的各类别场景。简单的配置变更可能只需一个场景；支付流程则可能需要十几个。衡量质量的标准是具体性——每个场景都应说明输入、操作和预期结果，让实现者无需自行构思覆盖范围。对于不涉及行为变更的单元（纯配置、脚手架、样式），填写 Test expectation: none -- [reason]，不要留空。
  • 正常路径行为——核心功能及其预期输入和输出
  • 边界情况（当此单元存在有意义的边界时）——边界值、空输入、nil/null 状态、并发访问
  • 错误和失败路径（当此单元存在失败模式时）——无效输入、下游服务故障、超时行为、权限拒绝
  • 集成场景（当此单元跨越多个层时）——仅靠模拟无法验证的行为，例如“创建 X 会触发回调 Y，进而持久化 Z”。对于涉及回调、中间件或多层交互的单元，必须包含此类场景
• 验证——说明实现者如何通过结果而非 shell 命令脚本判断单元已完成

每个包含功能的单元都必须在 **Files:** 中包含测试文件路径。

谨慎使用 Execution note。适用情况包括：

• Execution note: 先针对请求／响应契约编写一个失败的集成测试。
• Execution note: 修改这个旧解析器前，先添加特征测试覆盖。
• Execution note: 先编写测试，再实现新的领域行为。

不要将单元扩展为字面上的 RED/GREEN/REFACTOR 子步骤。

3.6 将规划阶段与实现阶段的未知项分开

如果某项内容很重要，但目前无法确定，请在延后处理的实现说明中明确记录，而不要假装已在计划中解决。

例如：

• 确切的方法或辅助函数名称
• 实际查看代码后才能确定的最终 SQL 或查询细节
• 取决于实际测试失败情况的运行时行为
• 开始实现后可能发现没有必要的重构

第 4 阶段：编写计划

无论计划深度如何，都应采用统一的规划理念。调整细节的多少，而不是规划与执行之间的界限。

4.1 计划深度指南

轻量级

• 保持计划简洁
• 通常包含 2–4 个实现单元
• 省略价值不大的可选部分

标准

• 使用完整的核心模板；省略对此项工作无帮助的可选部分（包括高层技术设计）
• 通常包含 3–6 个实现单元
• 在相关时纳入风险、延后处理的问题和系统范围的影响

深入

• 使用完整的核心模板，并根据需要加入可选分析部分
• 通常包含 4–8 个实现单元
• 如果有助于提高清晰度，可将单元分组到不同阶段
• 在适当时纳入考虑过的替代方案、文档影响和更深入的风险分析

4.1b 可选的深度计划扩展

对于规模足够大、风险较高或涉及多个方面的工作，添加确实有帮助的章节：

• 备选方案
• 成功指标
• 依赖项 / 前置条件
• 风险分析与缓解措施
• 分阶段交付
• 文档计划
• 运维 / 发布说明
• 仅当未来考量会实质性影响当前设计时，才添加 未来考量

不要将这些章节当作模板套话。只有在能提升执行质量或促进利益相关方达成共识时才添加。

4.2 核心计划模板

省略明显不适用的可选章节，尤其是对于轻量级计划。

---
title: [Plan Title]
type: [feat|fix|refactor]
status: active
date: YYYY-MM-DD
origin: docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md  # include when planning from a requirements doc
deepened: YYYY-MM-DD  # optional, set when the confidence check substantively strengthens the plan
---

# [Plan Title]

## Overview

[What is changing and why]

## Problem Frame

[Summarize the user/business problem and context. Reference the origin doc when present.]

## Requirements Trace

- R1. [Requirement or success criterion this plan must satisfy]
- R2. [Requirement or success criterion this plan must satisfy]

## Scope Boundaries

- [Explicit non-goal or exclusion]


### Deferred to Separate Tasks

- [Work that will be done separately]: [Where or when -- e.g., "separate PR in repo-x", "future iteration"]

## Context & Research

### Relevant Code and Patterns

- [Existing file, class, component, or pattern to follow]

### Institutional Learnings

- [Relevant `docs/solutions/` insight]

### External References

- [Relevant external docs or best-practice source, if used]

## Key Technical Decisions

- [Decision]: [Rationale]

## Open Questions

### Resolved During Planning

- [Question]: [Resolution]

### Deferred to Implementation

- [Question or unknown]: [Why it is intentionally deferred]


## Output Structure

    [directory tree showing new directories and files]


## High-Level Technical Design

> *This illustrates the intended approach and is directional guidance for review, not implementation specification. The implementing agent should treat it as context, not code to reproduce.*

[Pseudo-code grammar, mermaid diagram, data flow sketch, or state diagram — choose the medium that best communicates the solution shape for this work.]

## Implementation Units

- [ ] **Unit 1: [Name]**

**Goal:** [What this unit accomplishes]

**Requirements:** [R1, R2]

**Dependencies:** [None / Unit 1 / external prerequisite]

**Files:**
- Create: `path/to/new_file`
- Modify: `path/to/existing_file`
- Test: `path/to/test_file`

**Approach:**
- [Key design or sequencing decision]

**Execution note:** [Optional test-first, characterization-first, or other execution posture signal]

**Technical design:** *(optional -- pseudo-code or diagram when the unit's approach is non-obvious. Directional guidance, not implementation specification.)*

**Patterns to follow:**
- [Existing file, class, or pattern]

**Test scenarios:**

- [Scenario: specific input/action -> expected outcome. Prefix with category — Happy path, Edge case, Error path, or Integration — to signal intent]

**Verification:**
- [Outcome that should hold when this unit is complete]

## System-Wide Impact

- **Interaction graph:** [What callbacks, middleware, observers, or entry points may be affected]
- **Error propagation:** [How failures should travel across layers]
- **State lifecycle risks:** [Partial-write, cache, duplicate, or cleanup concerns]
- **API surface parity:** [Other interfaces that may require the same change]
- **Integration coverage:** [Cross-layer scenarios unit tests alone will not prove]
- **Unchanged invariants:** [Existing APIs, interfaces, or behaviors that this plan explicitly does not change — and how the new work relates to them. Include when the change touches shared surfaces and reviewers need blast-radius assurance]

## Risks & Dependencies

| Risk | Mitigation |
|------|------------|
| [Meaningful risk] | [How it is addressed or accepted] |

## Documentation / Operational Notes

- [Docs, rollout, monitoring, or support impacts when relevant]

## Sources & References

- **Origin document:** [docs/brainstorms/YYYY-MM-DD-<topic>-requirements.md](path)
- Related code: [path or symbol]
- Related PRs/issues: #[number]
- External docs: [url]

对于较大的 Deep 计划，仅在有用时才通过以下章节扩展核心模板：

## Alternative Approaches Considered

- [Approach]: [Why rejected or not chosen]

## Success Metrics

- [How we will know this solved the intended problem]

## Dependencies / Prerequisites

- [Technical, organizational, or rollout dependency]

## Risk Analysis & Mitigation

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| [Risk] | [Low/Med/High] | [Low/Med/High] | [How addressed] |

## Phased Delivery

### Phase 1
- [What lands first and why]

### Phase 2
- [What follows and why]

## Documentation Plan

- [Docs or runbooks to update]

## Operational / Rollout Notes

- [Monitoring, migration, feature flag, or rollout considerations]

4.3 规划规则

• 所有文件路径都必须相对于仓库——绝不要使用 /Users/name/Code/project/src/file.ts 这类绝对路径。应使用 src/file.ts。绝对路径会导致计划无法在不同机器、工作树和团队成员之间移植。如果计划针对的仓库与文档所在仓库不同，请在计划顶部说明一次目标仓库（例如，**Target repo:** my-other-project），并在全文使用相对于仓库的路径
• 优先使用路径加类 / 组件 / 模式引用，而非脆弱的行号
• 使用 - [ ] 语法，确保实施单元可检查并用于跟踪进度
• 不要包含实现代码——不得包含导入语句、精确的方法签名或特定于框架的语法
• 如果伪代码草图和 DSL 语法有助于表达设计方向，可以将其放在高层技术设计章节和各单元的技术设计字段中。请明确说明它们是方向性指导，而非实现规范
• 如果 Mermaid 图能阐明仅靠文字难以说明的关系或流程，建议使用——数据模型变更可用 ERD，多服务交互可用时序图，生命周期转换可用状态图，复杂分支逻辑可用流程图
• 不要包含 git 命令、提交消息或精确的测试命令步骤
• 不要将实施单元拆解为微小的 RED/GREEN/REFACTOR 步骤
• 不要为了让计划显得完整，就假装执行期间才需回答的问题已有定论

4.4 计划文档中的可视化表达

当计划包含 4 个或更多具有非线性依赖关系的实施单元、系统范围影响中包含 3 个或更多相互作用的界面、概述或问题框架中包含 3 个或更多行为模式 / 变体，或关键技术决策中包含 3 个或更多相互作用的决策或备选方案时，请阅读 references/visual-communication.md，了解图表和表格的使用指南。这里指的是计划结构的可视化内容（依赖关系图、交互图、对比表），而非解决方案设计图；后者见第 3.4 节。

阶段 5：最终审查、写入文件并交接

5.1 写入前审查

定稿前，请检查：

• 计划没有臆造本应在 ce:brainstorm 中定义的产品行为
• 如果没有源文档，有限范围的规划启动流程已建立足够清晰的产品认知，可以负责任地制定计划
• 每项重大决策都有源文档或研究依据
• 每个实施单元都具体、依赖顺序明确，并已做好实施准备
• 如果明确要求或强烈暗示采用测试优先或特征描述优先的方式，相关单元应通过简短的 Execution note 延续这一要求
• 每个包含功能的单元都涵盖所有适用类别的测试场景（正常路径、边缘情况、错误路径、集成）；场景数量应与单元复杂度相称，既不凑数也不遗漏
• 测试场景应明确列出具体输入、操作和预期结果，但不要写成测试代码
• 测试场景为空或缺失的功能单元应标记为不完整——功能单元必须包含实际测试场景，不能只有注释。Test expectation: none -- [reason] 注释仅适用于不包含功能的单元（纯配置、脚手架、样式）
• 明确列出延期事项，不要将其伪装成确定事项
• 如果包含 High-Level Technical Design 部分，应采用适合该工作的形式，保留非规定性表述，且不包含实现代码（不含导入语句、精确签名或特定框架的语法）
• 如果存在按单元划分的技术设计字段，应简洁且侧重方向，而非可直接复制粘贴的内容
• 如果计划创建新的目录结构，Output Structure 树是否有助于评审者了解整体布局？
• 如果 Scope Boundaries 列出的是计划在单独 PR 或任务中完成的事项，它们是否放在 ### Deferred to Separate Tasks 下，而不是与真正的非目标混在一起？
• 依赖关系图、交互图或比较表等视觉辅助内容，是否比单纯阅读文字更有助于读者快速理解计划结构？

如果计划源自需求文档，请重新阅读该文档并确认：

• 所选方案仍符合产品意图
• 保留了范围边界和成功标准
• 阻塞性问题已解决、明确标记为假设，或已提交给 ce:brainstorm
• 计划涵盖了源文档的每个部分——逐节检查，确认没有内容被悄然遗漏

5.2 编写计划文件

必需：在提供任何选项之前，先将计划文件写入磁盘。

使用 Write 工具，将完整计划保存到：

docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md

确认：

Plan written to docs/plans/[filename]

流水线模式： 如果由 LFG、SLFG 等自动化工作流，或任何 disable-model-invocation 上下文调用，请跳过交互式提问。自动做出所需选择，然后继续编写计划。

5.3 信心检查与深化

写入计划文件后，自动评估计划是否需要进一步完善。

两种深化模式：

• 自动模式（计划生成期间的默认模式）：无需征求用户批准即可运行。用户会看到正在完善的内容，但无需做出决定。子 Agent 的发现会直接整合到计划中。
• 交互模式（通过 Phase 0.1 中的重新深化快捷路径激活）：用户明确要求深化现有计划。子 Agent 的发现会逐项呈现，以供审阅。用户可以接受、拒绝或讨论每个 Agent 的发现。只有已接受的发现才会整合到计划中。

交互模式的存在是因为按需深化代表着不同的用户立场——用户已经有一份投入精力完成的计划，并希望谨慎地调整内容。这适用于由此技能生成、手动编写或由其他工具生成的计划。

document-review 与此信心检查的用途不同：

• 当文档需要提升清晰度、简洁性、完整性或范围控制时，使用 document-review 技能
• 当计划结构合理但仍需要更充分的依据时，此信心检查用于强化论证依据、步骤安排、风险处理和系统级思考

流水线模式： 在流水线／禁用模型调用的上下文中，此阶段始终以自动模式运行。无需用户交互。

5.3.1 对计划深度和主题风险分类

根据文档确定计划深度：

• 轻量级——规模小、范围明确、歧义低，通常包含 2-4 个实施单元
• 标准——复杂度适中，包含一些技术决策，通常有 3-6 个单元
• 深入——涉及多个方面、风险高或具有战略重要性，通常包含 4-8 个单元或分阶段交付

建立风险档案。以下情况应视为高风险信号：

• 身份验证、授权或安全敏感行为
• 支付、计费或财务流程
• 数据迁移、回填或持久化数据变更
• 外部 API 或第三方集成
• 隐私、合规或用户数据处理
• 跨界面一致性或多端行为
• 重大发布、监控或运营相关事项

5.3.2 门槛：决定是否深化

• 轻量级计划通常无需深化，除非存在高风险
• 标准计划若仍有一个或多个重要部分内容单薄，通常可从深化中获益
• 深入或高风险计划通常可从有针对性的第二轮审查中获益
• **本地依据不足时的例外规则：**如果 Phase 1.2 因本地模式依据不足（少于 3 个直接示例，或仅能匹配相邻领域）而触发外部研究，则无论计划看起来依据多充分，都必须继续评分。计划建立在不熟悉的领域时，对系统行为的判断更可能是未经验证的假设。评分过程成本很低——如果计划确实完善，评分不会发现问题，并会迅速结束

如果计划看起来已经有充分依据，且不适用本地依据不足例外规则，则报告“信心检查已通过——无需完善任何部分”，并跳至 Phase 5.3.8（文档审查）。无论是否需要深化，文档审查都会运行——这两种工具发现的问题类型不同。

5.3.3–5.3.7 深化执行

需要深化时，请阅读 references/deepening-workflow.md，了解信心评分清单、章节到 Agent 的分派映射、执行模式选择、研究执行、交互式发现审查以及计划综合说明。执行该文件中的步骤 5.3.3 至 5.3.7，然后返回此处执行 5.3.8。

5.3.8–5.4 文档审阅、最终检查和生成后选项

进入此阶段时，请阅读 references/plan-handoff.md，了解文档审阅说明（5.3.8）、最终检查和清理（5.3.9）、生成后选项菜单（5.4）以及问题创建流程。不要提前加载此文件。文档审阅是必须步骤——即使已经运行过置信度检查，也不要跳过。

切勿编写代码！进行研究、作出决策并编写计划。