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/待确认
禁止完整实现体：技术方案只写流程/算法/策略，不写完整代码

核心工作流程

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

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

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

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

按照以下顺序生成文档：

生成 overview.md（战略层）
- 基于 Plan 讨论内容填充
- 必须包含：通俗摘要、目标/非目标、现状与约束、目标架构树、关键类型/接口、影响面清单、任务索引
- 禁止：具体实现代码、完整类实现
生成 taskXX_{subtask}.md（战术层）
- 将 Plan 分解为独立的可执行步骤
- 每个 task 文件对应一个最小闭环的施工单
- 必须包含：通俗摘要、本步目标、范围、变更清单、技术方案、本步契约、验证、DoD
- 禁止：完整实现体
生成 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 独立闭环，可单独验证。

关键规则与约束

红线（必须遵守）

禁止直接编码
- 本阶段产物只能是 .md 文档
- 若出现写 .py/.ts 等实现倾向，必须纠正
禁止编造需求/结论
- 不确定的信息必须写 TODO/待确认
- 不允许为了"完成度"而填充看似合理但未经确认的内容
上下文解耦/自包含
- 生成的文档必须能让"新接手的 Agent 只看这些文档"就能推进开发
- 不依赖回看聊天记录

决策点规则

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

可选内容的填写原则

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

Resources

本 skill 包含以下资源文件：

references/

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

template_dev_overview.md
- 战略层全景图模板
- 包含：通俗摘要、目标/非目标、现状与约束、目标架构树、关键类型/接口、影响面清单、任务索引
- 使用时：基于 Plan 讨论内容填充各章节
template_dev_task_subtaskstep.md
- 战术层施工单模板
- 包含：通俗摘要、本步目标、范围、变更清单、技术方案、本步契约、验证、DoD
- 使用时：为每个独立的开发步骤创建一个 taskXX_*.md 文件
template_dev_task_summary.md
- 审计层验收单模板
- 包含：结果、变更摘要、验证证据、文档同步、问题与解决、后续建议
- 使用时：创建时仅搭建框架（所有内容为 TODO），开发中逐步填写

使用方式

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

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

plan-to-spec

Safety Notice

Copy this and send it to your AI assistant to learn