嘉为蓝鲸 AI 研发实践：从 AI 辅助编码到 Agentic 研发范式

一、 AI 辅助编程的局限性

我们很早就开始让 AI 参与日常研发，但随着实践深入，一个反直觉的现象开始浮出水面：工具用得越来越熟，问题却越来越多，交付数据反而不支持主观感受。

1) 上下文工程有效，但远远不够：

我们从 GitHub Copilot 的 instructions.md 开始构建工程上下文，后来统一迁移到 AGENTS.md。效果肉眼可见：Agent 更懂规范，违规代码明显减少。但随着任务复杂度上升，五个困境开始暴露。

1) 困境一：长上下文中的注意力丢失

LLM 在处理复杂任务的中后段时，AGENTS.md 开头写的约束会悄悄失效 —— 规则在注意力竞争中输给了眼前的代码，导致随机违规，难以预判。

2) 困境二：MVC 架构天然不利于 Agent

历史系统基于 Java MVC 架构。MVC 在复杂业务下，单层 Service 必然会出现职责蔓延：业务逻辑散落在各处，组件之间循环依赖，代码里开始出现几种典型的代码异味 ——

・发散式变化：同一个类因为不同业务原因被反复修改，改支付逻辑要动它，改通知逻辑也要动它

・霰弹式修改：一个业务变更需要同时修改多个看似不相关的类

・依恋情结：一个方法对其他类的数据兴趣远大于对自己类的数据

这些问题对人来说已经够头疼了，对 Agent 来说更致命。发散式变化和霰弹式修改意味着完整的业务逻辑被打散在多个文件里，Agent 在有限的上下文窗口内几乎不可能拼出全貌，于是经常出现「改了这里、漏了那里」的问题。Feature Envy 则让 Agent 频繁判断错误逻辑归属，把代码写到了不该写的地方。

3) 困境三：代码风格不一致，让代码库变成噪声源

根因不是写法差异，而是团队没有形成显式的工程共识，代码库沉淀的是个人偏好而非集体约定。Agent 生成代码时会从现有代码推断规范 —— 同类问题存在三种写法，它就看到三个正确答案。更糟的是，Agent 生成的新代码加入后进一步稀释风格信号，形成风格熵增的正反馈循环：代码库越乱，Agent 生成越乱。

4) 困境四：缺少单元测试，Agent 无法自我纠错

没有可靠的反馈机制，Agent 不知道自己改对了还是改错了，每一个「编码→验证」循环都必须人工介入。

5) 困境五：PRD 和 Agent 之间缺少桥梁

需求文档存在 CTeam 里，格式面向人阅读，研发需要手动转化为 Spec，这个翻译过程耗时且容易出现信息损耗。

02 我们引入了 SDD，解决了一部分问题

接触到 SDD（Spec Driven Development）之后，我们选用 OpenSpec 作为工具，在一个大型功能模块上完整跑了一遍工作流。效果是真实的：Agent 对设计意图的理解更准确，生成代码的整体质量有明显提升。

但局限同样真实：

・杀鸡用牛刀：简单 CRUD 接口，文档编写成本已超过直接编码成本。

・返工成本高：评审发现问题就要回到 Spec 重改，Agent 再重新处理大量文档，这个链路在需求模糊的早期阶段极慢。

・解决不了架构问题：Spec 明确了「做什么」，但没有解决「怎么做才符合架构规范」，Agent 还是会在「逻辑该放哪」上出错。

・Spec 难以保鲜：需求频繁变更是常态，过时的 Spec 比没有 Spec 更危险 —— 错误的指引比没有指引更具误导性。

03 代码评审，开始成为最大瓶颈

Agent 带来最直接的变化是代码量大幅增加。批量评审几百行「AI 写的、自己没参与设计的代码」，认知负担远高于审查自己熟悉的代码。团队普遍反映评审越来越没有成就感，评审疲劳带来的后果是：有效性下降，问题在后续测试或上线后才暴露。

随着 Agent 生成有效代码的速度越来越快，研发已经达成共识：人工代码评审是现在 Agent 开发速度的最大瓶颈。

04 主观感觉提效了，复盘数据却不支持

用了 AI 之后，主观感受是效率大幅提升，但复盘会上的实际交付数据，提升幅度远低于预期，某些任务类型上甚至出现了负提升。

原因有三：

