deepen-plan

深化计划

简介

注意：当前年份是 2026 年。 搜索近期文档和最佳实践时请以此为准。

ce:plan 执行第一轮规划。deepen-plan 是第二轮信心检查。

当计划已经存在，且问题不是“这份文档是否清晰？”，而是“这份计划是否充分考虑了相关复杂性和风险？”时，请使用此技能。

此技能不会将计划转变为实施脚本。它会找出薄弱部分，仅针对这些部分开展有针对性的研究，并在原计划中加以完善。

document-review 和 deepen-plan 各有不同用途：

• 当文档需要提升清晰度、简化内容、补充完整性或控制范围时，使用 document-review 技能
• 当文档结构合理，但仍需加强论据、步骤安排、风险处理或全系统考量时，使用 deepen-plan

交互方式

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

一次只问一个问题。存在自然选项时，优先使用简洁的单选题。

计划文件

<plan_path> #$ARGUMENTS </plan_path>

如果上方的计划路径为空：

1. 检查 docs/plans/ 中最近的文件
2. 使用平台的阻塞式提问工具（若可用；参见“交互方式”）询问用户要深化哪个计划。否则，请在聊天中列出编号选项，并等待用户回复后再继续

在获得有效的计划文件路径之前，不要继续。

核心原则

1. 压力测试，而非扩充内容——深化应提升有依据的信心，而不是为了拉长计划而增加内容。

2. 只深入必要之处——聚焦最薄弱的 2-5 个部分，而不是面面俱到地补充内容。

3. 优先选择最简单的执行模式——默认直接综合 Agent 信息。只有当研究范围足够大，导致内联返回所有发现会造成不必要的上下文压力时，才改用基于产物的研究。

4. 守住规划边界——不编写实现代码、不编排 git 命令、不提供精确的测试命令步骤。

5. 使用产物中包含的证据——依据书面计划、其中的 Context & Research、Sources & References 以及（若存在）源文档开展工作。

6. 尊重产品边界——不得虚构新的产品需求。如果深化过程中发现产品层面的缺口，应将其列为开放问题，或转回 ce:brainstorm。

7. 优先处理风险与跨领域影响——工作越危险或关联越广，再进行一轮规划就越有价值。

工作流

阶段 0：加载计划并判断是否值得深化

0.1 阅读计划及支持材料

完整阅读计划文件。

如果计划的 frontmatter 中包含 origin: 路径：

• 同时阅读源文档
• 检查计划是否仍符合产品意图、范围边界和成功标准

0.2 判定计划深度与主题风险

根据文档确定计划深度：

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

同时建立风险概况。以下情况应视为高风险信号：

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

0.3 判断是否需要深化

使用以下默认规则：

• 轻量级计划通常不需要深化，除非风险较高或用户明确提出要求
• 标准计划通常可以从深化中受益，尤其是仍显单薄的重要章节
• 深度或高风险计划通常可以从有针对性的第二轮审查中受益

如果计划看起来已经有足够依据：

• 简要说明这一点
• 建议转到 /ce:work 或使用 document-review 技能
• 如果用户明确要求继续深化，则进行轻量审查，最多深化 1-2 个章节

阶段 1：解析当前 ce:plan 结构

将计划映射到当前模板。查找以下章节或最接近的对应章节：

• Overview
• Problem Frame
• Requirements Trace
• Scope Boundaries
• Context & Research
• Key Technical Decisions
• Open Questions
• High-Level Technical Design（可选概述——伪代码、DSL 语法、mermaid 图或数据流）
• Implementation Units（可能包含各单元的 Technical design 子章节）
• System-Wide Impact
• Risks & Dependencies
• Documentation / Operational Notes
• Sources & References
• 可选的深度计划章节，例如 Alternative Approaches Considered、Success Metrics、Phased Delivery、Risk Analysis & Mitigation 和 Operational / Rollout Notes

