实际开发中，很多功能从来不是"改一个文件"就能搞定的。新增一个 RESTful 接口可能需要同步修改路由注册、控制器、服务层、数据模型和类型定义；引入统一的日志中间件可能涉及十几个现有文件的批量调整。Cursor 的跨文件自动落地能力，就是要把这种"牵一发而动全身"的重复劳动交给 AI 自动完成。
适用场景
- 新增完整业务模块（如用户权限、支付流程）；
- 重构影响面较广的公共函数或接口（如统一错误码、替换请求库）；
- 给现有逻辑追加横切关注点（如日志、鉴权、参数校验）。
操作流程
- 描述需求并绑定项目上下文
在 Agent 模式（或支持项目级改写的对话面板）中，用自然语言描述目标，例如："给所有 /api 开头的路由增加 JWT 鉴权中间件，未登录返回 401"。同时输入 @代码库（或 @Codebase）让 AI 先读取项目结构，确保它基于真实目录做决策，而非凭空生成。
- AI 分析并列出修改计划
几秒后，AI 会返回一份待修改文件清单，例如：
src/middleware/auth.js（新建中间件）src/routes/user.js（引入中间件）src/routes/order.js（引入中间件）src/app.js（全局注册）
此时你可以检查清单是否遗漏了关键文件（如类型定义 types/api.d.ts），有遗漏直接补充追问。
- 逐文件生成 Diff 并审查
确认清单后，AI 会按文件生成具体的代码差异（Diff）。Cursor 会在编辑器标签页中以对比视图展示修改内容，绿色新增、红色删除一目了然。逐文件浏览，重点检查：
- 接口变更是否同步到了所有调用方；
- 是否有误删原有业务逻辑；
- 命名是否与项目现有规范一致。
- 一键应用与依赖处理
审查无误后点击 "Accept All"，AI 会批量写入所有文件，并自动处理文件间的引用关系（如自动导入路径、更新导出列表）。如果某个文件需要微调，可以单独点击 "Reject" 后手动修改，或在对话中要求 AI 针对该文件重新生成。
真实示例
假设你的 Express 项目需要把 userId 从 req.params 迁移到 req.query。AI 在执行时会同时：
- 修改
router.get('/:userId')为router.get('/')； - 修改控制器中的取值方式；
- 同步更新对应的单元测试用例中的请求构造；
- 如果项目中存在前端调用封装，还会提示你手动检查（因为 AI 通常不直接修改外部前端代码）。
实用建议
- 先 commit 再执行：跨文件改写前务必用 Git 提交当前工作区。一旦 AI 改坏了，可以瞬间回退。
- 复杂需求拆两步：如果涉及"改接口 + 改数据库 + 改缓存"这类重型操作，建议先让 AI 改接口层并验证通过，再执行数据层，降低一次性审查的认知负担。
- 关注边缘文件：AI 很容易漏掉配置文件、Dockerfile、CI 脚本或接口文档。执行后全局搜索一下功能关键词，确认没有"漏网之鱼"。
跨文件自动落地是 Cursor 项目级能力中最省时间的环节，但也是最需要人工审查的环节。把它当作一个"会自动写代码的高级实习生"：它能快速把活干完，但你作为负责人，必须在合并前过一遍 diff。