sql-optimization-patterns

sql-optimization-patterns スキルの概要

sql-optimization-patterns でできること

sql-optimization-patterns は、遅い SQL の原因を切り分け、なぜそのクエリが遅いのかを説明し、クエリの形・インデックス・JOIN・ページネーション・実行計画の読み取りに沿って具体的な改善策を提案するスキルです。特に、すでに現実の性能問題が起きていて、ありがちな「とりあえずインデックスを追加」といった助言ではなく、構造化された最適化ワークフローで進めたいときに役立ちます。

どんな人に向いているか

このスキルは、勘に頼らずクエリを高速化したいバックエンドエンジニア、データベースエンジニア、プラットフォームチーム、アプリケーション開発者に向いています。とくに PostgreSQL 系の EXPLAIN 出力を扱うチームと相性が良いですが、ここで使われる考え方は他のリレーショナルデータベースにも応用できます。

実際に解決する仕事

多くのユーザーが必要としているのは、単なる SQL 構文レビューではありません。必要なのは次のような支援です。

• なぜそのクエリが遅いのかを特定する
• 実行計画の症状から、あり得る根本原因に結びつける
• クエリ書き換えとインデックス変更のどちらを選ぶべきか判断する
• 1 本のクエリは速くなるが、書き込み性能やストレージを悪化させるような“改善”を避ける
• トレードオフをチームにわかりやすく共有する

こうした場面では、単なるプロンプトより sql-optimization-patterns のほうが実務で使いやすくなります。

このスキルが違う理由

最大の特徴は、パターンベースで最適化を進める設計にあります。単に「SQL を最適化しましょう」で終わらず、次のような実践的なデータベースエンジニアリング観点にエージェントを向かわせます。

• EXPLAIN と EXPLAIN ANALYZE を読む
• シーケンシャルスキャン、不適切な JOIN 選択、非効率なページネーションを見抜く
• 意図を持ってインデックス戦略を選ぶ
• N+1 アクセスパターンのような典型的アンチパターンに対応する

sql-optimization-patterns がハマるケース / ハマりにくいケース

向いているケース:

• 遅いことが確認できているクエリがある
• クエリプランをそのまま貼れる
• スキーマ、インデックス、行数規模の情報がある
• API レイテンシや DB 負荷に直結する性能改善をしたい

向いていない、または弱くなるケース:

• クエリ本文がない
• 実行計画がない
• SQL が見えないまま ORM レイヤーだけで議論している
• プロンプト内にないエンジン内部事情に強く依存するベンダー固有チューニングをしたい

sql-optimization-patterns スキルの使い方

sql-optimization-patterns の導入時に知っておくこと

このリポジトリでは、SKILL.md 内に専用インストーラは用意されていません。そのため、wshobson/agents リポジトリ向けの通常のスキル読み込みフローで導入し、そのうえでエージェントが sql-optimization-patterns という名前のスキルにアクセスできる状態にしてください。

環境で一般的な Skills フローを使っている場合は、まずリポジトリを追加し、その後 SQL 最適化分析を明確に依頼するタスク内でスキル名を指定して呼び出す、という流れが実用的です。

最初に読むべきファイル

まず確認すべきなのは次のファイルです。

• plugins/developer-essentials/skills/sql-optimization-patterns/SKILL.md

このスキルは自己完結型です。スキルフォルダ内に補助的な references/、rules/、スクリプト類はなく、実際に使えるガイダンスの大半はこの 1 ファイルにまとまっています。導入しやすい反面、入力の質が結果により強く影響します。

このスキルに必要な入力

sql-optimization-patterns で精度の高い出力を得るには、エージェントに次の情報を渡してください。

• SQL クエリ
• わかるならデータベースエンジン名とバージョン
• テーブルスキーマ、または関係するカラム
• 現在のインデックス
• 行数規模、またはおおよそのテーブルサイズ
• EXPLAIN または EXPLAIN ANALYZE の出力
• たとえば「P95 のエンドポイントレイテンシを下げたい」のような業務上の目標

プラン情報がなくてもパターンベースの提案はできますが、助言の信頼性は下がります。

最低限使えるプロンプト

実用的な sql-optimization-patterns usage プロンプトの例は次のとおりです。

Use the sql-optimization-patterns skill.

Database: PostgreSQL 15
Goal: reduce this query from 2.4s to under 200ms
Tables:
- users(id, email, created_at, status)
- orders(id, user_id, order_total, created_at)

Current indexes:
- users_pkey(id)
- orders_user_id_idx(user_id)

