Claude Codeプラグインの依存関係|版の指定と束ね方

この記事の要点
- プラグインの dependencies に、頼りにしているほかのプラグインを書ける。版の範囲(~2.1.0 など)も指定できる
- 依存先だけを並べたプラグインを作れば、部署向けの「一括セット」を1回の操作で入れられる
- 版の範囲を効かせるには、依存先の作り手が「名前--v版」の形でタグを付ける必要がある
活用例:部署ごとに、AI の開発ツールに入れる道具(プラグイン)の標準セットを配る
- 部署
- 開発基盤・情報システム
- 使うもの
- Claude Code のプラグインと社内のマーケットプレイス
- AIに任せる
- セットに入った道具を使った日々の作業
- 人が決める
- どの道具をセットに入れるか・どの版まで許すか・更新の時期
Claude Code のプラグインが増えてくると、「このプラグインは、あのプラグインの機能を使っている」という関係が生まれます。相手が更新されて名前が変わると、こちらが急に動かなくなることもあります。
この記事では、公式ドキュメント「Plugin dependencies」(2026年11月15日確認)にもとづいて、プラグインの 依存関係 の書き方と、版の範囲の決め方、チーム向けにまとめて配る使い方を解説します。プラグインそのものの基本は Claude Codeのプラグインとは? をご覧ください。
結論:plugin.json に「頼っている相手」と「許す版」を書く
依存関係は、プラグインの設定ファイル(.claude-plugin/plugin.json)の dependencies に書きます。 書き方は2通りです。
{
"name": "deploy-kit",
"version": "3.1.0",
"dependencies": [
"audit-logger",
{ "name": "secrets-vault", "version": "~2.1.0" }
]
}
- 名前だけ(audit-logger):相手のマーケットプレイスが出す最新の版について行く
- 名前と版の範囲(secrets-vault の ~2.1.0):試した範囲の版だけを使う
版を指定しないと、相手が新しい版を出した時点で、利用者の更新に合わせてそのまま切り替わります。相手が道具の名前を変えると、こちらのプラグインが全員の手元で動かなくなります。大事な相手には版の範囲を付ける のが安全です。
版の範囲の書き方
| 書き方 | 意味(例) |
|---|---|
| ~2.1.0 | 2.1.x の修正版だけ。2.2 には上がらない |
| ^2.0 | 2.x の中なら上がる。3.0 には上がらない |
| >=1.4 | 1.4 以上なら何でも |
| =2.1.0 | 2.1.0 に固定 |
ベータ版(2.0.0-beta.1 のような版)は、範囲の末尾に -0 を付けない限り対象になりません。新しい版に上げたいときは、自分で試してから範囲を広げた新しい版を出します。
部署向けの「一括セット」を作る
依存先だけを並べたプラグインは、それだけで立派なプラグインです。 プラグインに最低限必要なのは名前だけなので、次のようなセットを作れます。
{
"name": "backend-standard",
"version": "1.0.0",
"description": "バックエンド担当の標準セット",
"dependencies": [
"secrets-vault",
"deploy-kit",
{ "name": "db-migrate", "version": "^3.0" },
"oncall-runbook"
]
}
社員は claude plugin install backend-standard の1回で、セットの中身をまとめて入れられます。セットに道具を足したいときは、新しい版を出すだけです。全員に配るなら、管理者が管理設定の enabledPlugins に入れます。管理設定の配り方は Claude Code の管理設定とは? にまとめています。
別のマーケットプレイスの道具に頼るとき
初期設定では、別のマーケットプレイスの依存先は自動で入りません。 利用者が見ていない場所から勝手に入るのを防ぐためです。許すときは、入れようとしているプラグインがある側のマーケットプレイス(marketplace.json)の allowCrossMarketplaceDependenciesOn に、相手のマーケットプレイスの名前を書きます。
利用者がその依存先を先に自分で入れて有効にしていれば、この許可が無くても入ります。
手元で一緒に試す
自分のプラグインと依存先を同時に作っているときは、起動時に両方を読み込ませます。
claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin
手元の依存先は、版の範囲の確認を受けません。依存先の読み込みを外して起動すると、自分のプラグインは「入っていない」というエラーで止まります。
依存される側は「タグ」を付ける
版の範囲は、git のタグで判断されます。 依存される側のプラグインは、リリースごとに「プラグイン名--v版」の形(例 secrets-vault--v2.1.0)でタグを付けます。プラグインのフォルダで次を実行すると、検査をしてからタグを作って送ってくれます。
claude plugin tag --push
このコマンドは、設定ファイルとマーケットプレイスの版が一致しているか、未保存の変更が無いか、同じタグが無いかを確かめます。--dry-run で、作らずに計画だけ見ることもできます。
複数のプラグインが同じ相手に頼っているとき
全員の範囲を満たす、いちばん新しい版が選ばれます。 範囲が重ならない場合(片方が 2.1 系、もう片方が 3.0 系など)は、後から入れようとした方が conflicting version requirements という表示で止まります。どの版に決まったかは claude plugin list で確かめられます。
使われなくなった依存先は claude plugin prune で片付けられます。依存のエラーの読み方は Claude Codeプラグインが動かない時の直し方 も参考になります。
まとめ
- 依存関係は plugin.json の dependencies に書く。大事な相手には 版の範囲 を付ける
- 依存先を並べただけのプラグインで、部署向けの 一括セット が作れる
- 別のマーケットプレイスからは 許可リスト が無いと入らない
- 依存される側は 「名前--v版」のタグ を付けて範囲を効かせる
出典
この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。


