AI 辅助开发实践。团队如何与 AI 一起编写、审查和交付代码。
目的
用 AI 写代码有一个核心矛盾：生成快，但你不知道该信任多少。信任太多，问题进代码库；信任太少，AI 帮不上忙。
这一章给出判断框架：什么时候用 AI、上下文怎么准备、审查怎么分工、出了问题怎么处理。读完后，面对一个开发任务你知道该做哪些决定，而不是靠感觉。
开发循环
需求 → 结构化 → 提示 → 生成 → 审查 → 精炼 → 提交
| 步骤 | 人类做什么 | AI 做什么 |
|---|---|---|
| 结构化 | 定义目标、约束、验收标准 | — |
| 提示 | 从 04-prompt/ 选择对应提示，或自行编写；提供上下文 | — |
| 生成 | — | 生成代码 / 测试 / 文档初稿 |
| 审查 | 验证正确性、完整性、风险 | 辅助检查已有代码 |
| 精炼 | 修改不符合意图的部分 | 根据反馈迭代 |
| 提交 | 填写 PR 检查清单，合并 | 生成 PR 描述初稿 |
规则：不理解的代码不提交。AI 生成的代码与人工编写的代码适用同一质量标准。
什么时候直接人工写
以下情况，从一开始就人工编写，不走 AI 生成流程：
- 领域知识密集：逻辑高度依赖背景知识，无法用文字完整传递给 AI，生成结果需要大量修改
- 安全相关：认证、权限、加密——AI 生成的代码审查成本高于人工编写成本
- 需求未定型：接口还没想清楚，边写边发现需求——此时 AI 产出是噪音，不是帮助
- 代码量极小：逻辑不超过 20 行，写提示比直接写代码费时间
这四种情况以外，默认走 AI 辅助流程。
上下文管理
给 AI 提供上下文时：
- 包含：相关接口定义、已有的实现模式、约束和验收标准
- 排除：无关文件、历史废弃代码、超出当前任务范围的内容
- 明确说明：不能改动的部分、需要兼容的旧接口、团队代码约定
上下文质量直接决定输出质量。不要将整个代码库丢给 AI；要主动筛选出最相关的 2-3 个文件。
标准上下文包（发给 AI 前准备）：
[接口定义] 相关类型、函数签名、枚举
[现有模式] 同类功能在代码库中的实现示例（1-2 个）
[约束声明] 不能修改的接口、必须兼容的版本、禁用的库
[验收标准] 明确的完成判定条件
[排除范围] 本次不做的部分
代码审查：AI 与人工的分工
AI 和人工审查的发现范围不同，不是互相替代，是互补的两轮过滤。
AI 擅长发现：
– 常见 bug 模式：null 检查遗漏、边界条件、类型不匹配
– 接口一致性：函数签名、返回类型是否与调用方匹配
– 安全风险模式：明显的注入点、硬编码敏感信息
– 代码与文档、注释不一致
人工擅长发现：
– 业务意图偏差：代码逻辑正确，但解决的不是正确的问题
– 架构风险：这种实现方式在规模变化时会不会成为瓶颈
– 隐式依赖：改动对没有显式引用的模块有影响
– 过度设计：引入了不必要的复杂度
发现后的修正方式：
| 发现来源 | 典型问题 | 修正方式 |
|---|---|---|
| AI 审查 | bug 模式、格式错误、接口不一致 | 直接让 AI 修改，人工确认结果 |
| 人工审查 | 意图偏差、架构风险、隐式影响 | 人工决策后，再指导 AI 修改，或直接人工改 |
流程：先跑 AI 审查（使用 04-prompt/review/pr-review.md），清掉 AI 能发现的问题；再做人工审查，让人工精力集中在 AI 无法判断的部分。
规则：AI 审查不替代人工审查。AI 通过 ≠ 可以合并。
测试策略
按风险等级决定测试方式，而不是按代码类型。
| 风险等级 | 判断依据 | 最低要求 |
|---|---|---|
| 高：核心业务逻辑 | 出错直接影响数据正确性或用户决策 | 人工编写测试，AI 生成的测试不能作为唯一覆盖 |
| 中：集成点和外部接口 | 依赖真实的输入/输出格式，mock 无法发现格式错误 | 集成测试，验证真实数据格式，不只测 happy path |
| 低：工具函数和格式转换 | 逻辑简单、影响范围小、出错易发现 | AI 生成测试 + 人工检查边界值和异常输入 |
规则：AI 生成的测试要像对待生产代码一样审查。测试通过 ≠ 逻辑正确。
AI 生成失败的处理模式
当 AI 输出与预期不符时，不要反复追加提示直到”它猜对了”。
标准处理流程：
- 检查输入 — 问题通常在上下文，不在 AI：接口定义是否完整？约束是否明确？
- 缩小范围 — 把任务拆小，让 AI 做一件事，而不是一次做多件事
- 提供反例 — 明确说”不要生成 X 类型的代码，原因是 Y”
- 切换层级 — AI 卡在实现时，退回到让它先生成接口或伪代码
- 人工接管 — 核心逻辑或安全相关代码，人工编写比反复调整 AI 输出更高效
判断标准：同一段代码迭代超过三轮还未达标，应当人工编写而非继续依赖 AI。
PR 检查清单
可复用模板见 04-prompt/templates/pr-checklist.md，复制到 PR 描述中填写。