legacy-safe-editlisted

# 改老项目不崩 ## 何时用 - 接手别人的项目，第一次在陌生仓库里加功能或修 bug。 - 在大型存量仓库里改动，不清楚某段代码被多少地方依赖。 - 需要在没有完整测试覆盖的老代码里动手，改错了难以发现。 - 产品要求在已上线系统里追加功能，不能影响现有用户流程。 ## 核心规则 ### 1. 先摸地形 **规则：** 改动前用搜索把所有调用点、依赖关系、相似实现全部找出来，弄清影响面再动手。 **为什么：** AI 拿到任务后习惯直接写代码，不会主动去确认"这个函数还有哪些调用方"。结果改了函数签名，三个其他模块悄悄挂掉；或者重写了一段逻辑，却不知道旁边已经有一个功能完全一样的工具函数。常见事故：在 `utils/format.ts` 里新写了 `formatDate`，没发现 `helpers/date.ts` 里已有同名函数，两套逻辑并存，下次维护的人一头雾水。 **怎么做：** - 用 Grep 搜索要改动的函数名、类名、常量名，确认所有引用位置。 - 用 Glob 扫描目录结构，了解仓库的模块划分和文件命名规律。 - 改动前在脑中（或明文写出）画出依赖链：「A 调用 B，B 被 C 和 D 引用，改 B 要同步检查 C 和 D」。 - 若发现影响面超出预期，先向用户确认范围，不要默默扩大改动。 --- ### 2. 跟随既有约定 **规则：** 完全模仿该仓库现有的命名风格、文件结构、错误处理方式，不引入个人偏好或"更好的写法"。 **为什么：** AI 有自己的代码风格偏好，在老库里容易不自觉地引入新的写法：项目用 `callback` 风格，AI 改成 `async/await`；项目用 `snake_case`，AI 写成 `camelCase`；项目统一用 `if (err) return callback(err)` 处理错误，AI 换成抛异常。这些风格切换单独看无害，但会让代码库出现多套约定并存的割裂感，后续维护者不知道该以哪种为准，技术债积累加速。 **怎么做：** - 改动前先读目标文件和它的邻居文件，摸清命名规范和代码结构。 - 有现成的同类代码就对着抄格式，不要凭记忆写"我觉得更���的写法"。 - 错误处理方式（返回错误码、抛异常、Result 类型）严格沿用仓库已有方式。 - 若发现现有约定确实有问题，新建 issue 记录，不在当前任务里顺手"修正"。 --- ### 3. 小步可回退 **规则：** 把改动拆成尽可能小的提交，每一步都能独立验证功能，出问题可以精确定位并回滚。 **为什么：** AI 倾向于一次性生成大段代码，一个 PR 改动几十个文件。当测试挂掉或功能出问题时，没人能快速判断是哪一步引入的问题，只能整体回滚，浪费大量时间。老代码库尤其危险——缺乏测试覆盖意味着问题可能只在特定场景下才暴露，小步提交是唯一能把"发现问题"和"引入问题的那次改动"对应起来的手段。 **怎么做：** - 每次提交只做一件事：改逻辑、改命名、调整结构，分开提交，不混在一起。 - 提交前本地跑一遍相关测试（哪怕只是冒烟测试），确认当前步骤没有破坏已有功能。 - 写清楚提交信息，说明"改了什么"和"为什么改"，方便事后用 `git bisect` 定位问题。 - 若一次改动无法拆小（比如大规模重命名），使用专门的 rename commit，不要把重命名和逻辑改动混进同一个提交。 --- ### 4. 不动公共接口除非必要 **规则：** 修改对外暴露的函数签名、导出接口、HT