当 AI 协作 Repo 开始让自己的规则失去权威

越来越多团队开始把 AI Agent 纳入日常开发。很快，团队就不再只有几份 Prompt，而是拥有一整套共享 Repo：Skills、Plugins、团队规则、项目入口、操作流程和各种经验总结。

我负责的这套 Repo 也经历了同样的增长。每次遇到问题，最自然的反应都是再增加一条规则或一个 Skill。短期看，每一项都有理由；长期累积后，Repo 本身开始腐化它原本想保护的 single source of truth（SoT）。

背景

这套 Repo 的用途，是让多个团队和多个 AI Agent 共享工作方式。它既包含全公司共同遵守的契约，也包含各团队内部动作、对外接口、能力生命周期和个人效率方法。

这类 Repo 的特殊之处在于：文档不是给人偶尔阅读的参考资料，而是会直接进入 Agent 上下文并改变行为。因此，每增加一个实体都会持续产生成本：

• 需要维护和更新；
• 需要处理它与其他规则的冲突；
• 会撑大 Agent 的上下文；
• 多个相似 Skill 会稀释注意力；
• 相互冲突的指令会让 Agent 行为不可预测。

所以判断标准不能只是“这段内容有没有用”，而应该是：它带来的行为增量，是否大于长期维护成本？

痛点

1. SoT 与投影相互竞争

同一个规则可能同时出现在团队 Contract、Skill、README、静态项目地图和操作说明里。某一份更新后，其他副本逐渐漂移。Agent 无法判断哪一份是权威事实，只能同时接收多个互相冲突的版本。

2. 不同性质的能力混在一起

公司级强制契约、团队对外接口、团队内部流程和个人效率技巧都被当成同一种 Skill 管理。结果是可选建议看起来像强制规则，团队内部动作又被误当成全公司标准。

3. 自己维护平台已经提供的能力

Repo 自己定义了一套发现、安装、更新、评审和发布规则，其中不少已经可以由 Codex 原生 Plugin/Skill 管理工具、GitHub Issue/PR 和 release contract 处理。自建规则没有增加独特行为，却产生了第二套生命周期。

4. 内容变多，不代表 Agent 更可靠

清理前，22 个 Skill 的 SKILL.md 正文共有 2,975 行。数量和体积持续增长，但无法证明每一部分都让 Agent 做得更对或更快。

对策

第一步：用删除反事实判断价值

我对每个实体只问一个问题：

如果删除它，Agent 会做错，还是会明显变慢？

如果答案是两者都不会，它就不应该作为独立 Skill 存在。仍有独特行为的内容被迁入正确的 canonical home；重复内容直接删除，而不是继续保留一个转发层。

第二步：把共享能力分成五类

我重新定义了 Repo 的能力地图：

1. Skill 生命周期：Find、Adopt、Contribute、Release 的唯一入口；
2. 公司级 Contract：所有团队共同遵守的 SoT、授权、状态和交付边界；
3. 团队对外接口：公开入口、输入、可见状态、产物和验收；
4. 团队内部 Contract 与动作：同一领域成员共同采用的判断和操作边界；
5. Adhoc 效率能力：可选方法，不升级为强制团队契约。

这个分类不是为了整理目录，而是为了明确每类内容的使用者、权限和 canonical owner。

第三步：建立统一准入门槛

所有正式 Skill 必须通过同一组九条 invariant gate。它们约束 Skill 的职责、事实来源、授权边界、状态语义和交付证据。未满足门槛的能力进入 HOLD，而不是因为“可能有用”就直接加入团队上下文。

第四步：复用原生能力

发现、安装、删除和回读交给 Codex 原生 Plugin 工具；实现与评审证据留在 GitHub Issue/PR；发布状态由 release contract 管理。共享 Repo 只保留公司真正独特的 WHAT、判断边界和路由规则。

结果

量化范围严格限定为 plugins/*/skills/*/SKILL.md，与改造前的同一范围比较：

指标	改造前	改造后	变化
Skill 正文行数	2,975	1,437	-51.7%
Skill 数量	22	18	-18.2%

具体变更包括：删除 9 个 Skill，再通过新增或合并形成 5 个能力。正文净减少 1,538 行；主要收益来自对保留 Skill 的大幅瘦身，而不只是删除目录。

源码改造通过了 98 项测试，全部 18 个 Skill 也通过了独立校验。更重要的是，Repo 现在有明确的 SoT、投影关系和能力归属：团队规则、团队接口与个人方法不再竞争同一个权威位置。

我不会把这写成“Agent 生产率提升了多少倍”。目前没有足够的量化证据支持这种说法。可以确认的结果是：相互冲突的上下文被移除，Agent 收到的规则更少、边界更清楚，源码治理也有了可验证的准入和生命周期。

这次改造再次证明：对 AI 协作系统而言，更多上下文并不天然意味着更强能力。真正有价值的是更少的冲突、更清晰的权威来源，以及每一条规则都能说明自己究竟改变了什么行为。