AI（Artificial Intelligence，人工智能）辅助编码已经从“帮开发者补几行代码”，逐渐演进到“参与需求理解、方案拆解、代码生成、测试和交付”的研发协作方式。

但在企业级系统里，单纯依赖 AI Code（人工智能辅助编码）并不容易。业务逻辑复杂、系统模块多、技术规范严格，AI 如果只拿到一句需求描述，很容易生成能跑但不符合架构的代码，甚至把逻辑写错位置、漏掉安全校验、破坏已有设计。

更适合复杂系统的做法，不是让 AI 自由发挥，而是把研发过程改造成 AI 能理解、能执行、能被检查的流程：

flowchart LR
    A[需求确认] --> B[面向 AI 的技术方案]
    B --> C[标准化 Prompt]
    C --> D[Agent 生成代码]
    D --> E[AI 自我总结]
    E --> F[人工 Review]
    F --> G[测试与上线]

这套流程的关键，不在于“让 AI 多写代码”，而在于把上下文、规范、位置、任务和验收标准都提前说清楚，让 AI 知道：

代码补全和自由生成的天花板

很多团队最早接触 AI Code，是从 Tab 模式的代码补全开始的。它适合补全局部代码，比如补一个 if 判断、生成一个简单函数、补齐测试数据。问题是，补全工具主要依赖当前位置附近的上下文，对完整业务需求、跨文件调用、架构规范理解有限，所以效率提升有明显上限。

另一类方式是 Agent（智能体）模式。开发者把需求交给 AI，AI 自己读代码、改文件、生成实现。这种方式看起来更接近“自动开发”，但在复杂系统中会遇到几个典型问题：

对于广告审核、风控、交易、权限、计费这类系统，需求往往不是“新建一个页面”这么简单，而是在已有系统里增加一个分支、补一个策略、改一段流程、兼容一批历史数据。AI 如果没有足够上下文，很难直接生成可采纳的代码。

两类典型 AI Code 范式

行业里有两种比较有代表性的 AI Code 思路：规范驱动和 AI Native。

这两类范式各有价值，但在企业内部已有系统里，通常还需要补一层工程化适配：把已有研发流程、技术规范、代码结构和工具链接入 AI，让 AI 不只是“会写代码”，还要“按团队方式写代码”。

核心范式：技术方案 → Prompt → 代码生成 → AI 总结

适合复杂业务系统的 AI Code 流程，可以拆成四个核心环节：

flowchart TD
    A[技术规范与代码索引] --> B[面向 AI 的技术方案]
    C[业务需求与验收标准] --> B
    B --> D[标准化 Prompt]
    D --> E[Agent + MCP 工具]
    E --> F[生成代码]
    F --> G[AI 自我总结]
    G --> H[人工 Review 与测试]

其中，MCP（Model Context Protocol，模型上下文协议）用于把外部工具、知识库、文档系统、项目管理系统等能力接入 AI Agent，让模型能够获取更多上下文，而不是只依赖当前编辑器里的几段代码。

这套流程可以理解成一个约束明确的人机协作模式：

1. 人负责判断需求、设计方案、补齐关键上下文。
2. AI 负责根据明确指令生成代码、修改文件、归纳变更。
3. 人再根据 AI 总结和代码 Diff 做 Review，检查是否符合预期。

AI 不再是独立完成任务的“黑盒开发者”，而是被放进一个有规范、有步骤、有检查点的研发流水线里。

技术基座：工具、模型、MCP 和度量

AI Code 要在团队里稳定使用，不能只选一个编辑器插件。比较完整的技术基座通常包含四部分：

flowchart LR
    A[IDE 集成开发环境] --> B[AI 编程插件]
    B --> C[大模型]
    B --> D[MCP 工具]
    B --> E[代码仓库]
    F[效能度量平台] --> B

IDE 和 AI 编程插件

IDE（Integrated Development Environment，集成开发环境）是开发者日常写代码的入口。AI 编程插件需要和 IDE 深度结合，至少要支持：

• 读取当前仓库代码；
• 理解文件结构和依赖关系；
• 按任务修改多个文件；
• 展示代码 Diff；
• 支持人工确认或回滚；
• 接入团队内部模型和工具。

在企业内部环境里，安全性和模型可控性很重要。代码、需求、接口文档、数据结构都可能包含敏感信息，如果工具无法满足内部安全要求，就很难在核心系统中推广。

大模型选择

代码生成效果与底层模型能力关系很大。复杂业务系统不仅考验模型写代码的能力，还考验它理解长上下文、遵循指令、保持风格一致、处理跨文件修改的能力。