如果计划是手动编写的，或使用了不同的标题：

• 按意图而非精确标题名称映射章节
• 如果某章节在结构上存在，只是标题不同，则视为对应章节
• 如果计划确实缺少某个章节，请判断这是符合计划深度的有意省略，还是值得评分的信心缺口

还需收集：

• Frontmatter，包括现有的 deepened: 日期（如有）
• 实施单元的数量
• 列出的文件和测试文件
• 引用的经验总结、模式或外部参考资料
• 哪些章节看似因不必要而省略，哪些则因缺失而省略

阶段 2：评估信心缺口

采用清单优先、风险加权的评分流程。

针对每个章节，计算：

• 触发项数量——符合条件的清单问题数量
• 风险加分——如果该主题风险较高且此章节与该风险有实质关联，则加 1 分
• 关键章节加分——对于 Standard 或 Deep 计划中的 Key Technical Decisions、Implementation Units、System-Wide Impact、Risks & Dependencies 或 Open Questions，加 1 分

满足以下条件的章节可作为候选：

• 总分达到 2 分以上，或
• 在高风险领域得分达到 1 分以上，且该章节具有实质重要性

按得分只选择排名最高的 2-5 个章节。如果用户明确要求深化轻量级计划，则最多选择 1-2 个章节，除非主题风险较高。

示例：

• Key Technical Decisions 章节有 1 项清单触发项，并获得关键章节加分，得 2 分，可作为候选
• 高风险迁移计划中的 Risks & Dependencies 章节有 1 项清单触发项，并获得风险加分，因此也可作为候选

如果计划已有 deepened: 日期：

• 如果各章节得分相近，优先选择尚未得到实质加强的章节
• 只有当已深化的章节得分明显高于其他选项，或用户明确要求再次审查该章节时，才重新审查该章节

2.1 各部分检查清单

使用以下触发条件。

需求追踪

• 需求含糊，或与实现单元脱节
• 缺少成功标准，或下游内容未体现这些标准
• 各单元未能明确推进所追踪的需求
• 未明确延续源头需求

上下文与研究 / 来源与参考资料

• 提到了相关代码仓库模式，但决策或实现单元中从未使用
• 引用的经验或参考资料并未实质性影响计划
• 高风险工作缺少适当的外部或内部依据
• 研究内容过于笼统，未结合此代码仓库或此计划

关键技术决策

• 陈述了决策，却没有说明理由
• 理由未解释权衡或被否决的替代方案
• 决策未关联范围、需求或源头上下文
• 存在明显的设计分歧，但计划未说明为何选择其中一条路径

待解决问题

• 将产品层面的阻碍隐藏为假设
• 将应由规划阶段解决的问题错误地推迟到实现阶段
• 已解决的问题缺少明确依据，未关联代码仓库上下文、研究或源头决策
• 延后处理的事项过于含糊，无法供后续使用

高层技术设计（存在时）

• 草图所用形式不适合当前工作（例如，用伪代码表达时序图会更清晰的内容）
• 草图包含实现代码（导入语句、精确签名、特定框架语法），而非伪代码
• 缺少非指令性的表述，或表述不够清晰
• 草图未关联关键技术决策或实现单元

高层技术设计（不存在时）（仅限 Standard 或 Deep 计划）

• 工作涉及 DSL 设计、API 表面设计、多组件集成、复杂数据流或状态繁杂的生命周期
• 通过可视化表示或伪代码更容易验证关键技术决策
• 实现单元中的方案部分过于单薄，高层技术设计可补充必要的上下文

实现单元

• 依赖顺序不清楚或可能有误
• 未在适当位置明确列出文件路径或测试文件路径
• 单元过大、过于笼统，或被拆分成过多微小步骤
• 方案说明过于单薄，或未指出应遵循的模式
• 测试场景或验证结果含糊不清

系统级影响

