一、AICoding 范式

2023 年，Cursor 和 GitHub Copilot 把 AI Coding 带入主流视野。那时候的体验是：你描述一个函数，AI 给你代码。一个排序算法、一段数据处理、一个工具函数——AI 写得又快又好。

这给了很多人一个错觉：AI 编程时代来了，码农要被取代了。但这个错觉止步于真实项目。

当你让 AI 从零开始做一个完整的项目——有多个模块、有前后依赖、有边界条件处理、有测试覆盖——你很快就会发现：AI 不缺能力，缺的是约束。

1、AI Coding 的三个致命幻觉

幻觉一：AI 理解了我的需求

现实：AI 只能理解你写出来的需求，而自然语言天然存在歧义。

你说"实现一个缓存"，AI 可能实现了一个 5 分钟过期的内存字典，而你的系统实际上需要 LRU + 持久化 + 容量上限。

这不是 AI 的问题——这是需求模糊的问题。在传统工程中，需求模糊会在设计评审阶段被暴露；在纯对话式 AI Coding 中，AI 会直接按它理解的最合理方式实现，然后你验收时才发现方向错了。

幻觉二：AI 的代码质量有保证

现实：AI 写的代码通过了测试不等于满足需求。

一个函数可以通过单元测试，但测试本身可能覆盖了错误的场景。AI 擅长实现"看起来合理"的逻辑，但难以主动识别你没有说出来的边界条件。

举个例子：处理用户输入时，你没有明确说"用户名不能为空"，AI 可能就没处理这个边界，然后你的系统在空用户名进入时崩溃了。

幻觉三：多模块协作不需要协调

现实：当多个 AI Agent（或同一个 AI 的多轮对话）分别实现不同模块时，模块间的接口对齐是一个巨大的隐性成本。

A 模块写了一个 UserService.get_user() 返回字典，B 模块期望它返回对象实例——两个 AI 在各自的对话窗口里写代码，最后集成时发现类型不匹配，每个模块都要改。

2、给 AI 建立约束

范式不是限制 AI 的能力，而是建立工程秩序。

AI 最大的优势是执行力强、速度快；最大的劣势是没有工程直觉、需要人类的方向判断。范式的作用，就是把人类的方向判断前置，把 AI 的执行效率最大化。

具体来说，一个好的 AI Coding 范式需要解决三个核心问题：

问题 1：如何让 AI 不跑偏？

解法：在代码实现之前，先对齐需求和设计。

需求文档 + 概要设计 + 详细设计，构成了一道道"检查站"。AI 必须先在每个检查站获得人类的确认，才能进入下一个阶段。这不是低效，而是把错误成本降到最低。

问题 2：如何让 AI 之间不打架？

解法：接口合约 + 共享上下文。

详细设计完成后，额外生成一份接口合约文件（shared-api.md），明确每个模块对外暴露的接口。然后在代码实现阶段，维护一个共享上下文文件（shared-context.md），每个子 Agent 在实现前必须读取，实现后必须更新。

这解决了两个问题：模块间接口对齐，以及避免重复造轮子。

问题 3：AI 失败了怎么办？

解法：量化粒度 + 失败回退机制。

每个任务的代码量不超过 200 行，对话轮次不超过 5 轮——超出则强制拆分。失败后重试 3 次仍未通过，标记为阻塞项（BLOCKED），跳过继续推进其他模块，最后统一处理。

结合上述问题，我整理了一套七阶段的 AI Coding 标准流程，适用于中大型工程：

