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" }
  ]
}

版を指定しないと、相手が新しい版を出した時点で、利用者の更新に合わせてそのまま切り替わります。相手が道具の名前を変えると、こちらのプラグインが全員の手元で動かなくなります。大事な相手には版の範囲を付ける のが安全です。

版の範囲の書き方

書き方意味(例)
~2.1.02.1.x の修正版だけ。2.2 には上がらない
^2.02.x の中なら上がる。3.0 には上がらない
>=1.41.4 以上なら何でも
=2.1.02.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プラグインが動かない時の直し方 も参考になります。

まとめ

出典

永上裕之

ユニコスクール株式会社 代表取締役。AIエージェント専門のスクール&コミュニティを運営しています。

この記事はAIを使って下書きし、著者が事実確認・加筆しています。ツールの機能や料金は変わることがあるため、最新の情報は各社の公式ページでご確認ください。

関連する記事