用手工 Spec Coding 开发“基金申赎指令审核与复核”应用（附实践模板）

很多团队做 AI Coding 时，最容易掉进一个坑：

代码生成很快，但需求和规则没写清，后续越改越乱。

这次我们做了一个完整实践：用手工 Spec Coding（不依赖 OpenSpec 工具链）开发了一个可运行应用，包含：

• 前端：Vue 页面（流程操作 + 学习侧栏）
• 后端：Flask API（提交/审核/复核/查询）
• 规格：一组可迭代的 Spec 文档
• 验证：按 AC 编号命名的 pytest 自动化验收
• 亮点：Workshop 侧边栏联动高亮（规则/Spec/AC 一键映射）

一、为什么要手工 Spec Coding？

一句话： 把“口头需求”变成“可实现、可测试、可追踪”的工程资产。

如果不先写 Spec，常见问题是：

• 前后端对业务规则理解不一致
• 状态流转混乱（该审核的去复核，不该通过的通过了）
• 错误码和异常处理“想到哪写到哪”
• 改需求时无法定位影响范围，回归成本爆炸

手工 Spec Coding 的价值就在于：先约束，再编码；先定义，再实现。

二、我们是怎么落地的（过程拆解）

1）先建 Spec 包（过程文件）

先创建了可版本化的模板和示例，核心包括：

• 01-问题定义与范围-SPEC.md
• 02-领域模型与业务规则-SPEC.md
• 03-流程状态接口与验收-SPEC.md
• 以及示例填充与过程模板等实践材料

目标不是“文档好看”，而是让每个需求都有归属：

• 属于哪个规则（R-xxx）
• 影响哪个接口
• 对应哪个验收（AC-xxx）

2）再落地应用（前后端）

开发了“基金申赎指令审核与复核”应用：

后端 Flask API

• POST /api/orders 提交指令（含幂等 requestId）
• POST /api/orders/{id}/audit 审核
• POST /api/orders/{id}/review 复核
• GET /api/orders / GET /api/orders/{id} 查询

前端 Vue 页面

• 创建指令
• 审核/复核操作
• 订单详情与日志回放

并且严格按 Spec 的流程状态执行：

PENDING_AUDIT -> PENDING_REVIEW -> APPROVED/REJECTED

3）最后补“规格即测试”

按 Spec 的 AC 编号写了自动化验收：

• AC-001 正常提交进入 PENDING_AUDIT
• AC-002 风险不匹配拦截
• AC-003 审核通过进入 PENDING_REVIEW
• AC-004 审核复核同人拦截
• AC-005 复核通过后归档日志存在

形成闭环：Spec -> API -> AC -> pytest

三、这些 Spec 文件各自干什么？

可以把它理解成“分层控制面”：

spec/01-需求与范围-v0.1.md

回答：我们要解决什么，不做什么

用于控制范围，防止需求蔓延。

spec/02-领域规则-v0.1.md

回答：规则是什么、编号是什么、状态是什么

用于约束业务行为，防止接口各自为政。

spec/03-流程接口验收-v0.1.md

回答：流程怎么走、接口怎么定、验收怎么测

用于开发联调和验收统一口径。

spec/04-逐步对照SpecCoding流程-v0.1.md

回答：怎么从 v0.1 迭代到 v1.0

用于变更治理和版本演进。

四、后续需求变更，怎么改 Spec？

这是重点：先改 Spec，再改代码。

推荐流程：

1. 1. 在 01 更新范围变化（新增目标/非目标）
2. 2. 在 02 新增或修订规则编号（如 R-011、R-012）
3. 3. 在 03 增加接口或 AC（如 AC-006~AC-010）
4. 4. 更新版本号（v0.2-review -> v0.9-rc -> v1.0-baseline）
5. 5. 补对应 pytest 用例，再改实现

一个简单原则：

每次变更都要能回答“三个问题”

• 影响了哪条规则？
• 影响了哪个接口？
• 对应哪个验收？

五、页面亮点：Workshop 侧边栏联动高亮

我们在右侧做了 Workshop 学习区，包含：

• Spec 文件映射
• 接口 -> Spec 对照
• 当前操作命中（接口 / R-xxx / FUND-SPEC-xx / AC-xxx）
• 命中规则详情（含反例）
• 规则全量清单（命中自动高亮）

当点击“提交/审核/复核/详情”时，侧边栏会同步高亮对应规则和规格文档。

这让“抽象规则”变成“可见映射”，非常适合快速学习。

点击“审核”后的命中高亮

规则详情中的“反例”说明

点击“提交指令”，规则全量清单的命中高亮状态。

六、还做了一个 Vibe 详情页（帮助新人入门）

考虑到“基金申赎指令”对部分同学不熟，我们增加了独立介绍页：

• 支持“新手解释版 / 专业术语版”一键切换
• 包含基金行业典型应用场景（直销、代销、机构交易台、调仓等）
• 与主 Spec 页面并存，不互相干扰

这页的定位是： 降低行业门槛，让新人先懂业务，再看规则。

七、结语：手工 Spec Coding 不是慢，而是省总成本

看起来前期多写了几份文档，但换来的是后续迭代的“低混乱、低返工、高可追踪”。

如果你也想在团队推行，可以从一个中等复杂场景开始（比如审批流、交易流、调仓流）：

• 先做 v0.1-draft
• 小范围评审到 v0.2-review
• 冻结 v1.0-baseline
• 用 AC 驱动测试和联调

真正的效率，不是“今天写快一点”，而是“一个月后还能改得动”。

后续加工后公开源码和文档，如需要可以留言或小窗。