# Monte Carlo Prevent > 在 SQL/dbt 编辑前呈现 Monte Carlo 数据可观测性上下文（表健康度、告警、血缘、爆炸半径）。当用户要求修改 dbt 模型或 SQL 管道时使用。 - Skill: `kscz0000/monte-carlo-prevent` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add kscz0000/monte-carlo-prevent` - Raw SKILL.md: https://api.skillmd.com/api/skills/kscz0000/monte-carlo-prevent/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - Author: kscz0000 (https://skillmd.com/u/kscz0000) - Updated: 2026-09-21 - Page: https://skillmd.com/skills/kscz0000/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。** 当用户表达修改模型的意图时即适用 — 包括以下表述： - "我想加一列…" - "让我加 / 我正在加…" - "我想改 / 更新 / 重命名…" - "能不能加 / 修改 / 重构…" - "我们加…" / "加一个 `` 列" - 任何其他对计划中的 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 服务器可用。 | 工具 | 用途 | | ---------------------------- | -------------------------------------------------------------------- | | `testConnection` | 验证认证和连接性 | | `search` | 按名称查找表/资产 | | `getTable` | 表的 schema、统计信息、元数据 | | `getAssetLineage` | 上游/下游依赖（使用 mcons 数组 + direction 调用） | | `getAlerts` | 活跃事件和告警 | | `getMonitors` | 监控器配置 — 使用 mcons 数组按表过滤 | | `getQueriesForTable` | 近期查询历史 | | `getQueryData` | 特定查询的完整 SQL | | `createValidationMonitorMac` | 生成验证 monitors-as-code YAML | | `createMetricMonitorMac` | 生成指标 monitors-as-code YAML | | `createComparisonMonitorMac` | 生成比较 monitors-as-code YAML | | `createCustomSqlMonitorMac` | 生成自定义 SQL monitors-as-code YAML | | `getValidationPredicates` | 列出可用的验证规则类型 | | `updateAlert` | 更新告警状态/严重程度 | | `setAlertOwner` | 分配告警负责人 | | `createOrUpdateAlertComment` | 向告警添加评论 | | `getAudiences` | 列出通知受众 | | `getDomains` | 列出 MC 域 | | `getUser` | 当前用户信息 | | `getCurrentTime` | API 调用用的 ISO 时间戳 | ## 核心工作流 每个工作流在 `references/workflows.md` 中有详细分步说明（使用 Read 工具）。 ### 1. 表健康度检查 **时机：** 用户打开 dbt 模型或提及表。 **内容：** 呈现健康度、血缘、告警和风险信号。若检测到变更意图且存在风险信号，自动升级到工作流 4。 ### 2. 添加监控器 **时机：** 向模型添加新列、过滤条件或业务规则。 **内容：** 使用对应的 `create*MonitorMac` 工具建议并生成 monitors-as-code YAML。保存到 `monitors/.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）。这使插件钩子能在提交时提醒工程师监控器覆盖情况。仅当缺口具体涉及正在变更的列或逻辑时才输出此标记 — 不针对一般的表级监控器缺失。 ## 限制 - 仅当任务明确匹配上述范围时使用本技能。 - 不要将输出视为环境特定验证、测试或专家审查的替代。 - 若缺少必要输入、权限、安全边界或成功标准，停止并请求澄清。