Anthropic 如何用 Claude 实现自助式数据分析

核心思想

Anthropic 数据团队复盘：他们把 95% 的业务分析查询交给 Claude、整体准确率约 95%，靠的不是更强的代码生成，而是一个判断——分析准确性本质上是上下文与验证问题。文章给出对症三大失败模式（概念<>实体歧义、数据陈旧、检索失败）的四层技术栈：数据基础层、真相源、技能、验证；核心取舍是把歧义收拢成唯一受治理的答案，并坦然接受治理与验证背后的人力成本。

很多数据科学和数据工程团队都深有体会：让业务分析实现自助（self-service），历来是件苦差事。

为了让技术能力较弱的同事更容易上手数据模型，团队常常用又宽又反范式的表(denormalized tables)来铺路，可随着业务扩张，这往往演变成定义彼此矛盾、相互重叠的一堆视图（而对那些压根不想学 SQL 的员工来说，几乎起不到弥合作用）。另一条路是为用户搭建更多围栏式的环境，但这又常常漏掉长尾的业务问题，并在各团队各自为政时催生指标和看板的泛滥。

大语言模型(LLM)的兴起，为自助式分析提供了又一条能绕开这些难题的路径。然而，把 Claude 直接对准数据仓库、放手让智能体去执行，可能制造一种虚假的精确感。

摆脱临时取数请求的最初狂喜，会在你意识到一件事后变成恐慌：这种做法把利益相关方与底层的基础设施、文档和专业知识隔开了，而正是这些东西，过去一直在引导他们走向那些精心整理过的数据集。

在 Anthropic，95% 的业务分析查询由 Claude 自动完成，整体准确率约 95%。把这些往往机械、重复的活儿交给 Claude，我们的数据科学团队就能腾出手来，专注于更具战略性的工作，比如因果建模、预测和机器学习。

在与数十位 Anthropic 顶级 Claude Code 用户交流、见识过五花八门的分析智能体设计模式之后，我们为其他正在使用 LLM 的数据团队沉淀出了一些最佳实践。在这篇文章里，我们将分享这些把 Claude 驱动自助业务洞察的能力发挥到极致的技巧与方法，包括：

为什么分析准确性是一个上下文与验证问题，而非代码生成问题；
导致大多数错误的三种失败模式；
我们为消除这些错误而搭建的智能体分析技术栈；
我们如何衡量效果；以及
我们创建大多数技能(skill)所用的一份基础模板（见附录）

数据不是软件

LLM 的生成能力是一把双刃剑：那套能为复杂问题给出创造性解法的机制，同样可能产生幻觉(hallucination)、吐出错误的输出。要透彻理解分析智能体面临的挑战，不妨拿它和编码智能体作个对比。

编码是一个开放式的解空间，它奖励模型的创造力，而文档和测试为防范幻觉提供了天然护栏。相比之下，分析类用例往往只有一个正确答案、对应一个正确的数据源，而且没有任何确定性的办法去证明答案的正确性。

对于自助式智能体业务分析来说，复杂性主要在于数据的歧义。问题的核心，归结为我们把用户的问题映射到数据模型中具体且最新的实体、并知道与之打交道的正确方式的能力。只要能做到这一点，后续的执行和 SQL 就变得微不足道了。

我们识别出这个问题的三个属性，它们解释了绝大多数不准确的回答：

概念<>实体歧义：在数据模型中数以百计可行的选项里（而潜在字段可能多达数百万），智能体无法选出最能回答用户问题的那些正确字段。比如，在衡量活跃用户数时：哪些行为才算”活跃”？要不要把欺诈用户算进去？用多长的回溯窗口？
数据陈旧(staleness)：数据源、业务定义和模式（schema）一直在变；数据资产和智能体的知识会逐渐过时，开始返回一些细微出错的答案。
检索失败(retrieval failure)：正确的信息其实可能就在数据模型里、也标注妥当了，但鉴于搜索空间之浩瀚，智能体就是找不到它。

我们的智能体分析技术栈

在 Anthropic，我们把这三类错误降到最低的主要手段，就是这套智能体数据技术栈。每一层的存在，主要都是为了攻克其中一个或多个问题：

