construction-plan

---
name: construction-plan
description: 把任务清单/审查报告/待办列表变成可跨对话接力执行的施工规划文件（XXX-PLAN.md）：工作包拆分、一个对话一个任务、红线标记、交接日志、整轮验证清单。Turns a task list / audit report / backlog into a cross-session construction plan — work packages, one task per conversation, redline gating, handoff log, verification checklist. 触发词 / Triggers：做施工文件、施工规划、开工规划、把任务编成工作包、做成 FIX-PLAN 那种、接力文档、一个对话一个任务、按顺序接力做、construction plan、work packages、break tasks into packages、one conversation per task。
---

# 施工规划文件生成器（Construction Plan）

**版本：v1.1.0**（变更记录见仓库 README 的 Changelog；生成的 PLAN 文件头部会带模板版本号）

把一份任务来源（审查报告 / TODO 清单 / bug 列表 / 用户口述的多项任务）整理成一份**可跨对话接力执行**的施工规划文件。核心机制：一个对话只做一个工作包（WP），做完勾选 + 写交接日志 + 关对话，下一个 WP 新开对话——靠文件续接，不继承上下文。

## 语言规则（全局）

- **输出语言跟随用户输入语言**：用户用中文 → 生成的 PLAN 文件、汇报、日志全部中文；用户用英文 → 全部英文；其他语言同理。
- 代码标识符、命令、文件路径一律保留英文原文。
- 本 skill 指令自身用中文编写，仅用于指导 AI，不构成对输出语言的限制。

## 何时使用

- 用户说：做施工文件 / 施工规划 / 开工规划 / 把任务编成工作包 / 做成 FIX-PLAN 那种 / 一个对话一个任务 / 按顺序接力做 / construction plan / work packages
- 用户给出 ≥4 项任务的清单或报告，且明显一个对话做不完
- 用户担心上下文过长，要求把任务落到文件里分次做

## 何时不用（禁忌症）

开工前先对照，命中任一条就**不要生成施工文件**，直接告诉用户理由并给出更轻的做法：

- 全部任务一个对话内做得完（约 1 小时工作量、改动 ≤3 个文件）——直接做，套这套机制的开销比上下文损失还大
- 任务少于 4 项且彼此独立——逐条做即可
- 纯调研 / 问答，不产生代码改动——没有施工可言

## 工作流（按顺序执行）

### 第一步：读项目约定
读项目根目录 CLAUDE.md（没有就跳过），提取三样东西：
1. **红线清单**——必须先问用户才允许的操作（如改安全配置、数据结构变更、删大段代码、git 强制操作、生产发布），用于给工作包打 🔴 标记
2. **验证命令**——语法检查、测试套件、启动方式，用于写「验收」和「整轮验证清单」
3. **沟通约定**——语言、结论先行等；若项目未指定，按上方「语言规则」跟随用户

### 第二步：拆工作包
把任务拆成工作包（WP01、WP02…；功能升级类可用 UP 前缀、修复类 FIX 前缀，与项目既有文件呼应），规则：
- **一包 = 一个对话能做完的量。尺子是「要读的文件数 × 陌生程度」，不是代码行数**——吃上下文的是阅读和理解，不是敲键盘。参考线：小包 ≤3 个文件；中包 4~8 个文件或约 250 行；超过就拆 a/b。
- 复杂包可前置一个**只读侦察包**（只调研出方案、零代码改动），实施包引用其结论。
- 同一文件域的相邻任务尽量并包，减少新对话重复读文件。
- **排序**：小而安全的在前 → 红线项居中（需用户拍板，不卡住前面的活）→ 大重构 / 拆文件放最后（它搬动一切，必须等功能全部落定）。
- 标依赖：某包必须在另一包之后做的，写进总览开头的一段话里。

### 第三步：标红线
对照第一步的红线清单逐个 WP 检查，命中即在标题加 🔴，并在包内固定写一句：**开工前先把方案发用户确认，批准后才动手**。项目无红线清单时用通用默认：安全/权限配置变更、数据结构迁移、删除超 50 行代码、git 强制操作、生产发布。

**执行期红线守则**（写进每个 WP 的注意事项或会话纪律）：实施中若发现计划外的红线触点（如原定改渲染层，实际必须动主进程安全配置）→ **立即停下问用户**，不许顺手做完。