实践中可以把模型能力拆成几个观察点：

模型不一定只选一个。补全、解释代码、生成单测、跨文件重构，对模型能力要求不同，可以根据场景切换。

MCP 工具集成

Agent 只看本地代码还不够。很多关键信息放在需求平台、知识库、接口文档、数据库结构、技术规范文档里。MCP 的价值，就是把这些上下文以工具形式开放给 AI。

典型集成方式如下：

flowchart TD
    A[Agent] --> B[MCP: 知识库]
    A --> C[MCP: 需求系统]
    A --> D[MCP: 接口文档]
    A --> E[MCP: 数据库结构]
    A --> F[MCP: 代码索引]
    B --> G[业务规则与技术规范]
    C --> H[需求描述与验收标准]
    D --> I[API 契约]
    E --> J[表结构与字段含义]
    F --> K[类、方法、模块位置]

MCP 不应该无限开放权限。更合理的方式是按开发任务提供只读或受控能力，例如查询知识库、读取接口定义、检索代码索引，而不是让 AI 随意访问和修改所有系统。

效能度量

AI Code 推广不能只靠体感判断，需要有可量化指标。常见指标包括：

这些指标要结合使用。比如代码行采纳率高，不一定代表质量高，还要看缺陷率、Review 成本、返工次数和上线稳定性。

技术规范：让 AI 知道不能怎么写

AI 生成代码最大的问题之一，是它会倾向于“完成任务”，但未必理解团队长期积累的技术约束。因此，第一步要把隐性经验变成显式规则。

规范可以放在仓库内，例如：

.project-rules/
  security.md
  architecture.md
  coding-style.md
  api-design.md
  database.md
  logging.md

一个规则文件可以这样写：

# API 参数校验规范

## 必须遵守

1. Controller 层必须对外部入参做基础校验。
2. 用户身份、租户、权限相关字段不能直接信任前端传值。
3. 批量接口必须限制单次请求数量。
4. 错误信息不能暴露数据库字段名、内部类名、SQL 语句。

## 推荐写法

- 使用统一的参数校验工具。
- 业务异常统一抛出 BizException。
- 日志中保留 requestId，方便排查链路问题。

## 禁止写法

- 禁止直接拼接 SQL。
- 禁止吞掉异常后返回成功。
- 禁止在 Controller 中写复杂业务逻辑。

技术规范不需要一开始就追求大而全。更有效的方式是从 AI 最容易犯错的地方开始沉淀，例如安全校验、目录结构、异常处理、日志规范、数据库访问规则。

代码索引：让 AI 知道在哪里改

复杂系统的代码通常有清晰分层，例如 Controller、Service、Repository、Entity、DTO（Data Transfer Object，数据传输对象）。人类开发者熟悉这些约定，但 AI 不一定知道当前项目的具体组织方式。

因此，需要给 AI 一份“代码地图”。

# 代码结构说明

## 模块

- audit-web：对外 HTTP API
- audit-service：审核业务逻辑
- audit-repository：数据库访问
- audit-common：通用工具、枚举、异常

## 分层约定

- Controller：只处理参数接收、基础校验、调用 Service，不写业务流程
- Service：承载核心业务逻辑，负责流程编排和规则判断
- Repository：只处理数据访问，不写业务决策
- Entity：数据库实体，与表结构对应
- DTO：接口输入输出对象

有了代码索引，AI 在实现需求时更容易把代码放到正确位置，而不是随手新建一个类或把业务逻辑塞进 Controller。

技术方案模板：把人能懂的方案改成 AI 能执行的方案

传统技术方案主要面向人类阅读，很多内容是概括性的，例如“增加审核策略配置能力”“复用已有查询逻辑”“注意权限控制”。人能根据经验补齐细节，但 AI 需要更明确的输入。

面向 AI 的技术方案要尽量结构化，至少包含：

• 需求目标；
• 代码修改范围；
• 新增或修改的文件；
• 分层设计；
• 接口契约；
• 核心业务逻辑；
• 数据访问方式；
• 边界条件；
• 验收标准。

可以用 YAML 格式表达：

需求名称: 新增审核策略状态查询接口

目标:
  - 给前端提供审核策略状态查询能力
  - 支持按策略ID批量查询
  - 返回策略是否启用、更新时间、最近操作人

修改范围:
  仓库: audit-platform
  模块:
    - audit-web
    - audit-service
    - audit-repository