实体歧义：数据基础层与真相源(source of truth)收缩可能实体的空间，直到只剩一个受治理的答案。
陈旧：维护与验证流程防止一切随业务变化而腐烂。
检索失败：技能确保智能体可靠地找到、并正确地用上那个答案。

在这一节，我们将逐层讲述每一层是怎么搭起来的。

维度建模(dimensional modeling)这类标准的数据工程实践，其重要性一如既往。

数据基础层

确保分析智能体准确性最重要的一环，是扎实的数据基础——它包括数据仓库中的数据模型、转换（transform）、测试和表，以及描述它们的元数据。维度建模、左移测试(shift-left testing)、对关键管道做新鲜度(freshness)与完整性检查等标准的数据工程与数据质量实践，依然全部适用（这些我们就不再赘述了）。

维度建模这类标准的数据工程实践，其重要性一如既往。

真正发生变化的是：你数据模型的终端用户不再是数据专家（比如数据科学家），而是代表用户行事的智能体——而这些用户对数据的专业程度、对底层基础设施的理解参差不齐。这一转变带来一个挑战：结果不能要求用户去验证底层的正确性，原因很简单——终端用户根本不懂。

数据基础层主要针对的是歧义：举例来说，如果营收能解析到一个受治理的数据集、而不是四十个看似可行的候选，那么这个问题在智能体动手搜索之前就基本消失了。这一层也是抵御陈旧的第一道防线，因为定义规范模型的那个仓库，天然就是强制它们保持最新的地方。

我们发现有几项实践特别管用：

打造规范数据集(canonical dataset)：到目前为止，最常见的失败是智能体无法把一个概念（“产品 X 的营收”）映射到唯一正确的表、列和指标定义上，通常是因为存在多个看似可行、实现却有细微差异的候选。解法是更少、治理更严的逻辑模型：精心整理出一小批规范的、单一真相源(source of truth)的数据集，让它们归属清晰、开箱即用、易于发现，然后大刀阔斧地弃用那些近似的重复项。物理汇总表和缓存对成本与性能仍然重要，但它们应当从规范模型机械地派生出来，而不是作为替代品与之并列存在。目标是：当智能体搜索一个概念时，它找到的是一个受治理的唯一答案。
强制执行你的标准：我们发现，只有当规范模型和指标定义被以下三者强制执行时，根基才站得住：被工具强制（智能体从结构上被优先路由到它们，下文详述）、被CI（持续集成）强制（绕开它们的改动通不过审查）、被强制要求强制（下游团队要么在受治理的层之上构建，要么解释为什么不这么做）。否则，没有强制执行的治理(governance)会迅速退化回那个”多候选”问题。
就近放置工件（colocate）：我们对抗数据模型和业务逻辑不断变化的主要防线，就是同仓共置(colocate)。几乎所有数据代码（即建模、语义层、参考文档、规范看板定义）都放在同一个仓库里，并辅以保护跨层完整性的 CI 检查。如果一处建模改动会破坏下游某个看板、或让某个有文档记录的指标失效，CI 会标记出来，修复也在同一个 PR（拉取请求）里随之上线。（这一机制的细节，我们会在下文的技能一节再回来讲。）
把元数据当作一等公民产品来对待：编码智能体表现出色，部分原因在于代码库是可读的（legible）：README、类型签名、文档字符串（docstring）等等。你的数据仓库也可以同样可读，但前提是列与表的描述、规范指标定义、粒度(grain)文档、有效取值范围、血缘(lineage)、归属和模型分级，都要以与转换本身同等的严谨度来维护。这虽算不上什么新见解，但良好的治理能提供关键上下文，帮助智能体选对数据集。

真相源

如果说数据基础层就是数据仓库本身，那么真相源就是智能体为了在仓库中导航而查阅的那些参考面（reference surface）。这一层降低概念<>实体歧义，把利益相关方问题里的”周活跃用户”变成你数据模型中一个具体的、受治理的实体。大致按信任度从高到低排列：

