Claude CodeのClickHouseプラグインで28ルールのレビューを回す

ClickHouse社が公開しているclickhouse-best-practicesプラグインは、ClickHouseのスキーマ設計、クエリ最適化、データ挿入について、優先度つきの28ルールをClaude Codeに渡します。入れると、CREATE TABLEを書かせたりスロークエリを相談したりするたびに、Claude Codeがルール名を挙げながらレビューするようになります。

ClickHouseには接続しません。入るのは知識であって、データベースを操作する道具ではありません。なお「28ルール」はマーケットプレイスの説明文とREADMEの数字で、実際に入るSKILL.mdは31ルール版です(後半で触れます)。ここでは導入、28ルールの分類、レビュー依頼の書き方、手元のGitHubリポジトリとの差分まで順に説明します。

入れ方は公式マーケットプレイスから1コマンド

プラグインは、Anthropicの公式マーケットプレイス(claude-plugins-official)にカテゴリdatabaseで登録されています。Claude Codeのセッション内で次を実行します。

/plugin install clickhouse-best-practices@claude-plugins-official

マーケットプレイスの登録は、提供元のGitHubリポジトリ(ClickHouse/agent-skills)を特定のコミットに固定する形です。追加の手順やコマンドラインからの書式の違いは、claude plugin installの導入経路を選ぶにまとめています。

リポジトリのREADMEには、別の入れ方も載っています。

• npx skills add clickhouse/agent-skills: 検出したエージェントを選んでスキルを入れる
• clickhousectl skills: ClickHouseのCLI clickhousectlから入れる

Claude Code以外のCursorやCodexなどにも同じスキルを入れられる、というのがnpx経路の位置づけです。Claude Codeだけで使うなら、上のプラグイン経路で足ります。

28ルールは11カテゴリ、重さの順に並ぶ

READMEの表では、28ルールが11カテゴリに分かれ、それぞれに影響度(CRITICAL / HIGH / MEDIUM)が付いています。

CRITICALが17本、HIGHが10本、MEDIUMが1本です。数えると、ルールの6割がCRITICALに集まっています。ClickHouseでは主キーとデータ型を後から変えにくく、最初の設計で性能がほぼ決まる、という重みづけです。実際、schema-pk-plan-before-creationは「ORDER BYは作成後に変えられないので、作る前に計画する」というルールです。

ルールはrules/ディレクトリに1ファイルずつ置かれ、ファイル名の接頭辞(schema-pk- schema-types- query-join- insert- など)でカテゴリが分かります。各ファイルは、理由の説明、Incorrect(悪い例)、Correct(良い例)、補足の順で書かれています。

レビューは「スキーマ」「クエリ」「挿入」の3つの読み順で動く

SKILL.mdには、依頼の種類ごとに読むルールの順番が書かれています。

SKILL.mdは出力の形も指定しています。「Rules Checked」でルールごとに準拠か違反かを並べ、「Findings」で違反の現状・求められる形・修正案を示し、最後に優先順の推奨を置く構成です。説明文には「回答前に該当ルールを読み、応答でルールを引用すること」とあり、Per schema-pk-cardinality-order...のようにルール名を添えて答える運用が前提になっています。

つまり、「このテーブル定義をレビューして」と頼むだけで、根拠つきの指摘が返る設計です。感想ではなくルール名で返ってくるので、指摘を検証しやすくなります。

依頼はテーブル定義とクエリの実物を添えて書く

効かせるコツは、設計の意図ではなく実物を渡すことです。たとえば次のように頼めます。

次のテーブル定義とクエリを、clickhouse-best-practicesのルールでレビューして。
違反したルール名と修正案を出して。
CREATE文は変更せず、修正案は別のコードブロックで。
 
CREATE TABLE events (
    event_id UUID,
    event_type String,
    user_id Nullable(UInt64),
    created_at DateTime
) ENGINE = MergeTree ORDER BY (event_id, created_at);

READMEの例文は「user_id、event_type、properties(JSON)、timestampを持つユーザーイベントのテーブルを作って」という新規作成の依頼です。書かせる側でも、レビューさせる側でも、同じルールが働きます。

この定義には、公式のルールファイルに照らして、少なくとも次の指摘が出る形です。

• UUIDを先頭に置いたORDER BY: schema-pk-cardinality-order(高カーディナリティが先頭だと、インデックスで読み飛ばせない)
• Nullable(UInt64)のuser_id: schema-types-avoid-nullable(Nullableは別列で管理されるぶん保存量が増える)

ただし、これはルールの文面から導いた予想です。実際の返答はモデルと文脈で変わるため、出力を鵜呑みにせず、後述の確かめ方を併用してください。

3つのルールを具体例で見る

ORDER BYは低カーディナリティの列から並べる

ルールファイルの悪い例はORDER BY (event_id, event_type, timestamp)で、良い例はORDER BY (event_type, event_date, event_id)です。スパースインデックスは行ではなくグラニュール(ブロック)単位で働くため、先頭の列の値がブロックごとに違うと、1つも読み飛ばせないという理屈です。同じファイルには、日単位で絞れるなら生のDateTimeではなくtoDate(timestamp)を使うと索引が小さくなる、という補足もあります。

更新はALTER TABLE UPDATEでなくReplacingMergeTreeか軽量UPDATEへ

insert-mutation-avoid-updateは、ALTER TABLE UPDATEがデータパート全体を書き直すミューテーションだと説明します。ルールは書き込みの増幅、ディスクI/Oの急増、取り消し不可、読み取りの不整合を理由に挙げ、代替を3つ比べています。

