Anthropic 用 Claude 赋能自助数据分析

正如许多数据科学和数据工程团队所亲身经历的那样，实现自助式业务分析历来都是一件苦差事。

通过宽表和反规范化表让技术背景较弱的同事也能更轻松地使用数据模型，往往会在业务规模扩大时导致视图重叠、定义不一致（而且对于压根不想学 SQL 的员工来说，几乎起不到弥合鸿沟的作用）。反过来，为用户打造更多圈定范围的环境，往往会遗漏长尾业务问题，并因各团队各自为政而导致指标和仪表盘泛滥。

大语言模型的兴起为自助式分析提供了一条额外路径，能够避开这些挑战。然而，把 Claude 直接指向数据仓库并让智能体去执行查询，可能会制造出一种虚假的精确感。

最初从临时取数需求中解放出来的喜悦，很快会变成恐惧——因为人们意识到，这种设置让利益相关者与底层基础设施、文档和专业知识脱节，而正是这些此前引导他们走向精心整理的数据集。

在 Anthropic，95% 的业务分析查询由 Claude 自动完成，整体准确率约为 95%。把这类往往枯燥重复的工作交给 Claude 之后，我们的数据科学团队可以专注于更具战略性的工作，比如因果建模、预测和机器学习。

在与数十位 Anthropic 的顶尖 Claude Code 用户交流，并见识了分析类智能体的各种设计模式之后，我们为其他使用 LLM 的数据团队总结出了一些最佳实践。在这篇文章中，我们将分享这些技巧和方法，以最大化 Claude 驱动自助式业务洞察的能力，包括：

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

数据不是软件

LLM 的生成能力是一把双刃剑：那些让模型能够为复杂问题提供创造性解决方案的机制，同样也可能产生模型幻觉式的错误输出。要全面理解分析类智能体所面临的挑战，将它们与编程智能体进行对比会很有帮助。

编程是一个开放式的解空间，它奖励模型的创造力，而文档和测试则提供了抵御模型幻觉的天然护栏。相比之下，在分析类用例中，往往只有一个正确答案、一个正确的数据源，且不存在确定性的方式来证明其正确性。

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

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

1. 概念 <> 实体歧义：数据模型中有数百个可用选项（而字段总数可能达数百万），智能体无法选出最能回答用户问题的正确字段。例如，在衡量活跃用户数时：哪些行为构成“活跃”？是否包含欺诈用户？使用多长的回溯窗口？

2. 数据陈旧：数据源、业务定义和 schema 不断变化；资产和智能体知识逐渐过时，开始返回微妙错误的答案。

3. 检索失败：正确的信息实际上可能就在数据模型中，并且已被恰当标注，但鉴于搜索空间的广阔，智能体就是找不到它。

我们的智能体分析技术栈

在 Anthropic，我们将这三类错误降至最低的主要方式，是通过我们的智能体数据栈。每一层的存在，主要是为了解决其中一个或多个问题：

1. 实体歧义：数据基础与事实来源收窄了可能实体的范围，直到只剩下一个受治理的唯一答案。

2. 数据陈旧：维护与验证流程确保一切不会随着业务变化而腐化。

3. 检索失败：技能确保智能体能够可靠地找到并正确使用那个答案。

在本节中，我们将讨论我们是如何构建每一层的。

数据基础

确保分析智能体准确性的最重要方面，在于扎实的数据基础，其中包括数据仓库中的数据模型、转换、测试和表，以及描述它们的元数据。标准的数据工程与数据质量实践，例如维度建模、左移测试、对关键流水线的新鲜度与完整性检查，依然全部适用（我们不再赘述这些）。

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

真正发生变化的是，你的数据模型的最终用户不再是数据专家（例如数据科学家），而是代表用户行事的智能体，这些用户的数据专业水平或对底层基础设施的理解程度参差不齐。这一转变带来的挑战在于，结果不能要求用户去验证底层的正确性，因为最终用户根本不懂。

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

我们看到有几种做法效果特别好：