语义层(semantic layer)： 即编译后的指标与维度定义。如果一个问题干净利落地映射到某个已定义的指标，智能体调用一个函数就能得到一个数字——和公司里其他每一个面给出的，是同一个数字。我们的智能体从结构上被要求（通过技能指令）优先调用语义层（见附录）。有一个我们试过、却没奏效的点子：用一个 LLM 从原始表和查询日志中自动生成指标定义，以此为语义层做冷启动。它产出的定义看上去合情合理，却把我们正想消除的那些歧义固化了进去，而且在我们的评测里，相比一个更小、由人工整理的层，它是净负面的。因此我们建议：用 Claude 来生成文档，但让人来掌管定义。
血缘与转换图： 当语义层覆盖不到某个问题时，血缘和表排名（按被引用次数）让智能体能够推断：哪些上游模型供给了某个概念、哪些已被弃用、哪些共享同一粒度。这就把”我不知道这个指标”变成了”我知道该从哪个受治理的模型去聚合”。它也是我们在下文在线验证中呈现的新鲜度与溯源信号的骨干。
查询语料库(query corpus)： 即来自看板、笔记本和既往分析的历史 SQL。直觉上，这应该很有价值：凡是已正确回答过的问题，它都有记录。但实践中我们发现，让智能体直接检索数千条既往查询，准确率的提升还不到一个百分点（这个消融实验我们会在后文某一节里详细走一遍）。非结构化的检索无法把一个新问题映射到正确的先例上。真正奏效的，是把这份语料库提炼成结构化的、按领域划分的参考文档(reference docs)，以及在技能中描述的可复用分析模式。把查询历史当作供整理的原材料，而不是智能体直接读取的真相源。
业务上下文： 这是大多数团队会跳过的一层，也是我们低估了最久的一层。一个不懂你业务的智能体，会回答用户字面上问的，而不是他们真正想问的。它不会知道”Q2 那次发布”指的是某个特定产品，不会知道两个团队对同一个术语的定义并不相同，也不会知道某个问题之所以被提出，是因为周四要开董事会。我们接入了一张公司知识图谱，由建好索引的文档、路线图、决策日志和我们的组织架构构成，好让智能体能够解析这些隐含的指代、并提出更到位的澄清式提问。

贯穿这四者的共同失败模式，和数据基础层那一层是同一个：糟糕或陈旧的文档。Claude 在弥合这一鸿沟上格外有用（起草列描述、从查询模式中提议指标文档、在 CI 中标记未写文档的模型），但整理与归属仍由人来管理。

接下来的两节，我们将讨论如何把这种”归属”的成本压到足够低，低到它真的会发生。

技能

如果说真相源是智能体的陈述性知识（即一个指标意味着什么），那么技能就是它的程序性知识：该按什么顺序查阅哪些源、如何在有歧义的数据中导航、一份完成的分析长什么样。

在 Claude Code 里，一个技能就是智能体按需读取的一个 markdown 文件夹。在 Anthropic，我们开发的技能价值巨大。没有技能时，Claude 在我们评测中准确回答分析问题的能力没能超过 21%。加上技能后，这个数字整体稳定在 95% 以上，在某些领域还常常在 99% 上下。我们创建大多数技能所用的一份骨架，见附录。

一些最佳实践：

创建成对的技能： 一个knowledge技能充当一个轻量的顶层路由器(router)，让额外的领域细节得以按需加载。它说的是：“先试语义层，但如果没有覆盖，这里有这个领域约 30 个参考文件，描述了相关的表、列、连接（join）和坑（gotcha）。“这个路由器实际上就是我们对检索失败的回应：与其放任智能体在一个百万字段的仓库里搜索，不如在任何查询被写出之前，就把空间收窄到几十个精心整理过的文件。而unbook技能则把一位资深分析师会遵循的流程编码下来：澄清问题、（通过 knowledge 技能）找到数据源、运行查询，然后让结果穿过一圈对抗性审查(adversarial review)子智能体。它还打包了十几个可复用的分析模式（留存曲线、比率分解、漏斗分析），这样常见的请求就不必每次都重新发明一遍。

编写规范的参考文档：写出来是供 LLM 检索用的。我们的参考文档描述表（粒度、范围和排除项）、坑的机理（例如”排除已知的免费邮箱域名，但保留像 anthropic.com 这样的自定义域名”），以及明确的路由触发条件（例如”如果问题是关于实验提升量……不要用于原始事件计数”），而不写那些会过时的处方式食谱。我们创建参考文档所用的一份骨架，见下文。

# [Domain] Tables
 
