Claude Codeプラグイン依存関係 — バージョン制約とタグでリリースを固定する

Claude Codeのプラグインはplugin.jsonのdependencies配列に他のプラグイン名を書くだけで、インストール時に自動解決させられます。バージョンを指定しなければ常に最新を追いますが、上流の破壊的変更にそのまま巻き込まれます。本記事は依存関係の仕組み全体(宣言・自動解決・有効化と無効化の連動・クロスマーケットプレイス許可・エラー対処)をハブとして扱い、~2.1.0のようなセマンティックバージョニング範囲を使ったバージョン固定の詳細はプラグインの依存バージョンを固定する、チーム配布用のバンドル構成はプラグインをチームバンドルとして配布するにそれぞれ譲ります。

Claude Codeプラグインの依存関係とは

プラグインの依存関係とは、あるプラグインが動作するために別のプラグインのインストールを前提にする仕組みです。deploy-kitというデプロイ支援プラグインが、シークレット管理を担うsecrets-vaultというMCPサーバー入りプラグインを呼び出す構成を想定します。

バージョン指定なしで依存させると、secrets-vault側が自動更新されるたびにdeploy-kitが予告なく道連れになります。ツール名が変わる更新が入れば、その日からdeploy-kitは壊れます。バージョン制約はこの巻き込まれを止める仕組みで、deploy-kitが「secrets-vaultは~2.1.0の範囲で」と宣言すれば、エンジニアの手元では2.1.xの最新パッチに留まり続けます。デプロイチームは幅を広げた新バージョンを自分たちのタイミングで公開してから移行できます。

plugin.jsonで依存とバージョン制約を宣言する

依存はプラグイン自身の.claude-plugin/plugin.jsonにあるdependencies配列に書きます。

{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

配列の要素はプラグイン名だけの文字列でも、細かく制御するオブジェクトでも書けます。audit-loggerのようにバージョンを省略すると、そのマーケットプレイスが提供する版をそのまま使います。オブジェクト形式で使えるフィールドは3つです。

プレリリース版(2.0.0-beta.1など)は、範囲側で^2.0.0-0のようにプレリリースを許可する接尾辞を付けない限り対象から外れます。

依存が宣言されたプラグインをインストールすると、Claude Codeは依存先を自動で解決してインストールします。例外はcommandソースやheadersHelperを持つマーケットプレイスエントリで、これらはユーザーが自分で先にインストールする必要があります。以降は/reload-pluginsの実行、依存元プラグインのマーケットプレイスの自動更新、claude plugin installの再実行、claude plugin marketplace addのいずれかのタイミングで、未導入の依存が同じルールに従って追加インストールされます。

チーム配布用にプラグインをバンドルする

依存関係の仕組みは、単体のツール連携だけでなく「役割ごとに整えたプラグインセットを1つのインストールで配る」用途にも使えます。名前とdependencies配列だけを持つプラグインを作れば、それ自体がバンドルになり、利用者は1回のインストールで複数の依存プラグインをまとめて導入できます。バンドルの設計・更新運用・組織全体への配布(managed settingsのenabledPlugins)はプラグインをチームバンドルとして配布するで扱います。

他のマーケットプレイスにあるプラグインに依存させる

Claude Codeは既定で、宣言元と別のマーケットプレイスにある依存を自動インストールしません。あるマーケットプレイスが、レビューしていない別の配布元のプラグインを黙って引き込むのを防ぐためです。

許可するには、依存を引き込む側(ルートマーケットプレイス)のmarketplace.jsonで、allowCrossMarketplaceDependenciesOnに許可先の名前を追加します。ルートマーケットプレイスとは、ユーザーがインストールしようとしているプラグインを直接ホストしているマーケットプレイスのことで、信頼関係は中間のマーケットプレイスを経由して連鎖しません。

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "allowCrossMarketplaceDependenciesOn": ["acme-shared"],
  "plugins": [
    {
      "name": "deploy-kit",
      "source": "./deploy-kit",
      "dependencies": [
        { "name": "audit-logger", "marketplace": "acme-shared" }
      ]
    }
  ]
}

このフィールドが無い、または対象のマーケットプレイス名を含んでいない場合、インストールはcross-marketplaceエラーで失敗し、設定すべきフィールド名がエラーメッセージに表示されます。許可を出さなくても、ユーザーが依存先を先に自分でインストールしておけば制約自体は満たされます。

リリースをタグ付けしてバージョン解決させる

バージョン制約を機能させるには、依存先プラグインのリリースがgitタグとして打たれている必要があります。Claude Codeはバージョン範囲を、依存先をホストするリポジトリのgitタグと突き合わせて解決します。github / url / git-subdirソースならプラグイン自身のリポジトリ、マーケットプレイスが相対パスで参照しているプラグインならマーケットプレイスのリポジトリが対象です。

タグの命名規則は{プラグイン名}--v{バージョン}で固定されています。プラグインのディレクトリで次のコマンドを実行します。

claude plugin tag --push

