Cursor 的多文件编辑，靠的是「限定范围的引用 + 先计划后出 diff + 逐文件接受」，而不是把三个文件粘进 Chat 再手工拷贝回去。目标是一次把接口、实现、测试和调用方改齐，同时避免它顺手重写你没点名的基础库。
为什么 Chat 窗口不够用
Chat 适合解释和单文件建议。当你要改共享类型，调用方可能散落在五个包里，靠人工搜索再粘贴，一定会漏。多文件编辑把仓库索引用起来：你点名目录，它列出候选文件，你再决定哪些进入本轮。没有这一步，所谓「智能」只是在当前缓冲区里即兴发挥。
一套不容易漏改的流程
- 用
@Folders点选业务包和对应测试目录，避免引用整个 monorepo。 - 第一句写清契约：函数签名、错误码、兼容旧字段还是允许破坏性变更。
- 要求先输出文件清单。清单里多了文档站或基础库，立刻删范围，不要让它开始写代码。
- 接受 diff 时按依赖顺序：先类型与接口，再实现，最后测试。反了容易在半应用状态无法编译。
- 应用后用仓库里已有的测试命令验证，而不是只看 Agent 说「应该可以了」。
- 用 Git 看
git diff --stat。出现你没要求的目录，就回滚那部分，不要在脏工作区上继续加需求。
范围控制比模型选择更重要
同一套模型，范围小就能改对，范围大就容易在无关文件里「统一风格」。规则文件可以写「未经要求不得重命名公共 API」。生成代码、锁文件和快照目录应默认排除。多文件编辑的质量，往往取决于你肯不肯花三十秒点引用，而不是取决于有没有打开最强推理档。
多文件编辑和 Git 节奏绑在一起
每一轮多文件任务开始前，工作区应是干净的，或至少把无关改动 stash 掉。任务结束后立刻提交或拆成可回滚的提交，不要让三次 Agent 会话的 diff 混在一起。混在一起时，你无法判断是哪一轮引入了无关重构。提交信息写清意图，例如「为账单接口增加幂等键」。这样即便要回滚，也只回滚这一意图。多文件编辑的技术上限，常常取决于你肯不肯维持这种 Git 卫生，而不是模型名字。
遇到生成文件和手写文件混在同一目录时，先在说明里禁止改生成物。Agent 很爱「顺手」重写 lockfile 或 protobuf 生成代码，下一轮构建会把这些改动覆盖，看起来像多文件编辑失败。真正该改的是源文件和测试。把生成物路径写进忽略和规则，成功率会立刻上去。
常见问题
一次最多能改多少文件才算安全？
没有魔法数字。接口变更涉及的文件该多少就多少，但不要把「顺便升级依赖」塞进同一轮。一轮一个意图，回滚才回得干净。
应用一半失败，工作区烂了怎么办？
不要继续让 Agent 修补残骸。用 Git 还原到会话开始前，收紧范围后重开一轮。在脏树上叠第二轮，冲突会指数上升。
它总漏掉调用方？
把调用方目录显式引用进去，并在验收标准写「所有编译错误清零」。只说「改一下类型」时，它可能只动定义文件。
