OpenSpec 驱动开发在后端项目中的实践

面向服务端团队的实践分享 · D5 Works 后端项目

用 OpenSpec 把复杂后端改动变得更可控

这不是一次"AI 编程工具介绍"，而是基于 创作者提现系统 等真实需求的开发方式分享：当需求、设计、实现和评审开始围绕 Spec 组织时，后端开发会发生什么变化。

先明确问题和边界，不急着写代码

在 Cursor 中围绕同一份 Spec 多轮推进

让 AI 输出更稳定，也让 review 更有依据

项目背景

D5 Works · 后端服务

JDK 21 + Spring Boot 3.5 + MyBatis + MySQL 8.0
微服务架构，依赖 Nacos、RocketMQ、Redis

核心案例

creator-withdrawal-system

创作者收益入账 → 余额管理 → 提现申请 → 审核打款，6 天完成 6 张新表 + 15 个 API 的全流程闭环。

已归档 Changes

5 个版本迭代，覆盖大中小需求

从修排序 Bug（3 个 task）到 MAX 模型异步对接（跨服务 BREAKING 改造），都走了同一套流程。

为什么我们需要 Spec 驱动开发

在后端项目里，很多问题并不来自"代码不会写"，而来自"问题没有被定义清楚"。AI 可以帮我们更快地产出代码，但如果上下文和约束不完整，它也会更快地把错误放大。

需求理解不一致

同一句"做个提现功能"，有人想到 PayPal 自动打款，有人想到线下打款 + 审核流。

改动范围不清晰

提现系统影响订单、支付中心、通知、Redis 分布式锁——漏掉一个就是线上 bug。

AI 产出容易跑偏

没有约束时 AI 会选"最常见方案"而非"最适合当前项目的方案"。

文档、设计、实现脱节

讨论散落在聊天、issue 和代码 diff 里，后来者无法还原决策过程。

什么是 OpenSpec

一种更结构化的开发协作方式：不是直接让 AI 改代码，而是先把"要做什么、为什么这么做、边界是什么、如何验收"明确下来，再推动设计和实现。

先定义问题，再定义解法，最后进入实现。

让需求、设计、实现围绕同一个 Spec 对齐。

适合中大型功能、跨模块改造、需要评审和追溯的需求。

和"直接让 AI 写代码"有什么区别

直接让 AI 写代码

Spec 驱动开发

需求理解靠对话上下文

需求、边界、验收标准先显式写出

AI 自由发挥空间大

AI 在更明确的约束下工作

结果容易依赖单次 prompt 质量

结果更多依赖 Spec 的完整性和一致性

review 重点常落在代码细节

review 可以前移到需求和设计阶段

OpenSpec 核心流程

从提出变更到完成交付，经过四个阶段。每个阶段有明确的输出物和评审节点，让讨论前置、分歧显式化。

Step 01

Proposal

先回答为什么要做：背景、问题、收益、影响范围。

Step 02

Spec

把需求边界写清楚：目标、非目标、约束、验收标准。

Step 03

Design

技术方案讲明白：接口、数据、模块、流程、风险和权衡。

Step 04

Task

把执行动作拆出来：先后顺序、交付物和检查点。

一句话理解这条链路

Proposal 说明"为什么值得做"→ Spec 定义"到底要做什么"→ Design 说明"准备怎么做"→ Task 推动"接下来谁去做、怎么落地"

核心文档结构

四类文档分开存放，分别服务于不同阶段。让评审更聚焦，也让 AI 在每个阶段只关注正确的问题。

Proposal ## Why / ## What Changes / ## Impact

变更提案，说明背景、动机、收益、影响范围。

Spec ## ADDED / MODIFIED / REMOVED Requirements

需求规格，WHEN-THEN-AND 格式定义行为要求和验收标准。

Design ## Context / ## Decisions / ## Risks

技术设计，记录每个决策的选择、理由和替代方案。

Task - [x] / - [ ] checkbox 格式

任务拆解，带编号、依赖关系和完成状态跟踪。

D5 Works 的文件组织

