1. 项目缘起与整体交付思路
1.1 一个真实到有点扎心的背景
去年年底，我接了一个企业级内部管理系统的项目。客户那边原本的规划是：4 人团队，2 个月工期，预算按人天算得清清楚楚。结果我这边实际投入的，只有我一个人，外加 3 个 AI Agent 组成的“虚拟小组”，3 周交付上线。
这不是标题党，也不是为了炫技。我之所以敢接这个活，是因为在接之前我已经用类似的方式跑通过两个小项目，心里有底。但即便如此，3 周做完一个原本 4 人 2 个月的项目，中间踩的坑、熬的夜、推翻重来的次数，一点都不少。
这篇文章不打算跟你聊“AI 会不会取代程序员”这种大而空的话题。我想把整个项目的交付过程拆开，讲清楚三件事：AI Agent 到底在哪些环节真正提效了、哪些环节它反而拖了后腿、以及一个人带着 3 个 Agent 干活，工程上要怎么组织才不至于把自己搞崩。
如果你是一个独立开发者、小团队技术负责人，或者正在评估要不要把 AI Agent 引入日常交付流程，这篇内容应该能帮你省下不少试错成本。
1.2 为什么是“3 个 Agent”而不是“1 个全能 Agent”
很多人一上来就想搞一个“什么都能干”的超级 Agent，我试过，结论是：单 Agent 做企业项目，越到后面越失控。
原因很简单。企业项目不是写一个算法题，它涉及需求理解、架构设计、编码实现、测试验证、部署运维等多个阶段，每个阶段对上下文的要求完全不同。你让一个 Agent 同时记住需求文档、代码规范、数据库 schema、接口约定、部署脚本，它的上下文窗口会被迅速撑爆，然后开始“胡言乱语”——生成看似合理但完全跑不通的代码。
所以我把它拆成了 3 个角色，各管一段：
| Agent 角色 | 主要职责 | 核心依赖 |
|---|---|---|
| 需求与架构 Agent | 拆解需求、生成数据模型、输出接口契约 | RAG 知识库、历史项目文档 |
| 编码 Agent | 按契约生成业务代码、单元测试 | 代码规范库、worktree 隔离环境 |
| 审查与集成 Agent | code review、CI 流水线校验、集成测试 | CI 配置、静态分析规则 |
这三个 Agent 不是各自为战，它们之间通过结构化的中间产物通信——接口契约、数据模型、测试用例，而不是靠自然语言互相“聊天”。这一点非常关键，后面会详细讲。
1.3 3 周时间是怎么分配的
先给你一个整体节奏，心里有个数：
- 第 1 周：需求梳理 + RAG 知识库搭建 + 架构设计 + 接口契约冻结
- 第 2 周：核心业务模块编码 + 单元测试 + 每日 code review
- 第 3 周：集成测试 + CI 流水线打通 + 部署 + 修 bug + 交付文档
看起来挺顺，但实际执行中，第 1 周我花了整整 5 天在“让 Agent 理解这个项目”上，第 2 周有 2 天在跟 Agent 生成的“幻觉代码”搏斗，第 3 周有 1 天因为 CI 配置问题差点通宵。所以真实的时间账，比表面看起来紧得多。
2. 核心工具链选型与背后的取舍逻辑
2.1 为什么用 git worktree 而不是 git branch
这是整个项目里我最想先讲的一个点，因为它直接决定了多 Agent 并行编码能不能跑通。
一开始我用的是传统的git branch。每个 Agent 在自己的分支上干活，干完再 merge。听起来没问题，但实际操作中你会发现：切换分支要 stash、要 checkout，工作目录是共享的。当编码 Agent 在写业务代码、审查 Agent 同时想跑测试的时候，两边会互相干扰。你切过去，它的编译缓存就废了；它跑测试，你的未提交改动就被搅乱了。
后来我换成了git worktree。简单说，worktree 允许你把同一个仓库的不同分支同时检出到不同的目录，每个目录有自己独立的工作区、独立的编译缓存、独立的运行环境。
# 为主仓库创建两个额外的工作树 git worktree add ../project-agent-code feature/agent-code git worktree add ../project-agent-review feature/agent-review # 查看当前所有工作树 git worktree list这样编码 Agent 在../project-agent-code目录里写代码，审查 Agent 在../project-agent-review目录里跑测试，互不干扰。实测下来，这个改动让并行效率提升了至少 40%。
注意：worktree 不是银弹。它会让你的磁盘占用翻倍，而且每个 worktree 的依赖需要单独安装。如果你的项目依赖特别重，要提前评估磁盘和内存。
2.2 RAG 知识库：企业项目的“记忆外挂”
企业项目最大的特点是什么？上下文极其庞杂。客户有历史系统、有内部规范、有行业术语、有各种没写进文档但老员工都知道的“潜规则”。这些东西你不可能全部塞进 Agent 的 prompt 里。
我用 RAG（检索增强生成）来解决这个问题。具体做法是：
- 把客户提供的需求文档、历史接口文档、数据库设计文档全部切块、向量化，存进知识库
- 把团队内部的代码规范、命名约定、常用工具类也存进去
- Agent 在生成代码前，先检索相关知识片段，再基于检索结果生成
这里有个坑我必须提醒你：RAG 的瓶颈往往不在检索，而在切块。我一开始按固定 500 字切块，结果一个完整的接口定义被切成两半，Agent 检索到半截信息，生成的代码自然对不上。后来改成按语义结构切块——一个接口定义、一个数据表、一个业务规则各成一块，效果立刻好转。
关于“RAG 知识库能不能存图片”，我的实践是：可以存，但意义有限。图片里的信息如果没被 OCR 转成文字，检索时基本命中不了。企业项目里真正有用的还是结构化的文本知识。
2.3 CI 流水线：让 Agent 的产出“有据可查”
AI Agent 生成代码最大的风险是什么？它看起来很对，但可能根本跑不起来。所以我从第 2 周开始，就把 CI 流水线接入了。
每次编码 Agent 提交代码，CI 自动触发：
- 静态代码检查（lint）
- 单元测试
- 接口契约校验
- 构建打包
只有全部通过，代码才允许合并。这一步看似增加了流程，实际上是把审查 Agent 从“人肉检查”中解放出来，让它专注于逻辑层面的 review，而不是纠结语法错误。
我用的是 GitLab CI，配置不复杂，核心就是几个 stage：
stages: - lint - test - build lint: stage: lint script: - npm run lint test: stage: test script: - npm run test:unit build: stage: build script: - npm run build这套配置跑通之后，我每天早上的第一件事就是看 CI 报告，而不是逐行读 Agent 生成的代码。效率差别巨大。
3. 核心环节的实操细节与避坑经验
3.1 需求拆解：别让 Agent 直接读原始需求
这是我踩过的第一个大坑。一开始我把客户给的 30 页需求文档直接丢给架构 Agent，让它输出数据模型和接口设计。结果它生成的东西大方向没错，但细节全是想当然——字段类型拍脑袋定、业务规则自己编、边界条件完全忽略。
后来我改成了“人工预处理 + Agent 细化”的模式：
- 我先花半天时间，把需求文档里的核心业务实体和关键业务流程手动梳理出来
- 把梳理结果作为“骨架”喂给 Agent，让它在此基础上补充字段、生成接口
- 我再逐条 review，把不合理的打回去重生成
这样做的好处是，Agent 的发挥空间被限制在“细化”而不是“创造”上，幻觉大幅减少。实测下来，需求拆解阶段的时间从 3 天压缩到 1.5 天，而且返工率明显下降。
实操心得：给 Agent 的输入越结构化，它的输出越可靠。自然语言需求文档是“非结构化”的，你必须先把它变成表格、列表、流程图，再交给 Agent。
3.2 接口契约冻结：多 Agent 协作的“宪法”
3 个 Agent 要协作，最怕的是什么？各干各的，最后对不上。编码 Agent 以为用户 ID 是字符串，审查 Agent 以为是整数，集成的时候直接崩。
所以我在第 1 周结束前，强制做了一件事：接口契约冻结。具体来说，就是把所有对外接口的请求参数、响应结构、错误码全部定义清楚，写成一份机器可读的契约文件（我用的是 OpenAPI 规范）。
这份契约一旦冻结，就成为 3 个 Agent 共同的“宪法”：
- 编码 Agent 按契约生成实现
- 审查 Agent 按契约校验代码
- CI 流水线按契约做接口测试
任何一方想改契约，必须走变更流程，重新生成受影响的代码。这个约束看起来死板，但它避免了后期大量的“接口对不上”问题。
3.3 编码阶段：worktree + 小步提交
编码阶段是整个项目最耗时的部分，也是 Agent 提效最明显的部分。我的做法是：
- 把每个业务模块拆成独立的 worktree 任务
- 编码 Agent 在对应 worktree 里生成代码
- 每完成一个小功能就提交一次，触发 CI
- CI 通过后，审查 Agent 介入做逻辑 review
这里的关键是小步提交。我试过让 Agent 一次性生成一个大模块，结果 CI 报了几十个错，排查起来极其痛苦。改成小步提交后，每次只关注几个文件的改动，问题定位快得多。
还有一个细节：Agent 生成的代码必须带注释。不是为了好看，而是为了审查 Agent 能理解代码意图。我在 prompt 里明确要求“每个函数必须有说明其业务目的的注释”，这样审查 Agent 在 review 时能快速判断逻辑是否正确。
3.4 审查阶段：人机分工的边界在哪
审查 Agent 能干什么、不能干什么，我摸索了整整一周才搞清楚。
它能干的：
- 检查代码是否符合规范
- 检查接口实现是否与契约一致
- 检查是否有明显的空指针、越界等低级错误
- 检查单元测试覆盖率是否达标
它干不好的：
- 判断业务逻辑是否符合客户真实意图
- 判断架构设计是否合理
- 判断性能瓶颈在哪里
所以我的分工是：Agent 负责“形式正确”，我负责“实质正确”。Agent 审查通过的代码，我会再快速过一遍核心逻辑，确认没有理解偏差。这个分工让我的 review 时间从每天 4 小时降到 1.5 小时左右。
4. 常见问题与排查技巧实录
4.1 Agent 生成“幻觉代码”怎么办
这是最高频的问题。表现是：代码语法正确、逻辑自洽，但调用的方法不存在、引用的字段没定义、依赖的库没安装。
我的排查思路是分三步：
- 看 CI 报错：大部分幻觉代码会在编译或测试阶段暴露
- 看契约校验：接口对不上的，契约校验会直接标红
- 看依赖清单：Agent 有时会“发明”不存在的依赖，检查 package.json 或 pom.xml 能快速发现
解决方法是在 prompt 里明确约束可用依赖。我维护了一份“允许使用的依赖清单”，每次生成代码前都把它塞进上下文，Agent 就不会乱引用了。
4.2 CI 流水线跑得太慢怎么优化
项目中期，CI 一次要跑 8 分钟，严重拖慢节奏。我做了三件事：
- 并行化：lint、test、build 三个 stage 并行跑，而不是串行
- 缓存依赖：把 node_modules 缓存起来，避免每次重新安装
- 增量测试：只跑受影响的模块的测试，而不是全量测试
优化后 CI 时间降到 2 分半，基本可以接受。
4.3 多 Agent 上下文冲突怎么解
当 3 个 Agent 同时工作时，它们可能会对同一个文件产生不同的理解。我的解法是用文件锁 + 任务队列：
- 每个 worktree 同一时间只允许一个 Agent 操作
- 任务按优先级排队，避免并发冲突
- 关键文件（如契约文件）设为只读，只有我能改
这套机制不复杂，但能避免 90% 以上的并发问题。
4.4 常见问题速查表
| 问题现象 | 可能原因 | 排查方向 | 解决手段 |
|---|---|---|---|
| 代码编译不过 | 幻觉依赖/方法 | 看 CI 报错 | 约束依赖清单 |
| 接口对不上 | 契约未同步 | 看契约校验 | 重新生成受影响代码 |
| 测试覆盖率低 | Agent 偷懒 | 看覆盖率报告 | prompt 强制要求 |
| CI 频繁失败 | 提交粒度过大 | 看提交记录 | 改小步提交 |
| Agent 理解偏差 | 上下文不足 | 看检索结果 | 优化 RAG 切块 |
5. 交付后的复盘与个人体会
项目最终按时上线，客户验收通过。但复盘下来，有几个点我觉得值得所有想用 AI Agent 做企业项目的人注意。
第一，AI Agent 不是用来替代人的，是用来放大人的。我之所以能 3 周做完，不是因为我什么都不干，而是因为我把大量重复性、机械性的工作交给了 Agent，自己专注于架构决策、业务理解和关键 review。如果我自己对业务一窍不通，Agent 生成的东西我根本判断不了对错。
第二，工程规范比 Agent 本身更重要。worktree、CI、契约冻结、小步提交，这些都不是 AI 时代的新东西，但正是这些“老掉牙”的工程实践，让 Agent 的产出变得可控。你如果连基本的版本管理和 CI 都没有，直接上 Agent，只会把混乱放大。
第三，RAG 知识库的质量决定 Agent 的上限。我花在整理知识库上的时间，占了整个项目前期的一半。但这是值得的，因为知识库越干净、越结构化，Agent 的检索命中率越高，生成的代码越靠谱。
最后分享一个小技巧：给每个 Agent 起个名字，并且在 prompt 里明确它的角色边界。我管架构 Agent 叫“老架”，编码 Agent 叫“小码”，审查 Agent 叫“严审”。听起来有点中二，但实测下来，明确角色后，Agent 的“越界行为”明显减少——它知道自己该干什么、不该干什么。
这个项目之后，我又用类似的方式接了 2 个活，节奏越来越顺。但我也很清楚，这套方法有它的适用边界：需求相对明确、技术栈相对标准、团队有一定工程基础的项目，效果最好。如果是那种需求天天变、技术栈极其冷门的项目，AI Agent 的提效会大打折扣，甚至可能帮倒忙。
所以别盲目跟风，先拿一个小项目试试水，把 worktree、CI、RAG 这套基础设施跑通，再考虑上大项目。这是我用 3 周时间换来的最实在的经验。
