写在前面

2026 年，AI 编码助手已经从"尝鲜"变成了日常——无论是 Cursor、GitHub Copilot 还是 JetBrains 系的 AI 插件，几乎每个开发者每天都在和 AI 结对编程。

但大多数人的体感是：AI 写代码"能用"，但离"好用"还有距离。 它能帮你补全一段函数、写一个 CRUD，但产出的代码经常需要大量人工修改——命名不规范、异常处理粗糙、分层混乱、缺少日志、事务管理遗漏。

问题出在哪？不是 AI 不行，而是你没有告诉它什么是"好代码"。

这篇文章从实战角度出发，系统讲解如何通过提示词优化、规则体系建设、上下文管理三板斧，让 AI 产出的代码质量从"能跑"提升到"可上线"。所有方法来自我们团队半年多的实践，经过日均数百次 AI 编码验证。

---

一、核心认知：AI 代码质量 = f(提示词, 规则, 上下文)

先建立一个认知模型：

AI 产出代码质量 = f(提示词质量, 规则约束, 上下文充分度)

其中：
- 提示词质量：你"说清楚了没有"——需求描述是否精确、无歧义
- 规则约束：你"立规矩了没有"——AI 是否知道你的编码规范
- 上下文充分度：你"给够背景了没有"——AI 是否理解项目的技术栈和设计

三者的影响权重大致是：

规则约束 (40%) > 上下文充分度 (35%) > 提示词质量 (25%)

为什么规则约束排第一？因为一个好的规则体系可以系统性地消灭低级问题——命名、分层、异常处理、日志格式这些问题，不应该每次在提示词里重复说，而是写成规则让 AI 持续遵守。

---

二、提示词优化：从"写个函数"到"精确表达意图"

2.1 差提示词 vs 好提示词

先看反面教材：

❌ 差提示词：
"写一个用户注册接口"

AI 产出：能跑，但没有参数校验、没有重复检测、没有事务、没有日志、
返回值格式不统一、异常直接抛出不包装...

好的提示词应该包含五要素：

✓ 好提示词的五要素：

1. 做什么（What）：实现用户注册功能
2. 输入输出（IO）：入参 RegisterRequest，返回 Result<UserVO>
3. 约束条件（Constraints）：手机号唯一性校验、密码加密存储
4. 异常场景（Edge Cases）：手机号已注册、验证码过期、并发注册
5. 技术上下文（Context）：Spring Boot + MyBatis-Plus，分层：Controller → Service → Mapper

示例：

实现用户注册 Service 方法。

入参：RegisterRequest（phone, password, verifyCode）
返回：Result<UserVO>

业务逻辑：
1. 校验验证码是否有效（调用 VerifyCodeService.validate）
2. 检查手机号是否已注册（查 user 表）
3. 密码 BCrypt 加密
4. 插入用户记录
5. 发送注册成功事件（Spring Event）

约束：
- 步骤 2-4 需要在同一事务内
- 手机号已注册抛出 BizException(USER_PHONE_DUPLICATE)
- 验证码校验失败抛出 BizException(VERIFY_CODE_INVALID)
- 方法入口和异常处记录 INFO/ERROR 日志

2.2 提示词四层模型

把提示词按抽象层级分成四层，越底层越稳定、越顶层越具体：

┌─────────────────────────────────────────────┐
│  Layer 4: 任务指令（每次不同）                  │
│  "实现 UserService.register 方法"             │
├─────────────────────────────────────────────┤
│  Layer 3: 业务上下文（按需提供）                │
│  "用户注册需要验证码、手机号唯一..."            │
├─────────────────────────────────────────────┤
│  Layer 2: 技术上下文（项目级别）                │
│  "Spring Boot 3 + MyBatis-Plus + RocketMQ"   │
├─────────────────────────────────────────────┤
│  Layer 1: 编码规则（全局级别，写一次永久生效）   │
│  "命名规范、异常处理、日志格式..."              │
└─────────────────────────────────────────────┘

