建模即意图之AI Coding高价值软件白皮书

建模即意图之高价值软件白皮书

面向对象：架构师、研发部门管理者

摘要

在 AI Coding 快速普及的背景下，代码生成能力正在迅速商品化。越来越多的团队已经可以借助模型、模板、脚手架和自动化工具快速产出大量代码，但真正决定软件长期价值的，已不再是“能否更快生成代码”，而是“生成出来的软件是否具有持续业务价值”。

本白皮书认为，所谓高价值软件，不在于代码量大、功能数量多，或短期交付速度快，而在于其是否具备以下能力：清晰承载业务边界、稳定表达核心意图、支持持续演进、具备审计与复盘能力、支持跨团队协作，并能够在 AI 时代持续吸收自动化带来的效率红利。

为此，本白皮书提出一个核心判断：

在 AI Coding 时代，建模即意图，是构建高价值软件的前置条件。

换言之，软件要具备长期价值，组织必须先将系统真正承认的业务动作、流程边界、状态依赖和结果产出清晰建模，再让代码生成、模板扩展、adapter 脚手架和 AI 自动化去承载这些意图。

1. 高价值软件的定义：区别于 vibe coding 的日抛软件

1.1 什么是高价值软件

高价值软件，不是“短时间能跑起来的软件”，而是“能够长期承载业务、稳定演进并跨团队复用的软件系统”。

它通常具备以下特征：

1. 业务表达清晰

系统的核心能力能够被清楚表达为一组业务动作，而不是一组松散的技术模块。

2. 边界稳定

业务边界不会因为一次接口改造、一次框架升级或一次服务拆分而整体失真。

3. 结构可演进

新增需求时，可以围绕既有边界做局部扩展，而不需要每次全局返工。

4. 结果可审计

系统能够稳定回答：

• 谁做了什么
• 为什么成功
• 为什么失败
• 哪个规则决定了当前结果

5. 组织可复用

不同团队可以围绕同一套模型语言协作，而不是每个团队重新定义自己的业务表达。

6. AI 可放大

AI 可以在既有模型约束下稳定出码，而不是将错误边界和短期便利性放大成长期架构问题。

1.2 什么是日抛软件

与高价值软件相对的，是“日抛软件”。

这里的“日抛”，并非指代码只使用一天，而是指这类软件虽然当下能跑，但不具备持续积累价值：

• 短期可用，但不值得沉淀
• 一改就散，一扩就乱
• 一旦换团队，维护成本迅速升高
• 每次需求变化都更依赖个体经验而不是结构化模型

这类软件通常具备以下表现：

• 系统以 handler、gateway、consumer 为主角，而不是业务动作
• 业务边界只能从代码中反推
• 设计评审只能讨论实现细节，无法稳定讨论意图与边界
• 代码每次变更都容易产生连锁反应
• AI 越容易生成代码，系统越快膨胀和失控

1.3 高价值软件与日抛软件的对照

维度	高价值软件	日抛软件
业务表达	以意图、角色、状态、结果组织	以接口、协议、技术组件组织
边界	明确、稳定、可评审	模糊、漂移、依赖实现习惯
演进	局部可控	改一处动全局
审计	有结构化解释链	依赖口述和代码猜测
组织协作	共用一套模型语言	各团队各说各话
AI 作用	放大正确结构	放大混乱结构

因此，高价值软件的根本，不在于“写得更快”，而在于“组织是否有能力稳定表达业务意图”。

2. SDD 的主要问题

很多组织已经做了规格驱动设计、流程建模、需求说明、接口文档和模板化开发，但最终并没有形成高价值软件资产。

根本原因通常不在于“没有文档”，而在于“文档没有真正固定住业务意图”。

2.1 实现先行

设计讨论往往从如下问题开始：

• API 如何设计
• 数据表如何拆分
• MQ 如何接入
• Gateway 如何实现

而不是从“系统承认哪些业务动作”开始。

结果是：

• 实现先走
• 文档被动补齐
• 业务边界依赖代码反推

2.2 边界漂移

如果没有先定义流程域和 Use Case，系统边界就会持续被以下因素改写：

• 微服务拆分方式
• 当前框架能力
• 接口协议习惯
• 团队短期实现便利性

2.3 用例碎片化

很多内部步骤被误建模成伪 Use Case：

• 序列化
• 转发
• 入队
• 签名
• 校验
• 调第三方接口

这样产出的并不是高价值模型，而是一份技术步骤清单。

2.4 角色技术化

模型中出现的主要角色变成了：

• Handler
• Gateway
• Consumer
• Engine
• Worker

而不是：

• Trader
• Clearing
• Validator
• Auditor

一旦角色技术化，授权、审计和责任链都会失焦。

2.5 审计困难

如果输入、状态、约束、结果没有被结构化表达，系统就难以稳定回答：

• 谁做了什么
• 为什么通过
• 为什么拒绝
• 哪个规则决定了当前结果

2.6 演进高风险

流程、规则和实现混在一起时，任何局部改动都可能影响整个系统。

最终，SDD 变成了“文档不少，但系统依然脆弱”。

这说明：

