AI SDD 开发规范-35-如何拆分巨大的详细设计?
2025/12/27大约 4 分钟
如何拆分巨大的详细设计?
这是一个架构与认知层面的问题，不是“文档排版技巧”，而是如何把一个“大而混”的详细设计，拆成 AI 与人都能稳定执行的“最小认知单元”。
我从 拆分原则 → 常见拆分维度 → 可操作拆分技巧 → 一个完整示例 四个层面回答。
一、先给结论：详细设计“变大”的根因是什么？
不是功能多，而是“维度混叠”。
一个设计之所以显得“巨大”，通常是因为在同一份文档里同时讨论了：
- 做什么（What）
- 为什么（Why）
- 怎么做（How）
- 谁负责（Who）
- 异常怎么办（Edge / Risk）
- 与哪些系统交互（Integration）
人和 AI 都会被迫在多个维度来回切换，认知负载指数级上升。
拆分的目标不是“切碎”，而是一维一文档、一文档一目的。
二、拆分的第一性原则（非常重要）
原则 1：一个文档只回答一个核心问题
| 文档类型 | 只回答 |
|---|---|
| OVERVIEW.md | 这个需求是什么、边界在哪里 |
| FLOW.md | 流程如何走 |
| DATA.md | 数据怎么变 |
| INTERFACE.md | 外部怎么调用 |
| RULES.md | 业务规则是什么 |
| EXCEPTION.md | 异常与兜底 |
| RISK.md | 风险与不确定性 |
禁止在一个文档里“顺带提一下另一个维度”。
原则 2：拆分不是“分页”，而是“解耦关注点”
错误的拆分：
- 第 1～10 页：设计说明
- 第 11～20 页：设计说明（续）
正确的拆分：
- 主流程一份
- 数据一份
- 异常一份
原则 3：主文档必须“轻”，重内容全部下沉
主设计文档（DESIGN.md）应该满足：
10 分钟能看完 + 不需要滚动太多
否则必拆。
三、六种“稳定有效”的拆分维度（可组合使用）
下面这些，是我在复杂系统、历史包袱项目、AI 编程场景中最稳定的拆分方式。
1️⃣ 按「认知阶段」拆分（最通用）
把设计拆成人理解的顺序：
- 目标
- 非目标
- 成功标准
- 主流程
- 子流程
- 状态流转
- 每一步如何实现
适合：
- 新功能
- 跨团队协作
- AI 先读文档再写代码
2️⃣ 按「流程主干 vs 分支」拆分
规则：
主流程独立成文档，任何 if / else 都不许出现在主流程文档中
结构示例：
DESIGN/
├── FLOW_MAIN.md
├── FLOW_REFUND.md
├── FLOW_RETRY.md
├── FLOW_TIMEOUT.md好处：
- 主流程极其清晰
- 分支可以单独演进
- AI 不会在主路径里迷路
3️⃣ 按「数据视角」拆分（强烈推荐）
很多“文档很大”的项目，本质是数据变化写得到处都是。
正确方式：
DATA/
├── MODEL.md # 核心模型
├── STATE.md # 状态机
├── MIGRATION.md # 变更影响然后在流程文档中只写：
“此步骤导致 Order 状态从 PAID → SHIPPED（详见 DATA/STATE.md）”
4️⃣ 按「稳定性」拆分（AI 非常吃这一套）
| 类型 | 特点 |
|---|---|
| STABLE.md | 几乎不会变 |
| VARIABLE.md | 高频变化 |
| EXPERIMENT.md | 不确定 |
AI 执行顺序：
- 锁定 STABLE
- 重点关注 VARIABLE
- 对 EXPERIMENT 保守实现
这是降低 AI 发散的关键技巧。
5️⃣ 按「角色 / 职责」拆分（复杂协作系统）
例如：
DESIGN/
├── USER_FLOW.md
├── ADMIN_FLOW.md
├── SYSTEM_FLOW.md或者：
SERVICE/
├── ORDER_SERVICE.md
├── PAYMENT_SERVICE.md每个文档只描述“该角色 / 该服务视角下的世界”。
6️⃣ 按「风险密度」拆分（非常适合历史系统）
把风险最高的部分单独拎出来：
RISK/
├── LEGACY_COMPAT.md
├── DATA_CORRUPTION.md
├── PERFORMANCE.md主设计文档只引用，不展开。
四、几个“立竿见影”的拆分技巧（很实用）
技巧 1：超过 3 层标题，立即拆
如果你看到：
### 3.2.1.4 xxx 场景下的处理这是一个确定的拆分信号。
技巧 2：凡是“重复出现的词”，都该独立成文档
例如：
- “状态”
- “幂等”
- “重试”
- “补偿”
出现 3 次以上，说明这是一个独立关注点。
技巧 3：流程图和文字分家
不要混在一起。
技巧 4：让 AI 帮你“找拆分点”
一个非常好用的提示词：
“请识别以下设计中混合的不同关注点，并给出可拆分的文档结构建议。”
AI 在结构分析上比人稳定。
五、一个“从大到小”的完整示例
原始状态（典型问题）
DESIGN.md（30 页）
- 背景
- 接口
- 流程
- 状态
- 异常
- 补偿
- 风控拆分后
DESIGN/
├── README.md # 总入口（必读）
├── OVERVIEW.md
├── FLOW_MAIN.md
├── FLOW_EXCEPTION.md
├── DATA_MODEL.md
├── STATE_MACHINE.md
├── INTERFACE.md
├── RISK.mdREADME.md 只做导航，不承载细节。