• Layer 1-2 不应该每次手写——应该配置成 AI 编辑器的全局规则/项目规则
• Layer 3-4 是每次需要人工输入的——但越精确，AI 产出越好

2.3 提示词模板化

高频场景可以建立提示词模板，降低每次的思考成本：

## 新增接口模板

实现 [Controller/Service/Mapper] 的 [方法名] 方法。

### 接口签名
- 入参：[参数类型及含义]
- 返回：[返回类型]
- HTTP 方法/路径：[POST /api/v1/xxx]

### 业务逻辑（按步骤）
1. [步骤1]
2. [步骤2]
3. ...

### 边界情况
- [异常场景1] → 抛出 BizException([错误码])
- [异常场景2] → 返回 [特定响应]

### 依赖
- 调用 [XxxService.yyy 方法]
- 查询 [表名.字段]

## Bug 修复模板

修复 [类名.方法名] 的 [Bug 现象描述]。

### 当前行为
[描述现在的错误表现]

### 期望行为
[描述修复后应该怎样]

### 根因分析
[如果已知根因写上；如果不知道让 AI 先分析]

### 约束
- 不要改变方法签名
- 不要影响 [其他功能]
- 修复后补充对应的单元测试

2.4 提示词的反模式

反模式	问题	改进
“帮我优化一下这个类”	太模糊，AI 不知道优化什么	“把这个类的 N+1 查询改为批量查询”
一次让 AI 写 500 行	上下文越长 AI 越容易偏	拆分成 3-5 个小任务分步完成
不给示例	AI 不知道你的代码风格	给一个标杆文件让它参考
描述实现而非目标	“用 for 循环遍历…”	“过滤出满足条件的元素”（让 AI 选择最佳实现）
忽略异常场景	AI 默认走 happy path	显式列出需要处理的异常

---

三、规则引导：建立 AI 必须遵守的编码规范

3.1 为什么规则比提示词更重要

提示词是"临时的"——每次对话都要写。
规则是"持久的"——写一次，AI 持续遵守。

把重复出现的质量要求沉淀成规则，而不是每次在提示词里重复。

现代 AI 编辑器都支持"规则文件"的机制：

• Cursor：.cursorrules 文件
• Qoder / JetBrains AI：项目级 Rules 配置
• GitHub Copilot：.github/copilot-instructions.md
• Windsurf：.windsurfrules 文件

3.2 规则体系的三层设计

┌────────────────────────────────────────────────┐
│  全局规则（所有项目通用）                          │
│  - 编程语言级规范                                │
│  - 通用设计原则                                  │
│  - AI 交互偏好                                  │
├────────────────────────────────────────────────┤
│  项目规则（当前项目特有）                          │
│  - 技术栈声明                                    │
│  - 分层架构规范                                  │
│  - 业务术语词典                                  │
├────────────────────────────────────────────────┤
│  模块规则（特定模块/领域）                         │
│  - 该模块的设计决策                              │
│  - 性能约束                                     │
│  - 安全要求                                     │
└────────────────────────────────────────────────┘

3.3 五类硬性规则（必须配置）

根据我们团队的实践，以下五类规则能消灭 80% 的 AI 代码质量问题：

规则一：命名规范

## 命名规范

### 类命名
- Controller 类：{业务}Controller（如 FlowController）
- Service 接口：{业务}Service（如 FlowService）
- Service 实现：{业务}ServiceImpl（如 FlowServiceImpl）
- Mapper 接口：{业务}Mapper（如 FlowMapper）
- 实体类：{业务}Entity 或 {业务}DO（如 FlowEntity）
- VO/DTO：{业务}VO / {业务}DTO / {业务}Request / {业务}Response

### 方法命名
- 查询单条：get{Entity}ById / find{Entity}By{Condition}
- 查询列表：list{Entity}s / page{Entity}s
- 新增：create{Entity} / add{Entity}
- 修改：update{Entity}
- 删除：delete{Entity} / remove{Entity}
- 判断：is{Condition} / has{Property} / can{Action}
- 转换：convert{Source}To{Target} / build{Target}