• 创建规范数据集：迄今为止最常见的失败是，智能体无法将一个概念（“产品 X 的 revenue”）映射到唯一正确的表、列和指标定义，通常是因为存在多个看似合理、但实现上又有细微差异的候选。解决办法是减少逻辑模型的数量、加强治理：精心挑选一小组规范的、单一事实来源的数据集，它们归属清晰、可直接消费、易于发现，然后大力弃用那些近乎重复的版本。物理汇总和缓存对于成本和性能仍然重要，但它们应当从规范模型机械地派生出来，而不是作为替代方案与之并存。目标是当智能体搜索某个概念时，它能找到唯一一个受治理的答案。
• 强制执行你的标准：我们发现，只有当规范模型和指标定义被工具链强制执行（智能体在结构上被优先路由到它们；详见下文）、被CI强制执行（绕过它们的变更无法通过审查）、以及被强制要求强制执行（下游团队必须基于受治理的层来构建，否则需说明原因）时，这些基础才能站得住脚。没有强制执行，治理很快就会退化回多候选方案的问题。
• 将产物共置一处：我们抵御数据模型和业务逻辑不断变化的主要防线是共置。几乎所有数据代码（即建模、语义层、参考文档、规范仪表盘定义）都存放在同一个仓库中，并通过 CI 检查来保护跨层完整性。如果某项建模变更会破坏下游仪表盘或使某个已记录的指标失效，CI 会将其标记出来，修复随同一个 PR 一起发布。（我们会在下文的技能部分回到这一机制的细节。）
• 将元数据视为一等产品：编码智能体表现出色，部分原因是代码库具有可读性：README、类型签名、文档字符串等。你的数据仓库同样可以具备可读性，但前提是列和表的描述、规范指标定义、粒度文档、有效值范围、血缘关系、归属关系以及模型分层，都要以与转换逻辑本身同等的严谨度来维护。虽然这并非新见解，但良好的治理提供了关键的上下文，帮助智能体选择正确的数据集。

真相来源

如果数据基础是数据仓库本身，那么事实来源就是智能体用来在其中导航的参考界面。这一层减少了概念与实体之间的歧义，并将利益相关者问题中的“周活跃用户”转化为你的数据模型中一个具体的、受治理的实体。大致按信任度从高到低排列：

• 语义层：编译后的指标和维度定义。如果一个问题能清晰地映射到某个已定义的指标，智能体就调用一个函数并得到一个数字，与公司中其他所有界面产出的数字完全一致。我们的智能体被结构性地要求（通过技能指令）优先利用语义层（参见附录）。我们尝试过但没有成功的一个想法是：让 LLM 从原始表和查询日志中自动生成指标定义来引导语义层。它产出了看似合理的定义，却恰恰编码了我们试图消除的那些歧义，在我们的评估中相对于一个更小的人工策划层是净负面的。因此我们建议用 Claude 生成文档，但由人工负责定义。
• 血缘关系和转换图：当语义层无法覆盖某个问题时，血缘关系和表排名（基于引用次数）让智能体能够推理哪些上游模型为某个概念提供数据、哪些已弃用、哪些共享粒度。这将“我不知道这个指标”转化为“我知道该从哪个受治理的模型进行聚合”。它也是我们在下方在线验证中呈现的新鲜度和溯源信号的支柱。
• 查询语料库：来自仪表盘、notebook 和以往分析的历史 SQL。直觉上，这应该价值很高：它记录了每一个已经被正确回答过的问题。但在实践中我们发现，让智能体直接以原始检索方式访问数千条历史查询，准确率提升不到一个百分点（我们会在下文后续章节中详细走查那次消融实验）。非结构化检索无法把一个新问题映射到正确的先例。真正有效的是把该语料库蒸馏成结构化的按领域划分的参考文档，以及 技能中描述的可复用分析模式。要把查询历史当作供人工策展的原材料，而不是让智能体直接读取的真相来源。
• 业务上下文：这是大多数团队会跳过的一层，也是我们低估得最久的一层。一个不理解你业务的智能体会回答用户问出的问题，而不是他们真正想问的问题。它不会知道“Q2 发布”指的是某个特定产品，不会知道两个团队对同一个术语的定义不同，也不会知道有人问某个问题是因为周四要开董事会。我们接入了一个公司知识图谱，由已建立索引的文档、路线图、决策日志以及我们的组织结构组成，这样智能体就能消解那些含糊的指代，并提出更好的澄清性问题。

这四层中常见的失败模式，与数据基础层中的那个如出一辙：文档质量差或已过时。Claude 在弥合这一差距方面格外有用（起草列描述、根据查询模式提出指标文档建议、在 CI 中标记出未记录在案的模型），但策展和归属管理仍由人来负责。

在接下来的两节中，我们将讨论如何让这种所有权变得足够廉价，从而真正得以实现。

技能

如果说事实来源是智能体的陈述性知识（即某个指标意味着什么），那么技能就是它的程序性知识：按什么顺序查阅哪些来源、如何应对有歧义的数据，以及一份完成的分析应该是什么样子。

在 Claude Code 中，一个技能就是一个 markdown 文件夹，智能体按需读取。在 Anthropic，我们开发的技能带来了巨大的价值增益。没有技能时，Claude 在我们的评测中准确回答分析问题的能力不超过 21%。加入技能后，这些数字总体上稳定超过 95%，在某些领域经常达到 99% 左右。我们用来创建大多数技能的骨架模板见附录。

一些最佳实践：