## Quick Reference
### Business Context — [what this domain means in plain words]
### Entity Grain — [what one row represents]
### Standard Hygiene Filter — [the filter every query in this domain applies]
 
## Dimensions
- [How the key dimensions are encoded, and how the same concept is named
  differently across tables]
 
## Key Tables
### [table_name]
- **Grain**: [...] · **Scope/exclusions**: [...]
- **Usage**: [when to use it, when NOT to, join keys, required filters]
[... one short section per governed table ...]
 
## Gotchas
- [The wrong-answer modes a senior analyst would warn you about]
 
## Best Practices / Common Query Patterns
- [Default choices, standard cuts, worked patterns where the exact query
  form is the hard part]
 
## Cross-References
- [Neighboring domain docs that own adjacent questions]

把技能维护当作一等公民：技能文档描述的是一个每天都在变的数据模型，所以缺了主动维护，它们几周内就会变得不对。我们曾眼睁睁看着离线准确率在一个月里从上线时的约 95% 漂移到约 65%，之后才把这件事当成一个工程问题来对待。这意味着把技能 markdown 文件与我们的转换模型就近放置在同一个仓库里，于是改动某个模型的那个 PR，就是更新描述它的那份文档的同一个 PR。一个 code-review hook 会标记任何”动了上报模型却没碰技能文件”的改动。如今我们大约 90% 的数据模型 PR，在同一个 diff 里都包含了一处技能改动。随着模型的进步、以往的失败模式不再适用，我们也会定期修剪技能脚手架。

在所有触达面（surface）上打造一致而无缝的体验：同一个技能必须对 Slack、IDE、看板工具和独立智能体会话中的同一个问题，给出同一个答案。我们做到这一点的办法，是确保只有一个规范来源（数据仓库），并让技能改动自动同步。在合并时，技能会同步到一个插件市场(plugin marketplace)（供 IDE 用户使用）、同步到云存储 blob（供那些读取单个文件的托管应用使用），并通过 MCP 直接作为资源提供。我们从一开始就为可移植性做了设计，避免硬编码仓库路径和特定于触达面的命名空间。

验证

最后，验证是你弄清楚三种失败模式中哪一种仍在漏出来的方式。

离线评测

我们常见到一种模式：数据团队会搭起精致的分析环境，却没有任何流程去了解他们分析智能体的准确性。

弥补这一缺口的一种办法是离线评测(offline evals)，也就是简单的问/答对。你可以把离线评测类比为对一个机器学习模型做离线测试：它们不会告诉你在线智能体的表现，但确实能让你大致看出自己有没有什么关键缺口。

在 Anthropic，我们部署了两类离线评测。基于看板的评测由 Claude 自动生成（再经人工校验），覆盖最常见的利益相关方问题。长尾评测则是我们把业务上下文（路线图、表文档）喂给 Claude，让它在该领域的其余部分生成合情合理的问题。我们还持续地收割每一次利益相关方在某个会话串里纠正智能体的情形——因为那一次纠正，就是一个候选评测。

其他最佳实践包括：

锚定基准答案(ground truth)，让它无法漂移：一个针对实时数据写的评测，会在底层数字一变动的那一刻就过时。把每个评测钉在一个快照日期上、针对一张稳定的事实表来写，或者让评分器去评判智能体的查询而非它给出的数字。把整套评测接进 CI，这样一个改动了某依赖的 PR 就会重跑受影响的评测。
像存遥测数据那样存结果，而非像存测试日志： 每一次运行都落到一张数据仓库表里，带上技能版本、git SHA、模型 ID、逐条断言的通过/失败、token 数和实际耗时（wall-clock）。“那次改动有没有帮助？“就此变成一条查询，而且你会拿到时间序列，用来捕捉单次 CI 运行抓不到的缓慢回退。
按领域设置上线门禁：一位领域负责人，在其负责的那部分评测集清过某个阈值（我们最初用约 90%）之前，不得向其利益相关方宣布该智能体可用。这迫使参考文档的修复发生在用户看到失败之前。
创建数量适当的评测：你该有多少个评测，取决于业务领域的复杂度和底层数据模型的复杂度。校准的办法是追踪离线准确率对在线准确率的预测能力有多好：我们发现，每个主题（比如”增长”）超过几十个评测之后，收益就开始递减，而且这个上限会随着每一代新模型的出现而下降。
离线评测准确率应当达到约 100%；每一个正确答案也都应当命中你的语义层（如果你有的话）。再说一遍，这个准确率水平并不能告诉你你的系统不会产出错误答案，它只是说明——在你有恰当评测覆盖的前提下——没有什么明显的缺口。

