03 · 机器门禁：不靠自觉的规则¶
建仓第二天（2026-06-11），他们写下了整套体系的奠基决策，note 标题就叫《机械门禁优于文字规范》（Mechanical quality gates over prose guidelines）。核心论证转述如下：
这个代码库主要由 coding agent 开发。agent 遵守强制门禁远比遵守文字约定可靠；而"这样做工作量大"不构成成本论据——因为干活的是 agent。
还附了一条早期实证：有测试通不过类型检查却照样合入了（vitest 默认不做 typecheck），只被人工 review 偶然抓到。结论：每一条能被机械检查的 AGENTS.md 承诺，都配一个 exit 非零的命令。
门禁的三层结构¶
1. git hooks 层（lefthook，husky 同类）——只放便宜检查：pre-commit 跑快速 lint 和暂存区空白校验，pre-push 跑增量 typecheck。原则是本地不卡手，穷尽性检查归 CI。
2. CI 层——大头：最严格 TypeScript（noUncheckedIndexedAccess 等全开）、每文件 100% 测试覆盖率、跨文件重复代码检测（jscpd）、死代码检测（knip，8 月末被拆除，理由见第 09 章）、三个 Node 版本矩阵、各入口冒烟测试。
3. 自写校验脚本层（他们的特色）——scripts/ 下几十个 verify-* 脚本，把文档规则也变成检查：
| 脚本 | 拒绝什么 |
|---|---|
| verify-doc-budgets | 文档超出字数预算（根 AGENTS.md 目标 ≤1,600 词，manifest 里的门禁上限当时是 1,900；上限 08-17 先调到 1,950，08-25 目标再直接调到 1,950 与上限持平，见第 09 章） |
| verify-agent-note-format | 决策文档格式不符（implemented note 里出现 "should" 都会挂） |
| verify-md-links | markdown 死链、死锚点 |
| verify-translation-pairing | 中英文档结构不同步 |
| verify-export-jsdoc | 公开导出缺 JSDoc |
关键分界：机器管事实，review 管语义¶
他们不是"一切都上门禁"。7 月的一篇 note 明确否决了"加一个 CI 门禁判断改动是否平凡"——理由：机械检查无法可靠判断语义上的轻重，硬加只会催生假阳性和表面应付。
所以规则分两类，各有去处：
- 事实层面（格式、链接、字数、覆盖率、配对）→ 全部脚本化，进 CI
- 语义层面（这算不算重要改动、这个抽象该不该存在、测试是不是真的防住了回归）→ 留给 review，但 review 怎么做写成 skill（见第 4 章）
两边都不依赖自觉。这个分界是整套方法论里最容易被忽略、也最值得抄的一刀。
文档也有预算，超了怎么办有明确次序¶
字数门禁红了时的处理顺序写死在文档标准里：
- 搬走——这段内容是不是本该放在别的层级？留一行链接
- 压缩——属于这里但能更短
- 调高上限——只有内容真的需要空间时才做，PR 里说明理由
配套原则叫"每个事实只有一个家"：同一条规则不允许出现在两个文档里，别处只能放链接。这是 AGENTS.md 能压在 149 行的原因——它不需要讲道理，讲道理的地方有链接。
对副作用的清醒¶
100% 覆盖率门禁会催生凑数测试——这一点他们在写下门禁的同一天就预判了，note 的"后果"一节明说覆盖率压力可能产生无断言的测试，并同日提交了 mutation testing 的提案作为对冲。测试文档里也写着：未覆盖的行往往是门禁正确标记出来的死代码，该删，而不是该补一个测试；行覆盖是必要的，永远不是充分的。
每上一道闸门，同时记录这道闸门会诱导什么坏行为——这个习惯比任何单条门禁都值钱。三周后这个预判有了完整样本，同期还有门禁被拆、被降级、被放宽，每一种都留了案，见第 09 章。
← 上一章 · 返回目录 · 下一章：Skills 蒸馏 →