三Agent流水线实战：3周完成2个月企业级项目

1. 三周干完两个月的活，到底省在哪儿了

先把这个项目的底牌摊开说：一个标准的企业级内部系统，按常规配置——4 人团队、2 个月工期——大概需要 320 人天左右。我实际投入的是 3 周，核心执行单元是 3 个 AI Agent 加上我自己。这不是"AI 帮我写了几段代码"那种程度，而是从需求拆解、接口设计、代码生成、测试覆盖到 CI 流水线搭建，整条链路都由 Agent 承担了主要工作量。

先说清楚这个项目是什么类型的活，因为不是所有项目都适合这么干。它是一个典型的企业内部工具：前端管理后台 + 后端 REST API + 数据库 + 定时任务 + 权限体系。技术栈是 Spring Boot + Vue3 + MySQL + Redis，部署在 GitLab CI 上。这类项目的特点是——模式化程度高、业务逻辑清晰、没有太多需要"灵光一现"的架构决策。这正是 AI Agent 最能发挥的场景。

为什么是 3 个 Agent 而不是 1 个？这是整个项目里最关键的一个决策。单个 Agent 处理复杂项目时，上下文窗口会被迅速撑爆，而且它容易在"写代码"和"改 bug"之间反复横跳，效率极低。我把职责拆成了三条线：架构 Agent负责需求拆解、接口定义、数据库设计；编码 Agent负责按接口契约生成具体实现；审查 Agent负责 code review、测试用例生成和 CI 配置。三个 Agent 之间通过结构化的文档和代码仓库交互，而不是靠对话上下文传递信息。

这里有个反直觉的点：Agent 之间的"沟通成本"必须用文件系统来承载，而不是对话。我一开始试过让架构 Agent 把设计直接"告诉"编码 Agent，结果就是编码 Agent 经常"记错"字段名、漏掉边界条件。后来改成架构 Agent 输出 OpenAPI 规范文件和数据库 DDL 文件，编码 Agent 直接读文件，错误率立刻降下来了。这个经验后面会展开讲。

三周的时间分配大概是这样的：第一周做需求拆解和架构设计，同时把 CI 流水线和 Git worktree 的工作流搭好；第二周是编码 Agent 的主力输出期，我主要在做 review 和纠偏；第三周做集成测试、修 bug、补文档、上线。真正"写代码"的时间其实只占了一半，另一半全花在给 Agent 搭脚手架和验收上。

所以如果你问我"3 周做完 2 个月的活"省在哪儿了，答案不是"AI 写得快"，而是省掉了人类团队里大量的沟通对齐、等待、返工和上下文切换。4 人团队里，两个人对接口理解不一致，可能要开半小时会才能对齐；Agent 之间不存在这个问题，只要契约文件写死了，它们就严格按契约执行。这才是效率差异的真正来源。

2. 三个 Agent 的职责边界怎么划才不打架

2.1 为什么按"交付物"而不是按"功能模块"来分工

很多人搭多 Agent 系统时，第一反应是按功能模块分——你负责用户模块，我负责订单模块。我试过这个方案，很快就崩了。原因是模块之间是有依赖的，用户模块的 Agent 改了数据结构，订单模块的 Agent 不知道，集成的时候一堆冲突。

正确的切法是按交付物类型分。架构 Agent 的交付物是设计文档和契约文件；编码 Agent 的交付物是可运行的代码；审查 Agent 的交付物是 review 意见、测试用例和 CI 配置。每个 Agent 的输入和输出都是明确的文件，不依赖对话记忆。

这个表看着简单，但每一行的"输入"都是上一行的"输出"，形成了一条流水线。流水线的好处是可中断、可重跑。编码 Agent 某次输出质量差，我不用重跑整个流程，只要把架构 Agent 的契约文件重新喂给它就行。

2.2 契约文件是整个流水线的"宪法"

OpenAPI 规范文件在这个项目里的地位，怎么强调都不过分。它不只是给前端看的接口文档，而是编码 Agent 的唯一真相来源。我在架构 Agent 的 prompt 里写死了一条规则：任何接口的字段名、类型、必填性、错误码，都必须在 OpenAPI 文件里定义清楚，不允许有"待定"字段。

为什么这么严格？因为编码 Agent 在生成 Controller 和 Service 时，会严格按 OpenAPI 文件来。如果文件里有个字段叫userName，但数据库 DDL 里叫user_name，编码 Agent 生成的代码就会在映射层出错。我踩过这个坑——第一版契约文件里字段命名不统一，结果编码 Agent 生成了 30 多个文件，其中一半的字段映射是错的，光修这个就花了大半天。

后来我加了一道校验：架构 Agent 输出契约文件后，先跑一个脚本检查 OpenAPI 里的字段名和 DDL 里的列名是否一一对应（驼峰转下划线），不通过就打回重做。这个脚本本身也是审查 Agent 生成的，大概 50 行 Python，但省了我至少两天的返工时间。

