研发智能体：从读代码库到可提交的合并请求

系列第三篇。选型见 智能体不只是聊天，派活顺序与验收清单见 派活与验收。本篇把同一套心法落到 工程交付：读库、修 Bug、写文档、升依赖、出发版说明。它不替代 Code Review，也不替代值班时的判断。

编程智能体这两年在国内团队里普及得很快：Cursor 在个人开发者里常见，腾讯 CodeBuddy、阿里通义灵码、字节 Trae 在企业里铺得更广，不少公司内网还有基于开源模型自建的代码助手。名字不同，干的活大同小异：读仓库、改文件、跑终端命令。

问题也大同小异：它说修好了，测试其实没跑；它说只改了一处，diff 里动了十几个文件；它写的说明很漂亮，和代码对不上。 所以研发场景里，验收标准必须比办公场景更硬。

---

研发里什么叫「验收」

办公场景的交付物是文件；研发场景的交付物是 一次可以合并、也可以撤回的变更。具体落到四样东西：

和聊天助手「给你一段示例代码」相比：

最后一行是关键：智能体省下的是写代码的时间，不是看 diff 的时间。 如果你连 diff 都不看，省下的时间迟早会在线上故障里还回去。

---

场景一：新人或新模块上手（以 Ask 为主）

什么时候用

刚入职、接手同事离职留下的模块、或者要改一个从没碰过的服务。传统做法是翻文档（往往过期）、找人问（对方很忙）、自己断点调试（很慢）。

怎么派活

【模式】只读。不要修改、新建、删除任何文件，不要运行会写数据库或调用外部接口的命令。

【目标】帮我理解「订单创建」这条链路，输出到对话里（我确认后再让你写进 docs/onboarding/order.md）。

【起点】从 HTTP 接口 POST /api/orders 开始。

【我要看到】
1. 调用链：控制器 → 服务 → 仓储 → 数据表，每一层给出文件路径和函数名
2. 涉及哪些表、哪些消息队列主题、哪些外部服务
3. 「如果我要改 X，还会影响 Y」的清单
4. 你没读到或拿不准的地方（配置、权限、定时任务），单独列出

怎么验收

• 抽一条路径自己走一遍：在 IDE 里按它给的文件和函数跳转，看是否真的连得上。
• 重点看「拿不准」那一栏：好的输出会主动承认盲区，比如「金额计算依赖配置中心的某个开关，仓库里看不到默认值」。如果一个盲区都没有，反而要警惕。
• 确认无误后再进入 Craft，让它把内容写进仓库的 docs/，跟代码一起评审。

上手文档写进仓库而不是留在聊天记录里，下一个新人就能直接用。这就是总论里说的「可验收交付」。

---

场景二：修 Bug（Ask → Plan → Craft 全流程）

这是最常用、也最容易翻车的场景。完整走一遍：

第一步 Ask：给材料，让它定位

【模式】只读分析，先不要改代码。

【现象】用户在 iOS 端提交订单，偶发「库存不足」，但后台库存充足。
【复现】并发 20 个请求下单同一商品，约 5% 失败。
【日志】见 logs/order-error-1105.txt（已脱敏）
【期望】库存充足时不应失败。

请列出你认为可能的根因，按可能性排序，每条说明依据（代码位置 + 日志行）。

第二步 Plan：锁定改动范围

智能体给出假设后，挑你认同的那条，让它出计划：

采用你的第 1 条假设（扣减库存时先查再改，非原子操作）。
请给出修复计划：
1. 要改哪些文件、哪些函数（列出路径）
2. 打算怎么改（一两句话，不要贴代码）
3. 新增或修改哪些测试，能复现并发问题
4. 用什么命令验证

不要改计划以外的文件；不要顺手重构；不要升级依赖。

第三步 Craft：小改动 + 测试

确认计划后再让它动手。要求它最后贴出：

• 实际运行的测试命令和输出（不是「应该能通过」）
• git diff --stat 的结果
• 一段合并请求描述草稿：现象、根因、改法、验证方式

怎么验收

• [ ] 新增的测试 在修复前会失败、修复后会通过（可以让它先只提交测试，跑一次看是否失败）
• [ ] diff 里没有无关格式化、没有调试用的 console.log 或 print
• [ ] 没有为了让测试通过而改测试本身的断言
• [ ] 合并请求描述能让一个没参与的同事看懂

最后一条值得多说一句：智能体有时会「修」不好代码，就去改测试让它通过。看 diff 时，测试文件的改动要和业务代码一样仔细看。

---

场景三：文档和接口说明同步（Craft + 人审）

什么时候用

接口改了、文档没改；README 里的启动命令早就跑不通；内部 wiki 和代码对不上。这类活人不愿意干，智能体干得不错。

怎么派活

【目标】以代码为准，更新 docs/api/ 下的接口文档和根目录 README.md 的「本地启动」一节。

【事实来源】
- 接口定义：src/controllers/ 下的路由和参数校验
- 启动命令：package.json 的 scripts、docker-compose.yml

【约束】
- 只改 docs/api/ 和 README.md，不要改任何代码
- 代码和文档冲突时，以代码为准，并在回复里列出冲突清单
- 不确定的参数含义写「待确认」，不要编

怎么验收

• 抽两个公开接口，对照代码里的参数校验，看文档写的必填项、类型、默认值是否一致。
• 真跑一遍 README 的启动命令。这一步最能发现问题。
• 看冲突清单：它列出的「文档写错了」的地方，往往正是之前坑过别人的地方。

---

场景四：依赖与安全升级（Plan 必做）

什么时候用