### 第四步：生成施工文件
文件名 `XXX-PLAN.md`（XXX 取任务主题，如 AGENT-UPGRADE-PLAN、FIX-PLAN），放项目根目录。结构照下方模板，**一节都不许少**，文件头部保留模板版本号。

### 第五步：挂交叉引用
项目 CLAUDE.md 的「参考资料」（或等效位置）加一行指向新文件；任务来源文档的进度区加一行指回新文件。保证以后的新会话一定能发现这份规划。

### 第六步：大白话汇报
用户多为非技术背景，结论先行说清：文件在哪、共几个包、执行顺序、哪几个是红线要先确认、以后怎么用（新开对话说一句「读 XXX-PLAN.md，做第一个没勾选的包」即可）。语言跟随用户。

## 输出文件的固定结构（模板）

````markdown
# <主题> · 施工规划（XXX-PLAN）

> 本文件由 construction-plan skill v1.1 生成。
> **核心原则：一个对话只做一个工作包（WP）。** 做完、自测、记录、提交、关对话。下一个 WP 新开对话。
> 本文件是进度唯一真相源——每个新对话先完整读本文件（不长），靠状态标记和交接日志续接，不继承上一个对话的上下文。
> 任务来源：<来源文档与章节>。

## 一、会话纪律（每个新对话都要遵守）

### 开工三步
1. `git status` 确认上一个 WP 已提交（工作区有存量脏改动属正常，见存量隔离纪律）。
2. 完整读本文件，找到第一个**未完成**的 WP（未勾选且不带 ✅）；「参考」指向外部文档某节时**只读那一节**。若它带 🔶（进行中）或 ⛔（卡住）标记，先查 git status 与交接日志搞清现场，再接手。
3. 🔴 的 WP ＝红线项，**先把改动方案发用户确认，批准后才动手**。

### 收工五步
1. 自测：<从 CLAUDE.md 提取的验证命令，如 改动文件逐个 node --check；动过 lib/ 跑 npm test；动过 UI 则启动应用验证无报错>。
2. **用大白话向用户总结**（非技术用户，此步强制，固定格式）：

   ```text
   【这次做了什么】一句话概括本次优化
   【原来是什么样】修改前的问题（生活化比喻，别堆术语）
   【现在是什么样】修改后的样子
   【你能感受到什么】用户能感知的变化 / 去哪里验证
   【风险和注意】没有就写「无」
   ```

   要求：整段不超过 200 字；技术词加括号白话解释；用户说「可以」之前不进第 3 步。
3. 勾选本 WP 复选框（状态改 ✅）。
4. 文末交接日志追加一行。
5. 一次提交：`feat(WP01): 一句话` —— 代码 + 本文件同一个 commit。

### WP 状态四态
| 标记 | 含义 | 规则 |
|---|---|---|
| 未开始 | 未勾选、无标记（默认） | —— |
| 🔶 进行中 | 做到一半中断 | **必须**在该 WP 条目下写一行「状态：🔶 停在 <具体位置>」；中止会话前不标记＝失职 |
| ⛔ 卡住 | 等人拍板 / 等外部条件 | 写清「状态：⛔ 等 <谁/什么>」 |
| ✅ 完成 | 复选框勾选 [x] | 交接日志必须已有对应行 |

新会话接手 🔶 包之前，先核对现场（git status / 未提交的半成品 / 交接日志），再决定续做还是推倒重来。

### 验收演化规则
- 验收标准写于动手之前，不可能预见一切。**执行中发现计划外的失败模式 → 立即给该 WP 追加验收项**，并在交接日志「偏差」栏记一笔。
- **安全类 WP 必须含反向用例**（构造攻击 / 滥用输入，断言被拒绝）；没有反向用例的安全改动不算完工。

### 上下文防卡死规则
- **禁止**在一个对话里顺手修下一个 WP，哪怕「就两行」。
- **禁止**整文件读巨文件——Grep 定位后 Read 局部。
- 引用代码位置**用函数名 / 关键词，不是行号**——多轮改动后行号必漂移，行号是快照不是地址。
- 上下文吃紧（大文件读超 3 次、或开始忘前文）→ 立即停，把当前 WP 标 🔶 并写清停在哪，交接日志写「中止：进度到哪、卡在哪」，必要时拆 a/b，新对话续做。
- 不碰版本号与发布流程（除非某个 WP 的内容就是发版）。

