> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/03-build.md).

# 03 · 构建

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 输出与预期不符时，不要反复追加提示直到"它猜对了"。

**标准处理流程：**

1. **检查输入** — 问题通常在上下文，不在 AI：接口定义是否完整？约束是否明确？
2. **缩小范围** — 把任务拆小，让 AI 做一件事，而不是一次做多件事
3. **提供反例** — 明确说"不要生成 X 类型的代码，原因是 Y"
4. **切换层级** — AI 卡在实现时，退回到让它先生成接口或伪代码
5. **人工接管** — 核心逻辑或安全相关代码，人工编写比反复调整 AI 输出更高效

**判断标准**：同一段代码迭代超过三轮还未达标，应当人工编写而非继续依赖 AI。

***

## PR 检查清单

可复用模板见 [`04-prompt/templates/pr-checklist.md`](/haiqing-docs/04-prompt/templates/pr-checklist.md)，复制到 PR 描述中填写。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/03-build.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.