### 变量命名
- 布尔变量：is/has/can 开头（如 isEnabled, hasPermission）
- 集合变量：复数名词（如 users, orderItems）
- Map 变量：{key}To{Value}Map（如 userIdToNameMap）
- 常量：全大写下划线分隔（如 MAX_RETRY_COUNT）

### 禁止
- ❌ 单字母变量（循环变量 i/j/k 除外）
- ❌ 拼音命名
- ❌ 无意义缩写（如 usr, mgr, proc）
- ❌ 匈牙利命名法（如 strName, intCount）

规则二：分层架构

## 分层规范

### 调用关系（严格单向）
Controller → Service → Mapper/Repository
                    → 外部 Client
                    → MQ Producer

### 各层职责
- Controller：参数校验（@Valid）、调用 Service、包装 Result
- Service：业务逻辑、事务管理、事件发布
- Mapper/Repository：数据访问，不含业务逻辑
- Client：外部系统调用封装

### 禁止
- ❌ Controller 直接调用 Mapper
- ❌ Service 之间循环依赖
- ❌ Mapper 中写业务判断逻辑
- ❌ 在 Controller 中写超过 10 行的业务逻辑
- ❌ Entity/DO 对象暴露到 Controller 层（必须转 VO）

规则三：异常处理

## 异常处理规范

### 业务异常
- 统一使用 BizException(ErrorCode code, String message)
- ErrorCode 为枚举，格式：{模块}_{异常描述}
- 示例：FLOW_INSTANCE_NOT_FOUND, USER_PHONE_DUPLICATE

### 异常分类
- 参数校验异常：Controller 层 @Valid 抛出，全局拦截器统一处理
- 业务异常：Service 层主动抛出 BizException，返回 400
- 系统异常：未预期的 RuntimeException，返回 500，记录 ERROR 日志

### 规则
- ✓ 异常消息必须包含关键业务标识（如 flowId, userId）
- ✓ 捕获异常必须记日志或重新抛出，禁止空 catch
- ✓ 外部调用（HTTP/RPC）必须 catch 并包装为业务异常
- ❌ 禁止用异常控制业务流程（如用 try-catch 代替 if-else）
- ❌ 禁止 catch(Exception e) 后吞掉不处理
- ❌ 禁止在循环内 try-catch（应该在循环外）

规则四：日志规范

## 日志规范

### 必须记录日志的场景
- 方法入口（INFO）：核心 Service 方法入口记录入参关键字段
- 外部调用前后（INFO）：HTTP/RPC/MQ 调用的请求和响应
- 异常（ERROR）：包含异常堆栈和业务上下文
- 状态变更（INFO）：关键业务状态机变更

### 日志格式
- 使用 Slf4j 占位符：log.info("处理流程实例, flowId={}, status={}", flowId, status)
- 禁止字符串拼接：❌ log.info("处理" + flowId + "状态" + status)

### 级别使用
- ERROR：系统异常、外部调用失败、数据不一致
- WARN：业务异常（可预期的错误）、性能退化
- INFO：核心业务流程、状态变更、外部调用
- DEBUG：调试信息、详细数据内容（生产不开启）

### 禁止
- ❌ 日志中打印密码、Token、身份证号等敏感信息
- ❌ 在循环内打印日志（大批量场景改为汇总后打印）
- ❌ 使用 System.out.println
- ❌ 使用 e.printStackTrace()

规则五：事务管理

## 事务管理规范

### 基本规则
- 事务注解只加在 Service 层方法上
- 默认传播行为：REQUIRED
- 默认隔离级别：READ_COMMITTED
- 只读查询加 @Transactional(readOnly = true)

### 事务边界
- ✓ 事务内只做数据库操作和必要的内存计算
- ❌ 事务内禁止调用外部 HTTP/RPC（网络超时导致长事务）
- ❌ 事务内禁止发 MQ 消息（事务回滚消息不回滚）
- ✓ 需要在事务提交后发消息：使用 @TransactionalEventListener(phase = AFTER_COMMIT)