• 遗漏受影响的接口、回调、中间件、入口点或功能对等面
• 未充分探讨故障传播
• 在相关情况下，未提及状态生命周期、缓存或数据完整性风险
• 跨层工作缺少充分的集成覆盖

风险与依赖 / 文档 / 运维说明

• 列出了风险，却没有缓解措施
• 在有必要时，缺少有关发布、监控、迁移或支持的说明
• 外部依赖假设薄弱或未说明
• 明显适用的安全、隐私、性能或数据风险未提及

将计划自身的 Context & Research 和 Sources & References 作为依据。如果这些章节引用的模式、经验或风险未影响决策、实现单元或验证，则视为存在信心缺口。

第 3 阶段：选择目标研究 Agent

针对每个选中的章节，选择最少但有用的 Agent。不要运行所有 Agent。每个章节最多使用 1-3 个 Agent，总数通常不超过 8 个 Agent。

在 Task 调用中使用完整限定的 Agent 名称。

3.1 确定性章节到 Agent 的映射

需求追踪 / 待解答问题分类

• compound-engineering:workflow:spec-flow-analyzer：用于发现缺失的用户流程、边缘情况和交接缺口
• compound-engineering:research:repo-research-analyst（范围：architecture, patterns）：用于基于代码仓库梳理模式、惯例，并核实实际实现情况

上下文与研究 / 来源与参考资料缺口

• compound-engineering:research:learnings-researcher：用于查找组织知识和过去已解决的问题
• compound-engineering:research:framework-docs-researcher：用于了解框架或库的官方行为
• compound-engineering:research:best-practices-researcher：用于查找当前的外部模式和行业指导
• 仅当历史原因或先前先例存在实质性缺失时，才添加 compound-engineering:research:git-history-analyzer

关键技术决策

• compound-engineering:review:architecture-strategist：用于评估设计完整性、边界和架构权衡
• 当决策需要超出代码仓库证据的外部依据时，添加 compound-engineering:research:framework-docs-researcher 或 compound-engineering:research:best-practices-researcher

高层技术设计

• compound-engineering:review:architecture-strategist：用于验证技术设计是否准确体现预期方案，并找出缺口
• compound-engineering:research:repo-research-analyst（范围：architecture, patterns）：用于依据现有代码仓库模式和惯例，为技术设计提供依据
• 当技术设计涉及 DSL、API 表面或适合通过外部验证的模式时，添加 compound-engineering:research:best-practices-researcher

实现单元 / 验证

• compound-engineering:research:repo-research-analyst（范围：patterns）：用于确定具体文件目标、应遵循的模式，以及代码仓库特有的执行顺序线索
• compound-engineering:review:pattern-recognition-specialist：用于检查一致性、重复风险，以及与现有模式的契合度
• 当执行顺序取决于用户流程或交接完整性时，添加 compound-engineering:workflow:spec-flow-analyzer

系统级影响

• compound-engineering:review:architecture-strategist：用于分析跨边界影响、接口表面和架构连带影响
• 添加与风险相匹配的专门 Agent：
  • compound-engineering:review:performance-oracle：用于分析可扩展性、延迟、吞吐量和资源风险
  • compound-engineering:review:security-sentinel：用于审查身份验证、校验、攻击面和安全边界
  • compound-engineering:review:data-integrity-guardian：用于分析迁移、持久化状态安全、一致性和数据生命周期风险

风险与依赖 / 运维说明

• 使用与实际风险相匹配的专门 Agent：
  • compound-engineering:review:security-sentinel：用于分析安全、身份验证、隐私和攻击风险
  • compound-engineering:review:data-integrity-guardian：用于分析持久化数据安全、约束和事务边界
  • compound-engineering:review:data-migration-expert：用于评估迁移的可行性、回填和生产数据转换风险
  • compound-engineering:review:deployment-verification-agent：用于制定发布检查清单、回滚计划和上线验证方案
  • compound-engineering:review:performance-oracle：用于分析容量、延迟和扩展性问题

