用途
snowflake-dbt-model-refactoring 是一个面向 Snowflake 后端 dbt 项目的模型重构技能。当目标模型出现以下情况时可触发：超过约 200 行、单个查询块超过 5 个 join、单个 CTE 超过约 50 行、同一逻辑（如支付透视、RFM 分桶）在 3 个以上模型中重复、硬编码列表或阈值在内联中反复出现、且存在会受结构变更影响的下游消费方。
该技能不是纯性能调优工具：若只想优化查询性能，应使用 query-optimize；重构必须保持行数与逐行取值不变；不得触碰用户未指定的模型。若项目目标为 BigQuery、Redshift 或 Databricks，应改用通用的 refactoring-dbt-models 技能，因为其第 7 阶段的仓库基准测试是 Snowflake 专用的。
主要能力
技能以分阶段流程运行，目标端到端耗时 5–6 分钟，硬上限 8 分钟。
- 基线采集：一次性统计总行数、join 数、CTE 数与最大 CTE 大小、重复≥3 次的硬编码字面量；获取下游 dbt 子树及各下游模型消费的列；执行 dbt build 证明当前状态可构建，并从 manifest 解析物化关系名；将现有数据快照到带时间戳的唯一表名（使用 CREATE TABLE，不覆盖他人快照）；用一条动态构造的查询采集聚合签名。
- 重构计划：在改文件前列出每个拟新增的模型/宏/变量及其承接的逻辑，引用列使用图证明未丢弃被消费列，任何语义变更须显式指出并等待用户确认。
- 执行：严格在已批准写入集内操作；将抽取的中间模型设为 ephemeral；将重复字面量提升为 dbt_project.yml 中的 var；把目标模型改写为薄组合，并严格保持最终列列表（顺序、名称、类型）。对 incremental 模型有专门例外：含
{{ this }}、is_incremental()或引用自身先前状态的 CTE 不得抽取为 ephemeral，以免增量过滤失效导致重复插入历史行。 - 一致性验证：在非生产 schema 中构建候选版本，生产关系保持原版直到校验通过。校验包含两项独立检查：(a) 行数相等；(b) 考虑重复行计数的集合比对——对全部列 GROUP BY 后 FULL OUTER JOIN，使用
IS NOT DISTINCT FROM保证 NULL 安全，任何缺失行、多余行或计数偏移都会暴露。两项都通过才算一致。此外还做列契约检查，比对前后输出 schema 的名称、顺序与类型。 - 报告：报告始终在末尾内联展示，不保存到文件；产出量化的前后对比，说明哪些质量指标改善及原因。
使用方式
使用前需向用户确认两个问题：目标模型名称（必填）；一致性严格度（仅行数校验，或完整列哈希校验；默认行数加 grain 列与一个数值列的抽查哈希）。仓库基准测试不在开头询问，而在最后阶段按需选择。
工具委派有两条路径：
- 首选 altimate-code（随 dbt-snowflake kit 提供）。先用
command -v altimate-code确认可用，然后以非交互方式委派子任务：
altimate-code run "<task description>" --yolo \
--output /tmp/altimate-result.md --dir "$(pwd)"
之后读取 /tmp/altimate-result.md 使用结果。
- 回退方案：未安装 altimate-code 且用户不愿安装时，使用纯 dbt 与直接 SQL：用
dbt ls --select +<target>+ --output json加dbt docs generate并读取 target/catalog.json 与 target/manifest.json 构建列使用图（比列级血缘更粗）；用普通 dbt build / dbt compile 替代编译委派；数据一致性检查直接对仓库执行第 4 阶段 SQL；用 sqlfluff lint 替代 sql-review；成本报告改为直接查询 SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY 与 QUERY_ATTRIBUTION_HISTORY。
若 altimate-code 与纯 dbt 都不可用，应停止并告知用户，不得仅凭读取文件编造结果。
适用场景与限制
适用于存在结构膨胀、逻辑重复、下游依赖明确的 Snowflake dbt 模型，且需要在保持数据语义不变前提下做结构化重构并量化收益的工程场景。
主要限制：列使用图只能看到 dbt 跟踪的消费方，看不到 BI 看板、直连仓库查询、反向 ETL 等外部消费，因此默认不在未获逐列确认的情况下删除任何列；构建必须在非生产目标或隔离 schema 中进行，项目若无非生产目标则停止并询问用户；同一文件重写两次仍失败即停止并上报，不做静默重试；快照表名冲突须报错而非覆盖；报告中不得把仅行数匹配标称为完整一致性。分类方面，该技能属于数据工程与重构流程，暂未提供更细的平台兼容范围与定价信息。