【技术教程】AI Coding开发文档教程

Chandler_Song

37人浏览 · 2026-07-24 15:45:44

Chandler_Song · 2026-07-24 15:45:44 发布

AI原生契约开发文档教程

——面向 Codex 编码场景的"轻量级、全生命周期"文档体系

一、方法论定位：为什么不是纯瀑布，也不是纯敏捷

在"用 Codex 编码 + 快速原型 + 文档齐全 + 灵活变更"这个复合需求下，纯瀑布模型太重（文档先行、变更成本极高），纯敏捷模型又太轻（容易导致 AI 在缺乏边界的情况下"自由发挥"、代码失控）。

因此，本教程采用的是 “契约驱动的 AI 协作开发”（Contract-Driven AI Development）：本质上是敏捷开发的节奏（小步快跑、允许迭代），叠加瀑布模型的纪律（关键契约先行冻结、变更留痕可追溯）。

核心铁律：文档是代码的"上游"。变更时严守"先改文档，后改代码"，Codex 只负责在契约框架内执行，人负责定义契约和审查结果。

二、核心理念：用"契约"代替"需求"与"详设"

传统开发中，需求文档和详细设计文档容易脱节，导致 AI 编码时无据可依。本方法论把两者合并为一套 AI 可以直接读取执行的"契约"，主要包括：

产品需求（PRD）：项目范围、用户故事、验收标准
架构契约（ARCHITECTURE）：数据库结构、API 定义、模块依赖关系
AI 操作手册（AGENTS.md）：技术栈、代码风格、禁止行为、常用命令
任务拆解计划（TASK_PLAN）：把需求拆成 AI 可独立执行的最小任务单元

三、全生命周期文档清单

阶段 1：项目启动与快速原型（0→1）

目标：圈定边界，产出可运行的原型。此阶段建立 4 份根目录 /docs/ 核心文档：

文档	内容	作用
AGENTS.md	技术栈、目录结构、代码风格、禁止行为、常用命令	让 Codex 每次读取后保持上下文一致，避免"胡写"
PRD.md	用户故事（作为…我想要…以便…）、核心功能清单、验收标准（Checklist 形式）	极简需求基线，拒绝长篇大论
ARCHITECTURE.md	数据库 ER 图简稿、核心 API 定义（OpenAPI/Swagger）、模块依赖关系	变更时的"底线契约"，任何修改必须在此留痕
TASK_PLAN.md	把 PRD 拆解为可独立执行的子任务，完成后标记 `[DONE]`	让开发进度可视化、可追溯

Codex 提示词模板：

根据 ARCHITECTURE.md 中的接口定义和 TASK_PLAN.md 的 Task 1.2，
编写登录 API 代码，无需额外解释。


---

### 阶段 2：新增需求（横向扩展新功能）

场景示例：新增"用户积分商城"模块。

需要变动的文档：

1. **更新 PRD.md** —— 追加新功能条目及验收标准
2. **更新 ARCHITECTURE.md** —— 追加新表、新 API 路径的契约定义
3. **更新 TASK_PLAN.md** —— 追加新任务编号
4. **新增 CHANGELOG.md** —— 记录本次新增的时间、原因、影响范围

**关键动作**：4 份文档必须先改完，再交给 Codex：

依据最新文档，增量开发 Task 3.x。


---

### 阶段 3：需求变更（纵向修改旧逻辑）

场景示例：原"验证码登录"改为"密码 + 滑块验证码登录"。

这是风险最高的环节，因此单独拆出两份"刹车文档"：

#### 3.1 变更申请单（`/changes/CR-编号-简述.md`）

作用：**审批关口**。Codex 拿到这份文档才允许动代码，否则禁止修改。

必备章节：

- 变更 ID：如 `CR-20260724-001`
- 变更类型：新增功能 / 逻辑修改 / Bug 修复 / 架构重构
- 变更原因：一句话说明业务驱动或技术债动因
- **影响范围评估**：波及前端页面 / API 接口（是否破坏现有契约）/ 数据库表（是否需迁移）
- 兼容性方案：灰度发布 或 强制停机
- 审批状态：待审批 → 已批准 → 已实施

#### 3.2 变更影响评估（`MIGRATION_PLAN.md`）

- 影响范围（前端 / 后端 / DB）
- 兼容策略（是否灰度？旧数据如何处理？）
- 回滚方案（出错时如何快速恢复）

**Codex 提示词模板：**

