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 编号。