### 大事务拆分
- 单个事务内操作行数不应超过 1000 行
- 批量操作分批提交（每批 200-500 条）
- 长流程用编程式事务 TransactionTemplate 代替 @Transactional

### 分布式事务
- 优先用最终一致性方案（MQ + 本地事务表）
- 避免使用 2PC/XA（性能差、可用性低）

3.4 反模式清单

除了"该怎么做"，还需要告诉 AI “不该怎么做”。反模式清单的效果往往比正面规则更好——因为 AI 有时候会"创造性地"犯错。

## 反模式清单（AI 禁止产出以下代码）

### 性能反模式
- ❌ N+1 查询（循环内查数据库）
- ❌ 全表扫描（无 WHERE 条件的 SELECT *）
- ❌ 大对象序列化后存 Redis（应该只存 ID/关键字段）
- ❌ 同步调用外部接口无超时设置

### 安全反模式
- ❌ SQL 拼接（必须用参数化查询）
- ❌ 日志打印完整 Token / 密码 / 身份证号
- ❌ 硬编码数据库密码 / AK/SK
- ❌ 用户输入未校验直接使用

### 设计反模式
- ❌ God Class（单个类超过 500 行）
- ❌ 万能 Map 传参（应该定义 DTO）
- ❌ 魔法数字（应该定义常量或枚举）
- ❌ 在 Controller 中写超过 3 行的数据转换逻辑

### 并发反模式
- ❌ 非线程安全的 SimpleDateFormat（用 DateTimeFormatter）
- ❌ 双重检查锁不加 volatile
- ❌ 直接 new Thread()（应该用线程池）
- ❌ HashMap 在并发场景使用（用 ConcurrentHashMap）

3.5 标杆文件机制

光有规则还不够——给 AI 一个"好代码长什么样"的参考，比规则更直观。

## 标杆文件对照表

当 AI 需要编写以下类型的代码时，先阅读对应的标杆文件作为参考：

| 任务类型 | 标杆文件 | 参考要点 |
|---------|---------|---------|
| 新增 Controller | FlowController.java | 参数校验、Result 包装、接口注释 |
| 新增 Service | FlowServiceImpl.java | 事务管理、异常处理、日志记录 |
| 新增 Mapper | FlowMapper.java + FlowMapper.xml | SQL 写法、动态条件 |
| 新增连接器 | DingTalkConnector.java | 模板方法、鉴权流程、错误处理 |
| 新增定时任务 | FlowInstanceCleanScheduler.java | 分页处理、幂等、监控埋点 |
| 新增 MQ 消费者 | FlowResumeMessageListener.java | 幂等校验、重试策略、死信处理 |
| 新增单元测试 | FlowServiceTest.java | Given-When-Then、Mock 用法 |

配置方式：在规则文件中引用标杆文件路径，AI 编辑器会自动在相关任务时加载参考。

---

四、上下文管理：让 AI 理解你的项目

4.1 为什么上下文这么重要

一个没有项目上下文的 AI，写出来的代码是"通用的"——它不知道你的项目用了什么框架、分了什么层、有什么公共工具类。结果就是：

• 自己造了一个工具方法，实际项目里已经有了
• 用了项目里不存在的依赖
• 返回值格式和项目其他接口不一致
• 不知道项目的 Result 包装类、分页对象叫什么

4.2 四种上下文喂养策略

策略一：技术栈声明

在规则文件开头声明项目技术栈：

## 项目技术栈

- 语言：Java 17
- 框架：Spring Boot 3.2 + Spring Cloud 2023
- ORM：MyBatis-Plus 3.5
- 数据库：MySQL 8.0
- 缓存：Redis 7 (Lettuce)
- 消息队列：RocketMQ 5.x
- 注册中心：Nacos 2.x
- 构建工具：Maven 3.9
- 日志框架：Logback + Slf4j
- 接口文档：Knife4j (OpenAPI 3)
- 单元测试：JUnit 5 + Mockito

