指标口径该不该像代码一样进仓库、走 review 和 CI 校验？

背景

做了 3 年技术文档、这两年转做指标体系，最近帮几个团队把散落在 BI 看板、SQL 脚本、wiki 指标字典里的口径往「一个地方」收敛。做着做着撞到一个根本分歧：口径到底算「文档」还是「代码」？

这个分歧站内其实已经有人聊过「口径该谁说了算」（我认同那几位对「口径不一致是跨团队最贵成本」的判断），但讨论基本停在「谁来定、怎么对齐」。我这次想往下推一步：口径定下来之后，它该以什么形态被管理、被 review、被回归？ 这才是我反复翻车的地方。

常见的三种做法

1. 文档派：口径写进 wiki / 指标字典，人读为主，变更走文档 PR。
   • 优点：可读性强、门槛低、业务方也能改。
   • 我踩到的坑：文档说的和 SQL 实际跑的经常对不上，「活跃用户」文档写「7 天有登录」，脚本里其实是「7 天有任一事件」，改口径时只改了文档没改 SQL，下游全错。
2. BI 配置派：口径活在 BI 工具（Looker / Superset / Quick BI）的模型层，改口径 = 改字段模型。
   • 优点：口径和取数天然绑定，不容易脱节。
   • 我踩到的坑：逻辑藏在工具里，review 靠截图，换工具或跨工具几乎不可移植，新人接手基本靠口口相传。
3. 代码派（Metrics as Code）：口径用 YAML / DSL 定义进 git 仓库，CI 做 lint、口径回归测试，变更走 PR + review + 版本化 + 可 diff。
   • 优点：可审计、可回滚、变更留痕，「谁在什么时候把分母改了」一查就出来。
   • 我踩到的坑：团队要真的接受「口径是代码」，DSL、CI、review 习惯都是新增维护成本，小团队容易过度工程。

我的倾向与理由

我倾向分层，而不是一刀切：

• 核心指标（少数、被多团队依赖、口径错了直接影响业务决策）→ 走代码。它们值得 diff、值得回归测试、值得变更留痕。判据很简单：口径改动后如果没人发现，代价有多高？代价高的，就值得上工程手段。
• 长尾 / 探索性指标 → 留文档或 BI 配置即可。别为一次性分析指标搭 DSL 和 CI，那是把 80% 的成本投给了 20% 的指标。

一句话：代码化的成本是真实的，只该投给「口径错了代价高」的那部分指标。

想听大家聊聊

• 你们团队大概多大规模、多少指标，才开始觉得「口径该代码化」是划算的？有没有一个具体的触发点（比如一次口径事故）？
• 换 BI 工具 / 数仓时，代码化的口径怎么迁移？你们踩过吗？
• 有没有「口径代码化之后反而更难改、review 更慢」的反例？我是真担心把口径锁死在代码里，业务方改个口径要走三周流程。
• 纯业务团队（基本不写代码）想有「口径留痕 + 可回归」，有没有比写 DSL 更轻的落地方式？

欢迎举具体例子，指标名和数字口径都可以脱敏。