・写代码只占研发工作的 30%–50%，Agent 把编码效率提升 50% 对整体交付的贡献只有 15%–25%；

・省下的编码时间被 Spec 编写、Code Review、测试验证吃掉了；

・「Agent 跑、研发等、再接手评审」的工作流在等待阶段产生大量碎片时间，长度不固定，既无法启动新任务，又白白流失。

05 上下文工程有效，但远远不够

我们一直在用 AI 辅助人，而不是让 AI 替代人完成系统中的某个环节。

生成速度快了，但验证、评审、修正还是原来的人来跑。Agent 吞吐量远超人工处理速度时，人就成了整个系统的速度上限。问题不出在模型能力上，而是工作流还是开环的 ——AI 生成，人判断，人修正，再循环。

二、 Agentic 研发范式

蒸汽机时代，工人守在机器旁边手动调节阀门，最终成为整个系统的速度上限。有了离心调速器之后，机器自己感知偏差、自己调节、自己维持稳态。

第一章的所有问题，回头看都可以归结为一句话：我们一直在扮演调速器的角色。读完OpenAI的Harness Engineering之后，我们意识到——工程师的工作，应该是设计调速器，而不是亲手拧阀门。

1) 认知转变：从「AI 辅助人」到「人驾驭 AI」：

我们最初把 Agent 理解成更聪明的 Copilot—— 用它加速编码，人负责质量、Review、发现问题、修复。这套机制有一个隐藏的结构性问题：人在扮演调速器。人工 Review 是传感器，人工修改是执行器。在人工编码时代，生成速度和审核速度大致匹配，勉强能转。Agent 介入后，生成速度大幅提升，人作为调速器的速度没变 —— 瓶颈必然出现，而且会随着 Agent 能力提升越来越严重。OpenAI 的判断直接点出了这个问题：

「当事情进展不顺利时，解决方案基本上再也不会是 ' 再努力一点 '。取得进展的唯一方式是让 Agent 来完成工作，而人类工程师则总是追问：究竟还需要什么样的能力，我们又该如何让这个能力对 Agent 来说既清晰可读又可强制执行？」

认知转变的核心是：人的价值不在于比 AI 更能写代码，而在于设计让 AI 能稳定产出正确代码的系统。

Kubernetes 工程师不管理每一个 Pod，他们声明目标状态，控制器持续把实际状态对齐过去。我们在 smp 想做的是同一件事：让代码库也有一个自己的控制器。

当 AI 能力继续增强，人工维护的 scaffolding 会越来越少，但驾驭者的核心职责不会消失 —— 定义目标态、校准传感器、在系统判断不了的边界问题上做裁决。这是工程师价值在 AI 时代的真正锚点。

2) Agentic 系统的三个核心要素：

传统 AI 辅助开发是开环系统 ：指令→执行→人工判断。当 Agent 吞吐量超过人的处理能力，系统必然失控。

Agentic 研发范式将其改造为闭环系统，核心是一个由三个要素构成的负反馈回路：

3) 目标态：让系统知道「对」是什么样的：

目标态决定了整个回路所能达到的精度上限 —— 它必须可见、版本化、存在于仓库里。OpenAI 说得直接：

存储在 Google Docs、聊天记录或人们头脑中的知识，都无法被系统访问。代码仓库本地的、已版本化的工件，才是它能看到的全部。

目标态是三层复合结构：

1）Spec—— 业务目标

没有 Spec，Agent 面对开放性问题，会生成「语法正确、逻辑合理、但和业务预期不符」的代码。有效的 Spec 要写清楚三件事：业务目标、验收标准、关键边界。Spec 存在仓库里，Agent 直接读取，不依赖人工搬运上下文。

2）架构 —— 结构约束

Spec 告诉 Agent 做什么，架构告诉它代码怎么组织。架构是持久生效的目标态，对整个代码库所有代码的结构性约束。我们在 smp 选择了四层单向依赖架构：

api → application → domain → repository

这个结构把约束编码进了文件系统本身。Agent 打开一个文件，通过路径就能判断「我该做什么、不该做什么」—— 代码结构是最好的 Prompt。OpenAI 的判断和我们一致：

「智能体在具有严格边界和可预测结构的环境中最为高效。这种架构通常要等到你拥有数百名工程师时才会考虑。对于编码智能体来说，这是一个早期的先决条件。」

3）工程上下文 —— 项目约束、规范

