用 Claude Code Harness 搭建数仓 AI 开发流水线

血缘查询结果：500 ~ 3000 tokens
自测 SQL 执行结果：5000 ~ 15000 tokens
SKILL 规范文件：约 10000 tokens
数据比对样本：大量明细行
DDL、字段枚举、上下游表结构：持续追加

# 当前迭代状态

## 正在开发
- 表：db_a.dws_table_a
- 版本：V1.0
- node_id：1000000001
- 状态：ETL 开发阶段（Step 3/8）

## 本次迭代约束
- 禁止修改：dwd_table_b（已上线，只读）
- 分区字段：partition_dt（格式 yyyyMMdd，不是 dt）
- amount 字段单位：千元（不是元）
- 本次写入模式：INSERT OVERWRITE
- field_a：本次暂不参与计算

## 当前迭代技术设计决策
- 表名：db_a.dws_table_a
- 主键：order_no + partition_dt
- 粒度：订单明细粒度
- 特殊口径：amount 字段继承上游千元单位，不做单位转换

## 数仓全局规范
- 建表分区字段必须是 partition_dt string
- 禁止 SELECT *
- INSERT 必须带 PARTITION 子句
- UPDATE / DELETE 必须带 WHERE
- 金额字段使用 DECIMAL(20,4)，不使用 DOUBLE
- 字段名使用 snake_case
- 多表 JOIN 必须有 ON 条件

~/.claude/projects/<project>/memory/MEMORY.md

这张表的 amount 字段单位是千元，请记住。

field_a 在售后场景下可能为空，请记住这个口径。

V1.0 的关键变更是 field_b 逻辑调整，请记住。

数仓项目根目录/
└── .claude/
    ├── settings.json
    ├── CLAUDE.md
    ├── context/
    │   └── dw_conventions.md
    └── hooks/
        ├── validate_sql.sh
        ├── block_dangerous_ddl.sh
        └── inject_context.sh

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate_sql.sh",
            "timeout": 60,
            "statusMessage": "检查 SQL 规范..."
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block_dangerous_ddl.sh"
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "cat \"$CLAUDE_PROJECT_DIR\"/.claude/context/dw_conventions.md",
            "statusMessage": "重注入数仓规范..."
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "检查用户要求的所有任务是否都已完成。如果还有未完成项，返回提示但不要重新开始。检查 stop_hook_active 是否为 true，如是则直接 exit。",
            "model": "claude-haiku-4-5-20251001"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env bash
set -euo pipefail

INPUT="$(cat)"

FILE_PATH="$(
  printf '%s' "$INPUT" | python3 -c '
import sys, json
try:
    d = json.load(sys.stdin)
    print(d.get("tool_input", {}).get("file_path", ""))
except Exception:
    print("")
'
)"

# 只处理 .sql 文件
[[ -z "$FILE_PATH" ]] && exit 0
[[ "$FILE_PATH" != *.sql ]] && exit 0
[[ ! -f "$FILE_PATH" ]] && exit 0

SQL="$(cat "$FILE_PATH" 2>/dev/null || true)"
[[ -z "$SQL" ]] && exit 0

ERRORS=()

# 规范 1：禁止 SELECT *
if echo "$SQL" | grep -iqE 'SELECT\s+\*'; then
  ERRORS+=("CRITICAL: 发现 SELECT *，必须明确列名")
fi

# 规范 2：INSERT 必须带 PARTITION
if echo "$SQL" | grep -iqE 'INSERT\s+(INTO|OVERWRITE)'; then
  if ! echo "$SQL" | grep -iqE 'PARTITION\s*\('; then
    ERRORS+=("CRITICAL: INSERT 缺少 PARTITION 子句")
  fi
fi

# 规范 3：金额字段不建议使用 DOUBLE
if echo "$SQL" | grep -iqE '\bDOUBLE\b'; then
  ERRORS+=("WARNING: 金额字段建议用 DECIMAL，不用 DOUBLE")
fi

# 规范 4：UPDATE / DELETE 必须有 WHERE
if echo "$SQL" | grep -iqE '\b(UPDATE|DELETE)\b'; then
  if ! echo "$SQL" | grep -iqE '\bWHERE\b'; then
    ERRORS+=("CRITICAL: UPDATE/DELETE 缺少 WHERE 条件")
  fi
