Plan-to-Spec：上下文固化与施工图生成

Overview

本 skill 扮演"施工监理"角色，不写代码，只将 Plan Mode 的讨论结论固化为可执行的 Markdown 施工图纸。核心目标是上下文序列化（Context Serialization）：将短期对话记忆转录为长期存储文档，作为后续开发（同会话/新会话/Subagent）的唯一可信输入。

何时使用这个 Skill

触发时机：

• 用户确认 Plan 已完成，准备进入开发阶段
• 需要将讨论的架构设计、技术方案固化为文档
• 需要为后续开发提供清晰的施工指南

典型场景：

用户："Plan 讨论完成了，现在帮我生成施工图文档"
用户："把我们刚才讨论的方案整理成开发文档"
用户："准备开始开发，先把任务文档生成好"

不适用场景：

• 直接开发代码（应该先生成文档，再开发）
• Plan 尚未完成或方案不明确
• 简单的单文件修改（无需完整施工图）

核心设计哲学

1. 上下文序列化

将短期对话记忆转录为长期存储文档，确保：

• 新接手的 Agent 只看文档就能推进开发
• 不依赖回看聊天记录
• 上下文解耦、自包含

2. 三层文档架构

• 战略层（overview.md）：架构总览、目标、影响面、任务索引
• 战术层（taskXX_*.md）：可执行的施工单，每个 step 独立闭环
• 审计层（summary.md）：验收框架，开发中逐步填写

3. 关键约束

• 禁止直接编码：本阶段只产出 .md 文档
• 禁止编造需求/结论：不确定的信息写 TODO/待确认
• 禁止完整实现体：技术方案只写流程/算法/策略，不写完整代码

核心工作流程

阶段一：初始化与结构确立

1. 确认任务名称：询问用户任务名称（如 pseudo_section_builder）
2. 创建目录结构：在 docs/dev_notes/{task_name}/ 创建目录
3. 生成文件清单：一次性列出所有要生成的文件（路径 + 用途）
   • overview.md - 战略层全景图
   • task01_{subtask}.md, task02_{subtask}.md, ... - 战术层施工单
   • summary.md - 审计层验收单

目的：避免边写边改结构导致遗漏、重复、漂移。

阶段二：逐一填充文档内容

按照以下顺序生成文档：

1. 生成 overview.md（战略层）

   • 基于 Plan 讨论内容填充
   • 必须包含：通俗摘要、目标/非目标、现状与约束、目标架构树、关键类型/接口、影响面清单、任务索引
   • 禁止：具体实现代码、完整类实现

2. 生成 taskXX_{subtask}.md（战术层）

   • 将 Plan 分解为独立的可执行步骤
   • 每个 task 文件对应一个最小闭环的施工单
   • 必须包含：通俗摘要、本步目标、范围、变更清单、技术方案、本步契约、验证、DoD
   • 禁止：完整实现体

3. 生成 summary.md（审计层）

   • 仅搭建框架，所有正文内容以 TODO 占位
   • 不填写任何事实性内容（避免编造未发生的交付/验证结果）
   • 开发过程中逐步更新

阶段三：交付确认

生成完成后，输出施工图绘制完成报告：

✅ 施工图绘制完成

已在 `docs/dev_notes/{task_name}/` 生成施工图文档：
1. overview.md - 架构总览与任务索引
2. task01_{...}.md - 待执行
3. task02_{...}.md - 待执行
...
n. summary.md - 验收框架（开发中填写）

请确认后开始执行 task01。

文档模板说明

本 skill 提供三个文档模板，位于 references/ 目录：

1. overview.md 模板（战略层）

用途：架构总览，给人和 Agent 快速建立上下文

必须包含的章节：

• 通俗摘要（3~5句）：为什么做/做成什么/怎么做/影响面
• 目标/非目标：明确做什么、不做什么
• 现状与约束：当前状态、痛点、兼容性/性能/依赖约束
• 目标架构树：
  • 目录/包树（代码落点）
  • 模块职责树（概念落点）
  • 依赖规则（可选）
• 关键类型/接口清单：仅名称与用途，不写实现
• 影响面清单：会改动的模块、可能影响的调用方、兼容性注意
• 任务索引：列出所有 taskXX_*.md 的范围与依赖

字数控制：

• 通俗摘要限 3~5 句
• 架构树保持 2~3 层深度
• 清单优先，少段落解释

2. taskXX_{subtask}.md 模板（战术层）