### 存量隔离纪律（仅当工作区有大量未提交改动时保留本节，否则整节删掉）
每个 WP 的提交**只允许含本 WP 改动**，不许顺带存量入库。两条路线：
- **Track A（首选）**：备份改前文件 → 用「改前 vs 改后」差异生成只含本 WP 改动的补丁 → 只把补丁加入暂存区（如 `git apply --cached`），存量原样留在工作区。
- **Track B（A 的补丁贴不干净时转轨）**：从干净基线（如 `git show HEAD:文件`）取出原始内容，在基线上施加本 WP 改动，再用 git 底层命令（hash-object / update-index 一类）把重建的内容直接写入暂存区——全程不触碰工作区，用户的未提交改动不会被误伤。

## 二、工作包总览

顺序与依赖：<一段话：按编号做；谁必须在谁之后；🔴 项开工前先出方案；其余独立>。

- [ ] **WP01｜<名称>** [🔴]｜<来源引用>｜`<改动文件>`｜<量级：小/中/大>
  - 做：<具体改什么，可执行，不写虚的>
  - 参考：<来源文档的具体章节>
  - 验收：<具体步骤 + 通过标准，禁止「功能正常」式描述；安全类必带反向用例>
  - （🔴 项必带）**开工前先把方案发用户确认**
  - （大包必带）**过大预案**：拆 WPxxa / WPxxb 两个对话
  - （中断后才出现）状态：🔶 停在 <具体位置> / ⛔ 等 <谁/什么>

## 三、整轮验证清单（全部 WP 完成后，用户照着点一遍）

> 生成要求：面向非技术用户，每条都是「打开 X → 做 Y → 看到 Z 算通过」，禁止「功能正常」式描述。分三档：
>
> **① 自动检查**：逐条命令 + 通过标准（如 `npm test` 全绿、`node --check` 无输出）
> **② 用户手测**：启动方式 + 具体点击路径，每条一步，标清「看到什么算通过」；本轮每个 WP 的用户可感知改动至少对应一条
> **③ 回归抽查**：没改但容易受牵连的模块各一条
>
> 安全类轮次额外一档：**④ 攻击拒绝统计**（反向用例总数 / 通过数，未全过不发布）。
> 末尾固定一条：**出问题怎么反馈**（截图 + 控制台报错 + 应用内诊断导出入口，如有）

## 四、交接日志（每个 WP 收工 / 中止时追加一行）

格式：`日期 | WP编号 | 结果 | 实际改动量 | 与计划的偏差 | 此路不通（试过失败的做法及原因，无则写「无」） | 下个 WP 注意`

「此路不通」一栏是给未来对话的排雷记录：哪种方案试了行不通、为什么，防止下个对话把失败的路再走一遍。

| 日期 | WP | 结果 | 改动量 | 偏差 | 此路不通 | 注意 |
|------|----|------|--------|------|----------|------|
| _示例_ | _WP01_ | _完成_ | _28 行_ | _无_ | _无_ | _WP02 不受影响_ |
````

## 收尾协议（全部 WP 完成后）

最后一个 WP 收工时额外做三件事：
1. 文件头部加一行状态：`> ✅ 本轮施工已完成（YYYY-MM-DD），共 N 个工作包。`
2. 提醒用户：整轮验证清单（第三节）尚未执行则执行；涉及发版的按项目发布流程走。
3. 若任务来源文档还在维护，回去更新它的进度区为「已完成」。

## 质量自检（生成后逐条核对）

- [ ] 已对照「何时不用」，确认本轮确实需要施工文件
- [ ] 每个 WP 自包含：新对话只读本文件 + 指向章节就能开工，不依赖「上个对话说过」
- [ ] 每个 WP 的验收标准可执行、可判定（具体输入 → 预期输出）；安全类 WP 含反向用例
- [ ] 🔴 包都带「先出方案」备注；量级「大」的包都带拆包预案
- [ ] 模板含状态四态表与「引用用函数名不用行号」规则；交接日志含「此路不通」列
- [ ] 整轮验证清单档位齐全，手测条目都是具体点击路径
- [ ] 文件头部带模板版本号；输出语言跟随用户
- [ ] 交叉引用已挂（CLAUDE.md + 来源文档各一行）

## 样例

仓库 `examples/sample-fix-plan.md` 是一份完全脱敏的真实结构样例（含 🔴 红线包、🔶 中断状态、「此路不通」日志条目），生成前可参照它的颗粒度与措辞。