AIエージェントに「本番品質」のSQLを実装させる：TiDB Skillsのご紹介

※このブログは2026年02月03日に公開された英語ブログ「Teaching AI Agents to Speak “Production” SQL: Introducing TiDB Skills」の拙訳です。

AIコーディングエージェントは「自分のローカル環境では動作する」コードを生成するのが得意です。しかしデータベースエンジニアなら誰もが知っているように、ローカルのDockerコンテナで動作するクエリと、高い同時実行性が求められる本番環境で耐えうるクエリとの間には、大きな隔たりがあります。

私たちは、エージェントが一般的なチュートリアルをもとにSQLを生成した際に、同じ問題が繰り返し発生するのを目にしてきました：

• 一見「問題なさそう」に見えるクエリが、実際には実行計画が不適切で、スケール時に破綻するケース (しかも誰もEXPLAINを確認していない)。
• ITLS検証設定が不完全なことによる、安全でない接続。
• アプリケーション側がInnoDBと同様の動作を前提としている一方で、分散データベースエンジンが異なる動作をしていることによるトランザクションの不具合。
• MySQLには存在する機能でも分散システムでは動作が異なる互換性の落とし穴。

データベース障害の大半は構文ミスではなく「コンテキスト」の欠如が原因です。

そこで私たちは、TiDB Skillsをリリースしました。これは、Claude Code、Cursor、CodexといったAIエージェントがコード生成時に参照できるコンテキストを集めたGitHubリポジトリです。これにより、TiDB Cloudにおいて、より安全で本番運用に耐えうるSQLを生成できるようになります。

TiDB Skillsの仕組み

私たちは、こうした運用上の「落とし穴」を、AIが参照できる小さなスキルフォルダとしてまとめました。これにより、エージェントはSQLを書いているとき、移行作業をレビューしているとき、あるいは本番環境の問題をトラブルシューティングしているときに、適切なルールを確実に参照できるようになります。

リポジトリは、エージェントが必要なコンテキストだけを取得できる構造になっており、プロンプトウィンドウを効率的に保てるように設計されています：

ワークフローは、シンプルでユーザーからは見えない形になるよう設計されています：

1. 選択：エージェントは関連するスキルフォルダを選択します (例：SQLを生成する際はskills/tidb-sql)。
2. 取得：特定のタスクに必要なリファレンスだけを取り込みます (例：複数ステップの書き込み処理を扱う場合はtransactions.md)。
3. 適用：「ベストエフォート」の推測に頼るのではなく、コード生成時にそのガイダンスを制約条件として適用します。

Deep Dive：「汎用」と「本番環境」の間にあるギャップ

この仕組みが生み出す違いを見るために、汎用的なSQL生成が本番環境で失敗する2つの具体例を見てみましょう。

1. トランザクションの落とし穴

tidb-sqlスキルがない場合は、エージェントは単にBEGINと記述するだけで、特に意識することなく「悲観的ロックが使われる前提」で進めてしまいます。スキルがある場合は、どのモード (悲観的 / 楽観的) を使うのかを明示的に選ぶ必要があり、エージェントはその選択を意識的に行わなければなりません。

ルール (transactions.mdより)：「競合が頻繁に発生する場合は悲観的 (pessimistic) トランザクションを優先すること。書き込み同士の競合が少なく、かつアプリケーション側でコミット失敗を適切に処理できる場合は楽観的 (optimistic) トランザクションを検討すること。」

エージェントの出力：このルールを取り込むことで、エージェントは楽観的 (Optimistic) モードを選択した場合、アプリケーションレベルでのリトライループも併せて生成する必要があることを理解します。そして、COMMITを必ず成功する処理として扱わなくなります。

-- The agent now explicitly declares the mode [cite: 64]
BEGIN PESSIMISTIC;
-- ... DML ...
COMMIT;

2. プライマリキーのホットスポット

MySQLのチュートリアルで学習したエージェントは、AUTO_INCREMENTを好んで使います。単一ノードのデータベースであれば、これは問題ありません。しかし分散システムでは、連番で増加するIDによってすべての書き込みが単一のリージョン (いわゆる「ホットスポット」) に集中し、書き込み性能が大きく低下してしまいます。

ルール (hotspots.mdより)：「ホットスポット回避／ID戦略 (中〜高)：AUTO_RANDOMをいつ、どのように使用するか。」

エージェントの出力：汎用的なデフォルトに従うのではなく、エージェントは大規模環境での正しさを考慮して最適化されたスキーマを生成します:

CREATE TABLE users (
  -- Agent switches to AUTO_RANDOM for distribution 
  id BIGINT PRIMARY KEY AUTO_RANDOM, 
  email VARCHAR(255) NOT NULL,
  ...
);

ツールキット：含まれる内容

このガイダンスは、中核となるSQLスキルと、それを補完する接続およびORMスキルを中心に構成されています。以下は、私たちがエージェントに注入しているコンテキストの内訳です。

1. 安全性と正確性 (最重要)

