当 AI 能写出语法正确的 SQL，却写不出「你们公司认可的 SQL」——问题不在模型，在于上下文。本文介绍一套可复用的知识架构：让 Cursor 不只帮你敲代码，更帮你把数仓经验沉淀成团队资产。

---

开场：两个 SQL，两种命运

周一早上，数据开发小李收到需求：「按门店统计上周 GMV，剔除测试订单。」

他打开 Cursor，输入需求。十秒后，Agent 交出一份 SQL：分区没滤、金额没换算、关联键用了 store_code 而不是公司约定的 store_id，测试订单过滤字段也猜错了。

小李叹了口气，自己改了一小时。

周三，同事小王接同样需求。Agent 这次对了——因为项目里已经有了 Skill（怎么写）和 Reference（用什么写）。小王只花了十分钟核对样本数。

差别不在 AI 变聪明了，而在 AI 终于「入职」了。

数仓是最适合这种「入职培训」的领域：规则多、口径硬、表关系绕，但模式高度重复。Cursor 的价值，不是替代数据工程师，而是把 隐性经验 变成 可加载、可版本化、可 Review 的知识。

---

一、先建立共识：我们要沉淀的是什么

很多人把 Skill 当成「更长的 Prompt」。更准确的说法是：

资产	角色	类比
Skill	工作手册	飞行员检查单——短、硬、必须遵守
Reference	数据字典 + 口径百科	随查随用的运维手册
主题 SQL	可运行样板	教科书里的例题，带标准答案
主题 README	业务链路说明	一张「从源到报表」的地铁线路图

四者分工明确：

• Skill 回答：「在这种公司、这种分层下，应该怎么写？」
• Reference 回答：「这张表是什么粒度？该用哪个时间字段？金额是分还是元？」
• SQL 回答：「我们实际落地长什么样？」
• README 回答：「这个主题涉及哪些表、指标怎么串？」

不要把 200 张表的 DDL 塞进 Skill。 那相当于把百科全书塞进口袋——谁也读不完，Agent 也抓不住重点。

---

二、推荐目录结构

your-dw-project/
├── .cursor/
│   └── skills/
│       └── data-warehouse/
│           ├── SKILL.md           # 入口：规范、速查、触发词
│           └── reference.md       # 深读：维表、事实表、模板
├── sql/
│   └── {topic}/                   # 按业务主题拆分
│       ├── README.md              # 链路说明、粒度、口径摘要
│       ├── dwd_*.sql
│       ├── dws_*.sql
│       └── dm_*.sql
├── docs/                          # 设计文档、本博客
└── .cursor/rules/                 # 可选：全局短规则

这套结构的本质是：知识可 diff，代码可执行，二者互相校验。

---

三、SKILL.md：写给 Agent 的「上岗手册」

3.1 篇幅与语气

• 篇幅：一次能读完（通常 150～300 行），细节链到 Reference。
• 语气：祈使句、表格、清单；少叙述，多规则。
• 更新：口径争议有结论 → 当天回写 Skill，别只留在飞书消息里。

3.2 必备章节（规范模板）

---
name: data-warehouse
description: >
  公司数仓开发规范。适用于 Hive / Spark SQL / Snowflake /
  BigQuery / MaxCompute 等。触发词：dwd_, dws_, dm_, 分区 ds,
  调度参数 bizdate, 数据分层 ODS DWD DWS DM。
---

# 环境与分层
# 命名规范
# SQL 工程约定（分区、INSERT、DDL、幂等）
# 金额 / 时间 / 精度规范
# 场景 → 表选用矩阵（核心！）
# 标准反模式（禁止事项）
# Review 清单
# 延伸阅读 → reference.md

3.3 最有 ROI 的一节：场景 → 表选用矩阵

数仓事故里，「语法错」远少于「表选错、时间字段选错、单位错」。

把这类决策写成矩阵，Agent 收益最大：

分析场景	推荐表	时间字段	默认过滤
订单量 / 订单金额	dwd_order	first_pay_time	is_test = false
商品 / SKU 销售	dwd_order_item	item_pay_time	按主题确认
支付退款 / 销售净额	dwd_payment_flow	trade_time	is_test = false
用户活跃	dws_user_active_d	ds	—

一行矩阵，胜过十页 DDL。 这是 Skill 的灵魂。

3.4 触发词：让 Agent「该读时才读」