用途：可执行的施工单，给 Coding Agent 执行

必须包含的章节：

• 通俗摘要（3~5句）：本步做什么/怎么做/产出/影响与风险
• 本步目标：最小闭环的交付结果
• 范围：做什么、不做什么
• 变更清单：文件级变更（add/modify/delete + 目的）
• 技术方案：流程/算法/策略，3~6 条 bullet，禁止完整实现体
• 本步契约：只写本步相关的 I/O、边界、错误处理
• 验证：测试点 + 命令 + 预期
• 本步 DoD：完成定义检查清单

字数控制：

• 技术方案 3~6 条 bullet
• 契约表只写"本步相关"
• 验证写"命令 + 预期"一行到两行

3. summary.md 模板（审计层）

用途：验收总结框架，开发中逐步填写

创建时策略：

• 仅搭建框架，所有正文内容以 TODO 占位
• 禁止填写事实性内容（避免编造未发生的交付/验证结果）

包含的章节：

• 结果（状态、已交付、未交付/延期）
• 变更摘要（新增、修改、移除、破坏性变更）
• 验证证据（单测、其他检查）
• 文档同步（勾选清单）
• 问题与解决
• 后续建议

填写时机：开发过程中逐步更新，任务结束时完整填写

使用示例

示例 1：基础使用流程

用户："Plan 讨论完成了，现在帮我生成施工图文档"

Agent（使用 plan-to-spec skill）：
1. 询问任务名称
2. 创建 docs/dev_notes/{task_name}/ 目录
3. 生成文件清单并确认
4. 逐一生成 overview.md、taskXX_*.md、summary.md
5. 输出完成报告

用户："确认，开始执行 task01"
Agent：读取 task01_*.md，按照施工单执行开发

示例 2：处理不确定信息

Plan 讨论中提到："可能需要支持 Redis 缓存，但还没确定"

在 overview.md 中应该写：
- 现状与约束：缓存策略待确认（TODO：确认是否使用 Redis）
- 影响面清单：如启用缓存，需考虑缓存失效策略

在 taskXX.md 中应该写：
- 范围 - 不做：缓存实现（待后续确认）

示例 3：任务分解

Plan 目标：实现伪断面构建功能

分解为 3 个 task：
- task01_data_loader.md：加载电极数据和测量数据
- task02_pseudo_section_builder.md：构建伪断面网格
- task03_visualization.md：可视化输出

每个 task 独立闭环，可单独验证。

关键规则与约束

红线（必须遵守）

1. 禁止直接编码

   • 本阶段产物只能是 .md 文档
   • 若出现写 .py/.ts 等实现倾向，必须纠正

2. 禁止编造需求/结论

   • 不确定的信息必须写 TODO/待确认
   • 不允许为了"完成度"而填充看似合理但未经确认的内容

3. 上下文解耦/自包含

   • 生成的文档必须能让"新接手的 Agent 只看这些文档"就能推进开发
   • 不依赖回看聊天记录

决策点规则

• 决策点为可选项，仅在存在关键取舍时记录
• 何时需要写：架构取舍、兼容策略、性能策略、接口选择、依赖选择
• 没有决策时：写 N/A 或直接移除该节

可选内容的填写原则

• 标注为「可选」的小节：不要求填写
• 若无信息或无必要：写 N/A 或删去该节
• 避免模板驱动的"无意义填充"

Resources

本 skill 包含以下资源文件：

references/

包含三个文档模板，用于生成施工图文档：

1. template_dev_overview.md

   • 战略层全景图模板
   • 包含：通俗摘要、目标/非目标、现状与约束、目标架构树、关键类型/接口、影响面清单、任务索引
   • 使用时：基于 Plan 讨论内容填充各章节

2. template_dev_task_subtaskstep.md

   • 战术层施工单模板
   • 包含：通俗摘要、本步目标、范围、变更清单、技术方案、本步契约、验证、DoD
   • 使用时：为每个独立的开发步骤创建一个 taskXX_*.md 文件

3. template_dev_task_summary.md

   • 审计层验收单模板
   • 包含：结果、变更摘要、验证证据、文档同步、问题与解决、后续建议
   • 使用时：创建时仅搭建框架（所有内容为 TODO），开发中逐步填写

使用方式

生成文档时，参考这些模板的结构和章节，但不是简单复制粘贴：

• 根据实际 Plan 内容填充
• 不确定的信息写 TODO/待确认
• 可选章节可删除或写 N/A
• 保持简洁，避免冗余