clickhouse-best-practices

clickhouse-best-practices 技能概览

这个技能适合做什么

clickhouse-best-practices 是一套面向 ClickHouse 的评审与指导技能包，覆盖 schema 设计、查询调优、写入策略和 agent 连接能力。它最适合在你需要的不只是通用 SQL 建议，而是基于 ClickHouse 的存储机制、MergeTree 行为和查询执行模式给出具体建议的时候使用。

适合谁使用

如果你在做 ClickHouse 的数据库工程工作，比如 schema 设计、慢查询排查、数据摄取管道、MV（物化视图）和 agent 驱动分析，就适合用 clickhouse-best-practices。当你的问题是“该怎么建模数据”，而不只是“修复某一条查询”时，它尤其匹配。

它为什么不一样

它的核心价值在于规则化结构：仓库里包含可以直接引用到回答中的原子检查项，这能减少猜测，也让建议更容易自证。之所以重要，是因为 ClickHouse 的取舍往往并不直观，尤其是在 ORDER BY、分区、join 以及重度 mutation 的工作流上。

如何使用 clickhouse-best-practices 技能

安装并启用它

在执行 clickhouse-best-practices install 这一步时，把技能从 ClickHouse agent skills 仓库加入，然后在你的 agent 工作流中加载它：

npx skills add ClickHouse/agent-skills --skill clickhouse-best-practices

如果你的环境使用的是其他技能管理器，也要保持 repo 路径和 skill slug 不变，这样 agent 才能解析到正确的目录。

给它正确的输入

clickhouse-best-practices usage 这种用法，在你一次性提供表结构、查询模式、数据量和目标时效果最好。高质量输入应该明确 engine、基数、过滤条件、写入速率和痛点。例如：“请审查这个 MergeTree 表，面向按 event_date 和 tenant_id 过滤的仪表盘查询；当前表有 20 亿行、每天写入，join 很慢。”

从正确的文件开始看

一个实用的 clickhouse-best-practices guide，通常先看 SKILL.md，然后是 README.md、AGENTS.md 和 metadata.json，接着再看 rules/ 下的具体规则文件。做 schema 相关工作时，优先阅读 rules/schema-pk-plan-before-creation.md、rules/schema-partition-start-without.md 和 rules/schema-types-avoid-nullable.md。做查询相关工作时，优先看 rules/query-join-filter-before.md 和 rules/query-join-choose-algorithm.md。

用工作流来提问，不要只给一个笼统提示

高质量提示词会要求对适用规则做审查，而不是让模型随意发表意见。比如：“请根据 clickhouse-best-practices 评估这个 schema，引用相关的规则文件名，指出高风险设计，并提出能提升扫描效率的最小改动。” 这样得到的会更接近可执行的工程审查，而不是泛泛的最佳实践总结。

clickhouse-best-practices 技能 FAQ

这只适合专家吗？

不是。只要你已经知道自己的 ClickHouse 使用场景，并且能提供表定义或查询示例，它对初学者也很友好。这个技能最能发挥作用的场景，是用户已经知道问题所在，但想找对 ClickHouse 模式，而不是学习 SQL 基础教程的时候。

什么时候不该用它？

不要把 clickhouse-best-practices 用在无关的 SQL 系统上，也不要用它处理不具备 ClickHouse 特征的宽泛分析建议。如果你不用 ClickHouse，关于 merge tree、稀疏索引和分区的规则，可能误导性大于帮助。

它比普通提示词好在哪里？

普通提示词往往只会给出“加个索引”或“把数据去规范化”这类泛泛建议。这个技能更有用，是因为它会推动 agent 去检查适用的规则集，这在 ClickHouse 的最佳实践里尤其关键，比如 ORDER BY、join、批量插入和避免 mutation 这些方面。

它支持 agent 到 ClickHouse 的工作流吗？

支持。仓库里包含 agent 连接和发现相关的指导，因此当 agent 需要安全地连接 ClickHouse、在查询前检查 schema、并避免无界扫描时，clickhouse-best-practices 也同样适用。

如何改进 clickhouse-best-practices 技能

提供具体的表和工作负载细节

最好的结果来自包含 ENGINE、主键或排序键、分区方式、行数、插入频率以及准确查询形态的输入。例如，“表有 4 亿行，按月分区，查询会按 tenant_id 和 created_at 过滤，并在 user_id 上做 join”就比“让它更快”有用得多。

要求给出带规则引用的建议

如果你希望 clickhouse-best-practices 的输出更可信，就要求 agent 说明它用了哪些规则文件，并把必须修的问题和可选优化分开。这样你能看出答案是基于 schema 规则、查询规则、插入规则，还是 agent 安全规则。

从诊断迭代到重设计

常见失败模式是：只问一个 SQL 改写，但真正的问题其实是 schema 层面的。如果第一轮回答仍然扫描太多数据，或者必须依赖 FINAL，就继续提供表 DDL、慢查询和预期访问模式。这样技能才能从表面调优，推进到更符合 ClickHouse 存储行为的设计。

尽早用它挑战默认假设

对于 Database Engineering 来说，最大收益往往来自在生产前就发现不合理默认值：不必要的 Nullable 列、分区值过多、先 join 后过滤、或者过小的插入批次。clickhouse-best-practices 技能最强的使用场景，是把它放在设计评审阶段，而不只是性能事故之后。