导读: 你是否曾经遇到过"需求改了三版,代码还是按第一版写的"的尴尬?是否困惑于"这个API字段是谁定义的,测试用例覆盖了吗"?本文带你深入了解一套完整的14份Spec文档体系,看看它是如何让需求、设计、开发、测试全链路可追溯的。无论你是刚接触Spec Coding的新手,还是想优化团队协作流程的技术Leader,这篇指南都能帮你快速掌握核心要点。
《企业级AI Coding成熟度模型》PDF已开源至GitHub
https://github.com/lvzhaobo/mumu-coding/

痛点一:需求与实现脱节
产品经理: "我想要个优惠券系统"
后端开发: "我理解的是满减券"
前端开发: "我做的是折扣券"
测试工程师: "那我测哪个?"没有统一的规格定义,每个角色按自己的理解干活,最后交付物牛头不对马嘴。
痛点二:变更影响无法评估
老板: "把优惠券领取限制从3张改成5张"
开发: "改一行代码的事"
结果: 改了代码,忘了改测试用例,忘了更新API文档,忘了通知前端痛点三:新人上手成本极高
新同事: "这个接口为什么要返回traceId?"
老员工: "因为三年前出了个bug,后来加上的"
新同事: "那这个字段的业务含义是什么?"
老员工: "你得翻翻两年前的需求文档,哦不对,那文档已经丢了"一句话总结: 用结构化的文档体系,把"口头沟通"变成"可追溯的契约"。
传统模式: 需求 → 口头沟通 → 写代码 → 补文档 → 上线
Spec模式: 需求 → 14份Spec文档 → AI/人工生成代码 → 自动验证 → 上线四大核心原则:



