zl585451 Execution Planner — 规划转交付
这个 skill 做什么
读代码 → 分析 → 产出一个可直接喂给 Cursor 的执行计划文件。
文件设计原则：
- Cursor 读文件后无需追问，直接能执行
- 每个 Task 原子化，只做一件事，可独立验证
- 每个 Task 结束有 STOP 点，Cursor 停下生成简报
- 简报格式标准化，GPT 或 Claude 读简报 + 文件就能验收
- 验收通过后的下一步指令预先写好，可直接复制给 Cursor
Claude 做完规划就退出，后续由 Cursor 执行、GPT/Claude 验收，最小化 Claude 使用。
执行流程
Step 1：建立上下文（读代码，不问用户）
主动读取相关文件，自己建立上下文。优先读：
- 目标文件（完整读取）
- 直接依赖文件（import 关系）
- CLAUDE.md / AGENTS.md（了解项目约束）
不要问用户"你想怎么拆"——这正是 Claude 的工作。读完再给判断。
Step 2：识别拆解边界
判断标准：
- 每个 Task 只移动/改动一个关注点
- Task 之间有明确的先后依赖（前一个完成才能开始下一个）
- 每个 Task 完成后验证命令必须通过
- 从风险最低的开始（完全独立的逻辑优先）
常见拆解模式：
- 大文件拆小：按职责提取子模块，每次提取一个
- 逻辑去重：先找共同路径，再提取，最后删除副本
- 类型迁移：先移类型定义，再移实现，最后改引用
- 补测试：每个核心模块单独一个 Task
Step 3：写执行计划文件
保存路径：docs/_archive/<任务名称>-<YYYY-MM>/EXECUTION_PLAN.md
（若 docs/_archive/ 不存在则创建）
使用下方标准模板写文件。
Step 4：输出给用户
只说两件事：
- 文件保存路径（computer:// 链接）
- 第一步让 Cursor 做什么（复制即用的一段指令）
不做长篇解释，不重复文件内容。
执行计划文件标准模板
# [任务名称] 执行计划
> 归档类型：Cursor 执行包
> 创建日期：[日期]
> 目标：[一句话说清楚要做什么]
> 执行者：Cursor
> 验收者：GPT-4 / Claude
> 监督者：[用户名]
---
## 工作流说明
Cursor 读本文件 → 执行当前 Task → 到 STOP 点停下 → 生成简报
→ 用户把简报发给验收方 → 验收通过则继续 → 验收不通过则返工
铁律：
- 每个 Task 只做一件事
- 每步完成必须跑 [验证命令]，通过才算完成
- 每步完成后 git commit 一次
- 不改任何对外接口 / 函数签名 / 字段名
---
## 开始前确认
Cursor 在开始 Task 1 前，执行以下命令并记录结果：
- [ ] [验证命令] → 记录当前错误数（基准线）
- [ ] git status → 确认工作区干净
- [ ] git log --oneline -3 → 记录当前最新 commit
---
## Task 1 — [任务名]
### 背景
[一段话说清楚：为什么做这个，这个逻辑现在在哪，移出去有什么好处]
### 读取文件
```
[精确文件路径，每行一个]
```
### 执行内容
[具体步骤：新建什么文件、签名是什么、修改哪里、删除哪里]
### 约束（禁止触碰）
- 不改 [具体函数/接口/字段名]
- 不动 [具体逻辑块]
- 不改任何调用方文件
### 验证命令
```
[可直接运行的命令]
```
必须：错误数 ≤ 基准线
---
### ⛔ STOP — Task 1 简报模板
Cursor 完成后停下，按以下格式输出简报，不继续执行 Task 2。
```
=== Task 1 简报 ===
【完成状态】已完成 / 未完成（说明原因）
【新增文件】
- [文件路径]（X 行）
【修改文件】
- [文件路径]（原 X 行 → 现 X 行，减少 X 行）
【验证结果】
基准错误数：X
当前错误数：X
结论：通过 / 不通过
【git commit】
commit hash: xxxxxxx
message: "[commit message]"
【移走的内容清单】
[逐条列出，打 ✓/✗]
【对外暴露说明】
新模块是否暴露了不该暴露的内部状态、setter 或 ref？
（有 / 无，如有请列出并说明为何需要暴露）
【遇到的问题】
（无 / 描述问题及处理方式）
【等待验收】将此简报发给验收方，等待指令。
=================
```
---
## Task 2 — [任务名]
> ⚠️ 必须在 Task 1 验收通过后才能开始
[同 Task 1 结构]
---
## 验收方使用指引
每次收到简报，把以下内容 + 简报一起发给验收方（GPT 或 Claude）：
```
你是 [项目名] 的代码审查员。
项目路径：[路径]
项目语言：[语言]
我刚完成了一个重构步骤，简报如下：
[粘贴简报]
请验收：
1. 读取简报列出的所有新增和修改文件
2. 确认新模块职责单一，没有混入其他逻辑
3. 确认被移走的代码在原文件中已删除（无残留副本）
4. 确认对外接口 / 字段名没有变化
5. 重点检查"对外暴露说明"中提到的问题是否需要处理
结论：
✅ 验收通过 → 告诉 Cursor："Task X 验收通过，请执行下一步指令：[下一步内容]"
❌ 验收不通过 → 列出具体问题，告诉 Cursor 修复后重新生成简报
```
---
## 重构完成后的状态
| 文件 | 重构前 | 重构后 | 职责 |
|------|--------|--------|------|
| [原文件] | X 行 | X 行 | [职责] |
| [新文件1] | — | X 行 | [职责] |
完成后建议补充：
- docs/02_architecture/ 对应模块说明
- docs/05_changelog/ 一条变更记录
质量检查清单（写完文件后自查）
- 每个 Task 只改动一个关注点？
- Task 顺序从风险最低到最高？
- "读取文件"是精确路径，不是"读相关文件"？
- "约束"是具体限制，不是"不要搞坏"？
- 简报模板包含"对外暴露说明"？
- 验证命令可直接运行？
- 文件已保存到 docs/_archive/？
常见错误示范
Task 太大 ❌ "把 useMessages.ts 拆成 4 个 hook" ✅ 每个 hook 一个 Task，分 4 步执行
约束太模糊 ❌ "不要破坏现有功能" ✅ "不改 useMessages 对外 return 的字段名；不改任何调用 useMessages 的组件"
缺少验证命令 ❌ 没有验证步骤 ✅ 每个 Task 末尾必须有可直接运行的验证命令
简报模板缺少暴露声明 ❌ 只问"有没有问题" ✅ 明确问"是否暴露了不该暴露的内部状态/setter/ref" 原因：Cursor 会为了让 tsc 通过而做妥协，但不会主动说
适用范围
适用：代码重构、模块拆分、逻辑去重、接口对齐、补测试、补架构文档
不适用：全新功能开发（未知太多，无法精确规划）、单步任务（直接做即可）