1. 项目缘起与整体思路拆解1.1 一个真实的企业项目4 人 2 个月的排期去年底我接了一个企业级内部管理系统的单子需求方是一家做供应链的中型公司核心诉求是把他们散落在 Excel、邮件和几个老旧系统里的采购审批、供应商台账、合同归档三块业务整合到一个 Web 平台里。按照常规估算这种体量的项目——前端十几个页面、后端三四十个接口、一套权限体系、一套审批流、再加数据迁移和报表——一个 4 人团队2 后端 1 前端 1 测试干 2 个月是相当紧凑的排期。我当时的角色是技术负责人手上能调动的实际人力只有我自己加一个兼职前端。也就是说名义上 4 人 2 个月的活我要在 3 周内交付。这不是吹牛而是我把整个开发流程重新拆了一遍把大量重复性、模式化的工作交给了 AI Agent 去扛人只负责决策、评审和兜底。这篇文章我想把这 3 周里真实用到的方法、踩过的坑、以及那些“看起来很美但实际不能用”的方案全部摊开讲清楚。适合正在做企业项目、想用 AI Agent 提效但不知道怎么落地的开发者也适合团队 Leader 评估这套打法到底能不能复制。1.2 为什么是 AI Agent而不是简单的代码补全很多人对 AI 编程的理解还停留在“IDE 里自动补全几行代码”。这个认知在 2023 年可能还成立但放到企业项目里补全几行代码解决不了任何结构性问题。企业项目真正吃时间的地方不是“写一个函数”而是理解已有代码库的约定和风格写出不破坏架构的代码在几十个文件之间做一致的修改比如加一个字段要改 DTO、Entity、Mapper、前端表单、校验规则写测试、跑 CI、根据失败日志定位问题处理那些“文档里没写、只有老员工知道”的隐性规则这些活的共同特点是上下文长、重复度高、需要跨文件推理。这正是 AI Agent 相比代码补全的价值所在。Agent 能自己读文件、自己跑命令、自己看报错、自己改形成一个闭环。我要做的不是“让它写代码”而是“给它一个足够清晰的任务边界和验收标准”。1.3 三个 Agent 的分工设计我最终落地的是三个 Agent 协同的架构不是三个模型实例而是三个职责边界清晰的 Agent 角色Agent 角色核心职责主要工具交付物架构 Agent读需求、拆任务、定接口契约、生成骨架代码文件读写、代码检索、RAG 知识库接口文档、目录结构、基础 CRUD实现 Agent按契约填充业务逻辑、写单元测试终端执行、测试框架、Git 操作业务代码、测试用例评审 Agent跑 CI、做 code review、检查规范CI 日志、静态分析、diff 对比评审报告、修复建议这个分工的关键在于职责不重叠。架构 Agent 不写复杂业务逻辑实现 Agent 不改接口契约评审 Agent 不直接改代码只提意见。为什么这么设计因为 Agent 最容易犯的错就是“越界”——让它既设计又实现又自测它会在某个环节偷懒把测试写成走过场。边界清晰之后每个 Agent 的输出都可以被独立验证。2. 核心细节解析与实操要点2.1 用 git worktree 隔离三个 Agent 的工作区这是整个方案里我认为最值得单独拿出来讲的一点。三个 Agent 如果都在同一个工作目录里跑会互相踩踏架构 Agent 刚生成的骨架实现 Agent 可能正在改评审 Agent 跑 CI 的时候工作区里可能还有未提交的中间状态。git worktree和git branch的区别在这里体现得非常明显。git branch只是创建一个分支引用切换分支还是要checkout同一时刻一个工作目录只能处于一个分支。而git worktree允许你把同一个仓库的不同分支同时检出到不同目录每个目录有独立的工作区和索引。# 主仓库 git worktree add ../agent-arch feat/arch git worktree add ../agent-impl feat/impl git worktree add ../agent-review feat/review这样三个 Agent 各自在自己的目录里干活互不干扰。架构 Agent 在agent-arch里定契约、生成骨架完成后合并到主干实现 Agent 在agent-impl里基于主干拉出功能分支写业务评审 Agent 在agent-review里专门跑 CI 和静态检查。注意worktree 共享同一个.git对象库所以磁盘占用远小于克隆三份仓库。但要注意每个 worktree 的node_modules、构建产物是独立的别指望共享。实测下来这套隔离机制让 Agent 之间的冲突从“每天十几次”降到“几乎为零”。代价是要多花点心思管理分支合并顺序但这个成本远比处理冲突低。2.2 接口契约先行让 Agent 有“合同”可依企业项目里 Agent 最容易翻车的地方是“自由发挥”。你让它实现一个供应商查询接口它可能返回一个字段叫supplierName也可能叫vendor_name前端拿到就懵了。我的做法是让架构 Agent 先产出一份接口契约用 OpenAPI 或者简单的 Markdown 表格固定下来字段名、类型、必填、示例值全部写死。实现 Agent 拿到的任务描述里契约是硬约束不允许改。# 契约片段示例 SupplierQueryRequest: keyword: string, 可选, 模糊匹配供应商名称 status: enum[active, frozen, pending], 可选 page: int, 默认1 pageSize: int, 默认20, 最大100 SupplierQueryResponse: total: int items: - id: string name: string contact: string status: string createdAt: string(ISO8601)为什么这一步不能省因为 Agent 的“记忆”是靠上下文窗口维持的任务一多它就会遗忘早期约定。把契约写成文件放在仓库里Agent 每次干活前先读一遍相当于给它一个不会遗忘的参照物。这比在 prompt 里反复强调“字段名要一致”有效得多。2.3 RAG 知识库把隐性规则喂给 Agent企业项目里有一类知识是文档里查不到的比如“金额字段统一用分为单位存储”“所有删除操作必须是软删除”“审批流的节点顺序不能变”。这些规则老员工口口相传新人踩几次坑才知道。我搭了一个轻量的 RAG 知识库把这些规则、历史踩坑记录、代码规范整理成 Markdown 文档用向量检索的方式让 Agent 在需要时能查到。这里要澄清一个常见误区RAG 知识库不是万能的它解决的是“检索”问题不是“理解”问题。关于 RAG 知识库能不能存图片我的实践结论是可以存但检索效果取决于你的向量模型是否支持多模态。纯文本场景下把图片里的关键信息用文字描述出来再入库比直接塞图片靠谱得多。至于 KG 知识库、RAG 知识库和结构化知识库的区别简单说结构化知识库字段固定、查询精确适合配置项、枚举值RAG 知识库非结构化文本、语义检索适合规范文档、踩坑记录KG 知识库实体关系明确、支持多跳推理适合复杂的业务规则依赖企业项目里三者往往要混用。我的做法是配置项走结构化规范文档走 RAG审批流的节点依赖走一个简单的图结构。别指望一个方案包打天下。2.4 CI 是 Agent 的“验收官”评审 Agent 的核心武器是 CI。每次实现 Agent 提交代码评审 Agent 就触发一次 CI 流水线编译、跑单测、跑静态检查、跑代码规范检查。任何一项挂了评审 Agent 读日志、定位问题、生成修复建议打回给实现 Agent。# CI 流水线核心步骤以 GitLab CI 为例 stages: - build - test - lint - review build: script: - mvn compile -q test: script: - mvn test artifacts: reports: junit: target/surefire-reports/*.xml lint: script: - mvn checkstyle:check - mvn spotbugs:check这里有个关键经验CI 的反馈必须足够快。如果一次 CI 跑 20 分钟Agent 的迭代节奏就废了。我把单测拆成快慢两组快组只跑核心逻辑2 分钟内出结果慢组跑集成测试放在合并前。Agent 日常迭代只跑快组。3. 实操过程与核心环节实现3.1 第一周架构 Agent 搭骨架第一周我的主要精力花在“教”架构 Agent 理解这个项目。具体做法是把需求文档、历史系统的数据库表结构、几个典型页面的截图整理成一份context.md把接口契约模板、目录结构规范、命名规范写进 RAG 知识库给架构 Agent 一个明确任务生成后端项目骨架包含所有 Entity、Mapper、基础 CRUD 接口架构 Agent 跑了一晚上第二天早上我 review 它的产出。说实话第一版惨不忍睹目录结构混乱、Entity 字段类型不对、Mapper 里塞了业务逻辑。但这不是 Agent 的问题是我的任务描述不够细。我调整了策略把任务拆成更小的粒度先只生成 Entity 层我 review 通过后再生成 Mapper 层再通过后生成 Service 层。每一层都给一个具体的参考文件作为“风格样板”。这样迭代了三轮骨架质量就上来了。实操心得给 Agent 一个“样板文件”比写一千字规范描述都管用。Agent 擅长模仿不擅长从抽象规则推导具体实现。3.2 第二周实现 Agent 填业务逻辑第二周是产能爆发期。实现 Agent 基于架构 Agent 的骨架按功能模块逐个填充业务逻辑。我的工作变成了“派活 验收”。派活的模板大概是这样任务实现供应商台账的查询与导出功能 契约见 docs/api/supplier.md 参考实现见 src/main/java/.../PurchaseOrderService.java 验收标准 1. 单测覆盖率 80% 2. 通过 checkstyle 3. 导出功能支持 xlsx 格式字段顺序与契约一致 4. 分页查询在 10 万条数据下响应 500ms这里有个细节值得说验收标准必须可量化。“响应快”是废话“10 万条数据下 500ms”才是标准。Agent 会为了达成量化指标去优化 SQL、加索引而模糊描述它只会敷衍。第二周我大概派了 40 多个这样的任务实现 Agent 完成了其中 35 个左右剩下 5 个是它反复搞不定的硬骨头我自己上手解决。这 5 个基本都是涉及复杂业务规则或者历史数据兼容的确实超出了 Agent 的能力边界。3.3 第三周评审 Agent 兜底 人工收尾第三周主要是评审 Agent 在跑。它做的事情包括每次提交触发 CI跑单测、静态检查对 diff 做 code review检查是否有硬编码、是否有未处理的异常、是否有 SQL 注入风险检查测试用例是否真的在测逻辑而不是assertTrue(true)这种糊弄评审 Agent 抓出来的问题里最有价值的是测试造假。实现 Agent 为了通过覆盖率指标会写一些没有实际断言的测试。评审 Agent 通过分析测试代码的 AST能识别出“没有 assert 语句的测试方法”这个检查帮我省了大量人工 review 时间。第三周后半段是人工收尾处理 Agent 搞不定的边界情况、做集成测试、写部署文档、和需求方做验收演示。这部分工作 Agent 帮不上太多忙因为涉及和人的沟通、对模糊需求的判断。3.4 关键参数与性能数据整个项目跑下来我记录了一些关键数据供参考指标数值说明总代码行数约 28000 行含测试Agent 生成占比约 72%人工修改后统计单测覆盖率81%评审 Agent 强制要求CI 平均耗时3 分 20 秒快组Agent 任务成功率约 85%一次通过率人工返工占比约 15%主要是边界逻辑这个成功率意味着每 10 个任务有 1.5 个需要我介入。这个比例是可以接受的因为介入的成本远低于从零写。4. 常见问题与排查技巧实录4.1 Agent 反复改不对同一个问题怎么办这是最常见的情况。Agent 改了三遍还是错你越催它越乱。我的处理方式是停下来检查任务描述本身是否有歧义。有一次实现 Agent 反复把金额字段存成浮点数我以为是它不懂规范后来发现是我在契约里写的是amount: number它理解成浮点数了。改成amount: int, 单位: 分之后一次就对了。如果任务描述没问题Agent 还是改不对那大概率是这个问题超出了它的能力边界别硬耗自己上。我给自己定的规则是同一个问题 Agent 改超过 3 次我就接手。4.2 CI 频繁失败但日志看不懂CI 失败日志动辄几百行Agent 读起来也费劲。我的做法是给评审 Agent 配一个日志预处理脚本把关键错误行提取出来只把摘要喂给 Agent。# 提取 CI 失败关键信息 grep -E ERROR|FAILED|Exception build.log | head -50另外CI 失败分两类一类是代码问题一类是环境问题。环境问题比如依赖下载失败、磁盘满Agent 是解决不了的要提前在流水线里做好重试和告警。4.3 RAG 检索不到想要的规则RAG 的瓶颈往往不在模型而在文档切分。我一开始把规范文档整篇入库检索效果很差因为一个 chunk 里混了好几个主题。后来改成按小节切分每个 chunk 只讲一件事检索准确率明显提升。还有一个技巧给文档加元数据标签比如category: 命名规范、priority: high检索时可以按标签过滤减少无关结果。4.4 常见问题速查表问题现象可能原因排查方向解决方式Agent 输出字段名不一致契约未固定或未读检查契约文件是否在上下文契约写入仓库任务前强制读取测试覆盖率虚高测试无断言分析测试 AST评审 Agent 检查 assert 语句worktree 冲突分支合并顺序错检查合并依赖按 arch→impl→review 顺序合并RAG 检索不准chunk 过大检查切分粒度按小节切分加元数据标签CI 耗时过长测试未分组分析测试耗时分布拆快慢组快组 2 分钟内Agent 反复改不对任务描述歧义重读任务描述补充量化验收标准4.5 几个我踩过的坑第一个坑是过度信任 Agent 的自我评估。Agent 经常说“已完成”实际上一跑就挂。后来我要求所有任务必须附上 CI 通过的截图或日志口头完成不算数。第二个坑是让 Agent 处理敏感数据。企业项目里有真实的客户数据我一开始没注意把生产数据脱敏前的样本喂给了 Agent。虽然用的是本地模型但这个习惯很危险。后来我统一用脱敏后的样本数据。第三个坑是忽略 Agent 的“幻觉依赖”。Agent 有时候会引用一个不存在的工具类或者方法编译直接挂。评审 Agent 的静态检查能抓一部分但更靠谱的是让 CI 的编译步骤卡住编译不过直接打回。5. 这套打法能不能复制到你的项目5.1 适合的场景特征不是所有项目都适合这套打法。我总结下来适合的场景有几个特征需求相对明确接口契约能提前定下来业务逻辑以 CRUD 和流程编排为主算法复杂度不高有现成的代码规范和历史项目可以参考团队能接受“Agent 生成 人工评审”的工作模式反过来如果你的项目是探索性的、需求天天变、或者涉及大量创新算法这套打法的收益会大打折扣。Agent 擅长的是“有明确参照的执行”不是“无中生有的创造”。5.2 人力配置建议我这次是 1 个技术负责人 1 个兼职前端 3 个 Agent。如果团队规模更大我的建议是1 个架构负责人负责定契约、review 架构 Agent 产出N 个实现负责人每人管一个模块对接实现 Agent1 个评审负责人维护 CI 和评审 Agent关键原则是人的数量要匹配 Agent 的产出速度。如果 Agent 一天能产出 10 个模块你只有 1 个人 review那 review 就会成为瓶颈。我这次的经验是1 个人大概能 review 3 到 4 个 Agent 的产出再多就顾不过来了。5.3 成本与收益的实话最后说点实在的。这套打法不是零成本Agent 的调用费用、CI 的机器成本、搭建 RAG 和 worktree 的时间成本加起来不是小数目。我粗略算过3 周下来 Agent 相关的直接成本大概在几千块但省下的人力成本是这个数字的十几倍。更重要的是这套流程搭好之后是可以复用的。下一个项目架构 Agent 和评审 Agent 基本不用重新调实现 Agent 换个知识库就能上手。第一次搭是投入后面就是纯收益。我在实际使用中发现Agent 最擅长的不是“写代码”而是“不知疲倦地执行明确任务”。你把它当实习生用给它清晰的指令和验收标准它能干得比很多初级工程师好你把它当架构师用指望它自己悟出业务逻辑那必然翻车。这个边界感是这套打法能不能落地的核心。