fi

if [ "${#ERRORS[@]}" -gt 0 ]; then
  echo "=== SQL 规范检查失败：$FILE_PATH ===" >&2
  for err in "${ERRORS[@]}"; do
    echo "  $err" >&2
  done

  # Claude Code 中需要使用 exit 2 才能阻断或反馈给模型修正
  exit 2
fi

echo "SQL 规范检查通过: $(basename "$FILE_PATH")" >&2
exit 0

#!/usr/bin/env bash
set -euo pipefail

INPUT="$(cat)"

CMD="$(
  printf '%s' "$INPUT" | python3 -c '
import sys, json
try:
    d = json.load(sys.stdin)
    print(d.get("tool_input", {}).get("command", ""))
except Exception:
    print("")
'
)"

# 拦截生产表 DROP / TRUNCATE，放行 _dev / _test / _stg 后缀
if echo "$CMD" | grep -iqE '\b(DROP\s+TABLE|TRUNCATE\s+TABLE)\b'; then
  if ! echo "$CMD" | grep -qiE '(_dev|_test|_stg)\b'; then
    echo "BLOCKED: 检测到生产表 DROP/TRUNCATE 操作，请确认表名是否正确" >&2
    exit 2
  fi
fi

exit 0

---
name: sql-validator
description: ODPS/MaxCompute SQL 语法验证与规范检查专用 agent。生成或修改 SQL 文件后调用，在独立 context 中运行，避免验证日志污染主会话。
tools: Read, Bash, Grep, Glob
model: haiku
permissionMode: dontAsk
---

你是数仓 SQL 规范专家，只做验证，不修改文件。

验证项按优先级执行：
1. 禁止 SELECT *
2. INSERT 必须带 PARTITION
3. 字段使用 snake_case 命名
4. 金额字段使用 DECIMAL，不使用 DOUBLE
5. 多表 JOIN 必须有 ON 条件
6. 检测笛卡尔积风险
7. 检测 UPDATE / DELETE 是否缺少 WHERE

输出格式：
- 状态：PASS / FAIL
- 问题列表：CRITICAL / WARNING / INFO
- 修改建议：具体到文件和行号

限制：
- 不输出大段 SQL 原文
- 不超过 50 行
- 只返回结构化报告

---
name: dw-explorer
description: 数仓结构探索 agent。需要大量读取表结构、DDL、字段信息、血缘关系时调用，避免大量文件内容进入主 context。只读，不修改任何文件。
tools: Read, Glob, Grep, Bash
model: haiku
permissionMode: dontAsk
---

你是数仓探索专家，只执行只读操作。

任务：
1. 读取指定表的 DDL、字段信息、分区策略
2. 分析一层上下游血缘
3. 识别关键字段口径，重点关注金额、日期、状态类字段
4. 标记可能影响计算结果的特殊口径或历史坑点

输出不超过 80 行，包含：
- 表基本信息：层级、粒度、分区策略
- 核心字段定义：含口径说明
- 上下游血缘：只列出表名，不展开完整内容
- 特殊口径或风险点

---
name: data-quality-checker
description: 数仓自测与数据质量检查 agent。适合执行多条检查 SQL，并只返回汇总结果，避免执行明细撑满主 context。
tools: Bash, Read, Grep
model: haiku
permissionMode: dontAsk
---

你是数仓数据质量检查专家。

执行要求：
1. 根据输入表名、分区和口径约束执行标准自测
2. 检查主键非空、分区数据量、金额准确性、枚举值合法性、上下游一致性
3. 只输出 PASS / FAIL 汇总和失败项详情
4. 不输出原始大结果集
5. 不超过 50 行

输出格式：
- 状态：PASS / FAIL
- 检查项总数
- 失败项列表：检查项、失败原因、关键差值、建议动作

用 dw-explorer 分析 db_a.dwd_table_a 的结构，只返回摘要。

对刚生成的 insert_dws_table_a.sql 用 sql-validator 验证。

