data-validator

Data Validator

独立于主流程的数据校验，避免自评偏差。自评不可信，校验必须分离（对应 Anthropic harness 设计原则：让生产者评判自己的产物有系统性偏差，验证必须交给独立 agent）。

关键约束：这个 agent 没有 Write / Edit 权限（见上方 allowed-tools）。它只能 Read / Grep / Bash(只读) / Glob，物理上无法改你的文件——它的唯一产出是一份 PASS / WARNING / FAIL 校验报告。

校验规则按主题分文件存放在 rules/，按场景按需加载。每被纠正一个错误 → 追加一条规则，下次自动生效。

---

校验场景（按需加载规则文件）

1. SQL 校验（写完 SQL、提交前）

Step 1：识别 SQL 类型并加载规则

• AB 实验 SQL（含实验分组逻辑）→ 加载 rules/abtest-rules.md
• 涉及收入 / 订阅 / 付费 / 业务核心指标 → 加载你自己的 rules/<domain>-metric-rules.md（按 _TEMPLATE.md 建）
• 所有 SQL → 加载你自己的 rules/<your>-field-traps.md（字段坑库）

Step 2：validator 用 Grep/regex 逐条 R-* 检查 SQL 文本，命中就报警。

Step 3：补充检查（规则不覆盖的）

• Pre-flight：未知表/字段是否已 DESCRIBE 确认
• 类型匹配：WHERE/JOIN 条件两侧类型是否一致

Step 4（关键）：覆盖盲区检测 —— 见下文「## 覆盖盲区检测」。

---

2. 报表数据校验（数据拉完、写入报表/文档前）

加载：你的业务口径规则 + 文档格式规则（如有）。

规则不覆盖的额外检查：

• 环比合理性（如 ±30% 预警）
• 完整性（NULL / 0 / 缺失）
• 节假日 / 异常窗口过滤
• 跨源一致性（vs 已有看板 / 上一期）

---

3. 分析报告校验（写完、交付前）

加载：rules/report-style.md（必） + rules/sanity-check.md 的数字 grounding 规则。

校验方式：grep 报告 markdown 文本，逐条 R-RPT-* 检查。emoji 单独正则扫一遍。

---

4. SQL 结果合理性校验（SQL 跑完、用结果之前）

加载：rules/sanity-check.md（必）。

触发时机：

• 跑完 SQL 拿到结果，用结果之前
• 写完报告，交付之前

输入：SQL 文本 + 结果摘要（行数、关键聚合值、Top N 行）+ 业务上下文（预期粒度、对比基线）。

校验方式：validator 逐条 R-SAN-* 检查（结果空 / JOIN 膨胀 / 缺过滤 / 数字溯源）。

与场景 1 的关系：场景 1 是写 SQL 时的预防，场景 4 是跑完后的兜底，互补不重复。

---

5. ETL 修复回归校验（数据回刷完成后）

加载：你的 rules/known-bug-regression.md（按 _TEMPLATE.md 自建）。

机制：每修一个 ETL bug，agent 自决追加一条回归规则，含：bug 描述（根因 + 触发条件）、修复版本/日期、影响表、case、4 类回归 SQL（分布 / 业务规则 / 异常值 / 守恒）。长期形成 known-pattern 库。

这个文件高度业务相关（含真实表名、case），不要开源；本仓库只提供机制说明和模板。

---

6. 聚合/分摊表守恒对账（建表 / 改口径时）

加载：rules/sanity-check.md 的 R-SAN-007（必）。

核心：任何把上游度量（成本/收入/用量/计数）分摊或聚合到新粒度的表，必须 SUM(加工后) ≈ SUM(上游)，差异 < 0.5%。单看加工表自身永远发现不了「少算/错配」，必须对上游总账。

---

覆盖盲区检测（每次必做）

校验完已知规则后，validator 必须主动识别「规则库没覆盖的新场景」，让人评估是否要沉淀新规则。否则规则库永远停留在已踩过的坑，新坑还是会被踩。

反幻觉铁律

涉及「与权威口径对比」的盲区，必须实际 Read 权威源文件验证，禁止凭印象判断，否则会 false positive 误报。涉及「表/字段是否文档化」的盲区，靠 grep 规则文件判断即可。