Spec 定义任务目标，架构定义结构边界，工程上下文填补两者之间的空白：技术栈用法、命名约定、错误处理方式、测试规范…… 这些共识长期存在于口头传递和历史 PR 里，对人来说够了，对 Agent 来说等于不存在。

我们用分层的 AGENTS.md 把这些知识版本化、固定到仓库：

三层共同作用，才构成一个完整的基准：Spec 告诉 Agent 这次做什么，架构告诉它怎么组织，工程上下文告诉它细节怎么处理。目标态定义了「对」，下一个问题是：系统怎么自己发现偏差、并在没有人介入的情况下持续趋近「对」。

4) 反馈回路：让感知与修正持续运转：

目标态定义了「对」，传感器和执行器决定了系统能不能在没有人介入的情况下持续趋近「对」。两者是一件事的两个面，缺少任何一个，回路就断开，系统重新需要人来盯着。

传感器：我们最核心的传感器是构建验证：

./gradlew build # 编译 + 测试，每次修改后必须通过

这一条命令覆盖三层检测：Kotlin 编译器的类型约束、单元测试的逻辑验证、集成测试的端到端验证。任何一层失败都是清晰的偏差信号，且足够具体，Agent 能直接读取并理解偏差在哪里。判断标准从「人觉得对不对」变成了「系统说对不对」—— 客观、可重复，不依赖任何人的注意力状态。

执行器：传感器产生偏差信号之后，Agent 读取构建失败的输出，理解哪条约束被违反了，修正代码，再次触发构建，循环直到偏差信号清零。

人的角色变了：从流水线上的必经节点，变成系统的设计者和边界问题的裁决者。

三、 构建一个能让 Agent 稳定交付的系统

1) 已经建立的三层目标态：

1. Spec 层：把需求带进仓库

一开始「先让 Agent 写，写完再看」，问题出现得很快：同一个概念每次命名不一样，updateStatus、changeStatus、modifyStatus 同时出现在不同模块；项目成员的「添加」接口有时叫 /add，有时叫 /create，有时叫 /invite。这些不是 Agent 的错，是我们没给它足够清晰的输入。

我们建立起两层 Spec 的工作方式：业务规则、验收标准写成 Markdown 提交到 prd/ 目录；技术契约以 Swagger 注解的形式直接在 Controller 和 DTO 里定义。同时整理了一份操作名白名单（create/update/remove/page/close/assign...），明确禁止自造同义词 —— 这条规则让跨模块命名一致性问题基本消失了。

2. 架构层：让约束变成 Agent 可感知的信号

换到四层单向架构之后，关键不是换了一套架构图，而是把约束从文档里移出来，编码进 Agent 每次开工就能感知到的地方。

・文件路径即语义：当 Agent 打开 smp-domain/.../project/Project.kt，路径本身已经告诉它：这是 domain 层实体，不应该有 @TableName 注解，不应该注入任何 Spring Bean。不需要记住规则，路径就是约束。

・编译器做第一道门控：Agent 如果在 domain 层引入了 Spring 注解，或让 application 层直接调用了 mapper，编译器立刻报错，错误指向具体的行 —— 一个不需要人触发、不依赖注意力的检测器。

・错误信息即修复指令：AGENTS.md 里的约束描述有意识地包含「违反时会看到什么报错、应该怎么修」，而不只是「禁止这么做」。Agent 读取构建失败信息时，能直接从错误上下文里找到修复方向。

3. 上下文层：让每一次人工介入都变成仓库里的永久资产

存在 Slack 里的讨论、口头传递的经验、历史 PR 评论 —— 对 Agent 来说不存在。只有进入仓库的知识，才是 Agent 能看到的知识。

我们建立的机制很简单：每一次人工介入，都是一次把经验写进仓库的机会。Spring Boot 4 移除了 @WebMvcTest 是典型例子：Agent 踩坑报错，我们定位修复，立刻把正确写法、背景说明和原因一起写进 AGENTS.md。这个坑此后再也没踩过 —— 不是因为团队成员都记住了，而是因为它已经进入了 Agent 每次启动时都能读到的上下文。

随着项目推进，这套飞轮积累下来：

・领域新增 5 步流程：建包→建层→分配错误码前缀→Flyway 脚本→对照参考实现，不会遗漏步骤。

・错误码命名空间：20xxx = 用户、21xxx = 角色、22xxx=SMP 认证，Agent 直接查表分配，不产生跨模块冲突。

