企业官网建设流程全解析

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 不改接口契约，评审 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 理解这个项目。具体做法是：

1. 把需求文档、历史系统的数据库表结构、几个典型页面的截图整理成一份context.md
2. 把接口契约模板、目录结构规范、命名规范写进 RAG 知识库
3. 给架构 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 关键参数与性能数据

整个项目跑下来，我记录了一些关键数据，供参考：

这个成功率意味着，每 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 常见问题速查表

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 个实现负责人，每人管一个模块，对接实现 Agent
• 1 个评审负责人，维护 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 最擅长的不是“写代码”，而是“不知疲倦地执行明确任务”。你把它当实习生用，给它清晰的指令和验收标准，它能干得比很多初级工程师好；你把它当架构师用，指望它自己悟出业务逻辑，那必然翻车。这个边界感，是这套打法能不能落地的核心。