executing-plans 快速入门

让 AI 执行大任务时,不再是”一口气干到底”,而是分批执行 + 中途检查 + 出错能回退。

这是什么?解决什么问题?

executing-plans 是 Obra 公司在 obra/superpowers 仓库下提供的一个 Skill,和 writing-plans 是配对关系。writing-plans 负责”把工作拆成 2-5 分钟小任务”,executing-plans 负责”按计划逐步执行,中途做检查点和回退”。

它解决的问题,是 AI 编程助手在执行大任务时的一个常见”翻车模式”:

• 用户让 AI”重构整个支付模块”,AI 一口气改了 200 行代码,运行测试全挂。
• 用户让 AI”把项目从 Vue 2 升级到 Vue 3”,AI 改了 50 个文件,中间某一步出错,整个分支废了。
• 用户让 AI”迁移数据库到 Postgres”,AI 写了 30 个 migration,其中一个失败,前面的 migration 不知道该不该回滚。

这个 Skill 沉淀的工作流是:

1. 分批执行:把大任务拆成 N 批,每批执行 3-5 个小任务。
2. 检查点(Checkpoint):每批执行完,停下来汇报进度,让用户确认是否继续。
3. 支持回退:如果某批失败,可以从上一个 checkpoint 回退,而不是全部重做。
4. 状态跟踪:维护一个 plan 文件,记录每个子任务的状态(pending / in_progress / done / blocked)。

它适合的场景:大重构、大迁移、跨多文件的特性开发、数据库 schema 演进、第三方 SDK 升级。

准备工作

1. 一个支持 Skill 加载的 AI 编程助手(Claude Code 体验最好)。
2. 项目里有一个清晰的目录结构(便于 AI 列出修改清单)。
3. 有一个 plans/ 目录,用于存放执行计划(可选但推荐)。
4. Clone 仓库:

   git clone https://github.com/obra/superpowers.git
   

5. 软链 Skill:

   ln -s superpowers/skills/executing-plans ~/.claude/skills/executing-plans
   

3 步快速上手

第 1 步:安装 Skill

重启 AI 助手,Skill 生效。

第 2 步:验证安装

向 AI 发送请求:

“我要把项目从 Vue 2 升级到 Vue 3,先用 executing-plans 给我生成一个分批执行计划,每批 3-5 个步骤,带检查点。”

如果 AI 输出的是一个清晰的 Markdown 列表,每批有”完成定义”(Definition of Done),带 Checkpoint 标签,说明 Skill 加载成功。

第 3 步:用 executing-plans 跑第一个任务

让 AI 帮你把”将 Express 4 升级到 Express 5”拆成可执行计划:

# 升级到 Express 5 计划

## 第 1 批:代码扫描与依赖盘点
- [ ] 跑 `npm outdated`,列出所有过期依赖
- [ ] 跑 `npx express-inspector`,标记过时的 API 用法
- [ ] 在 README 加 DEPRECATION 警告
- [ ] **Checkpoint 1**:汇报过期依赖清单,等用户确认升级范围

## 第 2 批:升级非破坏性依赖
- [ ] 升级 lodash、axios 等无 breaking change 的包
- [ ] 跑测试,确认无回归
- [ ] **Checkpoint 2**:汇报测试结果,等用户确认进入下一批

## 第 3 批:升级 Express 到 5.x
- [ ] 修改 package.json,锁定 5.0.0
- [ ] 处理 removed APIs(`req.param()` 等)
- [ ] 处理 changed APIs(`res.sendfile` → `res.sendFile`)
- [ ] **Checkpoint 3**:本地起服务,跑 smoke test,等用户验证

## 第 4 批:回归与发布
- [ ] 跑完整测试套件
- [ ] 部署到 staging,跑 1 小时
- [ ] **Checkpoint 4**:用户决定是否上生产

## 回退策略
- 任意 Checkpoint 失败:git reset --hard 到上一批 commit
- 升级到 5.x 后严重不兼容:git revert 升级 commit

Skill 会让 AI 在每批执行前先读计划,执行完汇报进度,等用户说”继续下一批”再动,而不是”一口气干完”。

常见踩坑