これらのスキルは、データ損失や接続障害を防ぐことに重点を置いています：

• TLSおよび接続の安全性：不安定または安全でない接続を防ぐため、厳格なSSL検証要件やクライアント設定パターンを強制します。
• トランザクションと並行処理：これは最もよくある落とし穴のひとつです。このスキルは、楽観的トランザクションと悲観的トランザクションの違い、コミット失敗の処理方法、そしてセッションレベルとグローバルレベルの設定をいつ使い分けるべきかを明確にします。

2. Pパフォーマンスとスケール (重要)

エージェントはしばしば、分散環境でのパフォーマンスを考慮せずにスキーマを書いてしまいます。これらのスキルは、スケーラブルなパターンへと導きます：

• ホットスポット回避 / ID戦略：Tプライマリキーの書き込みホットスポットを避けるために、AUTO_INCREMENTの代わりにAUTO_RANDOMをいつ、どのように使うべきかをエージェントに教えます。
• クエリプランと診断：パフォーマンスを検証するためにEXPLAINやEXPLAIN ANALYZEをどのように使用するか、また統計情報をいつ更新すべきかをエージェントに指示します。
• 互換性の落とし穴：「MySQLでは動作するが、TiDBでは問題を引き起こす」一般的な構文や書き方にフラグを立てて注意を促します。

3. 高度な機能

特定のDDLや可用性チェックを必要とする高度な機能についてもカバーしています：

• ベクトル検索：VECTOR型、ベクトル関数、ベクトルインデックスのDDLに関する正しいパターンを提供します。
• リカバリ手順：FLASHBACK TABLEやFLASHBACK DATABASEを含む、フラッシュバックベースのリカバリワークフローの構文を示します。
• 全文検索：TiDBにおける全文検索の実装に特有のSQLパターンや、可用性に関する注意点 (落とし穴) を示します。

4. アプリケーション統合 (ドライバ & ORM)

アプリケーションとの統合に向けては、コネクションプーリング、安全なパラメータ化、TLS設定をカバーする専用のドライバスキルを提供しています。これにより「デフォルトのNode.jsドライバ」を使用する場合でも、本番環境で安全に利用できることを保証します。

• Node.js：標準的なプーリングおよびTLS対応には
  tidbx-javascript-mysql2、レガシーコードベース向けにはtidbx-javascript-mysqljsを使用します。
• TypeScript / ORM：型付きSQL、スキーマ管理、そして正しいDATABASE_URLのTLSパラメータ設定のためにtidbx-kyselyおよびtidbx-prismaを使用します。
• Serverless / Edge：TCP接続が利用できないエッジランタイム環境向けに、HTTPベースの接続方法を示すtidbx-serverless-driverのガイダンスを提供します。
• Python：CRUD、ベクトル検索、ハイブリッド検索統合のためのpytidbのガイダンスを提供します。

エージェントのインストール

リポジトリはpingcap/agent-rulesで利用可能です。これらのスキルは、Vercelのスキルパッケージを使って、直接エージェントの設定にインストールできます。

ターミナルで以下のコマンドを実行してください。実行すると、使用したいスキルや利用中のエージェント (Claude Code、Codex、Cursorなど) を選択する必要があります：

npx skills add pingcap/agent-rules

インストールが完了すると、エージェントは適切なタイミングで自動的に正しいスキルを選択します。通常、「どのスキルを使うか」を意識する必要はありません。

よくある質問

Q：これは標準的なMySQLでも使えますか？A：TLSの安全性、EXPLAINチェック、安全なパラメータ化など、多くのスキルはどのMySQL環境でも共通のベストプラクティスです。しかし、AUTO_RANDOMや特定のトランザクションモードのような分散向け機能はTiDB向けに最適化されており、単一ノードのMySQLでは調整が必要な場合があります。

Q：これらのスキルを手動で起動する必要はありますか？A：いいえ。skillsCLIをインストールすれば、Claude CodeやCursorのようなエージェントは、例えば「TiDB用のスキーマを書いてほしい」と要求したときに自動でコンテキストを検出し、コード生成前に関連するルールを取得します。

Q：これはコードレビューの代わりになりますか？A：いいえ。TiDBスキルは、コード生成中に動作する「ガードレール」やリンターのようなものと考えてください。TLSの漏れやホットスポットのような典型的な「新人エンジニアのミス」を早期に検出しますが、本番環境への変更は常に人間によるレビューを経るべきです。

まとめ

これらのスキルは、コードレビューやセキュリティポリシーの代わりになるものではありません。しかし、典型的なミスを防ぐ「ガードレール」として機能します。AIエージェントに不足していたコンテキストを提供することで、早期に警告を出し、より安全なデフォルト設定を生成し、本番環境でも問題なく動作するSQLを作成できるようになります。

もしMySQL／TiDBの未対応の注意点やハマりどころを見つけた場合は、IssueやPRを作成してください。そうすることで、将来のエージェント実行時にデフォルトで正しく処理されるようになります。