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