ce-plan

制定技术方案

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

ce-brainstorm 通过输出一份“纯需求统一方案”来明确要做什么（WHAT）；ce-plan 在此基础上填充怎么做（HOW）；而 ce-work 则负责落地执行这份可实施的方案。前期做过头脑风暴固然是很好的背景参考，但并非必须——ce-plan 可以基于任何输入开始工作：纯需求方案、旧版需求文档、Bug 报告、功能点子，哪怕是一段粗略的描述都没问题。

只要被直接调用，就始终执行规划流程。 切勿将直接调用判定为“非规划任务”而擅自中断工作流。如果输入信息不够明确，可以通过追问澄清或使用规划引导机制（阶段 0.4）来建立足够的上下文背景——但必须始终保留在规划工作流中。

本工作流的目标是生成一份持久可用的实施方案。它不会去编写代码、运行测试或根据运行时反馈迭代。如果某个问题的解答依赖于“改改代码看看会发生什么”，那属于 ce-work 的职责范围，而非本 Skill 的工作。

强制完成契约

每一个正常交互且生成了方案产物或检查点的 ce-plan 分支，在向用户展示对应的接续提问之前，都算作未完成状态。对于过了阶段 0.1b 的软件实施方案任务，终点线是阶段 5.4 的“生成后交接菜单”。非软件规划分支和方案视角选择分支，则使用它们路由到的参考工作流中的终点交接；如果已经明确跳过后续阶段，切勿强行将其推入阶段 5.4。唯一的例外是纯解答类任务：在给出解答后即可结束，除非通用规划参考文档要求提供保存/分享选项。

对于软件实施方案任务，写入方案文件、运行置信度检查、以及运行或跳过 ce-doc-review 统统属于中间里程碑，不代表任务结束。即便用户的 Prompt 只是简单地说“做个方案”、“写个文档”、“跑一下 ce-doc-review”，这一规则依然适用。唯一的例外是流水线模式（Pipeline Mode，如 LFG 或任意开启了 disable-model-invocation 的上下文），在此模式下，一旦方案文件、置信度检查和无头文档审查完成，下一步操作即交由调用方接管。

在给出任何可能结束软件实施方案任务的回复之前，请确认方案路径已明确、无头审查状态（或记载的跳过状态）已总结，并且已向用户发起提问：“方案已就绪，保存路径为 <absolute path to plan>。接下来您想做什么？”如果平台支持阻塞式提问工具，请在工具中发起提问；否则请在对话中列出带编号的交接选项并等待回复。用户选择某项操作后，先执行阶段 5.4 中针对该选项的路由逻辑，随后才可将 Skill 标记为完成。

交互方式

向用户提问时，请优先使用当前平台的阻塞式提问工具：Claude Code 中使用 AskUserQuestion（若未加载 Schema，请先调用 ToolSearch 传入 select:AskUserQuestion）；Codex 中使用 request_user_input；Antigravity CLI (agy) 中使用 ask_question；Pi 中使用 ask_user（需安装 pi-ask-user 扩展）。仅当当前环境不存在阻塞式工具或调用报错（例如 Codex 的编辑模式）时，才回退到在对话中显示带编号的选项并等待回复——切勿仅因需要加载 Schema 就放弃使用工具。绝不能静默跳过提问。

每次仅提一个问题。如果有现成的备选项，优先提供简洁的单选菜单。

功能描述与需求输入

功能描述（feature description） 是调用本 Skill 时传入的初始输入——即需要规划的内容，可以来自当前 Prompt 或对话上下文，无论是由用户直接提供，还是由上游 Skill（如 mode:pipeline 下的 lfg）传递而来。

如果未提供任何功能描述，请主动询问用户： “您想要规划什么内容？请描述您心中的任务、目标或项目。” 然后等待用户回复后再继续。

若已提供输入但不够清晰或描述不全，切勿直接中断——请抛出一两个澄清问题，或进入阶段 0.4 的规划引导机制来收集足够的上下文。最终目标始终是协助用户完成规划，而不是退出工作流。