# 项目结构
openspec/
├── project.md                  # 项目宪法：技术栈、架构约束、编码规范
├── specs/                         # 按业务领域组织的全局 Spec
│   ├── product/spec.md
│   ├── order/spec.md
│   ├── creator/spec.md
│   └── ...
└── changes/                       # 变更记录
    ├── creator-withdrawal-system/ # ← 当前活跃的 change
    │   ├── .openspec.yaml
    │   ├── proposal.md
    │   ├── design.md
    │   ├── tasks.md
    │   └── specs/                 # 4 个子 spec
    │       ├── creator-earnings/spec.md
    │       ├── withdrawal-request/spec.md
    │       ├── withdrawal-setting/spec.md
    │       └── withdrawal-admin/spec.md
    └── archive/                   # 已归档的变更
        ├── V1.3.3-fix-download-stats-sorting/
        ├── V1.3.3-fix-violation-image-deletion/
        ├── V1.3.3-max-async-review-integration/
        ├── V1.3.3-add-group-model-support/
        └── V1-3-3-machine-review-enhancements/

每个 change 归档后自动进入 archive/，保留完整审计记录。全局 specs 被 change 中的 spec 引用，实现增量定义。

真实案例

creator-withdrawal-system：从 Proposal 到实现

创作者在 D5 Works 销售商品后没有提现通道。我们需要在 6 个工作日 内搭建完整的提现系统：收益入账 → 等待期结算 → 提现申请 → 财务审核 → 打款标记。以下是 OpenSpec 四层文档如何串起这个需求的。

01 Proposal — 说清"为什么要做"

## Why
创作者在 Works 平台销售商品后，目前没有提现通道，无法将收益提取到个人账户。
需要搭建完整的提现系统（Phase 1），实现收益入账、余额管理、提现申请、
财务审核、打款标记的全流程闭环，使创作者能够通过 PayPal 提取收益。

## What Changes
- 新增创作者收益入账机制：个人订单和团队订单支付成功后自动计算创作者净收益
  （Stripe 手续费通过支付中心结算查询接口精确获取）
- 新增创作者余额体系：可提现余额、冻结金额、待结算金额、累计已提现
- 新增提现设置模块：PayPal 收款账户配置，含制裁国家校验、邮箱唯一性校验
- 新增提现申请流程：全额提现、前置校验、风控限制（24h/1次）
- 新增提现状态机：待审核 → 待打款 → 已完成/打款失败
- 新增财务后台管理：提现列表筛选、审核通过/拒绝、标记打款成功/失败
- 新增定时任务：等待期到期自动结算

## Capabilities  # 用 capability 把 change 拆成可独立验收的子模块
- withdrawal-setting: 创作者提现账户设置
- creator-earnings: 创作者收益计算与余额管理
- withdrawal-request: 提现申请与状态流转
- withdrawal-admin: 财务后台管理

## Impact
- 新增 6 张数据库表
- 新增 ~15 个 API（创作者端 8 + 财务后台 7）
- 依赖：支付中心、通知系统、用户中心、Redis

02 Spec — 定义"做什么、不做什么"

每个 capability 对应独立的 spec 文件，用 WHEN-THEN-AND 格式逐场景定义行为要求。以下是两个代表性片段：

specs/withdrawal-request/spec.md

### Requirement: 提现前置校验

系统 MUST 在接受提现申请前校验以下条件：
（1）已配置提现账户
（2）可提现余额 ≥ 最低门槛（可配置，默认 $100）
（3）无处理中的提现申请

#### Scenario: 未配置提现账户
- WHEN 创作者未配置提现设置就发起提现
- THEN 系统拒绝并提示配置提现账户

#### Scenario: 所有前置条件满足
- WHEN 所有前置条件均满足
- THEN 系统创建提现申请，冻结全部可提现余额，
       生成提现单号

### Requirement: 风控限频

系统 MUST 限制每位创作者 24h 内只能成功提交 1 次提现。
失败或被拒绝的提现不计入此限制。

#### Scenario: 上次提现被拒绝
- WHEN 创作者上次提现被拒绝或失败，不论时间
- THEN 系统允许提交新的提现申请

specs/creator-earnings/spec.md

### Requirement: 订单支付成功后创建收益记录

创作者净收益 = 消费者支付金额（USD）- Stripe 手续费（USD）
Stripe 手续费 MUST 通过支付中心结算查询接口精确获取。

