AI开发中大型项目开发 SOP(标准作业程序)

AI开发中大型项目开发 SOP（标准作业程序）

版本: v2.0
适用: Web 应用、API 服务、AI Agent 项目
核心理念: 规格驱动 × TDD × 质量门禁
本 SOP 不绑定任何具体工具，任何执行者（人或 Agent）均须遵守。

总则

执行原则

每一阶段有明确的输入检查
—— 材料不齐，不得开工
每一阶段有明确的产出标准
—— 产出未达标，不得进入下一阶段
每一个产出有对应的验收方式
—— 不可验收 = 不可交付
质量门禁是硬约束
—— 不通过的代码不得合并

阶段总览

阶段 1: 需求分析与规格定义

1.1 输入检查清单

进入本阶段前，必须确认以下材料齐全：

□ 业务目标陈述（一句话：谁、解决什么问题、核心价值是什么）
□ 目标用户画像（至少 2 个角色，含角色的目标与痛点）
□ 竞品参考（至少 1 个竞品的主要功能对比）
□ 非功能需求草案（性能、安全、合规、可访问性的初步期望）
□ 遗留系统约束（如有，列出不可改的部分）

1.2 执行步骤

步骤	操作	产出
1. 业务分析	梳理核心业务流程，画业务流程图	业务流程图
2. 用户故事编写	按用户角色拆解功能，标注优先级 P0 / P1 / P2	用户故事地图
3. 验收标准定义	每条 P0/P1 故事写 Given-When-Then 验收标准	验收标准清单
4. 非功能需求量化	将性能/安全/可用性指标转化为可测量的数字	NFR 指标文档
5. PRD 汇总	整合以上产出为标准 PRD 文档	PRD.md

1.3 输出标准

□ 业务流程图（含主流程、异常流程、参与角色）
□ 用户故事覆盖 ≥ 2 个角色 × ≥ 3 条故事，每条标注 P0/P1/P2
□ 所有 P0 故事有 Given-When-Then 验收标准
□ P0 验收标准经人工逐条确认
□ NFR 全部量化（用数字，不用"快""稳定"等模糊词）

1.4 验收标准格式（强制）

Feature: [功能名称]
  作为 [角色]
  我想要 [做什么]
  以便 [达成什么价值]

Scenario: [场景名称]
Given [前置条件]
When [触发动作]
Then [预期结果]
And [附加验证]

示例:

Scenario: 正常下单
Given 用户已登录，购物车中有 2 件商品
When 用户点击"结算"，选择微信支付，点击"确认支付"
Then 页面跳转到支付成功页
And 订单状态为"待发货"
And 商品库存减少 2
And 用户收到订单确认通知

Scenario: 库存不足时下单
Given 用户已登录，购物车中有商品 A 数量 5
And 商品 A 库存仅剩 2
When 用户点击"结算"
Then 系统提示"商品 A 库存不足，当前仅剩 2 件"
And 数量自动调整为 2

阶段 2: 架构设计

2.1 输入检查

□ PRD 已完成，所有 P0 验收标准确认完毕
□ NFR 全部量化
□ 无阻塞性待决策问题

2.2 执行步骤

步骤	操作	产出
1. 技术选型	列出候选技术栈，对比优劣，给出推荐方案及理由	技术选型决策表
2. 架构设计	绘制系统架构图、数据流图、部署拓扑图	架构图
3. 数据建模	设计 ER 图，定义所有表/集合的字段、类型、约束、索引	数据模型文档
4. 接口定义	设计所有 API 端点，定义请求/响应结构、状态码、错误格式	OpenAPI 3.0 规格文件
5. 原型验证	实现核心链路的最小可行原型，验证技术方案可行	原型代码
6. 变更影响分析	如果是改造项目，分析本次变更对现有系统的影响	影响分析报告
7. 架构决策记录	记录关键决策及其理由	ADR 文档

2.3 输出标准

□ 系统架构图：组件、数据流向、外部依赖标注清楚
□ 数据模型：所有实体、字段类型、约束、索引完整定义
□ API 规格：OpenAPI 3.0 格式，含所有端点的请求/响应 Schema
□ 技术选型决策表：候选方案 + 对比维度 + 最终选择 + 理由
□ ADR：关键决策记录（至少 1 条）
□ 原型代码可运行，核心链路走通

2.4 架构产出格式规范

技术选型决策表:

维度	候选 A	候选 B	候选 C	最终选择	理由
运行时	Node.js	Python	Go	—	—
Web 框架	Express	FastAPI	Gin	—	—
数据库	PostgreSQL	MongoDB	MySQL	—	—
...	...	...	...	...	...

阶段 3: 任务拆解与排期

3.1 输入检查

□ PRD 完整
□ 架构设计文档完整
□ API 规格文件完成
□ 技术选型已确认