分层设计:
  controller:
    文件: audit-web/src/main/java/com/example/audit/controller/StrategyController.java
    操作: 新增接口
  service:
    文件: audit-service/src/main/java/com/example/audit/service/StrategyService.java
    操作: 新增批量查询方法
  repository:
    文件: audit-repository/src/main/java/com/example/audit/repository/StrategyRepository.java
    操作: 新增按策略ID列表查询方法
  dto:
    新增:
      - StrategyStatusQueryRequest
      - StrategyStatusResponse

验收标准:
  - 策略ID为空时返回参数错误
  - 单次最多查询100个策略
  - 无权限访问时返回权限错误
  - 数据不存在时返回空结果，不抛系统异常

这种写法比一段自然语言更适合 AI 执行，因为它明确告诉模型“改哪里、怎么改、什么算完成”。

代码层级结构模板

代码层级结构设计的目标，是让 AI 明确文件应该创建在哪里、类承担什么职责、不同层之间如何调用。

## 代码层级结构设计

### 新增文件

| 层级 | 文件 | 职责 |
|---|---|---|
| DTO | StrategyStatusQueryRequest.java | 接收前端查询参数 |
| DTO | StrategyStatusResponse.java | 返回策略状态 |
| Controller | StrategyController.java | 暴露 HTTP 查询接口 |
| Service | StrategyService.java | 编排业务逻辑 |
| Repository | StrategyRepository.java | 查询数据库 |

### 调用关系

Controller -> Service -> Repository -> Database

调用关系可以用图表示：

flowchart LR
    A[StrategyController] --> B[StrategyService]
    B --> C[StrategyRepository]
    C --> D[(strategy_table)]

这一层模板主要解决“在哪里”的问题。只要位置说清楚，AI 生成的代码就更容易融入现有项目结构。

Controller 层模板：定义 API 契约

Controller 层面向前端或外部调用方，最重要的是 API（Application Programming Interface，应用程序编程接口）契约。契约不清楚，AI 就可能生成不符合前端预期的路径、参数或响应结构。

## Controller 设计

接口名称: 查询审核策略状态

请求方法: POST
请求路径: /api/audit/strategy/status/query

请求参数:
| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| strategyIds | List<Long> | 是 | 策略ID列表，最多100个 |

响应字段:
| 字段 | 类型 | 说明 |
|---|---|---|
| strategyId | Long | 策略ID |
| enabled | Boolean | 是否启用 |
| updateTime | Long | 最近更新时间 |
| operator | String | 最近操作人 |

校验规则:
- strategyIds 不能为空
- strategyIds 长度不能超过100
- strategyIds 中不能包含 null

对应的 Prompt 可以要求 AI 不要在 Controller 写业务逻辑：

Controller 层只允许完成参数接收、基础校验、权限校验和调用 Service。
禁止在 Controller 中直接访问数据库。
禁止在 Controller 中编写策略状态判断逻辑。

Service 层模板：描述核心业务逻辑

Service 层是 AI 最容易写偏的地方，因为业务规则通常有很多隐含条件。模板要把目标类、目标方法、处理流程、边界条件说清楚。

## Service 设计

目标类:
- StrategyService

新增方法:
- List<StrategyStatusResponse> queryStrategyStatus(List<Long> strategyIds)

处理流程:
1. 校验 strategyIds 是否为空。
2. 对 strategyIds 去重。
3. 调用 PermissionService 校验当前用户是否有查询权限。
4. 调用 StrategyRepository 查询策略记录。
5. 将数据库实体转换为 StrategyStatusResponse。
6. 对不存在的策略ID不抛异常，只是不返回对应记录。

边界条件:
- 输入为空: 抛出参数异常
- 超过100个ID: 抛出参数异常
- 无权限: 抛出权限异常
- 部分ID不存在: 返回已存在部分

Service 层模板要避免只写“实现查询逻辑”这种泛化描述。AI 需要明确的流程，不然很容易补出团队不想要的判断逻辑。

Repository 层模板：约束数据访问

Repository 层需要提供表名、字段名、查询条件、索引使用方式。否则 AI 可能猜字段，甚至生成不存在的 SQL。

## Repository 设计

目标接口:
- StrategyRepository

数据库表:
- audit_strategy

字段:
| 字段名 | 类型 | 说明 |
|---|---|---|
| id | bigint | 策略ID |
| enabled | tinyint | 是否启用 |
| update_time | datetime | 更新时间 |
| operator | varchar | 最近操作人 |

新增方法:
- List<StrategyEntity> queryByIds(List<Long> strategyIds)

查询要求:
- 使用 id in (...) 查询
- strategyIds 已在 Service 层限制最大100个
- 不查询已逻辑删除的数据

