Monte Carlo Prevent

Monte Carlo Prevent 技能

本技能将 Monte Carlo 的数据可观测性上下文直接带入编辑器。修改 dbt 模型或 SQL 管道时，可用它呈现表健康度、血缘、活跃告警，并生成 monitors-as-code，无需离开 Claude Code。

参考文件位于本技能文件旁。使用 Read 工具（而非 MCP 资源）访问：

• 完整工作流分步说明：references/workflows.md（相对于本文件）
• MCP 参数详情：references/parameters.md（相对于本文件）
• 故障排查：references/TROUBLESHOOTING.md（相对于本文件）

何时激活本技能

无需等待用户请求。 当用户执行以下操作时，自动运行对应工作流：

• 引用或打开 .sql 文件或 dbt 模型（models/ 目录下的文件）→ 运行工作流 1

• 顺带提及表名、数据集或 dbt 模型名 → 运行工作流 1

• 描述对模型的计划变更（新列、join 更新、过滤条件变更、重构）→ 停止 — 在编写任何代码前运行工作流 4

• 向现有模型添加新列、指标或输出表达式 → 先运行工作流 4，然后无论风险等级如何， 始终提供工作流 2 — 不得跳过监控器建议

• 询问数据质量、新鲜度、行数或异常 → 运行工作流 1

• 需要分诊或响应数据质量告警 → 运行工作流 3

将结果作为工程师继续操作前所需的上下文呈现 — 而非作为对问题的回答。

何时不激活本技能

以下情况不调用 Monte Carlo 工具：

• Seed 文件（seeds/ 目录下的文件）
• Analysis 文件（analyses/ 目录下的文件）
• 不属于 dbt 项目的一次性 SQL 脚本
• 配置文件（dbt_project.yml、profiles.yml、packages.yml）
• 测试文件，除非用户专门询问数据质量

如不确定文件是否为 dbt 模型，检查是否包含 {{ ref() }} 或 {{ source() }} Jinja 引用 — 若无则不激活。

宏和快照 — 门控编辑，跳过自动上下文

宏文件（macros/）和快照文件（snapshots/）不是模型，因此打开时不要自动获取 Monte Carlo 上下文（工作流 1）。但宏在编译时会被内联到每个调用它的模型中 — 一行宏的变更可能静默影响数十个模型。快照控制历史追踪，同样敏感。

预编辑钩子会门控这些文件。 若钩子对宏或快照触发，识别受影响的模型，在继续编辑前对这些模型运行变更影响评估（工作流 4）。

必需：任何 SQL 编辑前的变更影响评估

编辑或编写任何 dbt 模型或管道的 SQL 之前，必须运行工作流 4。

当用户表达修改模型的意图时即适用 — 包括以下表述：

• "我想加一列…"
• "让我加 / 我正在加…"
• "我想改 / 更新 / 重命名…"
• "能不能加 / 修改 / 重构…"
• "我们加…" / "加一个 <column> 列"
• 任何其他对计划中的 schema 或逻辑变更的描述
• "排除 / 过滤掉 / 移除 [记录/客户/行]…"
• "调整 / 增加 / 减少 [阈值/参数/值]…"
• "修复 / 修bug / 打补丁 [问题/bug]…"
• "回退 / 恢复 / 撤销 [变更/之前的行为]…"
• "禁用 / 启用 [功能/逻辑/标志]…"
• "清理 / 移除 [引用/列/代码]…"
• "为…实现 [后端/功能]"
• "为…创建 [模型/dbt 模型]"（当修改现有被引用表时）
• "增加 / 减少 / 更改 [max_tokens/阈值/日期常量/数值参数]…"
• 对 SQL 中硬编码值、常量或配置参数的任何变更
• "删除 / 移除 / 去掉 [列/字段/表]"
• "将 [列/字段] 重命名为 [新名称]"
• "添加 [列]"（简短祈使形式，如"添加一个 created_at 列"）
• 针对列、表或模型的任何单动词祈使命令 （如"删除 X"、"重命名 Y"、"添加 Z"、"移除 W"）

参数变更（阈值、日期常量、数值限制）看似安全但会静默改变模型输出。在影响评估中应与逻辑变更同等对待。

在变更影响评估（工作流 4）呈现给用户之前，不得编写或编辑任何 SQL。 评估必须先于编辑，而非之后，也非并行。

预编辑门控 — 修改任何文件前检查

在调用 Edit、Write 或 MultiEdit 修改任何 .sql 或 dbt 模型文件之前，必须检查：

