P2 methodology AI工程Synapse自动化

当 AI 团队的人数出现三个版本：我们如何用元规则修复数字漂移

从一个真实事故出发：同一个 AI 体系中出现 44/46/50 三个'AI agent 人数'，剖析数字漂移的根因并提出 Fact-SSOT 元规则作为系统性解法

  • 同一事实存在多副本，漂移几乎必然发生
  • 数字漂移不报错，只在人工对比时才暴露
  • 解法：为高风险数字指定唯一权威来源（SSOT）
  • 用元规则约束 AI agent，比靠人记忆更可靠
  • 20分钟修复存量，3周内验证无新漂移

问题背景：三个数字，三种"真相"

上周审查系统文档时，我把三份文件并排打开，发现了一个让我有点坐不住的问题：描述同一个 AI 协作体系成员规模，CLAUDE.md 写的是「Multi-Agent 团队 (44人)」，obs/01-team-knowledge/ 下的团队文档写的是 46 人，Notion 对外展示页面写的是 50 人。

这三个数字都是我自己写的。Synapse 是我们内部的 Multi-Agent 执行体系，团队成员随着体系演化陆续增加，每次新增成员我都会去更新"相关的地方"。理论上三处应该一致。但实际上，我自己都说不清楚哪一个才是对的。

为什么难排查：我们一开始以为这是"同步遗漏"

我最初的判断是：这不过是某次更新时手滑漏掉了一两个地方，修一下就好。但花了一小时追溯每个数字的来历之后，我意识到问题比这深得多。

44 是某次配置重写后遗留的旧值，当时没有触发其他文件的同步。46 是某次整理文档时的实际人数，但那次整理没有通知到 CLAUDE.md。50 是某次对外演示时的"预期规划"数字，某个时间点被当成现状写进了展示页面——它从未对应过任何真实时刻的团队规模。

换句话说，这不是一次遗漏，而是三次独立的写入事件，每次都有各自"正确"的上下文，但没有任何一个机制把它们关联起来。更麻烦的是：数字漂移不会触发任何报错。系统照常运行，AI agent 照常被调用，矛盾安静地藏在文档里，直到有人把几份文件放在一起才浮出水面。靠"记得同步"是不够的，因为每一次写入时，写入者都认为自己做了正确的事。

数字漂移的本质不是人的失误，而是架构上缺少对抗漂移的机制。当同一个事实分散存储在多个位置、各自独立维护时，不一致是迟早的事，和团队能力无关。

根因与设计决策：引入 Fact-SSOT 元规则

根因很清晰：同一个事实没有唯一的权威来源（SSOT，Single Source of Truth），导致每个副本都在独立漂移。软件工程里这个问题早有解法——数据库用主键约束保证唯一性，代码用变量避免魔法数字散落——但文档、配置文件、对外材料之间的一致性，通常只靠人记得去同步。

我们引入的解法叫 Fact-SSOT，是一条元规则（meta-rule）：不针对某个具体数字，而是针对"如何管理所有高风险数字"这件事本身制定规则。核心约定是：对于任何会被多处引用的数字事实，必须指定唯一的权威文件，其他所有引用必须标注来源，禁止在非 SSOT 文件中直接写死数值。

落地分三步。第一步是识别漂移高风险数字：会随时间变化、会被多文件引用、变更时没有自动提醒——满足这三条的数字全部纳入管理，包括团队人数、版本号、价格、配置参数。第二步是为每类事实指定 SSOT 文件。我们的约定：

# agent-butler/config/organization.yaml
# 这是团队人数的唯一权威来源
# 其他文件引用此处数值，不独立维护

team:
  name: Synapse Multi-Agent Team
  headcount: 46          # SSOT: 本文件
  last_updated: 2025-06-01

第三步是在 AI 指令层面写入约束。我们在 CLAUDE.md 里加入了如下元规则片段：

# CLAUDE.md — Fact-SSOT 元规则（节选）

fact_ssot:
  rule: |
    当任何数字被多于一个文件引用时，必须在提案阶段标注该数字的 SSOT 来源。
    修改数字事实时，必须先更新 SSOT 文件，再检查并更新所有引用位置。
    非 SSOT 文件中不得直接写死数值，只能引用并注明来源文件。
  ssot_registry:
    headcount: "agent-butler/config/organization.yaml"
    version:   "VERSION"

规则确立后，存量修复用了约 20 分钟：打开 organization.yaml，确认实际人数，在所有引用位置统一替换，每处标注「来源：organization.yaml」。为了防止未来再次漂移，我们在代码提交流程里加了一个检查提醒：凡涉及 SSOT 文件变更的 commit，系统自动提示检查关联引用位置。这是提醒而非强制拦截——规则要有弹性，能处理特殊情况，而不是用技术手段把流程锁死。

三周后回看：做了两次成员变动，两次都完成了全文件同步，没有出现新的漂移。更值得记录的变化是：团队成员在讨论任何数字时，会下意识地问「这个数字的 SSOT 在哪里」——这个习惯本身就是最好的防漂移机制。

可移植的原则

如果你在维护多文件系统，先做这一步：把所有「会变、会被多处引用、改了不会自动提醒」的数字列出来，这张清单就是你的漂移风险地图。

  1. 如果你在构建 AI agent 系统，把 SSOT 约定写入 agent 的指令层，而不只是写在团队 wiki 里——让系统架构本身承载一致性保证，而不是靠人记住。
  2. 如果你在维护产品文档，把「支持 X 种语言」「速率限制为 Y 次/分钟」这类数字集中存放在一个权威文件，官网、App Store 描述、用户手册全部引用这个文件，新增语言时只改一处。
  3. 如果你在管理前后端共用的枚举值，显式维护一份枚举定义作为 SSOT，让前端代码和数据库 schema 都从这里派生，而不是各自维护一份"差不多一样"的副本。
  4. 如果你在设计变更流程，区分「强制拦截」和「提醒」——对 SSOT 变更触发提醒足够，不需要把流程锁死，保留处理特殊情况的弹性。

元规则的价值在于作用于规则本身。当系统足够复杂，靠人记住每一个细节是不现实的，这时候需要的不是更多提醒，而是让系统架构来承载一致性保证。漂移不会消失，但通过显式化引用关系，可以让它从「必然发生且难以发现」变成「可以发现并修复」。

如果你在构建 AI 工程团队，我们把 Fact-SSOT 元规则作为标准模块集成进了开源的 Synapse 框架，包含 SSOT 文件约定、引用标注格式和变更检查流程。如果你也遇到过类似的数字漂移，或者有不同的解法，欢迎在 GitHub issue 里聊——我很想知道这个问题在 n8n workflow 里具体是怎么表现的。