如果项目中使用 ORM（Object Relational Mapping，对象关系映射），还要说明使用 MyBatis、JPA 还是其他框架，以及 XML、注解、Mapper 接口的写法要求。

Prompt 模板：把技术方案变成可执行指令

技术方案解决“信息完整”的问题，Prompt 解决“如何执行”的问题。一个稳定的 Prompt 不应该只写“根据方案生成代码”，而要包含角色、上下文、任务、约束、步骤、输出格式和验收标准。

你是一个熟悉当前 Java 后端项目的研发助手，需要根据技术方案生成代码。

## 输入材料

1. 技术规范:
   - 遵守项目安全规范、异常规范、日志规范、分层规范。
2. 代码索引:
   - 按给定目录和类名修改，不允许随意新增无关文件。
3. 技术方案:
   - 按方案中的 Controller、Service、Repository、DTO 分层实现。

## 执行要求

1. 先阅读相关文件，确认已有代码风格。
2. 只修改技术方案列出的文件。
3. 如果发现必须修改额外文件，先说明原因，不要直接修改。
4. 保持已有命名风格和异常处理方式。
5. 不要删除已有逻辑。
6. 不要引入新的第三方依赖。

## 任务清单

- 新增请求 DTO。
- 新增响应 DTO。
- 修改 Controller，增加查询接口。
- 修改 Service，增加业务方法。
- 修改 Repository，增加数据查询方法。
- 补充必要单元测试。

## 验收标准

- 项目可以编译通过。
- 参数校验符合技术方案。
- 权限校验不能缺失。
- 不存在的策略ID不抛系统异常。
- AI 总结中列出所有修改文件和风险点。

Prompt 标准化的价值，是降低每个开发者临时写提示词的成本，也减少不同人使用 AI 时结果差异过大的问题。

Agent 执行流程

Agent 模式适合执行跨文件任务，但必须让它按步骤工作。一个较稳的流程如下：

sequenceDiagram
    participant Dev as 开发者
    participant Agent as AI Agent
    participant MCP as MCP 工具
    participant Repo as 代码仓库
    participant Review as 人工 Review

    Dev->>Agent: 提供技术方案和 Prompt
    Agent->>MCP: 查询规范、知识库、代码索引
    MCP-->>Agent: 返回上下文
    Agent->>Repo: 读取相关文件
    Repo-->>Agent: 返回代码
    Agent->>Repo: 生成并修改代码
    Agent->>Agent: 自检任务清单和验收标准
    Agent-->>Dev: 输出 AI 总结
    Dev->>Review: 检查 Diff、运行测试、确认合并

关键点是：Agent 每次执行任务都要被限制在明确范围内。需求越复杂，越要拆小任务，不要一次让 AI 修改过多模块。

AI 自我总结：让 Review 更快、更可追踪

AI 生成代码后，必须要求它输出自我总结。这个步骤看起来简单，但对代码审查和后续维护很重要。

一个可用的总结模板如下：

# AI 代码变更总结

## 需求目标

实现审核策略状态批量查询接口。

## 修改文件

| 文件 | 修改类型 | 说明 |
|---|---|---|
| StrategyController.java | 修改 | 新增策略状态查询接口 |
| StrategyService.java | 修改 | 新增 queryStrategyStatus 方法 |
| StrategyRepository.java | 修改 | 新增按ID列表查询方法 |
| StrategyStatusQueryRequest.java | 新增 | 查询请求 DTO |
| StrategyStatusResponse.java | 新增 | 查询响应 DTO |

## 核心逻辑

1. Controller 接收 strategyIds 并做基础参数校验。
2. Service 去重后校验权限。
3. Repository 查询未删除的策略记录。
4. Service 转换响应对象并返回。

## 已处理边界

- strategyIds 为空
- strategyIds 超过100个
- 无权限访问
- 部分策略ID不存在

## 潜在风险

- 未补充接口自动化测试。
- 如果后续策略状态字段含义变化，需要同步调整响应转换逻辑。

## 建议人工检查

- 权限校验是否符合当前业务要求。
- Repository 查询是否命中现有索引。
- 前端是否依赖固定返回顺序。

人工 Review 时不应该只看 AI 生成了哪些代码，还要检查 AI 声称完成的事情是否真的完成。AI 总结是索引，不是结论。

适合和不适合的场景

这种 AI Code 范式适合已有系统的常规迭代，但并不是所有任务都适合交给 AI。

一个实用原则是：AI 更适合执行明确任务，不适合独立做高风险决策。越是复杂、关键、不可逆的变更，越要让人掌控方案和验收。

