前言¶

在 Agent 里问 ClickHouse 建表、改查询或调配置，模型往往会套用通用 OLTP 直觉：随便 Nullable、大分区、JOIN 后再过滤。列存、稀疏索引和 MergeTree 的机制不同，这类建议轻则浪费存储，重则拖垮查询。下面介绍 ClickHouse 官方维护的 Agent Skill clickhouse-best-practices：在给出 schema、查询或配置相关建议之前，必须先对照内置规则核对，并在回复里引用具体规则名。

这是什么¶

clickhouse-best-practices 是 ClickHouse Agent Skills 仓库中的一个 Skill，由 ClickHouse Inc 维护，许可证 Apache-2.0，当前元数据版本为 0.4.0。Skill 描述写明：审查 ClickHouse schema、查询或配置时必须使用；内含 31 条须在给出建议前检查的规则，覆盖 schema 设计、查询优化、数据写入与 Agent 连通四类，并按影响优先级排序。规则与官方文档 ClickHouse Best Practices 对齐，属于「可执行的检查清单 + 引用格式」，而不是替代 ClickHouse 文档本身。

同仓库还提供架构顾问、Node 客户端排障、chdb、基础设施等其它 Skill；本篇只围绕 best-practices 这一条。

核心功能¶

规则优先的回答流程¶

回答任何 ClickHouse 相关问题前，Skill 要求按以下顺序处理：

1. 在 rules/ 目录中查找适用规则；
2. 若存在适用规则：按规则执行，并在回复中用 Per \rule-name`…` 形式引用；
3. 若无对应规则：再用模型自带的 ClickHouse 知识或查文档；
4. 仍不确定时：用 Web 搜索当前最佳实践；
5. 始终标明来源：规则名、「general ClickHouse guidance」或 URL。

这样做的原因是：列存、稀疏索引、MergeTree 合并等行为与常见数据库直觉不一致，规则里编码的是经校验的 ClickHouse 专用指导。

四类审查与 Agent 工作流¶

Schema 审查（CREATE TABLE / ALTER TABLE）：按固定顺序阅读主键规划、基数排序、过滤列、类型、LowCardinality、Nullable、分区等规则文件，并核对 ORDER BY 不可变、分区基数约 100–1,000、ReplacingMergeTree 是否带版本列等检查项。

查询审查（SELECT / JOIN / 聚合）：覆盖 JOIN 算法选择、JOIN 前过滤、ANY JOIN、跳数索引、WHERE 与 ORDER BY 对齐等。

写入策略审查：批量大小（建议每批约 10K–100K 行）、避免频繁 ALTER TABLE UPDATE/DELETE、异步小批量写入、慎用 OPTIMIZE TABLE 等。

Agent 连通与查询：连接（MCP + CLI）、7 步 schema 发现、带 LIMIT 与超时的安全查询；推荐会话顺序为 Connect → Discover → Plan → Execute → Recover。

规则分类与优先级（节选）¶

规则文件命名示例：schema-pk-plan-before-creation（建表前规划 ORDER BY，因其不可变）、query-join-filter-before（JOIN 前先过滤）、insert-batch-size（批量写入大小）等，完整列表见仓库内 SKILL.md 与 rules/。

规定的输出结构¶

做审查类回复时，Skill 要求 Agent 按模板组织结果，便于对照合规与违规项：

## Rules Checked
- `rule-name-1` - Compliant / Violation found
...

## Findings
### Violations
- **`rule-name`**: ...
### Compliant
- `rule-name`: ...

## Recommendations
...

安装与启用¶

Skill 随 clickhouse/agent-skills 整包分发，可用官方文档中的两种方式安装到已支持的 Agent 环境：

npx skills add clickhouse/agent-skills

npx skills 会检测本机已安装的 Agent 并提示选择安装目标。若已安装 clickhousectl，也可执行：

clickhousectl skills

Skill 遵循 agentskills.io 开放规范；加载后，在处理 ClickHouse 建表、写查询或设计数据管道时，Agent 应自动激活相关指导。人类可读总览见仓库内 skills/clickhouse-best-practices/SKILL.md，完整编译版见同目录 AGENTS.md。

Cursor、Claude Code、Copilot 等平台对 Skills 的挂载路径与触发方式以各产品文档为准；安装命令以 ClickHouse 仓库 README 为准。

典型用法¶

场景一：评审一张新表的 DDL

把 CREATE TABLE 语句交给已加载该 Skill 的 Agent，要求其按 Schema Review 流程逐条读 rules/schema-pk-*、rules/schema-types-*、rules/schema-partition-* 等文件，并按「Rules Checked / Findings / Recommendations」输出。你会看到是否违反「ORDER BY 列低基数到高基数排序」「过滤列是否进入排序键前缀」「分区数量是否失控」等具体规则引用。

场景二：优化慢查询

提供 SELECT 与表结构上下文，Agent 应优先查阅 query-join-*、query-index-skipping-indices、schema-pk-filter-on-orderby 等，检查 JOIN 前是否过滤、算法是否匹配表规模、非排序键过滤是否考虑跳数索引。

场景三：Agent 直连 ClickHouse 探数

按 Skill 要求先走 rules/agent-connect-mcp.md 建立连接，再执行 rules/agent-discovery-schema.md 中的七步发现（库 → 表 → 列与注释 → 排序键 → 跳数索引 → 采样 → EXPLAIN），最后在 rules/agent-query-safety.md 约束下带 LIMIT 与超时执行查询；超时或内存错误时缩小过滤范围重试。

适用场景与注意¶

适合谁

• 用 Cursor、Claude Code、Copilot 等 Agent 做 ClickHouse schema 设计、SQL 评审或写入策略讨论的团队；
• 希望 AI 建议与 clickhouse.com/docs/best-practices 一致、且能追溯「哪条规则」的读者；
• 在 analytics 或 AI 数据管道里加大 ClickHouse 用量、又不想让 Agent 凭泛化数据库经验乱改键或分区的人。

限制与注意

• Skill 是审查与流程指令，不替代你连上集群做 EXPLAIN、看 system.parts 等实证；Agent 规则里也写明无适用规则时再查文档或搜索。
• 仓库 README 对「业务规则条数」的表述与 Skill 元数据（31 条、含 agent 类）略有层次差异；以 clickhouse-best-practices 目录内 SKILL.md 及 rules/ 实际文件为准。
• 全量 schema 设计若需「何时分区、如何选型架构」，可配合同仓库的 clickhouse-architecture-advisor，best-practices 侧重可检查的 what，架构 Skill 侧重 when/why/how。

结尾¶

clickhouse-best-practices 把 ClickHouse 官方最佳实践拆成 31 条必查规则和固定审查流程，让 Agent 在改表、改 SQL、谈写入之前先对齐列存与 MergeTree 的真实约束，并在输出里点名规则。安装整包后，在处理 ClickHouse 相关任务时加载该 Skill 即可。

官方地址：https://github.com/clickhouse/agent-skills/tree/main/skills/clickhouse-best-practices