重要提示：方案文档中的所有文件引用必须使用相对于仓库的相对路径（例如 src/models/user.rb），绝不能使用绝对路径（例如 /Users/name/Code/project/src/models/user.rb）。此规则适用于所有地方——包含实现单元的文件列表、设计模式参考、原始文档链接以及正文中的文本提及。绝对路径会导致跨机器、跨 Worktree 及团队协作时路径失效。

产物根目录

本 Skill 会将方案写入 <root>/plans/ 目录，并从 <root>/solutions/ 目录读取积累的经验方案。当首次需要拼装 <root>/ 路径时（按下方配置块执行），再来解析 <root> 的具体位置，切勿提前解析。向 <root>/... 写入或从 <root>/solutions/ 读取都属于拼装 <root>/ 路径的操作，均会触发解析；只有完全不触及 <root>/ 路径的运行（如纯草稿或无仓库流程）才可以跳过。解析后的实际路径应直接传递给子 Agent，而非传递配置文件。

<!-- ce-docs-root:start -->
在拼装任何产物路径之前，必须先解析出 CE 产物的根目录 <root>。

• 读取配置：优先从 <repo-root>/.compound-engineering/config.local.yaml 读取 docs_root，若无则读取 config.yaml；以首个非空值为准（其中 <repo-root> 通过 git rev-parse --show-toplevel 获取）。若均未配置 -> <root> 默认取 docs，与此前保持一致。
• 校验配置值：确保该值为相对仓库路径的目录，且解析符号链接后的真实路径依然留在仓库内部，既不能是仓库根目录，也不能在 .git/ 目录下。若校验不通过，直接报错抛出 docs_root 及其错误值并终止——绝不静默回退到 docs。
• 使用路径：将 <root> 作为唯一的产物存放位置：若目录不存在则自动创建，后续所有路径均按 <root>/<subdir> 拼接（带上本 Skill 专属的子目录），且不再去读取默认的 docs。
  <!-- ce-docs-root:end -->

核心原则

1. 以产品契约为唯一事实来源（Single Source of Truth） - 如果 ce-brainstorm 已经生成了一份纯需求统一方案，规划过程应当在此基础上原地补充与深化，而非重新发明行为逻辑或另起炉灶创建第二个产物。
2. 聚焦技术决策，而非撰写代码 - 重点梳理实现思路、边界范围、涉及文件、依赖项、风险点及测试场景。切勿预先编写实现代码或 Shell 命令排期。如果伪代码草图或 DSL 语法有助于评审人员校验技术方向，欢迎适度使用——但必须明确声明其仅作为方向性指导，而非具体的实现规范。
3. 先调研，后结构化 - 在定稿方案前，视情况深入探索代码库、团队内部沉淀的经验库以及外部参考指南。
4. 方案体量动态适配 - 小需求对应精简版方案，大工程对应更具结构化的方案。无论深度如何变化，核心理念始终如一。
5. 明确区分“规划期探索”与“执行期探路” - 在规划阶段彻底解决设计层面的疑问；将属于执行阶段的未确定因素显式推迟到具体实现时处理。
6. 保持方案的通用可移植性 - 方案文档应能独立作为动态更新的文档、评审产物或 Issue 正文使用，切勿嵌入绑定特定工具或执行器的指令。
7. 按需轻量体现执行导向 - 当需求、原始文档或仓库上下文明确提示需要“测试先行验证（Test-first）”、“特征测试覆盖（Characterization coverage）”、“冒烟优先验证”等非默认执行方向时，在方案中通过自然语言进行轻量化提示即可。无需将其定义为固定的枚举值，也不必把方案写成事无巨细的步骤清单。
8. 尊重用户指定的资源 - 当用户明确提到了某个特定资源（如 CLI、MCP 服务、URL、文件、文档链接或先前的产物）时，请将其视为权威输入而非仅作参考。遇到未知的资源，先通过工具探索验证（如 command -v、抓取页面、读取文件），不要直接假设其不可用。优先使用该资源替代通用方案；若资源确实不存在或调用失败，应明确告知用户，绝不能悄悄用其他方案替换。