3.2 Agent 提示词结构

针对每个选定的章节，传入：

• 第 3.1 节中的范围前缀（例如 Scope: architecture, patterns.），前提是 Agent 支持限定范围的调用
• 简短的计划摘要
• 章节原文
• 选择该章节的原因，包括触发了哪些检查清单条件
• 计划深度和风险概况
• 一个需要回答的具体问题

要求 Agent 返回：

• 能提升计划质量的发现
• 更有力的依据、排序、验证、风险处理或参考资料
• 不要提供实现代码
• 不要提供 shell 命令

3.3 选择研究执行模式

使用可行的最轻量模式：

• 直接模式 - 默认模式。选定的章节数量较少，且父级可安全地直接阅读 Agent 输出时使用。
• 基于产物的模式 - 仅当选定的研究范围足够大，导致直接返回结果会不必要地增加上下文负担时使用。

足以支持采用基于产物的模式的信号：

• 可能有 5 个以上的 Agent 返回有实质意义的发现
• 选定章节的摘录足够长，在多个 Agent 输出中重复会造成浪费
• 主题风险较高，且可能需要大量基于来源的分析
• 平台在大量并行返回时曾出现父级上下文不稳定的问题

如果无法明确证明基于产物的模式合理，就采用直接模式。

第 4 阶段：开展有针对性的研究与审查

使用第 3.3 步中选择的执行模式并行启动选定的 Agent。如果当前平台不支持并行调度，则改为顺序运行。

优先使用本地仓库和机构来源的证据。只有在无法负责任地通过仓库上下文或已有引用来源填补信息缺口时，才进行外部研究。

如果仔细阅读源文档能改进某个选定章节，应先完成阅读，再调度外部 Agent。

4.1 直接模式

让每个选定的 Agent 直接向父级返回发现。

保持返回内容聚焦：

• 只提供最有力的发现
• 提供关键证据或来源
• 说明该发现带来的具体计划改进

如果直接模式下的 Agent 开始生成冗长或重复的内容，请停止并将剩余研究切换为基于产物的模式，避免父级上下文膨胀。

4.2 基于产物的模式

在 .context/compound-engineering/deepen-plan/ 下使用每次运行专属的临时目录，例如 .context/compound-engineering/deepen-plan/<run-id>/ 或 .context/compound-engineering/deepen-plan/<plan-filename-stem>/。

临时目录仅用于当前的深化流程。

对于每个选定的 Agent：

• 向其提供第 3.2 步中所述的相同计划摘要、章节文本、触发原因、深度和风险概况
• 指示其为分配到的章节编写一个精简的产物文件
• 要求其仅向父级返回简短的完成摘要

除非机器可读结构显然更有用，否则优先使用精简的 Markdown 产物。每个产物应包含：

• 目标章节 ID 和标题
• 选择该章节的原因
• 3-7 条能够实质性提升规划质量的发现
• 有来源依据的理由，包括证据来自仓库上下文、源上下文、组织经验、官方文档还是外部最佳实践
• 每条发现所暗示的具体计划变更
• 计划中应明确保留的任何未解决权衡

产物规则：

• 不包含实现代码
• 不包含 shell 命令
• 不包含检查点日志或自诊断
• 不在多个文件中重复通用模板内容
• 不设置评审或合并子流程

综合之前：

• 快速确认每个选定章节至少有一份可用产物
• 如果缺少产物或产物明显格式错误，则重新运行对应 Agent，或针对该章节改用直接模式推理，而不是构建验证流程

如果 Agent 的输出相互冲突：

• 优先采用基于仓库和源上下文的证据，而非通用建议
• 如果冲突涉及库的行为，优先采用官方框架文档，而非二手最佳实践摘要
• 如果仍存在实际权衡，应在计划中明确记录，而不是假装冲突不存在

阶段 5：综合并重写计划