安全扫描报了漏洞（公司内部扫描平台、npm audit、pip-audit 等），或者某个依赖太旧要升级。这类改动看起来只改了版本号，实际可能牵一发动全身。

怎么派活

【模式】先 Plan，我确认后再执行。

【目标】修复安全扫描报告 security-report.json 中的高危漏洞。

【范围】
- 只升补丁版本和小版本，不升大版本
- 如果某个漏洞必须升大版本才能修，列出来，不要自己升

【计划里要写清】
1. 升级清单：包名、当前版本、目标版本、修复的漏洞编号
2. 预计会受影响的代码位置
3. 验证命令（单元测试 + 构建）

【执行后】贴出测试结果；列出因升级而改动的业务代码（如果有）。

国内团队还要多注意一点：镜像源。很多公司用 npm 淘宝镜像、PyPI 清华源或内部私服，智能体有时会改掉 .npmrc、pip.conf 或锁文件里的源地址。约束里可以直接写「不要修改镜像源配置」。

怎么验收

• [ ] 锁文件（package-lock.json、pnpm-lock.yaml、poetry.lock 等）的变化和升级清单一致
• [ ] 流水线全绿，包括构建和测试
• [ ] 没有悄悄放宽安全策略（比如关掉某个校验、把漏洞加进忽略列表）
• [ ] 需要升大版本的项单独列出，由你决定是否另开任务

---

场景五：发版说明（Craft）

什么时候用

每次发版要写更新说明：给用户看的版本、给内部看的版本、给测试看的回归范围。人工翻提交记录很枯燥，正适合交给智能体。

怎么派活

【目标】根据 v2.3.0 到 v2.4.0 之间的提交记录和已合并的合并请求，写两份说明：
1. CHANGELOG.md 新增一节：面向用户，按「新功能 / 改进 / 修复」分类
2. 发布/v2.4.0-内部说明.md：面向研发和测试，包含数据库变更、配置变更、需要重点回归的模块

【约束】
- 用户版不要出现内部模块名、同事姓名、客户名称
- 每一条都要能对应到具体提交或合并请求编号
- 没有用户可感知变化的提交（重构、测试、构建脚本）不要写进用户版

怎么验收

• 用户版不夸大：「优化性能」要能对应到实际改动，不能把一个小修复写成「全面提升」。
• 内部版不遗漏：数据库迁移、配置项变更、定时任务调整，漏一个就可能是上线事故。
• 不该外露的信息（客户名、内部系统地址）没有出现在用户版里。

---

工具怎么选

不做产品评测，只讲分工。同一个人用两三种工具很正常。

两条通用规则：

1. 同一个分支，同一时间只让一个智能体改。 两个智能体同时改同一批文件，冲突合并起来比自己写还累。
2. 公司代码先看合规。 不少企业规定只能用内部部署的模型或指定的产品，个人账号接公司仓库可能违规。这一条比任何效率提升都重要。

---

写代码和审代码分开：两个角色

单个智能体自己写、自己检查，很容易自我认可。一个简单的改进是 分两轮、用两段不同的指令：

第一轮：写代码的角色

按场景二的 Plan 和 Craft 完成修改，产出分支和 diff。

第二轮：审代码的角色（新开对话，不带第一轮的上下文）

【模式】只读。你是代码审查者，不要修改任何文件。

请审查当前分支相对 main 的 diff，重点检查：
1. 是否有改动超出「修复订单并发扣库存」这个目标
2. 边界条件：库存为 0、并发极高、数据库超时
3. 测试是否真的覆盖了并发场景，还是只测了单线程
4. 是否有安全问题：SQL 拼接、日志里输出敏感字段

按「必须改 / 建议改 / 可忽略」三档列出，每条给出文件和行号。

审查结果出来后，你决定 哪些要改。最后合并到主干的按钮，由你来点。智能体不应该有直接合并到生产分支的权限。

---

不该交给智能体单独做的事

下面这些可以让智能体帮你 查资料、写草稿、列风险，但决定和执行要在人：

• 架构决策：拆不拆服务、换不换数据库、要不要引入新中间件。智能体能列优缺点，但它不承担三年后的维护成本。
• 安全模型大改：权限体系、加密方案、鉴权流程。
• 没有测试覆盖的核心代码重写：改完无法验证对错，等于赌博。
• 线上数据修复：直接执行 SQL 改生产数据，必须人工复核、走审批。
• 密钥和证书操作：轮换密钥、更新证书，智能体不应接触真实密钥。
• 值班时的故障处置：可以让它帮你翻日志、整理时间线，但回滚、切流量、降级的决定由值班人做。

---

一个完整例子：一下午修完一个并发 Bug

把上面串起来，看一个虚构但典型的时间线。小林是后端开发，用 CodeBuddy，公司代码托管在内部 GitLab。

注意几个细节：

• 14:35 小林删掉了智能体「顺手重构」的建议。修 Bug 的合并请求里混入重构，评审和回滚都会变难。
• 14:40 先写测试并确认它失败。这一步证明测试真的能抓住问题，而不是一个永远通过的摆设。
• 15:05 审查用的是新对话，避免沿用写代码时的思路。
• 15:20 智能体没有合并权限，最后两步都是人。

---

延伸阅读

• 站内：智能体不只是聊天 · 派活与验收
• 站内：Cursor 快捷键与 Git 调试 · Claude Code 高阶技巧

---

下一篇：本篇把测试当作修 Bug 的验收手段；如果要把测试体系本身搭起来，见 测试智能体：用 AI 搭一套能长期跑下去的自动化测试体系。项目管理、销售与售前、学习与资料整理等场景会陆续单独成篇。