方案质量标准

一份合格的方案应包含以下要素：

• 清晰的问题定义与边界范围
• 可追溯至原始需求或文档的具体需求映射
• 本次变动涉及的文件路径（必须使用相对仓库的路径，绝不能用绝对路径——详见规划规则）
• 包含功能变动的实现单元必须指定明确的测试文件路径
• 包含决策依据与理由，而非单纯的任务清单
• 可供参考的现有代码模式或样例代码引用
• 为每个功能单元列出具体的测试场景，足够详细以确保开发者无需盲目补充测试覆盖
• 明确的依赖关系与执行顺序

当开发者无需方案代写代码就能有条不紊地开始编码时，说明这份方案已经准备就绪。

任务进度可视化

当初始评估确认 ce-plan 将执行多阶段的大型任务时，若当前平台支持任务跟踪功能（Task-tracking），请根据选定的路由路径及后续规划工作，展示一份简短的进度视图。请针对阶段性成果进行跟踪，而不是记录每一个工具调用或细微步骤；仅在触发条件满足时才添加条件任务，并在关键节点更新状态。任务命名应简短且以结果为导向。若平台不支持任务跟踪，正常继续即可，无需在对话中手动伪造任务列表。

工作流

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

0.0 确定输出模式

在触发任何其他阶段之前，必须优先确定 OUTPUT_FORMAT。输出模式具有互斥性——方案要么输出为 Markdown (.md)，要么输出为 HTML (.html)，绝不能同时输出两种格式。优先级顺序为：Prompt 内显式请求 > 用户偏好设定 > 配置文件 > 默认值 (md)，在流水线模式（Pipeline mode）下有强制覆盖规则。

读取配置：在运行时使用 Shell 工具执行 git rev-parse --show-toplevel 来解析出 <repo-root>。随后使用原生文件读取工具读取 <repo-root>/.compound-engineering/config.local.yaml。如果无法解析出根目录（非 Git 仓库）或配置文件不存在，则回退到下述默认逻辑。

具体的解析步骤如下：

1. Prompt 内显式请求：分析用户本次调用的 Prompt 中是否包含对本方案文档输出格式的要求，形式可以是 output: 简写或自然语言描述（如“把方案做成网页”、“我想要 HTML 格式”）。对于明确指定的格式，忽略大小写匹配 md/html；当把 Prompt 的其余部分提取为功能描述时，忽略 output: 标签。注意区分“对文档格式的要求”与“作为需求主题的格式名称”：例如“添加 HTML 导出功能”或“规划 CSV 导入器”属于需求内容本身，而非对方案文档格式的请求——切勿对此类内容误判切模。
   • 仅包含 output:（未填值） → 忽略此项，继续执行步骤 2。
   • output:<未知值>（例如 output:pdf） → 丢弃该标记，继续执行步骤 2。同时请记住，在最终解析完成后，需在生成后菜单上方输出一行提示：Ignored unknown output: value '<value>' — using <resolved_format> instead.（已忽略未知的 output 参数值 '<value>'，改用 <resolved_format> 格式）。注意不要在提示语中硬编码 md，以免当配置项设置为 HTML 时误导用户。
2. 用户偏好设定：若本次 Prompt 未包含格式请求，但用户在此前的会话、记忆中或生效的指令中曾明确过输出格式偏好（Markdown 对比 HTML），且该偏好已在当前上下文中（不区分大小写匹配 md/html），则予以遵循。已记录的用户偏好比很少修改的配置文件更新，因此会覆盖步骤 3 中的配置。无需主动打开或搜索指令文件去查找——仅当偏好已存在于当前上下文时才生效；若不存在，则回退到配置文件。
3. 配置文件：若步骤 1-2 均未解析出...

<!-- （因翻译批次截断；完整正文请见源文件） -->