Skill 的 YAML description 决定 Cursor 是否加载它。务必包含：

• 平台：Spark、Airflow、dbt、DataWorks……
• 分层前缀：ods_ dwd_ dws_ dm_
• 公司高频表名（5～15 个即可）
• 业务黑话：GMV、留存、归因、SCD……

3.5 不要写进 Skill 的

内容	放哪里
全字段 DDL	Reference
未定稿口径	Reference，标「待确认」
与官方看板不一致的临时口径	Reference，标「项目口径」
长篇背景故事	docs/ 或 README

---

四、reference.md：数仓的「第二大脑」

如果 Skill 是检查单，Reference 就是 可以搜索的、带版本号的维基。

4.1 推荐目录

1. 调度变量（${bizdate}、${bizdate-1}……）
2. DDL 与类型规范（分区、生命周期、COMMENT 写法）
3. 金额与时间规范（分/元、时区、半开区间）
4. 分层 retention 默认值
5. 核心 ER / 表关系（ASCII 或 mermaid 即可）
6. 维度表速查（主键、默认 JOIN 键、禁用键）
7. 高频事实表目录（一行摘要）+ 分表详解（按需展开）
8. 场景选用矩阵（可与 Skill 互链，Reference 侧更细）
9. 标准 CTE 模板（日/周/月/年窗口、同期对比）
10. 主题域索引（链到 sql/{topic}/README.md）
11. 已知坑 / 待确认（越写越少才是目标）

4.2 单表条目：最小可用信息集

每张高频表不必抄 DDL，只写 写 SQL 时一定会用到的决策信息：

## fact_payment_flow — 支付退款流水

- 粒度：订单明细 × 单笔流水
- 业务键：order_id + line_id + payment_id
- 分区：dt (yyyy-MM-dd)
- 金额单位：分（入汇总层 /100）
- 统计时间：**trade_time**（禁止用 order_create_time 代替）
- 默认过滤：is_test = false
- 常用 JOIN：fact_order_item ON order_id, line_id
- 慎用：is_promo 仅营销主题使用，通用 GMV 不过滤

4.3 维护策略：增量，别「大 bang」

阶段	做什么	耗时
Day 1	环境 + 分层 + 命名 + 分区规则	半天
Day 2	组织维 JOIN 键 + 3 张最常用事实表	半天
Day 3	一个真实主题端到端样板 + README	1 天
之后	每遇新口径 / 新坑 → 补一行	5 分钟/次

Reference 是活文档。 只读不写，会迅速腐烂。

---

五、主题 SQL 与 README：让知识「跑起来」

5.1 按主题而非按层分目录

❌ sql/dwd/、sql/dws/ 堆满文件，Agent 不知道业务链路。

✅ sql/user_growth/、sql_revenue/ —— 一个文件夹讲一个故事。

5.2 主题 README 模板

# 主题：用户增长日报

## 粒度
- DWS：user_id × ds
- DM：channel × ds

## 链路
ods_app_event → dwd_event_clean → dws_user_active_d → dm_rpt_growth_d

## 窗口
- 日：[ds, ds+1) 半开区间
- 7 日回流：event_time >= ds-6 AND event_time < ds+1

## 口径定稿
- 活跃：至少 1 次 launch 事件
- 剔除：is_test_account = true

## 已知差异
- 与 BI 看板差异：看板含 H5，本链路仅 App（待对齐）

5.3 单文件 SQL 结构建议

-- ============================================================
-- dm_rpt_growth_d | 用户增长日报 | 上游: dws_user_active_d
-- 口径: 见 sql/user_growth/README.md
-- ============================================================

WITH params AS (
    SELECT CAST('${bizdate}' AS DATE) AS biz_dt
)
,base AS (
    SELECT ...
    FROM dws_user_active_d
    WHERE ds = '${bizdate}'
)
INSERT OVERWRITE TABLE dm_rpt_growth_d PARTITION (ds = '${bizdate}')
SELECT ... FROM base
;

-- DDL（开发环境）
-- DDL（生产环境，若命名空间不同）

INSERT 与 DDL 同文件，改字段时结构不脱节。

---

六、还可以配什么：从能用到好用

