企业官网建设流程全解析

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

先把结论摆在前面：这个项目能压缩到三周，靠的不是让 AI Agent 替我写代码那么简单，而是把整个交付流程里最耗人的几个环节——需求拆解、并行开发、代码审查、知识检索——全部重新编排了一遍。四人团队两个月的工作量，折算下来大约是 320 人时。我一个人三周，按每天有效投入 6 小时算，也就 90 人时左右。中间那 230 人时的差额，就是这篇文章要拆的东西。

先说清楚这个项目的背景。这是一个企业内部管理系统，包含权限模块、审批流、数据看板、报表导出四块核心功能，技术栈是 Spring Boot 后端加 Vue 前端，数据库用 MySQL，部署走 GitLab CI。团队原本的排期是四个人并行开发两个月，其中后端两人、前端一人、测试一人。我接手之后，用三个 AI Agent 分别承担后端接口生成、前端组件生成、测试用例生成，自己只做架构决策、关键逻辑审核和集成联调。

这里有个很多人会误解的点：AI Agent 不是"帮你写代码的工具"，它更像是一个能独立完成子任务的虚拟同事。区别在于，你得给它足够清晰的边界和上下文，否则它产出的东西你改起来比自己写还慢。我见过太多人把 Agent 当成高级代码补全来用，结果就是生成一堆看起来能跑、实际上到处是坑的代码，最后返工的时间比省下来的还多。

所以这篇文章不讲"AI 多厉害"，讲的是怎么把一个企业项目拆成 Agent 能接住的粒度，怎么让三个 Agent 并行不打架，怎么在 CI 和 code review 环节把住质量关，以及 RAG 知识库在整个流程里扮演什么角色。适合有一定工程经验、想真正把 AI Agent 用进实际交付的开发者，也适合正在评估"AI 能不能替代部分人力"的技术负责人。

我踩过的坑不少，有些是工具本身的限制，有些是我自己编排流程时的失误。下面按实际推进的顺序，一块一块拆开讲。

2. 三个 Agent 的分工边界：为什么不是越多越好

2.1 从"一个全能 Agent"到"三个专精 Agent"的取舍

最开始我试过用一个 Agent 干所有事。给它一个完整的模块需求，让它同时生成后端接口、前端页面和测试用例。结果非常糟糕：生成的代码风格前后不一致，后端返回的数据结构和前端期望的对不上，测试用例覆盖的路径和实际接口逻辑有偏差。原因很简单——一个 Agent 在一次对话里要同时维护三套上下文，它的注意力被稀释了。

后来我改成三个 Agent，每个只负责一个层面：

• 后端 Agent：输入是接口文档和数据库表结构，输出是 Controller、Service、Mapper 三层代码，以及对应的单元测试。
• 前端 Agent：输入是页面原型和接口契约，输出是 Vue 组件、API 调用层和表单校验逻辑。
• 测试 Agent：输入是接口契约和业务规则，输出是集成测试用例和边界条件测试。

这三个 Agent 之间不直接通信，它们通过接口契约这个中间产物来对齐。接口契约是我手写的，用 OpenAPI 格式定义，包含每个接口的路径、方法、请求体、响应体、错误码。这份契约是整个项目的"宪法"，三个 Agent 都基于它工作，谁也不能偏离。

提示：接口契约一定要自己写，不要让 Agent 生成。契约是三个 Agent 协作的唯一对齐点，一旦契约本身有歧义，后面所有产出都会跟着歪。

2.2 为什么是三个而不是五个或两个

有人会问，既然专精更好，为什么不拆成五个 Agent，比如把数据库操作单独拆出来？我的实测结论是：Agent 数量要和"上下文隔离的必要性"匹配，而不是越多越好。

拆成五个的问题是，Agent 之间的接口变多了。三个 Agent 有 3 对协作关系，五个 Agent 就有 10 对。每多一对协作关系，就多一个对齐成本和出错点。数据库操作和后端逻辑耦合太紧，拆开之后后端 Agent 生成 Service 时还得等数据库 Agent 先产出 Mapper，串行化了，反而慢。