claude plugin tagはプラグインのマニフェストとマーケットプレイスエントリからタグ名を導き出します。実行前にプラグインの内容を検証し、plugin.jsonとマーケットプレイスエントリのバージョンが一致しているかを確認し、プラグインディレクトリ配下がクリーンな作業ツリーであることを求め、同名タグが既に存在すれば拒否します。

• --pushを付けるとタグをoriginリモートへpushします(--remoteで別のリモート名を指定可能)
• pushに失敗してもタグ自体はローカルに作成済みで、コマンドはエラー終了します
• --pushありで成功するとCreated tag secrets-vault--v2.1.0とPushed to originが表示されます
• --pushなしの場合、実行すべきgit pushコマンドが代わりに表示されます
• --dry-runを付けると、実際にタグを作らずに何をタグ付けするかだけを表示します

git tag secrets-vault--v2.1.0を直接叩いても等価です。ただしplugin.jsonとマーケットプレイスエントリのバージョンを自分で同期させる責任が生じます。プラグイン名を接頭辞にすることで、1つのマーケットプレイスリポジトリで複数プラグインが独立したバージョン系列を持てます。

{ "name": "secrets-vault", "version": "~2.1.0" }という依存を持つプラグインをインストールするとき、Claude Codeはsecrets-vaultをホストするリポジトリのタグを一覧し、secrets-vault--vで始まるものに絞り込み、~2.1.0を満たす最も高いバージョンを取得します。条件を満たすタグが1つも無ければ、インストールはDependency "secrets-vault@acme-tools" has no git tag satisfying ~2.1.0のエラーで失敗し、依存先とマーケットプレイス名の両方が表示されます。相対パス参照のプラグインで一致するタグが無い場合は、マーケットプレイスの現行コピーがそのままインストールされ、制約はプラグインの読み込み時にチェックされます。

解決されたタグのセマンティックバージョンはplugin.jsonのversionとは別に記録されます。そのため、あるコミット時点のplugin.jsonが古い値のままでも、制約チェックには実際に取得したタグの値が使われます。タグ解決でインストールしたキャッシュディレクトリ名には12文字のコミットSHAが付くため、メンテナーがタグを別のコミットへ強制的に動かしても、次回インストールでは古い内容を使い回さず新しいキャッシュディレクトリが作られます。

npm / archive / commandソースの依存では、この制約はどのバージョンを取得するかを制御しません(タグベースの解決はgit系ソースにのみ適用されます)。制約は読み込み時にチェックされ、インストール済みのバージョンが範囲を満たさなければdependency-version-unsatisfiedでそのプラグインが無効化されます。commandソースの場合、Claude Codeは依存先のplugin.jsonのバージョンを見てコンテンツハッシュの接尾辞は無視するため、バージョンを設定していない依存先はどんな制約も満たせません。制約を掛ける前にバージョンを設定しておく必要があります。

依存条件が競合したときの解決ルール

複数のインストール済みプラグインが同じ依存先に制約を掛けている場合、Claude Codeはそれぞれの範囲を交差させ、すべてを満たす最も高いバージョンに解決します(交差できなければrange-conflictで片方のインストールが失敗します)。自動更新もマーケットプレイスの最新版ではなくこの交差範囲内の最高タグを追うため、制約付きの依存先も許容範囲の中で更新を受け続けられます。制約元プラグインをすべてアンインストールすれば固定は解けます。具体的な組み合わせ例と自動更新の詳しい挙動はプラグインの依存バージョンを固定するにまとめています。

依存関係がある状態での有効化・無効化

有効化・無効化はマーケットプレイスからインストールしたプラグインが対象です(--plugin-dirで読み込んだローカルコピーの扱いは後述の「ローカル開発中の依存プラグインの扱い」を参照)。

プラグインを有効化すると、依存先も同じスコープで一緒に有効化されます。依存先がさらに別の依存を持っていれば、それも連鎖して有効化されます。成功メッセージには、指定したプラグインと一緒に有効化された依存先が並んで表示されます。依存先のplugin.jsonがdefaultEnabled: falseを指定していても、Claude Codeはその依存先に明示的なtrueを書き込むため既定値は上書きされます。インストール時に依存先が引き込まれる場合も同様にtrueで入ります。

依存先を有効化できない場合、コマンドは失敗し、何が原因でどう直せるかを表示します。

無効化は逆方向で制約されます。有効な別のプラグインがまだ依存している状態でプラグインを無効化しようとすると、Claude Codeは拒否し、依存している側の名前を挙げます。たとえばdeploy-kitがsecrets-vaultに依存している状態でsecrets-vaultだけを無効化しようとすると、次のようなエラーになります。

secrets-vault is still required by deploy-kit. Disable that plugin first, or
disable everything together: claude plugin disable deploy-kit@acme-tools && claude plugin disable secrets-vault@acme-tools

エラーメッセージに表示される連結コマンドをそのままコピーすれば、正しい順序で一括無効化できます。

依存関係エラーの読み方と直し方

