面对长期积累的技术债或框架升级需求，批量改造存量代码是最棘手的任务之一。核心原则是可控、分批、可回退。CodeBuddy 适合承担其中模式固定、重复性高的机械劳动，但关键决策点仍需人工把关。
步骤一：划定范围，建立基线
不要上来就要求"把整个项目重构一遍"。先用 @目录 绑定待改造模块，让 CodeBuddy 完成两件事：
- 梳理该模块的对外接口与核心依赖，明确改动影响面；
- 扫描出符合改造特征的文件清单（如"所有使用旧版 API 的文件"、"包含超过 200 行的大函数"）。
同时，确保当前 Git 工作区干净，为后续批量改动建立明确的回退基线。
步骤二：试点验证，确认模式
从清单中挑选 1–2 个具有代表性的文件，在侧边栏使用具体指令做试点改造。例如：
"将这两个文件中所有
var声明替换为let或const，保持原有作用域逻辑不变；对于需要提升的变量，改为显式提前声明。"
观察生成结果是否符合预期。若结果不理想，当场调整提示词（增加约束或示例），直到确认 AI 理解正确为止。此步骤能避免将错误模式复制到全库。
步骤三：分批执行跨文件改造
将改造任务按目录或业务模块拆分为多批，每批控制在 20–50 个文件以内，方便代码评审。对每批文件执行以下流程：
- 使用 @目录 绑定当前批次上下文；
- 结合 @规则 导入团队编码规范，确保改造后的命名、格式与项目一致；
- 要求 CodeBuddy 先输出变更清单（diff 概览），人工快速审阅后再决定是否应用，而非直接覆盖原文件。
对于模式极其固定的替换（如统一错误码格式、废弃函数更名），可明确要求"仅做语法/命名替换，不改动业务逻辑"。
步骤四：排查遗漏与行为验证
批量修改后，使用全库代码问题统一排查（3.5.3）扫描是否还有同类历史遗留问题。随后对改造涉及的核心路径，利用单元测试自动生成（3.6.1）快速补全用例，验证改造前后输入输出行为一致。若项目原有测试覆盖率较低，这一步尤为重要。
步骤五：渐进落地与回退
每完成一批改造，提交一次独立的代码变更记录。若某批次出现大规模编译错误或运行时异常，直接 git reset 回退该批次，缩小问题范围后重新调整提示词再试。
避坑建议
- 一次只做一件事：不要同时要求"把回调改成 async/await，并且拆分所有大函数，再统一加上 TypeScript 类型"。分阶段推进，出问题时容易定位根因。
- 警惕硬编码与正则：涉及复杂正则、位运算、或高度业务耦合的代码，AI 容易误判，此类文件必须人工逐行核对。
- 保留边界注释：在提示词中显式要求"不要删除原有 FIXME/TODO 注释"、"保持对外导出的函数签名不变"，防止改造过程中丢失关键上下文。