很多数据科学和数据工程团队都深有体会：让业务分析走向自助，历来是件苦差事。
为了让技术不那么强的同事更容易上手数据模型，常见做法是建一堆宽表、反范式的表，但随着业务规模变大，这往往导致视图相互重叠、定义彼此不一致（而且对那些根本不想学 SQL 的员工帮助也不大）。另一种做法是给用户建更多围起来的隔离环境，但又常常照顾不到业务问题的长尾，而且随着各团队各自为政，指标和看板会不断膨胀。
LLM 的兴起，为自助式分析提供了一条能绕开这些麻烦的新路。然而，把 Claude 接到数据仓库、让 agent 直接执行，可能会制造一种虚假的精确感。
刚摆脱临时取数请求时的那份解脱与欣喜，会在意识到这套设置把业务方和底层基础设施、文档、专业知识隔开之后，变成一种隐隐的不安——而正是这些底层东西，过去一直在引导他们去用那些精心整理过的数据集。
在 Anthropic，95% 的业务分析查询由 Claude 自动完成，整体准确率约 95%。把这些往往机械、重复的活儿交给 Claude 后，我们的数据科学团队就能腾出手来做更具战略性的工作，比如因果建模、预测和机器学习。
在跟数十位 Anthropic 顶尖的 Claude Code 用户交流、见识过形形色色的分析 agent 设计模式之后，我们为其他与 LLM 打交道的数据团队总结出了一些最佳实践。在这篇文章里，我们会分享这些让 Claude 更好地驱动自助式业务洞察的技巧和思路，包括：
- 为什么分析的准确性是一个 context（上下文）和验证的问题，而不是代码生成的问题；
- 导致大多数错误的三种失败模式；
- 我们为应对这些错误而搭建的 agentic 分析技术栈；
- 我们如何度量有效性；以及
- 我们创建大多数 skill 时所用的一个基础模板（见附录）
数据不是软件
LLM 的生成能力是一把双刃剑：能为复杂问题给出创造性解法的那套机制，同样也会幻觉出错误的输出。要把分析 agent 的挑战彻底搞清楚，拿它和编码 agent 做个对比会很有帮助。
编码是一个开放式的解空间，奖励模型的创造力，同时文档和测试天然地构成了防幻觉的护栏。相比之下，分析类场景往往只有一个正确答案、对应一个正确来源，而且没有确定性的办法去证明这个答案是对的。
对于自助式的 agentic 业务分析，复杂性主要在于数据本身的歧义。核心问题归结为我们 把用户的问题映射到数据模型里具体且最新的实体、并知道该如何正确使用它们的能力。只要能做到这一点，剩下的执行和 SQL 就变得不值一提了。
我们识别出这个问题的三个属性，它们占了不准确回答中的绝大多数：
- 概念<>实体歧义（Concept <> entity ambiguity）：一个数据模型里有数百个可用选项（而潜在字段可能多达数百万），agent 没法选出最能回答用户问题的那些正确字段。举个例子，在统计活跃用户数时：哪些行为才算「活跃」？要不要把欺诈用户算进去？用多长的回溯窗口？
- 数据陈旧（Data staleness）：数据源、业务定义和 schema 一直在变；数据资产和 agent 的知识会过时，开始返回一些微妙的错误答案。
- 检索失败（Retrieval failure）：正确的信息可能确实就在数据模型里、也标注得很到位，但搜索空间实在太大，agent 就是找不到它。
我们的 agentic 分析技术栈
在 Anthropic，我们把这三类错误降到最低的主要手段，就是我们的 agentic 数据栈。每一层的存在，主要是为了攻克其中一个或多个问题：
- 实体歧义：数据底座（data foundations）和真值源（sources of truth）不断收缩可能实体的空间，直到只剩下一个受治理的答案。
- 陈旧：维护和验证流程让一切不会随着业务变化而烂掉。
- 检索失败：skill 确保 agent 能稳定地找到、并正确使用那个答案。
在这一节里，我们会讲讲每一层是怎么搭起来的。
数据底座（Data foundations）
确保分析 agent 准确性最重要的一点，是靠扎实的数据底座，这包括数据仓库里的数据模型、transform、测试和表，以及描述它们的元数据。标准的数据工程和数据质量实践——比如 维度建模、左移测试（shift-left testing）、对关键 pipeline 做新鲜度和完整性检查——全都依然适用（这些我们就不再重复论证了）。
像维度建模这样的标准数据工程实践，跟以往一样重要。
变的是：你数据模型的终端用户不再是数据专家（比如数据科学家），而是代表用户行事的 agent——这些用户对数据的熟悉程度、对底层基础设施的理解千差万别。这个转变带来一个挑战：结果不能要求用户去验证底层的正确性，单纯因为终端用户根本不懂。
数据底座这一层主要针对的是歧义：举个例子，如果 revenue（营收） 能解析到唯一一个受治理的数据集、而不是四十个看似都行的候选项，那么在 agent 还没开始搜索之前，问题就基本消失了。它也是第一道防陈旧的防线所在，因为定义规范模型（canonical model）的那个仓库，天然就是强制让它们保持最新的地方。
我们发现有几种做法效果特别好：
- 创建规范数据集（canonical datasets）：到目前为止最常见的失败，是 agent 没法把一个概念（「产品 X 的 revenue」）映射到唯一正确的表、列和指标定义上，通常是因为存在多个看似都行、但实现上有微妙差异的候选项。解法是更少、治理更严的逻辑模型：精选出一小批规范的、单一真值源的数据集，让它们归属清晰、可直接消费、易于发现，然后大刀阔斧地废弃掉那些近似重复的。物理 rollup 和缓存对成本和性能仍然重要，但它们应该从规范模型机械地派生出来，而不是作为替代品跟规范模型并列摆放。目标是：当 agent 搜索一个概念时，它找到的是唯一一个受治理的答案。
- 强制执行你的标准：我们发现，只有当规范模型和指标定义被 工具 强制执行（agent 在结构上被优先路由到它们，下面会细说）、被 CI 强制执行（绕过它们的改动通不过 review）、被 强制规定 强制执行（下游团队要么在受治理的层上构建，要么解释为什么不这么做），这套底座才立得住。否则，没有强制执行的治理很快就会退化回「多候选项」的问题。
- 把工件放在一起（colocate）：我们对抗数据模型和业务逻辑不断变化的主要防线，就是放在一起（colocation）。几乎所有数据代码（即建模、语义层、参考文档、规范看板定义）都住在同一个仓库里，并有 CI 检查来保护跨层的完整性。如果一个建模改动会破坏下游的某个看板、或让某个有文档的指标失效，CI 会标记出来，修复会在同一个 PR 里一起合入。（这套机制我们会在下面的 Skills 一节里再回来讲。）
- 把元数据当成一等公民的产品：编码 agent 表现好，部分原因是代码库是 可读的（legible）：README、类型签名、docstring 等等。你的数据仓库也可以一样可读，但前提是列和表的描述、规范指标定义、粒度（grain）文档、有效值范围、血缘（lineage）、归属、模型分级，都要跟 transform 本身一样严谨地维护。这虽然算不上什么新见解，但好的治理提供了关键的 context，帮 agent 选对数据集。
真值源（Sources of truth）
如果说数据底座是数据仓库本身，那么真值源就是 agent 用来在仓库里导航时所查阅的参考面。这一层降低概念<>实体歧义，把业务方问题里的「周活跃用户」变成你数据模型里一个具体的、受治理的实体。大致按可信度从高到低排列：
- 语义层（Semantic layer）： 编译好的指标和维度定义。如果一个问题能干净地映射到某个已定义的指标，agent 就调一个函数、得到一个数字——这个数字和公司里其他每个面给出的数字都一样。我们的 agent 在结构上被 强制要求（通过 skill 指令）优先使用语义层（见附录）。有一个我们试过但 没成功 的想法：通过让 LLM 从原始表和查询日志里自动生成指标定义，来给语义层做冷启动。它生成的定义看着像模像样，却把我们正想消除的那些歧义给编码了进去，而且在我们的 eval 上相比一个更小、人工精选的层是净负面。所以我们的建议是：用 Claude 来生成 文档，但让人来掌管 定义。
- 血缘与 transform 图（Lineage and the transformation graph）： 当语义层覆盖不到某个问题时，血缘和表排序（基于引用次数）让 agent 能推理出哪些上游模型供给某个概念、哪些已被废弃、哪些共享同一粒度。这把「我不知道这个指标」变成了「我知道该从哪个受治理的模型去聚合」。它也是我们在下面 在线验证 中所呈现的新鲜度和溯源信号的骨干。
- 查询语料（Query corpus）： 来自看板、notebook 和过往分析的历史 SQL。直觉上，这东西应该很有价值：它记录了每一个已经被正确回答过的问题。但实践中，我们发现给 agent 原始检索权限去访问数千条过往查询，对准确率的提升还不到一个百分点（我们会在后面某一节里走一遍那个消融实验）。非结构化检索没法把一个新问题映射到正确的先例上。真正有效的，是把那个语料蒸馏成结构化的、按领域划分的参考文档，以及在 skill 中描述的可复用分析模式。把查询历史当成供人精选的原材料，而不是 agent 直接去读的真值源。
- 业务 context（Business context）： 这是大多数团队会跳过的一层，也是我们低估得最久的一层。一个不理解你业务的 agent，会回答用户问出口的问题，但答不上他们真正想问的。它不会知道「Q2 那次发布」指的是某个特定产品、不会知道两个团队对同一个术语有不同定义、也不会知道某个问题被问出来是因为周四要开董事会。我们灌入一个公司知识图谱，由建好索引的文档、路线图、决策日志和我们的组织架构构成，好让 agent 能解析那些隐含的指代、并问出更好的澄清问题。
这四者共通的失败模式，跟数据底座那一层是同一个：文档差或文档过时。Claude 在弥合这个缺口上极其有用（起草列描述、从查询模式里提出指标文档、在 CI 里标记没文档的模型），但精选和归属是由人来管的。
在接下来的两节里，我们会讨论如何把这份归属的成本降到足够低，低到它真的会发生。
Skills
如果说真值源是 agent 的 陈述性（declarative） 知识（即一个指标意味着什么），那么 skill 就是它的 程序性（procedural） 知识：按什么顺序查阅哪些来源、如何在有歧义的数据里导航、以及一份完成的分析长什么样。
在 Claude Code 里，一个 skill 就是一个由 markdown 组成、agent 按需读取的文件夹。在 Anthropic，我们开发的 skill 带来了巨大的增值。没有 skill 时，Claude 准确回答分析问题的能力在我们的 eval 上不超过 21%。加上 skill 后，这些数字整体稳定在 95% 以上，在某些领域常常在 99% 左右。我们创建大多数 skill 所用的一个骨架，见附录。
一些最佳实践：
成对地创建 skill： 一个 knowledge skill 充当一个轻量的顶层路由器，让额外的领域细节能按需加载。它说的是「先试语义层，但如果没覆盖到，这里有这个领域约 30 个参考文件，描述了相关的表、列、join 和坑（gotcha）」。这个路由器实际上就是我们对检索失败的答案：与其让 agent 去搜一个百万字段的仓库，不如在还没写出任何一条查询之前，就把空间收窄到几十个精选文件。而 unbook skill 编码了一位资深分析师会遵循的流程：澄清问题、找来源（通过 knowledge skill）、跑查询，然后把结果送进对抗性审查子 agent 里循环过一遍。它还捆绑了十几个可复用的分析模式（留存曲线、比率分解、漏斗分析），这样常见请求就不用每次都重新发明一遍。
创建合格的参考文档：为 LLM 检索而写。我们的参考文档描述表（粒度、范围和排除项）、坑的机制（比如「排除已知的免费邮箱域名，但保留像 anthropic.com 这样的自定义域名」），以及明确的路由触发条件（比如「IF 问题是关于实验 lift……DO NOT 用于原始事件计数」），同时避免那些会过时的规定式套路。下面是我们创建参考文档所用的一个骨架。
# [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]
把 skill 维护当成一等公民：skill 文档描述的是一个每天都在变的数据模型，所以没有持续维护的话，它们几周内就会过时出错。我们眼看着自己的离线准确率从上线时的约 95% 在一个月里漂移到约 65%，之后才把这当成一个工程问题来对待。这意味着要把 skill 的 markdown 文件和我们的 transform 模型放在同一个仓库里，这样改动某个模型的那个 PR，就是更新描述它的那份文档的同一个 PR。一个 code-review hook 会标记任何没有动到 skill 文件的报表模型改动。如今我们大约 90% 的数据模型 PR，都会在同一个 diff 里包含一处 skill 改动。随着模型变强、过去的失败模式不再适用，我们也会定期修剪 skill 的脚手架。
在所有面上创建一致、无缝的体验：同一个 skill 必须 对 Slack 里、IDE 里、看板工具里、独立 agent 会话里的问题给出同一个答案。我们的做法是确保有唯一一个规范来源（数据仓库），并让 skill 的改动自动同步。合入时，skill 会同步到一个插件 marketplace（给 IDE 用户）、到云存储 blob（给那些只读单个文件的托管应用），并直接作为资源通过 MCP 提供。我们一开始就为可移植性做了设计，避免硬编码仓库路径和特定于某个面的命名空间。
验证（Validation）
最后，验证是你查清这三种失败模式中还有哪个在漏过去的方式。
离线评测（Offline evaluations）
我们看到一个常见的模式：数据团队会搭起一套精巧的分析环境，却没有任何流程来了解他们分析 agent 的准确率。
弥补这个缺口的一个办法是离线 eval，也就是简单的问题/答案对。你可以把离线 eval 想成对一个 ML 模型做离线测试：它们不会告诉你在线 agent 的表现，但确实能让你大致判断出自己有没有什么关键缺口。
我们在 Anthropic 部署了两种离线 eval。基于看板的 eval 由 Claude 自动生成（再经人工校验），覆盖最常见的业务方问题。长尾 eval 则是我们给 Claude 喂业务 context（路线图、表文档），让它在该领域的其余部分生成一些合理的问题。我们还会持续收割：每当业务方在某个 thread 里纠正 agent，那条纠正就是一个候选 eval。
其他最佳实践包括：
- 锚定 ground truth，让它没法漂移：一个针对实时数据写的 eval，在底层数字一动的那一刻就过时了。把每个 eval 钉到一个快照日期上、针对一张稳定的事实表来写、或者让打分器去评判 agent 的 查询 而不是它的数字。把整个套件接进 CI，这样一个动到某个依赖的 PR 就会重跑受影响的 eval。
- 像存遥测数据那样存结果，而不是像存测试日志： 每一次运行都落进一张仓库表，带上 skill 版本、git SHA、模型 ID、每条断言的通过/失败、token 数和墙钟时间。「那个改动有没有帮助？」就变成了一条查询，而且你拿到了时间序列，能抓到单次 CI 运行抓不到的缓慢回退。
- 按领域设launch门禁：一个领域的负责人，在他那部分 eval 集清过某个阈值之前（我们最初用约 90%），不能向他的业务方宣布这个 agent。这逼着大家在用户看到失败 之前 就先修好参考文档。
- 创建数量合适的 eval：你应该有多少个 eval，取决于业务领域的复杂度和底层数据模型的复杂度。校准方式是追踪离线准确率对在线准确率的预测有多准：我们发现每个主题（比如「增长」）超过几十个之后就是边际递减，而且这个上限会随着每一代新模型而下降。
- 离线 eval 准确率应该约为 100%；每个正确答案也都应该命中你的语义层（如果你有的话）。再说一遍，这种水平的准确率并不能告诉你系统不会产生错误答案，只能说明——在你有合适 eval 覆盖的前提下——没有明显的缺口。
消融技术（Ablation techniques）
关于 skill 的每一个结构性决策（比如暴露哪些来源、某个子 agent 值不值它带来的延迟、要不要把两个 skill 并成一个），都是在保持我们的离线 eval 集固定不变的前提下做出的。
我们恰好只改一个组件，然后对比通过率。每次运行只花一小时，却能省掉一大堆争论。方法论比任何单个结果都重要：
- 为零结果而设计。 我们最有用的一次消融，是一个否定性的结果。我们给了 agent 直接 grep 我们整个看板、transform 和分析师 notebook SQL（数千个文件）的权限。然后我们在 transcript 里核实它确实在每次回答前都读了它们。准确率两个方向上的变动都不到一个百分点。接着我们检查了那些显而易见的混淆因素：对它答错的那些问题，答案是不是真的在语料里？大约 80% 的情况下，是的。「答案在场」能不能预测「现在答对了」？不能，翻转率是平的。信息就在那儿，agent 也看到了，可它依然没用上。这一个实验就告诉我们：我们的瓶颈不是对过往工作的 访问，而是 结构（即把一个问题映射到正确的实体上）。这个洞察重新指引了好几个月的路线图。
- 以 PR 的粒度做消融。 每一处有意义的 skill 编辑，都在相关的 eval 切片上跑一次 before/after，并把差值写进 PR 描述里。这让「我把文档改好了」这话保持诚实，也能抓到那种出人意料地常见的情况：一处出于好意的添加反而让事情变糟了。
- 维护一份简短的「什么没用」清单。 我们的两个：在某个点之后继续叠加几轮文档打磨（我们连续撞上三次净负面的迭代：文档是变长了，而不是变好了），以及为了砍延迟把对抗性审查者换成一个更便宜的模型（它把大部分准确率收益都丢了，却没换来真正的提速）。否定性结果记录起来很便宜，而且能让下一个人不用重跑同一个实验。
在线验证（Online validation）
最后一步，是确保实际的在线系统表现尽可能准确。我们采取的一些步骤包括：
- 对抗性审查（Adversarial review）：我们发现，启用一个 Claude skill 去对一个潜在的最终答案激进地挑战其所有底层假设，能在我们的 eval 集内把准确率提升 6%，但代价是多花 32% 的 token 和高出 72% 的延迟。
- 溯源页脚（Provenance footer）： 每个回答都带一个页脚，里面包含它来自哪个来源层级（语义层 › 精选参考 › 原始表）、底层数据有多新、以及谁是这个模型的归属方。它不会让答案更正确，但确实能帮使用者判断自己能在多大程度上信任这个回答。一个「原始表，新鲜度未知」的页脚，就是一个在往上转发前先核实的信号，而这也是我们针对静默失败为数不多的缓解手段之一。
- 数据质量检查（Data quality checks）：有可能你的 agent 用对了字段、用法也恰当，但数据本身是错的。加上一些基础的数据质量检查，确保被引用的字段是最新的、完整的、没有异常，一般来说是良好的卫生习惯。
- 被动监控（Passive monitoring）： 我们持续追踪两个生产信号：通过语义层解析的 agent 查询占比，以及使用了纠正性措辞（「那是错的表」「你漏了欺诈过滤器」）的回答占比。两者都汇入一个每周连同离线通过率一起 review 的看板。
- 主动收割纠正（Active correction harvesting）：这是闭环的那一环。一个定时 agent 每隔几小时扫一遍业务方的频道，找类似的纠正性措辞，给相关参考文档起草一行修复，并开一个标记给领域负责人的 PR。这条修复路径被刻意设计得很无聊——编辑一个 markdown 文件、合入、到处自动同步——这样领域负责人就不用在这事上花太多时间。这些同样的纠正会反哺回离线 eval 集。
这一切都没法完全抓住的那种失败模式，是 静默的 那一种。答案是错的，但看着合理，被人毫无异议地用了。我们的缓解手段是溯源页脚、对任何要呈给领导层的东西做明确的人工签字确认，以及为每个领域的头部 KPI 设一个常驻 eval，每天拿它跟那个权威看板做一次合理性核对——尽管我们还没有一个稳健的解法。
上手起步
如果你从零开始，几个规范数据集、几十个离线 eval、再加一个轻量的 knowledge skill，就能拿下大部分收益；这篇文章里其余的一切，都是我们在那些建好之后才加上去的。
我们也分享了很多最佳实践，但并非每一条都适合每个数据团队。通过问自己下面这些问题，跟你的组织在几条会影响你做法的原则上对齐：
- 今天答案正确有多重要，相比未来？AI 模型正以飞快的速度进步。我们常看到一些公司构建大量基础设施来弥补当前模型的不足，可一旦那些模型变强，这些基础设施就成了多余。知道模型在哪些地方还差口气、然后等模型变强来填上这个缺口，开销要小得多，但可能不符合你公司的风险承受度。
- 你预期自己业务的复杂度会随时间如何变化？我们讨论的有些流程可能是杀鸡用牛刀，比如说，如果你产生的数据不多、输出的消费者只有寥寥几个、或者你的数据模型大概率会一直保持简单。
- 输出的目标受众技术水平如何？换个说法，如果你是为那些能认出答案错误的数据科学家构建这套分析系统，那相比受众对底层数据模型毫不熟悉的情形，你可能对错误的容忍度更高。
- 为了提升准确率你愿意花多少钱？我们发现像对抗性验证这样的某些流程能显著提升准确率，但往往伴随着更高的成本和延迟。
- 你对访问控制和内部数据隐私的接受程度如何？agent 拿到的 context 越多，往往表现越好；然而，宽泛的数据访问权限跟大多数公司的治理姿态是相悖的。这决定了你是在构建一个 agent，还是多个范围受限的 agent。
无论你走哪条路，我们最大的收益都来自对这三种失败模式逐一下手：把歧义坍缩成唯一一个受治理的答案、让那个答案易于发现、并在其中任何一个已经过时的时候发出标记。
本文由 Chen Chang、Clement Peng、Justin Leder、Johanne Jiao 和 Josh Cherry 撰写，他们是数据科学与数据工程团队的成员。作者们要感谢 Michael Segner 的贡献。
附录
Skill 文件骨架
下面是我们主仓库 skill 的骨架：真实文件的结构，内部的具体细节用 [方括号占位符] 替换掉了。它不是用来逐字照抄的；它是用来展示我们发现值得写下来的那些章节类型。
---
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 …]