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 - 保持简洁，避免冗余