改老项目不崩

何时用

• 接手别人的项目，第一次在陌生仓库里加功能或修 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. 不动公共接口除非必要

规则： 修改对外暴露的函数签名、导出接口、HTTP 端点、数据库字段前，先评估所有下游影响；非必要则保持向后兼容。

为什么： AI 在改内部实现时容易顺手调整函数签名——加个参数、改个返回值类型——觉得"反正我会把调用方也一起改掉"。但老项目里，调用方可能散布在文档里、第三方 SDK 里、甚至客户端的缓存配置里，AI 根本不知道这些存在。常见翻车：把 REST API 的响应字段从 user_id 改成 userId，前端代码全部 undefined，但 AI 只改了后端，以为没问题。

怎么做：

• 改公共函数前，用 Grep 全局搜索函数名，确认所有调用方都在可控范围内。
• 若必须修改签名，优先采用兼容性方案：新增可选参数而非改变已有参数、保留旧函数并标注 @deprecated、新旧端点并存一段时间。
• 数据库字段变更（尤其是重命名、类型变更）单独评估迁移方案，不要在业务逻辑 PR 里夹带。
• 拿不准下游影响时，向用户明确说明风险，不要默默改掉。

5. 保留并复用既有工具

规则： 优先使用仓库里已有的工具函数、组件、常量，不重复造轮子，不引入同功能的新依赖。

为什么： AI 在生成代码时经常从零开始写，不会主动检查仓库里是否已有现成的实现。结果同一个功能在代码库里出现三份实现：一份在 utils/，一份是 AI 刚写的，一份是某个业务模块里的私有方法。三份实现行为略有差异，哪天出现 bug，修了这里忘了那里，线上问题反复出现。更常见的情形是：项目已经用了 lodash，AI 又自己实现了一遍 debounce。

怎么做：

• 动手前搜索要实现功能的关键词（如 format、validate、debounce），确认仓库里有没有现成实现。
• 检查 package.json / go.mod / requirements.txt，了解项目已有哪些依赖，有需要的功能优先用现有依赖解决。
• 若现有实现有缺陷，在原处修复，而不是在旁边新建一个"修复版"。
• 若确实需要引入新依赖，单独提交并说明理由，让 reviewer 可以有意识地审查。

正例 / 反例

反例：凭习惯重写无关代码，引入风格割裂

项目里所有异步操作都用 callback 风格，AI 在新增功能时顺手把相邻函数"顺便优化"成了 async/await，同时重写了错误处理逻辑，导致调用方的 callback 永远不会被触发。

// 反例 — 原始代码（项目统一风格）
function fetchUserData(userId, callback) {
  db.query('SELECT * FROM users WHERE id = ?', [userId], function(err, rows) {
    if (err) return callback(err);
    callback(null, rows[0]);
  });
}

// 反例 — AI "顺手优化"后（引入新风格，破坏调用方）
async function fetchUserData(userId) {          // ❌ 签名变了，callback 消失
  const rows = await db.query(                  // ❌ 调用方还在传 callback，永远不执行
    'SELECT * FROM users WHERE id = ?',
    [userId]
  );
  return rows[0];
}

// 正例 — 只加新功能，完全沿用现有风格
function fetchUserDataWithRole(userId, callback) {   // ✅ 新函数，不动老函数
  db.query(
    'SELECT u.*, r.name AS role FROM users u JOIN roles r ON u.role_id = r.id WHERE u.id = ?',
    [userId],
    function(err, rows) {
      if (err) return callback(err);               // ✅ 错误处理与项目一致
      callback(null, rows[0]);
    }
  );
}

反例：没搜索就重复造轮子，引入多套实现

// 反例 — AI 直接写了一个新的日期格式化函数
// 不知道项目里 src/utils/date.ts 已有完全一样的实现

// src/features/order/helpers.ts（AI 新写的）
function formatOrderDate(date: Date): string {
  const y = date.getFullYear();
  const m = String(date.getMonth() + 1).padStart(2, '0');
  const d = String(date.getDate()).padStart(2, '0');
  return `${y}-${m}-${d}`;                        // ❌ 与 src/utils/date.ts 里的 formatDate 重复
}

// 正例 — 先搜索，发现现成实现，直接复用
// 搜索结果显示：src/utils/date.ts 已导出 formatDate(date: Date): string

import { formatDate } from '@/utils/date';        // ✅ 复用现有工具，没有引入重复逻辑

function buildOrderSummary(order: Order): OrderSummary {
  return {
    id: order.id,
    createdAt: formatDate(order.createdAt),        // ✅ 行为一致，单点维护
  };
}

自查清单

• 改动前已用 Grep 搜索过所有相关调用点，确认影响面在可控范围内。
• 新写的代码命名风格、错误处理方式与文件中的现有代码保持一致。
• 没有在本次任务里顺手修改与任务无关的代码、风格或结构。
• 若改动了公共函数签名或导出接口，已评估并处理所有下游调用方。
• 没有重新实现仓库里已有的工具函数或引入功能重复的新依赖。
• 改动已拆成可独立验证的小步骤，每步提交信息清楚说明了改动原因。
• 若发现范围外的问题（技术债、其他 bug），已记录为独立 issue，没有混入本次改动。