常见问题和处理方式

1. AI 生成代码发散

表现为新增不必要的类、引入新依赖、改动无关文件。

处理方式：

• 在 Prompt 中限制修改范围；
• 要求 AI 修改前列出计划；
• 分阶段执行，不要一次提交大任务；
• 明确“不允许新增依赖”“不允许修改无关文件”。

2. AI 漏掉边界条件

表现为只实现主流程，缺少异常、权限、空数据、数量限制等处理。

处理方式：

• 在技术方案中单独写边界条件；
• 在验收标准中列出必须覆盖的场景；
• 要求 AI 自检每个验收项；
• 用单元测试反向约束生成结果。

3. AI 不理解业务黑话

表现为概念混淆，例如把“审核策略”和“审核任务”当成同一类对象。

处理方式：

• 建立业务术语表；
• 在技术方案中补充概念定义；
• 通过 MCP 接入知识库；
• 对关键业务概念给出正例和反例。

示例：

## 业务术语

- 审核策略: 用于决定内容是否进入某类审核流程的规则配置。
- 审核任务: 策略命中后生成的待处理任务。
- 策略状态: 策略是否启用，不等于审核任务状态。

4. AI 不知道项目历史约束

表现为生成的新代码看似合理，但破坏了已有兼容逻辑。

处理方式：

• 把历史约束写入项目规则；
• 对老接口、老字段、兼容逻辑加注释；
• 在 Prompt 中要求 AI 不删除、不替换已有兼容逻辑；
• 对关键链路保留人工设计和人工 Review。

推广效果应该如何判断

AI Code 的价值不能只看“生成了多少代码”。更合理的判断方式，是同时看覆盖、采纳和节约成本。

一个可参考的指标组合：

在成熟使用后，可以达到类似这样的状态：

这些数字的意义不在于每个团队都要完全一致，而是说明 AI Code 需要用工程指标持续观察，不能停留在“感觉好用”或“偶尔惊艳”。

从编码提效走向全链路协同

当前 AI Code 最容易落地的环节是编码，因为代码仓库、技术方案和测试结果都比较明确。更进一步，可以把 AI 能力向研发链路两端扩展。

flowchart LR
    A[需求] --> B[需求澄清]
    B --> C[技术方案生成]
    C --> D[任务拆解]
    D --> E[代码生成]
    E --> F[单元测试]
    F --> G[联调测试]
    G --> H[部署变更]
    H --> I[上线总结]

其中最值得探索的是“需求到技术方案”的自动化。也就是让 AI 根据需求文档、业务规则、历史代码和接口规范，先生成结构化技术方案，再由开发者确认和修订。这样可以把 AI 从单纯写代码，提升到辅助设计和任务拆解。

但这个阶段风险也更高，因为技术方案一旦错了，后续代码生成会沿着错误方向执行。因此，人仍然要负责关键判断：

• 需求是否理解正确；
• 技术边界是否合理；
• 是否影响核心链路；
• 数据兼容方案是否完整；
• 是否存在安全和权限风险。

一套可落地的最小实践

如果团队想从零开始落地，不需要一次性建设完整平台，可以从一个最小闭环开始：

flowchart TD
    A[选择一个低风险需求] --> B[整理项目规则]
    B --> C[编写技术方案模板]
    C --> D[编写 Prompt 模板]
    D --> E[让 Agent 生成代码]
    E --> F[要求 AI 输出总结]
    F --> G[人工 Review 和测试]
    G --> H[沉淀问题到规则库]

最小版本只需要四份材料：

1. 一份项目规则；
2. 一份代码结构说明；
3. 一份技术方案模板；
4. 一份 Prompt 模板。

随着使用次数增加，再把高频问题补进规则库，把常见需求固化成模板，把知识库和代码索引接入 MCP 工具。

关键结论

企业级 AI Code 的核心不是“让 AI 自己想办法”，而是把研发流程改造成模型可理解、可执行、可验证的结构化流程。

比较稳定的链路是：

技术规范 + 代码索引 + 技术方案模板
        ↓
标准化 Prompt
        ↓
Agent + MCP 工具生成代码
        ↓
AI 自我总结
        ↓
人工 Review、测试、上线

这套范式解决的是复杂系统里 AI 生成代码的可控性问题。AI 负责提高执行效率，人负责需求判断、方案约束和质量把关。只有把规范、上下文、任务和验收标准都工程化，AI Code 才能从“偶尔好用的编码助手”，变成团队研发流程中稳定可复用的一环。