组件	用途	优先级
.cursor/rules/	语言、commit、PR 等全局短规则	中
MCP 连元数据平台	Agent 查真实 schema，减少幻觉	高（有平台时）
报表截图 / 字段映射	列名 ↔ 中文表头 ↔ SQL 字段	高（出报表场景）
DQ 规则摘要	主键重复、空分区、环比阈值	中
dbt schema.yml	若用 dbt，与 Reference 互链	视技术栈

MVP 三角：Skill + Reference + 一个主题 SQL。 其余按需加，别第一天就造「知识中台」。

---

七、注意事项：AI 很勤快，也很会编

7.1 三类典型幻觉

1. 表存在、字段不存在 —— Reference 或 MCP 补 schema。
2. 字段存在、口径不对 —— 选用矩阵写死时间字段与过滤条件。
3. 逻辑自洽、业务错误 —— 人做样本抽检，Agent 不做最终定稿。

7.2 五条铁律

1. 口径人定，代码机写。
2. 金额单位写进 Skill，写三遍都不嫌多。
3. 枚举不猜 —— 订单状态、渠道码、退款原因，表格化进 Reference。
4. JOIN 键不猜 —— 写清默认键与「发散风险」备用路径。
5. 每次 Review 的修正，回写文档 —— 否则下次照样错。

7.3 人机分工

人	AI
定指标口径	生成 CTE / INSERT 骨架
确认是否一对多发散	批量重命名、补 COMMENT
Dev 环境跑数验证	按 Review 清单自查
对齐业务与看板差异	文档润色与结构整理

---

八、提效到底提在哪：别只数「少写了多少行」

8.1 速度：从「从零写」到「从零审」

• 分层 SQL 骨架、窗口 CTE、DDL 双环境 —— 分钟级出初稿。
• 宽表拼接、字段 COMMENT 对齐报表表头 —— 机械劳动大幅减少。
• 同类主题复制改写 —— Agent 读 README 即可类推。

8.2 质量：把事故扼杀在习惯里

• 分区必滤、SELECT * 禁止、半开区间 —— 成为默认肌肉记忆。
• 反模式清单 = Review Checklist，新人也能按图索骥。

8.3 知识：离职不带走，争论不重演

• Skill / Reference 在 Git 里 可 diff、可回滚。
• 对话里的结论不沉淀 = 下次重新解释；沉淀了 = 团队复利。

8.4 协作：从「口口相传」到「PR 式改口径」

旧模式：问老员工 → 搜历史 SQL → 复制改 → 上线后才发现口径不一致

新模式：改 Reference → Agent 按新口径生成 SQL → 人审 + 跑数 → 合并

每一轮需求都在加固数仓，而不是消耗老员工。

---

九、七天落地计划（可直接执行）

天	任务	产出
D1	建 Skill 骨架：环境、分层、命名、分区	SKILL.md v0.1
D2	写 3～5 张最高频表的 Reference 条目	reference.md v0.1
D3	选最简单主题，跑通 ODS→DWD 或 DWD→DWS 一条链	sql/{topic}/
D4	补选用矩阵 + 反模式；用 Agent 重写 D3 SQL 做 diff	Skill v0.2
D5	加 date_bound / 调度参数模板	Reference 模板节
D6	第二主题或 DM 报表层；写 README	链路文档
D7	同事试用；收集「Agent 哪里错了」→ 回写文档	v1.0

不要等文档完美。 用真实需求养文档，用文档训 Agent。

---

十、结语：Cursor 是笔，Skill 是章法

会用 Cursor 写 SQL 的人很多，能把它变成 团队数仓操作系统 的人很少。

记住三句话：

1. Skill 定章法，Reference 存事实，SQL 验真假。
2. AI 负责快，人负责对。
3. 口径争论结束的那一刻，就是文档该更新的一刻。

数仓的 AI 提效，表面是「写得更快」，底层是 知识有没有被结构化。Cursor 只是笔；你留给 Agent 的那本手册，才决定它写的是「能跑的 SQL」，还是「你们公司认的 SQL」。

相关内容

实时数仓新征程
https://blog.csdn.net/weixin_43932609/article/details/144446342
开启数据湖 “宝匣”
https://blog.csdn.net/weixin_43932609/article/details/144406593
数据仓库：智控数据中枢
https://blog.csdn.net/weixin_43932609/article/details/144393368

=========================================================

人生得意须尽欢，莫使金樽空对月！
__一个热爱说唱的程序员。
今日份推荐音乐：王以太 / 艾热AIR《周旋》

=========================================================