提示：契约文件一定要用机器可校验的格式（OpenAPI、JSON Schema、DDL），不要用 Markdown 表格或自然语言描述。自然语言描述给 Agent 读，它每次理解都可能不一样。

2.3 审查 Agent 不是"找茬"，而是"补位"

审查 Agent 的定位很容易被误解成"挑代码毛病"。实际上它最大的价值是补编码 Agent 漏掉的横切关注点。编码 Agent 在生成业务代码时，注意力全在业务逻辑上，很容易漏掉日志、异常处理、参数校验、权限注解这些东西。审查 Agent 的职责就是系统性地检查这些"每个接口都应该有但容易被忽略"的部分。

我让审查 Agent 按一个固定的 checklist 来 review，这个 checklist 包括：每个 Controller 方法是否有@PreAuthorize权限注解、每个 Service 方法是否有入参校验、每个数据库操作是否在事务里、每个外部调用是否有超时和降级、每个接口是否有对应的单元测试。这个 checklist 是固定的，审查 Agent 每次 review 都按这个来，不会漏。

实测下来，审查 Agent 平均每个 PR 能找出 5 到 8 个问题，其中大部分是编码 Agent 漏掉的横切关注点。如果靠人工 review，这些问题可能要等到测试阶段才暴露，那时候修的成本就高多了。

3. Git worktree 撑起的多 Agent 并行工作流

3.1 worktree 和 branch 的区别，以及为什么这个项目非它不可

先说清楚 git worktree 和 git branch 的区别，因为这是整个并行工作流的基础。branch 是同一个工作目录下的不同分支，你切换分支时，工作目录里的文件会跟着变。worktree 则是同一个仓库的多个工作目录，每个 worktree 可以 checkout 不同的分支，互不干扰。

这个区别在多 Agent 场景下是决定性的。如果三个 Agent 共用一个工作目录，它们会互相踩脚——编码 Agent 正在写文件，审查 Agent 去 checkout 另一个分支，文件全变了。用 worktree，每个 Agent 有自己的目录，各自 checkout 自己的分支，物理隔离。

# 主仓库 git worktree add ../agent-arch feat/architecture git worktree add ../agent-code feat/implementation git worktree add ../agent-review feat/review # 每个目录独立工作，互不影响 cd ../agent-code && git checkout -b feat/user-module

我实际用的结构是：主仓库放架构 Agent 的产出（契约文件、DDL），三个 worktree 分别给三个 Agent 用。编码 Agent 在agent-code目录里写代码，审查 Agent 在agent-review目录里跑测试和 review，架构 Agent 在主仓库里更新契约。

3.2 分支策略：短分支 + 频繁合并

多 Agent 并行最大的风险是合并冲突。三个 Agent 同时改代码，如果分支活得太久，合并时就是灾难。我的策略是短分支 + 频繁合并：每个功能点一个分支，编码 Agent 写完一个模块就立刻合并到集成分支，审查 Agent 在集成分支上 review。

具体节奏是：编码 Agent 每完成一个 Controller + Service + Mapper 的组合，就提交一次，分支存活时间不超过半天。审查 Agent 在集成分支上持续 review，发现问题就开一个 fix 分支，修完立刻合回。这样任何时刻，集成分支上的代码都是"接近可运行"的状态。

这个策略的代价是提交次数多、分支多，但好处是永远不会出现"合并地狱"。我见过太多项目，feature 分支开了两周，合并时几百个冲突，光解决冲突就花掉好几天。短分支策略把这个成本摊平到了每一天。

3.3 用 CI 做 Agent 产出的"自动验收"

CI 在这个项目里不只是"跑测试"，而是Agent 产出的自动验收关卡。我配了 GitLab CI，每次 push 触发以下流水线：

stages: - lint - build - test - contract-check lint: script: - mvn checkstyle:check - npm run lint build: script: - mvn clean package -DskipTests - npm run build test: script: - mvn test - npm run test:unit contract-check: script: - python scripts/check_contract.py

其中contract-check是我自己加的，专门检查 OpenAPI 契约文件和实际代码是否一致。这个关卡拦住过好几次编码 Agent 的"自由发挥"——它有时候会自作主张加个字段或改个类型，CI 一跑就暴露了。

CI 的另一个作用是给审查 Agent 提供客观依据。审查 Agent 的 review 意见里，凡是 CI 已经报出来的问题，它就不用重复说了，专注在 CI 覆盖不到的层面（比如业务逻辑正确性、边界条件）。这样审查 Agent 的 token 花在刀刃上。

4. RAG 知识库：让 Agent 记住项目的"潜规则"

4.1 为什么通用模型搞不定企业项目的"隐性知识"

