Appearance
Spec-Driven 开发：订单导出什么时候算完成
Spec-Driven 关注一个朴素问题：代码什么时候算完成。对于订单导出，答案不应该是“页面上有按钮，点了能下载”，而应该是“规格里的成功路径、边界情况、失败路径和验证命令都满足”。
在 AI 编程中，这一点尤其重要。模型很擅长根据模糊描述补全实现，但它补出来的细节未必是业务真正需要的。Spec-Driven 的作用，就是把判断标准提前写清楚，让实现、测试和 review 都围绕同一份规格工作。
从感觉驱动到规格驱动
感觉驱动的订单导出通常这样推进：
text
需求：订单列表加个导出。
实现：页面加按钮，后端返回 CSV。
试用：能下载，但字段不对；无权限用户也能请求接口；数据量大时接口超时。
返工：补字段、补权限、补性能限制、补失败提示。这些返工并不是因为开发不努力，而是因为“完成”的定义太晚才出现。
规格驱动会先把完成条件写出来：
text
订单导出规格：
- 导出范围必须与当前筛选条件一致。
- 只导出字段白名单中的 7 个字段。
- 无权限用户不能看到入口，直接请求接口返回 403。
- 空结果导出生成只有表头的 CSV。
- 1 万行以内同步导出，超过限制提示缩小筛选范围。
- 导出失败时页面保留筛选条件，并显示重试入口。
- 相关测试和构建命令通过。有了这组标准，代码是否完成就不再由主观感受决定。
规格不是长文档
规格不等于完整 PRD，也不要求每个小改动都写成十几页文档。它是一组能约束实现的事实：目标、范围、数据边界、失败行为和验证方式。
对于订单导出，规格可以短到一页，但必须覆盖关键风险：
| 规格部分 | 需要说明的问题 |
|---|---|
| 目标 | 运营为什么需要导出，导出结果用于什么 |
| 范围 | 支持哪些筛选、格式和字段，不支持什么 |
| 权限 | 谁能导出，无权限时页面和接口怎么表现 |
| 数据边界 | 哪些字段允许导出，哪些敏感字段禁止导出 |
| 失败路径 | 空结果、超量、服务异常、下载失败如何处理 |
| 验证方式 | 哪些测试、构建、人工检查必须通过 |
这些内容足以指导模型实现，也足以指导人类 review。
规格如何变成测试
Spec-Driven 的关键是让规格尽量可执行。不是所有规格都能完全自动化，但越多标准能进入测试，后续改动越稳定。
| 规格 | 可验证方式 |
|---|---|
| 无权限用户不能导出 | 权限单元测试和接口 403 测试 |
| 只导出字段白名单 | CSV 表头测试和敏感字段扫描 |
| 空结果生成表头 | 空数据用例测试 |
| 筛选条件与列表一致 | 前端参数组装测试或接口参数测试 |
| 超过 1 万行提示缩小范围 | 服务端边界测试和页面错误态测试 |
| 导出失败可重试 | UI 状态测试或端到端测试 |
测试不是为了替代规格，而是让规格有执行入口。规格改了，测试也要随之更新；测试失败，说明实现和规格至少有一个需要修正。
成功路径、边界路径和失败路径
很多导出功能只验证成功路径：有数据、有权限、数据量不大、网络正常。真实系统的问题通常出现在边界和失败路径。
订单导出至少要写清楚三类路径：
| 路径 | 例子 |
|---|---|
| 成功路径 | 有权限运营按支付时间导出 300 条已支付订单，下载 CSV 成功 |
| 边界路径 | 查询结果为空、金额为 0、字段中包含逗号和换行、导出接近 1 万行 |
| 失败路径 | 无权限、查询超量、服务端异常、文件生成失败、浏览器下载被中断 |
边界路径和失败路径决定了功能能不能进入生产。它们也能帮助模型避免只写“阳光场景”。
规格与提示词、上下文、Harness 的关系
提示词是规格的一次执行表达。它告诉模型这次任务要满足哪些标准。上下文是规格的证据来源，让模型知道这些标准在当前项目里如何落地。Agent 负责按规格执行并验证。Harness 则把部分规格变成强制规则，例如 CI 检查、权限测试、敏感字段扫描和人工确认点。
同一条规格可以在不同层次出现：
text
规格：订单导出不能包含手机号。
提示词：禁止导出 mobile、phone、receiverPhone 等字段。
上下文：订单字段说明中标记手机号为敏感字段。
测试：CSV 表头和内容不得包含手机号字段。
Harness：导出相关 PR 必须通过敏感字段扫描。
Review：检查是否绕过字段白名单。这样，规格不只是文档，而是贯穿实现链路的约束。
规格变更也要受控
开发中可能发现原规格不合适。例如运营后来要求增加“支付渠道”字段，或者财务要求导出 Excel。规格可以改，但不能悄悄改代码绕过去。
规格变更应至少记录三件事：
- 改了什么，例如新增支付渠道字段。
- 为什么改，例如对账需要按渠道分组。
- 如何验证，例如补充字段白名单测试和导出样例。
高风险变更还需要额外 review。比如新增手机号、详细地址、内部备注等字段，不应只由实现者决定。
规格粒度
不同任务需要不同粒度：
| 任务类型 | 规格粒度 |
|---|---|
| 原型导出按钮 | 写清入口、字段、格式和限制即可 |
| 真实后台导出 | 补充权限、失败、测试和性能边界 |
| 涉及敏感字段 | 增加字段审批、审计日志和安全 review |
| 大批量异步导出 | 增加任务状态、重试、过期清理、监控和回滚 |
规格的目标不是增加流程，而是让复杂度与风险匹配。
Review 的标准
Spec-Driven 的 review 不应只问代码是否整洁，还要问规格是否满足：
- diff 是否只改了规格允许的范围。
- 字段白名单是否和规格一致。
- 无权限、空结果、超量、失败重试是否有测试。
- 新增依赖是否必要，是否引入安全或维护风险。
- 验证命令是否运行，失败项是否解释清楚。
- 规格本身是否需要更新。
当 review 围绕规格展开，争议会更少，修改意见也更容易落地。
总结
Spec-Driven 把“感觉完成”改成“规格满足”。订单导出的完成标准不是按钮、接口或文件本身，而是完整行为是否满足事先写清楚的规则。
在 AI 编程中，规格越清楚，模型越少猜测；验证越可执行，交付越少依赖人工反复试错。规格、上下文、Agent 和 Harness 结合起来，才能把快速产出变成可靠交付。
→ 回到首页