Composer / Agent 的多文件编辑能力，会把「一次说对」的收益放大，也会把「一次说错」的半径放大。很多重构事故不是模型不够聪明，而是人跳过了计划：没有范围、没有验收、没有回滚，直接「帮我把这层重构掉」。
本文给一份可执行清单：先计划再批量、分层看 diff、回滚预案写在动手前。适合中型仓库的结构性调整；支付/鉴权等核心路径请叠加 Manual 精修（见后续文）。
摘要
- 先计划：目标、范围、禁止事项、完成定义，Ask 确认后再改。
- 基线绿：独立分支，测试可跑，记下还原方式。
- 小步批量：按包/按层推进，步步验证。
- 分层审 diff：先结构后高风险，避免从头滚到尾。
- 超范围即停：回滚优先于「再让它修一下」。
结论：批量是油门，计划与回滚是刹车；只踩油门的重构不是勇敢，是赌博。
结论卡
| 阶段 | 关键产出 | 失败信号 |
|---|---|---|
| 计划 | 范围+验收+禁区 | 「顺便把别的也改了」 |
| 基线 | 分支+绿测+还原命令 | 直接在 main 试验 |
| 批量 | 小步提交 | 单提交三千行混杂 |
| 审阅 | 结构清单+风险点 | 只看最后几行 |
| 收尾 | PR 证据+回滚说明 | 「应该没问题」 |
背景与边界
Cursor 的 Composer、Agent 等多文件能力名称与交互随版本变化；本文讲工作流，不绑定某一按钮文案。不覆盖：具体快捷键表；也不鼓励在无测试仓库上「盲飞」大规模重构。
七步清单
1. 一句话目标与完成定义
写清：要解决什么疼痛（例如「重复 HTTP 客户端合并为一」），以及如何证明完成（测试、调用方迁移完毕、旧 API 删除或标记废弃）。没有完成定义，Agent 会以「改了很多文件」冒充完成。
2. 范围与禁止事项
列出允许路径与禁止路径。例：允许packages/http/**与调用方适配；禁止billing/**、禁止改生成物策略。范围是给模型的栅栏，也是给你自己的刹车。
3. Ask 出计划，人确认
先用 Ask（或只读）要求：步骤列表、每步涉及目录、风险、回滚点。人只确认计划，不在此步改文件。计划不过关就迭代计划，不要「边改边想」。
4. 建基线
- 独立分支；
- 相关测试在重构前为绿；
- 记下还原：
git status、git stash、git reset --hard/revert的适用场景； - 大仓库可先打 tag。
5. 按步批量执行
每步：明确「只做计划中的第 k 步」→ 执行 → 跑相关测试 → 提交。禁止一步里塞迁移+格式化+无关清理。格式化若需要，单独提交。
6. 分层审 diff
先看结构：文件列表、重命名、导入导出、配置与锁文件。再看高风险：鉴权、数据、并发、对外契约。结构不过关，不要陷入行级争论。高风险文件可转 Manual 逐段确认。
7. 回滚与收尾
超范围、测试红且无法快速理解、或出现密钥/权限扩散：立即停，回滚到上一个绿点。PR 描述写清风险与回滚；贴测试证据。
回滚与安全网
- 独立分支，禁止直推 main
- 每逻辑步一次可回退提交
- 还原命令写进任务书
- 大批量前基线必须绿
- 锁文件/生成物变更单独审
- 超范围改动立即停并回滚
任务书示意：
目标： 范围： 禁止： 完成定义： 回滚：回到 commit/tag XXX 第1步：… 验证：… 第2步：… 验证：…何时用批量
| 场景 | 建议 | 备注 |
|---|---|---|
| 机械重命名/搬迁 | 可批量 | 先计划+测试 |
| 跨包行为重构 | 分步批量 | 每步验收 |
| 鉴权/支付核心 | 慎批量 | Manual 精修 |
| 探索性试验 | 先 Ask | 别直接改仓 |
提示词套路（可复制）
请先给出重构计划（不要改文件）： 目标：… 允许路径：… 禁止路径：… 完成定义：… 请输出分步计划、风险、回滚点。 等我确认「执行第 N 步」后再改；每步结束列出变更文件与验证命令。执行步：
仅执行计划第 2 步，不要提前做第 3 步。 改完后运行：…（测试命令） 若测试失败，停止并总结，不要扩大范围。踩坑
| 坑 | 现象 | 处理 |
|---|---|---|
| 无计划批量 | 目录被「顺便整理」 | 回滚，重来 |
| 单提交过大 | 无法审 | 拆分重做 |
| 只看颜色 | 漏结构问题 | 先文件列表 |
| 失败继续催 | 洞越挖越大 | 停并回滚 |
| 无测试 | 靠感觉 | 补最小测再改 |
验收标准
- 计划文档（或 PR 首评）可追溯；
- 每步有提交与验证记录；
- diff 无禁止路径文件；
- 相关测试绿；
- 回滚演练至少做过一次（在废弃分支上）。
练习
选一个「安全的机械重构」（如重命名内部函数），走完七步并写半页复盘：哪一步最想偷懒，偷懒会怎样。
与 Monorepo / 多根工作区的配合
多包仓库里，计划阶段就要写清「本轮只动哪些包」。可配合@文件夹限制上下文，避免 Agent 为了「完整性」改到无关包。验收按包跑测试，而不是只跑根目录随便一个脚本。若计划显示影响面超过两包，先拆成两次 PR，比一次英雄式重构更像工程。
diff 审阅的实际操作顺序
1）看git diff --stat；2）看重命名与删除；3）看配置与 CI；4）再打开高风险文件的 hunk；5）最后才是样式与命名洁癖。把顺序写进团队公约，能减少「在注释空格上争论一小时，却放过鉴权改动」的经典翻车。
回滚演练怎么做才不算形式主义
在废弃分支上故意让第 2 步失败，练习git reset或git revert回到绿点，并更新任务书里的「还原命令是否仍正确」。演练时间十五分钟，却能避免真正压力下的手抖。把演练截图或命令记录进内部笔记即可，不必对外炫耀。
一周习惯化
本周每次超过三个文件的改动，强制先贴计划到对话或 PR。两周后统计：有计划的 PR 返工率是否下降。若没有下降，检查是不是计划太假（「优化代码」这种空目标）。
补充说明（1）
落地时请以你当前工具链的官方文档为准，把本文步骤当成检查清单而非版本锁定说明书。每完成一步就记录「命令、现象、是否可复现」，这比追求一次性写完美长文更接近工程。把失败也写进团队笔记，能减少下一位同事重复踩坑。若字数与信息密度冲突，优先保留可执行步骤与验收标准。
补充说明（2）
落地时请以你当前工具链的官方文档为准，把本文步骤当成检查清单而非版本锁定说明书。每完成一步就记录「命令、现象、是否可复现」，这比追求一次性写完美长文更接近工程。把失败也写进团队笔记，能减少下一位同事重复踩坑。若字数与信息密度冲突，优先保留可执行步骤与验收标准。
补充说明（3）
落地时请以你当前工具链的官方文档为准，把本文步骤当成检查清单而非版本锁定说明书。每完成一步就记录「命令、现象、是否可复现」，这比追求一次性写完美长文更接近工程。把失败也写进团队笔记，能减少下一位同事重复踩坑。若字数与信息密度冲突，优先保留可执行步骤与验收标准。
补充说明（4）
落地时请以你当前工具链的官方文档为准，把本文步骤当成检查清单而非版本锁定说明书。每完成一步就记录「命令、现象、是否可复现」，这比追求一次性写完美长文更接近工程。把失败也写进团队笔记，能减少下一位同事重复踩坑。若字数与信息密度冲突，优先保留可执行步骤与验收标准。
补充说明（5）
落地时请以你当前工具链的官方文档为准，把本文步骤当成检查清单而非版本锁定说明书。每完成一步就记录「命令、现象、是否可复现」，这比追求一次性写完美长文更接近工程。把失败也写进团队笔记，能减少下一位同事重复踩坑。若字数与信息密度冲突，优先保留可执行步骤与验收标准。
计划模板（可直接贴进对话）
【重构任务书】 目标（一句话）： 用户可见行为是否变化：是/否 允许路径： 禁止路径： 完成定义（可勾选）： 风险（高/中/低）与原因： 回滚点（commit/tag）： 分步： 1) … 验证： 2) … 验证： 请先只审计划；未经「执行第 N 步」指令禁止改文件。把任务书留在 PR 描述顶部，审阅者能在五分钟内判断「这是受控重构还是情绪化大扫除」。
测试策略：最小相关集
不要每次都跑全量若全量很慢；但要诚实定义「相关集」。规则示例：改了包 A 的导出，则跑 A 的单测 + 直接依赖 A 的包的冒烟。相关集写进计划第 0 步。若仓库缺少测试，先补「表征现状」的金丝雀测试，再重构——否则你在无仪表飞行。
何时从 Composer 退回 Manual
出现任一信号就降级：触及鉴权/支付；出现数据迁移；diff 中有大量生成物且说不清；模型连续两步越范围；你看不懂某文件为何被改。降级不是害羞，是成人。先回滚到绿，再对高风险文件 Manual 精修。
团队示范：一次成功的小重构复盘结构
背景与目标；计划原文；实际偏差；测试命令与结果；diff 统计；回滚点；下次改进一句。把复盘放进内部知识库，比再买一个「AI 重构工具」更能提升下一次成功率。开源对外时可打码路径与业务名。
工程备忘 1
请把本节当成可删减的备忘：结合你们仓库的分支保护、评审人与发布节奏裁剪。关键是保留「可执行步骤、验收标准、失败时回滚」，而不是保留形容词。若某一条与公司安全基线冲突，以公司基线为准，并在团队公约注明差异。把本次落地的命令与现象记在内部笔记，便于下一位同事复现。配置键与 Actions 字段以平台当前文档为准，避免被过期截图误导。
小结
Composer 多文件重构的清单可以压成一句：先计划，再批量，步步测，分层审，随时回得去。批量能力是杠杆；没有清单的杠杆，撬动的是事故。
草稿未发布 · 作者 梧桐秋海 · 活动：九月创作之星、工具实践
