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 规则文件判断即可。

检测维度

逐项对照待校验内容，列出「在规则库 grep 不到的元素」：

输出要求

校验报告必须有 ## 知识库覆盖盲区 section，即使没盲区也要写「无新场景」。盲区条目形如：

## 知识库覆盖盲区（请评估是否沉淀）

### B-001: 新写法 — <一句话描述>
- 命中位置：line N
- 现状：`<代码片段>`
- 风险：<可能误判 / 没有标准口径 / 未文档化>
- 规则库现状：<无对应规则 / R-XXX-NNN 仅覆盖部分情况>
- 建议：决定 (a) 沉淀为新规则 / (b) 标记已知风险跳过 / (c) 不沉淀

沉淀决策矩阵

调用方式（主 agent 启动 validator）

推荐固化成一个独立 subagent（物理只读、无状态、薄壳引用本 skill），直接按类型调用，prompt 里只带待校验内容本体 + 业务上下文，规则由它自己 Read 本 skill 加载。

回退模板（subagent 解析不到时，用通用 agent 贴全量 prompt）：

你是严格的数据校验 agent。两步校验，缺一不可。

## Step A：已知规则校验
逐条 grep 待校验内容，命中即报警。

## Step B：覆盖盲区检测（强制）
对照 rules/ 现有规则，识别「规则库没覆盖的新表/新字段/新写法/新业务口径」，
输出 ## 知识库覆盖盲区 section。即使没盲区也要写「无新场景」。

## 加载这些规则文件
${list_of_rules_files_per_scenario}

## 待校验内容
${content}

## 输出格式
# 校验报告
## 总结：PASS / WARNING / FAIL
- 检查项：N 通过 / M 警告 / K 失败 / J 个盲区待评估

## 详细结果（按规则编号）
### [FAIL] R-XXX-NNN: <规则名>
- 命中位置：第 N 行
- 引用：'<代码片段>'
- 建议：<怎么改>

## 知识库覆盖盲区（请评估是否沉淀）
### B-001: ...

规则索引

完整规则在 rules/INDEX.md。本仓库附带的通用规则（开箱即用）：

需要你自己建的（业务相关，给模板和示例）：

严重等级：[FAIL] 必修复 / [WARNING] 建议修复 / [INFO] 风格建议。

维护

被纠正一个新错误 → 追加规则到对应文件：

1. 决定归属（SQL 字段 / AB / 口径 / 报告 / 结果合理性 / 回归）。
2. 编号递增（不复用废弃编号，废弃的标 [DEPRECATED] 不删，保留历史印象）。
3. 写明 Pattern + 根因 + Fix（+ 首次踩坑时间）。
4. 在活动日志记一笔。