两个 Agent 也不够。后端和前端必须分开，因为它们的上下文差异太大——后端关心事务、并发、数据一致性，前端关心渲染、交互、状态管理。硬塞进一个 Agent，它会在两种思维模式之间反复切换，产出质量明显下降。

三个是刚好能覆盖"后端逻辑、前端交互、质量验证"这三个正交维度的最小数量。测试 Agent 单独拆出来，是因为测试的思维方式和开发完全不同——开发想的是"怎么让功能跑通"，测试想的是"怎么让它跑不通"。这两种思维放在一个 Agent 里会互相干扰。

2.3 Agent 之间的"交接棒"怎么设计

三个 Agent 并行工作，最大的风险是"各干各的，最后合不上"。我的做法是设置三个同步点：

契约冻结这一步特别关键。我在第一个模块上偷懒，契约只写了个大概就开工了，结果后端 Agent 把某个字段定义成Integer，前端 Agent 理解成String，联调的时候报了一堆类型错误。后来我强制要求契约必须精确到字段类型和是否可空，这类问题就再没出现过。

契约变更的处理也有讲究。开发过程中需求微调是常事，但不能让某个 Agent 自己改了契约就继续干。我的规则是：任何契约变更都要先停下来，评估影响范围，然后三个 Agent 一起更新。听起来很重，但实际上变更频率很低，而且每次变更如果不同步，后面返工的代价远大于停下来对齐的成本。

3. git worktree 撑起并行开发：和 branch 到底差在哪

3.1 为什么 branch 不够用，非要上 worktree

三个 Agent 并行工作，意味着同一时间有三份代码在被修改。如果用传统的git branch，你只能在一个工作目录里来回切换分支。Agent A 在写后端的时候，工作目录里是后端分支的代码；Agent B 要写前端，就得先git checkout到前端分支。这个切换过程会打断 Agent 的工作流，而且切换时如果有未提交的改动，还得先 stash，非常麻烦。

git worktree解决的就是这个问题。它允许你把同一个仓库的多个分支同时检出到不同的目录。也就是说，后端 Agent 在/work/backend目录里改后端分支，前端 Agent 在/work/frontend目录里改前端分支，测试 Agent 在/work/test目录里改测试分支，三个目录互不干扰，共享同一个.git仓库。

# 在主仓库里创建三个 worktree git worktree add ../work-backend feature/backend git worktree add ../work-frontend feature/frontend git worktree add ../work-test feature/test # 查看当前所有 worktree git worktree list

这样每个 Agent 在自己的目录里独立工作，提交、切换、回滚都不影响别人。等各自完成后，再通过 merge 或 rebase 合并到主分支。

3.2 worktree 和 branch 的本质区别

很多人搞不清 worktree 和 branch 的关系，我用一句话说清楚：branch 是"提交历史的分叉"，worktree 是"工作目录的分身"。

一个 branch 可以对应零个、一个或多个 worktree。默认情况下，你 clone 一个仓库，主分支对应一个 worktree（就是你的工作目录）。当你git worktree add的时候，你是在为某个分支再创建一个工作目录。同一个分支不能同时被两个 worktree 检出，这是 Git 的限制，也是合理的——否则两个目录同时改同一个分支，冲突无法处理。

对 AI Agent 场景来说，worktree 的价值在于消除了上下文切换的成本。Agent 不需要知道"现在该切到哪个分支"，它只需要在自己的目录里持续工作。我实测下来，用 worktree 之后，三个 Agent 的并行效率比用 branch 切换高了大概 40%，主要省在不用反复 stash 和 checkout 上。

3.3 worktree 使用中的几个坑

第一个坑是目录规划。worktree 的目录最好放在主仓库的同级或专门的worktrees/目录下，不要放在仓库内部，否则 Git 会把 worktree 目录当成未跟踪文件，git status会很难看。

