Coding Agent 合并前别只看绿灯：一张六栏发布收据，拦住“测试全过也翻车”
你让 Coding Agent 修了个 Bug。
它提交了一堆文件，终端里一片绿色：10 passed in 3.227s。Agent 还贴心地告诉你，构建产物有 SHA-256 校验值。
看起来很稳？先别急着点 Merge。
测试全绿，只能说明：在这次执行的环境里，被选中的那批检查没有报错。
它回答不了这些更要命的问题：
- 这次改动有没有越出授权范围？
- 有没有偷偷改配置、锁文件或部署脚本？
- 有没有访问网络、下载新依赖、触碰生产数据？
- 没跑哪些检查？Windows 跑过吗？生产权限跑过吗？
- 出事故后，谁来回滚？几分钟能恢复？
真正可靠的 AI 协作，不是让 Agent 交一份“绿灯截图”。而是让它交一张发布收据（Release Receipt）。
人负责做合并决策。Agent 负责把证据、未知项和退路摆到桌面上。这个边界，千万别混。
为什么 10 个测试全绿，仍然不够
测试是验证工具，不是免责协议。
假设 Agent 接到的任务是：“修复用户资料页头像上传失败的问题。”
它可能完成了下面这些动作：
✅ 修改 uploadAvatar.ts
✅ 新增 3 条单元测试
✅ pnpm test 全部通过
可你打开变更列表，发现还有这些内容：
⚠️ 修改 .env.example
⚠️ 更新 package-lock.json
⚠️ 调整 GitHub Actions 的发布权限
⚠️ 新增一个访问第三方图床的请求
测试也许都过了，可问题已经变了。
这不再只是“头像上传修好了没”。它开始涉及密钥暴露、供应链依赖、网络出站、CI 权限和用户数据流向。
绿灯很漂亮。事故报告里也经常是绿的。😅
测试能覆盖的是已知行为。团队真正该警惕的，常常是没有被测试覆盖的未知项。
给 Coding Agent 的交付标准：六栏发布收据
每次让 Agent 提交可合并的代码时，要求它附上一份固定结构的收据。
不用追求文采。要的是清楚、可核验、能追责。
1. 任务范围：允许改什么，明确不改什么
这一栏是在防止 Agent “顺手优化”。
很多风险不是来自代码写错，而是来自它改了本不该动的地方。
模板：
## 任务范围
- 目标：修复头像上传时 HEIC 文件返回 500 的问题。
- 允许修改：
- src/api/uploadAvatar.ts
- src/api/uploadAvatar.test.ts
- docs/avatar-upload.md
- 明确不修改：
- 数据库结构与迁移文件
- CI/CD 配置
- 鉴权逻辑
- 生产环境变量
- 第三方依赖版本
这里有个很实用的动作：把“不许碰什么”写得比“要做什么”还具体。
比如你只说“修复上传问题”，Agent 可能顺手升级图片处理库。你写明“禁止修改依赖版本”，它就没法拿升级大包当快捷键。
2. 实际变更：文件变了什么，为什么要变
别接受“已完成修复”这种空话。
你需要看到文件级别的变更说明。不是为了形式主义，是为了在两分钟内发现不该出现的文件。
模板：
## 实际变更
| 文件 | 改动 | 原因 |
| --- | --- | --- |
| src/api/uploadAvatar.ts | 为 HEIC 文件增加格式转换分支 | 图片处理服务不支持直接读取 HEIC |
| src/api/uploadAvatar.test.ts | 新增 HEIC 上传成功、转换失败两条测试 | 覆盖新增分支与错误响应 |
| docs/avatar-upload.md | 补充支持的文件格式 | 同步接口约束 |
未修改：数据库、依赖清单、CI 配置、权限策略。
审查时有个简单判断法：
每一个被改的文件，都必须能回答“为什么非改它不可”。
答不上来，就该追问。
特别留意这几类文件：
package.json、锁文件：依赖是不是被悄悄换了.github/workflows/：CI 权限和发布流程有没有变化.env*、配置中心文件：密钥和环境参数有没有风险- 数据库迁移文件：是否会影响存量数据
- Docker、K8s、Terraform 文件：部署边界是不是被碰了
3. 验证证据：命令、退出码、结果、产物一个都别省
“测试通过”不是证据。
完整命令 + 退出码 + 输出摘要 + 产物位置，才是能复查的证据。
模板：
## 验证证据
| 检查项 | 执行命令 | 退出码 | 结果 |
| --- | --- | ---: | --- |
| 单元测试 | `pnpm test -- --runInBand` | 0 | 10 passed, 0 failed，耗时 3.227s |
| 类型检查 | `pnpm typecheck` | 0 | 无错误 |
| 代码格式 | `pnpm lint` | 0 | 无错误 |
| 构建 | `pnpm build` | 0 | 产物位于 `dist/` |
构建产物：`dist/app.tar.gz`
SHA-256：`<hash>`
执行环境：Ubuntu 22.04 / Node.js 20.11.1 / pnpm 9.1.0
这里有个细节很容易被忽略：命令必须准确。
写“跑了测试”没意义。
pnpm test 和 pnpm test -- --runInBand 可能不是同一件事；本地 Node 18 和 CI 的 Node 20，也可能跑出两个世界。
如果你的项目会发包、构建镜像或生成数据文件，再多补两项：
- 产物的路径和哈希值
- 构建使用的运行时版本、操作系统、关键依赖版本
出问题时，这些信息能帮你快速定位“代码有问题”还是“环境在闹鬼”。
4. 未知项：没跑什么，没覆盖什么，直接摊开说
这一栏最值钱。
成熟团队不怕存在未知项，怕的是未知项被藏起来。
Agent 很容易把“未验证”包装成“应该没问题”。别吃这套。要求它明确列出来。
模板：
## 未知项与未覆盖范围
- 未执行真实对象存储上传，仅使用 Mock 服务。
- 未在 Windows 环境验证文件路径兼容性。
- 未使用超过 20MB 的 HEIC 文件压测。
- 未验证弱网下转换服务超时后的重试行为。
- 未覆盖生产 IAM 权限配置。
看到未知项后，不要机械地要求“全部补齐”。那样只会把小改动拖成无底洞。
该问的是：哪一个未知项最可能推翻当前的合并决定？
举个例子：
- 只是文案调整，没跑 Windows 测试，大多可以接受。
- 改了文件上传路径，却没验证生产对象存储权限，这就不能当小事。
- 修改支付回调逻辑，却没有沙箱验证和回放测试，直接阻断，别赌。
未知项要按风险排队，不要按数量吓自己。
5. 权限与副作用：Agent 到底碰了哪些边界
这部分决定了“代码正确”之外的风险。
一个 Agent 在本地改了两行代码，和它联网安装依赖、调用远程 API、改云资源配置，完全不是一个风险等级。
模板：
## 权限与副作用
- 文件系统：修改 3 个业务代码文件和 1 个文档文件。
- 网络访问：未发起外部网络请求。
- 依赖变更：无新增、删除或升级依赖。
- 远程系统：未访问 GitHub、云服务、数据库或对象存储。
- 数据处理：未读取、写入或导出真实用户数据。
- 需要批准：无。
如果 Agent 确实做了高风险操作，别让它一句“已执行”带过。
把审批人写出来：
- 远程系统：调用 staging 环境的对象存储 Bucket。
- 数据处理：上传 5 个脱敏测试文件。
- 需要批准：由后端负责人确认 Bucket 写入权限，由安全同学确认出站域名白名单。
这里的原则很朴素：
Agent 可以执行任务，但不能替人承担权限责任。
特别是涉及这些操作时，必须有明确批准人：
- 读取或写入生产数据库
- 修改 IAM、Token、CI Secret
- 删除云资源或批量文件
- 向外部服务发送用户数据
- 安装来源不明的脚本和依赖
- 触发真实支付、邮件、短信、推送
6. 回滚办法：什么情况撤，怎么撤，谁来恢复
没有回滚路径的上线，跟走夜路不带手电差不多。
“有 Git 就能回滚”也不够。代码回退、数据库状态、缓存、异步任务、外部副作用，经常不是一回事。
模板：
## 回滚计划
- 触发条件：HEIC 上传错误率超过 1%，或上传接口 5xx 增长超过基线 0.5%。
- 回滚动作：将发布版本从 `v2.8.1` 回退到 `v2.8.0`。
- 数据影响：本次变更不写入数据库，无数据迁移，无需数据修复。
- 验证方式：回滚后执行 3 个 JPG、PNG、HEIC 上传冒烟测试，并观察 15 分钟接口错误率。
- 负责人：值班后端工程师；升级联系人：服务负责人。
如果改动涉及数据库，回滚计划必须再往前走一步：
- 迁移是否可逆？
- 回滚脚本在哪里？
- 已写入的新字段怎么办？
- 新旧版本会不会同时读写同一张表？
- 队列里积压的旧任务谁来处理？
找不到恢复负责人，或者说不清恢复路径，就别合并。
这不是保守，这是正常求生欲。
一份可直接复制的 Coding Agent 提示词
把下面这段放进你的 Agent 任务模板、PR 模板，或者团队规范里。
完成编码后，请输出“发布收据”，不要只给结论。
必须包含以下内容：
1. 任务范围
- 本次目标
- 允许修改的文件或模块
- 明确未修改、禁止修改的范围
2. 实际变更
- 每个变更文件的路径、改动摘要、改动原因
- 标记任何配置、依赖、CI、数据库、权限相关变更
3. 验证证据
- 完整执行命令
- 每条命令的退出码
- 测试数量、失败数量、耗时
- 构建产物路径、哈希值和执行环境
4. 未知项
- 未执行的检查
- 未覆盖的环境、平台、数据规模和异常场景
- 可能影响合并决定的风险
5. 权限与副作用
- 是否修改文件、依赖、配置
- 是否访问网络、远程系统、数据库、云资源
- 是否读取、写入、传输用户数据
- 需要谁批准
6. 回滚计划
- 触发回滚的条件
- 回滚命令或操作步骤
- 数据修复需求
- 回滚负责人和验证方式
如果某项未执行、无法确认或没有权限，请明确写“未知”或“未执行”，不得猜测。
关键句是这一句：不得猜测。
Agent 最擅长给出流畅答案。工程团队最需要的，却是它在不知道时老老实实说“不知道”。
合并前 3 分钟检查法
PR 不可能每次都开半天会。你可以用下面这套快筛方法，把注意力放在最容易翻车的地方。
看范围：有没有越界文件
打开文件列表。
一个修前端样式的 PR，为什么动了 package-lock.json？一个修 API 参数的 PR，为什么出现 .github/workflows/deploy.yml？
看到这种不匹配，先停一下。
看未知项：哪个风险最能推翻决定
别被“已通过 42 项测试”冲昏头。
盯住未验证内容：生产权限、数据迁移、跨平台、外部接口、真实流量。只要其中一项可能造成不可逆损失，就该补证据或升级审批。
看回滚：出事时谁在几分钟内动手
“可以回滚”不算答案。
要看到：触发阈值、操作路径、负责人、验证动作。
如果深夜报警，值班同学能不能照着文档把系统拉回来？不能，那这份收据还没合格。
常见坑：这些“看起来没问题”的说法，别轻易放过
坑 1：测试全过，所以可以合并
测试通过是证据的一部分，不是合并许可。
处理方式：要求补齐范围、未知项、权限副作用和回滚计划。
坑 2：Agent 说“没有副作用”
它可能只是在说“代码逻辑没有副作用”。网络请求、锁文件变化、缓存写入、遥测上报，也都属于副作用。
处理方式：让它按文件、网络、依赖、远程系统、数据五个维度回答。
坑 3：没跑的检查被写成“预计通过”
“预计”“理论上”“应该”这类词，都是风险提示灯。
处理方式：统一标记为“未执行”，再评估是否阻断合并。
坑 4：回滚方案只有一句 git revert
代码撤回了，数据库迁移怎么办？已经发出的消息怎么办？第三方系统收到的请求怎么办？
处理方式：把数据状态、异步任务、外部副作用单独写进回滚计划。
坑 5：把收据当成文书工作
收据不是为了让 PR 更长。
它的作用是让审查者快速定位：证据在哪，盲区在哪，谁有权限，翻车后往哪撤。
只要这四件事清楚，文档越短越好。
结尾：Agent 交证据，人来按合并键
Coding Agent 会越来越能写代码，也会越来越像一个手速惊人的新同事。
问题是，新同事写完代码，你会因为终端全绿，就把生产权限、数据风险和回滚责任全交给它吗？显然不会。
把六栏发布收据固化下来：
- 范围有没有越界
- 文件为什么变化
- 验证证据能不能复查
- 未知项有没有摊开
- 权限和副作用谁批准
- 出事后谁来恢复
测试负责证明一部分行为没坏。
发布收据负责把风险边界画出来。
Agent 可以提交证据。至于能不能合并，那个键，还是得由清楚后果的人来按。