依存関係のエラーはclaude plugin listと/plugin画面に、以下の表のコードそのものではなく説明的なメッセージとして表示されます。該当プラグインは解決するまで無効化されます。

プログラムから確認したいときはclaude plugin list --jsonを使います。問題があるプラグインにはerrorsフィールドが並び、正常に読み込めたプラグインではこのフィールド自体が省略されます。

ローカル開発中の依存プラグインの扱い

依存元と依存先を同時に開発しているときは、両方を--plugin-dirで読み込みます。

claude --plugin-dir ./my-dependency --plugin-dir ./my-plugin

依存先のローカルコピーは、依存エントリがマーケットプレイス名を指定していても、その宣言を満たします。マーケットプレイスから依存先をインストールし直す必要はありません。ローカルコピーに対してはバージョン制約をチェックしないため、ローカルのplugin.jsonにバージョンが無くても構いません。

依存先をそのマーケットプレイスからインストールしていない状態で、ローカルコピーが無くなると読み込みが止まります。挙動は2パターンに分かれます。

• 自分でローカルコピーを無効化した場合: 次回のプラグイン読み込み時に依存元も無効化されます。マーケットプレイス名を指定した依存エントリならDependency "<name>@inline" is disabled — enable it or remove the dependency、ベア名のエントリならその名前で依存が報告されます。<name>@inlineは--plugin-dirと--plugin-urlで読み込んだすべてのプラグインを指す識別子です
• 依存先の--plugin-dirフラグを付けずにセッションを開始した場合: 依存先が未インストールとして報告されます。フラグを付け直すか、依存先をマーケットプレイスからインストールします

使われなくなった依存関係を掃除する

自動インストールされた依存プラグインは、それを導入した元のプラグインをアンインストールしたあともディスクに残ります。依存元を再インストールしたり、依存先を単独で使い続けたい場合に備えるためです。片付けたいときはclaude plugin pruneを実行します。

claude plugin prune

このコマンドは、もう必要とするプラグインが無くなった自動インストール済みの依存先を一覧し、確認プロンプトのあとで削除します。対象が無ければNothing to pruneと理由が表示され、これはエラーではなく新規インストール直後によく出る正常な結果です。

既定ではuserスコープを対象に、削除前に確認を求めます。--scope projectか--scope localで別スコープを指定でき、--dry-runは削除せず対象を一覧するだけ、-yは確認プロンプトを省略します。標準入力・標準出力が端末でない場合、-yを付けない限り一覧だけ表示して何も削除しません。

アンインストールと同時に片付けたいときは--pruneを付けます。

claude plugin uninstall deploy-kit --prune

指定したプラグインを削除したあと、それによって孤立した自動インストール済みの依存先を探して削除します。確認の挙動はclaude plugin prune単体と同じです。自分で明示的にインストールしたプラグインは、たとえ他のプラグインの依存先と同じ名前でも、pruneの対象にはなりません。

よくある質問

バージョンを指定しない依存はどう解決されますか

そのマーケットプレイスが提供している現行バージョンをそのまま使います。上流が更新するたびに一緒に更新されるため、意図的に追従させたい依存だけバージョンを省略します。

プレリリースバージョンは依存先として選ばれますか

既定では選ばれません。2.0.0-beta.1のようなプレリリースを対象にしたい場合は、範囲側に^2.0.0-0のようなプレリリース許可の接尾辞を付ける必要があります。

タグを打たずに依存先を配布できますか

制約なしの依存(バージョンを指定しないエントリ)であればタグは不要です。ただしバージョン範囲を1つでも指定した瞬間、依存先のリポジトリに命名規則どおりのgitタグが無いと解決できません。

依存先を無効化するとどうなりますか

依存元プラグインがまだ有効な状態で依存先を無効化しようとすると、Claude Codeは拒否し、依存している側の名前を挙げます。エラーメッセージには両方を正しい順序で無効化する連結コマンドが表示されるので、それをそのままコピーして実行できます。

npmソースのプラグインにもバージョン制約は使えますか

使えますが挙動が異なります。タグベースの解決はgit系ソースのみが対象で、npm / archive / commandソースでは制約がどのバージョンを取得するかを左右しません。制約は読み込み時にチェックされ、範囲外ならdependency-version-unsatisfiedで無効化されます。

まとめ

Claude Codeのプラグイン依存関係は、plugin.jsonのdependenciesにバージョン範囲を書くだけで上流の破壊的変更から手元の環境を守れる仕組みです。バンドル配布・クロスマーケットプレイス許可・タグ付けの3つがそろって初めて、宣言した範囲どおりにバージョンが解決されます。プラグインを自作・配布する担当者はタグ付け運用を、複数チームのプラグインを束ねる立場ならバンドルとallowCrossMarketplaceDependenciesOnの設定を優先して押さえておくと運用が安定します。配布そのものの基本はClaude Codeプラグイン完全ガイド、信頼できないソースを弾く仕組みは「untrusted source」エラーの対処で扱っています。