第二个坑是清理。Agent 完成任务后，对应的 worktree 要记得删掉，否则会残留一堆目录。删除命令是git worktree remove ../work-backend，如果目录里有未提交的改动，需要加--force。

第三个坑是分支冲突。如果两个 Agent 不小心检出了同一个分支，Git 会直接报错。这个反而是好事，能提前发现问题。我在流程里规定，每个 Agent 的分支名必须带前缀（feature/backend-、feature/frontend-），从命名上就避免撞车。

注意：worktree 不是万能的。如果两个 Agent 需要修改同一批文件，worktree 也救不了你，该冲突还是冲突。所以拆分任务时，要尽量让不同 Agent 负责不同的文件集合。

4. CI 流水线怎么接住 Agent 的产出

4.1 Agent 生成的代码，CI 要检查什么

Agent 生成的代码有个特点：表面看起来都很规范，但细节上容易出问题。比如命名风格统一但不符合项目规范，异常处理写了但吞掉了关键错误，日志打了但泄露了敏感信息。所以 CI 不能只跑单元测试，要加几道针对性的检查。

我的 GitLab CI 流水线分四个阶段：

stages: - lint - test - security - build lint: stage: lint script: - mvn checkstyle:check - mvn spotbugs:check - npm run lint test: stage: test script: - mvn test - npm run test:unit security: stage: security script: - mvn dependency-check:check - grep -rn "password\|secret\|token" src/ || true build: stage: build script: - mvn package -DskipTests - npm run build

lint 阶段用 Checkstyle 和 SpotBugs 检查代码规范，前端用 ESLint。这一步能拦住大部分 Agent 生成的"风格漂移"问题。test 阶段跑单元测试，覆盖率低于 70% 直接失败。security 阶段做依赖漏洞扫描和敏感信息扫描，后者是我专门加的，因为 Agent 有时候会把示例里的假密码写进代码。

4.2 为什么 CI 反馈要"快而准"

Agent 的工作模式是"生成-验证-修正"的循环。如果 CI 反馈太慢，Agent 就得干等着，并行效率大打折扣。我的做法是把 CI 拆成"快速检查"和"完整检查"两层：

• 快速检查：只跑 lint 和单元测试，控制在 3 分钟内。Agent 每次提交都触发。
• 完整检查：跑安全扫描和构建，控制在 10 分钟内。合并到主分支前触发。

快速检查的 3 分钟是硬指标。我试过把安全扫描也放进快速检查，结果每次要等 8 分钟，Agent 的并行度直接掉了一半。后来拆开之后，Agent 的迭代速度明显上来了。

还有一个细节：CI 的失败信息要结构化。默认的 CI 日志是一大坨文本，Agent 读起来很费劲。我在流水线里加了一步，把失败信息解析成 JSON 格式，包含文件路径、行号、错误类型、错误描述。Agent 拿到这个 JSON，能直接定位到问题，不用在日志里大海捞针。

4.3 code review 环节，人要看什么

CI 能拦住机器能判断的问题，但有些东西必须人来看。我在 code review 环节重点关注三类：

第一类是业务逻辑的正确性。Agent 能写出语法正确的代码，但它不理解业务。比如审批流里的"会签"和"或签"，Agent 可能都实现成一样的逻辑，但实际业务里这两个完全不同。这类问题 CI 测不出来，必须人看。

第二类是边界条件的处理。Agent 生成的代码往往只处理"正常路径"，对空值、超长输入、并发冲突这些边界情况考虑不足。我会专门检查每个接口的参数校验和异常分支。

第三类是架构一致性。Agent 可能用了一种新的设计模式，虽然能跑，但和项目现有架构不一致。比如项目里统一用ResponseEntity包装响应，Agent 却直接返回了对象。这类问题不影响功能，但会破坏代码的一致性。

提示：code review 不要试图看完所有代码。我的做法是让 Agent 自己生成一份"变更摘要"，列出每个文件的改动点和理由，我只审查摘要里标记为"高风险"的部分。这样能把 review 时间压缩到原来的三分之一。