**创建成对技能：**一个知识技能充当一个轻量级的顶层路由器，允许按需加载额外的领域细节。它说的是：“先试试语义层，但如果没有覆盖，这里有该领域约 30 个参考文件，描述了相关的表、列、连接方式和注意事项。”这个路由器实际上是我们对检索失败的应对方案：与其让智能体去搜索一个拥有百万字段的数据仓库，不如在编写查询之前就把范围缩小到几十个精选文件。操作手册技能编码了资深分析师会遵循的流程：澄清问题、查找数据源（通过知识技能）、运行查询，然后让结果经过对抗性审查子智能体的循环审核。它还打包了十几个可复用的分析模式（留存曲线、比率分解、漏斗分析），这样常见的请求就不必每次都重新发明一遍。

创建合适的参考文档：为 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。一个代码审查钩子会标记任何未触及技能文件的报表模型改动。如今我们大约 90% 的数据模型 PR 都在同一个 diff 中包含了技能改动。我们还会随着模型改进、此前的失败模式不再适用，定期修剪技能脚手架。

在所有界面上打造一致且无缝的体验：同一个技能必须在 Slack、IDE、仪表盘工具以及独立智能体会话中对问题给出相同的答案。我们通过确保只有一个权威来源（数据仓库）并让技能改动自动同步来实现这一点。合并时，技能会同步到一个插件市场（供 IDE 用户使用）、同步到云存储 blob（供读取单个文件的托管应用使用），并直接通过 MCP 作为资源提供。我们还从一开始就为可移植性而设计，避免硬编码仓库路径和特定界面的命名空间。

验证

最后，验证是你查明这三种失败模式中哪一种仍在漏网的方式。

离线评估

我们常见的一种情况是，数据团队会搭建起精细复杂的分析环境，却没有任何流程来了解其分析智能体的准确性。

弥补这一缺口的一种方式是离线评估，即简单的问答对。你可以把离线评估类比为 ML 模型的离线测试：它们不会告诉你线上智能体的表现如何，但能让你很好地判断自己是否存在任何关键缺口。

我们在 Anthropic 部署两种离线评估。基于仪表盘的评估由 Claude 自动生成（随后经人工验证），覆盖最常见的利益相关方问题。长尾评估则是我们向 Claude 提供业务上下文（路线图、表格文档），让它在该领域其余部分生成合理的问题。我们还会持续收集每一次利益相关方在对话线程中纠正智能体的情况，因为这种纠正就是一个候选评估。

其他最佳实践包括：

• 锚定基准真值，使其无法漂移：针对实时数据编写的评估，会在底层数字变动的那一刻就过时。把每个评估都固定到一个快照日期，针对稳定的事实表来编写，或者让评分器评判智能体的查询而非其数字。把这套评估套件接入 CI，这样一旦有 PR 触及某个依赖项，就会重新运行受影响的评估。
• 像存储遥测数据一样存储结果，而不是像测试日志那样： 每次运行都会落入一张仓库表中，包含技能版本、git SHA、模型 ID、每条断言的通过/失败、token 数量和实际耗时。“那个改动有帮助吗？”变成了一个查询，你还能获得时间序列，从而捕捉单次 CI 运行无法发现的缓慢回归。
• 按领域设置发布门槛：领域负责人无法向其利益相关者宣布该智能体，除非其对应的评估集切片达到某个阈值（我们最初使用约 90%）。这会迫使用户看到失败之前就修复参考文档。
• 创建适当数量的评估：你应该拥有多少评估取决于业务领域的复杂度和底层数据模型的复杂度。通过追踪离线准确率对在线准确率的预测程度来进行校准：我们发现每个主题（例如“增长”）超过几十个之后收益递减，而且这个上限会随着每一代新模型而下降。
• 离线评估准确率应约为 100%；每个正确答案也应命中你的语义层（如果你有的话）。再次强调，这种准确率水平并不能告诉你系统不会产生错误答案，只能说明假设你有恰当的评估覆盖，就不存在明显的缺口。

消融技术

关于技能的每一项结构性决策（例如，要暴露哪些数据源、某个子智能体是否值得其带来的延迟、是否将两项技能合并为一项），都是在固定我们的离线评测集的前提下做出的。

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

• 为无结果而设计。我们最有用的消融实验是一个负面结果。我们让智能体直接以 grep 方式访问我们整个仪表盘、转换流程和分析师笔记本的 SQL（数千个文件）。随后我们在对话记录中核实，它在每次回答之前确实读取了这些内容。准确率的变动在两个方向上都不足一个百分点。接着我们检查了显而易见的混杂因素：对于那些它答错的问题，答案是否真的存在于语料库中？大约 80% 的情况下，答案是肯定的。"答案存在"是否能预测"现在答对了"？不能，翻转率持平。信息就在那里，智能体也看到了，但它仍然没有使用。那一个实验告诉我们，我们的瓶颈不是对以往工作的访问权限，而是结构（即把问题映射到正确的实体）。这一洞见重新调整了我们数月的路线图。
• 以 PR 为粒度进行消融。每一次有意义的技能编辑都会在相关评测切片上做一次改动前/改动后的运行，并在 PR 描述中附上差值。这让"我改进了文档"这种说法保持诚实，并能捕捉到一种出奇常见的情况：一个出于好意的添加反而让事情变得更糟。
• 保留一份简短的“无效尝试”清单。我们自己的两个例子：在超过某个点之后继续叠加更多轮文档精炼（我们连续三轮迭代都是净负收益：文档变得更长，而不是更好），以及把对抗性审查员换成更便宜的模型以降低延迟（它丢掉了大部分准确率收益，却没有带来真正的速度提升）。负面结果记录起来成本很低，却能防止下一个人重复跑同一个实验。