消融技术

关于技能的每一个结构性决策（例如该暴露哪些源、某个子智能体值不值得它带来的延迟、要不要把两个技能合成一个），都是在保持我们的离线评测集固定不变的情况下做出的。

我们每次只改变一个组件，然后比较通过率。每次运行只花一小时，却能替代一大堆口水仗。方法论比任何单个结果都更重要：

为零结果(null result)而设计。 我们最有用的一次消融实验(ablation)，得出的是一个否定性的结论。我们让智能体可以直接 grep 我们全部的看板、转换和分析师笔记本 SQL（数千个文件）。随后我们在转录记录里核实：它在每次回答之前确实读过它们。准确率上下浮动都不到一个百分点。接着我们排查那些显而易见的混杂因素：对于它答错的那些问题，答案是否真的在语料库里？大约 80% 的情况下，是的。那么”答案在场”能否预测”现在答对了”？不能——翻转率（flip rate）几乎没动。信息就在那儿，智能体也看到了，可它还是没用上。仅这一个实验就告诉了我们：瓶颈不是对既往工作的访问，而是结构（即把一个问题映射到正确的实体）。这个洞见让我们调转了数个月的路线图方向。
以 PR 为粒度做消融。 每一次有意义的技能编辑，都会在相关的评测切片上跑一次前/后对比，并把差值写进 PR 描述里。这让”我改进了文档”这句话经得起检验，也能抓住一种出人意料地常见的情况：一处出于好意的添加，反而把事情弄糟了。
保留一份”没奏效的东西”的简短清单。 我们的两个例子：把额外几轮的文档精修叠加到某个点之后（我们撞上了连续三轮净负的迭代：文档是越来越长，而不是越来越好），以及把对抗性审查器换成一个更便宜的模型以削减延迟（它丢掉了大部分准确率上的收益，却没换来什么真正的提速）。阴性结果记录起来成本很低，而且能防止下一个人重跑同一个实验。

在线验证

最后一步，是确保实际在线系统的表现尽可能准确。我们采取的一些措施包括：

对抗性审查：我们发现，启用一个 Claude 技能去激进地挑战一个潜在最终答案背后的所有假设，能在我们的评测集内把准确率提升 6%，但代价是多消耗 32% 的 token、延迟升高 72%。
溯源页脚(provenance footer)： 每一个回答都带一个页脚，载明它来自哪个数据源层级（语义层 › 整理过的参考 › 原始表）、底层数据有多新鲜、以及谁是这个模型的归属人。它不会让答案更正确，但确实能帮助消费者判断自己能在多大程度上信任这个回答。一个”原始表，新鲜度未知”的页脚，就是一个”在向上转发之前先核实”的信号，也是我们针对静默失败为数不多的缓解手段之一。
数据质量检查：有一种可能是，你的智能体用对了字段、用法也得当，但数据本身就是错的。加上一些基本的数据质量检查，确保被引用的字段是最新的、完整的、没有异常，通常是个好习惯。
被动监控： 我们持续追踪的两个生产信号是：智能体查询中通过语义层解析的占比，以及回答中使用纠正性措辞（“那张表用错了""你漏了欺诈过滤器”）的占比。两者都汇入一个每周审阅的看板，与离线通过率并列查看。
主动纠错采集：这是闭合整个回路的那一环。一个定时智能体每隔几小时扫描一次利益相关方的频道，寻找类似的纠正性措辞，为相关的参考文档起草一行修复，并开一个标记给领域负责人的 PR。这条修复路径刻意做得平淡无奇——编辑一个 markdown 文件、合并、自动同步到各处——好让领域负责人不必在这件事上花太多时间。同样的这些纠正，也会反哺回离线评测集。

