dw-harness

中文

用 Claude Code 做数仓开发,聊久了 AI 就开始犯糊涂——忘字段口径、SQL 不合规范、血缘查询把上下文撑爆。这些坑做数仓的人都踩过。

dw-harness 把这些反复踩的坑变成了代码:hooks 自动拦截问题 SQL,subagents 把重活隔离出去,skills 把八步流程写死。复制到项目里,启动 claude 就能用。

不需要从零教 AI 你的规范,因为它根本不该靠"记住"。

English

If you use Claude Code for data warehouse work, you know the drill: long conversations make AI sloppy — forgetting field definitions, writing SQL that breaks your conventions, lineage queries eating up the entire context window.

dw-harness turns these recurring headaches into code: hooks block bad SQL automatically, subagents isolate heavy lifting, skills lock in an 8-step workflow. Copy it into your project, run claude, done.

Your conventions shouldn't rely on AI "remembering" them.

确认模板没问题 / Make sure the template works:

python tests/run_hook_smoke_tests.py

也可以用一键脚本 / Or use the init script:

# macOS / Linux
bash init.sh /your-dw-project
# Windows
.\init.ps1 C:\path\to\your-dw-project

手动复制 / Manual copy:

macOS / Linux:

git clone https://github.com/pugyy/dw-harness.git
cp -r dw-harness/template/.claude /your-dw-project/
cd /your-dw-project
claude

Windows PowerShell:

git clone https://github.com/pugyy/dw-harness.git
Copy-Item -Recurse .\dw-harness\template\.claude C:\path\to\your-dw-project\
Set-Location C:\path\to\your-dw-project
claude

Hook 脚本默认用 python 调用。如果你的系统只有 python3,改一下 .claude/settings.json 里的命令就行。

Hook scripts use python by default. If your system only has python3, change the commands in .claude/settings.json.

填上你当前在开发的表名、版本、字段口径、不能动的表这些信息。 Fill in your current table name, version, field definitions, and tables that should not be modified.

详细说明 / Full details: docs/five-layers-defense.md

需求分析 ──→ 技术设计 ──→ ETL开发 ──→ 自测 ──→ 数据比对 ──→ SR导入 ──→ 性能优化 ──→ SLA/DQC
Analysis ──→ Design ──→ ETL Dev ──→ Test ──→ Compare ──→ SR Import─→ Perf Tune ──→ SLA/DQC

详细说明 / Full details: docs/eight-steps-workflow.md

• SELECT * -- 不行,必须写清楚字段 / Not allowed, list fields explicitly
• INSERT 不带 PARTITION -- 不行,必须指定分区 / Not allowed, specify partition
• UPDATE / DELETE 不带 WHERE -- 不行,必须加条件 / Not allowed, add WHERE clause
• 金额字段用 DOUBLE -- 不行,换成 DECIMAL(20,4) / Money field uses DOUBLE -- not allowed, use DECIMAL(20,4)
• 分区字段叫 dt -- 不行,统一叫 partition_dt / Partition field named dt -- not allowed, use partition_dt

支持 ODPS/MaxCompute、Hive、Spark SQL。默认按环境变量 DW_HARNESS_DIALECT、文件名/近邻目录、SQL 文件头部注释和语法特征自动判断;不确定时按 ODPS 处理。

Supports ODPS/MaxCompute, Hive, and Spark SQL. Detection checks DW_HARNESS_DIALECT, file names/nearby directories, header comments, and dialect syntax; ODPS is the fallback.

• DROP TABLE / DROP DATABASE
• TRUNCATE TABLE
• ALTER TABLE ... DROP COLUMN
• DELETE FROM 不带 WHERE / DELETE FROM without WHERE

dw-harness/
├── README.md
├── docs/ # 设计文档 / Design docs
├── examples/
│ ├── example_claude_md.md # CLAUDE.md 填写示例 / CLAUDE.md example
│ └── sample-sql/ # 好/坏 SQL 示例 / Good/bad SQL samples
├── template/.claude/ # <-- 复制这个目录到你的项目 / Copy this to your project
│ ├── CLAUDE.md # 上下文持久化 / Context persistence
│ ├── settings.json # Hooks 配置 / Hook config
│ ├── context/ # compact 后重注入的规范 / Re-injected after compact
│ ├── hooks/ # 自动化脚本 / Automation scripts (Python)
│ ├── agents/ # 4 个 subagent
│ ├── rules/ # 路径级规范,按需加载 / Path-scoped rules, load on demand
│ │ └── etl-rules.md # ETL SQL 规范 / ETL SQL conventions
│ └── skills/ # 8 个 SKILL 文件 / 8 SKILL files
└── tests/ # Hook 冒烟测试 / Hook smoke tests

所有 subagent 默认用 opus,图个稳。复制过去之后想省钱可以改成 sonnet 或 haiku。

All subagents default to opus for reliability. Downgrade to sonnet or haiku if cost is a concern.

部分 agent 允许使用 Bash 执行只读探索、质量检查或数据比对命令。复制模板到生产项目后,请先确认这些命令只能访问你允许的环境,必要时在 agent 文件里移除 Bash 或调整 permissionMode。

Some agents can use Bash for read-only exploration, quality checks, or comparisons. After copying the template into a production project, confirm the commands can only access approved environments. Remove Bash or adjust permissionMode in agent files if needed.

中文:数仓 AI 开发的瓶颈从来不是 AI 不会写 SQL,而是两件事老出问题:语义理解对不上、规范执行不稳定。所以思路很简单——人擅长的事(判断口径、理清语义)写死到文件里,AI 擅长的事(检查规范、干重复活)交给代码去强制执行。 别让 AI 靠"记住"来做事,让它靠代码来做事。

English: The bottleneck in DW AI development is never about whether AI can write SQL. It's about two things that keep breaking: getting the semantics right, and enforcing conventions consistently. The idea is straightforward -- persist human judgment (field definitions, semantics) into files, and let code enforce what AI is good at (checking rules, doing repetitive work). Don't make AI rely on "remembering". Make it rely on code.

• Claude Code Hooks
• Claude Code Skills
• Claude Code Memory & Rules

MIT