AI Coding SOP 严格开发交付标准 v2 使用手册
一份给真实开发使用的操作手册：先定交付标准，再按项目规模裁剪；默认 Codex-only，检测到设计 Agent 产物后再确认切换。
1. 这份手册解决什么
这套 SOP 的目标不是让 AI 多写文档，而是让 AI 开发过程可控、可验收、可复盘。你应该把它当成一个开发交付标准，而不是单次提示词。
核心规则：所有开发默认走 Codex-only；如果提供了设计 Agent 的前端设计方案，Codex 必须识别并询问你是否切换到 Design-Agent + Codex。
它会约束什么
- 需求是否清楚
- 设计是否完整
- 开发计划是否可执行
- 测试证据是否存在
- 交付是否能验收
它不会强制什么
- 不会要求所有小任务都写满 17 份文档
- 不会让设计 Agent 接管生产代码
- 不会替你静默切换流程
- 不会把文档当成最终成果
2. 5 分钟快速开始
- 在项目根目录准备或更新
AGENTS.md。 - 把 AGENTS 自动应用规则 中的片段复制进去。
- 新任务开始时，让 Codex 先判断任务等级：
L0到L4。 - 让 Codex 创建任务目录：
docs/tasks/YYYY-MM-DD-task-name/。 - 先产出
00-tailoring-decision.md，确认哪些文档必须写、哪些可以裁剪。 - 在
09-development-plan.md确认前，不让 Codex 写代码。 - 开发完成后，必须有
13-test-report.md和17-delivery-summary.md。
推荐启动提示词
本任务请严格采用 AI Coding SOP v2。
请先不要写代码，先完成：
1. 读取 AGENTS.md 和项目上下文。
2. 判断任务等级 L0-L4。
3. 判断是否存在设计 Agent 产物。
4. 生成 00-tailoring-decision.md，列出必需文档和裁剪文档。
5. 根据裁剪结果生成 PRD、设计方案、测试用例和开发计划。
6. 等我确认 development-plan 后再开始编码。3. 选择开发模式
模式选择只影响前端设计来源，不影响完整交付链路。系统设计、数据库设计、接口设计、测试报告、交付总结仍然需要按 SOP 执行。
默认
Codex-only
Codex-only
检测
是否存在设计 Agent 产物
是否存在设计 Agent 产物
确认
询问用户是否切换
询问用户是否切换
执行
按确认后的模式开发
按确认后的模式开发
| 模式 | 何时使用 | 谁负责前端设计 | 谁负责生产代码 |
|---|---|---|---|
| Codex-only | 默认；后台、工具、MVP、常规业务功能 | Codex | Codex |
| Design-Agent + Codex | 已有 Figma、原型图、UI Design Spec、设计 Agent 方案 | Design Agent | Codex |
不要让多 Agent 同时修改生产前端代码。Design Agent 交付设计产物，Codex 统一落地工程实现。
4. 选择裁剪等级
先完整定义标准，再根据任务裁剪。裁剪必须写进 00-tailoring-decision.md。
| 等级 | 适用场景 | 最低要求 |
|---|---|---|
| L0 | 文案、小样式、单文件 bug | 任务摘要、实现计划、验证报告、交付总结 |
| L1 | 小功能、单页面、单接口 | PRD、简版设计、测试用例、测试报告、交付总结 |
| L2 | 标准业务功能 | PRD、需求分析、系统设计、条件设计文档、开发日志、测试报告 |
| L3 | 跨模块、数据库、外部集成、复杂前端流程 | 完整设计包、任务拆解、代码审查、集成报告、验收报告 |
| L4 | 生产核心、高风险、支付、权限、数据安全 | L3 全量文档 + 安全/性能/回滚/发布审批证据 |
5. 创建过程文档
建议每个任务使用独立目录。小任务可以合并文档，但必须保留对应章节。
docs/tasks/YYYY-MM-DD-task-name/
00-tailoring-decision.md
01-prd.md
02-requirements-analysis.md
03-system-design.md
04-database-design.md
05-api-integration-design.md
06-frontend-design.md
07-security-permission-design.md
08-test-case-design.md
09-development-plan.md
10-task-breakdown.md
11-development-log.md
12-code-review-report.md
13-test-report.md
14-integration-report.md
15-deployment-rollback-plan.md
16-acceptance-report.md
17-delivery-summary.md
design/
references/什么时候必须写专项设计
| 触发条件 | 必须文档 |
|---|---|
| 新增表、字段、索引、迁移、查询模式 | 04-database-design.md |
| 前后端接口、外部 API、Webhook、消息队列 | 05-api-integration-design.md |
| 新页面、新组件、响应式、交互状态 | 06-frontend-design.md |
| 登录、权限、敏感数据、文件上传、外部输入 | 07-security-permission-design.md |
| 任何实现任务 | 08-test-case-design.md 和 13-test-report.md |
6. Codex-only 用法
这是默认模式。Codex 负责完整交付链路，但仍必须先写计划再开发。
操作顺序
- 让 Codex 判断任务等级。
- 让 Codex 生成
00-tailoring-decision.md。 - 让 Codex 生成 PRD、系统设计和触发的专项设计。
- 让 Codex 生成测试用例设计。
- 让 Codex 生成开发计划。
- 你确认开发计划后，Codex 开始编码。
- Codex 维护开发日志。
- Codex 运行测试并生成报告。
- Codex 生成验收报告和交付总结。
Codex-only 提示词
本任务采用 Codex-only SOP。
请按 AI Coding SOP v2 执行：
1. 判断任务等级和裁剪范围。
2. 创建 docs/tasks/YYYY-MM-DD-task-name/。
3. 生成 00-tailoring-decision.md。
4. 根据任务范围生成必要设计文档，包括系统、数据库、接口、前端、安全、测试。
5. 生成 09-development-plan.md，等待我确认。
6. 确认后再编码。
7. 开发过程维护 11-development-log.md。
8. 完成后生成 13-test-report.md、16-acceptance-report.md、17-delivery-summary.md。7. Design-Agent + Codex 用法
这个模式只在你提供设计 Agent 的前端设计产物时启用。它不替代完整开发 SOP，只替换前端设计来源。
必须提供的设计 Agent 产物
design/ui-design-spec.mddesign/design-agent-handoff.mddesign/prototype.md或可访问的 Figma/截图/HTML 原型
Codex 应该做什么
- 检测到设计产物后询问你是否切换。
- 确认后审查设计交付物是否完整。
- 如果不完整，列出缺口，而不是直接猜。
- 将 UI Design Spec 映射到组件、样式、状态和测试。
- 由 Codex 实现生产代码。
- 用截图对照设计方案。
切换提示词
我已提供设计 Agent 的前端设计产物。
请先不要写代码：
1. 检查是否满足 Design-Agent + Codex SOP 的最低交付物。
2. 如果满足，请询问我是否确认切换到 Design-Agent + Codex。
3. 我确认后，你再审查 UI Design Spec、Handoff 和 Prototype。
4. 将设计映射到系统设计、组件实现、测试用例和开发计划。
5. 生产代码仍由 Codex 统一实现。
6. 完成后用桌面和移动端截图对照设计。8. 开发过程中怎么推进
开发过程中不要只盯代码。你应该让 Codex 维护执行证据。
| 阶段 | 你要看什么 | 不通过怎么办 |
|---|---|---|
| 开发前 | 09-development-plan.md 是否具体可执行 |
要求拆小任务，不准直接编码 |
| 开发中 | 11-development-log.md 是否记录偏离和决策 |
要求补日志，并解释偏离原因 |
| 开发后 | 13-test-report.md 是否有命令和结果 |
要求运行验证或记录不能运行的原因 |
| 前端后 | 是否有桌面和移动端视觉 QA | 要求截图检查并继续 polish |
| 交付前 | 17-delivery-summary.md 是否说明风险 |
要求补充已知限制和后续项 |
9. 测试、验收和交付
完成不是“代码写完”。完成必须有证据。
完成前检查
- PRD 验收标准是否逐项满足。
- 设计文档是否没有被随意偏离。
- 数据库、接口、前端、安全变更是否有对应设计。
- 测试用例是否覆盖核心验收标准。
- 测试报告是否记录命令和结果。
- 前端是否完成视觉 QA。
- 交付总结是否说明风险和后续项。
禁止：没有测试报告就说“已完成”；没有视觉 QA 就说“前端完成”；没有回滚方案就发布数据库迁移。
10. 常用提示词
让 Codex 判断任务等级
请根据 AI Coding SOP v2 判断这个任务属于 L0-L4 哪个等级。
请输出：
1. 等级
2. 判断理由
3. 必须文档
4. 可以裁剪的文档
5. 裁剪风险
6. 是否涉及系统、数据库、接口、前端、安全、测试、部署让 Codex 补齐设计方案
请根据当前 PRD 和需求分析，补齐设计方案文档。
必须判断是否需要：
- system-design
- database-design
- api-integration-design
- frontend-design
- security-permission-design
- test-case-design
- deployment-rollback-plan
只生成被触发的文档，并说明未生成文档的裁剪理由。让 Codex 做完成前检查
请按 AI Coding SOP v2 做完成前检查。
检查：
1. 必需过程文档是否存在。
2. 裁剪项是否有理由。
3. PRD 验收标准是否满足。
4. 设计方案是否被遵守。
5. 测试报告是否有命令和结果。
6. 前端是否有视觉 QA。
7. 交付总结是否完整。
如果缺失，请继续补齐，不要直接宣布完成。11. 常见错误
| 错误 | 后果 | 正确做法 |
|---|---|---|
| 一开始就让 Codex 写代码 | 需求和设计被模型猜测 | 先裁剪、再设计、再计划、再开发 |
| 把 SOP 当成必须全写的文档清单 | 小任务过重 | 使用 L0-L4 裁剪等级 |
| 设计 Agent 直接改生产代码 | 代码风格、架构和状态管理分裂 | 设计 Agent 交付设计，Codex 落地代码 |
| 没有接口设计就前后端并行 | 集成返工 | 先写 API 契约和错误码 |
| 测试报告只写“通过” | 没有证据 | 记录命令、结果、失败和修复 |
12. SOP 文档入口
这些文件和本手册位于同一目录。
- 00 摘要索引
- 01 SOP 总则与裁剪规则
- 02 过程文档清单与交付标准
- 03 设计方案文档标准
- 04 Codex-only 开发 SOP
- 05 Design-Agent + Codex 开发 SOP
- 06 开发计划、日志、测试报告标准
- 07 AGENTS 自动应用规则
- 08 模板集合
建议下一步：把 07-AGENTS自动应用规则.md 的 AGENTS 片段复制到你的 AI_Coding_SOP 项目模板中。