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 --stat2看重命名与删除3看配置与 CI4再打开高风险文件的 hunk5最后才是样式与命名洁癖。把顺序写进团队公约能减少「在注释空格上争论一小时却放过鉴权改动」的经典翻车。回滚演练怎么做才不算形式主义在废弃分支上故意让第 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 多文件重构的清单可以压成一句先计划再批量步步测分层审随时回得去。批量能力是杠杆没有清单的杠杆撬动的是事故。草稿未发布 · 作者 梧桐秋海 · 活动九月创作之星、工具实践