AI团队仓库治理与提交纪律方法论
> 编制：万有AI产品团队
> 定位：万有AI通用方法论系列 | 研发治理的载体层——纪律要有地方落，代码要有办法回
> 依据：万有AI双仓治理实践（治理文档真仓纠正、钩子路径版本化、部署前快照断言）与AI协作研发的实际运行记录
> 一句话：代码仓库的第一功能不是存文件，是让每一次改变都可追溯、可回退、可审计
一、单仓混装为什么会失控
大多数团队一开始都是「一个仓库装一切」：代码、部署脚本、规范文档、证据报告、密钥配置样例，全塞在一起。三个人以内没事，一旦AI参与研发就会迅速恶化：
| 混装的后果 | 具体表现 |
|---|---|
| 权限无法分层 | 能改代码的人顺手能改规范 |
| 审计无法定位 | 一份规范到底哪版有效，翻不到 |
| 门禁无法分工 | 敏感词表放在代码仓，谁都能改 |
| 回滚牵连过广 | 回滚代码把治理文档一起回退了 |
根因是一句话：不同性质的资产，治理要求不一样，却被迫共用一个权限边界。
二、双仓制：治理归治理，代码归代码
| 仓 | 装什么 | 谁维护 | 门禁 |
|---|---|---|---|
| 治理仓 | 工程规范、词表、豁免登记、巡检脚本、证据与报告 | 安全/治理责任方 | 全部钩子共用一套 |
| 代码仓（可多仓） | 站点代码、后端服务、部署脚本 | 研发执行方 | 只读引用治理仓词表 |
| 独立治理仓 | 岗位守则、开发规范等制度文本 | 制度责任方 | 指向同一钩子目录 |
三条关键规则：
- 词表只存一份：词表放治理仓，各代码仓通过路径回退引用，杜绝多份漂移；
- 豁免表分仓登记：词表共享，豁免不共享——每个仓只登记自己合法的例外；
- 文档与代码不同仓：规范变更的审批链和代码变更的审批链，本来就是两条链。
> 这一条是踩出来的：早期出现过「治理文档声称已在真仓，实际真仓里没有」的情况，后来靠独立治理仓 + 提交补正才闭环。教训写进了台账：制度文本必须有真仓落点，口头声明不算落地。
三、钩子必须版本化：不能住在本地配置里
门禁要生效，光有脚本文件不够，还有两个隐性条件：
| 条件 | 常见错法 | 正确做法 |
|---|---|---|
| 钩子路径被登记 | 手动拷到本地钩子目录 | 钩子路径写进仓库配置，随仓生效 |
| 钩子源文件入库 | 本地改、不入库 | 钩子本身是代码，必须提交并评审 |
只把脚本拷到本地钩子目录，会产生一个隐蔽的失败模式：换机器、重新克隆、换人接手，门禁全部静默失效，而且没有任何报错。 所以验收时要多问一句「克隆一份下来，门禁还生效吗」。
四、提交纪律：让 commit 成为存档点
4.1 分类标记
| 前缀 | 类型 | 纪律 |
|---|---|---|
| BF | 缺陷修复 | 只含修复代码，不得夹带重构 |
| FF | 未发布功能修复 | 仅限尚未上线的功能 |
| NF | 新功能 | 配套文档与验收口径 |
| RF | 重构 | 不改变外部行为 |
| ENH | 功能增强 | 已有功能的能力扩展 |
| DOC | 文档 | 规范、说明、报告 |
| TEST | 测试 | 用例与测试脚本 |
核心红线：BF 提交里不得出现 RF/ENH/NF 的改动。混装提交的最大代价不是难看，而是出了问题时无法判断是「修复引入」还是「重构引入」。
4.2 分支与粒度
main（生产，受保护）
└ develop（集成分支）
├ feature/xxx（功能）
├ fix/xxx（缺陷，只含修复）
└ refactor/xxx（重构，与修复严格分离）
- 一个任务一次提交，不攒着一起交；
- 提交信息写「为什么改」，不只写「改了什么」；
- AI参与的提交在信息里标注 AI 参与，便于日后追溯。
4.3 快照断言：补掉首提交的盲区
钩子只对常规提交生效，而首提交、重初始化、批量导入这些动作常常绕过常规提交流程。所以在部署前必须再做一次双断言：扫暂存区内容 + 检索历史提交记录，命中即逐处定性——真实的脱敏重建，误报的登记豁免。
五、版本与真相源：仓库里最贵的是「哪版算数」
| 问题 | 坏做法 | 好做法 |
|---|---|---|
| 哪版是当前版本 | 各处写各自的版本号 | 版本号单一真相源，其余位置引用 |
| 声明与实现不一致 | 文档写一套，代码跑一套 | 四件套联动断言，不一致不上线 |
| 历史版本对不上账 | 只留最新，删旧档 | 定版时点快照存档，只加注不追改 |
第三条尤其容易被忽略：定版快照一旦发布，就不要再回头修改它的历史表述。要说明「当前值」时，另起一行加注即可。追改历史快照，会让所有引用过它的人集体失去可信基准。
六、私有与对外的边界
仓库保持私有，是治理前提，不是保守：
- 词表、豁免表、事故语料本身就是受控资产，公开等于把防护说明书交出去；
- 对外分享方法论，讲方法与结论，不给仓库入口与可拷贝配置；
- 公开材料里不出现「已开源」「可直接下载」这类承诺——承诺了给不出，比不承诺更伤信任。
万有AI的实际做法是：白皮书中明确写「配套资产属内部资产，暂不对外提供仓库或下载」，把所有指向外部代码托管的入口清空，避免死链与虚承诺。
七、常见漂移与对策
| 漂移形态 | 怎么发现 | 对策 |
|---|---|---|
| 钩子被就地手改 | 钩子文件与仓库版本不一致 | 钩子入库、比对校验和 |
| 脚本与仓内版本不同源 | 服务器上的脚本校验和与仓库不同 | 每次部署都从仓库取件，不就地改 |
| 配置在服务器手改后未回写 | 线上行为与仓库配置不一致 | 变更必须回写仓库，再部署 |
| 词表多份并存 | 各仓词表条数不一 | 单点词表 + 回退定位 |
| 门禁路径未随仓生效 | 新克隆环境门禁静默失效 | 克隆后生效断言纳入验收 |
八、落地清单
8.1 起步
- [ ] 把仓库按「治理/代码」拆开，明确每个仓的维护责任方
- [ ] 词表收进治理仓，代码仓改为引用
- [ ] 钩子源文件入库，钩子路径写进仓库配置
- [ ] 克隆一份到干净目录，验证门禁仍生效
8.2 成体系
- [ ] 提交分类标记写入团队约定，BF/RF 严格分离
- [ ] 部署脚本一律从仓库取件，禁止服务器就地改
- [ ] 部署前快照断言常态化
- [ ] 版本号单一真相源 + 定版快照只加注不追改
8.3 自检五问
| # | 自检问题 |
|---|---|
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 |
> 一句话收口：判断一个AI团队工程成熟度，不用看代码写得多漂亮，只要看两件事——门禁是否在拦，提交是否可回。
万有AI | 依据双仓治理与AI协作研发实际运行记录萃取