#### Scenario: 团队订单支付成功
- WHEN 某创作者商品的团队订单支付成功
- THEN 系统为每个订单商品行项创建收益记录
- AND 单个商品行项创建失败时捕获异常并钉钉告警，
       不影响其他商品行项处理

### Requirement: 余额并发安全

系统 MUST 通过 SQL 原子操作保护所有余额修改操作。
全额提现冻结使用 SELECT ... FOR UPDATE 行锁。
提现申请使用分布式锁防止并发创建重复提现单。

#### Scenario: 并发修改余额
- WHEN 两个操作同时修改同一创作者的余额
- THEN InnoDB 行级锁自然序列化写入，
       WHERE 非负守卫防止余额穿透

03 Design — 讲清"怎么做、为什么这么选"

Design 最核心的部分是 Decisions：每个技术决策都记录了"选择 + 理由 + 替代方案"，而不仅仅是"我们用了 X"。

Decision 1

余额表 + 流水记录

选择：独立 balance 表 + earnings 流水
理由：查询效率高、支持负余额、便于对账
替代：实时聚合 — 查询慢且负余额复杂

Decision 2

SQL 原子操作 + 声明式事务

选择：incrementBalance SQL + @Transactional
理由：InnoDB 行锁序列化并发写入，无需 Redis 分布式锁
弃用：Redis 锁 + REQUIRES_NEW 编程式事务 — 三层嵌套复杂

Decision 5

Stripe 手续费精确获取

选择：调用支付中心 settlement/retrieve 接口
理由：Stripe 手续费因卡类型不同，固定公式不准确
细节：当前 SGD 结算需汇率换算，后续 USD 主体可简化

Decision 6

PayPal 邮箱不做存在性验证

选择：Phase 1 仅格式+唯一性校验
理由：PayPal 不提供公开的邮箱验证 API
后续：Phase 2 接入 PayPal Login OAuth

Decision 7

PayPal 手续费独立落库

选择：paypalFee 独立字段 + 三数一致性校验
理由：避免精度/舍入推算不一致
校验：amount - paypalFee == actualAmount

Decision 9

退款延至 Phase 2

选择：Phase 1 不实现退款扣减
理由：余额已支持负数，能力预留
砍掉：退款涉及权益撤销等复杂逻辑

Design 的价值在于

不仅记录了"我们怎么做"，更记录了"我们为什么不那样做"。后来的开发者不需要重走决策过程，AI 也能基于 Design 给出更精准的实现。

04 Task — 拆成可执行的动作清单

整个提现系统被拆成 8 个任务组、40+ 个子任务，每个任务带编号和 checkbox 状态。

1. 数据库与基础代码层

6 张表的 DDL、Entity、Mapper、Req/Resp DTO、枚举类
17 个子任务 ✓

2. 提现设置模块

配置 CRUD、制裁国家校验、邮箱唯一、验证码
10 个子任务 ✓

3. 收益计算与余额管理

Stripe 手续费获取、收益入账、等待期结算、团队订单支持
15 个子任务 ✓

4-8. 提现/API/后台/配置/重构

申请流转、创作者端 API、财务后台、通知配置、分层重构
多个子任务 ✓

## 3. 收益计算与余额管理（节选）

- [x] 3.2 在 PayCenterClient 中新增结算查询接口：POST /internal/payment/settlement/retrieve
- [x] 3.3 实现 Stripe 手续费获取与币种换算逻辑：SGD → USD
- [x] 3.4 实现收益入账逻辑：计算净收益、保存手续费明细 JSON、创建 PENDING 记录
- [x] 3.5 重构 createEarnings 支持团队订单：抽取 doCreateEarnings 共用
- [x] 3.7 修复团队订单 handlePaymentResult 时序缺陷：afterPaymentSucceeded
      必须在 updateByOrderNo 之后执行，否则 externalOrderNo 未落库
- [x] 3.9 实现 CreatorBalanceService：incrementBalance SQL 原子操作 +
      WHERE 非负守卫，全额冻结使用 SELECT FOR UPDATE 行锁

## 8. 分层架构重构