这一切都无法完全捕获的那个失败模式，是静默的那一个：答案是错的，但看起来合情合理，于是被无异议地采用了。我们的缓解手段是溯源页脚、对任何呈送领导层的内容做明确的人工签字确认，以及为每个领域的头部 KPI 设一个常驻评测，每天对照那张获认可的看板做一次合理性核查——尽管我们还没有一个稳妥的解决方案。

上手起步

如果你从零开始，少数几个规范数据集、几十个离线评测，外加一个轻量的 knowledge 技能，就能拿下大部分收益；本文中其余的一切，都是我们在这些东西建好之后才加上去的。

我们也分享了许多最佳实践，但并非每一项都适合每一个数据团队。不妨通过自问以下几个会影响你做法的问题，与你的组织在几条原则上达成一致：

今天就要一个正确答案，相对于将来才要，有多重要？AI 模型正在以飞快的速度进步。我们常看到一些公司为弥补当前模型的不足而构建大量基础设施，可一旦那些模型变强，这些设施就变得无关紧要了。摸清模型在哪里不足、并等待模型进步去填补缺口，开销要小得多，但这未必契合你公司的风险容忍度。
你预计你的业务复杂度会随时间如何变化？我们讨论的某些流程也许是杀鸡用牛刀——比如说，如果你产出的数据不多、输出的消费者只有寥寥几个、或者你的数据模型大概率会保持简单。
输出的目标受众技术水平如何？换个说法：如果你是在为那些能识别出答案何时不对的数据科学家构建这套分析系统，那么相比受众对底层数据模型毫无了解的情形，你也许能更容忍错误。
为了提升准确率，你愿意花多少钱？我们发现，对抗性验证之类的某些流程能显著提升准确率，但往往伴随更高的成本和延迟。
你对访问控制和内部数据隐私的接受度如何？智能体往往是上下文越多、表现越好；然而，宽泛的数据访问权与大多数公司的治理姿态相抵触。这一点决定了你是在构建一个智能体，还是多个范围受限的智能体。

无论你走哪条路，我们最大的收益都来自针对那三种失败模式逐一对症下药：把歧义收拢成一个受治理的唯一答案、让这个答案易于被发现、并在两者中任意一个变得陈旧时发出标记。

本文由数据科学与数据工程团队成员 Chen Chang、Clement Peng、Justin Leder、Johanne Jiao 和 Josh Cherry 撰写。作者感谢 Michael Segner 的贡献。

附录

技能文件骨架（Skill File Skeleton）

接下来是我们主仓库技能的骨架：真实文件的结构，其中的内部细节已被替换为[方括号占位符]。它并不是要被逐字照抄，而是要展示我们认为值得写下来的那几类章节。

---
name: [warehouse-skill]
version: [x.y.z]
description: "IF the user asks to query [the company]'s data warehouse for any
  [list of business domains] question — THEN invoke this skill. DO NOT invoke
  for [adjacent engineering tasks] or questions with no data-warehouse component."
---
 
# [Warehouse] Skill Instructions
 
## Description
The single source of truth for safe and effective [warehouse] querying.
Referenced by other skills [listed] for query execution guidance.
 
Act as a Data Analyst, providing strategic insights and data-driven
recommendations but seek guidance along the way.
 
**Out-of-scope decisions**: [product areas, etc.] → surface data only,
state "decision is [owning team]'s call", do NOT take a position or author
code fixes.
 
## Executing queries
Priority:
1. **[Managed connection]** (if available): [query tool] / [schema tool]
2. **[CLI fallback]** (if installed): [default project, fallback project]
3. **Neither** — ask the user to authenticate, then stop
 
---
 
# Semantic Layer (REQUIRED first step)
 
The governed semantic layer is the **mandatory default path** for every data
question — same numbers as [the BI tool], joins/grain/filters baked in. Raw SQL
via the reference docs below is the **fallback**, used only after the
semantic-layer path is shown not to cover the ask.
 
## Required workflow
1. **Load** — [how to load the semantic layer in each runtime, with fallbacks]
2. **Discover** — search measures/dimensions by keyword; **always check
   segments** (the named canonical population filters — hand-rolled WHERE
   clauses for these are the dominant wrong-answer mode)