Query:
SELECT u.*, o.order_total
FROM users u
JOIN orders o ON u.id = o.user_id
WHERE u.created_at > NOW() - INTERVAL '30 days'
ORDER BY u.created_at DESC
LIMIT 100;

EXPLAIN ANALYZE:
[paste full plan]

Please identify likely bottlenecks, explain the plan, recommend query/index changes, and rank fixes by expected impact and risk.

曖昧な依頼を強い依頼に変えるコツ

弱い依頼:

Make this SQL faster.

強い依頼:

Use sql-optimization-patterns for Database Engineering.

I need:
1. plan interpretation
2. likely root cause
3. index recommendations with rationale
4. query rewrite options
5. tradeoffs for write amplification and storage
6. a safe rollout order

Engine: PostgreSQL 14
Traffic pattern: read-heavy API endpoint
Data scale: users 8M rows, orders 120M rows
Current problem: endpoint P95 is 1.8s, DB CPU spikes during peak
Query: [paste]
Plan: [paste]
Existing indexes: [paste]

後者のほうがうまく機能するのは、単なる一般論の羅列ではなく、運用上の優先順位まで含めて改善案を絞り込むだけの文脈をスキルに渡せているからです。

最も結果が出やすい実践ワークフロー

sql-optimization-patterns を活かすなら、次の流れが有効です。

1. 正確なクエリ全文と完全なプランを貼る
2. まず最大のコスト要因を平易な言葉で説明させる
3. 修正候補は 10 個ではなく 2〜3 個に絞って出させる
4. それぞれの期待効果とデメリットを確認する
5. 最も低リスクな変更から試す
6. EXPLAIN ANALYZE を再実行する
7. 変更前後を比較する

この進め方なら、推測ベースの調整ではなく、測定可能な結果に基づいて改善できます。

sql-optimization-patterns が特に得意なこと

元の内容で強く打ち出されているのは、次の領域です。

• EXPLAIN の解釈
• インデックス戦略
• JOIN パターンの分析
• 効率的なページネーション
• N+1 クエリの問題

つまり、単なる SQL 整形や見た目の改善ではなく、クエリ単位の最適化やスキーマ / インデックス判断に強いスキルです。

明示的に依頼するとよいこと

sql-optimization-patterns install や日々の活用で、より使える出力を得たいなら、エージェントに次のように明示してください。

• 「このプランで最大のボトルネックは何か」
• 「最初の一手は新しいインデックスか、クエリ書き換えか」
• 「どの scan / join タイプが効いていないのか」
• 「index-only にできる余地があるか」
• 「この変更は writes、vacuum、storage にどう影響するか」
• 「ロールアウト後に何を計測すべきか」

こうした聞き方をすると優先順位づけが必須になり、出力が“役立つ分析”になりやすく、ノイズの多い一般論になりにくくなります。

導入時によくある詰まりどころ

実際の障害は、インストールではなく証拠不足であることがほとんどです。

• プラン出力が一部しかない
• テーブルサイズ情報がない
• 現在のインデックス一覧がない
• ORM が生成した SQL だけ貼られていて業務文脈がない
• 実際の問題経路を診断せずに「ベストプラクティス」を求めている

クエリ本文しか渡さなければ、返ってくるのは広い一般論になりがちです。プラン、スキーマ、ワークロード文脈まで渡せば、このスキルは意思決定にかなり使えるものになります。

出力を安全に解釈するには

提案されたインデックスをすべて“無料で効く改善”だと考えないでください。sql-optimization-patterns guide として使うなら、少なくとも次を検証すべきです。

• filter や join predicate が、本当に提案インデックスの列順に合っているか
• そのクエリに十分な選択性があり、インデックスの恩恵を受けるか
• 単一カラムのインデックスを複数作るより、複合インデックスのほうが適切ではないか
• その修正は 1 本のクエリを助けても insert / update 性能を悪化させないか

このスキルは、すぐ検証できる仮説を出させる使い方で最も力を発揮します。

sql-optimization-patterns スキル FAQ

SQL をすでに理解していても、sql-optimization-patterns を入れる価値はある？

あります。とくに、プレッシャーのある状況でも一貫した最適化分析をしたいなら有効です。価値の中心は初歩的な SQL 知識ではなく、実行計画、scan type、JOIN、インデックス選択を軸にした構造化パターンにあります。

初心者でも使いやすい？

ある程度は使えますが、実例と一緒に使うのがおすすめです。クエリ本文と EXPLAIN ANALYZE の出力を見比べると、このスキルの意図がかなり理解しやすくなります。実行計画に不慣れなら、改善案を出させる前に、重要なノードをすべて平易な言葉で説明するよう依頼するとよいです。