用 data-quality-checker 对 db_a.dws_table_a 的 partition_dt=20260520 执行标准自测，只返回 PASS/FAIL 汇总。

@"sql-validator (agent)" 验证 path/to/insert_dws_table_a.sql

---
# .claude/rules/etl-rules.md
paths:
  - "**/*insert*.sql"
  - "**/*_di.sql"
  - "**/*_df.sql"
---

# ETL 开发规范

- 必须使用 partition_dt 分区
- INSERT OVERWRITE 前检查目标分区是否已存在
- INSERT 必须带 PARTITION 子句
- 不允许无血缘关系的跨库 JOIN
- 禁止 SELECT *
- 金额字段使用 DECIMAL，不使用 DOUBLE

用 dw-explorer subagent 先读取上游表结构，只返回摘要。

基于需求文档生成：
1. 需求摘要，不超过 5 行
2. 表字段口径草稿
3. 待确认问题清单，按优先级排序
4. 可能影响计算结果的字段单位、时间口径、状态口径

需求文档 URL：[粘贴 PRD 链接]

基于已确认需求，按 OneData 规范完成技术设计。

输入：
- 目标表名：[按 层级_域_主题_粒度_周期 命名]
- 粒度：[描述]
- 分区：partition_dt string，格式 yyyyMMdd
- 主键：[字段列表]
- 禁止：任何与上游口径不一致的字段命名

输出：
- OneData 建模说明
- 字段清单
- 主键与分区说明
- 特殊业务口径
- 不超过 60 行

## 当前迭代技术设计决策
- 表名：db_a.dws_table_a
- 主键：order_no + partition_dt
- 粒度：订单明细粒度
- amount 字段继承上游千元单位，不做转换
- GMV 口径：用户视角，不使用交易视角

按 ETL 开发规范生成建表 DDL 和 Insert SQL。

输出文件：
- ddl_[表名].sql
- insert_[表名].sql

要求：
- INSERT 使用 OVERWRITE 模式
- INSERT 必须带 PARTITION(partition_dt='${bizdate}')
- 金额字段使用 DECIMAL(20,4)
- amount 单位继承上游千元，不做单位转换
- 禁止 SELECT *
- 多表 JOIN 必须有 ON 条件

生成完毕后，用 sql-validator subagent 验证两个文件。

用 data-quality-checker subagent 对 [表名] 执行 23 项标准自测。

输入：
- bizdate = [日期]
- 口径约束：[例如 is_perform=1 只取履约订单]

输出限制：
- 只返回 PASS/FAIL 汇总
- FAIL 项返回检查项、失败原因、关键差值
- 不返回原始 SQL 执行结果
- 不超过 50 行

用 data-comparator subagent 对比新旧表。

新表：[新表名]，partition_dt = [日期]
参考表：[旧表名或线上表]
比对字段：[核心金额字段列表]
金额类容差：≤ 0.01%

只返回：
- 差异超过容差的字段列表
- 新旧值、差值、差异比例
- 可能原因
不返回全量对比数据。

用 dw-sr SKILL 生成 SR 建表和同步任务建议。

先用 dw-explorer 查询以下内容，只返回摘要：
- 源表：[ODPS 表名]
- 目标表：[SR 表名]
- 一层上下游血缘

基于 DDL 摘要分析同步任务风险：
1. DECIMAL / DOUBLE 是否存在精度丢失风险
2. Key 字段选择是否合理，重复率是否过高
3. partition_live_number 是否匹配下游查询窗口
4. DISTRIBUTED BY HASH 的 bucket 数是否匹配数据量
5. DATETIME 字段是否被存成 VARCHAR，导致时间过滤无法高效执行

输出：
- 同步任务配置建议
- 按风险高 / 中 / 低排序
- 每条格式：[风险等级] 问题描述 → 建议修改方式
- 不超过 20 行

用 dw-explorer subagent 查询 [表名] 的一层上下游血缘和 DDL，只返回摘要。

然后分析当前 Insert SQL 的性能瓶颈：
1. 是否有全表扫描
2. 是否有笛卡尔积风险
3. 是否可以用 MAP JOIN 替代 HASH JOIN
4. 分区裁剪是否生效
5. 大表 JOIN 顺序是否合理