仅强化选定的部分。保持计划连贯，并保留其整体结构。

如果使用了基于产物的模式：

• 阅读计划、起源文档（如果有）以及选定部分的产物
• 同时纳入在中途切换前由直接模式 Agent 内联返回的所有发现，避免早期结果被悄然遗漏
• 一次性完成综合
• 除非用户明确要求再进行一轮，否则不要另设评审、合并或质量审查阶段

允许的更改：

• 阐明或强化决策依据
• 加强需求追溯或对起源文档的忠实度
• 在实施单元的排序不合理时重新排序或拆分
• 补充缺失的模式参考、文件／测试路径或验证结果
• 在有依据时，扩展系统范围的影响、风险或推出处理方案
• 在证据支持更改时，将待解决问题重新归类到 Resolved During Planning 或 Deferred to Implementation
• 在工作需要且当前表述薄弱、媒介不当或缺失但有帮助时，强化、替换或新增“高层技术设计”部分。保留非规定性的表述方式
• 当实施单元的方法不易理解且当前方案说明不充分时，强化或补充各单元的技术设计字段
• 仅在能显著提升执行质量时，添加可选的深度计划部分
• 在前置信息中添加或更新 deepened: YYYY-MM-DD，以标明计划得到了实质性改进

不要：

• 添加实现代码——不得添加导入语句、精确的方法签名或特定框架语法。伪代码草图和 DSL 语法可用于顶层“高层技术设计”部分及各单元的技术设计字段
• 添加 git 命令、提交编排或精确的测试命令配方
• 到处添加通用的 Research Insights 子章节
• 从头重写整个计划
• 在未明确指出的情况下，臆造新的产品需求、范围变更或成功标准

如果研究发现产品层面的歧义，且该歧义可能改变行为或范围：

• 不要在此处擅自决定
• 在 Open Questions 下记录
• 如果问题确实关乎产品定义，建议使用 ce:brainstorm

阶段 6：最终检查并写入文件

写入之前：

• 确认计划在具体方面有所加强，而不只是变长
• 确认规划边界保持不变
• 确认选定的部分确实是最薄弱的部分
• 如果存在起源文档，确认保留了其中的决策
• 确认最终计划的篇幅仍与其深度相称
• 如果使用了基于产物的模式，确认临时产物没有演变成另一套隐藏的计划格式

默认就地更新计划文件。

如果用户明确要求单独的文件，则在 .md 前添加 -deepened，例如：

• docs/plans/2026-03-15-001-feat-example-plan-deepened.md

如果使用了基于产物的模式，且用户没有要求查看临时文件：

• 在计划安全写入后，清理临时目录
• 如果当前平台上无法实际清理，请说明产物留在何处，并指出它们是临时工作流输出

增强后的选项

如果进行了实质性修改，请在平台提供阻塞式提问工具时使用该工具展示后续步骤（参见「交互方式」）。否则，请在聊天中列出带编号的选项，并等待用户回复后再继续。

问题：“已深化 [plan_path] 中的计划。接下来你想做什么？”

选项：

1. 查看差异 - 显示变更内容
2. 运行 document-review 技能 - 通过结构化文档审查改进更新后的计划
3. 启动 ce:work 技能 - 开始实施计划
4. 进一步深化特定部分 - 针对指定部分再进行一轮定向深化

根据用户的选择：

• 查看差异 -> 显示重要新增内容和已更改的部分
• document-review 技能 -> 使用计划路径加载 document-review 技能
• 启动 ce:work 技能 -> 使用计划路径调用 ce:work 技能
• 进一步深化特定部分 -> 询问哪些部分仍显薄弱，并仅针对这些部分再进行一轮定向深化

如果无需进行实质性修改：

• 说明该计划看起来已经有充分依据
• 转而提供 document-review 技能或 /ce:work 作为下一步

绝不编写代码！研究、质疑并强化计划。