通用大模型懂 Spring Boot、懂 Vue，但它不懂你这个项目的约定。比如：这个项目的所有金额字段都用BigDecimal且保留两位小数；所有时间字段都用LocalDateTime且时区固定；所有对外接口都要加@Log注解记录审计日志。这些"潜规则"如果不在 prompt 里说清楚，Agent 生成的代码就是"能跑但不符合规范"。

把这些规则全塞进 prompt 是不现实的——太长，而且每次都要重复。我的做法是建一个 RAG 知识库，把这些项目约定、编码规范、历史踩坑记录都存进去，Agent 在生成代码前先检索相关规则。

4.2 知识库的切分策略：按"规则"而不是按"文档"切

RAG 效果好不好，切分策略占一半。我一开始按文档切，一个规范文档切成若干段，结果检索出来的内容经常是"半截话"，Agent 理解不了。后来改成按规则切：一条规则一个 chunk，每个 chunk 包含"规则描述 + 正例 + 反例"。

比如一条 chunk 是这样的：

规则：所有金额字段必须使用 BigDecimal，禁止使用 double 或 float。 正例：private BigDecimal amount; 反例：private double amount; 适用场景：实体类、DTO、VO 中的金额字段。

这样切的好处是检索粒度精准。Agent 在写实体类时检索"金额字段"，直接命中这条规则，不会检索到无关的文档段落。实测下来，按规则切分后，Agent 生成代码的规范符合率从大概 70% 提升到了 95% 以上。

4.3 RAG 的瓶颈和绕行方案

RAG 不是银弹，这个项目里我遇到两个明显的瓶颈。

第一个瓶颈是检索不准。有些规则的关键词和代码里的术语对不上，比如规则里说"审计日志"，代码里叫@Log注解，纯向量检索可能匹配不上。我的绕行方案是混合检索：向量检索 + 关键词检索，两路结果合并后重排。关键词检索用 BM25，能兜住那些术语对不上的情况。

第二个瓶颈是知识库更新滞后。项目进行中会产生新的约定，比如"这个模块的错误码统一用 5xxxx 段"，如果知识库没更新，Agent 就不知道。我的做法是把知识库更新纳入 CI：每次合并到主分支，如果 diff 里包含新的约定（通过 commit message 里的特定标签识别），就自动触发知识库更新流程。

注意：RAG 知识库不是越大越好。我一开始把整个项目的历史文档全塞进去了，结果检索噪音很大。后来精简到只保留"当前有效的规则"，检索质量立刻上来了。知识库要定期清理，过期的规则比没有规则更危险。

5. 三周里我踩过的坑和对应的解法

5.1 编码 Agent 的"过度设计"倾向

编码 Agent 有个很讨厌的习惯：喜欢加抽象层。你让它写一个用户查询接口，它会给你搞出UserQueryService、UserQueryStrategy、UserQueryFactory三层，实际上业务逻辑就是一句SELECT * FROM user WHERE id = ?。这种过度设计在人类开发者里也常见，但 Agent 干这事更隐蔽，因为它生成的代码"看起来"很专业。

我的解法是在编码 Agent 的 prompt 里加一条硬规则：除非明确要求，否则不允许创建接口 + 实现类的组合，不允许使用设计模式。所有 Service 直接写成@Service标注的类，不抽接口。这条规则加上去之后，代码量直接少了三分之一，可读性反而更好了。

5.2 审查 Agent 的"老好人"问题

审查 Agent 一开始特别"客气"，review 意见都是"建议考虑..."、"或许可以..."这种。这种意见编码 Agent 根本不当回事，因为它没有"必须改"的强制力。后来我把审查 Agent 的输出格式改成分级：BLOCKER（必须改，否则不合并）、MAJOR（应该改）、MINOR（可选）。只有BLOCKER和MAJOR会进入修复流程，MINOR记录但不强制。

分级之后，审查 Agent 的意见有了"牙齿"。BLOCKER级别的问题，编码 Agent 必须修完才能合并。实测下来，每个模块平均有 2 到 3 个BLOCKER，主要是权限注解缺失和事务边界错误，这些都是上线后会出大问题的点。

5.3 上下文窗口的"遗忘"问题

编码 Agent 在处理大模块时，写到后面会"忘记"前面的约定。比如它前面写的 Controller 用了@PreAuthorize("hasRole('ADMIN')")，写到第五个 Controller 时忘了加。这不是模型能力问题，是上下文窗口的物理限制。

我的解法是分块 + 检查点。每个模块拆成不超过 5 个文件的小块，每块写完立刻跑一次 CI 的 lint 和 contract-check，通过后再写下一块。这样即使 Agent "忘了"，CI 也会立刻发现。另外，我在每个块的 prompt 开头都重复一遍核心约定（权限注解、事务、日志），用重复来对抗遗忘。

5.4 合并冲突的"预防式"处理