需求发生变更，请先阅读 CHANGELOG.md 和 MIGRATION_PLAN.md。
忽略旧代码逻辑，严格按照更新后的 ARCHITECTURE.md 重构登录模块，
并附带数据库迁移脚本（如 Prisma migration）。


同时，`CHANGELOG.md` 只做**结果记录**（给人看的版本履历），不记录过程：

[2026-07-24] v2.1.0 - 登录模块增加滑块验证码 (关联 CR-20260724-001)


---

### 阶段 4：后续持续迭代（长期演进）

场景示例：项目运行两个月后需要重构或优化。

需要变动的文档：

- **更新 AGENTS.md**：把踩坑经验写进"坑爹集"，例如"日期存储一律用 UTC，避免时区问题"，让 Codex 以后不再犯同样错误
- **新增 RETROSPECTIVE.md**：记录本次迭代的性能瓶颈、技术债
- **更新 TASK_PLAN.md**：根据复盘结果拆解出重构任务和优化任务

---

## 四、独立的"审查"文档：训练 Codex 的"错题本"

Codex 生成代码速度快，但人工 Review 耗时，因此必须单独维护一份**审查记录**，用于统计 AI 的犯错规律，防止"同一个坑踩两次"。

### 审查记录单（`/reviews/REVIEW_RECORD.md`）

必备章节：

- 审查时间 / 关联变更（对应 CR 编号）
- **AI 生成代码缺陷统计**：逻辑错误 ___ 处 / 规范违背 ___ 处 / 安全漏洞 ___ 处
- 典型错误摘录：贴出错误代码片段和修复后代码
- 规则反哺：本次问题是否需要更新 AGENTS.md 以永久规避（是/否）

---

## 五、极简目录结构建议

```text
/your-project
├── AGENTS.md          # 永恒规则（AI操作手册）
├── PRD.md             # 需求基线
├── ARCHITECTURE.md    # 核心契约
├── TASK_PLAN.md       # 任务拆解与进度
├── CHANGELOG.md       # 只读，发布版本流水账
│
├── /changes           # 活跃变更专区（正在进行中）
│   ├── CR-001-登录加验证码.md
│   └── MIGRATION_CR-001.sql
│
└── /reviews           # 审查归档
    └── REVIEW-2026Q3.md   # 季度审查汇总，用于复盘

六、Codex 协作的两条硬性指令

在 AGENTS.md 中必须明确写入以下两条规则：

规则 1（变更纪律）：收到修改指令时，必须先检查 /changes 下是否有对应的 CR-*.md 文件。若无，不得修改任何代码，必须反问开发者：“请先创建变更申请单。”

规则 2（审查反哺）：每次完成代码后、提交前，必须将本次修改对比 /reviews/REVIEW_RECORD.md 中记录的"典型错误"进行自检。

给 Codex 的终极身份指令：

你只负责实现，我是架构师。任何逻辑冲突，以 /docs/ 目录下最新文档为准；
若文档冲突，停止编码并向我提问。

七、快速原型场景的补充策略：双轨开发

若需求本身还不明确，可在阶段 1 之前加入"双轨敏捷"：

轨道 1（探索）：用高保真可点击原型（Figma / 墨刀）快速验证业务逻辑，不写代码
轨道 2（交付）：开发团队只开发已验证通过的原型模块，未验证清楚绝不开工编码，避免返工

配合 Scrum + 看板的节奏：维护一个按优先级排序的需求池（Backlog），每轮迭代（1~4 周）从池顶拉取任务进入冲刺清单，用看板（待办→进行中→测试中→已上线）可视化流转，并严格限制"进行中"任务数量。

八、总结：极简文档矩阵与操作口诀

场景	必改文档	新增文档
初始开发	AGENTS.md / PRD.md / ARCHITECTURE.md / TASK_PLAN.md	无
新增需求	PRD.md / ARCHITECTURE.md / TASK_PLAN.md	CHANGELOG.md
变更逻辑	PRD.md / ARCHITECTURE.md（契约重点改）	CR 申请单 + MIGRATION_PLAN.md
后续迭代	AGENTS.md（补充规则）	RETROSPECTIVE.md
代码审查	—	REVIEW_RECORD.md

一句话口诀：

契约先行定边界，变更申请当刹车，审查记录做错题本，Codex 只管照契约执行。

规模裁剪建议：

小型项目/个人开发：CR 申请单可简化为在 TASK_PLAN.md 里加一行备注，但 REVIEW_RECORD.md 不能省——它是训练 Codex 趋于完美的"错题本"。
企业级/多人协作：CR 必须严格走审批流程，REVIEW_RECORD 必须关联到具体的 Git PR 编号。