# Execution Planner

> 触发场景：用户想对代码库做任何多步骤改动，但执行工作会交给 Cursor 或其他 AI 模型完成。 包括但不限于：重构、拆分大文件、提取模块、清理重复逻辑、迁移、接口对齐、补测试、补文档。 用户说"帮我规划"、"出个执行方案"、"写个给 Cursor 的任务"、"怎么拆这个文件"、 "帮我设计重构步骤"、"我想改 X 但不知道怎么分步"时，立即使用此 skill。 产出物是一个保存到本地的 Markdown 执行包文件，不是聊天回复。 Claude 的核心价值在于规划质量，执行和大部分验收由其他模型完成。

- Skill: `zl585451/execution-planner` (Agent Skill)
- Install (CLI): `npx skillmds add zl585451/execution-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zl585451/execution-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: zl585451 (https://skillmd.com/u/zl585451)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/zl585451/execution-planner

---


# 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：输出给用户

只说两件事：
1. 文件保存路径（computer:// 链接）
2. 第一步让 Cursor 做什么（复制即用的一段指令）

不做长篇解释，不重复文件内容。

---

## 执行计划文件标准模板

````markdown
# [任务名称] 执行计划

> 归档类型：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 通过而做妥协，但不会主动说

---

## 适用范围

适用：代码重构、模块拆分、逻辑去重、接口对齐、补测试、补架构文档

不适用：全新功能开发（未知太多，无法精确规划）、单步任务（直接做即可）