多 Agent 并行，合并冲突是必然的。我的处理原则是预防为主，解决为辅。预防的手段有三个：一是文件级隔离，不同 Agent 尽量不碰同一个文件；二是短分支，分支存活时间短，冲突窗口就小；三是约定文件修改权，OpenAPI 契约文件只有架构 Agent 能改，编码 Agent 只能读，审查 Agent 只能提意见。

即使这样，还是会有冲突，主要是pom.xml和package.json这种共享文件。我的做法是指定一个 Agent 负责共享文件，其他 Agent 需要加依赖时，不直接改文件，而是提交一个"依赖申请"（就是一个简单的 JSON 文件），由负责共享文件的 Agent 统一合并。这个流程听着麻烦，但比解决pom.xml的冲突简单多了。

6. 这套打法适合什么项目，不适合什么项目

6.1 适合的场景：模式化、契约清晰、横切关注点明确

这套三 Agent 流水线最适合的项目类型是企业级 CRUD 系统。这类项目的特征是：业务逻辑以增删改查为主，接口契约清晰，横切关注点（权限、日志、事务、校验）明确且统一。我做的这个项目就是典型，所以效果特别好。

另一个适合的场景是有现成规范和历史代码库的项目。因为 RAG 知识库需要"喂"规范，如果项目本身就有完善的编码规范和历史代码，知识库建起来很快，Agent 的产出质量也高。反过来，如果是一个全新的、没有任何规范的项目，你得先花时间定规范，这部分工作 Agent 帮不上太多忙。

6.2 不适合的场景：强创新、强交互、强领域知识

有三类项目我建议不要用这套打法。第一类是强创新项目，比如需要设计新算法、新架构的项目，Agent 的"过度设计"倾向和"按套路出牌"的习惯会拖后腿。第二类是强交互项目，比如需要频繁和用户确认需求的探索型项目，Agent 没法替你做需求判断。第三类是强领域知识项目，比如医疗、金融的核心业务逻辑，Agent 缺乏领域知识，生成的代码可能"语法正确但业务错误"，这种错误比语法错误更危险。

判断标准很简单：如果这个项目的需求文档能写到"任何合格开发者看了都能实现"的程度，那它就适合 Agent 流水线。如果需求本身还在模糊状态，需要人来反复澄清，那 Agent 帮不上忙，反而会增加沟通成本。

6.3 团队规模的影响：小团队收益最大

这套打法对团队规模很敏感。4 人团队 2 个月的活，我一个人 3 周做完，效率提升大概 4 倍。但如果是一个 20 人的团队，提升可能就没这么明显了，因为大团队里 Agent 产出的协调成本会上升，而且大团队本身就有分工，Agent 替代的是"执行"而不是"协调"。

我的观察是：1 到 5 人的小团队，用这套打法收益最大。因为小团队里每个人都是"多面手"，要同时做架构、编码、测试、运维，Agent 正好能补上这些角色的空缺。大团队里角色已经细分了，Agent 的边际收益反而低。

7. 如果重来一次，我会怎么调整

7.1 把契约校验提前到架构阶段

这次项目里，契约校验是在编码阶段才做的，导致架构 Agent 的一些命名不一致问题到编码时才暴露。如果重来，我会在架构 Agent 输出契约文件后立刻跑校验，不通过就打回。这样能把问题拦在源头，省掉编码阶段的返工。

7.2 给审查 Agent 加"业务逻辑"检查

这次的审查 Agent 主要检查横切关注点，对业务逻辑的检查比较弱。结果是有些业务逻辑错误（比如状态流转不对）到集成测试才发现。如果重来，我会给审查 Agent 加一个"业务规则"知识库，让它能对照业务规则检查代码逻辑。

7.3 知识库的维护要更早启动

这次知识库是项目进行到一半才建的，前半段的 Agent 产出规范符合率明显低于后半段。如果重来，我会在项目启动第一天就把知识库建起来，哪怕只有几条核心规则，也比没有强。

7.4 保留人工的"最终验收"环节

这次项目里，我虽然做了 review，但主要是抽查。如果重来，我会对核心模块做 100% 的人工 review，非核心模块才用抽查。因为 Agent 的错误有时候很隐蔽，CI 和审查 Agent 都可能漏掉，人工的最终验收是最后一道防线，不能省。

最后分享一个我在实际操作中的体会：这套打法的核心不是"AI 多强"，而是"流程多顺"。三个 Agent 的能力其实都差不多，真正决定效率的是它们之间的协作流程——契约文件、worktree 隔离、CI 关卡、知识库检索。这些"脚手架"搭好了，Agent 就是高效的执行者；搭不好，Agent 就是制造混乱的源头。我花在搭脚手架上的时间大概占整个项目的三分之一，但这部分投入是值得的，因为它让后面的三分之二变得可控。