首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >企业级AI Coding | 以618促销为例的14份Spec模板

企业级AI Coding | 以618促销为例的14份Spec模板

作者头像
用户5602664
发布2026-05-20 13:32:56
发布2026-05-20 13:32:56
1590
举报

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

《企业级AI Coding成熟度模型》PDF已开源至GitHub

https://github.com/lvzhaobo/mumu-coding/

📖 一、为什么需要14份Spec文档?传统开发的痛点与破局

1.1 传统开发模式的三大痛点

痛点一:需求与实现脱节

代码语言:javascript
复制
产品经理: "我想要个优惠券系统"
后端开发: "我理解的是满减券"  
前端开发: "我做的是折扣券"
测试工程师: "那我测哪个?"

没有统一的规格定义,每个角色按自己的理解干活,最后交付物牛头不对马嘴。

痛点二:变更影响无法评估

代码语言:javascript
复制
老板: "把优惠券领取限制从3张改成5张"
开发: "改一行代码的事"
结果: 改了代码,忘了改测试用例,忘了更新API文档,忘了通知前端

痛点三:新人上手成本极高

代码语言:javascript
复制
新同事: "这个接口为什么要返回traceId?"
老员工: "因为三年前出了个bug,后来加上的"
新同事: "那这个字段的业务含义是什么?"
老员工: "你得翻翻两年前的需求文档,哦不对,那文档已经丢了"

1.2 Spec Coding的核心理念

一句话总结: 用结构化的文档体系,把"口头沟通"变成"可追溯的契约"。

代码语言:javascript
复制
传统模式: 需求 → 口头沟通 → 写代码 → 补文档 → 上线
Spec模式: 需求 → 14份Spec文档 → AI/人工生成代码 → 自动验证 → 上线

四大核心原则:

  1. 1. 可验证: 每条需求都有可测试的验收标准
  2. 2. 可复用: 新人读Spec就能上手,不用问人
  3. 3. 可治理: 一个阶段没冻结,下一个阶段不启动
  4. 4. AI友好: 给足结构化上下文,AI生成质量稳定

🗂️ 二、14份文档全景图:7个阶段的流转逻辑

2.1 七阶段流程一览

代码语言:javascript
复制
Meta(01-02) → Proposal(03-04) → Spec(05-06-07) → Design(08-09-10-11) 
  ↓              ↓                  ↓                  ↓
 规范+素材      为什么做            做什么              怎么做
                                                ↓
                                        Plan(12) → Test(13) → Trace(14)
                                          ↓         ↓          ↓
                                        何时做      对不对      全对上没

2.2 每个阶段回答的核心问题

阶段

文档编号

核心问题

一句话定位

阅读优先级

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顺序,先理解"为什么做→做什么→怎么做",其他文档按需查阅。

🎯 三、必读核心文档(P0):开发者的第一优先级

3.1 📄 03-立项提案与范围说明(Proposal核心)

为什么必读: 这是整个项目的"锚点",回答"为什么做618促销系统"。

核心内容拆解:

章节

内容

对你的价值

§1 背景与问题

去年618系统崩溃、配置复杂、缺乏监控

理解痛点,避免重蹈覆辙

§2 提案概要

5大核心能力(可视化配置、高并发、实时监控等)

明确系统边界

§3 范围边界

做5件事+不做5件事

防止范围蔓延

§4 成功标准

可用性≥99.9%、配置时间≤2小时

知道"怎样算做好"

§5 风险

高并发压力、配置错误、数据延迟

提前识别坑点

检查要点:

  • ✅ "不做"清单是否明确?本文列出了5项:支付系统改造、财务结算、第三方平台对接、库存系统重构、会员积分系统
  • ✅ 成功标准是否可度量?本文全部是量化指标:99.9%、2小时、5秒延迟

典型使用场景:

当你接到一个需求说"能不能顺便加个积分功能",直接翻到§3范围边界,回答:"不在范围内,需要重新立项"。

3.2 📄 04-产品需求说明PRD(业务叙述)