策略二：业务术语词典（Glossary）

AI 不知道你的业务术语。给一份词典，避免命名混乱：

## 业务术语词典

| 术语 | 英文 | 含义 | 对应实体 |
|------|------|------|---------|
| 流程实例 | FlowInstance | 一次流程的完整执行记录 | flow_instance 表 |
| 连接器 | Connector | 对接第三方系统的适配器 | connector_config 表 |
| 节点 | Node | 流程中的单个执行步骤 | flow_node 表 |
| 执行快照 | Snapshot | 流程中断时保存的状态 | flow_snapshot 表 |
| 租户 | Tenant | 使用平台的企业客户 | tenant 表 |
| 空间 | Workspace | 租户下的逻辑隔离单元 | workspace 表 |

策略三：公共类清单

告诉 AI 项目里已有哪些工具类/基类，避免重复造轮子：

## 项目公共类（直接使用，禁止重复实现）

| 类名 | 作用 | 使用示例 |
|------|------|---------|
| Result<T> | 统一返回值包装 | return Result.success(data) |
| PageResult<T> | 分页返回值 | return PageResult.of(page) |
| BizException | 业务异常 | throw new BizException(ErrorCode.XXX) |
| ErrorCode | 错误码枚举 | ErrorCode.USER_NOT_FOUND |
| BaseEntity | 实体基类（含 id/createTime/updateTime） | extends BaseEntity |
| ConvertUtils | Bean 转换工具 | ConvertUtils.convert(source, TargetVO.class) |
| AssertUtils | 业务断言 | AssertUtils.notNull(user, ErrorCode.USER_NOT_FOUND) |
| RedisUtils | Redis 操作封装 | RedisUtils.set(key, value, 30, TimeUnit.MINUTES) |

策略四：架构决策记录（ADR）

对于关键的设计决策，写成 ADR 让 AI 理解"为什么这样设计"：

## ADR-001: 流程引擎使用自研执行器而非开源引擎

### 决策
自研流程执行器（ExecutionRunner），不使用 Camunda/Activiti。

### 原因
1. 开源引擎的 BPMN 模型对 iPaaS 场景过重
2. 我们需要深度控制执行快照和恢复机制
3. 连接器调用的异步编排是核心竞争力

### 影响
- 流程定义使用自研 JSON Schema，不是 BPMN XML
- 执行状态机需要自己维护
- 需要自己实现中断恢复机制（Snapshot + MQ 驱动）

### AI 编码时注意
- 不要引入 Camunda/Activiti 的任何依赖
- 流程相关代码参考 ExecutionRunner.java 的设计模式

4.3 上下文窗口管理

AI 的上下文窗口有限。不是给越多越好——信息过载会导致 AI "选择性忽视"关键信息。

原则：给精准的上下文，而不是给所有的上下文。

好的做法：
- 告诉 AI "参考 FlowServiceImpl.java 的第 50-80 行"
- 只贴与当前任务相关的接口定义
- 在提示词中明确指出"关注 XX 方法的异常处理方式"

坏的做法：
- 一次性把整个 Service 包的所有文件都丢给 AI
- 贴了 200 行代码但没说重点在哪
- 给了 10 个相关类但不说关联关系

---

五、工作流实践：AI 编码的正确打开方式

5.1 任务拆分原则

核心原则：一次让 AI 做一件事，做完验证再做下一件。

❌ 错误工作流：
"帮我实现用户模块的全部功能（注册、登录、修改密码、注销）"
→ AI 一次性写 800 行，质量失控

✓ 正确工作流：
1. "先实现 UserService.register 方法"       → 验证 → ✓
2. "实现 UserService.login 方法"            → 验证 → ✓
3. "实现 UserService.changePassword 方法"   → 验证 → ✓
4. "实现 UserService.deactivate 方法"       → 验证 → ✓

5.2 渐进式编码流程