传统 SDD 如果没有意图层，仍然无法稳定产出高价值软件。

3. 引入建模即意图的原因

“建模即意图”要解决的核心问题，是在人和 AI 进入实现之前，先把系统真正承认的业务边界、流程边界和职责边界固定下来。

它强调三件事：

1. 先定义意图，再展开实现
2. 先定义边界，再生成代码
3. 先定义业务角色，再映射技术组件

因此，建模不是编码前的附属动作，而是高价值软件的约束起点。

可以将其理解成一条从业务到代码的表达链：

业务价值
  -> 流程域
  -> Use Case
  -> 状态 / 约束 / 结果
  -> adapter / protocol / infra
  -> code

如果前半段不清楚，后半段只会更快地产生混乱。

如果前半段清楚，AI、脚手架和模板就会成为稳定放大器。

因此，“建模即意图”并不是多一套文档，而是在组织层面建立一个从业务理解到工程落地的稳定中间层。

4. 主要流程

为了让“建模即意图”真正落地为高价值软件生产方式，建议将研发链路拆成三个连续阶段：

1. 建模
2. 出码
3. 模型刷新

4.1 建模

建模阶段是核心设计工作，其目标是把系统真正承认的业务意图固定下来。

流程建模：生成 XPDL

流程建模的本质，接近很多大型金融软件组织中的“业务功能树”或“业务流程树”的工程化版本。

五级流程建模中的流程组织层，适合用 XPDL 表达。

XPDL 主要承载：

• 流程域划分
• WorkflowProcess 边界
• Activity 的顺序与依赖
• Performer 的挂接
• 跨流程产物衔接

它主要回答：

• 哪些动作属于同一个流程域
• 哪些动作先发生
• 哪些动作后发生
• 哪些结果进入下一段流程

核心 Use Case 详细建模：生成 Markdown 文档

单个核心 Use Case 最适合用 Markdown 表达。

一个完整的 Use Case 文档，至少应回答：

• Performer
• Command / Query
• GivenState
• Invariant
• Port
• Output
• Error

它解决的是：单个业务意图的边界到底是什么。

一个详细例子：XPDL 与 Use Case 文档

示例一：交易流程 XPDL

<PackageId="TradingDomain"Name="Trading Domain">
<WorkflowProcesses>
<WorkflowProcessId="TradingFlowProcess"Name="Trading Flow Process">
<Activities>
<ActivityId="PlaceOrdersUseCase"Name="PlaceOrdersUseCase">
<Performer>Trader</Performer>
</Activity>
<ActivityId="MatchOrdersUseCase"Name="MatchOrdersUseCase">
<Performer>Matching</Performer>
</Activity>
<ActivityId="ClearTradesUseCase"Name="ClearTradesUseCase">
<Performer>Clearing</Performer>
</Activity>
</Activities>
<Transitions>
<TransitionId="T1"From="PlaceOrdersUseCase"To="MatchOrdersUseCase"/>
<TransitionId="T2"From="MatchOrdersUseCase"To="ClearTradesUseCase"/>
</Transitions>
</WorkflowProcess>
</WorkflowProcesses>
</Package>

示例二：PlaceOrdersUseCase Markdown

# PlaceOrdersUseCase

## Performer
Trader

## Goal
交易者提交一组订单意图，系统决定是否接受这些订单。

## Command
- account_id
- market_id
- orders[]

## GivenState
- Account
- Market
- Position
- RiskProfile

## Invariant
- account is active
- market is tradable
- order price and quantity are valid
- risk limit is not exceeded

## Port
- LoadAccountPort
- LoadMarketPort
- LoadRiskPort
- PersistOrdersPort

## Output
- OrdersPlacedEvent
- AcceptedOrderIds

## Error
- AccountDisabled
- MarketClosed
- RiskLimitExceeded
- InvalidOrder

4.2 出码

出码阶段的目标，不是“尽快写代码”，而是让已经确认好的模型稳定映射到代码结构。

脚手架化生成 adapter

adapter 层最适合通过脚手架生成，而不是依赖团队重复手工搭建。

adapter 脚手架通常负责：

• 外部协议映射
• DTO / mapper / reply
• HTTP / queue / DB / RPC 接入
• 最小目录结构和占位实现

引入改良后的 clean 架构：core 与 adapter 两层

建议将结构收敛成两层：

• core
• adapter

职责划分如下：

• core：承载流程域、Use Case、状态、约束、事件等业务核心
• adapter：承载外部接口、协议转换、传输对象和基础设施接入

可以进一步这样映射：

• XPDL 映射业务流，对应多个 core API 边界
• Use Case Markdown 映射一个具体 API 的签名、逻辑、状态和事件
• 模板与脚手架把这些结构展开成稳定代码骨架

一个较详细的出码例子

核心接口可以表达为：

pubtraitPlaceOrdersApi {
typeCommand;
typeOutput;
typeError;

fnexecute(&self, command: Self::Command) ->Result<Self::Output, Self::Error>;
}

adapter 层则负责展开：

• PlaceOrdersHttpHandler
• PlaceOrdersRequestDto
• PlaceOrdersResponseDto
• PlaceOrdersMapper
• PersistOrdersGateway