3. **Compile + run** — build the spec → compile to SQL → execute
4. **Fallback** — only if discovery finds no relevant metric or compile fails
   → raw SQL via \`references/*.md\` (PART 3 below)
 
> **Don't bail early.** Do NOT fall back to raw SQL on these grounds:
> - "[custom date filtering / cohorts]" → [covered by time-dimension specs]
> - "[needs a join]" → [the metric layer already encapsulates its joins]
> - [3–4 more pre-rebutted excuses agents use to skip the semantic layer]
 
### Date windows & timezone — decide before you query
- **As-of date vs trailing-N days**: [convention for each]
- **"Last week/month"** → the last *complete* calendar week/month, not trailing-7/30
- **Timezone default**: [TZ]; [exception for certain reporting rollups]
- **Freshness lag**: [some] tables settle late — anchor on MAX(date), not "yesterday"
 
---
 
# PART 1: MUST KNOW (Read First for Every Request)
 
## 🚀 Quick Start Workflow
1. **Check for red flags first**: [restricted/PII requests, gated domains,
   high-stakes asks that need extra validation]
2. **Out of scope — escalate, don't guess**: [access requests, pipeline
   troubleshooting, stale dashboards, root-cause assertions, product/pricing
   recommendations] → redirect to [the owning team], don't answer
3. **Clarify the request**: time period, segment, the business decision it informs
4. **Check for existing dashboards**: [per-domain dashboard catalogs]
5. **Identify the data source**: [navigation map below; prefer governed/aggregated tables]
6. **Execute the analysis**: [required filters + adversarial review]
7. **Deliver insights**: show methodology, differentiate observations from interpretations
 
## 🏢 Business Context
 
### Entity Disambiguation (MUST CLARIFY)
- **"[Term A]" can mean**: [entity 1] or [entity 2] — always clarify which
- **"[Term B]" can mean**: [entity 1] → [entity 2] → [entity 3] (one-to-many chain)
- **"Users"**: [which identifier gives accurate counts, and which ones inflate them]
 
### Business Terminology
- [Current product names vs deprecated aliases that still appear as frozen
  values in the data layer — write with the new names, filter with the old]
- [Key internal acronyms]
- **[Headline metric] calculations**: [monthly / default window / leading indicator]
- **Unfamiliar terms — search [internal docs], don't guess**
 
### Data Integrity Requirements ⚠️
- **NEVER**: make up data/columns; make speculative assertions beyond what data shows
- **ALWAYS**: use safe division; differentiate observations ("data shows X")
  from interpretations ("this suggests Y"); flag limitations
 
---
 
# PART 2: HOW TO DO (Follow During Execution)
 
## 🔧 Technical Execution Guide
- [Managed-connection tools and CLI invocation details]
- **PII protection**: for restricted data, return the SQL for the user to run
  themselves — do not return results
 
## 📊 Analysis Best Practices Guide
1. Clarify the ask before querying
2. Show your work (filters, inclusions/exclusions, freshness)
3. Clarify denominators
4. Consider sample bias
5. Connect to business impact
6. **Adversarial SQL review (MANDATORY)** — spawn the [sql-reviewer] sub-agent
   for every query before the final answer; blocking findings must be fixed
   and re-reviewed; do not self-certify
7. **Report with provenance** — every answer ends with a footer:
   > **Source:** [semantic layer | governed table | raw exploration] ·
   > **Confidence:** [tier] · **Reviewed:** [reviewer ✓, round N] ·
   > **Freshness:** [max date in the data] · **Owner:** [owning team]
 
---
 
# PART 3: DATA REFERENCES & RESOURCES
 
## 📚 Knowledge Base Navigation
### [Domain A] → \`references/[domain_a].md\`
- **Use for**: [kinds of questions]
- **Key tables**: [...]
- **Dashboards**: \`references/[domain_a]_dashboards.json\`
 
### [Domain B] → \`references/[domain_b].md\`
- **Use for**: [...]
 
[... one entry per business domain — a few dozen in total ...]
 
## ⚠️ Troubleshooting Guide
 
### When Information Is Missing
- [missing tables / access denied / outdated docs / unknown enum values → what to do]
 
### Field Naming Gotchas
- Use \`[field_x_v2]\` NOT \`[field_x]\`
- [Two similarly-named tables report the same metric at different grains — which to use]
- [Which of two plausible sources is canonical for the headline metric]
- [… a dozen more hard-won one-liners …]

AI 知识库

探索