Step 1: 接口定义（让 AI 先定义签名，不写实现）
     "定义 UserService 接口，包含 register/login/changePassword 三个方法签名"
     → 人工审核方法命名、参数设计、返回值
     
Step 2: 核心逻辑（一次只实现一个方法）
     "实现 UserServiceImpl.register，参考标杆文件 FlowServiceImpl.java"
     → 人工审核业务逻辑正确性
     
Step 3: 异常处理增强
     "给 register 方法补充完整的异常处理和边界情况"
     → 人工审核异常覆盖度
     
Step 4: 单元测试
     "为 register 方法编写单元测试，覆盖正常流程 + 手机号重复 + 验证码过期三个场景"
     → 运行测试验证

5.3 Review-Fix 循环

AI 写完代码后，不要直接用。用以下 checklist 做 review：

## AI 代码 Review Checklist

### 正确性
□ 业务逻辑是否和需求一致
□ 边界情况是否处理（空值、空集合、并发）
□ SQL 是否有注入风险
□ 数据权限是否考虑（租户隔离、操作者权限）

### 规范性
□ 命名是否符合项目规范
□ 分层是否正确（没有跨层调用）
□ 异常是否用 BizException 包装
□ 日志是否在关键位置记录
□ 事务注解是否正确使用

### 性能
□ 是否有 N+1 查询
□ 循环内是否有 IO 操作
□ 大集合是否分页/流式处理
□ 是否需要加缓存

### 可维护性
□ 方法长度是否超过 50 行（超过需拆分）
□ 参数是否超过 5 个（超过需封装为对象）
□ 是否有魔法数字
□ 注释是否充分（复杂逻辑必须有注释）

发现问题后，精确地告诉 AI 哪里有问题：

✓ 好的反馈："register 方法的第 3 步缺少并发控制——
两个请求同时用同一个手机号注册会出现重复数据。
请加分布式锁或者数据库唯一索引 + catch DuplicateKeyException。"

❌ 差的反馈："这个代码有 bug，改一下"

---

六、进阶技巧

6.1 用测试驱动 AI

先让 AI 写测试，再让它写实现。

Step 1: "根据以下需求，为 UserService.register 编写单元测试。
        测试场景：正常注册成功 / 手机号已注册 / 验证码过期 / 密码为空"

Step 2: "现在实现 UserService.register，使上述测试全部通过。"

这样做的好处：

• 测试先行，逻辑边界提前定义清楚
• AI 写实现时有明确的"验收标准"
• 减少后期补测试的工作

6.2 对话式调优

不要期望 AI 一次就写对。把它当成一个"初级开发者"，通过对话引导它改进：

你：实现 FlowService.batchExport 方法，支持导出流程实例。
AI：[生成初版代码]
你：两个问题——1. 大批量导出需要分页查询，不能一次性加载到内存；
    2. 导出过程中如果某条失败，应该跳过继续而不是整体失败。请修改。
AI：[改进版]
你：分页 OK 了。但你在循环内每条数据都打了一次 INFO 日志，
    10万条数据会产生 10万行日志。改为每处理完一页打一次汇总日志。
AI：[再次改进]

6.3 善用"解释"能力

当 AI 产出的代码你看不懂或不确定是否正确时，让它解释设计意图：

你：解释一下你为什么在这里用了 CompletableFuture 而不是同步调用？
    如果其中一个 Future 异常了，其他的会怎样？

AI：[解释设计决策和异常传播机制]

你：明白了，但在我们的场景中不需要并行——这三个步骤有顺序依赖。请改回同步。

6.4 代码重构请求

AI 很擅长做机械性的重构。用精确的重构指令：

## 好的重构指令

- "把这个 400 行的方法按职责拆成 3-4 个私有方法，每个方法做一件事"
- "把 if-else 链路改成策略模式 + Map 注册"
- "把这段重复出现 3 次的逻辑抽成公共方法放到 XxxUtils"
- "把 MySQL 分页查询改成游标查询，避免深分页性能问题"
- "把硬编码的配置值提取到 application.yml，用 @Value 注入"