阶段	名称	人工介入	核心产出
1	需求分析	必须	proposal.md
2	概要设计	必须	high-level-design.md
3	详细设计	必须	detailed-design.md + shared-api.md
4	任务划分	可选	tasks/*.md + progress.md
5	代码实现	无需	src/ + shared-context.md
6	质量门禁	无需	pytest + mypy + ruff
7	AI 代码审查	可选	review/*.md

关键原则只有三条：

• 设计在前，实现在后——人类在设计阶段把方向定清楚，AI 在实现阶段专注执行

• 接口有合约，协作有上下文——多 Agent 之间通过共享文件同步，不靠记忆

• 失败有策略，阻塞有标记——不让错误卡住整个流程，量化任务粒度保持 AI 的专注度

当然 AI Coding 范式不能解决所有问题。你仍然需要懂技术的人来审核设计、来做架构决策、来判断 AI 的输出是否符合业务目标。

但范式解决了一个根本问题：把 AI 从一个"能干的实习生"变成一个"可控的执行者"。

没有范式，AI 写代码就像开一辆没有方向盘的车——速度很快，但目的地由不得你。

有了范式，AI 是你手里的工具：方向你定，执行它来，出了问题你能追溯到哪一步出了问题。

这才是 AI Coding 真正该有的样子。

二、AICoding 参考范式

阶段一：需求分析

目标

使用自然语言与 AI 共同确认项目需求，生成结构化需求文档。

输入

• 用户对项目的初步描述（自然语言）

• 现有工程目录结构（如有）

• 相关参考资料（如有）

输出

• doc/proposal.md

步骤

1. AI 阅读用户描述和工程目录

2. AI 以提问方式逐项确认需求，不得猜测用户意图，任何不明确的地方必须提问

3. 用户逐一回答后，AI 生成结构化需求文档

需求文档结构

# 需求文档
​
## 项目概述
## 功能需求（按模块列出）
## 非功能需求（性能、平台、依赖等）
## 约束条件
## 验收标准

---

阶段二：概要设计

目标

基于需求文档，划分系统模块及模块间关系，生成概要设计文档。

输入

• doc/proposal.md

输出

• doc/high-level-design.md

步骤

1. AI 阅读需求文档

2. 识别核心功能域，划分独立模块

3. 明确模块间的依赖关系和数据流向

4. 任何不明确的地方必须向用户提问，不得假设

5. 生成概要设计文档（须经用户确认后方可进入下一阶段）

概要设计文档结构

# 概要设计
​
## 模块划分
| 模块名 | 职责描述 | 对外接口 |
​
## 模块依赖关系图（文字版）
## 数据流说明
## 技术选型说明

---

阶段三：详细设计

目标

为每个模块编写详细设计，明确实现细节，模块间保持相互独立、可独立测试。

输入

• doc/proposal.md

• doc/high-level-design.md

输出

• doc/detailed-design.md

• doc/shared-api.md（模块间接口合约）

步骤

1. AI 阅读需求文档和概要设计

2. 为每个模块编写详细设计（数据结构、函数签名、处理逻辑）

3. 提取模块间公共接口，写入 doc/shared-api.md

4. 任何不明确的地方必须向用户提问

5. 生成详细设计文档（须经用户确认后方可进入下一阶段）

详细设计文档结构

# 详细设计
​
## 模块：[模块名]
### 数据结构定义
### 函数/类设计
### 处理流程（伪代码或文字描述）
### 错误处理策略
### 测试要点

接口合约文件（doc/shared-api.md）结构

# 模块间接口合约
​
## 公共数据类型
## 模块 A 对外暴露的接口
## 模块 B 对外暴露的接口
## 约定的错误码和异常类型

规则：子 Agent 实现代码前必须读取 shared-api.md，实现结果必须符合合约定义。

---

阶段四：任务划分

目标

将详细设计分解为 AI 可执行的最小编码任务，每个任务独立可测。

输入

• doc/proposal.md

• doc/detailed-design.md

输出

• doc/tasks/<module-name>.md（每个模块一个任务文件）

• doc/tasks/progress.md（总体进度）

步骤

1. AI 阅读需求文档和详细设计

2. 按模块逐一生成最小任务列表

3. 每个任务须满足粒度约束（见下方）

4. 生成进度总览文件

任务粒度约束

约束项	限制
单任务预期代码量	≤ 200 行
单任务对话轮次	≤ 5 轮
每个任务须有	独立测试文件
超出限制时	必须强制拆分为更小子任务

模块任务文件（<module-name>.md）结构

# 模块：[模块名]
​
## 任务列表
- [ ] 任务 1：实现 xxx 函数（预期 ≤50 行）
  - 输入：
  - 输出：
  - 测试文件：tests/test_xxx.py
- [ ] 任务 2：...

进度文件（progress.md）结构

# 总体进度
​
- [ ] 模块 A
- [ ] 模块 B
- [ ] 模块 C

---

阶段五：代码实现

目标

生成主 Agent 起始 Prompt，由主/子 Agent 协作完成全部模块的代码实现。

输入

• doc/proposal.md

• doc/detailed-design.md

• doc/shared-api.md

• doc/tasks/

输出

• doc/prompt.md（主 Agent 起始 Prompt）

• src/（各模块代码）

• tests/（各模块测试）

• doc/shared-context.md（共享上下文索引，由 Agent 运行时维护）

步骤

1. AI 阅读所有输入文档，了解工程全貌

2. 生成 doc/prompt.md 作为主 Agent 起始 Prompt

3. 主 Agent 按进度调度子 Agent，逐模块执行

4. 子 Agent 执行完成后更新 doc/shared-context.md

5. 整个过程无需人工参与，遇到阻塞时触发失败回退机制

主 Agent Prompt 模板

你是一个负责整体进度的主 Agent。
​
工程背景：[读取 doc/proposal.md]
详细设计：[读取 doc/detailed-design.md]
接口合约：[读取 doc/shared-api.md]
任务列表：[读取 doc/tasks/]
​
你的职责：
1. 按 progress.md 中的顺序调度子 Agent 实现每个模块
2. 每个子 Agent 启动前，让其读取 shared-api.md 和 shared-context.md
3. 每个子 Agent 完成后，更新 shared-context.md 和 progress.md 中的 checklist
4. 若某模块失败超过 3 次，标记为 BLOCKED 并跳过，继续推进其他模块
5. 所有模块完成后，输出最终状态报告

子 Agent Prompt 模板

你是负责实现 [模块名] 的子 Agent。
​
实现要求：
  读取 doc/shared-api.md，确保你的实现符合接口合约
  读取 doc/shared-context.md，复用已有的公共函数，不要重复实现
  读取 doc/tasks/[module-name].md，按任务列表逐一实现
​
编码要求：
  代码必须有完整的 pytest 单元测试
  通过 mypy --strict 类型检查
  通过 ruff check 代码风格检查
​
完成后：
  将本模块新增的公共接口追加写入 doc/shared-context.md
  更新 doc/tasks/[module-name].md 中对应任务的 checklist

共享上下文文件（doc/shared-context.md）结构

# 共享上下文索引
​
## 已实现的公共函数
| 函数名 | 所在文件 | 用途描述 |
​
## 已定义的公共常量/配置
## 已实现的公共类/数据结构

---

阶段六：质量门禁

目标

对每个模块的代码进行自动化质量检查，不合格的代码触发失败回退。

检查项

工具	命令	通过标准
pytest	pytest tests/	无 FAILED，覆盖率 ≥ 80%
mypy	mypy src/ --strict	无 error
ruff	ruff check src/	无 error

失败回退策略

重试次数 ≤ 3 次：
  - 将完整错误日志（结构化）传递给子 Agent 重试
  - 错误日志格式：{ "tool": "pytest", "error_type": "AssertionError", "location": "tests/test_xxx.py:42", "message": "..." }
​
重试次数 > 3 次：
  - 上报主 Agent
  - 主 Agent 将该模块标记为 BLOCKED
  - 继续推进其他模块
  - 在最终报告中列出所有 BLOCKED 模块，供人工处理

---

阶段七：AI 代码审查

目标

在质量门禁通过后，对照需求文档进行语义级审查，确保代码实现与需求一致。

输入

• doc/proposal.md

• 对应模块的 src/ 代码

输出

• doc/review/<module-name>-review.md

Reviewer Prompt 模板

你是一个资深代码审查员。
​
请对照需求文档 doc/proposal.md，对 src/[module_name]/ 进行语义级审查。
​
重点检查：
  1. 是否覆盖了需求中该模块的所有功能点
  2. 是否处理了边界条件和异常情况
  3. 函数命名和注释是否清晰、准确
  4. 是否存在明显的性能问题或安全隐患
  5. 测试用例是否覆盖了关键业务逻辑
​
输出审查报告至 doc/review/[module-name]-review.md，格式如下：
  ## 审查结论：PASS / PASS WITH NOTES / FAIL
  ## 功能覆盖情况
  ## 问题列表（含严重程度：P0/P1/P2）
  ## 改进建议

---

推荐的工程目录结构

project/
├── src/
│   ├── module_a/
│   └── module_b/
├── tests/
│   ├── test_module_a.py
│   └── test_module_b.py
├── doc/
│   ├── proposal.md              # 需求分析
│   ├── high-level-design.md     # 概要设计
│   ├── detailed-design.md       # 详细设计
│   ├── shared-api.md            # 接口合约
│   ├── shared-context.md        # 共享上下文索引（运行时维护）
│   ├── prompt.md                # 主 Agent 起始 Prompt
│   ├── tasks/
│   │   ├── progress.md          # 总体进度
│   │   ├── module-a.md          # 模块 A 任务列表
│   │   └── module-b.md          # 模块 B 任务列表
│   └── review/
│       ├── module-a-review.md   # 模块 A 代码审查报告
│       └── module-b-review.md   # 模块 B 代码审查报告
└── pyproject.toml / CMakeLists.txt

---