如何构造 SSOT 九层金字塔模型：一套可复用的 SSOT 原则
如何构造 SSOT 九层金字塔模型：一套可复用的 SSOT 原则
一套和具体业务无关的 SSOT 九层金字塔模型构造方法：让 AI agent、产品、运营、销售、客服/支持和研发围绕使命、战略、承诺、Flow、contract、实现和 evidence 共享同一套事实模型。
如何构造 SSOT 九层金字塔模型：一套可复用的 SSOT 原则
不要从“要建几个目录”开始设计 SSOT 九层金字塔模型。先问一个更尖锐的问题：当战略、产品、代码、测试和发布证据发生冲突时，团队用什么规则判断谁才是当前事实？
如果这个规则说不清，目录越多，事实越分裂；文档越勤奋，AI 和人越容易读出多个互相矛盾的系统。
这篇文章是 SSOT 九层金字塔模型的原则说明。它不依赖某个具体产品，也不要求你照搬我们的目录结构。它回答的是一个更通用的问题：
一个复杂软件团队，如何构造自己的 SSOT 九层金字塔模型？
如果你想先理解为什么我认为所有软件工程原则最后都在谈 SSOT，可以先读上一篇：
SSOT：为什么所有软件工程原则最终都在谈同一件事
本文只讲方法：根目标是什么，九层分别是什么，团队如何强制自顶向下阅读、自底向上更新，以及如何避免文档、代码、测试、日志、发布证据在不同历史阶段里互相打架。
根目标
SSOT 九层金字塔模型的目标不是新增一张系统组件图，而是把产品目标、当前战略、对外承诺、体验流程、领域模型、系统边界、接口契约、代码实现和证据闭环放在同一个可追踪模型里。
它要回答的不是“系统有哪些模块”，而是：
- 这个产品为什么存在？
- 当前阶段优先赢什么？
- 团队对用户和自己承诺什么？
- 真实任务如何完成？
- 稳定概念和不变量是什么？
- 系统边界在哪里？
- 可执行 contract 是什么？
- 代码如何实现？
- 什么 evidence 证明这些事实成立？
一句话概括：
SSOT 九层金字塔模型是团队业务、产品、技术决策的 up-to-date snapshot。
它的存在，是为了强迫人和 AI 对所有进入思考范围的事务和概念做优先级排序。
它也给非开发同事一张共同地图：当前战略是什么、哪些能力可以承诺、真实 workflow 如何运转、哪些 evidence 能证明它们，而不是让大家从会议、旧计划和某个工程师的即时回答里拼当前事实。
九层定义
| 层级 | 核心问题 | 典型 SSOT |
|---|
| L1 使命 | 产品为什么存在？长期要成为什么？ | 使命文档、公司级产品叙事 |
| L2 战略 | 当前阶段优先赢什么？资源如何分配？ | 当前优先级、资源竞争、路线图 |
| L3 承诺 | 对用户和团队承诺支持什么？ | 对外文案、支持边界、发布声明 |
| L4 Flow | 所有利益相关方如何完成真实任务？ | 用户流程、AI agent 流程、产运研流程、发布流程、客服/支持流程 |
| L5 领域模型 | 稳定概念、状态、权限、计费和不变量是什么？ | 领域对象、状态归属、权限、计费规则 |
| L6 系统边界 | 入口、能力、runtime、云端产品面、外部服务如何分工？ | 架构边界图、调用方向、职责约束 |
| L7 Contract | 接口、数据库、环境变量、权限、发布流程的合同是什么？ | API、数据库、环境变量、权限、发布合同 |
| L8 实现 | 代码、脚本、迁移、组件、自动化如何落地？ | 代码、脚本、迁移、自动化、配置 |
| L9 Evidence | 测试、日志、检查、发布证据如何证明前面八层成立？ | 测试、日志、状态检查、发布证据、线上事实 |
越往上，越接近“为什么”和“对外承诺”；越稳定，越少变，改变时越需要谨慎。
越往下，越接近“怎么实现”和“怎么证明”；越具体，越多变，越依赖自动化和 evidence。
唯一顶层模型
SSOT 九层金字塔模型必须是团队理解和讨论任何问题的唯一顶层模型。
专题文档可以存在，比如架构文档、工作计划、运维文档、设计文档、测试文档，但它们不能成为平行的顶层事实系统。每个专题文档都必须声明自己主要属于哪一层、服务哪些层、记录的是稳定事实还是当前工作、由什么 evidence 证明。
否则，一个团队很快就会拥有多套互相竞争的解释框架：
- 架构文档说一套。
- 产品路线图说一套。
- 测试文档说一套。
- 发布文档说一套。
- 会议纪要又说一套。
阅读必须自顶向下
任何人或 AI 在理解一个问题时，都必须先自顶向下：
- 先确认使命。
- 再确认当前战略。
- 再确认对外承诺。
- 再确认真实 Flow。
- 再确认领域模型。
- 再确认系统边界。
- 再确认 contract。
- 最后才进入实现和 evidence。
这条规则防止团队用代码细节反向定义产品，也防止 AI 读到某个局部文件后误以为它代表全局。
对产品、运营、销售、客服/支持同事来说，这条规则也能防止旧方案、过期发布说明或 legacy 排查路径被误当成当前战略或当前承诺。
- 如果一个页面还在，不能说明它仍是当前战略。
- 如果一个接口还在，不能说明它仍是用户承诺。
- 如果一个测试还在跑，不能说明它仍保护当前主线。
- 如果一个 POC 能跑，不能说明它已经是产品能力。
更新必须自底向上
- 先更新代码、脚本、数据库、配置、自动化。
- 再更新测试、日志、状态检查、发布证据。
- 如果实现变化改变了可执行 contract，再更新 contract 层。
- 如果 contract 改变了组件分工、状态归属或跨边界调用，再更新系统边界和领域模型。
- 如果领域或边界变化改变了用户、AI agent、发布 operator、客服/支持、销售或开发者可以依赖的能力，再更新 Flow 和承诺。
- 如果承诺变化改变了资源选择或长期产品身份，再更新战略和使命。
只有当底层变化真实改变上层语义时，才修改上层文档。
这条规则同样重要：它防止团队因为一个小脚本、一次 demo、一个临时客户需求，就把 POC 过早提升成战略。
反例和正确做法
下面这些不是罕见事故，而是复杂团队每天都会发生的事实分裂。
| 场景 | 错误做法 | 九层落点 | 正确做法 |
|---|
| AI agent 读到旧 README | 让 agent 从最近文件开始，自行综合旧战略、新代码和旧测试 | L2 战略：当前核心能力；L4 Flow：agent 阅读顺序；L8/L9：旧 README 和旧测试是否仍属于当前实现/evidence | 先更新 L2 和 L4，让 agent 明确从九层入口开始；再把旧 README 和旧测试在 L8/L9 标成 legacy、改成链接，或删除 |
| POC 被写进 BP 或官网 | 只要 demo 能跑，就把能力写成“已支持” | L3 承诺：是否可对外承诺；L7 Contract：输入、状态、失败语义；L9 Evidence：发布证据；必要时 L2 战略：是否成为资源优先级 | 只有 L3 写清支持边界、L7 有可执行 contract、L9 有 release evidence 后，才允许进入 BP、官网、demo 和销售话术 |
skill 已升级为 workflow，但命名没变 | 继续保留旧字段、旧日志、旧测试名，靠口头解释新语义 | L5 领域模型：workflow 是否是一等概念；L7 Contract：字段/API 语义；L8 实现：符号、schema、日志名；L9 Evidence：测试断言 | 先在 L5 改领域中心，再同步 L7-L9 的命名、contract、日志和测试；不能只靠口头说明新语义 |
| 内部 API 被多个入口依赖 | 仍按内部实现随意改字段 | L6 系统边界：谁拥有 API、谁调用；L7 Contract：schema、调用方、变更规则；L9 Evidence：contract test 或调用证据；必要时 L4 Flow：agent/operator 是否依赖它 | 把 API 从 L8 实现提升到 L7 contract，并补 L6 调用边界和 L9 证据；字段变更必须按 contract 变更处理 |
| 测试入口越来越多 | test、check、verify、ci 都存在，但没人知道谁证明发布 | L9 Evidence：每个入口证明什么事实；L8 实现：根命令和 CICD 配置；L4 Flow：发布前谁运行；L3 承诺：哪些检查支撑公开承诺 | 收敛测试入口，在 L9 写清证据类型，在 L8 保留少数命令，在 L4 写入发布流程；只有支撑 L3 承诺的检查进入 release gate |
| 日志和错误文案停留在旧概念 | 新主线是 workflow，日志仍写 skill failed | L5 领域模型：错误属于 workflow 还是 skill；L8 实现：日志、错误文案、事件名；L9 Evidence：可观测性证据；L4 Flow：客服/支持和 agent 的排查路径 | 先在 L5 定义当前故障语义，再更新 L8 日志和错误文案、L9 查询证据、L4 排查流程，保证所有角色查同一类事实 |
| 迁移计划完成后还留在 current-work | 三个月后读者以为迁移仍未完成 | Current work：删除或压缩计划；L5/L7：稳定领域和 contract 结论；L8：最终实现位置；L9：关闭证据 | 迁移完成后，把稳定结论提升到 L5/L7/L8/L9，current-work 只保留关闭记录或直接删除，不让计划继续当事实入口 |
| 临时 adapter / fallback 变成事实来源 | 为快速发布保留兼容层，后来新功能反而依赖它 | L6 系统边界：adapter 是否是正式边界；L7 Contract：兼容 contract 是否存在；L8 实现：临时代码 owner 和退出条件；L9 Evidence：删除或失败证据；必要时 L3：是否影响承诺 | 如果需要临时层，必须在 L6-L9 写清 owner、退出条件、删除时间和验证方式；不需要兼容时 fast fail，避免 fallback 成为新事实源 |
这些例子的共同点是：局部事实没有回到金字塔定位。解决它们不是靠“大家多沟通”，而是每次都回答三个问题：应该更新哪一层、那一层里的哪类事实变化了、有什么 evidence 证明变化完成。
上层约束下层，下层证明上层
使命约束战略，战略约束承诺，承诺约束 Flow，Flow 约束领域模型，领域模型约束系统边界，系统边界约束 contract，contract 约束实现，实现必须被 evidence 证明。
反过来，下层不能只“存在”，它必须证明上层成立。实现细节要通过测试、日志、状态检查、发布证据支撑 contract；contract 和 evidence 要共同支撑边界、领域、Flow、承诺和战略。
如果某个公开承诺找不到 evidence，它就不是承诺，只是愿望。
每一层必须有自己的入口
每一层都应该有自己的目录或文档入口，不能把所有正文继续堆在单篇总览文档里。
总览文档只负责解释层级关系和阅读入口，不承载每一层的完整正文。否则总览会变成第二套事实来源。
docs/
README.md
L1-mission/
L2-strategy/
L3-promise/
L4-flow/
L5-domain-model/
L6-system-boundary/
L7-contract/
L8-implementation/
L9-evidence/
working-plan/
architecture/
operations/
testing/
这个目录结构不是必须照搬，但每个团队都应该有等价的事实归属。
当前工作和稳定事实必须分开
稳定事实进入对应层，或进入由某一层拥有的专题文档。
当前计划、临时调查、待关闭事项，应该进入 current-work 区域。它们必须说明当前问题、负责人、下一步关闭动作和删除条件。
当计划完成并通过 evidence 闭环后，只把稳定结论提升到对应层，再删除或压缩计划文件。
不要让已完成计划、历史流水账和过期 checklist 长期留在主视野里。
专题文档族必须声明归属
- 架构文档：系统结构、runtime、适配器、边界。
- 工作计划：当前优先级、负责人、资源竞争。
- 运维文档：发布证据、外部平台事实、巡检和风险。
- UI 文档：体验、界面、设计实现参考。
- 测试文档：测试入口、证据等级、触发边界。
- 客服/支持文档：用户问题、日志证据、修复路径。
Layer owner：主要归属哪一层。Feeds / Affects：向哪些层提供事实或影响哪些层。Stability：稳定事实、当前工作、evidence，还是设计参考。Exit / Promotion：如果是计划或临时材料，完成后提升到哪里。
专题文档不是问题。问题是专题文档没有归属，最后变成另一套顶层事实系统。
如果文档冲突，先找 SSOT
如果没有明确 SSOT，一般以更新时间更晚、且更靠近事实源的文档为准。但这只是临时判断，不是长期制度。长期做法必须是补上 SSOT，并把冲突文档改成链接、引用或删除。
- 当前重点。
- 当前优先级。
- 核心能力。
- 已支持。
- 已发布。
- 主线。
- 暂停。
- 候选。
- legacy。
入口、路径和概念默认收敛
模块、工作流、命令、文档和治理入口都要默认收敛，而不是自然增长成多套并行路径。
- 为什么现有 SSOT 不能承载？
- 谁负责触发？
- 由什么 evidence 证明？
- 是否能由 CICD 或 AI 自动执行？
同一类工作只能有少数名实相符的入口。旧入口、别名、临时路径和过期概念要删除或重命名，不保留“以防有人记得”的兼容层。
人只应该处理真正需要人的事
人应该关注目标、范围、业务审批、权限授权、真实成本决策和最终判断。
流程执行、验证选择、证据收集、发布推进、常规治理检查，应该默认交给 CICD 或 AI。
AI agent 不只是执行者，也应该主动发现认知负担、重复入口、手工步骤和自动化缺口，并提出如何让人更少主动告知。
但流程优化会改变团队默认行为，必须先得到明确审批。审批通过后，再同步修改 contract、实现、文档和 evidence。
所有事实都要降低认知负担
一个事实是否值得进入长期文档，要看它是否降低未来读者和 AI 的认知负担。
长期文档应该写当前事实，不复述无用历史过程。历史过程只应该留在明确的日志、发布证据、审计记录或 current-work 计划里。
好的文档应该让第一次阅读的人最快理解最新现状，而不是逼读者理解完整演化史。
Evidence 不是文档
文档可以说明事实，但文档本身不是 evidence。
- 测试。
- 日志。
- 状态命令。
- 线上只读检查。
- 发布清单。
- 批准记录。
- 发布 evidence。
- 真实 provider 或真实用户路径的验收。
如果一个公开承诺找不到 evidence，它就不是承诺，只是愿望。
仓库覆盖从底层事实开始
构造 SSOT 九层金字塔模型时，不需要把每个文件内容复制进九层文档。
- 代码、脚本、workflow、schema、子模块、本地配置、vendor reference、临时资产分别是什么。
- 这些事实有什么 evidence：测试、smoke、发布证据、状态命令、外部服务健康检查，还是仅仅 inventory。
- 哪些事实改变了 contract。
- 哪些 contract 改变了边界或领域模型。
- 哪些领域或边界改变了 Flow 或承诺。
- 哪些承诺改变了战略或使命。
SSOT 九层金字塔模型不追求“文档覆盖所有细节”，它追求“每个重要 surface 都有明确归属和提升路径”。
图：不是所有底层事实都会升级。只有当 evidence、contract、边界、领域、Flow 或承诺真的改变时，才逐级提升到上层。
每次任务结束都要检查文档是否需要更新
- 是否有稳定事实变化？
- 是否有当前计划完成？
- 是否有承诺被扩大或缩小？
- 是否有 Flow、领域、边界、contract、实现或 evidence 变化？
- 是否有旧文档需要删除、压缩或改成链接？
文档必须持续反映当前事实。否则它很快就会从 SSOT 变成噪音。
一份最小落地清单
如果你想给自己的团队落地 SSOT 九层金字塔模型，可以从这个最小清单开始：
- 建立九层入口，不需要一开始写很长，但每层必须有 owner。
- 建立一个 current-work SSOT，只放当前仍未关闭的问题。
- 把“当前优先级”“当前重点”“核心能力”从其他文档里删掉或改成链接。
- 给每个专题文档补上
Layer owner、Feeds / Affects、Stability、Exit / Promotion。 - 定义证据等级：inventory、contract read、static evidence、runtime evidence、release evidence。
- 把测试入口、发布入口、运维入口全部收敛成少数命令。
- 给产品、运营、销售、客服/支持一条进入当前承诺、Flow 和 evidence 的路径。
- 给 AI agent 写清楚阅读顺序：先九层，再专题文档，再代码。
- 给 AI agent 写清楚更新顺序：先实现和 evidence，再判断是否提升上层。
- 每次完成任务时，检查是否有文档需要删除、压缩、提升或改名。
- 定期清理历史计划，避免 current-work 区域变成历史档案馆。
和 SSOT 主文的关系
上一篇文章解释了为什么所有软件工程原则最后都在谈 SSOT，以及为什么复杂团队会因为事实分裂而失控：
一个团队可以先读上一篇理解动机，再用本文搭建自己的金字塔。真正重要的不是目录名字，而是让团队持续拥有一个最新、唯一、可验证的业务、产品和技术事实模型。
