Claude CodeのAzure Cosmos DBプラグインで/cosmos-reviewを回す

Azure Cosmos DBを使うコードをClaude Codeにレビューさせるなら、azure-cosmos-db-assistant プラグインが近道です。パーティションキーの選び方やCosmosClientの使い方など、Cosmos DBで性能事故につながりやすい論点を、73のルールとして持っています。

インストール後の設定は要りません。READMEには、必須の環境変数も外部サービスも自動起動するバイナリも不要と書かれています。この記事では、入れたあとに何が使えるか、/azure-cosmos-db-assistant:cosmos-review の審査項目、Claude Code側に足しておくと効く設定を順に説明します。

入れると何が使えるようになるか

プラグインの中身は、スキル1つ、エージェント1つ、コマンド3つです。

ライブのデータベースにつなぐ機能は、この中に含まれません。つなぐ場合は別途MCP Toolkitのデプロイが必要で、後半で扱います。

インストールと名前空間

公式マーケットプレイスから入れます。

/plugin install azure-cosmos-db-assistant@claude-plugins-official
/reload-plugins

コマンドの名前空間は /azure-cosmos-db-assistant: です。READMEによると、以前のバージョンは /azure-cosmosdb:* を使っていました。古いブログや社内メモに旧名が残っていても、今は動きません。

プラグイン一般の入れ方や、導入範囲(ユーザー・プロジェクト)の選び方はClaude Codeのプラグインとマーケットプレイスの使い方にまとめています。プロジェクト単位で入れるとチーム全員に有効化されますが、各自のマシンへ取得するには claude plugin install が1回ずつ必要です。

/cosmos-reviewは何を見るのか

cosmos-review の手順書は、チェックリストを優先度順に並べています。レビューの順番が、そのまま重大度の序列です。

指摘1件ごとの出力形式も決まっています。

• 該当するルール名
• 重大度(CRITICAL / HIGH / MEDIUM / LOW)
• 現在のコードの挙動
• 問題点(RU・レイテンシ・スケーラビリティへの影響つき)
• 修正後のコード例

コマンドに引数を足すと、その文言が手順書の末尾に渡されます。レビュー範囲を絞るときに使えます。

/azure-cosmos-db-assistant:cosmos-review src/orders のリポジトリ層だけを対象に、CRITICALとHIGHの指摘に絞ってください

出力は「ルール名・重大度・現状・問題・修正案」の5項目で揃うので、指摘を修正タスクへ落とすのは機械的です。上の例のように重大度で絞れば、MEDIUM以下の細かい指摘に埋もれません。

モデリング相談はスキルとエージェントで回す

cosmos-review はコードが手元にあるときの入口です。コードを書く前の設計相談には、スキルとエージェントが働きます。READMEには、次のような質問例が載っています。

• 「このアプリのCosmos DBデータモデルをレビューして」
• 「マルチテナントSaaSなら、パーティションキーは何がよいか」
• 「このクエリをRUコストが下がるように最適化して」
• 「関連データは埋め込むか、参照にするか」

スキルの本文は、全ルールを一度に読み込まない作りです。質問のテーマに合うプレフィックスのファイルだけを開くよう指示しています。

SDK関連が19と最も多く、sdk-spring-data-annotations や sdk-newtonsoft-dependency のように、JavaとSpring Boot、.NETに固有のルールも含まれます。各ルールのファイルは、短い説明、悪い例、良い例、補足の順です。たとえば partition-high-cardinality は、ステータスや国のような値の少ない項目をキーにすると特定のパーティションに偏る、という例から始まります。

エージェントの定義には、進め方も書かれています。

• 推奨の理由(RUへの影響、レイテンシ、拡張性)を必ず添える
• 悪い例と良い例のコードを両方出す
• 利用者のSDK言語(.NET、Java、Python、Node.js)とフレームワークを考慮する
• データモデルやパーティションキーのような重大な論点を先に指摘する

つまり、質問に「言語」と「フレームワーク」を書いておくほど、ルールの当てはまりが良くなる設計です。

CLAUDE.mdに足すと、レビューが毎回同じ土俵に乗る

プラグインは汎用のルールを持っていますが、あなたのアプリの前提は知りません。次のような断片をCLAUDE.mdに置くと、cosmos-review もエージェントも同じ前提で話せます。以下は書き方の一例です。