- [x] 8.1 抽取 WithdrawalStatusLogService，消除跨服务 Mapper 直调
- [x] 8.3 CreatorEarningsServiceImpl 跨领域 Mapper 替换为 Service 调用

Spec 的语言规范

我们约定了统一的 Spec 写作规范，让所有文档保持一致的结构。

结构关键词保留英文

## ADDED Requirements ### Requirement: #### Scenario:

动词关键词使用英文

WHEN 条件 · THEN 预期结果 · AND 补充

内容描述使用中文

技术术语（API 名称、字段名、类名）可保留英文，其余用中文。

Task 强制 checkbox 格式

- [x] 1.1 描述 已完成 · - [ ] 1.2 描述 待做

Spec 如何约束 AI

以提现设置为例，Spec 中定义了明确的行为约束，AI 在实现时必须遵守。

### Requirement: 修改提现设置需邮箱验证码

#### Scenario: 首次配置无需验证码
- WHEN 创作者首次配置提现设置（此前无任何配置记录）
- THEN 系统不要求验证码，直接保存配置

#### Scenario: 60 秒内重复发送
- WHEN 创作者在上次发送后 60 秒内再次请求发送验证码
- THEN 系统拒绝并提示稍后再试

#### Scenario: 验证码尝试次数超限
- WHEN 创作者对同一验证码连续验证失败达到 10 次
- THEN 系统自动销毁该验证码并清零失败计数，
       提示"失败次数过多，验证码已失效，请重新获取"

### Requirement: 处理中提现时禁止修改设置
- WHEN 创作者尝试修改提现设置，且当前有活跃的提现申请
- THEN 系统拒绝并提示"你有正在处理中的提现申请，
       暂时无法修改提现设置"

每一个场景都是一条可验证的用例。AI 生成代码时，这些场景就是它的"测试用例清单"；review 时，我们对照 Spec 逐条检查实现是否正确。

不同规模的需求都在用同一套流程

D5 Works 已有 5 个归档的 change。从修一个排序 Bug 到跨服务 BREAKING 改造，OpenSpec 的四层文档结构都适用，只是"写多少"不同。

Change

类型

规模

亮点

fix-download-stats-sorting

Bug 修复

3 个 task，改 1 个 SQL

小需求也写了清晰的 Design：为什么选 LEFT JOIN、为什么用 COALESCE

fix-violation-image-deletion

Bug 修复

Gemini 审核路径遗漏删除

Modified Capability 精确补充 spec 行为要求

add-group-model-support

新功能

新增查询接口 + 同步字段

Proposal 清晰定义了跨系统影响边界

max-async-review-integration

跨服务改造

BREAKING 消息格式变更

Design 记录了 7 个技术决策，含完整的类重命名和多态继承重构

creator-withdrawal-system

大型新功能

6 张表 + 15 API + 40 task

4 个子 spec、9 个 Design Decision、8 个 Task Group

小需求（修 Bug）

Proposal 几行 + Design 1-2 个 Decision + Task 3-5 个。重点是明确"为什么这么改"和替代方案。

中需求（新接口/修改已有能力）

Spec 定义清楚 WHEN-THEN 场景，Design 讲清依赖和影响。AI 可以基于这些直接生成。

大需求（跨模块/新系统）

拆成多个 capability + 子 spec，Design 需要完整的决策记录。Task 拆到可独立验收的粒度。

OpenSpec CLI 常用命令

OpenSpec 提供了一个 Node.js CLI 工具，用于管理 change 的生命周期。以下所有输出均来自对 D5 Works 当前项目的实际执行结果。

1 openspec list — 查看所有活跃的 change

普通输出（人类阅读）

$ openspec list

Changes:
  creator-withdrawal-system     ✓ Complete    4h ago

JSON 输出（AI 消费）

$ openspec list --json

{
  "changes": [
    {
      "name": "creator-withdrawal-system",
      "completedTasks": 67,
      "totalTasks": 67,
      "lastModified": "2026-03-25T06:39:25.038Z",
      "status": "complete"
    }
  ]
}

2 openspec list --specs — 查看所有全局 Spec（按业务领域）

$ openspec list --specs