1. 当前提示中是否已为本次具体变更运行了综合分析步骤？
2. 若是 → 继续编辑
3. 若否 → 立即停止，运行工作流 4，呈现与本次具体变更关联的完整报告和综合分析。 若风险为高或中： 询问"是否继续编辑？"并等待明确确认。 若风险为低： 自行判断 — 若变更简单且未发现问题则继续，否则先询问。

重要："工作流 4 本会话已运行过"不足以继续。 每个不同的变更提示都需要自己的综合分析步骤，将 MC 发现与该具体变更关联。

综合分析必须引用当前提示中正在变更的具体列、过滤条件或逻辑 — 而非仅一般的表健康度。

示例：

• ✅ "鉴于 34 个下游模型依赖 is_paying_workspace，将 'MC Internal' 添加到排除列表会从所有下游健康评分和导出中排除这些工作区。确认？"
• ❌ "工作流 4 已运行。现在进行编辑。"

唯一例外：用户明确承认风险并确认跳过（如"我知道风险，直接改"）— 继续但注明跳过了评估。

可用 MCP 工具

所有工具通过 monte-carlo MCP 服务器可用。

核心工作流

每个工作流在 references/workflows.md 中有详细分步说明（使用 Read 工具）。

1. 表健康度检查

时机： 用户打开 dbt 模型或提及表。 内容： 呈现健康度、血缘、告警和风险信号。若检测到变更意图且存在风险信号，自动升级到工作流 4。

2. 添加监控器

时机： 向模型添加新列、过滤条件或业务规则。 内容： 使用对应的 create*MonitorMac 工具建议并生成 monitors-as-code YAML。保存到 monitors/<table_name>.yml。

3. 告警分诊

时机： 用户正在调查活跃的数据质量事件。 内容： 列出未确认告警，检查表状态，追踪血缘定位根因，审查近期查询。

4. 变更影响评估 — 修改模型前必需

时机： 任何修改 dbt 模型逻辑、列、join 或过滤条件的意图。 内容： 呈现爆炸半径、下游依赖、活跃事件、监控器覆盖和查询暴露。生成风险分级报告，综合分析将发现与具体代码建议关联。完整评估流程、报告格式和综合分析规则见 references/workflows.md。

5. 变更验证查询

时机： 仅工程师明确请求时（如"验证这个变更"、"准备提交"）。 内容： 生成 3-5 条针对性 SQL 查询，验证变更是否按预期执行。使用工作流 4 上下文 — 需要本会话中同时存在影响评估和文件编辑。

综合分析后确认规则

始终以一条清晰、具体的建议结束综合分析： "基于以上分析，建议：[具体行动]"

若风险为高或中： 停止并等待确认后再编辑任何文件。必须询问工程师并收到明确的"是"、"继续"、"确认"或类似确认后才能进行代码变更。 说："是否继续编辑？" 不要说："继续编辑。" — 那会跳过工程师的决策。

若风险为低： 根据综合分析发现自行判断。若变更简单且综合分析未发现问题，可继续。若有任何意外或值得标记的情况，先询问再编辑。

会话标记

这些标记协调技能与插件钩子之间的交互。条件满足时每行输出一个标记。

影响检查完成

工程师确认后（高/中风险）或呈现综合分析后（低风险），每个已评估的表输出一个标记。重要：仅使用表/模型名称，不使用完整 MCON：

（使用模型文件名，不含 .sql 扩展名 — 不是 "acme.analytics.orders" 或 "prod.public.client_hub"）

输出多少标记取决于评估如何触发：

钩子触发（预编辑钩子阻止了编辑并指示运行评估）：严格 — 仅为本会话中通过 Monte Carlo 工具直接获取了血缘和监控器覆盖的表输出标记。若工程师描述了对多个表的变更但仅正式评估了一个，仅输出一个标记。预编辑钩子会门控其他表并提示运行各自的工作流 4。

主动调用（工程师主动请求影响评估）：宽松 — 为评估实质性覆盖的所有表输出标记，即使某些表是通过血缘上下文而非直接 MC 工具调用评估的。工程师已有安全意识；不要对他们明确考虑的表强制冗余评估。

监控器覆盖缺口

当工作流 4 发现表的受影响列上零个自定义监控器时，输出：

仅使用表/模型名称（不使用完整 MCON）。这使插件钩子能在提交时提醒工程师监控器覆盖情况。仅当缺口具体涉及正在变更的列或逻辑时才输出此标记 — 不针对一般的表级监控器缺失。

限制

• 仅当任务明确匹配上述范围时使用本技能。
• 不要将输出视为环境特定验证、测试或专家审查的替代。
• 若缺少必要输入、权限、安全边界或成功标准，停止并请求澄清。