为什么必读: 把立项提案翻译成"用户视角"的业务故事。

核心内容拆解:

章节

内容

示例

§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文档的区别:

代码语言:javascript
复制
03 面向决策者: "为什么要做这个项目?"
04 面向产品+开发: "用户怎么用这个系统?"

检查要点:

  • ✅ 场景是否覆盖所有目标用户?本文5个场景覆盖了运营、用户、客服
  • ✅ 规则是否有来源追溯?每条规则都标注了来源(邮件沟通、用户访谈等)

3.3 📄 05-用户故事与验收标准(Spec Coding核心⭐⭐⭐)

为什么必读: 这是Spec Coding的灵魂文档,把业务叙述翻译成"可验证的规格"。

核心结构: 8个UserStory(US-001~US-008),每个US包含9个字段

US标准字段模板:

代码语言:javascript
复制
| 字段           | 内容示例                              |
|----------------|---------------------------------------|
| 需求编号       | 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必须可独立测试):

代码语言:javascript
复制
❌ 错误写法: "系统应该友好地提示用户"
✅ 正确写法: "当库存不足时,返回400 + error.code=COUPON_OUT_OF_STOCK"

US-002的验收标准:
AC-002-01: 用户可查看可用优惠券列表
AC-002-02: 系统检查领取限制(每人限领3张)
AC-002-03: 库存充足时,优惠券成功发放到用户账户
AC-002-04: 库存不足或已达上限时,提示用户无法领取

检查要点:

  • ✅ 每条AC是否可观察?能否通过接口响应、日志、UI状态验证?
  • ✅ 是否使用Given-When-Then格式?
  • ✅ 每条AC是否在13文档有对应TC?

典型使用场景:

开发写代码前,先看US-003的4条AC,写完直接对照AC自测,不用等产品经理验收。

3.4 📄 09-API接口规格(契约真源⭐⭐⭐)

为什么必读: 这是全部API端点的契约真源,前后端开发、测试断言都以此为准。

核心内容: 18个API端点的完整定义

API端点分类:

代码语言:javascript
复制
活动管理(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的标准定义:

代码语言:javascript
复制
### 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字符之间"
  }
}

统一响应规范:

代码语言:javascript
复制
// 成功响应
{
"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

服务降级

检查要点:

  • ✅ 每个端点是否有请求体/响应体Schema?
  • ✅ 字段名是否与10文档的数据库字段对齐?
  • ✅ 是否包含成功+错误两种响应示例?
  • ✅ 参数校验规则是否在§8汇总?

典型使用场景:

前端开发: 看09文档的响应Schema,直接定义TypeScript接口类型,不用猜后端返回什么。

3.5 📄 10-数据模型与存储规格(数据真相)

为什么必读: 定义"数据怎么存",是API规格的数据层支撑。

核心内容: 5张核心表的完整定义

概念模型(ER关系):

代码语言:javascript
复制
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表):

代码语言:javascript
复制
| 字段                      | 类型              | 必填 | 约束        | 说明     |
|---------------------------|-------------------|------|-------------|----------|
| 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张核心表:

  1. 1. Activity: 活动主表(14个字段)
  2. 2. Coupon: 优惠券表(12个字段)
  3. 3. UserCoupon: 用户优惠券表(9个字段)
  4. 4. OperationLog: 操作日志表(9个字段)
  5. 5. Role: 角色表(6个字段)

Storage方法清单(直接映射代码):

代码语言:javascript
复制
// 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)

检查要点:

  • ✅ 每个字段是否有类型、约束、说明?
  • ✅ 外键关系是否清晰?
  • ✅ 索引设计是否在§3说明?
  • ✅ 乐观锁/并发控制策略是否明确?

🔧 四、按需查阅文档(P1):特定角色的必读清单

4.1 🎨 06-功能规格说明FSD(前端/交互必看)

定位: 把05的UserStory翻译成"界面/交互行为规格"

核心内容:

代码语言:javascript
复制
§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等)