---

七、团队级落地清单

如果你要在团队中推行"AI 写高质量代码"，按以下步骤落地：

第一周：基础建设

□ 为项目创建规则文件（.cursorrules / copilot-instructions.md）
□ 编写命名规范、分层规范、异常处理规范（本文第三章的五类规则）
□ 整理反模式清单（至少 15-20 条）
□ 选定 5-8 个标杆文件
□ 编写项目术语词典（Glossary）
□ 配置技术栈声明

第二周：模板与流程

□ 制作 3-5 个提示词模板（新增接口/Bug修复/重构/测试）
□ 定义 AI 代码 Review Checklist
□ 明确团队的 AI 编码工作流（拆分 → 生成 → Review → Fix）
□ 跑通一个完整案例：从需求到代码到测试全流程用 AI 完成

第三周：持续优化

□ 收集团队成员使用中的问题，迭代规则文件
□ 把新发现的反模式补充到清单
□ 优秀的 AI 交互案例沉淀为团队 wiki
□ 定期 review 规则文件（每月一次），删除过时规则、补充新规则

---

八、常见问题（FAQ）

Q：规则文件写多长合适？

A：建议控制在 200-500 行。太短覆盖不全，太长 AI 会"选择性遗忘"。核心规则精简明确，用表格和列表代替大段文字。

Q：AI 不遵守规则怎么办？

A：常见原因：① 规则太模糊（“写好代码” vs “方法不超过50行”）；② 规则和提示词冲突；③ 上下文窗口被撑满，规则被"挤出去"了。解法：规则写得更具体、更短，重要规则放在前面。

Q：不同 AI 工具的规则格式通用吗？

A：核心内容通用（命名规范、分层规范这些放哪个工具都适用），但加载方式不同。建议维护一份"核心规则文档"，各工具各自做格式适配。

Q：一个人开发需要搞这么复杂吗？

A：规则体系的核心价值是"一次投入、持续收益"。即使一个人开发，配好规则后 AI 产出的代码质量也会显著提升——尤其体现在命名一致性和异常处理完整性上。投入 2-3 小时配规则，后续每天节省 30 分钟的 review 修改时间。

Q：AI 写的代码还需要 Code Review 吗？

A：绝对需要。 AI 代码的 Review 重点和人写的不一样——人写的代码重点看"设计是否合理"，AI 写的代码重点看"是否符合项目规范"和"边界情况是否遗漏"。建议建立 AI 代码专属的 Review Checklist。

Q：如何度量 AI 编码的质量提升效果？

A：三个可量化指标：① 代码首次提交通过 Review 的比例（无修改意见直接合并的占比）；② Bug 密度（每千行代码的 Bug 数）；③ 返工率（生成的代码需要人工修改的行数占比）。配好规则后这三个指标通常改善 30-50%。

---

九、写在最后

用 AI 写出高质量代码，本质上是把你脑子里的"编码常识"外化成机器可读的规则。

很多经验丰富的开发者觉得 AI 产出的代码"不靠谱"——但仔细想想，你之所以能写出高质量代码，是因为你经过多年积累形成了一套内化的规范。AI 没有这个积累，它需要你显式地告诉它。

三个核心要点：

1. 规则先行——把命名/分层/异常/日志/事务五类规范写成规则文件，一次配置持续生效
2. 上下文充分——技术栈声明 + 术语词典 + 公共类清单 + 标杆文件，让 AI 理解你的项目
3. 任务拆小——一次只做一件事，做完验证再做下一件，避免 AI 在大任务中失控

做到这三点，AI 产出的代码质量会从"能跑但需要大改"提升到"Review 几行就能合并"。这不是夸张——我们团队在配好规则体系后，AI 代码的首次 Review 通过率从 30% 提升到了 70%。

---

标签：#AI编码 #提示词工程 #代码质量 #编码规范 #CursorRules #GitHubCopilot #AI编程 #代码审查 #软件工程 #开发效率 #规则引导 #上下文管理 #Java #最佳实践