Specs:
  content                              requirements 6
  creator                              requirements 7
  download-stats-sorting               requirements 1
  general-file-validation              requirements 1
  group-model-query                    requirements 3
  max-async-result-consumption         requirements 4
  metadata                             requirements 6
  model-analyze-result-unification     requirements 5
  order                                requirements 5
  product                              requirements 5
  product-image-review                 requirements 0

每个 spec 按业务领域组织（content、creator、order、product 等），requirements 数量反映了该领域已沉淀的行为要求条数。随着 change 不断归档，主 spec 持续积累。

3 openspec status --change <name> — 查看 artifact 完成状态

普通输出

$ openspec status --change creator-withdrawal-system

Change: creator-withdrawal-system
Schema: spec-driven
Progress: 4/4 artifacts complete

[x] proposal
[x] design
[x] specs
[x] tasks

All artifacts complete!

JSON 输出（Skill 的核心依据）

$ openspec status --change creator-withdrawal-system --json

{
  "changeName": "creator-withdrawal-system",
  "schemaName": "spec-driven",
  "isComplete": true,
  "applyRequires": ["tasks"],
  "artifacts": [
    { "id": "proposal", "status": "done" },
    { "id": "design",   "status": "done" },
    { "id": "specs",    "status": "done" },
    { "id": "tasks",    "status": "done" }
  ]
}

applyRequires: ["tasks"] 告诉 Skill：只有 tasks artifact 完成后才能进入实现阶段。Skill 会读取这个字段来判断下一步做什么。

4 openspec instructions apply --change <name> --json — 获取实现阶段的指令和任务清单

$ openspec instructions apply --change creator-withdrawal-system --json

{
  "changeName": "creator-withdrawal-system",
  "schemaName": "spec-driven",
  "contextFiles": {                            ← AI 实现前必须读取的文件
    "proposal": ".../proposal.md",
    "specs":    ".../specs/**/*.md",
    "design":   ".../design.md",
    "tasks":    ".../tasks.md"
  },
  "progress": {
    "total": 67, "complete": 67, "remaining": 0
  },
  "tasks": [                                    ← 67 个任务的完整清单
    { "id": "1",  "description": "1.1 创建 SQL 脚本：works_creator_balance 表...", "done": true },
    { "id": "2",  "description": "1.2 创建 SQL 脚本：works_creator_earnings 表...", "done": true },
    ... 省略 63 条 ...
    { "id": "66", "description": "8.3 跨领域 Mapper 替换为 Service 调用...", "done": true },
    { "id": "67", "description": "8.4 新增 getByOrderNos 批量查询方法...", "done": true }
  ],
  "state": "all_done",
  "instruction": "All tasks are complete! This change is ready to be archived."
}

这是 apply Skill 的核心数据源。Skill 读取 contextFiles 加载上下文，遍历 tasks 数组逐个执行，通过 state 判断是否已全部完成。

5 openspec validate <name> — 校验结构完整性

$ openspec validate creator-withdrawal-system

Change 'creator-withdrawal-system' is valid

校验 proposal、specs、design、tasks 的结构是否完整。支持 --all（校验全部 change + spec）、--strict（严格模式）。

6 openspec schemas — 查看可用的工作流 schema

$ openspec schemas

Available schemas:

  spec-driven
    Default OpenSpec workflow - proposal → specs → design → tasks
    Artifacts: proposal → specs → design → tasks

当前 D5 Works 使用的是 spec-driven schema，即标准的四层文档流程。Schema 定义了 artifact 的依赖关系和创建顺序。

7 openspec archive <name> — 归档已完成的 change

# 归档时自动检查 artifact 和 task 完成状态
# 支持将 delta spec 同步到全局主 spec
# 移动到 archive/YYYY-MM-DD-<name>/ 目录

$ openspec archive creator-withdrawal-system

# 归档后目录结构：
openspec/changes/archive/
├── V1.3.3-fix-download-stats-sorting/
├── V1.3.3-fix-violation-image-deletion/
├── V1.3.3-max-async-review-integration/
├── V1.3.3-add-group-model-support/
├── V1-3-3-machine-review-enhancements/
└── 2026-03-25-creator-withdrawal-system/  ← 新归档

命令与 Cursor Skill 的关系