3.2 执行步骤

步骤	操作	产出
1. 垂直切分	按用户可感知的功能拆分为独立追踪单元（Tracer Bullet）	功能切片列表
2. 生成任务	每个切片生成一个独立开发任务	任务卡片
3. 排序分流	按优先级和依赖关系排序	已排序任务列表
4. 排期	分配迭代周期	迭代计划

3.3 任务卡片标准格式

每个任务卡片必须包含以下字段：

## 用户故事
[一句话描述]

## 验收标准 (Given-When-Then)
- [ ] Scenario 1: [Given] ... [When] ... [Then] ...
- [ ] Scenario 2: [Given] ... [When] ... [Then] ...

## 技术规格
- 接口: POST /api/xxx（参见 openapi.yaml Line XX）
- 数据模型: 影响表 xxx，字段见 schema.md
- 依赖: 任务 #XX（需先完成）

## Definition of Done
- [ ] 代码实现完成
- [ ] 单元测试编写，覆盖率 ≥ 90%
- [ ] 集成测试覆盖所有关联端点
- [ ] E2E 测试覆盖核心用户流程
- [ ] 代码审查通过
- [ ] 所有验收标准通过

3.4 输出标准

□ 所有 P0 需求拆解为独立任务卡片
□ 每个任务卡片包含完整 AC + 技术规格 + DoD
□ 任务按依赖关系排序
□ 阻塞性依赖已识别并标注
□ 迭代计划明确（时间、负责人）

阶段 4: TDD 实现（迭代核心）

4.1 TDD 循环

每个任务必须严格遵循以下循环，不可跳过任何一步：

4.2 执行步骤

步骤	操作	验证
RED	基于 AC 写测试代码，运行，确认全部失败	测试结果红色
GREEN	写最小实现代码，运行，确认测试通过	测试结果绿色
REFACTOR	重构代码（不改行为），运行，确认仍通过	测试结果绿色
循环	重复以上步骤，直到该任务所有 AC 覆盖	所有 AC 有测试
覆盖率	运行覆盖率工具，确认达到门禁	单元 ≥ 90%
提交	提交代码，创建 PR，关联任务	PR 可审查

4.3 测试生成规则（强制执行）

对每个函数/API/页面，测试必须覆盖以下场景：

□ 正常路径 (Happy Path) — 标准输入，预期成功
□ 边界值 (Boundary) — 0、-1、最大值、空字符串、空数组
□ 错误路径 (Error Path) — 网络失败、数据库失败、认证失败
□ 空值输入 (Null/Undefined) — 传 null、undefined、缺失必填字段
□ 非法输入 (Invalid Input) — 超长字符串、非法格式、注入攻击
□ 并发场景 (Concurrency) — 并发写同一资源（如适用）
□ 状态转换 (State Transition) — 非法状态切换（如适用）

4.4 代码规范（强制执行）

□ 代码格式化：提交前自动格式化
□ 静态检查：零告警
□ 类型安全：禁止隐式 any / dynamic
□ 函数长度：≤ 50 行
□ 文件长度：≤ 300 行
□ 公开接口：有文档注释
□ 禁止：console.log、debugger、硬编码密钥

4.5 输出标准

□ 单元测试覆盖率 ≥ 90%
□ 集成测试覆盖所有新增/修改的 API 端点
□ 所有任务 AC 有对应的自动化测试
□ 代码通过静态检查（零告警）
□ 代码通过格式化检查
□ PR 描述完整（关联任务 + 变更说明 + 测试结果截图）

阶段 5: 代码审查

5.1 输入检查

□ PR 已创建，含完整描述
□ CI 自动检查已触发
□ 无合并冲突

5.2 审查流程

步骤	执行者	操作
1. 自动检查	CI 流水线	运行测试、静态分析、安全扫描、构建验证
2. 变更影响分析	审查者	确认变更范围，检查是否有意外副作用
3. 代码审查	审查者	逐条对照审查清单检查
4. 修复	开发者	解决审查意见，推送修复
5. 合并	审查者	确认全部通过后合并

5.3 审查清单（逐条确认）

□ 代码遵循项目规范，静态检查零告警
□ 所有 AC 有对应测试，测试全部通过
□ 测试覆盖 happy path + 边界 + 错误 + 空值 + 非法输入
□ 无调试代码残留（console.log, debugger, print）
□ 无硬编码密钥、密码、Token
□ 异常处理完善（不吞异常，有用户友好的错误信息）
□ 数据库查询无 N+1 问题
□ API 输入有校验，输出有类型定义
□ 变更影响分析已确认，无意外副作用
□ 新增依赖经过评估（许可证、安全、体积）
□ PR 描述与变更内容一致