在线验证

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

• 对抗性审查：我们发现，使用一个 Claude 技能来对潜在最终答案的所有底层假设进行激进质疑，在我们的评测集内将准确率提升了 6%，但代价是 token 用量增加 32%、延迟升高 72%。
• 来源页脚：每个响应都带有一个页脚，其中包含它来自哪个来源层级（语义层 › 精选参考 › 原始表）、底层数据的新鲜程度，以及模型的归属方。它不会让答案更正确，但确实能帮助使用者判断他们可以在多大程度上信任该响应。“原始表，新鲜度未知”的页脚是一个信号，提示在上游转发之前先做核实，而这也是我们针对静默失败为数不多的缓解手段之一。
• 数据质量检查：你的智能体可能以正确的方式使用了正确的字段，但数据本身是错误的。加入基本的数据质量检查，确保所引用的字段是最新的、完整的、没有异常的，这通常是一种良好的卫生习惯。
• 被动监控：我们持续追踪的两个生产信号是：通过语义层解析的智能体查询占比，以及使用纠正性措辞（“那是错的表”“你漏了欺诈过滤器”）的响应占比。两者都会汇入一个仪表盘，每周与离线通过率一同审阅。
• 主动纠正采集：这是闭环的关键一环。一个定时智能体每隔几小时扫描利益相关者频道，寻找类似的纠正性措辞，针对相关参考文档起草一行修复，并开一个 PR 并标记给领域负责人。修复路径刻意做得很无聊——编辑一个 markdown 文件、合并、自动同步到各处——这样领域负责人不会在这项任务上花太多时间。同样的纠正也会反馈到离线评测集中。

所有这些都无法完全捕捉到的失效模式，是静默的那种。答案是错的，但看起来合理，并且被毫无异议地使用了。我们的缓解措施是：来源脚注、任何面向领导层的内容都需明确的人工签核，以及针对每个领域顶级 KPI 的常设评测，每天对照权威仪表盘做合理性检查，不过我们目前还没有稳健的解决方案。

入门

如果你从零开始，少量经典数据集、几十个离线评测，再加上一个轻量的知识技能，就能捕获大部分收益；本文中的其他所有内容，都是我们在这些基础建成之后才逐步添加的。

我们还分享了许多最佳实践，但并非所有实践都适合每一个数据团队。请通过以下问题，与你的组织在若干将影响你方法的原则上达成一致：

• 当下获得正确答案与未来获得正确答案，哪个更重要？AI 模型正在快速进步。我们经常看到公司为了弥补当前模型的不足而构建大量基础设施，而这些不足一旦模型改进后便不复存在。了解模型在哪些方面存在不足，并等待模型改进来填补差距，开销要小得多，但可能不符合你公司的风险承受能力。
• 你预计你的业务复杂度会随时间如何变化？例如，如果你产生的数据不多、输出的消费者只有少数几个，或者你的数据模型很可能保持简单，那么我们讨论的某些流程可能就过于繁琐了。
• 输出的目标受众技术程度如何？换个说法，如果你是为数据科学家构建这套分析系统，他们能够识别出答案何时不正确，那么相比受众对底层数据模型毫无了解的情况，你对错误的容忍度可能更高。
• 为了提升准确率，你愿意投入多少成本？我们发现某些流程（例如对抗验证）可以显著提升准确率，但往往伴随着更高的成本和延迟。
• 你对访问控制和内部数据隐私的接受程度如何？AI 智能体拥有的上下文越多，其表现往往显著越好；然而，广泛的数据访问权限与大多数公司的治理立场相冲突。这决定了你是在构建一个智能体，还是多个范围受限的智能体。

无论你选择哪条路线，我们最大的收益都来自于解决这三种失败模式：将歧义收敛为单一受治理的答案、让答案易于被发现，以及在两者任一过时的时候发出标记。

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

附录

技能文件骨架

以下是我们主要仓库技能文件的骨架：真实文件的结构，其中内部细节已替换为[方括号占位符]。它并非供你逐字复制，而是用来展示我们认为值得记录下来的那些章节类型。

---
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 …]