⁶

关于业务规范文档（spec）的思考（VibeCoding，写的太乱让 gpt 整理了一下）

花水木

2026-04-02 17:37

阅读1287

花水木

2026-04-02 17:37

阅读 1287

spec 业务规范文档：为什么先定义业务域，而不是先讨论实现

一、这份文档要解决什么问题

这份 spec 文档的目的，不是描述代码如何实现，而是统一技术、产品、业务专家对同一业务域的理解，作为后续技术维护、产品 review、需求讨论和系统演进的共同基础。

它希望回答以下问题：

当前业务域有哪些核心领域对象
当前业务域的边界是什么：应该关心什么，不应该关心什么
当前业务域有哪些不变量和核心业务规则
当前业务域有哪些典型场景
当前还有哪些待确认问题和争议点

其中，第 5 点尤其重要： 待确认问题必须被显性记录下来，避免团队在未达成共识时形成隐性假设。

▼
mermaid
复制代码
mindmap
  root((spec 文档目标))
    统一术语
    明确边界
    沉淀核心规则与不变量
    描述典型场景
    记录待确认问题

二、为什么要先把业务域说清楚

我想表达的并不是“代码不重要”，而是：

代码实现不是业务共识的起点，领域对象、边界、核心规则和不变量才是。

对于业务系统来说，真正有长期价值的，往往不是某一版实现，而是系统中那些相对稳定、不会轻易变化的业务约束。

在没有 AI 的时候，这一点就已经成立；在有了 AI 之后，实现成本进一步下降，这反而会放大另一件事的重要性：

如果业务域本身没有定义清楚，那么实现越快，偏离业务本质的速度也可能越快。

代码可以重构，页面可以改版，流程可以调整；但如果业务规则没有被清晰定义，那么产品、技术、业务就很容易在“好像已经理解了”的前提下继续推进，最终不断提出彼此冲突、实现成本高、甚至难以落地的需求。

▼
mermaid
复制代码
flowchart LR
    A[业务目标] --> B[领域对象]
    B --> C[领域边界]
    C --> D[核心规则与不变量]
    D --> E[典型场景]
    E --> F[产品设计]
    F --> G[技术实现]
    G --> H[代码与交付]

    X[前面没定义清楚] --> Y[需求歧义]
    Y --> Z[高成本返工]

三、对业务系统来说，什么最重要

对于一个业务系统，最重要的不是某个页面，也不是某一段代码，而是系统中那些不变的、核心的业务规则。

这些规则决定了：

什么样的数据可以进入这个领域
数据在这个领域中应该被如何解释
业务统计和业务判断建立在什么前提之上
当新需求进入时，如何判断它是否合理、是否破坏现有领域模型

换句话说：

真正需要优先沉淀的，不是实现细节，而是业务域的共同语言、边界、核心规则和不变量。

▼
mermaid
复制代码
flowchart TD
    A[核心业务规则] --> B[定义可进入的数据]
    A --> C[定义数据解释方式]
    A --> D[定义统计与判断前提]
    A --> E[定义新需求是否合理]

四、一个例子：事件驱动的行为分析领域

以一个多数据源集成的分析系统为例。系统需要基于各种业务数据，分析一个人做过什么事情，例如：

某终端一周总共打印了多少次
某用户在某时间段内发生了哪些打印行为

在这个领域里，一个关键且不应轻易变化的规则是：

参与行为分析的数据，必须是“业务事件”，而不是“业务状态”。

术语定义

业务事件：已经发生的业务事实例如：用户打印了 3 份文件
业务状态：某一时刻对象的当前信息例如：某终端当前累计打印了 120 份文件

两者的差别在于：

业务事件描述的是“发生了什么”
业务状态描述的是“当前是什么样”

▼
mermaid
复制代码
flowchart TD
    A[业务数据] --> B{数据类型判断}
    B -->|已经发生的事实| C[业务事件]
    B -->|某一时刻的当前信息| D[业务状态]

    C --> E[可直接参与行为分析]
    D --> F[需先转换/还原/映射]
    F --> E

如果系统要做的是行为分析、过程还原、次数统计，那么分析基础就应该是事件。因此，即使某个新接入的数据源提供的只有“状态数据”，例如“当前累计打印份数”，那么在进入该分析领域之前，也应该先把它转换、还原或映射为能够被该领域理解的“事件表达”；否则，它就不应该直接参与同一套分析逻辑。

这类约束，才是真正应该在 spec 中被明确写下来的内容。因为它不是某个接口怎么写的问题，而是这个业务域成立的前提。

▼
mermaid
复制代码
flowchart LR
    A[外部数据源] --> B[原始数据接入]
    B --> C{是否为业务事件}
    C -->|是| D[进入行为分析领域]
    C -->|否，是业务状态| E[事件化转换]
    E --> D

    D --> F[行为统计]
    D --> G[过程还原]
    D --> H[行为分析]

    I[纯状态展示需求]
    I -. 不属于本领域核心分析逻辑 .-> D

五、想跟大家一起讨论一下

如果认可： 对于业务系统来说，领域边界、核心规则和不变量，比实现细节更值得优先定义。

那么接下来真正关键的问题就是：

作为业务专家，应该如何把这些内容描述清楚，既让产品经理能看明白，又能减少后续提出脱离领域约束、实现代价高甚至难以落地的需求？

我的理解是，这类文档至少要做到以下几点：每个核心域的 Spec 可以采用类似结构：

▼
text
复制代码
1）领域背景
说明这个核心域解决什么业务问题，为什么存在。

2）术语定义
列出核心概念及其定义。

3）领域对象与边界
描述本域关注哪些对象，不关注哪些对象。

4）核心业务规则
列出规则、适用条件、例外和优先级。

5）不变量
列出必须始终成立的约束。

6）状态与状态变化
描述各状态的业务含义及主要迁移约束。

7）典型场景
用业务场景解释规则的应用方式，但不写成测试脚本。

8）待确认问题
记录仍存在争议或待补充的规则，避免形成隐性假设。

▼
mermaid
复制代码
flowchart TD
    A[术语清晰] --> E[讨论基于同一语言]
    B[边界清晰] --> F[需求不会越界]
    C[规则清晰] --> G[实现不偏离业务本质]
    D[待确认问题显性化] --> H[避免默认假设推进]

    E --> I[减少反复沟通]
    F --> I
    G --> I
    H --> I

六、结论

我更倾向于这样理解 spec 文档的价值：

spec 不是实现说明书，而是业务域共识文档。

它的价值不在于把“怎么做”写得多细，而在于把以下内容说清楚：

这个领域里有哪些核心对象
这些对象分别代表什么
这个领域的边界在哪里
哪些规则是不能被破坏的
哪些问题目前还没有达成共识

AI 会降低实现成本，但不会替代领域建模。相反，越是实现变得容易，越需要先把业务本质定义清楚。否则，后续的需求讨论、产品设计和技术实现，就都可能建立在模糊理解和隐性假设之上。

▼
mermaid
复制代码
flowchart TD
    A[spec 不是实现说明书]
    A --> B[是业务域共识文档]
    B --> C[统一术语]
    B --> D[明确边界]
    B --> E[沉淀核心规则]
    B --> F[记录争议与待确认问题]
    C --> G[减少歧义]
    D --> G
    E --> G
    F --> G