前端开发检查清单:

  • ✅ 每个按钮的触发方式是否明确?
  • ✅ 表单校验规则是否与09 API的约束一致?
  • ✅ 错误码展示是否统一?
  • ✅ 状态变量是否覆盖所有场景?

4.2 🏗️ 07-非功能需求与约束NFR(架构师必看)

定位: 定义"不能怎么做、底线在哪里"

核心内容:

代码语言:javascript
复制
§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、滚动更新、健康检查

架构师检查清单:

  • ✅ 降级策略是否按顺序执行?
  • ✅ SLO指标是否可监控?
  • ✅ 限流阈值是否经过压测验证?
  • ✅ 敏感数据是否全链路加密?

4.3 🏛️ 08-系统架构与技术选型(技术Leader必看)

定位: 描述"系统怎么组织、为什么这样组织"

核心内容:

代码语言:javascript
复制
§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

架构决策检查清单:

  • ✅ 每个技术选型是否有"核心理由"?
  • ✅ ADR是否记录了"当时为什么不选B方案"?
  • ✅ 分层边界是否清晰(禁止跨层调用)?
  • ✅ 降级方案是否经过演练?

4.4 🛡️ 11-安全设计规格(安全工程师必看)

定位: 认证、授权、数据安全、审计日志

核心内容:

代码语言:javascript
复制
§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攻击、服务故障

安全检查清单:

  • ✅ 权限矩阵是否覆盖所有角色×操作组合?
  • ✅ 敏感数据是否全链路加密(传输+存储)?
  • ✅ 速率限制是否与实际业务场景匹配?
  • ✅ 应急响应流程是否演练过?

4.5 🧪 13-测试策略与质量门禁(测试工程师必看)

定位: 分层测试策略+28条TC+质量门禁

核心内容:

代码语言:javascript
复制
§一 测试分层(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映射表

测试用例示例:

代码语言:javascript
复制
| 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     |

测试检查清单:

  • ✅ 每条AC是否至少映射1条TC?
  • ✅ 每个API是否有正常+异常用例?
  • ✅ 质量门禁是否"硬"(不留"下版本优化"的口子)?
  • ✅ 分层执行顺序是否正确(L1→L2→L3→L4)?

📋 五、按需查阅文档(P2):管理与追溯

5.1 📐 01-Spec写作总则与文档编号索引(元规范)

定位: 14份文档的"操作系统",定义写作规范

核心内容:

代码语言:javascript
复制
§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有索引与约束说明

5.2 📝 02-需求来源与采集记录(原始素材)

定位: 第一手需求素材,追溯的真正起点

核心内容:

代码语言:javascript
复制
S-01 会议纪要(618促销规划会议)
  - 4个痛点: 系统崩溃、配置复杂、缺乏监控、优惠券规则复杂
  - 5个需求: 活动配置、高可用、实时监控、优惠券优化、订单分流

S-02 邮件沟通(3封邮件)
  - 邮件一: 优惠券类型简化、智能推荐、领取限制
  - 邮件二: 角色分级、审批流程、操作日志
  - 邮件三: FAQ自动回复、订单查询、一键补发

S-03 用户访谈(4个访谈)
  - 资深用户: 智能推荐最优优惠
  - 新用户: 清晰的活动指引
  - 运营人员: 自主配置系统
  - 客服人员: 自助查询支持

需求汇总(15个REQ)
  - P0(2个): 活动配置、高可用
  - P1(5个): 实时监控、优惠券优化、订单分流等
  - P2(7个): 领取限制、角色分级、审批流程等
  - P3(1个): 一键补发优惠券

使用场景:

当你质疑"这个需求是哪来的?",翻到02文档,找到原始出处(谁、何时、什么场景提出的)。

5.3 📅 12-实施计划与里程碑(项目管理)

定位: 把Spec变成可排期、可追责的任务包

核心内容:

代码语言:javascript
复制
§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人

项目经理检查清单:

  • ✅ 里程碑是否按"可独立演示"切分?
  • ✅ WBS颗粒度是否在2-5天?
  • ✅ 风险是否有"触发条件+应对动作+负责人"?
  • ✅ 依赖关系是否标注清楚?

5.4 🔗 14-需求追踪矩阵RTM(全链路闭环)

定位: REQ ↔ API ↔ TC 的四向追溯

核心内容:

代码语言:javascript
复制
§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;测试失败时,沿反向链路定位哪条需求受影响。

🔍 六、如何检查与审核这14份文档?

6.1 文档质量检查清单

通用检查项(适用于所有文档)
  • ✅ 文档元数据是否完整(模块编号、版本、Owner、Reviewer、生效日期)?
  • ✅ 是否有上下游追溯(上游←哪个文档,下游→哪个文档)?
  • ✅ 是否使用统一的编号规范(REQ-ID、US-ID、TC-ID)?
  • ✅ 是否避免歧义词("建议/大概/尽量"等)?
  • ✅ 版本变更记录是否维护?
分阶段检查项

Meta阶段(01-02):

  • ✅ 01: 编号对照表是否覆盖01~14全部文档?
  • ✅ 01: 5条基本原则是否清晰?
  • ✅ 02: 每条痛点是否保留原话出处?

Proposal阶段(03-04):

  • ✅ 03: "不做"清单是否明确(至少5条)?
  • ✅ 03: 成功标准是否可度量(全部量化)?
  • ✅ 04: 场景是否覆盖所有目标用户?
  • ✅ 04: 产品规则是否有来源追溯?

Spec阶段(05-06-07):

  • ✅ 05: 每条AC是否可观察(能被接口/日志/UI验证)?
  • ✅ 05: 是否使用Given-When-Then格式?
  • ✅ 06: 每个US是否在FSD有对应章节?
  • ✅ 07: SLO指标是否可监控?

Design阶段(08-09-10-11):

  • ✅ 08: 每个技术选型是否有"核心理由"?
  • ✅ 09: 每个端点是否有请求体+响应体Schema?
  • ✅ 09: 字段名是否与10文档对齐?
  • ✅ 10: 每个字段是否有类型+约束+说明?
  • ✅ 11: 权限矩阵是否覆盖所有角色×操作?

Plan阶段(12):

  • ✅ 里程碑是否按"可独立演示"切分?
  • ✅ WBS颗粒度是否在2-5天?

Test阶段(13):

  • ✅ 每条AC是否至少映射1条TC?
  • ✅ 每个API是否有正常+异常用例?
  • ✅ 质量门禁是否"硬"?

Trace阶段(14):

  • ✅ 正向追溯是否100%覆盖?
  • ✅ 反向追溯是否完整?
  • ✅ 覆盖率是否≥90%?

6.2 文档审核流程

代码语言:javascript
复制
1. 作者自检
   ↓ (按6.1检查清单)
2. 同行评审(Peer Review)
   ↓ (至少1人,关注"是否能看懂")
3. 跨角色评审
   ↓ (产品+开发+测试联合评审,关注"是否一致")
4. 冻结(Freeze)
   ↓ (签字确认,后续变更走变更流程)
5. 持续维护
   ↓ (每个PR更新对应文档行)

变更流程:

代码语言:javascript
复制
05(行为变更) → 09/10(契约变更) → 13/14(验证追踪变更)

变更记录示例:

代码语言:javascript
复制
| 版本 | 日期       | 说明                          | 变更人  |
|------|------------|-------------------------------|---------|
| v1.0 | 2026-05-15 | 首版填写                      | 李产品  |
| v1.1 | 2026-05-20 | US-003增加AC-003-05(叠加规则) | 陈开发  |
| v2.0 | 2026-05-25 | API字段name→activity_name     | 陈开发  |

👥 七、团队如何使用这套Spec文档?

7.1 不同角色的使用指南

产品经理(Product Manager)
代码语言:javascript
复制
主要使用: 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确认覆盖率
后端开发(Backend Developer)
代码语言:javascript
复制
主要使用: 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用例
前端开发(Frontend Developer)
代码语言:javascript
复制
主要使用: 05、06、09、13
工作流:
  1. 理解用户故事 → 阅读05
  2. 查看交互规格 → 阅读06(布局+表单+错误处理)
  3. 查看API契约 → 阅读09(请求/响应Schema)
  4. 编码 → 按06+09开发
  5. 联调 → 对照09的响应示例
  6. 自测 → 对照13的E2E用例
测试工程师(Test Engineer)
代码语言:javascript
复制
主要使用: 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的覆盖率
技术Leader/Tech Lead
代码语言:javascript
复制
主要使用: 01、07、08、11、12、14
工作流:
  1. 规范制定 → 维护01(写作总则)
  2. 架构决策 → 主导08(ADR记录)
  3. 非功能约束 → 审核07(SLO/降级)
  4. 安全设计 → 审核11(权限矩阵)
  5. 计划排期 → 主导12(里程碑+WBS)
  6. 追溯审计 → 查看14(覆盖率风险)
  7. 评审把关 → 各阶段冻结签字

7.2 典型工作流示例

场景1:开发一个新功能(优惠券领取)
代码语言:javascript
复制
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 ✅
场景2:变更需求(优惠券领取限制从3张改5张)
代码语言:javascript
复制
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: 评审+冻结
  → 产品+开发+测试三方评审
  → 确认无遗漏后,三个文档同步升级版本
场景3:排查线上Bug(优惠券超卖)
代码语言:javascript
复制
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
  → 增加并发测试用例

🎓 八、最佳实践与常见误区

8.1 5条黄金法则

法则1: 先薄后厚,快速冻结

代码语言:javascript
复制
❌ 错误: 一次性把01-14全部写完再评审
✅ 正确: 先写03→04→05核心,冻结后启动开发,其他文档并行补充

法则2: 单一真相,禁止重复

代码语言:javascript
复制
❌ 错误: API字段名在09叫activityName,在10叫activity_name
✅ 正确: 09定义字段名,10严格对齐,其他文档只引用

法则3: AC必须可观察

代码语言:javascript
复制
❌ 错误: "系统应该流畅运行"
✅ 正确: "P95响应时间<200ms,通过Prometheus监控验证"

法则4: 门禁要"硬"

代码语言:javascript
复制
❌ 错误: "覆盖率80%以上最好,达不到也可以merge"
✅ 正确: "覆盖率<80%不允许merge,没有例外"

法则5: RTM持续维护

代码语言:javascript
复制
❌ 错误: 上线前一次性填满14文档
✅ 正确: 每个PR更新对应行,RTM始终反映真实状态

8.2 常见误区Top 5

误区1: 把"初步方案"写进02

代码语言:javascript
复制
❌ 02需求采集: "建议用Redis做缓存"
✅ 02只收集痛点,方案交给08 Design阶段

误区2: Proposal阶段写"实现方案"

代码语言:javascript
复制
❌ 03立项提案: "使用Spring Cloud微服务架构"
✅ 03只谈Why和What,How交给08 Design

误区3: AC写成"感受"而非"规格"

代码语言:javascript
复制
❌ AC: "用户应该觉得优惠券很好用"
✅ AC: "当用户有3张可用券时,系统推荐优惠力度最大的,显示节省金额"

误区4: API文档写大白话

代码语言:javascript
复制
❌ 09: "返回订单信息"
✅ 09: "返回{orderId: string, total: number, items: array}, 200"

误区5: 把RTM当"应付检查"

代码语言:javascript
复制
❌ 上线前突击填14文档
✅ 每个PR更新对应行,持续维护

📚 九、总结:从Spec到代码的完整路径

9.1 核心要点回顾

代码语言:javascript
复制
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?

阅读优先级:

代码语言:javascript
复制
必读(P0): 03 → 04 → 05 → 09 → 10
按需(P1): 06 → 07 → 08 → 11 → 13
管理(P2): 01 → 02 → 12 → 14

检查核心:

代码语言:javascript
复制
03: "不做"清单 + 成功标准可度量
05: AC可观察 + Given-When-Then格式
09: 请求/响应Schema完整 + 错误码齐全
10: 字段类型/约束/说明完整
13: AC→TC映射100% + 质量门禁"硬"
14: 覆盖率≥90% + 持续维护

9.2 下一步行动

如果你是新手:

  1. 1. 先读03→04→05,理解"为什么做→做什么→怎么验证"
  2. 2. 再读09→10,理解"接口契约+数据模型"
  3. 3. 对照13的TC用例,尝试写一个简单功能
  4. 4. 查看14,确认你的功能是否完整追溯

如果你是技术Leader:

  1. 1. 审核01的写作规范是否适合团队
  2. 2. 主导08的ADR决策记录
  3. 3. 把关07的非功能约束(SLO/降级)
  4. 4. 定期检查14的覆盖率风险

如果你想引入AI Coding:

  1. 1. 确保05/09/10三份文档质量(这是AI的关键上下文)
  2. 2. 使用spec-console.html可视化追溯链路
  3. 3. 每个PR生成代码后,对照13的TC自动验证
  4. 4. 用14文档追踪AI生成代码的覆盖率

结语

这套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文档编写,所有数据、示例均来自示例项目文档。

本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2026-05-16,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 沐然云计算 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 📖 一、为什么需要14份Spec文档?传统开发的痛点与破局
    • 1.1 传统开发模式的三大痛点
    • 1.2 Spec Coding的核心理念
  • 🗂️ 二、14份文档全景图:7个阶段的流转逻辑
    • 2.1 七阶段流程一览
    • 2.2 每个阶段回答的核心问题
  • 🎯 三、必读核心文档(P0):开发者的第一优先级
    • 3.1 📄 03-立项提案与范围说明(Proposal核心)
    • 3.2 📄 04-产品需求说明PRD(业务叙述)
    • 3.3 📄 05-用户故事与验收标准(Spec Coding核心⭐⭐⭐)
    • 3.4 📄 09-API接口规格(契约真源⭐⭐⭐)
    • 3.5 📄 10-数据模型与存储规格(数据真相)
  • 🔧 四、按需查阅文档(P1):特定角色的必读清单
    • 4.1 🎨 06-功能规格说明FSD(前端/交互必看)
    • 4.2 🏗️ 07-非功能需求与约束NFR(架构师必看)
    • 4.3 🏛️ 08-系统架构与技术选型(技术Leader必看)
    • 4.4 🛡️ 11-安全设计规格(安全工程师必看)
    • 4.5 🧪 13-测试策略与质量门禁(测试工程师必看)
  • 📋 五、按需查阅文档(P2):管理与追溯
    • 5.1 📐 01-Spec写作总则与文档编号索引(元规范)
    • 5.2 📝 02-需求来源与采集记录(原始素材)
    • 5.3 📅 12-实施计划与里程碑(项目管理)
    • 5.4 🔗 14-需求追踪矩阵RTM(全链路闭环)
  • 🔍 六、如何检查与审核这14份文档?
    • 6.1 文档质量检查清单
      • 通用检查项(适用于所有文档)
      • 分阶段检查项
    • 6.2 文档审核流程
  • 👥 七、团队如何使用这套Spec文档?
    • 7.1 不同角色的使用指南
      • 产品经理(Product Manager)
      • 后端开发(Backend Developer)
      • 前端开发(Frontend Developer)
      • 测试工程师(Test Engineer)
      • 技术Leader/Tech Lead
    • 7.2 典型工作流示例
      • 场景1:开发一个新功能(优惠券领取)
      • 场景2:变更需求(优惠券领取限制从3张改5张)
      • 场景3:排查线上Bug(优惠券超卖)
  • 🎓 八、最佳实践与常见误区
    • 8.1 5条黄金法则
    • 8.2 常见误区Top 5
  • 📚 九、总结:从Spec到代码的完整路径
    • 9.1 核心要点回顾
    • 9.2 下一步行动
  • 结语
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档