开发篇 · 05 · AI 辅助开发
本章目标
把 AI（Claude）嵌入开发日常，不是替代思考，而是消化重复和模式化的工作。
一、AI 在开发侧的 9 个嵌入点
| # | 场景 | 痛点 | AI 价值 |
|---|---|---|---|
| 1 | 代码评审 | 低级错误漏检 | 批量扫描安全/风格/边界 |
| 2 | 接口文档生成 | 手写繁琐且易过期 | 根据代码生成 Markdown 文档草稿 |
| 3 | 单测生成 | 边界/异常场景漏测 | 根据接口契约生成用例框架 |
| 4 | 代码翻译 | 老代码迁移耗时 | 旧语言 → 新语言的初稿 |
| 5 | SQL 优化 | 慢查询分析 | 读 EXPLAIN 给优化建议 |
| 6 | 日志分析 | 海量日志找问题 | 识别异常模式 |
| 7 | 代码重构 | 手动重写工作量大 | 给出重构方案 + 保留原义 |
| 8 | 技术决策对比 | 方案选型调研耗时 | 多方案对比 + 权衡 |
| 9 | 错误排查 | 看不懂报错 | 解释错误 + 给排查步骤 |
二、核心 Prompt 模板
2.1 代码评审
你是一位资深代码评审员。评审以下 diff，重点关注：
1. **正确性**：逻辑、边界、异常
2. **安全**：注入、越权、敏感信息泄漏
3. **性能**：N+1、死循环、不必要的网络调用
4. **可读性**：命名、结构、复杂度
## 输出格式
每个问题输出：
- 文件:行号
- 严重度（must-fix / should-fix / nit）
- 问题描述（简洁）
- 修复建议（具体代码或思路）
对没问题的地方可以表扬。
## Diff
[粘贴 git diff]
2.2 从代码生成接口文档
根据以下代码生成 Markdown 格式的接口文档。
## 文档结构（参考 templates/testing/api-contracts/api-template.md）
- 基本信息（方法、路径、认证）
- 请求参数（Path / Query / Body）
- 响应结构（成功 + 业务错误码）
- 测试用例提示（边界、异常、安全）
- 变更历史（留空）
## 代码
[粘贴路由 + 处理函数 + schema]
## 要求
- 类型信息从代码里提取
- 错误码从异常处理代码里提取
- 对必填/可选做明确标注
- 标注"本文档由 AI 生成，需人工复核"
2.3 生成单元测试
你是一位资深测试开发工程师。根据以下接口契约，生成 [pytest / jest / junit] 单元测试。
## 要求
1. 覆盖正常流
2. 覆盖异常流（参数错误、权限错误、资源不存在）
3. 覆盖边界值（空、null、最大最小）
4. 覆盖并发场景（如涉及）
5. 用 AAA 模式（Arrange / Act / Assert）
6. 测试函数命名：should_<behavior>_when_<condition>
## 接口契约
[粘贴 api-template.md 的内容]
## 被测代码
[粘贴被测函数]
## 输出
可直接运行的测试代码 + 每个测试的简短说明
2.4 SQL 优化
你是一位资深 DBA。分析以下慢查询，给出优化方案。
## SQL
```sql
[粘贴 SQL]
EXPLAIN 输出
[粘贴 explain 结果]
表信息
- 表 A: 1 亿行，主键 id
- 表 B: 1000 万行
- 现有索引: [列出]
输出
- 慢的根本原因
- 3 个优化方案（按改动成本从小到大）
- 每个方案预期效果 + 风险
- 推荐方案及理由
### 2.5 代码重构
```markdown
你是一位资深软件架构师。帮我重构以下代码。
## 重构目标
- [ ] 降低复杂度
- [ ] 提升可读性
- [ ] 提取可复用逻辑
- [ ] 保持原有行为
## 约束
1. 不改变公共接口（签名、返回值）
2. 不引入新依赖
3. 保持原有测试全部通过
## 原代码
[粘贴]
## 输出
1. 重构后的代码
2. 改了什么、为什么改（按改动点说明）
3. 可能的风险点（需要人工 review）
2.6 错误排查
帮我排查这个错误。
## 错误信息
[粘贴完整 error stack]
## 复现步骤
1. ...
2. ...
## 相关代码
[粘贴触发错误的代码]
## 环境
- 语言/版本:
- 操作系统:
- 关键依赖版本:
## 我已经尝试过
1. ...
2. ...
## 输出
1. 最可能的原因（top 3，按概率排序）
2. 每个原因的验证方法
3. 对应的修复方案
2.7 技术决策对比
帮我在以下方案中做选择。
## 场景
[描述业务场景 + 关键约束]
## 候选方案
- 方案 A: [简述]
- 方案 B: [简述]
- 方案 C: [简述]
## 对比维度
1. 性能
2. 实现复杂度
3. 维护成本
4. 可扩展性
5. 学习曲线
6. 社区活跃度
7. 风险
## 输出
1. 对比矩阵（Markdown 表格，每维度打分 1-5）
2. 每个方案的决定性优缺点
3. 推荐方案及理由
4. 最终产出 ADR 格式（见设计规范）
2.8 代码翻译
把这段 [源语言] 代码翻译成 [目标语言]。
## 要求
1. 保持功能完全一致
2. 使用目标语言的**惯用法**（idioms）
3. 补充目标语言所需的类型声明
4. 异常处理按目标语言习惯
## 源代码
```[源语言]
[粘贴]
输出
- 翻译后的代码
- 关键差异说明（比如"Python 的 list comprehension 在 Go 里用 for loop"）
- 需要注意的语义差异（比如"Go 的 nil map 不能赋值，要先 make"）
### 2.9 日志分析
```markdown
分析以下一段日志，找出异常模式。
## 日志
[粘贴 100-500 行日志]
## 任务
1. 识别高频错误（并统计次数）
2. 识别**突发性**异常（时间上聚集）
3. 识别级联错误（一个错误引发的多个）
4. 给出排查优先级
## 输出
按优先级列出发现，每个发现包含：
- 错误模式
- 出现次数和时间分布
- 可能的根因
- 建议的下一步行动
三、使用 Claude 的最佳实践
3.1 小步快跑
❌ 一次让 AI 生成 500 行代码 → 审不过来，Bug 难找
✅ 分步骤：
- 让 AI 生成接口签名和数据模型
- 确认后生成主流程
- 再补异常处理
- 最后加单测
3.2 提供上下文
- 代码风格参考：附上团队的 lint 配置
- 项目约定：附上
CONTRIBUTING.md里的相关条款 - 业务上下文：简述所在模块的职责
3.3 让 AI 输出"为什么"
要求 AI 在代码里加注释解释为什么这样写，而不只是做什么。这样 review 时能更快判断。
3.4 对照测试
AI 生成的代码必须：
- 通过 lint
- 通过类型检查
- 通过所有单元测试
- 通过 CI 流水线
- 通过 code review
任何一项不过 = 不合入。
四、AI 使用的边界
4.1 不要让 AI 做的事
- ❌ 生成涉及敏感信息的代码（把内部系统 API Key 贴给 AI）
- ❌ 直接合入未审核的 AI 代码
- ❌ 用 AI 输出作为法律/合规的依据
- ❌ 让 AI 代替架构决策（它没有全局视图）
4.2 必须人工复核的事
- 业务逻辑正确性
- 架构级的设计决策
- 安全相关代码
- 与钱/权限/个人信息有关的代码
- 对接外部系统的协议实现
五、团队级 Prompt 库
5.1 目录结构
ep-code-ai/skills/development/prompts/
├── code-review.md
├── api-doc-from-code.md
├── unit-test-from-contract.md
├── sql-optimize.md
├── refactor.md
├── error-triage.md
├── tech-decision.md
├── translate-code.md
└── log-analysis.md
5.2 Prompt 版本化
每个 prompt 文件里带版本历史：
## unit-test-from-contract.md
**版本**: v1.4
### v1.4 (2026-04-15)
- 增加 AAA 模式要求
- 明确测试命名规范
### v1.3
- 增加并发场景覆盖要求
...
5.3 效果度量
跟踪 AI 参与的 MR 指标：
- 合入后的 Bug 率（对比纯人工）
- 评审轮次
- 评审时长
- 作者自评：AI 帮助程度（1-5）
持续迭代 Prompt。