实用提示：Anthropic 告诉你，代理分析并非仅仅是……
《实用笔记》操作指南：Anthropic指出，代理分析并不仅仅是那些供采用该模式的团队使用的合同、检查项以及可直接插入的代码模块。
以下内容梳理了一条实用路径，围绕“Anthropic想要告诉您：代理分析并不仅仅是文本转SQL”这一主题展开。重点在于契约、校验机制以及可直接插入的代码占位符，而非激励性表述。 在完成概览阶段时，首先列出契约内容：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个架构即可进行审计。
在哪里可以找到这篇博客文章？
将“舞台作品可在何处找到”视为一个可度量的指标会更为有效。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。 同时记录正常流程和恢复流程。重试机制、人工审核环节以及死信处理都是产品本身的一部分，而非后续的优化工作。 保持图表状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点编写了哪个字段的信息，还会在中断后导致流程无法继续。
本文将涵盖哪些内容？
“我们将涵盖什么”这一阶段最好被视为一个可度量的范畴。在扩大范围之前，先记录一份优秀的案例、一个失败实例以及回滚说明。 相较于庞大的脚本，应优先选择小型且可测试的单元。当某个步骤出错时，故障应能指向单一责任主体，而非复杂的流程链。 保持图表状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在流程中断后导致无法继续执行。
为何如此多的团队将智能分析简化为文本转SQL？
为何许多阶段工作在被视为可度量的对象时表现最佳？在扩大范围之前，先记录一份完美的操作日志、一个失败案例以及回滚说明。将这一阶段视为输入与已验证输出之间的契约，为相关成果命名，明确成功标准，绝不允许出现悄无声息的半完成状态。保持图结构简洁且类型明确，嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在中断后导致无法继续处理。为何许多阶段工作在被视为可度量的对象时表现最佳？在扩大范围之前，先记录一份完美的操作日志、一个失败案例以及回滚说明。将配置置于应用程序代码之外，环境文件、密钥存储和功能开关应集中存放于一个位置，这样操作人员无需查看整个图结构即可进行审计。
为何数据歧义才是分析代理中的真正问题？
在“数据模糊性原因分析”阶段，应在修改代码之前明确输入内容、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理措施都是产品本身的组成部分，而非后续需要补充的内容。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。
分析功能存在哪三种风险或故障模式？
对于三阶段模型，应在修改代码之前明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应优先使用小型且可测试的单元。当某个步骤失败时，故障原因应能指向单一责任主体，而非复杂的流程链。对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的逻辑连接并不等同于业务功能的完整性。
Anthropic实际上为自助分析功能构建了什么？
在修改代码之前，需明确Anthropic实际要处理的任务内容、输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，杜绝默许的半完成状态。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务上的完整性。 在修改代码之前，需明确Anthropic实际要处理的任务内容、输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于操作人员可审计的位置，无需阅读整个代码文件。
图表。
代理分析框架在编写SQL之前需要什么？
在处理“代理阶段”时，首先明确契约内容：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续代码修改的规范性。 同时记录正常流程和恢复流程。重试、人工审核以及死信处理都是产品功能的一部分，而非后续的优化工作。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的LLM接口。
标准数据集
在处理规范数据集阶段时，首先明确相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一责任模块，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
将元数据视为一流产品
在将元数据视为一个处理阶段时，首先需明确相关契约：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 应将此阶段视为输入与已验证输出之间的契约。为相关产物命名，定义成功判定标准，杜绝无声的半完成状态。 在成本较高的操作之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型接口。 在将元数据视为一个处理阶段时，首先需明确相关契约：所需的输入参数、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 将配置信息置于应用程序代码之外。环境文件、密钥存储及功能开关应集中存放于一个位置，以便操作员无需查看整个流程即可进行审计。
模型、文档、仪表板与技能文件的整合
将“模型、文档、仪表板”这一整合阶段视为可度量的工作面最为有效。在扩大范围之前，需记录一份最佳操作案例、一个故障实例以及回滚说明。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。 为每轮对话和每次会话设定令牌预算。智能工具会大量消耗上下文资源，设置上限可避免演示过程变成意外的费用账单。
为何语义层是分析智能体的地图？
将“为何”这一语义阶段视为可测量的对象时，其效果最佳。在扩大范围之前，先记录一份优秀的处理结果、一个失败案例以及回滚说明。 相较于庞大的脚本，应优先选择小型且可测试的单元。当某个步骤失败时，故障应能指向单一责任主体，而非复杂的流程链。 保持图结构的状态简洁且具有类型定义。嵌套的数据块会掩盖哪个节点修改了哪个字段的信息，还会在流程中断后导致无法继续执行。
示例查询也有助于增强语义层
将示例查询视为可度量的对象，才能最好地提升阶段工作的效率。在扩大范围之前，需记录一份理想状态下的输出、一个失败案例以及回滚说明。应将此阶段视为输入与已验证输出之间的契约，为相关成果命名、明确成功标准，并杜绝默许的半完成状态。要保持图结构的扁平化与类型化，嵌套的数据块会掩盖具体是哪个节点修改了哪个字段，还会在中断后导致无法继续处理。将示例查询视为可度量的对象，才能最好地提升阶段工作的效率。在扩大范围之前，需记录一份理想状态下的输出、一个失败案例以及回滚说明。应将配置置于应用程序代码之外，环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作人员无需查看整个图结构即可进行审计。
为何技能会影响准确性？
在进入“为何技能会变化”阶段时，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误处理都是产品本身的组成部分，而非后续需要补充的内容。 对于涉及资金支出或修改生产数据的操作，必须经过人工审批。编译时的配置并不等同于业务功能的完整性。
为何评估与维护与提示功能同样重要？
在修改代码之前，对于“为何进行评估和分阶段处理”，需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。相比冗长的脚本，更应采用小型、可测试的单元。当某个步骤失败时，故障原因应指向单一责任主体，而非复杂的流程链。如果后续步骤是代码调用或工具调用，相比自由形式的文字描述，结构化且经过模式验证的输出更为合适。
如果数据团队希望立即实现智能分析，应该怎么做？
对于数据团队应将其置于哪个阶段的问题，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将此阶段视为输入与已验证输出之间的契约。为相关成果命名，定义成功检测标准，并杜绝默许的半完成状态。 对于那些会耗费资金或修改生产数据的操作，必须经过人工审批。编译时的连接方式并不等同于业务上的完整性。 对于数据团队应将其置于哪个阶段的问题，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。
现在，想听听您的意见
在规划“现在您想要实现的功能”时，首先需列出相关要求：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程和异常恢复流程。重试机制、人工审核环节以及错误消息处理都是产品本身的组成部分，而非后续的优化工作。 在成本较高的步骤之后设置检查点。当操作员重新尝试某个节点时，恢复流程不应再次调用相同的大型语言模型。
敬请关注！
在处理“保持关注”阶段时，首先写下合同条款：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤失败时，故障应指向单一的责任模块，而非复杂的流程链。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。
参考资料
在处理“参考阶段”时，首先需写明合同条款：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。 将此阶段视为输入与验证后输出之间的契约。为相关成果命名，明确成功检测标准，并杜绝无声的半完成状态。 在成本较高的步骤之后设置检查点。当操作员重新尝试后续节点时，恢复流程不应再次调用相同的大型语言模型。 在处理“参考阶段”时，首先需写明合同条款：所需输入、成功信号以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持透明。 将配置信息置于应用程序代码之外。环境文件、密钥存储和功能标志应集中存放于一个位置，以便操作员无需查看整个流程即可进行审计。
附录
将附录阶段视为可度量的界面来处理效果最佳。在扩大范围之前，先记录一个成功的案例、一个失败案例以及回滚说明。同时记录正常流程和恢复流程的细节。重试机制、人工审核环节以及错误处理都是产品本身的一部分，而非后续需要补充的内容。保持图表状态简洁且类型明确，嵌套的数据结构会掩盖具体是哪个节点修改了哪个字段，还会在流程中断后导致无法继续执行。
---
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 …]
操作检查清单
在制定操作检查清单阶段时，应在修改代码之前明确输入参数、各步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行相应步骤，而无需猜测隐藏的状态信息。
在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免在流程从演示环境过渡到共享环境时出现意外费用。
对于会花费资金或修改生产数据的操作，必须经过人工审批。编译时的配置连接并不等同于业务功能的完整性。
编写一份简短的操作手册：说明如何轮换密钥、如何清空队列以及如何回滚上一次的数据导入操作。
将配置信息置于应用程序代码之外。环境文件、密钥存储以及功能开关应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审计。
对于会花费资金或修改生产数据的操作，必须经过人工审批。编译时的配置连接并不等同于业务功能的完整性。
在升级整个技术栈之前，应先冻结现有版本，为关键流程生成标准操作记录，并确认好回滚步骤。共享环境需要设置速率限制、进行租户身份验证，同时明确密钥轮换的责任人。与其追求花哨的一次性演示，不如注重扎实的可靠性。
关于 ce605454bbc9 的批量处理说明：不要将提供者密钥放入代码仓库，设定单次会话的令牌上限，并将转录内容存储在评估测试用例旁边，以便后续模型更换时仍能保持可比性。
针对强化安全性的第 0 阶段，在修改代码之前需明确输入内容、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应将此阶段视为输入与经过验证的输出之间的契约，为相关文件命名、定义成功检测标准，并拒绝默许部分完成的情况。
强化安全性细节 0/864：针对此说明需统计运行时间、错误类型以及令牌消耗情况，然后依据固定的问题集而非主观判断来决定是否保留该更改。
在处理强化措施的第一阶段时，首先写下相关约定：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 应将配置信息与应用程序代码分开存放。环境文件、密钥存储以及功能开关应集中于一个位置，这样操作人员无需查看整个系统结构即可进行审计。
强化措施细节 1/864：针对该措施记录运行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该变更。
将强化措施的第二阶段视为可度量的对象来处理效果最佳。在扩大范围之前，先记录一份理想的操作流程、一个失败案例以及回滚说明。 相比复杂的脚本，更应采用小型且可测试的单元。当某个步骤出现故障时，故障原因应能明确指向某个具体的责任模块，而非整个复杂的流程链。
强化措施细节2/864：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在强化措施的第3阶段，应在修改代码之前明确输入参数、该步骤的负责人以及完成标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录时间以及代币或查询成本。提前了解成本情况，可避免在从演示环境过渡到共享环境时出现意外费用。
强化措施细节3/864：为该记录测量运行时间、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
在处理强化建议的第4阶段时，首先需明确相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续的优化内容。
强化建议细节4/864：需测量该建议相关的执行时间、错误类型以及令牌消耗情况，然后依据固定的评估标准而非个人经验来决定是否保留该修改。
在处理强化建议的第0阶段时，首先需明确相关约定：所需输入、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。 同时记录正常流程与恢复流程。重试机制、人工审核环节以及错误处理方式都是产品本身的组成部分，而非后续的优化内容。
强化细节 0/883：测量该记录的耗时、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。
将强化笔记的第一阶段视为可测量的对象最为有效。在扩大范围之前，需记录一份最佳案例、一个故障实例以及回滚说明。将此阶段视为输入与经过验证的输出之间的契约，为相关文档命名，明确成功标准，并拒绝默许的半完成状态。
强化细节 1/883：测量该记录的耗时、错误类型以及代币消耗情况，然后依据固定的问题集而非个人经验来判断是否保留该变更。