- 类别企业 AI
- 产品Claude Code
- 日期2026 年 6 月 3 日
- 阅读时间5分钟
- https://claude.com/blog/how-anthropic-enables-self-service-data-analytics-with-claude
正如许多数据科学和数据工程团队所证实的那样，实现自助式业务分析历来是一项艰巨的任务。
通过宽表和反范式化表，让数据模型对技术能力较弱的同事更易用，往往会导致随着业务扩展而出现定义不一致的重叠视图（并且对于那些不太想学习 SQL 的员工来说，几乎无法弥合差距）。另一种选择是，为用户创建更多封闭的环境，但这往往会遗漏大量长尾业务问题，并导致指标和仪表盘臃肿，因为各个团队各自为政。
大语言模型的兴起为自助式分析提供了一条避免这些挑战的新路径。然而，直接将 Claude 指向数据仓库并让智能体执行操作，可能会产生一种虚假的精确感。
最初从临时请求中解放出来的喜悦，会随着意识到这种设置将利益相关者与底层基础设施、文档以及以往引导他们使用精心策划数据集的专业知识隔离开来，而转变为恐惧。
在 Anthropic，95% 的业务分析查询通过 Claude 实现自动化，整体准确率约为 95%。通过将这些通常单调重复的工作交给 Claude，我们的数据科学团队可以专注于更具战略性的工作，如因果建模、预测和机器学习。
在与数十位 Anthropic 顶尖的 Claude Code 用户会面，并观察了无数种分析智能体的设计模式后，我们为其他使用大语言模型的数据团队总结出了一些最佳实践。在这篇文章中，我们将分享这些技巧和方法，以最大化 Claude 驱动自助式业务洞察的能力，包括：
- 为什么分析准确性是一个上下文和验证问题，而不是代码生成问题；
- 导致大多数错误的三种失败模式；
- 我们为解决这些错误而构建的智能体分析技术栈；
- 我们如何衡量有效性；以及
- 我们创建大部分技能的基本模板（参见附录）
数据不是软件
大语言模型的生成能力是一把双刃剑：那些能够为复杂问题提供创造性解决方案的机制，也可能产生错误的模型幻觉输出。要全面理解分析型智能体面临的挑战，将其与编码型智能体进行对比会很有帮助。
编码是一个开放式的解决方案空间，它奖励模型的创造力，而文档和测试则提供了防止模型幻觉的自然护栏。相比之下，在分析用例中，通常只有一个使用单一正确来源的正确答案，而且没有确定性的方法来证明其正确性。
对于自助式的智能体业务分析而言，复杂性主要在于数据的模糊性。核心问题归结为我们能否将用户的问题映射到数据模型中具体且最新的实体上，并知道处理它们的正确方法。如果我们能做到这一点，那么后续的执行和 SQL 生成就变得微不足道了。
我们已识别出该问题的三个属性，它们导致了绝大多数的不准确回答：
- 概念与实体模糊性：在数据模型中存在数百个可行选项（而潜在字段可能有数百万个）的情况下，智能体无法选择最能回答用户问题的正确字段。例如，在衡量活跃用户数量时：哪些行为构成“活跃”？是否包含欺诈用户？使用多长的回溯窗口？
- 数据过时：数据源、业务定义和模式不断变化；资产和智能体的知识会变得陈旧，并开始返回细微的错误答案。
- 检索失败：正确的信息可能确实存在于数据模型中并已得到恰当标注，但由于搜索空间过于庞大，智能体就是找不到它。
我们的智能体分析技术栈
在 Anthropic，我们最小化这三类错误的主要方式是通过我们的智能体数据技术栈。每一层主要都是为了解决其中一个或多个问题而存在：
- 实体模糊性：数据基础层和事实来源层会缩小可能实体的范围，直到只剩下一个受管控的正确答案。
- 过时问题：维护和验证流程可以防止所有内容随着业务变化而腐化。
- 检索失败：技能确保智能体能够可靠地找到并正确使用该答案。
在本节中，我们将讨论如何构建每一层。
数据基础
确保分析型智能体准确性的最重要方面在于强大的数据基础，这包括数据仓库中的数据模型、转换、测试和表，以及描述它们的元数据。标准的数据工程和数据质量实践，例如维度建模、左移测试、关键管道的时效性和完整性检查，仍然适用（我们不会在此重新讨论这些）。
真正改变的是，你数据模型的最终用户不再是数据专家（例如数据科学家），而是代表用户行动的智能体，这些用户的数据专业知识或对底层基础设施的理解程度各不相同。这种转变带来了一个挑战：结果不能要求用户去验证底层的正确性，仅仅因为最终用户并不了解。
数据基础层主要针对模糊性问题：例如，如果“收入”最终指向一个受治理的数据集，而不是四十个可能的候选，那么问题在智能体需要搜索之前就基本消失了。这也是第一道防过时防线所在，因为定义规范模型的同一个仓库，正是强制它们保持更新的天然场所。
我们看到一些实践效果尤其出色：
- 创建规范数据集：目前最常见的失败原因是智能体无法将一个概念（例如“产品 X 的收入”）映射到唯一正确的表、列和指标定义，这通常是因为存在多个实现方式略有差异的候选方案。解决方法是减少逻辑模型数量，并加强治理：精心维护一小套规范的、单一事实来源的数据集，这些数据集应权责明确、可供直接消费且易于发现，然后积极淘汰那些近似的重复数据集。物理汇总和缓存对于成本和性能仍然重要，但它们应从规范模型机械派生而来，而不是作为替代方案与之并存。目标是当智能体搜索某个概念时，能找到唯一一个经过治理的答案。
- 执行你的标准：我们发现，只有当规范模型和指标定义通过工具（智能体在结构上被优先引导至这些模型，下文会详述）、CI（绕过它们的变更无法通过审查）和指令（下游团队必须在治理层之上构建，否则需说明原因）来强制执行时，基础才能稳固。否则，缺乏执行的治理很快就会退化回多个候选方案的问题。
- 整合工件：我们应对不断变化的数据模型和业务逻辑的主要策略是整合。几乎所有数据代码（即建模、语义层、参考文档、规范仪表盘定义）都存放在单一仓库中，并配有保护跨层完整性的 CI 检查。如果建模变更会破坏下游仪表盘或使已记录的指标失效，CI 会标记出来，修复方案会在同一个 PR 中提交。（我们将在下文“技能”部分再次讨论这一机制。）
- 将元数据视为一等产品：编码智能体表现良好，部分原因在于代码库具有可读性——README 文件、类型签名、文档字符串等。你的数据仓库同样可以做到可读，但前提是列与表的描述、规范化的指标定义、粒度文档、有效取值范围、血缘关系、所有权归属以及模型分层，都必须以与数据转换本身同样严格的标准来维护。这并非新见解，但良好的治理能为智能体提供关键上下文，帮助它选择正确的数据集。
事实来源
如果说数据基础是数据仓库本身，那么事实来源就是智能体在导航数据仓库时所参考的基准面。这一层减少了概念与实体之间的歧义，并将利益相关者问题中的“周活跃用户”转化为数据模型中一个具体的、受治理的实体。大致按可信度降序排列如下：
- 语义层：已编译的指标与维度定义。如果一个问题能清晰地映射到某个已定义的指标，智能体就会调用一个函数，得到一个数字——这个数字与公司内其他任何界面产生的数字完全一致。我们的智能体在结构上（通过技能指令）被要求优先利用语义层（参见附录）。我们尝试过但未奏效的一个想法是：通过让大语言模型根据原始表和查询日志自动生成指标定义来引导语义层。它产生了看似合理的定义，却编码了我们试图消除的那些歧义，并且与一个较小的人工策划层相比，对我们的评估产生了净负面影响。因此，我们建议用 Claude 生成文档，但由人工负责定义。
- 血缘关系与转换图谱：当语义层无法覆盖某个问题时，血缘关系与表排名（基于引用次数）能让智能体推理出哪些上游模型为某个概念提供数据、哪些已被弃用、哪些共享粒度。这便将“我不知道这个指标”转化为“我知道该从哪个受治理的模型进行聚合”。它也是我们下文在线验证中提供的时效性与来源信号的基础。
- 查询语料库：来自仪表盘、笔记本和过往分析的历史 SQL。直观上看，这应该是高价值数据：它记录了每一个已被正确回答过的问题。但在实践中，我们发现让智能体直接原始检索数千条过往查询，对准确率的提升不到一个百分点（我们将在下文的相关消融实验中详细说明）。非结构化检索无法将新问题映射到正确的先例上。真正有效的方法，是将该语料库提炼为结构化的领域参考文档，以及以技能形式描述的可复用分析模式。应将查询历史视为用于整理的原始素材，而非智能体直接读取的事实依据。
- 业务上下文：这是大多数团队会跳过的一层，也是我们长期低估的一层。一个不了解你业务的智能体，能回答用户提出的问题，却无法理解用户的真实意图。它不会知道“Q2 发布”指的是某个具体产品，不会知道两个团队对同一术语的定义不同，也不会知道某个问题之所以被提出是因为周四有董事会会议。我们接入了一个公司知识图谱，包含索引文档、路线图、决策日志和组织架构，以便智能体能够解析隐含的上下文引用，并提出更精准的澄清性问题。
这四个层面的常见失败模式，与数据基础层的问题如出一辙：文档质量差或文档过时。Claude 在弥补这一差距方面极为有用（例如草拟列描述、根据查询模式提出指标文档建议、在 CI 中标记未记录的模型），但整理和所有权归属仍需由人类来管理。
在接下来的两个部分中，我们将讨论如何让这种所有权归属的成本足够低，从而使其真正得以落实。
技能
如果说事实来源是智能体的陈述性知识（即某个指标的含义），那么技能就是它的程序性知识：按何种顺序查阅哪些来源、如何在模糊数据中导航、以及一份完整的分析报告应该是什么样子。
在 Claude Code 中，技能（skill）就是一个文件夹，里面存放着智能体按需读取的 Markdown 文档。在 Anthropic，我们开发的这些技能价值巨大。没有技能时，Claude 在我们的评估中准确回答分析类问题的能力不超过 21%。加入技能后，这一数字在整体上稳定超过 95%，并且在某些特定领域经常能达到 99% 左右。附录中提供了我们用于创建大部分技能的一个框架模板。
一些最佳实践：
创建成对技能：一个知识技能充当轻量级的顶层路由器，允许按需加载额外的领域细节。它会说“先尝试语义层，但如果覆盖不到，这里有该领域约 30 个参考文件，描述了相关的表、列、连接方式和注意事项。”这个路由器实际上是我们应对检索失败的方法：它不会让智能体去搜索一个拥有百万字段的数据仓库，而是在任何查询被写出之前，将搜索空间缩小到几十个精心整理的文件。另一个技能（unbook skill）则编码了资深分析师会遵循的流程：澄清问题、通过知识技能查找数据源、运行查询，然后将结果送入对抗性审查子智能体进行循环验证。它还打包了十几种可复用的分析模式（留存曲线、比率分解、漏斗分析），这样常见的请求就不必每次都从头开始。
创建合适的参考文档：这些文档是为大语言模型检索而编写的。我们的参考文档描述了表（粒度、范围和排除项）、注意事项的具体机制（例如，“排除已知的免费邮箱域名，但保留像 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 现在都在同一个差异中包含技能变更。随着模型改进且之前的失败模式不再适用，我们还会定期修剪技能脚手架。
在所有界面创建一致且无缝的体验：同一个技能必须在 Slack、IDE、仪表盘工具以及独立智能体会话中为问题提供相同的答案。我们通过确保一个权威来源（数据仓库）并自动同步技能变更来实现这一点。合并后，技能会同步到插件市场（供 IDE 用户使用）、云存储 Blob（供读取单个文件的托管应用使用），并直接通过 MCP 作为资源提供。我们还从一开始就通过避免硬编码仓库路径和特定于界面的命名空间来设计可移植性。
验证
最后，验证是用来找出三种失败模式中哪一种仍在渗透的方法。
离线评估
我们常见的一个模式是，数据团队会建立复杂的分析环境，却没有相应的流程来了解其分析智能体的准确性。
解决这一差距的一种方法是通过离线评估，即简单的问答对。你可以将离线评估类比为机器学习模型的离线测试，它们不会告诉你在线智能体的性能，但能让你很好地了解是否存在任何关键缺口。
我们在 Anthropic 部署了两种离线评估。基于仪表盘的评估由 Claude 自动生成（随后由人工验证），覆盖最常见的利益相关方问题。长尾评估则是我们向 Claude 提供业务背景信息（路线图、表格文档），让其生成覆盖领域其余部分的合理问题。我们还会持续收集利益相关方在线程中纠正智能体的每一次情况，因为那次纠正就是一个候选评估用例。
其他最佳实践包括：
- 锚定真实数据基准以防偏移：针对实时数据编写的评估，一旦底层数字发生变化就会失效。将每个评估固定到某个快照日期，基于稳定的事实表编写，或者让评分者评判智能体的查询而非其数字。将评估套件接入 CI 流水线，这样当 PR 修改了某个依赖项时，受影响的评估会自动重新运行。
- 像存储遥测数据一样存储结果，而非测试日志：每次运行都会存入数据仓库表，包含技能版本、Git SHA、模型 ID、每条断言的通过/失败状态、token 计数和实际耗时。"那个改动有帮助吗？"变成了一次查询，你还能获得时间序列数据，以捕捉单次 CI 运行无法发现的缓慢性能退化。
- 按领域设置发布门禁：领域负责人必须等到其负责的评估集切片达到某个阈值（我们最初设为约 90%）后，才能向利益相关方宣布智能体上线。这迫使参考文档在用户看到失败之前就得到修复。
- 创建适当数量的评估：评估数量应取决于业务领域的复杂度和底层数据模型的复杂度。通过追踪离线准确率对在线准确率的预测效果来进行校准：我们发现，每个主题（例如"增长"）的评估用例超过几十个后，收益会递减，而且这个上限会随着每一代新模型的推出而降低。
- 离线评估准确率应接近 100%；每个正确答案还应命中你的语义层（如果有的话）。再次强调，这种准确率水平并不能说明你的系统不会产生错误答案，只是表明在评估覆盖得当的前提下，不存在明显的漏洞。
消融技术
关于技能的所有结构性决策（例如，暴露哪些数据源、子智能体是否值得其带来的延迟、是否将两个技能合并为一个），都是通过固定我们的离线评估集来做出的。
我们每次只改变一个组件，并比较通过率。每次运行仅需一小时，却省去了大量争论。方法论本身比任何单一结果都更重要：
- 为无效结果而设计。我们最有用的消融实验是一个阴性结果。我们让智能体直接通过 grep 访问我们整个仪表盘、转换和分析师笔记本的 SQL（数千个文件）。然后我们在转录记录中验证，它是否在每次回答前确实阅读了这些文件。准确率在正负方向上的变化都不到一个百分点。接着我们检查了明显的混淆因素：对于它答错的问题，答案是否真的存在于语料库中？大约 80% 的情况下，答案是肯定的。“答案存在”是否能预测“现在就能答对”？不能，正确率的变化是平的。信息就在那里，智能体也看到了，但它仍然没有使用。这一个实验告诉我们，我们的瓶颈不在于获取先前的工作成果，而在于结构（即，将问题映射到正确的实体）。这一洞察改变了我们未来数月的路线图。
- 在 PR 粒度上进行消融。每一次有意义的技能编辑，都会在相关的评估切片上运行一次修改前/修改后的对比，并将差异写在 PR 描述中。这能确保“我改进了文档”的说法是诚实的，并能捕捉到那种出奇常见的情况：一个善意的添加反而让事情变得更糟。
- 保留一份“无效尝试”的简短清单。我们的两个例子：在文档优化上叠加额外的轮次超过某个点（我们连续遇到了三次净负向迭代：文档变得更长，而非更好）；以及将对抗性审查模型换成更便宜的模型以降低延迟（结果损失了大部分准确率提升，且几乎没有获得真正的速度提升）。记录阴性结果的成本很低，并且能防止下一个人重复运行相同的实验。
在线验证
最后一步是确保实际在线系统的性能尽可能准确。我们采取的一些措施包括：
- 对抗性审查：我们发现，使用 Claude 技能对潜在最终答案的所有基本假设进行激进挑战，在我们的评估集内将准确率提升了 6%，但代价是增加了 32% 的 token 消耗和 72% 的更高延迟。
- 溯源页脚：每个响应都带有一个页脚，其中包含该响应来自哪个源层级（语义层 › 精选参考 › 原始数据表）、底层数据的新鲜程度以及模型的所有者。它不会让答案更正确，但确实有助于使用者判断他们能在多大程度上信任该响应。一个“原始数据表，新鲜度未知”的页脚是一个信号，提示在向上游转发前需进行验证，这也是我们针对静默失败为数不多的缓解措施之一。
- 数据质量检查：你的智能体可能以正确的方式使用了正确的字段，但数据本身却是错误的。添加基本的数据质量检查，以确保所引用的字段是最新的、完整的且没有异常，这通常是一种良好的实践。
- 被动监控：我们持续跟踪的两个生产信号是：通过语义层解决的智能体查询占比，以及使用纠正性语言（“那是错误的表格”，“你漏掉了欺诈过滤器”）的响应占比。这两个信号都会输入到一个仪表盘中，该仪表盘与离线通过率一起每周进行审查。
- 主动纠正收集：这是形成闭环的部分。一个定时任务智能体会每隔几小时扫描利益相关者频道，寻找类似的纠正性语言，起草对相关参考文档的一行修复，并打开一个标记给领域负责人的 PR。修复路径被刻意设计得简单——编辑一个 markdown 文件、合并、自动同步到各处——这样领域负责人就不会在这项任务上花费太多时间。同样的纠正内容也会反馈到离线评估集中。
所有这些方法都无法完全捕获的失败模式是静默失败。答案错误，但看起来合理且被无异议地使用。我们的缓解措施包括溯源页脚、任何提交给领导层的内容需经人工明确批准，以及针对每个领域关键 KPI 的常设评估，该评估每天对照官方仪表盘进行合理性检查，不过我们目前还没有一个稳健的解决方案。
入门指南
如果你从零开始，一小批经典数据集、几十个离线评测，再加上一个轻量的知识技能，就能覆盖大部分收益；本文中其余内容都是我们在搭建好这些基础之后才添加的。
我们还分享了许多最佳实践，但并非所有实践都适合每个数据团队。请与你的组织就几个会影响你方法的原则达成一致，可以问以下问题：
- 当前答案的正确性与未来的正确性，哪个更重要？AI 模型正以极快的速度进步。我们经常看到，企业为了应对当前模型的不足而搭建大量基础设施，但这些不足一旦模型改进就变得无关紧要。了解模型的短板，并等待模型改进来填补缺口，开销要小得多，但这可能不符合你公司的风险承受能力。
- 你预计你的业务复杂性会随时间如何变化？例如，如果你产生的数据不多、输出结果的使用者很少，或者你的数据模型很可能保持简单，那么我们讨论的某些流程可能就过于繁琐了。
- 输出结果的目标受众技术能力如何？换句话说，如果你是为能够识别答案是否正确数据科学家构建这个分析系统，那么与受众对底层数据模型完全不熟悉的情况相比，你对错误的容忍度可能会更高。
- 你愿意为提高准确率投入多少成本？我们发现，某些流程（如对抗性验证）可以显著提高准确率，但通常成本更高、延迟也更大。
- 你对访问控制和内部数据隐私的接受程度如何？智能体拥有的上下文越多，其性能通常越强；然而，广泛的数据访问权限与大多数公司的治理策略相悖。这决定了你是构建一个智能体，还是构建多个有明确范围限制的智能体。
无论你选择哪条路，我们最大的收获来自于解决三种失败模式：将模糊性收敛为单一受管答案、让答案易于被发现，以及在答案或数据过时的时候发出标记。
本文由数据科学与数据工程团队的陈畅、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## DescriptionThe 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 queriesPriority:
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 workflow1.**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 Workflow1.**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 Guide1. 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 …]
借助 Claude 改变您组织的运作方式
- Category
- ProductClaude Code
- DateJune 3, 2026
- Reading time5min
- https://claude.com/blog/how-anthropic-enables-self-service-data-analytics-with-claude
As many data science and data engineering teams can attest, enabling self-service business analytics has traditionally been a slog.
Making the data model more accessible to less technical coworkers via wide and denormalized tables often leads to overlapping views with inconsistent definitions as the business scales (and does little to bridge the gap for employees with little desire to learn SQL). Alternatively, creating more ringfenced environments for users often misses the long tail of business questions and leads to metric and dashboard bloat as teams silo their work.
The rise of LLMs provides an additional path for self-service analytics that avoids those challenges. However, pointing Claude at a warehouse and letting the agents execute can create a false sense of precision.
The initial elation of liberation from ad-hoc requests turns into dread with the realization that this setup separates stakeholders from the underlying infrastructure, documentation, and expertise that previously steered them toward carefully curated datasets.
At Anthropic, 95% of business analytics queries are automated via Claude, with ~95% accuracy in aggregate. By giving this often rote, repetitive work to Claude, our data science team can focus on more strategic work like causal modeling, forecasting, and machine learning.
After meeting with dozens of Anthropic’s top Claude Code users and having seen myriad design patterns for analytics agents, we’ve cultivated some best practices for other data teams working with LLMs. In this post, we’ll share these tips and approaches to maximizing Claude’s ability to drive self-serve business insights, including:
- Why analytics accuracy is a context and verification problem, not a code generation issue;
- The three failure modes that cause most errors;
- The agentic analytics stack we built to address these errors;
- How we measure effectiveness; and
- A basic template for how we create the majority of our skills (see the appendix)
Data is not software
LLMs' generative abilities are a double-edged sword: the mechanisms that enable creative solutions to complex problems can also hallucinate erroneous output. To fully understand the challenges with analytics agents, it’s useful to compare them to coding agents.
Coding is an open-ended solution space that rewards the models' creativity, while documentation and tests provide natural guardrails against hallucination. In contrast, for analytics use cases, there’s often only a single correct answer using a single correct source in which there’s no deterministic way of proving the correctness.
For self-service agentic business analytics, the complexity mainly lies in the ambiguity of the data. The central problem comes down to our ability to map a user’s question to specific and up-to-date entities in our data model and know the correct way of working with them. If we can do that, then the resulting execution and SQL becomes trivial.
We’ve identified three attributes of this problem that account for an overwhelming majority of inaccurate responses:
- Concept <> entity ambiguity: with hundreds of viable options in a data model (out of potentially millions of fields), the agent is unable to choose the correct fields that best answer a user’s question. For example, in measuring the number of active users: what actions constitute being “active”? Do you include fraudulent users? What lookback window do you use?
- Data staleness: data sources, business definitions, and schemas change constantly; assets and agent knowledge go stale and start returning subtly wrong answers.
- Retrieval failure: the right information may actually be in the data model and properly annotated, but given the vastness of the search space, the agent simply doesn’t find it.
Our agentic analytics stack
At Anthropic, the main way we minimize these three errors is via our agentic data stack. Each layer exists primarily to attack one or more of these problems:
- Entity ambiguity: data foundations and sources of truth shrink the space of plausible entities until there's a single governed answer.
- Staleness: maintenance and validation processes keep everything from rotting as the business changes.
- Retrieval failure: skills make sure the agent reliably finds and correctly uses that answer.
In this section, we’ll discuss how we built each layer.
Data foundations
The most important aspect of ensuring analytics agents are accurate is via strong data foundations, which include the data models, transforms, tests, and tables in a data warehouse, along with the metadata describing them. Standard data engineering and data quality practices such as dimensional modeling, shift-left testing, freshness and completeness checks on critical pipelines all still apply (and we won't relitigate these).
What does change is that the end user of your data model is no longer a data expert (e.g. data scientist), but rather agents acting on behalf of users with varying degrees of data expertise or understanding of the underlying infrastructure. This shift presents a challenge in that the results can’t require the user to validate the underlying correctness simply because the end user doesn’t know.
The data foundations layer is aimed primarily at ambiguity: if revenue, for example, resolves to one governed dataset instead of forty plausible candidates, the problem largely disappears before the agent ever has to search. It's also where the first staleness defense lives, since the same repo that defines the canonical models is the natural place to enforce that they stay current.
We’ve seen a few practices work especially well:
- Create canonical datasets: By far the most common failure is that the agent can’t map a concept (“revenue for product X”) to the single correct table, column, and metric definition, usually because there are multiple plausible candidates with subtly different implementations. The fix is fewer, more heavily governed logical models: curate a small set of canonical, single source-of-truth datasets that are clearly owned, consumption-ready, and discoverable, then aggressively deprecate the near-duplicates. Physical rollups and caches still matter for cost and performance, but they should derive mechanically from the canonical models rather than living alongside them as alternatives. The goal is that when an agent searches for a concept, it finds a single governed answer.
- Enforce your standards: We’ve found the foundations only hold if the canonical models and metric definitions are enforced by tooling (the agent is structurally routed to them first; more on that below), by CI (changes that bypass them fail review), and by mandate (downstream teams build on the governed layer or explain why not). Governance without enforcement otherwise quickly decays back to the multiple candidates problem.
- Colocate artifacts: Our main defense against constantly changing data models and business logic is colocation. Nearly all data code (i.e., modeling, semantic layer, reference docs, canonical dashboard definitions) lives in a single repo, with CI checks that protect cross-layer integrity. If a modeling change would break a downstream dashboard or invalidate a documented metric, CI flags it and the fix ships in the same PR. (We’ll come back to the mechanics of this in the Skills sectionbelow.)
- Treat metadata as a first-class product: Coding agents perform well partly because codebases are legible: READMEs, type signatures, docstrings, etc. Your warehouse can be just as legible, but only if column and table descriptions, canonical metric definitions, grain documentation, valid value ranges, lineage, ownership, and model tiering are maintained with the same rigor as the transformations themselves. While not a new insight, good governance provides critical context that helps the agent choose the right dataset.
Sources of truth
If data foundations are the data warehouse itself, sources of truth are the reference surfaces the agent consults to navigate it. This layer reduces concept <> entity ambiguity and turns “weekly active users” in a stakeholder’s question into a specific, governed entity in your data model. Roughly in descending order of trust:
- Semantic layer: the compiled metric and dimension definitions. If a question maps cleanly to a defined metric, the agent calls a function and gets one number, the same number every other surface in the company produces. Our agents are structurally required (by skill instruction) to leverage the semantic layer first (see the appendix). One idea we tried that didn’t work: bootstrapping the semantic layer by having an LLM auto-generate metric definitions from raw tables and query logs. It produced plausible-looking definitions that encoded the very ambiguities we were trying to eliminate, and was net-negative on our evals versus a smaller, human-curated layer. Therefore we recommend generating the documentation with Claude, but having a human own the definition.
- Lineage and the transformation graph: when the semantic layer doesn’t cover a question, lineage and table ranking (based on number of references) let the agent reason about which upstream models feed a concept, which are deprecated, and which share grain. This transforms “I don’t know the metric” into “I know which governed model to aggregate from.” It’s also the backbone of the freshness and provenance signals we surface in online validation below.
- Query corpus: historical SQL from dashboards, notebooks, and prior analyses. Intuitively, this should be high-value: it’s a record of every question already answered correctly. In practice, we found that giving the agent raw retrieval access to thousands of prior queries moved accuracy by less than a point (we walk through that ablation in a later section below). Unstructured retrieval couldn’t map a new question to the right precedent. What does work is distilling that corpus into structured per-domain reference docs and reusable analysis patterns described in skills. Treat the query history as raw material for curation, not as a source of truth the agent reads directly.
- Business context: the layer most teams skip, and the one we underrated the longest. An agent that doesn’t understand your business will answer what the user asked, but not what they meant. It won’t know that “the Q2 launch” refers to a specific product, that two teams define the same term differently, or that a question is being asked because a board meeting is on Thursday. We pipe in a company knowledge graph consisting of indexed docs, roadmaps, decision logs, and our organizational structure so the agent can resolve ambient references and ask better clarifying questions.
The common failure pattern across all four is the same one from the data foundations layer: poor or stale documentation. Claude is exceptionally useful for closing the gap (drafting column descriptions, proposing metric docs from query patterns, flagging undocumented models in CI), but the curation and ownership are managed by humans.
In the next two sections, we discuss how to make that ownership cheap enough that it actually happens.
Skills
If the sources of truth are the agent's declarative knowledge (i.e., what a metric means) then a skill is its procedural knowledge: which sources to consult in what order, how to navigate ambiguous data, and what a finished analysis looks like.
In Claude Code, a skill is a folder of markdown the agent reads on demand. At Anthropic, the skills we developed are hugely value additive. Without skills, Claude’s ability to answer analytics questions accurately didn’t exceed 21% on our evals. Adding skills gets these numbers consistently above 95% in aggregate and regularly around 99% in certain domains. See the appendix for a skeleton we use to create a majority of our skills.
Some best practices:
Create pairwise skills: a knowledge skill acts as a thin top-level router that allows additional domain details to load on demand. It says "try the semantic layer first, but if there’s no coverage, here are ~30 reference files for this domain describing the relevant tables, columns, joins and gotchas.” This router is, in effect, our answer to retrieval failure: rather than letting the agent search a million-field warehouse, it narrows the space to a few dozen curated files before a query is ever written. The unbook skill encodes the process a senior analyst would follow: clarify the question, find sources (via the knowledge skill), run the query, and then loop the result through adversarial review sub-agents. It also bundles a dozen reusable analysis patterns (retention curves, rate decomposition, funnel analysis) so that common requests don't get reinvented each time.
Create proper reference docs: written for retrieval by an LLM. Our reference docs describe tables (grain, scope, and exclusions), the mechanics of gotchas (e.g., “exclude known free-email domains, but keep custom ones like anthropic.com”), and explicit routing triggers (e.g., “IF the question is about experiment lift… DO NOT use for raw event counts”) without prescriptive recipes that go stale. See below for a skeleton we use to create reference docs.
# [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]Treat skill maintenance as a first class citizen: Skill docs describe a data model that changes daily, so without active maintenance they're wrong within weeks. We watched our offline accuracy drift from ~95% at launch to ~65% over a month before we treated this as an engineering problem. That meant colocating skill markdown files in the same repo as our transformation models, so the PR that changes a model is the same PR that updates the doc describing it. A code-review hook flags any reporting-model change that doesn't touch a skill file. Roughly 90% of our data-model PRs now include a skill change in the same diff. We also regularly prune skill scaffolding as models improve and previous failure modes no longer apply.
Create a consistent and seamless experience across all surfaces: the same skill must provide the same answer to questions in Slack, in the IDE, in a dashboard tool, and in standalone agent sessions. We did this by ensuring one canonical source (the data repo) and that skill changes are synced automatically. On merge, the skill syncs to a plugin marketplace (for IDE users), to cloud-storage blobs (for hosted apps that read a single file), and is served directly as resources over MCP. We also designed for portability from the start by avoiding hardcoded repo paths and surface-specific namespaces.
Validation
Finally, validation is how you find out which of the three failure modes is still leaking through.
Offline evaluations
A common pattern we see is that data teams will set up elaborate analytic environments without having any process to understand the accuracy of their analytics agents.
One way of addressing this gap is via offline evals, which are simple question / answer pairs. You can think of offline evals similar to offline testing for an ML model in that they don’t tell you the performance of your online agents, but they do give you a good sense of whether you’ll have any critical gaps.
We deploy two kinds of offline evals at Anthropic. Dashboard-based evals are auto-generated by Claude (then human validated), covering the most common stakeholder questions. Long tail evals are where we feed Claude business context (roadmaps, table docs) and have it generate plausible questions across the rest of the domain. We also continuously harvest every time a stakeholder corrects the agent in a thread as that correction is a candidate eval.
Other best practices, include:
- Anchor ground truth so it can't drift: An eval written against live data goes stale the moment the underlying number moves. Pin every eval to a snapshot date, write it against a stable fact table, or have the grader judge the agent's query rather than its number. Wire the suite into CI so a PR touching a dependency re-runs the affected evals.
- Store results like telemetry, not like test logs: Every run lands in a warehouse table with the skill version, git SHA, model ID, per-assertion pass/fail, token count, and wall-clock. "Did that change help?" becomes a query, and you get the time-series to catch slow regressions that a single CI run won't.
- Gate launches per domain: A domain owner can't announce the agent to their stakeholders until their slice of the eval set clears some threshold (we initially used ~90%). It forces reference-doc fixes before users see the failures.
- Create the appropriate number of evals: The number of evals you should have depends on the complexity of the business area and the complexity of the underlying data model. Calibrate by tracking how well offline accuracy predicts online accuracy: we’ve found there are diminishing returns past a few dozen per topic (e.g., “growth”), and that ceiling drops with each new model generation.
- Offline eval accuracy should be ~100%; every correct answer should also be hitting your semantic layer (if you have one). Again, this level of accuracy doesn’t tell you your system isn’t going to produce a wrong answer, just that there are no obvious gaps, assuming you have proper eval coverage.
Ablation techniques
Every structural decision about the skill (e.g., which sources to expose, whether a sub-agent earns its latency, whether to merge two skills into one) is made by holding our offline eval set fixed.
We vary exactly one component and compare pass rates. Each run only takes an hour and replaces a lot of arguments. The methodology matters more than any single result:
- Design for null results. Our most useful ablation was a negative one. We gave the agent direct grep access to our entire dashboard, transformation, and analyst-notebook SQL (thousands of files). We then verified in transcripts that it actually read them before every answer. Accuracy moved by less than a point in either direction. We then checked the obvious confounds: was the answer actually in the corpus for the questions it got wrong? About 80% of the time, yes. Did "answer present" predict "now gets it right"? No, the flip rate was flat. The information was there, the agent saw it, and it still didn’t use it. That single experiment told us our bottleneck wasn't access to prior work, it was structure (i.e., mapping a question to the right entity). That insight redirected months of roadmap.
- Ablate at PR granularity. Every meaningful skill edit gets a before / after run on the relevant eval slice, with the delta in the PR description. It keeps "I improved the docs" honest and catches the surprisingly common case where a well-intentioned addition makes things worse.
- Keep a short list of what didn't work. Two of ours: stacking additional rounds of doc refinement past a certain point (we hit three consecutive net-negative iterations: the docs were getting longer, not better), and swapping the adversarial reviewer to a cheaper model to cut latency (it lost most of the accuracy wins, for no real speedup). Negative results are cheap to record and they prevent the next person from re-running the same experiment.
Online validation
The final step is ensuring the actual online system performance is as accurate as possible. Some of the steps we take include:
- Adversarial review: we’ve found that employing a Claude skill to aggressively challenge all underlying assumptions on a potential final answer increased accuracy by 6% within our eval set, but at the cost of 32% more tokens and 72% higher latency.
- Provenance footer: every response carries a footer that contains which source tier it came from (semantic layer › curated reference › raw table), how fresh the underlying data is, and who owns the model. It doesn't make the answer more correct, but it does help the consumer judge how much they can trust the response. A "raw table, freshness unknown" footer is a signal to verify before forwarding upstream, and it's one of the few mitigations we have for silent failures.
- Data quality checks: it’s possible that your agent is using the right field in the appropriate way, but the data itself is incorrect. Adding basic data quality checks to ensure the referenced field is up-to-date, complete, and has no anomalies is generally good hygiene.
- Passive monitoring: two production signals we track continuously are the share of agent queries that resolve through the semantic layer, and the share of responses that use correction language ("that's the wrong table," "you're missing the fraud filter"). Both feed a dashboard reviewed weekly alongside the offline pass rate.
- Active correction harvesting: the part that closes the loop. A scheduled agent scans stakeholder channels every few hours for similar correction language, drafts a one-line fix to the relevant reference doc, and opens a PR tagged to the domain owner. The fix path is deliberately boring — edit a markdown file, merge, auto-sync everywhere — so a domain owner doesn’t spend too much time on the task. The same corrections feed back into the offline eval set.
The failure mode none of this fully catches is the silent one. The answer is wrong, but looks plausible and is used without objection. Our mitigations are the provenance footer, explicit human sign-off on anything leadership-bound, and a standing eval for each domain's top KPIs that sanity-checks against the blessed dashboard daily, though we don’t have a robust solution yet.
Getting started
If you're starting from zero, a handful of canonical datasets, a few dozen offline evals, and a thin knowledge skill will capture most of the upside; everything else in this post is what we added once those were built.
We also shared many best practices, and not all of them will be appropriate for every data team. Align with your organization on a few principles that will affect your approach by asking:
- How important is a correct answer today vs. in the future? AI models are progressing at a rapid pace. We often see companies building a significant amount of infrastructure to account for current model shortfalls that become moot once those models improve. Knowing where models fall short, and waiting for model improvements to fill the gap has significantly less overhead, but may not fit your company’s risk tolerance.
- How do you anticipate the complexity of your business to change over time? Some of the processes we discussed may be overkill if, for example, you don’t produce much data, you only have a few consumers of the output, or your data model is likely to remain simple.
- How technical is the intended audience of the output? Phrased differently, if you’re building this analytics system for data scientists who can recognize when an answer is incorrect, you may be more tolerant of errors compared to a situation in which the audience has no familiarity with the underlying data model.
- How much are you willing to spend for improved accuracy? We’ve found certain processes like adversarial validation can significantly improve accuracy, but often at a higher cost and latency.
- What is your comfort around access controls and internal data privacy? Agents are often significantly more performant the more context they have; however, broad data access cuts against most companies' governance posture. This determines whether you're building one agent or many scoped ones.
Whatever your route, our greatest gains have come from addressing each of the three failure modes: collapsing ambiguity into a single governed answer, making the answer easily discoverable, and flagging when either has gone stale.
This article was written by Chen Chang, Clement Peng, Justin Leder, Johanne Jiao, and Josh Cherry, members of the Data Science and Data Engineering team. The authors would like to thank Michael Segner for his contributions.
Appendix
Skill File Skeleton
What follows is the skeleton of our main warehouse skill: the real file's structure, with internal specifics replaced by [bracketed placeholders]. It isn't meant to be copied verbatim; it's meant to show the kinds of sections we found worth writing down.
---
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## DescriptionThe 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 queriesPriority:
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 workflow1.**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 Workflow1.**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 Guide1. 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 …]