4.3 代码变更后主动刷新建模文档

高价值软件不是靠第一次设计就完成的，而是依赖持续演进中仍然保持边界有效。

因此，模型必须跟随代码变化主动刷新。

下面几类变化发生后，应主动回写模型：

• 新增核心 Use Case
• 删除核心 Use Case
• 调整流程域边界
• 修改关键 Performer
• 修改 GivenState / Invariant / Output
• 新增关键事件或状态依赖
• 改变 core / adapter 边界

如果模型不刷新，组织很快会回到以下状态：

• 文档失真
• 评审脱节
• 培训失效
• AI 失去稳定上下文

5. 主要涉及的方法论

“建模即意图之高价值软件”不是一种孤立方法，而是把多套成熟思想组织成一条工程化链路。

5.1 五级流程建模

帮助团队区分：

• 业务价值链
• 流程域
• 业务活动 / Use Case
• 任务与流转关系
• 系统细节与操作步骤

5.2 领域建模 / 四色建模

帮助团队识别：

• 稳定实体
• 业务角色
• 关键事件
• 规则描述

5.3 clean 架构

它在这里的作用不是教条分层，而是：

• 让 core 留住高价值业务能力
• 让 adapter 吸收变化与外部接入
• 让系统边界对 AI 保持清晰约束

5.4 事件溯源

在高审计、高追踪、高一致性系统中，事件溯源和“建模即意图”天然互补。

5.5 CQRS

CQRS 与 Use Case Markdown 中的 Command / Query 表达天然兼容。

它的价值在于：

• 命令边界更清晰
• 查询职责更稳定
• 模板代码结构更统一

6. 使用场景

下表根据不同场景对其投资回报率进行评级

“建模即意图”不是所有项目都要全量采用。它是一项工程投资，更适合以下场景：

等级	场景	说明
★★★★★	规模化、标准化交付	需要长期维护的大量重复性业务逻辑，例如大量相似 API、核心工作流自动化。
★★★★★	高合规、高约束系统	金融核心系统、多端一致交付、强审计与安全约束场景。
★★★★☆	团队协作与可审计交付	多人协作，需要完整变更追踪和评审闭环。
★★★★☆	跨域一致性改造	多服务、多语言之间要长期保持逻辑一致的复杂重构。
★★☆☆☆	生产止血式热修复	当速度远比一致性重要时，完整方法投入偏重。
★★☆☆☆	探索性原型	目标只是快速验证想法，而不是沉淀生产资产。
★★☆☆☆	一次性脚本	前期建模成本可能高于收益。
★☆☆☆☆	领域定义不清	业务边界尚未形成共识，模型无法稳定成立。
★☆☆☆☆	纯创意型工作	以审美和探索为核心，而不是规则和约束为核心。

7. 投资回报率

对组织的核心收益

益处	影响	速度	你将获得什么
决定论	高	即时	把业务逻辑编码进精确规范中，减少 AI 和人工实现中的自由发挥。
可追溯性	高	即时	每一次关键变更都能追溯到结构化模型与文档。
更快的评审	高	短期	评审重点回到逻辑、边界和设计，而不是格式和样板。
可解释性	中高	逐步显现	业务意图、角色、状态和结果在文档层面可见，降低认知成本。
更安全的演进	高	长期	把系统改动限制在清晰边界内，降低架构演进风险。

投资回报率的本质

高价值软件的 ROI，本质不是“少写了多少代码”，而是：

• 少走了多少弯路
• 少犯了多少方向性错误
• 少制造了多少未来难以清理的技术资产负债

8. 前期投入

高价值软件不是零成本获得的。前期投入主要集中在：

区域	障碍	节奏	需要什么
思维转变	高	持续投入	团队从“先写实现”切换到“先定义意图”。
前期资深专家	中高	按功能推进	需要能把业务规则转成清晰抽象和约束的架构师 / 高级工程师。
自动化工具	中等	基础设施搭建	需要模板、脚手架、流程工具保证模型、文档和代码的一致性。

如果没有自动化，建模成本容易变成组织负担。

如果有稳定工具链把 XPDL、Use Case Markdown、adapter 脚手架和代码模板串起来，那么这些工件就能进入版本控制、设计评审和持续演进，而不是停留在会议纪要和聊天记录里。

9. 结语

AI 时代，代码生成能力会越来越便宜，但高价值软件不会因此自动产生。

真正决定软件是否具有长期价值的，不是出码速度，而是组织是否有能力在出码之前，先把系统真正承认的业务意图建清楚。

因此，这篇白皮书的核心主张可以压缩成一句话：

建模即意图，是高价值软件的前置条件。

如果这条工程链成立：

业务价值
  -> 流程模型
  -> Use Case 文档
  -> core / adapter
  -> 代码落地
  -> 模型刷新

那么 AI 会成为高价值软件的放大器。

如果这条工程链不存在，AI 只会更快地放大混乱。

因此，对于架构师和研发管理者而言，真正重要的问题不再是：

“我们能不能更快生成代码？”

而是：

“我们能不能先把真正有价值的软件意图定义清楚？”

这正是“建模即意图之高价值软件”的核心含义。