5.4 质量门禁（CI 自动拦截，不可绕过）

❌ 任一测试未通过 → 禁止合并
❌ 覆盖率下降超过 2% → 禁止合并
❌ 静态检查有告警 → 禁止合并
❌ 安全扫描发现高危漏洞 → 禁止合并
❌ 构建失败 → 禁止合并

阶段 6: 集成测试与回归

6.1 输入检查

□ 代码已合并到主分支
□ 测试环境可用

6.2 执行步骤

步骤	操作	产出
1. 环境准备	启动测试环境（含数据库、缓存、消息队列等依赖）	测试环境就绪
2. 数据准备	执行数据库 Migration，填充测试数据	数据库就绪
3. 单元+集成测试	全量运行，并行执行	测试结果
4. E2E 测试	运行核心用户流程自动化测试	E2E 结果 + 截图
5. 回归测试	运行全量回归套件	回归报告
6. 性能冒烟	运行性能基线检查	性能报告

6.3 输出标准

□ 全量测试通过率 = 100%
□ E2E 核心流程全部通过
□ 无新增不稳定的测试（Flaky Test）
□ 性能指标未退化（与基线对比波动 ≤ 10%）
□ 测试报告归档可查

阶段 7: UAT 用户验收

7.1 输入检查

□ 集成测试阶段全部通过
□ UAT 环境已部署
□ 验收标准清单已就绪
□ 验收人员已就位

7.2 执行步骤

步骤	执行者	操作	产出
1. 自动验收	自动化测试系统	逐条运行验收标准，生成验收报告	自动验收报告
2. 人工验收	业务验收人员	验收关键业务场景	人工验收记录
3. 缺陷处理	开发者	分析失败原因，修复后重新验收	修复记录
4. 签核	业务负责人	确认验收通过	签核记录

7.3 验收通过标准

□ 所有 P0 验收标准 100% 通过
□ 所有 P1 验收标准 ≥ 95% 通过
□ 无阻塞性缺陷（Blocker）
□ 无严重缺陷（Critical）
□ 人工验收确认关键场景无问题
□ 验收报告已签署

阶段 8: 部署与监控

8.1 输入检查

□ UAT 验收已通过并签核
□ 生产环境就绪
□ 回滚方案已准备

8.2 执行步骤

步骤	操作	产出
1. 灰度发布	先 10% 流量 → 观察 30 分钟 → 50% → 观察 → 100%	发布记录
2. 生产冒烟	部署后立即运行核心流程冒烟测试	冒烟报告
3. 监控	观察错误率、延迟、流量等关键指标	监控面板
4. 回滚（如需要）	发现异常立即执行回滚	回滚记录

8.3 输出标准

□ 灰度发布各阶段无异常
□ 生产冒烟测试通过
□ 错误率 < 0.1%
□ API p99 延迟符合 NFR 要求
□ 24 小时内无紧急回滚
□ 部署记录归档

8.4 回滚触发条件（满足任一即回滚）

□ 错误率超过基线的 2 倍
□ p99 延迟超过基线的 2 倍
□ 核心功能不可用
□ 数据一致性问题

附录 A: 阶段门禁总表

阶段	进入条件	通过条件
1. 需求	业务目标 + 用户画像	PRD 完整 + AC 确认
2. 架构	PRD + NFR 量化	架构图 + 数据模型 + API Spec + 原型
3. 拆解	架构文档完整	任务卡片完整 + 排期明确
4. 实现	任务卡片 + AC	测试 ≥ 90% + 代码规范 + CI 通过
5. 审查	PR + CI 通过	审查清单全部确认 + 门禁通过
6. 集成	主分支 + 测试环境	全量通过 + E2E 通过 + 性能达标
7. UAT	集成通过 + UAT 环境	P0 100% + P1 ≥ 95% + 签核
8. 部署	UAT 签核 + 回滚方案	灰度正常 + 监控正常

附录 B: 质量度量指标

指标	目标值	测量频率
单元测试覆盖率	≥ 90%	每次提交
集成测试覆盖率	≥ 80%	每次合并
E2E 核心流程通过率	100%	每次合并
缺陷逃逸率	< 5%	每月统计
不稳定测试比例	< 2%	每周统计
代码审查覆盖率	100% PR	持续
平均故障发现时间	< 1 小时	持续
平均故障修复时间	< 4 小时	持续

附录 C: 文档协作规范

□ 所有设计文档使用 Markdown 格式，存于项目仓库 docs/ 目录
□ PRD → docs/prd.md
□ 架构 → docs/architecture.md
□ API → docs/openapi.yaml
□ ADR → docs/adr/ 目录，按序号命名
□ 迭代计划 → docs/sprints/ 目录
□ 验收报告 → docs/uat/ 目录，按版本命名