引言：从测试平台到开发范式
前文《契约驱动下的三层Agent协同实践》构建了一套可靠的自动化测试体系：通过接口契约、业务规则契约、术语契约和测试用例契约四大结构化资产，将 AI 的智能限制在受控的生成与辅助环节，保障了测试执行的确定性。当这套平台完成之后，一个更吸引人的想法浮现出来：能否让 AI 按照相同的契约，直接编写待测系统的代码？
设想这样的场景：您作为唯一的开发者，维护着一套严格定义的四大契约。当您需要开发一个新的微服务或功能模块时，您不再手写 Controller、Service、Entity，而是将契约作为输入，交由 AI 生成代码。这些代码天然包含正确的注解、扩展字段、错误码枚举，并且接口行为完全对齐业务规则。它们一旦部署，立刻就能被您的自动化测试平台无缝接管，无需额外的脚本编写或适配工作。
这是“一人即团队”模式的核心：借助契约约束的 AI，将软件生产的前端（需求与设计）、中端（编码）与后端（测试）打通，形成一个由个人控制的、高度自动化的流水线。
为实现这一构想，我们需要解决三个问题：
- Agent：负责代码生成的智能体应当如何定义？它的边界与职责是什么？
- Skill：如何将“编写符合契约的代码”这一复杂任务，拆解为可组合的技能单元？
- 驾驭工程：如何确保 AI 生成的代码真正遵守契约，而不是制造一批表面符合、实则隐含着错误实现的代码？
本文围绕这三个方面展开探讨，记录个人的思考与设计灵感。
一、Agent：代码生成智能体的定义与边界
在测试体系的三层架构中，智能化层 Agent 的职责是生成测试资产。现在，我们引入一个全新的 Agent 角色——编码 Agent，它的使命是根据契约生成业务系统的实现代码。
1.1 编码 Agent 的核心职责
编码 Agent 被定位为一名“极度遵守纪律的 AI 程序员”。它不进行创造性发挥，不引入契约未定义的逻辑，也不自行决定技术选型。它的职责仅限于：
- 基于接口契约生成控制器和请求/响应模型：读取 OpenAPI 文件，生成带有正确
operationId、Tag、扩展字段注解的 REST Controller。 - 基于业务规则契约生成服务层逻辑：将结构化的业务规则翻译为 Service 层的条件判断、异常抛出与返回值构造。
- 基于术语契约保障模型与错误码的语义一致性：确保字段命名、枚举值、错误码定义严格对齐术语表。
- 内置可测试性：所生成的代码的每个业务规则路径，都直接对应测试用例契约中的一条断言预期。
1.2 输入与输出定义
编码 Agent 的输入是完全结构化的四大契约，输出是可编译、可运行的代码文件。
| 输入 | 用途 |
|---|---|
| OpenAPI Contract | 生成 REST 接口层、请求/响应对象、全局异常处理器 |
| Business Rule Spec | 生成 Service 层的业务逻辑实现 |
| Terminology Spec | 指导字段命名、枚举定义、错误码常量，确保跨代码的统一语言 |
| Test Case Spec (approved) | 作为隐式的“需求补充”，帮助 Agent 理解边界条件，生成覆盖这些用例的代码路径 |
输出物的组织方式也遵循既定规范：项目模块划分、包命名、基类继承等均从契约中的扩展字段（如 x-module、x-layer）推导而来。
1.3 严格的边界约束
为防止 AI 的自由发散，编码 Agent 必须遵守以下硬性约束：
- 禁止自行创造业务规则：任何一条 if-else 分支都必须能追溯到一条 Business Rule ID，否则不应存在。
- 禁止修改契约定义的接口形状：路径、HTTP 方法、参数、响应体结构必须与 OpenAPI 完全一致，不允许增删字段。
- 错误码必须来源于契约声明的枚举：代码中抛出的所有业务异常，其 code 字段必须是 OpenAPI
x-error-codes中已声明的值。 - 所有扩展注解完整保留：生成的代码必须保留契约中的
x-rule-refs、x-term-refs等信息，以便下游的测试 Agent 进行链路分析。
这种设计将编码 Agent 的角色牢牢限制为一名“翻译官”，将结构化的契约“翻译”成等价的 Java/Python 代码，而非一名“设计师”。
二、Skill：将代码生成能力拆解为可编排的技能
“根据契约生成一个完整项目”是一项复合任务。为使其可控、可复用，需要将其分解为多个细粒度的 Skill（技能）。每个 Skill 是一个可独立调用、独立校验的生成单元。
2.1 技能单元分类
基于典型的服务端开发模式，我设想以下六个核心 Skill：
| Skill 名称 | 功能描述 | 主要输入 |
|---|---|---|
| project-init | 生成项目骨架、构建文件、基础配置类 | OpenAPI 中的模块分组 |
| model-gen | 生成请求/响应 DTO、Entity 定义 | OpenAPI 中的 Schema 定义 + Terminology Spec |
| error-gen | 生成错误码枚举类和全局异常处理器 | OpenAPI 中的 x-error-codes + Terminology Spec |
| controller-gen | 生成 REST Controller 代码 | OpenAPI Paths + x-module 等扩展字段 |
| service-gen | 生成 Service 层业务逻辑 | Business Rule Spec + Test Case Spec |
| test-harness-gen | 生成内嵌的契约校验辅助代码（如 Schema 校验拦截器） | OpenAPI Contract |
2.2 技能之间的契约化关联
这些 Skill 并非孤立运行，它们共享相同的契约上下文，并且存在生成顺序上的依赖。例如：
error-gen产出的错误码枚举会被service-gen引用。model-gen产出的 DTO 被controller-gen和service-gen同时使用。
为保证各 Skill 产出的一致性，所有 Skill 必须通过一个 共享上下文对象 交换信息。这个上下文本质上是四大契约的解析结果加上已生成代码的元数据索引。当一个 Skill 需要引用另一个 Skill 的产物时，它不进行“猜测”，而是通过查询上下文中的接口符号表来获取确切的类名、方法名和字段名。
2.3 技能编排示例：生成一个“合同创建”功能
以合同创建功能为例，技能的编排流程为：
- project-init：检测到当前工作区无项目结构，根据 OpenAPI 的模块标记生成 Spring Boot 项目骨架。
- model-gen：解析
ContractCreateRequest和ContractVO等 Schema，生成带有@Schema注解和术语绑定扩展的 Java DTO。 - error-gen：扫描所有接口的
x-error-codes，生成ContractErrorCode枚举，包含DUPLICATE_RESPONSIBLE_DEPT等常量，并生成基于该枚举的全局异常处理逻辑。 - controller-gen：生成
ContractController，@Operation中完整包含operationId、扩展字段，方法签名与契约一致。 - service-gen：读取
BR-CONTRACT-001等业务规则，生成ContractService.createContract()方法。例如，规则规定“负责人部门不能重复”，则生成判断逻辑，并在触发时抛出DUPLICATE_RESPONSIBLE_DEPT业务异常。 - test-harness-gen：为项目添加一个测试辅助模块，包含一个过滤器或拦截器，在测试环境下校验所有接口的响应体是否严格符合 OpenAPI Schema，进一步强化契约与实现的一致性。
每个 Skill 执行完成后，都会触发对应的校验动作（见下一节），确保该步骤的产出合规。
三、驾驭工程：确保AI生成的代码不偏离契约
让 AI 生成代码的最大风险在于，它会写出“看起来很正确、实际上违反契约”的实现。驾驭工程的目标就是建立一套工程化的防御体系，将这种风险降到最低，并为人工复审提供高效的支撑。
3.1 多层校验防线
我设想三道自动化的校验防线，分别作用于生成过程中、生成完成后和运行时。
（1）生成时：结构合规性校验
每个 Skill 在生成代码文件后，立即进行静态结构检查：
- 注解存在性检查：Controller 方法是否包含
@Operation，其operationId是否与契约一致；请求字段是否包含x-term-ref关联。 - 错误码枚举检查：
service-gen产出的 Service 中抛出的所有业务异常，其 code 值是否在error-gen生成的枚举中真实存在。 - 契约引用一致性：代码中任何
x-rule-refs字符串引用的规则 ID，必须在业务规则契约的index.json中存在。
这些检查类似于编译期 lint，由自研的静态分析器执行，不符合的代码直接标记为失败，Skill 需要重试或要求人工干预。
（2）生成后：编译与契约测试
所有 Skill 完成、代码库生成完毕后，执行完整的编译和契约驱动的自动化测试：
- 编译检查：确保项目可无错误编译、可启动，这排除了语法错误和基本的类型错误。
- 运行测试平台提供的契约一致性测试套件：这套用例并非用于测试业务逻辑本身，而是验证框架行为是否符合契约约定。例如：
- 请求一个接口，预期返回的错误码是否与契约声明的
x-error-codes一致。 - 响应体字段类型、必填性是否符合 Schema 定义。
- 分页接口的请求参数和响应结构是否遵循通用分页规范。
- 请求一个接口，预期返回的错误码是否与契约声明的
如果生成的代码通过了这一套元测试，基本可以确信它在技术层面对齐了契约。
（3）运行时：行为监控与契约回归
即使代码通过了上述检查，业务逻辑仍可能存在偏差。因此需要运行时监控：
- 业务规则覆盖度监控：在测试平台执行 approved 的测试用例时，统计每条业务规则 ID 被触发的次数。如果某条规则从未被覆盖，则说明代码实现可能缺失了该路径，或实现的触发条件与契约不符。
- 契约变更回归：当您手动修改契约后（例如新增一条业务规则），自动触发编码 Agent 重新生成受影响模块的代码，并运行全量测试，快速定位变更导致的新增失败。
3.2 人工复审的精准定位
即便自动化防线再严密，人工复审仍是最后一道不可或缺的关卡。然而，复审不应是逐行阅读代码，而应聚焦于契约遵守这个核心目标。我设想一个辅助审查视图：
- 契约-代码映射视图：审查界面将每条业务规则、每个接口错误码与生成的代码片段并排显示，并高亮标记出对应的条件判断和异常抛出。人工只需检查这些关键点，无需关注其他代码。
- 差异聚焦：当 AI 基于升级后的契约重新生成代码时，审查视图仅显示与上一版本的差异，并标注出差异是由哪条契约变更引起的。
通过这种方式，人工复审从耗时繁重的代码阅读，转变为目标明确的契约遵从性验证，效率与可靠性均可得到提升。
3.3 生成失败时的自我修正回路
当校验失败时，系统不立即放弃，而是尝试构建一个“反馈-修正”回路：
- 校验器将失败信息（如“缺少 DUPLICATE_RESPONSIBLE_DEPT 错误码的抛出”）转化为结构化的修正指令。
- 编码 Agent 被再次调用，但此次调用附带了失败上下文和具体的修正要求。
- Agent 重新生成受影响的文件（而非整个项目），并再次触发校验。
- 如果重试超过上限仍未通过，则标记为需要人工介入。
这种闭环机制借鉴了测试 Agent 设计中的人工兜底思路，既发挥了 AI 的自动修复潜力，又不至于陷入死循环。
结语：回顾与展望
本文所描绘的图景，本质上是将自动化测试平台所依赖的四大契约，向前推进一步，作为 AI 编写业务代码的最高指导原则。它不是要取代人类开发者，而是要在一个人的能力范围内，通过“契约约束 AI 生成，AI 产出受验代码”的模式，大幅压缩从需求到可测试系统的距离。
作为学生个人的灵感探索，这套模式目前还停留在设计层面。我清醒地认识到，真正的挑战在于契约编写的质量、AI 生成代码的鲁棒性以及众多细节的打磨。但这条以“契约”为主线，贯穿设计、编码、测试、治理的路径，给我带来了极大的思维乐趣。它让我看到，在 AI 能力不断涌现的今天，不是让 AI 替代一切，而是用精确的工程约束去驾驭 AI，让它成为个人创作力的倍增器，或许正是“一人即团队”开发模式的真正起点。
扫一扫
911
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