CLI 命令是底层引擎，Cursor Skill 是上层编排。你几乎不需要手动执行这些命令 —— Skill 会根据你的意图自动调用正确的命令序列，并把 --json 结果传递给 AI 解析。人类更多通过 openspec list 和 openspec status 了解全局状态。

Cursor 中的 OpenSpec Skills

D5 Works 项目在 .cursor/skills/ 下配置了 4 个 OpenSpec Skill。每个 Skill 是一个 SKILL.md 文件，定义了 AI 在特定阶段应该执行的步骤、调用的 CLI 命令和输出格式。Cursor Agent 会根据用户意图自动匹配并执行对应的 Skill。

openspec-propose

一键生成完整提案

输入一段需求描述，AI 自动完成全流程：创建 change 目录 → 按依赖顺序生成 proposal → specs → design → tasks，直到所有 artifact 就绪。

# 触发方式：描述你要做的事
用户："我要做一个创作者提现系统，支持 PayPal 提现"

# Skill 内部执行序列：
openspec new change "creator-withdrawal-system"
openspec status --change ... --json   # 获取 artifact 依赖图
openspec instructions proposal --json  # 获取写作模板和约束
生成 proposal.md
openspec instructions specs --json
生成 specs/*.md
openspec instructions design --json
生成 design.md
openspec instructions tasks --json
生成 tasks.md
# 完成后提示：运行 /opsx:apply 开始实现

openspec-explore

探索模式 · 思考伙伴

不写代码，只思考。 进入探索模式后，AI 会读代码库、画 ASCII 图、比较方案、质疑假设，帮你理清问题。可以随时把思考结论沉淀到 OpenSpec 文档。

适用场景：需求模糊时先探索、实现卡住时重新思考、技术选型时比较方案

核心约束：可以读文件、搜代码，但禁止写代码。可以创建 OpenSpec 文档（那是"记录思考"不是"实现功能"）

输出形式：ASCII 架构图、方案对比表、风险分析、决策建议

openspec-apply-change

逐任务执行实现

读取 change 的所有 context 文件（proposal + specs + design + tasks），然后逐个 task 执行：写代码 → 标记 checkbox → 继续下一个。遇到阻塞自动暂停并请求指导。

# 触发后 AI 的执行循环：
1. openspec instructions apply --change ... --json
2. 读取 contextFiles（proposal, specs, design, tasks）
3. 显示进度："4/40 tasks complete"

## Implementing: creator-withdrawal-system

Working on task 3.2: 新增结算查询接口
[...生成 PayCenterClient 代码...]
✓ Task complete

Working on task 3.3: Stripe 手续费币种换算
[...生成换算逻辑...]
✓ Task complete

# 每完成一个 task 自动在 tasks.md 中打勾：- [ ] → - [x]

openspec-archive-change

归档已完成的变更

所有 task 完成后，归档 change。自动检查 artifact 完成度和 task 状态，将 delta spec 同步到全局主 spec，然后把 change 移入 archive/。

Step 1：检查所有 artifact 和 task 是否完成，未完成则警告并确认

Step 2：比对 delta spec 与 main spec 的差异，提示是否同步（推荐同步）

Step 3：移动到 archive/YYYY-MM-DD-<name>/，保留完整审计记录

四个 Skill 的典型使用流转

  explore                propose                apply               archive
  ┌──────────┐          ┌──────────┐          ┌──────────┐          ┌──────────┐
  │ 探索问题 │    ─→    │ 生成提案 │    ─→    │ 逐项实现 │    ─→    │ 归档变更 │
  │ 理清思路 │          │ 四层文档 │          │ 标记完成 │          │ 同步 Spec│
  └──────────┘          └──────────┘          └──────────┘          └──────────┘
       │                      │                     │
       │    可随时回到探索     │   可随时更新文档     │  遇阻塞自动暂停
       └──────────────────────┴─────────────────────┘

  非线性流程：可以从任意阶段开始，随时在 Skill 之间切换

在 Cursor 中如何触发

直接用自然语言描述意图，Cursor Agent 自动匹配 Skill

"我要做一个 XX 功能" → 自动触发 propose

"帮我想想 XX 怎么设计" → 自动触发 explore

"开始实现 / 继续实现" → 自动触发 apply

"归档这个 change" → 自动触发 archive

Skill 的核心价值

标准化 AI 行为 — 不再依赖 prompt 质量，每次执行流程一致

语言规范内置 — 结构英文、内容中文的规范写在 Skill 里，AI 自动遵守

上下文自动加载 — Skill 自动读取 project.md、已有 artifact，不需手动 @ 引用

进度可追踪 — task checkbox 实时更新，随时可以看到 "15/40 完成"

我在 Cursor 中的实际工作流

Cursor 不只是代码编辑器，更是围绕 OpenSpec 协作的工作台。以 creator-withdrawal-system 为例，我的实际使用方式是：

Step 01

整理 Proposal

让 AI 帮我把"做个提现功能"展开成背景、问题、收益、影响范围。

Step 02

沉淀 Spec

用 WHEN-THEN 格式逐个场景定义行为要求。这一步 AI 参与率最高。

Step 03

补齐 Design

讨论技术决策。例如"余额管理用 Redis 锁还是 SQL 原子操作"就在这里确定。

Step 04

拆解 Task

把 40+ 个子任务按模块分组，带编号和依赖关系。

Step 05

推动实现

AI 基于 design + task 辅助生成代码。每完成一个 task 就打勾。

Step 06

Review 与校验

对照 spec 回看结果，确认实现没有偏离原始目标。

关键变化

以前是"给 AI 一段需求，让它直接改代码"；现在是"先让 AI 帮我把上下文整理进 OpenSpec 文档，再让它基于这些文档参与实现"。 代码生成只是最后一步，而不是第一步。

后端 Spec Checklist

最适合被团队复用的一页。"开始让 AI 动手前，至少先写清楚这些"的最小模板。

需求层

要解决什么问题（Why）
目标与非目标（Goals / Non-Goals）
成功标准 / 验收条件

接口层

请求与响应结构（Req / Resp）
错误码与兼容策略
对上下游的影响（Feign / MQ）

数据层

表结构 / 字段变更（DDL）
索引与性能影响
迁移与回滚方案（Flyway）

逻辑层

主流程与分支流程
边界条件（NULL / 空 / 极限值）
幂等与一致性策略

非功能性

并发安全（锁 / 事务隔离）
性能要求
日志 / 监控 / 告警

测试验收

单元测试
集成测试
回归范围与验收口径

我感受到的收益

需求理解更稳定 — creator-withdrawal-system 涉及支付、Redis、MQ 多个系统，Spec 让每个边界都有明确定义，减少"每个人脑补不同"的情况。

AI 产出更可控 — AI 最初建议用 Redis 分布式锁管理余额并发，但 Design 中的 Decision 2 明确选择了 SQL 原子操作。有了这个约束，AI 后续实现不会再跑偏。

review 更有依据 — 不再只看代码 diff，而是对照 Spec 逐条验证。"这个场景 Spec 定义了 THEN，代码是否实现了？"

决策可追溯 — 半年后有人问"为什么不用 Redis 锁"，直接看 Design Decision 2 的弃用理由，不需要考古代码。

目前的局限和边界

写 Spec 有成本 — fix-download-stats-sorting 只改了 1 个 SQL，但 Design 仍写了 3 个 Decision。小需求要权衡"写多少"。

Spec 写不清楚照样跑偏 — Spec 不是银弹。如果场景漏了、边界没写，AI 一样会自由发挥。

团队需要统一模板 — 如果每个人写的格式不同，Spec 的复用价值就会打折。我们已约定了语言规范（结构英文、内容中文）。

不是所有场景都值得 — 应急修 bug、一次性脚本、极小改动，不一定值得完整走一遍。但至少可以写 Proposal + 简单 Design。

团队如何开始落地

不建议一上来全量推行。更现实的方式是：先试点、再统一模板、然后评估收益。

从试点开始

挑中大型需求或跨模块改造，不从极小任务入手。类似 creator-withdrawal-system 的规模最合适。

统一轻量模板

先约定最小 Spec 结构和语言规范（WHEN-THEN-AND），降低上手成本。

沉淀 Cursor 工作流

形成固定的 Skill / Rule / Instruction 使用方式，让 AI 按照 Spec 约束工作。

评估效果

看返工次数、review 成本、AI 代码可用率是否改善。用数据说话。