5. RAG 知识库：让 Agent 记住项目规范

5.1 为什么 Agent 需要 RAG

Agent 的上下文窗口是有限的。一个企业项目的代码规范、接口约定、历史决策，加起来可能几十万字，不可能全部塞进 prompt。而且每次对话都塞一遍，token 成本高得离谱。

RAG（检索增强生成）解决的就是这个问题。它把项目知识存进向量数据库，Agent 需要的时候，根据当前任务检索相关片段，只把最相关的部分塞进 prompt。这样既保证了 Agent 能拿到需要的上下文，又控制了 token 消耗。

我搭的 RAG 知识库包含四类内容：

• 代码规范：命名约定、分层规则、异常处理规范、日志规范。
• 接口契约：所有接口的 OpenAPI 定义，按模块分片存储。
• 历史决策：项目过程中做过的技术选型和理由，比如"为什么用 MyBatis 而不是 JPA"。
• 常见问题：踩过的坑和解决方案，比如"分页查询的 count 语句要单独优化"。

5.2 RAG 知识库能存图片吗

这是热词里被问得很多的一个问题。答案是：能存，但检索效果取决于你的方案。

纯文本的 RAG 是把文本切片、向量化、存进向量库。图片不能直接向量化，需要先转成文本描述。有两种做法：

第一种是用多模态模型给图片生成描述，把描述文本存进向量库。比如一张架构图，生成描述"这是三层架构图，上层是 Controller，中层是 Service，下层是 Mapper"，检索时匹配的是这段描述。缺点是描述可能丢失图片里的细节。

第二种是把图片和文本一起存进支持多模态的向量库，检索时同时匹配文本和图片特征。这种方式效果更好，但对向量库的要求更高，成本也更大。

我的项目里图片不多，用的是第一种方案。架构图和流程图用多模态模型生成描述后存入，检索时能命中。但如果你的项目里有大量设计稿、UI 图，建议用第二种方案，或者干脆把图片单独管理，RAG 只负责文本部分。

5.3 RAG 的瓶颈在哪

用了几个月，我总结出 RAG 的三个主要瓶颈：

第一个瓶颈是切片策略。切片太粗，检索出来的内容包含大量无关信息，浪费 token；切片太细，又可能丢失上下文，检索出来的片段不完整。我的经验是，代码类知识按"函数"或"类"切片，文档类知识按"段落"切片，切片之间保留 20% 的重叠。

第二个瓶颈是检索精度。向量检索是基于语义相似度的，但语义相似不等于真正相关。比如你搜"分页查询优化"，可能检索出一堆"查询优化"的通用建议，但真正需要的是项目里那条具体的分页规范。解决办法是混合检索——向量检索加关键词检索，两者结果加权排序。

第三个瓶颈是知识更新。项目在推进，规范在变化，RAG 知识库如果不同步更新，Agent 就会拿到过时的信息。我的做法是把知识库的更新也纳入 CI 流程，每次代码合并时，自动检查是否有规范文档变更，有的话触发知识库重建。

6. 三周交付的完整时间线复盘

6.1 第一周：契约冻结和基础设施搭建

第一周基本没写业务代码，全在搭架子。周一和周二梳理需求，把四个模块的功能点拆成 47 个接口，写成 OpenAPI 契约。周三搭 worktree 环境，配好三个 Agent 的工作目录和分支。周四搭 RAG 知识库，把代码规范和接口契约灌进去。周五配 CI 流水线，跑通 lint 和 test 两个阶段。

这一周看起来"没产出"，但恰恰是最关键的。我见过太多项目一上来就写代码，写到一半发现接口对不上，返工的时间远超前期规划的时间。契约冻结这一步，把后面可能出现的对齐问题提前消灭了。

6.2 第二周：三个 Agent 并行冲刺

第二周是产出最密集的一周。三个 Agent 同时开工，后端 Agent 生成接口和 Service，前端 Agent 生成页面和组件，测试 Agent 生成用例。我每天做三件事：早上检查前一天的 CI 结果，中午做 code review，晚上处理 Agent 之间的契约变更。