1. 跳过 Checkpoint。用户嫌 AI 问太多,回一句”直接做完”,结果中间出错全盘崩。Skill 强调 Checkpoint 是质量保障,不能跳。
2. 每批任务过多。“一批改 20 个文件”等于”不分批”。Skill 建议每批 3-5 个 2-5 分钟任务,反馈循环要短。
3. 没有 Definition of Done。每批任务完成的标准不清楚,用户和 AI 理解不一致,经常出现”AI 觉得完了,用户觉得没完”的争论。
4. 回退策略不明确。出错时不知道该回退到哪个 commit,Skill 要求每个 Checkpoint 都对应一个 git commit。
5. 状态没有持久化。对话关掉后,plan 进度就丢了,下次再来 AI 不记得走到哪。Skill 建议 plan 文件保存在项目里。
6. 大文件修改不在单独 commit。一批任务里改了 30 个文件,出错时无法精确回退,Skill 建议每批一个 commit。

初级用法

用法 1:跨多文件的特性开发。让 AI 按 Skill 模式拆成”建数据模型 → 写 API → 写前端 → 写测试”4 批,每批 3-5 步。

用法 2:依赖升级。从 Vue 2 升 Vue 3、从 React 17 升 18、从 Webpack 升 Vite,都用这个工作流。

用法 3:数据库 schema 演进。新增字段、加索引、加表,每个 migration 单独一个 Checkpoint,出错可以只回退一个 migration。

高级玩法

玩法 1:并行批处理。对独立的任务批次,启动多个 AI agent 并行执行,Skill 建议最多 3-5 个并行,超过协调成本反而高。

玩法 2:进度看板化。把 plan 文件存到 GitHub Issue / Linear,每完成一个子任务勾选,团队成员都能看到进度。

玩法 3:与 verification-before-completion 联动。executing-plans 关注”如何执行”,verification-before-completion 关注”如何验证完成”,两个 Skill 配合形成完整工作流。

小技巧

1. 每批一个 git commit。git commit -m "batch 1: dependency audit",回退时精准定位。
2. 每批 Definition of Done 显式写出。“跑 npm test 全过” 而不是 “测试没问题”,标准要可验证。
3. Checkpoint 不要太多。4-6 个 Checkpoint 是甜蜜区,太少失去”分批”意义,太多又慢。
4. 失败时立刻停下,不要硬撑。AI 报错时,先回退到上一个 Checkpoint,不要”再改改试试”,Skill 明确反对。
5. 把 plan 文件 commit 进项目。docs/plans/2026-06-upgrade-express-5.md,半年后回看”我们当时怎么做的”非常有用。

常见问题 FAQ

Q1: 这个 Skill 跟 executing-plans 有什么关系?必须装吗?

A: Skill 是给 AI Agent 用的”技能包”,能告诉 Agent 怎么按特定规范工作。不是必须装——如果你的项目规模小、要求不高,不装也能用。但装上能让 Agent 输出的质量更高、更符合最佳实践,推荐装。

Q2: 这个 Skill 适合哪些 AI Agent?Cursor?Claude Code?其他?

A: executing-plans 来自 Obra,主要面向支持 Skill 机制的 Agent。常见兼容 Agent 包括 Claude Code、Cursor、OpenCode、Windsurf 等。具体兼容性请查 Skill 官方文档。

Q3: 装了这个 Skill 后,会拖慢 Agent 响应吗?

A: 会的——Skill 通常会增加 prompt 长度,导致响应变慢、token 消耗增加。但质量提升明显。建议:1) 只装项目必需的 Skill;2) 用 Skill 启动/加载/卸载机制按需加载;3) 定期清理不用的 Skill。

Q4: 怎么验证 Skill 装对了?

A: 在 Agent 中输入”列出已加载的 Skill”或类似命令。如果 Skill 出现在列表里,说明装对了。然后用 Skill 跑一个相关任务,看输出是否符合 Skill 规范。

Q5: 这个 Skill 有许可证吗?能商用吗?

A: 取决于 executing-plans 的许可证。常见许可证包括 MIT(完全自由)、Apache-2.0(自由但有专利条款)、源可用(可看不能用)、GPL(强开源)。商用前请查仓库 LICENSE 文件。

参考链接

• executing-plans 仓库:https://github.com/obra/superpowers
• Skill 路径:https://github.com/obra/superpowers/tree/main/skills/executing-plans
• writing-plans 配对 Skill:https://github.com/obra/superpowers/tree/main/skills/writing-plans
• Git 原子提交指南:https://www.atlassian.com/git/tutorials/using-branches
• Conventional Commits:https://www.conventionalcommits.org/

本文基于官方文档和公开资料整理，AI辅助生成，MagicNetWorld 尚未完成独立实测。如有错误或过时信息，请通过 contact@magicnetworld.com 反馈。