AI Coding Agent 怎么接项目才不乱：issue、repo、浏览器验证和测试要怎么分工
AI Coding Agent 最容易出问题的地方，不是它不会写代码，而是你把整个项目丢给它以后，任务边界乱了。它一边读 issue，一边改 repo，一边跑命令，一边打开浏览器，一边解释测试结果。如果没有分工，最后你很难知道它到底哪里做对了、哪里开始猜了、哪里需要人工接管。
这篇不讨论哪个 coding agent 最强，而是讲怎么把 AI Coding Agent 接进真实项目。我们把一个任务拆成四层：issue、repo、浏览器验证和测试。只要这四层分清，Claude Code、Codex、OpenHands、Cursor、Aider 或其他 coding agent 都更容易用。
先给一张分工表
| 层级 | Agent 可以做什么 | 人应该保留什么 |
|---|---|---|
| issue | 重写需求、拆任务、找验收标准 | 确认优先级和真实业务意图 |
| repo | 找文件、解释结构、提出改动计划 | 决定是否接受改动范围 |
| coding | 小步修改、补测试、更新文档 | review diff 和架构边界 |
| browser | 打开本地页面、截图、走低风险流程 | 判断体验和高风险操作 |
| tests | 跑指定测试、解释失败、建议修复 | 判断是否扩大回归范围 |
这张表的核心是：Agent 可以推进信息和执行，但不应该独占判断。尤其是业务意图、架构边界、高风险操作和最终 merge，仍然应该有人看。
第一步：issue 要先变成可执行任务
很多 coding agent 做坏，是因为一开始 issue 就太含糊。比如：
优化文章页体验。
这句话对人也不够清楚，对 agent 更容易发散。更好的写法是：
文章详情页移动端标题和摘要间距过大，请收紧标题区高度。验收标准：iPhone 宽度下首屏能看到标题、摘要、发布时间和正文第一段开头；不改桌面布局；不碰数据层。
我会让 Agent 先做 issue 整理，而不是直接改代码：
- 这次要解决什么问题
- 哪些文件可能相关
- 哪些文件不应该碰
- 验收标准是什么
- 需要跑哪些检查
如果它连这一步都说不清，就不要让它继续改。
第二步：repo 阶段只让它找路，不急着动手
进入 repo 后，Agent 的第一件事应该是定位，不是修改。
我会让它输出这样一张表：
| 文件 | 为什么相关 | 预计动作 |
|---|---|---|
| template / component | 页面结构在这里 | 小改布局 |
| css / style | 间距和移动端样式在这里 | 改少量规则 |
| test / smoke | 可能有页面测试 | 跑或补一条 |
| data / db | 不相关 | 不碰 |
这张表很重要。它能防止 Agent 从一个小 UI 问题一路改到数据层、路由层、构建配置。真正好用的 coding agent，不是改得多，而是知道哪些不该改。
第三步：coding 阶段要小步，不要一次大改
我会要求 Agent 每次只做一个小闭环：
- 改一个点
- 说明为什么改
- 跑一个相关检查
- 给出 diff 摘要
- 再决定下一步
如果它一次改 12 个文件，还顺手重构命名、改格式、补一堆不相关文案，这通常不是效率高，而是风险高。
Coding Agent 最适合做的不是“大手术”，而是：
- 小 bug 修复
- 明确 UI 调整
- 文档同步
- 测试补齐
- 重复性迁移
- 有清楚验收标准的功能切片
不适合第一轮交给它的，是需求还没定、架构还在争论、权限风险很高、数据迁移不可逆的任务。
第四步：浏览器验证要独立出来
如果任务涉及页面，浏览器验证不要混在“我已经改完代码”的一句话里。要单独成为步骤。
可以让 Agent 或 Browser Agent 做：
- 打开 localhost 页面
- 截图
- 检查关键文字是否存在
- 点击低风险按钮
- 验证表单错误提示
- 比较移动端和桌面
但这些事情要有边界：
| 可以 | 不建议 |
|---|---|
| 打开页面截图 | 真实支付 |
| 填表但不提交 | 删除数据 |
| 检查按钮是否存在 | 发布内容 |
| 跑 smoke path | 改生产配置 |
浏览器验证的价值，是把“代码看起来对”变成“页面真的能用”。但最后的体验判断，尤其是复杂设计和业务流程，仍然需要人看。
第五步：测试结果要让 Agent 解释，但别让它无限修
Agent 跑测试很有用，但也容易陷入“一个失败修一个，再引入另一个失败”的循环。我的做法是给它最多两轮自动修复机会。
| 情况 | 处理方式 |
|---|---|
| 明确的小失败 | 让 Agent 修一轮 |
| 第二次仍失败 | 要求总结原因，暂停人工看 |
| 失败范围扩大 | 立即停 |
| 测试和需求无关 | 不让它顺手改 |
测试阶段最重要的是解释失败，而不是盲修。一个好的 coding agent 应该告诉你：失败是什么、可能原因是什么、它建议改哪里、风险是什么。
一个完整接入流程
我会把 coding agent 接项目写成这样：
- issue intake：把需求改成可验收任务
- repo scan：找相关文件和不该碰的边界
- plan：给 3-5 个小步骤
- edit：每次只改一个小块
- test：跑最相关检查
- browser verify：页面任务必须截图或走 smoke path
- summarize：列出改了什么、没改什么、风险
- human review：人看 diff、页面、测试结果
这个流程看起来比“直接让 agent 改”慢，但长期更快。因为它让错误更早暴露，也让人知道什么时候该介入。
最后怎么判断接得好不好
一个 coding agent 接项目接得好，会有几个特征：
- 它先问清任务，不急着改
- 它能说清哪些文件相关，哪些不碰
- 它每次改动很小
- 它能跑检查并解释失败
- 它能用浏览器验证页面
- 它能在不确定时停下来
- 人 review diff 时不需要重新理解整个项目
如果反过来，它总是大改、乱碰文件、测试失败还继续猜、页面没看就说完成，那就不是工具不够强，而是接入方式太乱。
AI Coding Agent 的价值不是替你取消工程流程，而是把 issue、repo、浏览器和测试这些环节串得更顺。分工越清楚，它越像队友；分工越乱，它越像一个很勤快但容易跑偏的实习生。
三种任务不要第一批交给 Coding Agent
为了避免一开始就翻车，我会明确把三类任务排除在第一批之外：
| 任务 | 为什么不适合第一批 |
|---|---|
| 大范围架构重构 | 影响面太大，Agent 很难判断隐性约束 |
| 不可逆数据迁移 | 出错成本高，回滚复杂 |
| 需求还没定的产品功能 | Agent 会把模糊需求写成确定代码 |
这些任务不是永远不能用 Agent，而是不能作为“建立信任”的第一批。第一批应该选低风险、范围小、验收清楚的任务。等团队知道 Agent 的风格、弱点和复查成本以后，再逐步扩大范围。
一个可复制的 issue 模板
如果你想让 Coding Agent 稳定一点，可以把 issue 写成这样：
| 字段 | 内容 |
|---|---|
| 背景 | 为什么要改 |
| 目标 | 这次只解决什么 |
| 不做 | 明确哪些不碰 |
| 相关页面 / 文件 | 如果已知，直接列出来 |
| 验收标准 | 怎么判断完成 |
| 必跑检查 | pytest / npm test / smoke path / screenshot |
| 风险点 | 权限、数据、性能、兼容性 |
这个模板的价值是把“人脑里的边界”提前写出来。Agent 不是不会努力，而是不知道哪些努力是多余的。边界越清楚，它越不容易乱跑。
让 Agent 输出交付摘要，而不是只说完成
每次任务结束，我会要求 Agent 输出 5 件事：
- 改了哪些文件
- 为什么改这些文件
- 跑了哪些检查
- 哪些检查没跑，为什么
- 还剩什么风险需要人工看
如果它只说“已完成”，这个结果不可用。真实项目里，交付摘要和代码本身一样重要。因为 reviewer 要靠它快速判断是否值得继续看 diff，是否要补测，是否要退回。
一个实用评分表
每个 Coding Agent 试用 5 次后，可以用这张表评估：
| 维度 | 低分表现 | 高分表现 |
|---|---|---|
| 边界感 | 经常改不相关文件 | 明确说哪些不碰 |
| 可复盘 | 只给结果 | 给步骤、测试、风险 |
| 小步执行 | 一次大改很多文件 | 每次改动聚焦 |
| 测试习惯 | 不跑检查或乱跑 | 跑最相关检查并解释 |
| 浏览器验证 | 页面任务只看代码 | 能截图、走 smoke path |
| 停止能力 | 失败后继续乱修 | 失败扩大时停下来 |
如果一个 Agent 在边界感和停止能力上低分，就算它写代码很快，也不适合接核心项目。速度只有在可控前提下才有意义。
最后再补一句很实际的判断：如果你每次看完 Agent 的改动都要重新读完整个项目，说明它没有省时间；如果你只需要看它标出的文件、截图、测试和风险清单，就说明接入方式开始对了。