・操作命名白名单：create/update/remove/page/close/assign/approve 等，跨模块命名一致性因此得到保证。

・14 条反模式清单（AP-01 ~ AP-14）：从真实 Code Review 提炼，每发现一类新问题就追加，清单持续生长。

飞轮的本质：人的经验通过仓库变成了系统的记忆。个人认知可以流失，写进仓库的约束不会。

2) 已经跑通的反馈回路：

关键决策很简单：./gradlew build必须通过，才算任务完成。

这把验证标准从「人觉得对不对」变成了「系统说对不对」。目前项目有 42 个测试文件：

回路运转后，Code Review 的重心也迁移了。以前大量精力花在「实现细节对不对」上 —— 逻辑放没放对层、命名是否符合规范。这些问题现在大部分由架构约束和构建验证在提交前就过滤掉了。Review 的重心迁移到了更有价值的地方：这段业务逻辑本身是否合理，是否和 Spec 的验收标准对得上。

3) 现阶段的实际结果：

后端 99% 的覆盖率，不是手工补出来的 —— 是因为测试是目标态的一部分，Agent 生成业务代码的同时必须生成对应测试，构建不通过就不算完成。

效率收益不只是「更快」，而是「更可预期」：./gradlew build全量验证，Agent 每次修改都能在几分钟内得到明确的通过或失败信号，不需要等人告诉它对不对。架构决策文档化带来的另一个收益：Agent 知道的，团队成员也知道，Onboarding 路径清晰：读 AGENTS.md→看参考实现→跑构建。

4) 还不稳定的地方：

・PRD 到 Spec 仍需人工翻译：原型工程和研发工程之间存在术语偏差 —— 原型里的命名、交互描述方式和研发侧的代码约定不一致，Agent 读了产品上下文还是无法直接消化。

・构建通过不等于业务正确：测试本身也可能是错的。Agent 生成测试时如果对 Spec 理解有偏差，会把错误行为断言为正确的，传感器反而成了误导信号。

・运行时信号还看不到：Agent 能看到编译错误和测试失败，但运行时日志、接口调用链、页面行为它还看不到，遇到运行时 bug 仍需人工定位后再交给 Agent 修复。

・前端 Agentic 化还刚起步：前端覆盖率 70%，约束体系和上下文积累远不如后端成熟，组件边界、状态管理和 UI 行为验证不能简单套用后端的分层思路。

5) 下一阶段：把稳定性继续做深：

・缩短产品上下文到 Agent 的距离：在产品工程和研发工程之间建立显式的映射文档，把关键业务术语和数据结构的对应关系记录进仓库；更彻底的方向是在原型设计阶段就引入研发侧的约定，从源头减少两套语境之间的摩擦。

・让 AI 审查 AI 写的测试：参考 OpenAI 建立体系化 Lint Skill 的思路，用专门的 Skill 扫描已有测试，判断断言逻辑是否和 Spec 的验收标准对得上，发现问题自动提 PR 修正。「AI 写测试→AI 审查测试→AI 修正测试」，让质量闭环在人介入之前先自己跑一轮。

・把运行时信号接入 Agent：将本地日志接入 Agent 上下文，为关键接口建立可重放的集成测试场景，让 Agent 能自主复现并验证修复，自主修复范围从「编译 / 测试层」扩展到「运行时层」。

・前端引入同等约束体系：建立组件职责约束（展示组件 vs 容器组件，禁止在展示组件里发请求），引入端到端测试作为 UI 行为的自动化验证门控，目标覆盖率 90%+。

・让文档系统自我维护：目标态会随时间腐烂 —— 规范文档不更新，约定随代码演进悄悄失效，OpenAI 称之为 doc-gardening。让 Agent 定期扫描文档和代码之间的不一致，自动提 PR 修复。用 Agent 维护让 Agent 能自主运行的基础设施，回路开始自我维持。

这五个方向围绕同一个回路的五个维度，每推进一步，人需要介入的地方就少一点，系统就多自动运转一点。

我们接下来要做的，不是继续把 Agent 当工具用得更熟，而是持续构建一个能让 Agent 稳定理解、稳定执行、稳定自验证、稳定演进的研发系统。

从工人守在机器旁边手动拧阀门，到离心调速器自己维持稳态 —— 工人没有消失，他去设计了下一台机器。我们现在做的，就是把这台调速器调好。