普通の AI プロンプトより何が良い？

通常のプロンプトだと、汎用的なチューニングのコツに流れがちです。sql-optimization-patterns skill は、繰り返し使える最適化ワークフローと、実際のデータベースエンジニアリングで重要なシグナル、特にプラン解釈とインデックス戦略に焦点が当たっています。

PostgreSQL が必須？

いいえ。ただし、例は明らかに PostgreSQL 寄りです。MySQL、SQLite、SQL Server など別のエンジンを使う場合は、エンジン名と、それに対応する実行計画出力を一緒に渡してください。そうすればエージェント側で説明を合わせやすくなります。

sql-optimization-patterns を使わないほうがいいのはどんなとき？

主な問題が次のどれかなら、最初の選択肢にはしないほうがよいです。

• connection pooling
• クエリの証拠がないままの lock contention
• データベース外のインフラ飽和
• アプリケーションキャッシュ戦略の欠如
• 実際の SQL が見えなくなるほどの ORM の誤用

こうしたケースでは、後から補助的に役立つことはありますが、最初に使うツールではありません。

1 本の遅いクエリだけでなく、スキーマ設計にも役立つ？

はい。インデックス戦略やスケーラブルなクエリパターンまで扱うため、スキーマ判断の補助にも使えます。ただし最も効果が高いのは、アクセスパターン、想定フィルタ、JOIN、ソート順、データ量と結びつけて使うときです。

sql-optimization-patterns スキルを改善するには

sql-optimization-patterns に、より良い証拠を渡す

結果を最も早く良くする方法は、次の情報をきちんと渡すことです。

• 要約ではなく、完全なクエリ本文
• 冒頭数行だけでなく、完全なプラン出力
• 安全に出せるなら EXPLAIN ANALYZE の実測時間
• 現在のインデックス
• おおよその cardinality と行数
• read-heavy か write-heavy かというワークロード特性

証拠が良くなるほど、提案は信頼しやすくなり、関係の薄いインデックス提案も減ります。

優先順位つきで提案させる

このスキルは、修正案を次の観点で順位づけさせるとさらに実用的になります。

• 期待できるレイテンシ改善幅
• 実装コスト
• 運用リスク
• 書き込みオーバーヘッド
• 巻き戻しやすさ

こうした順位づけがあると、チームは「案を集める」だけでなく、実際に次のアクションを選びやすくなります。

トレードオフ分析を必ず入れる

よくある失敗は、読み取りは速くなるが、書き込みコストやインデックス肥大化を招く案をそのまま採用してしまうことです。sql-optimization-patterns の出力精度を上げるには、次のように聞いてください。

• 「このインデックスは inserts / updates にどんなコストを持つか？」
• 「冗長なインデックスを増やさないか？」
• 「さらにインデックスを足すより partitioning や rewrite のほうが適切ではないか？」
• 「ここでは offset pagination より keyset pagination のほうが良いか？」

変更前後を比較する反復にする

最初の提案を試したら、プランを取り直し、次の観点で比較させてください。

• 元のボトルネック
• 新しいボトルネック
• 何が改善したか
• まだ高コストな箇所はどこか
• 次の最適化を続ける価値がまだあるか

これが、単発の回答ではなく、継続的な最適化ループとしてこのスキルを使う最も確実な方法です。

よくある失敗パターンを警戒する

典型的なミスは次のとおりです。

• ANALYZE データなしで最適化する
• 選択性の低いフィルタにインデックスを追加する
• JOIN 順序や cardinality estimate を無視する
• 新しいプランを確認せずに SQL を書き換える
• 上流にある N+1 パターンを見落としたまま 1 本のクエリだけに集中する

こうしたミスは、変更案を出す前に前提条件を明示するようエージェントに求めることで減らせます。

出力品質を上げるプロンプトパターン

次のようなプロンプトが有効です。

Use the sql-optimization-patterns skill and do not give generic advice.
Base recommendations on the query plan provided.
For each proposed fix, explain:
1. why it should help
2. what plan node it targets
3. what tradeoff it introduces
4. how to validate it after deployment

この形式にすると、各提案を必ず根拠に結びつけて説明させやすくなります。

チーム導入を改善する

チームで使いたいなら、入力テンプレートを標準化するのが有効です。

• engine/version
• query
• schema
• indexes
• plan
• table sizes
• target latency
• workload notes

こうしておくと入力のばらつきが減り、sql-optimization-patterns for Database Engineering をインシデント対応やコードレビューでも再現性高く使えるようになります。