> 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/05-workflow/dev-cycle.md).

# 日常开发循环

从需求到 PR 合并的完整流程，以及 AI 在每个阶段扮演什么角色。

***

## 问题

AI 驱动开发中最常见的失败模式是：把任务直接扔给 AI，等它生成结果，然后发现结果偏了，再返工。这不是 AI 能力的问题，是输入阶段的结构问题。

AI 在每个步骤的质量上限，等于输入给它的上下文质量。模糊的需求产生模糊的代码，不完整的约束产生不完整的实现。结构化的输入是 AI 稳定输出的前提，不是可选项。

***

## 开发循环

```
需求 → 结构化 → 设计 → 生成 → 审查 → 合并
```

每个箭头都是一个交接点。交接点不清晰，后续阶段就会出现意外。

| 阶段 | 人类做什么       | AI 做什么        | 交接物      |
| -- | ----------- | ------------- | -------- |
| 需求 | 整理背景，明确验收标准 | —             | 结构化的任务描述 |
| 设计 | 选择方案，确认约束   | 生成实现方案初稿      | 确认的技术方案  |
| 生成 | 提供规格和约束上下文  | 生成代码和测试       | 待审查的 PR  |
| 审查 | 判断正确性和风险    | 初筛代码问题，生成审查评论 | 合并就绪的 PR |
| 合并 | 最终合并决策      | —             | 交付的功能    |

***

## 需求结构化

在向 AI 分配开发任务之前，先将需求结构化。这一步的作用是把模糊的意图转换成 AI 可以直接使用的上下文。

```
目标：[一句话，期望实现什么结果]
背景：[相关上下文，AI 需要知道什么才能做出正确决策]
约束：[不能做什么 / 必须兼容什么 / 性能或安全要求]
验收标准：[完成的判断依据，每条标准应该可以转化为测试]
排除范围：[明确不在本次任务内的内容]
```

**如果某个字段填不上，停在这一步**。填不完意味着需求本身还没有澄清，继续推进只会在后续阶段产生更大的返工成本。

**验收标准的质量决定代码质量**。写得足够具体的验收标准，可以直接转化为测试用例（见 [spec-code-alignment.md](/haiqing-docs/05-workflow/spec-code-alignment.md)）。写成"功能正常工作"这类标准是无效的。

***

## Sprint 中的 AI 检查点

Sprint 的每个环节都有适合 AI 参与的工作，也有必须由人类保留的判断。区分这两类，是让 AI 稳定参与迭代的前提。

| 环节 | AI 参与          | 人类保留       |
| -- | -------------- | ---------- |
| 规划 | 生成任务拆解初稿、估时参考  | 优先级决策、范围裁定 |
| 站会 | 生成进度摘要、识别阻塞模式  | 协调与当前决策    |
| 开发 | 生成代码、测试、文档初稿   | 架构决策、约束判断  |
| 审查 | 初筛代码问题、生成审查评论  | 最终合并裁决     |
| 复盘 | 汇总周期数据、提炼改进项候选 | 判断哪些值得跟进   |

**规则**：任何对外承诺、对优先级的裁定、对安全和性能约束的判断，都不能直接使用 AI 的输出作为最终结论。这些是判断权归属于人类的领域。

***

## 审查阶段

AI 代码审查的价值在于筛查量大的、规则性的问题（命名、重复、明显的逻辑错误、遗漏的边界情况），而不是替代人类对设计合理性和业务正确性的判断。

**有效的 AI 审查上下文**：

* 对应的需求文档（REQ 文件或结构化需求描述）
* 这段代码修改了哪个模块、影响了哪些现有行为
* 需要重点关注的约束（性能、安全、兼容性）

**人工审查必须覆盖**：

* 业务逻辑是否与需求一致
* 边界情况是否正确处理
* 是否引入了新的耦合或职责混乱

**规则**：AI 的审查评论是候选问题列表，不是已确认的问题列表。人工审查决定哪些评论是真正的问题。

***

## 循环断裂的信号

以下迹象说明循环的某个环节出了问题：

* 生成的代码频繁偏离需求 → 需求结构化阶段不彻底
* AI 反复修改同一段代码 → 约束没有在输入时明确，而是在输出后才发现
* 审查阶段发现大量问题 → 生成阶段没有提供足够的上下文（规格、测试要求）
* 相同的错误在多个 Sprint 重复出现 → 复盘阶段的改进项没有转化为结构化的约束更新


---

# 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/05-workflow/dev-cycle.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.