Meta(01-02) → Proposal(03-04) → Spec(05-06-07) → Design(08-09-10-11)
↓ ↓ ↓ ↓
规范+素材 为什么做 做什么 怎么做
↓
Plan(12) → Test(13) → Trace(14)
↓ ↓ ↓
何时做 对不对 全对上没阶段 | 文档编号 | 核心问题 | 一句话定位 | 阅读优先级 |
|---|---|---|---|---|
Meta | 01-02 | 游戏规则是什么? | "元规范+第一手素材" | ⭐⭐ |
Proposal | 03-04 | 为什么做?做什么? | "立项决策+产品定义" | ⭐⭐⭐⭐⭐ |
Spec | 05-06-07 | 用户要什么?长什么样? | "可验证的规格" | ⭐⭐⭐⭐⭐ |
Design | 08-09-10-11 | 怎么实现? | "架构+API+数据+安全" | ⭐⭐⭐⭐ |
Plan | 12 | 何时交付?谁来做? | "里程碑+任务包" | ⭐⭐⭐ |
Test | 13 | 做对了没? | "测试策略+质量门禁" | ⭐⭐⭐⭐ |
Trace | 14 | 全对得上吗? | "四向追溯闭环" | ⭐⭐ |
💡 阅读建议: 第一次阅读按 03→04→05→09→10顺序,先理解"为什么做→做什么→怎么做",其他文档按需查阅。
为什么必读: 这是整个项目的"锚点",回答"为什么做618促销系统"。
核心内容拆解:
章节 | 内容 | 对你的价值 |
|---|---|---|
§1 背景与问题 | 去年618系统崩溃、配置复杂、缺乏监控 | 理解痛点,避免重蹈覆辙 |
§2 提案概要 | 5大核心能力(可视化配置、高并发、实时监控等) | 明确系统边界 |
§3 范围边界 | 做5件事+不做5件事 | 防止范围蔓延 |
§4 成功标准 | 可用性≥99.9%、配置时间≤2小时 | 知道"怎样算做好" |
§5 风险 | 高并发压力、配置错误、数据延迟 | 提前识别坑点 |
检查要点:
典型使用场景:
当你接到一个需求说"能不能顺便加个积分功能",直接翻到§3范围边界,回答:"不在范围内,需要重新立项"。
为什么必读: 把立项提案翻译成"用户视角"的业务故事。
核心内容拆解:
章节 | 内容 | 示例 |
|---|---|---|
§1 愿景与目标 | 03痛点→04目标的映射表 | 系统崩溃→可用性≥99.9% |
§2 目标用户 | 5类角色(运营、审核员、普通用户、客服、管理员) | 明确为谁设计 |
§3 核心业务场景 | 5个场景SC-01~SC-05 | SC-01:运营配置活动全流程 |
§4 产品规则 | 8条规则R-01~R-08 | R-01:仅支持3种优惠券类型 |
§5 能力优先级 | P0~P3分级 | P0:活动配置、优惠券领取、订单优惠计算 |
与03文档的区别:
03 面向决策者: "为什么要做这个项目?"
04 面向产品+开发: "用户怎么用这个系统?"检查要点:
为什么必读: 这是Spec Coding的灵魂文档,把业务叙述翻译成"可验证的规格"。
核心结构: 8个UserStory(US-001~US-008),每个US包含9个字段
US标准字段模板:
| 字段 | 内容示例 |
|----------------|---------------------------------------|
| 需求编号 | REQ-SC618-001 |
| 故事 | 作为运营人员,我希望创建促销活动... |
| 优先级 | P0 |
| 来源 | ← 03 §3 / 04 SC-01 |
| 前置条件 | 运营人员已登录,拥有活动配置权限 |
| 功能对齐 | → 06 §2.1 · 07 §2.1 |
| 设计对齐 | → 08 §3 · 09 POST /api/activities |
| 验证对齐 | → 13 TC-SC618-001 · 14 第1行 |
| 验收标准 | AC-001-01~04 (4条可独立测试的标准) |
8个UserStory全景:
US编号 | 故事名称 | 优先级 | 对应API | 对应TC |
|---|---|---|---|---|
US-001 | 运营创建促销活动 | P0 | POST /api/activities | TC-SC618-001 |
US-002 | 用户领取优惠券 | P0 | POST /api/coupons/{id}/receive | TC-SC618-002 |
US-003 | 订单优惠计算 | P0 | POST /api/orders/calculate | TC-SC618-003 |
US-004 | 审核员审批活动配置 | P0 | PUT /api/activities/{id}/approve | TC-SC618-004 |
US-005 | 实时数据看板 | P1 | GET /api/dashboard | TC-SC618-005 |
US-006 | 优惠券智能推荐 | P1 | POST /api/coupons/recommend | TC-SC618-006 |
US-007 | 权限管理 | P1 | CRUD /api/roles | TC-SC618-007 |
US-008 | 操作日志 | P2 | GET /api/logs | TC-SC618-008 |
验收标准示例(AC必须可独立测试):
❌ 错误写法: "系统应该友好地提示用户"
✅ 正确写法: "当库存不足时,返回400 + error.code=COUPON_OUT_OF_STOCK"
US-002的验收标准:
AC-002-01: 用户可查看可用优惠券列表
AC-002-02: 系统检查领取限制(每人限领3张)
AC-002-03: 库存充足时,优惠券成功发放到用户账户
AC-002-04: 库存不足或已达上限时,提示用户无法领取检查要点:
典型使用场景:
开发写代码前,先看US-003的4条AC,写完直接对照AC自测,不用等产品经理验收。
为什么必读: 这是全部API端点的契约真源,前后端开发、测试断言都以此为准。
核心内容: 18个API端点的完整定义
API端点分类:
活动管理(8个):
POST /activities - 创建活动
GET /activities - 查询列表
GET /activities/{id} - 查询详情
PUT /activities/{id} - 更新配置
DELETE /activities/{id} - 删除活动
PUT /activities/{id}/submit - 提交审核
PUT /activities/{id}/approve - 审批活动
GET /activities/{id}/preview - 预览效果
优惠券(4个):
POST /coupons - 创建优惠券
GET /coupons - 查询列表
POST /coupons/{couponId}/receive - 用户领取
POST /coupons/recommend - 智能推荐
用户优惠券(1个):
GET /users/{userId}/coupons - 查询用户券
订单(1个):
POST /orders/calculate - 计算优惠
数据看板(2个):
GET /dashboard - 获取指标
GET /dashboard/export - 导出数据
权限+日志(2个):
CRUD /roles - 角色管理
GET /logs - 查询日志
每个API的标准定义:
### 3.1 POST /activities — 创建促销活动
**请求体**:
| 字段 | 类型 | 必填 | 约束 | 说明 |
|-------|--------|------|-----------|----------|
| name | string | 是 | 2-100字符 | 活动名称 |
**成功响应**(201):
| 字段 | 类型 | 必有 | 说明 |
|---------|--------|------|----------|
| traceId | string | 是 | 链路ID |
| code | number | 是 | 201 |
| data.id | string | 是 | 活动ID |
**错误响应**(400):
{
"traceId": "tr_abc123",
"code": 400,
"error": {
"code": "INVALID_QUERY",
"message": "活动名称长度必须在2-100字符之间"
}
}统一响应规范:
// 成功响应
{
"traceId":"tr_abc123def456...",
"code":200,
"message":"success",
"data":{}
}
// 错误响应
{
"traceId":"tr_abc123def456...",
"code":400,
"error":{
"code":"ERROR_CODE",
"message":"错误描述",
"details":{}
}
}12个标准错误码:
HTTP | error.code | 触发条件 |
|---|---|---|
400 | EMPTY_QUERY | 请求参数为空 |
400 | INVALID_QUERY | 参数格式错误 |
400 | COUPON_OUT_OF_STOCK | 库存不足 |
400 | COUPON_LIMIT_REACHED | 达到领取上限 |
401 | UNAUTHORIZED | 未登录或token失效 |
403 | FORBIDDEN | 无操作权限 |
404 | COUPON_NOT_FOUND | 优惠券不存在 |
404 | ACTIVITY_NOT_FOUND | 活动不存在 |
409 | ACTIVITY_ALREADY_APPROVED | 活动已审批 |
500 | INTERNAL_ERROR | 系统内部错误 |
502 | UPSTREAM_ERROR | 依赖服务不可用 |
503 | SERVICE_UNAVAILABLE | 服务降级 |
检查要点:
典型使用场景:
前端开发: 看09文档的响应Schema,直接定义TypeScript接口类型,不用猜后端返回什么。
为什么必读: 定义"数据怎么存",是API规格的数据层支撑。
核心内容: 5张核心表的完整定义
概念模型(ER关系):
Activity (活动) 1 ── * Coupon (优惠券)
│ │
│ id (PK) │ id (PK)
│ name │ activity_id (FK → Activity)
│ start_time │ name
│ end_time │ type
│ status │ discount_value
│ type │ total_stock
│ │ remaining_stock
│ └ limit_per_user
│
▼
UserCoupon (用户优惠券) * ── 1 User (用户)
│ │
│ id (PK) │ id (PK)
│ user_id (FK → User) │ level
│ coupon_id (FK → Coupon)
│ status
│ receive_time
│ expire_time
└ used_time核心表结构示例(Activity表):
| 字段 | 类型 | 必填 | 约束 | 说明 |
|---------------------------|-------------------|------|-------------|----------|
| id | BIGINT | 是 | PK, AUTO | 活动ID |
| name | VARCHAR(100) | 是 | NOT NULL | 活动名称 |
| start_time | DATETIME | 是 | NOT NULL | 开始时间 |
| end_time | DATETIME | 是 | NOT NULL | 结束时间 |
| type | VARCHAR(20) | 是 | ENUM | 活动类型 |
| status | VARCHAR(20) | 是 | ENUM | 状态 |
| full_reduction_threshold | DECIMAL(10,2) | 否 | >=0 | 满减阈值 |
| created_at | DATETIME | 是 | DEFAULT NOW | 创建时间 |5张核心表:
Storage方法清单(直接映射代码):
// Activity管理
Activity createActivity(Activity entity)
Activity getActivityById(Long id)
Page<Activity> getActivityList(Pageable pageable, String status, String keyword)
Activity updateActivity(Long id, Activity entity)
voiddeleteActivity(Long id)
Activity submitForApproval(Long id, String operator)
Activity approveActivity(Long id, Boolean approved, String remark, String operator)
// Coupon管理
Coupon createCoupon(Coupon entity)
Boolean decreaseStock(Long couponId)// 乐观锁扣减
Boolean increaseStock(Long couponId)
// UserCoupon管理
UserCoupon createUserCoupon(UserCoupon entity)
Integer getUserCouponCount(Long userId, Long couponId)// 检查领取上限
Boolean useUserCoupon(Long id, Long orderId)检查要点:
定位: 把05的UserStory翻译成"界面/交互行为规格"
核心内容:
§1 总体布局/界面结构
- 运营后台布局(header+导航+主内容区)
- 用户前端布局(活动横幅+优惠券区+商品区)
§2 活动配置管理
- 7个功能(查看列表、创建、编辑、预览、提交审核、审批、删除)
- 每个功能: 触发方式 + 调用接口 + 行为描述
§3 优惠券管理
- 5种状态(A可领取、B已领取、C已使用、D已过期、E已抢光)
- 3种类型(FULL_REDUCTION/DISCOUNT/FREE_SHIPPING)
- 用户领取流程图
§4 订单结算
- 优惠计算规则: 应付金额 = 商品金额 - 满减金额 - 优惠券金额
- 满减计算: floor(商品金额 / 满减阈值) × 满减金额
§5 实时数据看板
- 5个指标(订单量、销售额、转化率、优惠券使用率、平均客单价)
§6 用户输入区域
- 活动配置表单(7个输入元素)
- 优惠券配置表单(7个输入元素)
§7 错误处理与用户反馈
- 8个后端错误码 → 前端展示映射
§8 状态管理(前端)
- 8个State变量(activities、coupons、isLoading等)前端开发检查清单:
定位: 定义"不能怎么做、底线在哪里"
核心内容:
§1 性能需求
- 延迟SLO: 优惠券领取<200ms、订单计算<300ms、看板<500ms
- 降级策略: 4级降级(限流→缓存→只读→静态页面)
- 容量规划: 峰值QPS 50000、并发用户100000
§2 可用性需求
- 服务可用性: 99.9%
- MTTR: <5分钟
- 故障模式: 单点故障、数据库故障、网络分区
§3 可观测性需求
- 链路追踪: traceId格式、注入位置、采样率100%
- 错误码体系: 12个标准错误码
- 日志规范: DEBUG/INFO/WARN/ERROR/FATAL
§4 安全需求
- API认证: JWT Token
- 速率限制: 领取5次/分钟、下单10次/分钟
- 防刷机制: Redis计数+验证码
- 敏感数据保护: 密码BCrypt、手机号脱敏
§5 数据约束
- 输入约束: 活动名称2-100字符、满减阈值>=1
- 类型约束: Enum定义、Decimal精度
§6 兼容性需求
- Java 1.8、Spring Boot 2.7.18、Vue.js 3.2.x等
§7 运维需求
- 监控指标: CPU<80%、内存<85%、磁盘<90%
- 部署要求: Docker+K8s、滚动更新、健康检查架构师检查清单:
定位: 描述"系统怎么组织、为什么这样组织"
核心内容:
§1 架构总览
- 系统上下文图(前端→后端→数据库/Redis/RocketMQ)
- 架构风格: 前后端分离、单体应用、分层架构、事件驱动
§2 后端分层结构
- Controller: 参数校验、HTTP处理
- Service: 业务逻辑编排、事务管理
- Repository: 数据CRUD
- Entity/DTO/VO: 数据映射
§3 前端架构
- Vue.js 3.x + Vite + Pinia + Axios + Element Plus
§4 外部服务集成
- MySQL: 连接池健康检查、自动重连
- Redis: ping检测、降级到数据库
- RocketMQ: 心跳检测、消息持久化
§5 数据存储架构
- 缓存策略: 活动配置5分钟、优惠券3分钟、用户券1分钟
- 存储演进: P0单库→P1主从→P2分库分表
§6 部署架构
- docker-compose配置
§7 ADR架构决策记录
- ADR-001: 为什么选Spring Boot 2.7.18
- ADR-002: 为什么选MySQL 8.0
- ADR-003: 为什么选Redis
- ADR-004: 为什么选RocketMQ
- ADR-005: 为什么用单体而非微服务
§8 安全架构
- 认证: JWT→OAuth2.0
- 密钥: 配置文件→Vault/KMS架构决策检查清单:
定位: 认证、授权、数据安全、审计日志
核心内容:
§1 安全目标
- 数据完整性、身份认证、最小权限、审计追踪、防攻击
§2 认证与授权
- JWT Token: Access 2小时、Refresh 7天
- 角色权限矩阵: 5类角色×8种操作
- 权限粒度: 8个权限(activity:create、coupon:receive等)
§3 数据安全
- 数据分级: 机密/内部/一般
- 加密策略: TLS 1.2+、AES-256、BCrypt、SSL
- 敏感数据保护: 手机号脱敏138****8888
§4 接口安全
- 输入校验、SQL注入防护、XSS防护、CSRF防护
- 速率限制: 领取5次/分钟、下单10次/分钟
- 防刷机制: Redis计数+验证码
§5 外部服务安全
- 消息队列访问控制、Redis内网访问、数据库最小权限
§6 部署安全
- 环境隔离、密钥环境变量、依赖安全扫描
§7 安全审计
- 4类日志: 操作日志、登录日志、访问日志、异常日志
- 安全告警: 多次登录失败、异常访问、权限越权
§8 应急响应
- 系统入侵、数据泄露、DDoS攻击、服务故障安全检查清单:
定位: 分层测试策略+28条TC+质量门禁
核心内容:
§一 测试分层(4层)
L1 Unit: JUnit 5 + Mockito — 单个函数逻辑
L2 Integration: Spring Test + MockMvc — API端点
L3 Contract: Pact — 响应体结构
L4 E2E: Playwright — 完整用户旅程
§二 用例拆分原则
- 正常路径: 每个happy path = 1条TC
- 错误码: 每个distinct error code = 1条TC
- 分支路径: 每个if/else降级分支 = 1条TC
- 类型约束: 每个字段类型 = 1条TC
§三 测试用例(28条TC)
3.1 活动管理(8条TC-001~008)
3.2 优惠券(6条TC-009~014)
3.3 订单优惠计算(5条TC-015~019)
3.4 数据看板(2条TC-020~021)
3.5 权限管理(3条TC-022~024)
3.6 Storage层(4条TC-025~028)
§四 质量门禁(6个Gate)
G-LINT: mvn checkstyle:check通过 — 阻塞合并
G-UNIT: 覆盖率≥80% — 阻塞合并
G-INT: Integration全绿 — 阻塞合并
G-AC: P0验收标准100%覆盖 — 阻塞合并
G-PERF: P95响应<500ms — warning
G-SEC: 安全扫描无高危 — 阻塞合并
§五 TDD适用场景
- 简单CRUD: 低价值,写完补测试
- 参数校验: 中价值,建议TDD
- 多级降级/状态机: 高价值,强烈建议TDD
- 复杂业务计算: 极高价值,必须TDD
§六 追溯关系
- REQ→TC映射表测试用例示例:
| TC-ID | 层级 | 断言要点 | 关联REQ | 优先级 |
|---------------|--------------|---------------------------------------------|------------------|--------|
| TC-SC618-001 | Integration | POST /api/activities → 201,返回活动ID | REQ-SC618-001 | P0 |
| TC-SC618-011 | Integration | POST /api/coupons/{id}/receive → 400 库存不足 | REQ-SC618-006 | P0 |
| TC-SC618-018 | Unit | 满300减50,订单350 → 优惠50 | REQ-SC618-007 | P0 |测试检查清单:
定位: 14份文档的"操作系统",定义写作规范
核心内容:
§1 编号与阶段对照(01~14)
§2 基本原则(5条):
- 单一真相: 对外行为以09 API与10数据模型为准
- 先行为后实现: 先写05用户故事,再写06/09/10
- 可验证: 所有MUST条目必须能被测试验证
- 不混层: PRD不写SQL,API不写像素
- 无歧义: 禁止"可选其一/建议/大概/尽量"
§3 规范词(RFC风格)
MUST: 必须,违反即缺陷
SHOULD: 建议,不满足需说明理由
MAY: 可选,不影响基线验收
MUST NOT: 严禁
§4 统一编号规范
需求: REQ-{模块号}-{NNN} 示例: REQ-SC618-001
用户故事: US-{NNN} 示例: US-001
验收标准: AC-{US编号}-{NN} 示例: AC-001-01
测试用例: TC-{模块号}-{NNN} 示例: TC-SC618-001
规则约束: RULE-{NNN} 示例: RULE-001
§5 质量门禁(文档侧)
- 05每条P0 US在14有映射
- 14每条REQ在13存在至少1个TC
- 09有示例请求/响应/错误体
- 10有索引与约束说明定位: 第一手需求素材,追溯的真正起点
核心内容:
S-01 会议纪要(618促销规划会议)
- 4个痛点: 系统崩溃、配置复杂、缺乏监控、优惠券规则复杂
- 5个需求: 活动配置、高可用、实时监控、优惠券优化、订单分流
S-02 邮件沟通(3封邮件)
- 邮件一: 优惠券类型简化、智能推荐、领取限制
- 邮件二: 角色分级、审批流程、操作日志
- 邮件三: FAQ自动回复、订单查询、一键补发
S-03 用户访谈(4个访谈)
- 资深用户: 智能推荐最优优惠
- 新用户: 清晰的活动指引
- 运营人员: 自主配置系统
- 客服人员: 自助查询支持
需求汇总(15个REQ)
- P0(2个): 活动配置、高可用
- P1(5个): 实时监控、优惠券优化、订单分流等
- P2(7个): 领取限制、角色分级、审批流程等
- P3(1个): 一键补发优惠券使用场景:
当你质疑"这个需求是哪来的?",翻到02文档,找到原始出处(谁、何时、什么场景提出的)。
定位: 把Spec变成可排期、可追责的任务包
核心内容:
§1 里程碑(S1~S4)
S1 基础能力(5.16-5.20): 活动管理、优惠券基础
S2 核心业务(5.21-5.27): 优惠券领取、订单计算、智能推荐
S3 审批与数据(5.28-6.3): 审批流程、数据看板、权限管理
S4 收口优化(6.4-6.10): 操作日志、性能优化、上线准备
§2 WBS任务拆分(12个W1~W12)
W1: 后端服务搭建
W2: 活动管理模块
W3: 优惠券模块
...
W12: 测试与上线
§3 S×W对应矩阵
- ● 主要推进 ○ 少量涉及 — 不涉及
§4 依赖与风险
- 依赖链: S1→S2→S3→S4
- 6个风险: 库存超卖、高并发、数据一致性等
- 资源需求: 后端2人、前端2人、测试1人、运维1人、产品1人项目经理检查清单:
定位: REQ ↔ API ↔ TC 的四向追溯
核心内容:
§1 需求编号体系
- REQ-{模块号}-{NNN}: 功能需求
- RULE-{NNN}: 数据/类型约束规则
§2 需求定义表(10条)
- 7个功能需求(REQ-SC618-001~011)
- 3个规则约束(RULE-001~003)
§3 正向追溯矩阵(需求→US→API→TC)
REQ-SC618-001 → US-001 → POST/GET/PUT/DELETE /activities → TC-001~005 ✅
REQ-SC618-011 → US-008 → GET /api/logs → ❌ 待补
§4 反向追溯矩阵(TC→需求)
TC-001 → REQ-SC618-001, RULE-001
TC-011 → REQ-SC618-006
§5 API端点→TC映射(15个端点)
- 14个已覆盖(93%)
- 1个待补: GET /api/logs
§6 覆盖率分析
- API端点: 14/15 = 93%
- REQ需求: 9/10 = 90%
- TC测试用例: 28/30 = 93%
关键风险:
- 操作日志功能无测试(中严重度)使用场景:
变更需求时,沿正向链路定位受影响的API和TC;测试失败时,沿反向链路定位哪条需求受影响。
Meta阶段(01-02):
Proposal阶段(03-04):
Spec阶段(05-06-07):
Design阶段(08-09-10-11):
Plan阶段(12):
Test阶段(13):
Trace阶段(14):
1. 作者自检
↓ (按6.1检查清单)
2. 同行评审(Peer Review)
↓ (至少1人,关注"是否能看懂")
3. 跨角色评审
↓ (产品+开发+测试联合评审,关注"是否一致")
4. 冻结(Freeze)
↓ (签字确认,后续变更走变更流程)
5. 持续维护
↓ (每个PR更新对应文档行)变更流程:
05(行为变更) → 09/10(契约变更) → 13/14(验证追踪变更)变更记录示例:
| 版本 | 日期 | 说明 | 变更人 |
|------|------------|-------------------------------|---------|
| v1.0 | 2026-05-15 | 首版填写 | 李产品 |
| v1.1 | 2026-05-20 | US-003增加AC-003-05(叠加规则) | 陈开发 |
| v2.0 | 2026-05-25 | API字段name→activity_name | 陈开发 |主要使用: 03、04、05、12、14
工作流:
1. 收集需求 → 写入02
2. 立项提案 → 撰写03(Why+Scope)
3. 产品定义 → 撰写04(角色+场景+规则)
4. 需求拆分 → 撰写05(UserStory+AC)
5. 排期计划 → 参与12(WBS认领)
6. 验收 → 对照05的AC逐项验证
7. 追溯 → 查看14确认覆盖率主要使用: 05、07、08、09、10、13
工作流:
1. 理解需求 → 阅读05(UserStory)
2. 查看约束 → 阅读07(NFR:性能/安全)
3. 架构设计 → 阅读08(分层+ADR)
4. API定义 → 阅读09(端点+Schema)
5. 数据建模 → 阅读10(表结构+Storage方法)
6. 编码 → 按09+10生成代码
7. 自测 → 对照13的TC用例主要使用: 05、06、09、13
工作流:
1. 理解用户故事 → 阅读05
2. 查看交互规格 → 阅读06(布局+表单+错误处理)
3. 查看API契约 → 阅读09(请求/响应Schema)
4. 编码 → 按06+09开发
5. 联调 → 对照09的响应示例
6. 自测 → 对照13的E2E用例主要使用: 05、09、13、14
工作流:
1. 理解验收标准 → 阅读05(AC)
2. 查看API契约 → 阅读09(端点+错误码)
3. 编写测试用例 → 撰写13(TC清单)
4. AC→TC映射 → 确认每条AC至少1条TC
5. 执行测试 → L1→L2→L3→L4分层执行
6. 质量门禁 → 检查6个Gate
7. 追溯 → 更新14的覆盖率主要使用: 01、07、08、11、12、14
工作流:
1. 规范制定 → 维护01(写作总则)
2. 架构决策 → 主导08(ADR记录)
3. 非功能约束 → 审核07(SLO/降级)
4. 安全设计 → 审核11(权限矩阵)
5. 计划排期 → 主导12(里程碑+WBS)
6. 追溯审计 → 查看14(覆盖率风险)
7. 评审把关 → 各阶段冻结签字Step 1: 产品写需求
→ 05 US-002: 作为普通用户,我希望领取优惠券...
→ AC-002-01~04: 4条验收标准
Step 2: 开发看规格
→ 09 POST /api/coupons/{couponId}/receive
→ 请求体: {userId}, 响应体: {userCouponId}
→ 错误码: COUPON_OUT_OF_STOCK, COUPON_LIMIT_REACHED
Step 3: 开发看数据
→ 10 Coupon表: total_stock, remaining_stock, limit_per_user
→ 10 UserCoupon表: user_id, coupon_id, status, receive_time
→ Storage方法: createUserCoupon(), getUserCouponCount(), decreaseStock()
Step 4: 开发写代码
→ 按09的Schema定义DTO
→ 按10的Storage方法写Repository
→ 按05的AC写业务逻辑
Step 5: 测试验证
→ 13 TC-SC618-009: 正常领取 → 201
→ 13 TC-SC618-011: 库存不足 → 400 COUPON_OUT_OF_STOCK
→ 13 TC-SC618-012: 达到上限 → 400 COUPON_LIMIT_REACHED
Step 6: 追溯确认
→ 14 正向: REQ-SC618-006 → US-002 → POST /api/coupons/receive → TC-009~012 ✅
→ 14 反向: TC-011 → REQ-SC618-006 ✅Step 1: 产品更新需求
→ 修改05 US-002的AC-002-02: "每人限领5张"(原3张)
→ 修改04 §4 R-02: "每人限领5张"(原3张)
Step 2: 开发更新契约
→ 修改09 §8参数校验规则: limitPerUser <= 5(原3)
→ 修改10 Coupon表注释: limit_per_user最大值改为5
Step 3: 测试更新用例
→ 修改13 TC-SC618-012: 领取第6张时拒绝(原第4张)
Step 4: 更新追溯
→ 修改14正向追溯矩阵: 确认AC→TC映射仍然完整
Step 5: 评审+冻结
→ 产品+开发+测试三方评审
→ 确认无遗漏后,三个文档同步升级版本Step 1: 定位受影响的需求
→ 14反向追溯: TC-011(库存不足拒绝) → REQ-SC618-006
Step 2: 查看原始规格
→ 05 US-002 AC-002-03: "库存充足时,优惠券成功发放"
→ 09 POST /api/coupons/{couponId}/receive: 应检查remaining_stock
Step 3: 查看数据模型
→ 10 Coupon表: remaining_stock字段,乐观锁控制
Step 4: 查看测试用例
→ 13 TC-SC618-011: POST /api/coupons/{id}/receive → 400 COUPON_OUT_OF_STOCK
Step 5: 定位代码问题
→ 检查decreaseStock()方法: 是否正确使用乐观锁?
→ 检查并发场景: 是否有并发扣减未加锁?
Step 6: 修复+回归
→ 修复代码
→ 重跑TC-011
→ 增加并发测试用例法则1: 先薄后厚,快速冻结
❌ 错误: 一次性把01-14全部写完再评审
✅ 正确: 先写03→04→05核心,冻结后启动开发,其他文档并行补充法则2: 单一真相,禁止重复
❌ 错误: API字段名在09叫activityName,在10叫activity_name
✅ 正确: 09定义字段名,10严格对齐,其他文档只引用法则3: AC必须可观察
❌ 错误: "系统应该流畅运行"
✅ 正确: "P95响应时间<200ms,通过Prometheus监控验证"法则4: 门禁要"硬"
❌ 错误: "覆盖率80%以上最好,达不到也可以merge"
✅ 正确: "覆盖率<80%不允许merge,没有例外"法则5: RTM持续维护
❌ 错误: 上线前一次性填满14文档
✅ 正确: 每个PR更新对应行,RTM始终反映真实状态误区1: 把"初步方案"写进02
❌ 02需求采集: "建议用Redis做缓存"
✅ 02只收集痛点,方案交给08 Design阶段误区2: Proposal阶段写"实现方案"
❌ 03立项提案: "使用Spring Cloud微服务架构"
✅ 03只谈Why和What,How交给08 Design误区3: AC写成"感受"而非"规格"
❌ AC: "用户应该觉得优惠券很好用"
✅ AC: "当用户有3张可用券时,系统推荐优惠力度最大的,显示节省金额"误区4: API文档写大白话
❌ 09: "返回订单信息"
✅ 09: "返回{orderId: string, total: number, items: array}, 200"误区5: 把RTM当"应付检查"
❌ 上线前突击填14文档
✅ 每个PR更新对应行,持续维护14份文档 = 7个阶段 = 1个完整追溯链路
Meta(01-02): 游戏规则 + 原始素材
Proposal(03-04): Why + What(业务层)
Spec(05-06-07): What(规格层) ← 核心
Design(08-09-10-11): How ← AI Coding关键上下文
Plan(12): When + Who
Test(13): OK?
Trace(14): All linked?阅读优先级:
必读(P0): 03 → 04 → 05 → 09 → 10
按需(P1): 06 → 07 → 08 → 11 → 13
管理(P2): 01 → 02 → 12 → 14检查核心:
03: "不做"清单 + 成功标准可度量
05: AC可观察 + Given-When-Then格式
09: 请求/响应Schema完整 + 错误码齐全
10: 字段类型/约束/说明完整
13: AC→TC映射100% + 质量门禁"硬"
14: 覆盖率≥90% + 持续维护如果你是新手:
如果你是技术Leader:
如果你想引入AI Coding:
这套14份Spec文档体系,不是一开始就设计出来的,而是在多个促销项目(春节促销、周年庆活动等)的复盘中逐步沉淀的。它的核心价值不在于"文档多全",而在于**"让每个角色都能在自己的视角看到完整的故事,并且能追溯到上下游的每一个环节"**。
希望这篇指南能帮你快速上手,如果有疑问,欢迎在评论区交流!
附录:快速查阅表
我想知道... | 查看文档 | 章节 |
|---|---|---|
为什么要做这个项目? | 03 | §1 背景与问题 |
系统边界是什么? | 03 | §3 范围边界 |
目标用户是谁? | 04 | §2 目标用户 |
核心场景有哪些? | 04 | §3 核心业务场景 |
用户故事怎么写的? | 05 | US-001~008 |
API有哪些端点? | 09 | §1 端点总览 |
数据库表结构? | 10 | §3~§7 实体定义 |
性能指标是什么? | 07 | §1 性能需求 |
安全怎么做? | 11 | §2 认证与授权 |
测试用例有哪些? | 13 | §三 测试用例 |
需求覆盖率多少? | 14 | §6 覆盖率分析 |
项目排期? | 12 | §1 里程碑 |
写作规范? | 01 | §2 基本原则 |
说明:本文基于618促销活动系统的14份Spec文档编写,所有数据、示例均来自示例项目文档。