夜雨聆风AI开发中大型项目开发 SOP（标准作业程序）
版本: v2.0
适用: Web 应用、API 服务、AI Agent 项目
核心理念: 规格驱动 × TDD × 质量门禁
本 SOP 不绑定任何具体工具，任何执行者（人或 Agent）均须遵守。
总则
执行原则
- 每一阶段有明确的输入检查
—— 材料不齐，不得开工 - 每一阶段有明确的产出标准
—— 产出未达标，不得进入下一阶段 - 每一个产出有对应的验收方式
—— 不可验收 = 不可交付 - 质量门禁是硬约束
—— 不通过的代码不得合并
阶段总览
阶段 1: 需求分析与规格定义
1.1 输入检查清单
进入本阶段前，必须确认以下材料齐全：
□ 业务目标陈述（一句话：谁、解决什么问题、核心价值是什么）
□ 目标用户画像（至少 2 个角色，含角色的目标与痛点）
□ 竞品参考（至少 1 个竞品的主要功能对比）
□ 非功能需求草案（性能、安全、合规、可访问性的初步期望）
□ 遗留系统约束（如有，列出不可改的部分）
1.2 执行步骤
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 执行步骤
2.3 输出标准
□ 系统架构图：组件、数据流向、外部依赖标注清楚
□ 数据模型：所有实体、字段类型、约束、索引完整定义
□ API 规格：OpenAPI 3.0 格式，含所有端点的请求/响应 Schema
□ 技术选型决策表：候选方案 + 对比维度 + 最终选择 + 理由
□ ADR：关键决策记录（至少 1 条）
□ 原型代码可运行，核心链路走通
2.4 架构产出格式规范
技术选型决策表:
阶段 3: 任务拆解与排期
3.1 输入检查
□ PRD 完整
□ 架构设计文档完整
□ API 规格文件完成
□ 技术选型已确认
3.2 执行步骤
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 执行步骤
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 审查流程
5.3 审查清单（逐条确认）
□ 代码遵循项目规范，静态检查零告警
□ 所有 AC 有对应测试，测试全部通过
□ 测试覆盖 happy path + 边界 + 错误 + 空值 + 非法输入
□ 无调试代码残留（console.log, debugger, print）
□ 无硬编码密钥、密码、Token
□ 异常处理完善（不吞异常，有用户友好的错误信息）
□ 数据库查询无 N+1 问题
□ API 输入有校验，输出有类型定义
□ 变更影响分析已确认，无意外副作用
□ 新增依赖经过评估（许可证、安全、体积）
□ PR 描述与变更内容一致
5.4 质量门禁（CI 自动拦截，不可绕过）
❌ 任一测试未通过 → 禁止合并
❌ 覆盖率下降超过 2% → 禁止合并
❌ 静态检查有告警 → 禁止合并
❌ 安全扫描发现高危漏洞 → 禁止合并
❌ 构建失败 → 禁止合并
阶段 6: 集成测试与回归
6.1 输入检查
□ 代码已合并到主分支
□ 测试环境可用
6.2 执行步骤
6.3 输出标准
□ 全量测试通过率 = 100%
□ E2E 核心流程全部通过
□ 无新增不稳定的测试（Flaky Test）
□ 性能指标未退化（与基线对比波动 ≤ 10%）
□ 测试报告归档可查
阶段 7: UAT 用户验收
7.1 输入检查
□ 集成测试阶段全部通过
□ UAT 环境已部署
□ 验收标准清单已就绪
□ 验收人员已就位
7.2 执行步骤
7.3 验收通过标准
□ 所有 P0 验收标准 100% 通过
□ 所有 P1 验收标准 ≥ 95% 通过
□ 无阻塞性缺陷（Blocker）
□ 无严重缺陷（Critical）
□ 人工验收确认关键场景无问题
□ 验收报告已签署
阶段 8: 部署与监控
8.1 输入检查
□ UAT 验收已通过并签核
□ 生产环境就绪
□ 回滚方案已准备
8.2 执行步骤
8.3 输出标准
□ 灰度发布各阶段无异常
□ 生产冒烟测试通过
□ 错误率 < 0.1%
□ API p99 延迟符合 NFR 要求
□ 24 小时内无紧急回滚
□ 部署记录归档
8.4 回滚触发条件（满足任一即回滚）
□ 错误率超过基线的 2 倍
□ p99 延迟超过基线的 2 倍
□ 核心功能不可用
□ 数据一致性问题
附录 A: 阶段门禁总表
附录 B: 质量度量指标
附录 C: 文档协作规范
□ 所有设计文档使用 Markdown 格式，存于项目仓库 docs/ 目录
□ PRD → docs/prd.md
□ 架构 → docs/architecture.md
□ API → docs/openapi.yaml
□ ADR → docs/adr/ 目录，按序号命名
□ 迭代计划 → docs/sprints/ 目录
□ 验收报告 → docs/uat/ 目录，按版本命名