軽量UPDATEは25.7以降の機能として書かれています。使っているClickHouseのバージョンが古いなら、この選択肢は取れません。

1件だけ結合できれば足りるならANY JOINにする

query-join-use-anyは、結合先から1件だけ欲しいときにLEFT JOINをLEFT ANY JOINに替えるルールです。最初の一致だけ返すので、メモリと実行時間が減ります。注文に顧客名を付ける例のように、結合キーが一意だと分かっている場面向けです。一意でない結合に機械的に当てると結果の行数が変わるので、指摘を受けたら結合キーの一意性を確認してください。

手元の本物のClickHouseに向けるときは、クエリに上限を付けるルールが働く

GitHubリポジトリのSKILL.mdは、スキーマ・クエリ・挿入の3分類のほかに、エージェントがClickHouseに接続して問い合わせる場面のルールも持っています。

• agent-connect-mcp: MCPとCLIの接続、認証情報の探し方、出力形式の選び方
• agent-discovery-schema: クエリの前にスキーマを調べる7段階の手順
• agent-query-safety: LIMIT、タイムアウト、段階的な探索

agent-query-safetyは、エージェントが書くクエリには必ず制限を付けるという規則です。LIMITに加えてmax_rows_to_readなどでスキャン量を縛ること、max_execution_timeを設定することを求めています。ルール本文によれば、LIMITだけではフルスキャンを防げません。推奨設定の例は次のとおりです。

SELECT *
FROM events
WHERE event_date >= today() - 7 AND user_id = '123'
LIMIT 100
SETTINGS max_execution_time = 30,
         max_rows_to_read = 1000000000,
         timeout_before_checking_execution_speed = 0

ルールは、max_rows_to_readとmax_execution_timeが、セルフホストでもClickHouse Cloudでも既定は無制限(0)だと注記しています。Claudeが毎回この設定を付けてくれる保証はないので、本番に近い環境では設定プロファイルやクォータで強制する方が確実です。

ClickHouseへのMCP接続そのもの(mcp-clickhouseの導入、読み取り専用の既定、EXPLAIN ESTIMATEによる見積もり)は、ClickHouse MCPサーバーでOLAP分析クエリを実行するで扱っています。プラグインは「どう書くか」の指針、MCPは「実際に実行する経路」と考えると、役割が分かれます。

プラグインの中身は28ルールだけではない

提供元のplugin.jsonは、1つのプラグインにスキルを8つ登録しています。

アーキテクチャアドバイザーは、READMEによれば「何をするか」だけでなく「いつ、なぜ、どうするか」に答える補完役で、推奨を公式・派生・現場知見の3種に区分して示すとあります。ルール集がチェックリスト、アドバイザーが設計判断、という分担です。

28ルールと、GitHubの最新の数字がずれている

導入前に知っておきたいのは、数字の食い違いです。公式マーケットプレイスの説明文とREADMEは「28ルール」ですが、GitHubのmainにあるSKILL.mdはversion: "0.4.0"で「31ルール」と書かれています。差の3本は、前節のエージェント接続用ルール(agent-*)です。リポジトリのmarketplace.jsonとplugin.jsonは0.3.0のままなので、プラグインの版とSKILL.mdの版が揃っていません。

公式マーケットプレイスが固定しているコミット(356a8c1)のSKILL.mdも、すでにversion: "0.4.0"で31ルール(agent-*の3本を含む)です。マーケットプレイスの説明文の「28ルール」は古い数字のまま残っています。つまり、公式マーケットプレイスから入れると、31ルール版が手元に入ります。

確かめるなら、導入したスキルのrules/にagent-で始まるファイルがあるかを見ます。SKILL.md本文にも「28ルールすべてに照らしたスキーマ設計レビュー」という記述が残っており、28と31が併存しています。

つまずきやすい点

• ルールが引用されない: スキルの自動起動は説明文に依存します。起動しないときは、依頼文にclickhouse-best-practicesを名指しして頼みます。スキルの仕組みはClaude Codeのスキル解説にあります。
• 指摘が実バージョンに合わない: 軽量UPDATEは25.7以降です。古いバージョンのセルフホスト環境では、ReplacingMergeTree側の案を採ります。
• 性能が実際に上がったか分からない: ルールは一般論です。直したあとは、実データでEXPLAINやsystem.query_logを見て、読み取り行数が減ったことを確かめます。
• 対象はスキーマ・クエリ・挿入まで: 取り込み方式や事前集計のような設計判断は、前節のアーキテクチャアドバイザー側の守備範囲です。

同じデータベース系の公式プラグインでも、Redisプラグインは本プラグインと同じく接続せず指針だけを渡し、CockroachDBプラグインはMCPサーバーを同梱してクラスターに接続します。

まとめ

clickhouse-best-practicesは、ClickHouseを触る場面でClaude Codeの答えをルール名つきのレビューに変えるプラグインです。効果が大きいのは、テーブルを作る前です。ORDER BYとデータ型は後から直しにくく、CRITICALのルールがそこに集中しているためです。

依頼にはテーブル定義とクエリの実物、それにClickHouseのバージョンを添えます。指摘が返ったら、実データで読み取り行数を比べます。本番に近いデータベースへ繋ぐ場合は、プラグインのルールに頼らず、クォータや設定プロファイルで上限を強制しておくと安全です。