## Cosmos DB の前提
- API は NoSQL。SDK は .NET、CosmosClient は DI でシングルトン登録している
- コンテナ orders のパーティションキーは /customerId(階層キーは未使用)
- 開発は Emulator、本番は 2 リージョン構成
- Cosmos DB を触る変更では、完了前に /azure-cosmos-db-assistant:cosmos-review を実行し、
  CRITICAL と HIGH の指摘が 0 件になるまで直す

最後の1行が要点です。レビューの実行を完了条件にしておけば、「書いて終わり」ではなく「書いて、審査して、直して、再審査する」という反復をClaude Codeが自分で回します。再審査では、前回の指摘が消えたかどうかを出力の重大度で確かめられます。

ライブDBにつなぐ任意のMCP接続

実データを見ながら相談したい場合は、cosmos-setup から任意のMCP Toolkit接続を設定します。この接続には、プラグインとは別にAzure側の作業が必要です。

.mcp.json の中身は、HTTP型のサーバー定義です。サーバー名は azure-cosmosdb で、URLとAuthorizationヘッダーを環境変数から組み立てます。トークン自体はファイルに書かれないので、リポジトリにコミットしても漏れません。

cp .mcp.example.json .mcp.json

接続できると、SETUP.mdの表にある7つのツールが使えます。list_databases、list_collections、get_approximate_schema、get_recent_documents、find_document_by_id、text_search、vector_search です。スキーマの推定は、ドキュメントをサンプリングしてトップレベルのプロパティを推し量る方式です。

権限は読み取りだけに絞る

表の説明はいずれも参照系の操作です。ツール名は mcp__<サーバー名>__<ツール名> の形で、サーバー名は .mcp.json のキー azure-cosmosdb です。次のように許可すると、毎回の確認なしで使えます。許可に書かないツールは、通常どおり確認が入ります。以下は設定の一例です。

{
  "permissions": {
    "allow": [
      "mcp__azure-cosmosdb__list_databases",
      "mcp__azure-cosmosdb__list_collections",
      "mcp__azure-cosmosdb__get_approximate_schema"
    ]
  }
}

get_recent_documents や find_document_by_id は実データの中身を返します。本番のデータを会話に取り込んでよいかは、組織のルールに合わせて決めます。

トークンは約1時間で切れる

SETUP.mdによると、JWTトークンは約1時間で期限が切れます。切れると401が返るので、az account get-access-token を取り直します。短寿命のトークンを毎回の手作業にしたくない場合は、Claude CodeのMCPでheadersHelperを使う手順が参考になります。

プロジェクトの .mcp.json に書いたサーバーは、初回に承認が要ります。承認前は claude mcp list で「Pending approval」と表示されるので、claude を対話モードで起動して承認します。

generate-skillsでルールを上流に追従させる

ルールの元は、AzureCosmosDB/cosmosdb-agent-kitリポジトリです。generate-skills を実行すると、GitHub APIでルールファイルの一覧を取り、各ファイルをダウンロードして上書きします。

手順書の最後は、次の3点の報告です。

• 追加されたルール
• 内容が変わったルール
• 上流で削除されたルール

あわせてSKILL.mdの索引とルール総数も更新します。ネットワークからGitHubへ取得に行くコマンドなので、社内の制限環境では動かないことがあります。

Azure周辺の記事との使い分け

Cosmos DBのコードをデプロイまで進めるなら、Azure側の記事と組み合わせます。インフラをBicepで書いて what-if で確かめる流れはClaude CodeでBicepを書きAzureにデプロイに、Functionsの開発権限の設計はClaude CodeでAzure Functionsを開発するにあります。別のデータベースのプラグインとの違いを見たいときは、AlloyDBプラグインの導入が、接続情報を渡す型の例になります。

まとめ

このプラグインの価値は、接続ではなく知識にあります。入れた直後から使えるのは、73のルールに基づく cosmos-review と設計相談で、実データの参照には別途のデプロイとトークン運用が要ります。

まず cosmos-review を重大度で絞って回し、CLAUDE.mdに前提と完了条件を書いておく使い方から始めると、MCP接続を後回しにしても効果が出ます。ライブ接続は、権限を読み取り系に絞り、トークンの期限切れを前提にした運用を決めてから足す順序です。