输出：
- 优化建议
- 按收益排序
- 不超过 30 行

按 SLA/DQC 规范为 [表名] 生成 9 类 DQC 规则。

要求：
- 完整性：主键非空、分区数据量
- 准确性：核心金额字段与上游比对，容差 0.01%
- 一致性：is_perform 与 perform_flag 联动逻辑
- 合法性：枚举值范围检查
- 唯一性：主键重复检查
- 波动性：核心指标环比波动检查
- 时效性：产出时间 SLA ≤ 次日 8:00
- 血缘一致性：上游分区是否齐备
- 空值率：核心字段空值率阈值

输出 DQC 配置 JSON，可直接用于配置。

- 分区字段必须是 partition_dt string，格式 YYYYMMDD
- 金额字段使用 DECIMAL(26,4) 或团队指定精度
- INSERT 必须使用 INSERT OVERWRITE
- INSERT 必须带 PARTITION 子句
- 禁止 SELECT *
- 禁止无血缘依据的跨库 JOIN
- 建表语句必须包含字段注释

输出文件：
├── ddl_[表名].sql       # ODPS 建表语句，含字段注释、生命周期配置
├── insert_[表名].sql    # ODPS Insert SQL，含分区裁剪、JOIN 规范
└── ddl_sr_[表名].sql    # SR 建表语句，含 Key、分区、桶数建议

每次 .sql 文件写入后：
- PostToolUse hook 自动执行 validate_sql.sh
- 发现 SELECT *：exit 2 阻断
- 发现 INSERT 缺少 PARTITION：exit 2 阻断
- 发现 DOUBLE：返回 WARNING
- Claude 根据错误信息修正后继续

生成完成后：
- sql-validator 验证 DDL 和 Insert SQL
- 主会话只接收 PASS/FAIL 和问题列表
- 验证日志、grep 结果、执行细节不进入主 context

mkdir -p .claude/context
touch .claude/CLAUDE.md
touch .claude/context/dw_conventions.md

# 数仓项目上下文

## 正在开发
- 表：
- 版本：
- 当前阶段：

## 本次迭代约束
- 

## 字段口径
- 

## 禁止事项
- 禁止 SELECT *
- 禁止生产表 DROP/TRUNCATE
- INSERT 必须带 PARTITION

mkdir -p .claude/hooks
touch .claude/settings.json
touch .claude/hooks/validate_sql.sh
touch .claude/hooks/block_dangerous_ddl.sh
chmod +x .claude/hooks/*.sh

mkdir -p .claude/agents
touch .claude/agents/sql-validator.md
touch .claude/agents/dw-explorer.md
touch .claude/agents/data-quality-checker.md

准确率 = 语义理解深度 × 数据规范覆盖度

对话开始时说明 amount 单位是千元。
compact 后 Claude 只记得有 amount 字段，不记得单位。
生成 SQL 时按元处理，结果差 1000 倍。

- 当前迭代口径写入 CLAUDE.md
- 长期字段口径写入 Auto Memory
- SQL 生成提示词中要求引用 CLAUDE.md 中的口径

业务要“用户视角 GMV”，模型按“交易视角 GMV”生成逻辑。
自测时数据对不上，需要返工。

- 需求分析阶段强制输出口径草稿
- 待确认问题清单写入 CLAUDE.md
- 关键问题未确认前，不进入 ETL 开发
- Stop hook 检查未完成事项

规范要求 INSERT 必须带 PARTITION。
短会话里 Claude 能遵守，长会话或 compact 后开始遗漏。

- PostToolUse hook 监听 Write / Edit
- 每次 .sql 文件保存后执行 validate_sql.sh
- 严重违规使用 exit 2 阻断
- Claude 根据错误信息修正 SQL

血缘查询、DDL、自测结果、数据比对样本、SKILL 文件全部进入主会话。
compact 触发后，关键约束和中间决策丢失。

- 血缘查询交给 dw-explorer
- 自测交给 data-quality-checker
- 数据比对交给 data-comparator
- SKILL 文件由 subagent 内部读取
- 主会话只接收摘要、结论和产物路径