这一周遇到的最大问题是测试 Agent 的用例覆盖不全。它生成的用例大多覆盖正常路径，对异常路径覆盖不足。我的解决办法是给它一份"异常场景清单"，明确列出每个接口需要测试的异常情况，比如参数为空、参数超长、并发冲突、权限不足。有了这份清单，测试覆盖率从 62% 提到了 85%。

6.3 第三周：集成联调和收尾

第三周主要是联调和修 bug。前后端对接的时候，发现了一些契约里没定义清楚的细节，比如时间字段的格式、枚举值的映射。这些问题在契约里补上之后，让对应的 Agent 重新生成相关代码。

联调阶段我还做了一件事：让测试 Agent 生成端到端的集成测试。这些测试模拟真实用户操作，从登录开始，走完整个审批流程，验证数据看板的数字是否正确。这类测试跑起来慢，但能发现单元测试发现不了的问题。

三周下来，最终交付的代码量大约是 18000 行，其中 Agent 生成的部分占 75%，我手写的部分占 25%（主要是契约、关键业务逻辑和集成代码）。bug 数量比预期少，上线后第一周只收到 3 个问题反馈，都是边界情况，当天就修完了。

7. 几个让我少走弯路的关键决策

7.1 契约先行，宁可慢一天也不省这一步

前面反复提契约，这里再强调一次。契约不是"文档"，是三个 Agent 之间的通信协议。协议不清楚，通信就会出错。我在第一个模块上省了这一步，结果返工了两天。后面三个模块老老实实先写契约，每个模块省下的返工时间至少一天。

写契约的时候有个技巧：把错误码也定义清楚。Agent 生成异常处理代码时，如果不知道有哪些错误码，就会自己编一套，导致前后端对不上。我在契约里定义了统一的错误码规范，比如 40001 表示参数错误，40003 表示权限不足，50001 表示系统异常。Agent 照着这个规范生成，前后端的错误处理就对齐了。

7.2 Agent 的产出必须过 CI，不能靠"看起来对"

Agent 生成的代码有个迷惑性：它看起来很规范，命名整齐，注释齐全，容易让人放松警惕。但"看起来对"和"实际对"是两回事。我坚持所有 Agent 产出必须过 CI，lint 不过、测试不过，一律打回重做。

这个原则救了我好几次。有一次后端 Agent 生成了一个查询接口，逻辑看起来没问题，但 CI 的 SpotBugs 检查报了一个"可能的空指针"警告。我一看，果然在某个分支下会返回 null，前端没做判空处理。如果靠人眼看，这种问题很容易漏掉。

7.3 人的价值在决策，不在敲代码

三周做完这个项目，我最大的体会是：AI Agent 替代的是"执行"，不是"决策"。契约怎么定、架构怎么分层、异常怎么处理、哪些边界要考虑，这些决策还是得人来做。Agent 能把你从重复的编码劳动里解放出来，但前提是你得知道要它做什么。

我见过一些人用 Agent 的方式是"给个需求，等它生成，然后改改就用"。这种方式在简单任务上可行，但在企业项目里会出大问题。企业项目的复杂度不在于代码本身，而在于业务规则、历史包袱、团队约定这些"隐性知识"。这些知识 Agent 不知道，得你来告诉它，或者通过 RAG 喂给它。

所以我的建议是：把 Agent 当成一个执行力很强但需要明确指令的初级工程师。你给它的指令越清晰，它的产出越好。你偷懒省掉的思考，最后都会变成返工的时间还回来。

最后分享一个我在实操中总结的小技巧：给每个 Agent 建一个"工作日志"。每次它完成任务后，让它自己记录这次做了什么、遇到什么问题、怎么解决的。这些日志积累起来，一方面能帮你复盘，另一方面可以喂回 RAG 知识库，让后续的任务检索到这些经验。我用这个方法，让 Agent 在第三个模块上的产出质量明显高于第一个模块，因为它"记住"了前面踩过的坑。