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

Claude Codeのプラグインはplugin.jsonのdependencies配列に他のプラグイン名を書くだけで、インストール時に依存先まで自動で入ります。バージョンを書かなければ、依存先はマーケットプレイスの最新リリースを追い続けます。上流の破壊的変更にも、そのまま巻き込まれます。

~2.1.0のようなバージョン範囲の書き方と自動更新の細部はプラグインの依存バージョンを固定するに、チーム全員へ配るバンドルの運用はプラグインをチームバンドルとして配布するにあります。ここでは宣言からタグ付け、無効化、pruneまでを、v2.1.287で実行した出力と並べて見ていきます。

範囲を書くと、依存先の更新は誰が決めるようになるか

シークレット管理のMCPサーバーを持つsecrets-vaultを、デプロイ支援のdeploy-kitが呼び出す構成で考えます。

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"のように名前だけ、または"name@marketplace"で別のマーケットプレイスを指す形です。範囲を付けるときはオブジェクトにし、フィールドはすべて文字列です。

2.0.0-beta.1のようなプレリリース版は、^2.0.0-0のようにプレリリースを許す接尾辞を範囲に付けない限り選ばれません。

範囲の書き損じは、書いた時点では気づきにくい形をしています。versionを"~2.x.y"にしたplugin.jsonをclaude plugin validate .にかけると、descriptionとauthorが無いという警告だけが出て、結果は✔ Validation passed with warningsです(v2.1.287)。不正な範囲は、インストールか読み込みの段階でhas an invalid version requirementとして表に出ます。

依存先の公開側はタグでリリースを区切る

範囲は、依存先をホストするリポジトリのgitタグと突き合わせて解決されます。タグが無い依存先に範囲を掛けても、解決できません。タグを打つ担当は、依存先のソースで分かれます。

• github / url / git-subdirソース: プラグイン自身のリポジトリなので、プラグインの作者が打つ
• ./plugins/secrets-vaultのような相対パス: マーケットプレイスのリポジトリなので、マーケットプレイスの管理者が打つ

タグ名は<プラグイン名>--v<バージョン>で固定です。名前を接頭辞にするため、1つのマーケットプレイスのリポジトリで複数のプラグインが別々の版数を持てます。

secrets-vaultのplugin.jsonが"version": "2.1.0"のgitリポジトリで--dry-runを実行すると、次の出力でした。

claude plugin tag --dry-run

Plugin:  secrets-vault
Version: 2.1.0 (from plugin.json)
Tag:     secrets-vault--v2.1.0
 
✔ Dry run — would create tag secrets-vault--v2.1.0 at HEAD in /path/to/secrets-vault
  git -C /path/to/secrets-vault tag -a secrets-vault--v2.1.0 -m "secrets-vault 2.1.0"
  git -C /path/to/secrets-vault push origin refs/tags/secrets-vault--v2.1.0

作られるのは注釈付きタグ(-a)で、メッセージの既定は<名前> <バージョン>です。-mで変えられ、%sがバージョンに置き換わります。リモートを設定していない作業ディレクトリでも、--dry-runはpush用のコマンドまで表示して終わりました。

タグを作る前に、コマンドは次の4点を検査します。

• プラグインの検証
• plugin.jsonとマーケットプレイスのエントリで、バージョンが一致していること(プラグインがマーケットプレイスのチェックアウト内にあるとき)
• プラグインのディレクトリ配下の作業ツリーがクリーンであること
• 同名のタグが無いこと

-f / --forceを付けると、作業ツリーの検査と同名タグの検査は飛ばせます。--pushが失敗してもタグはローカルに残り、コマンドはエラー終了します。セッション中は/plugin tag [path] [--push] [--dry-run] [--force]でも同じタグを作れます。git tag secrets-vault--v2.1.0を直接打っても等価ですが、2つのバージョンを自分でそろえる責任が付きます。

範囲を満たすタグが見つからないとき

{ "name": "secrets-vault", "version": "~2.1.0" }を持つプラグインを入れると、secrets-vault--vで始まるタグのうち~2.1.0を満たす最も高いものが取得されます。満たすタグが無いときの行き先は、依存先のソースで3通りに分かれます。

commandソースの依存先は、Claude Code自身がインストールしません。headersHelperを持つマーケットプレイスエントリの依存先も同様で、どちらも利用者が先に自分で入れます。

claude plugin listには、タグから解決した依存先のバージョンが12文字のコミット接尾辞付き(2.1.0-8713c5b11005の形)で出ます。範囲の検査に使われるのはplugin.jsonのversionではなくタグ側のバージョンなので、そのコミットのplugin.jsonが古い値のままでも検査は通ります。タグを別のコミットへ強制的に動かした場合、次のインストールは古いキャッシュを使い回さず、移動先の内容を取得します。

別のマーケットプレイスにある依存先を許可する

依存先が宣言元と別のマーケットプレイスにあると、既定では自動インストールされません。レビューしていない配布元のプラグインを、別のマーケットプレイスが黙って引き込む事態を防ぐためです。例外は、同じスコープで依存先をユーザーが既に有効にしている場合です。

許可するには、ユーザーがインストールするプラグインを直接ホストしているマーケットプレイス(ルート)の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" }
      ]
    }
  ]
}

許可が無いときの失敗の形は、依存を書いた場所で変わります。

どちらの場合も、claude plugin install audit-logger@acme-sharedを、deploy-kitと同じ--scopeで先に実行しておけば通ります。

複数のプラグインが同じ依存先に範囲を掛けたとき

同じ依存先に複数のプラグインが範囲を掛けていると、すべての範囲を満たす最も高いバージョンに解決されます。

自動更新も、マーケットプレイスの最新ではなく、全プラグインの範囲を満たす最高のタグを取りにいきます。範囲が重ならないと、依存先は今のバージョンのまま残り、/pluginのErrorsタブに制約元のプラグインを名指しした項目が出ます。範囲は重なるのに該当するタグが無いときは、マーケットプレイスの現行コピーを取得します。そのコピーのversionがどれかの範囲の外なら、更新は見送られます。範囲を掛けていたプラグインを最後の1本までアンインストールすると、依存先は固定を外れ、次の更新からマーケットプレイスのエントリに追従します。

インストールからpruneまで、実行結果で追う

ローカルのacme-toolsマーケットプレイスから、deploy-kit(audit-loggerとsecrets-vault ~2.1.0に依存)を入れた場合の出力です(空のHOME、v2.1.287)。audit-loggerのplugin.jsonにだけ"defaultEnabled": falseを書いています。

claude plugin install deploy-kit@acme-tools

✔ Successfully installed plugin: deploy-kit@acme-tools (scope: user) (+ 2 dependencies: audit-logger, secrets-vault)

依存先の2つは、同じ操作の中で入ります。ここで目を引くのがsettings.jsonです。

{
  "enabledPlugins": {
    "deploy-kit@acme-tools": true,
    "audit-logger@acme-tools": true,
    "secrets-vault@acme-tools": true
  }
}

依存先として引き込まれたプラグインには、defaultEnabled: falseでも明示的なtrueが書かれました。依存元が呼び出す前提のプラグインが、既定の無効のまま残って動かない事態は起きません。claude plugin listも3つともStatus: ✔ enabledでした。

依存されているプラグインは単独で無効にできない

secrets-vaultだけを無効にしようとすると、次の結果になります(終了コードは1、v2.1.287)。

✘ Failed to disable plugin "secrets-vault@acme-tools": 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 enableは、依存先も有効にします。次のいずれかのときは失敗します。

アンインストールしても依存先は残る

deploy-kitをアンインストールした直後の表示です。

✔ Successfully uninstalled plugin: deploy-kit (scope: user)
2 auto-installed dependencies no longer needed: audit-logger, secrets-vault. Run `claude plugin prune` to remove.

自動で入った依存先は、依存元を消しても残ります。片付けはclaude plugin pruneの役目で、まず--dry-runで対象を見られます。

claude plugin prune --dry-run

2 auto-installed plugins no longer needed at user scope:
  audit-logger@acme-tools (1.0.0)
  secrets-vault@acme-tools (2.1.0)
(dry run — nothing removed)

claude plugin prune -yを実行するとRemoved 2 auto-installed plugins: audit-logger, secrets-vaultと表示され、claude plugin listはNo plugins installed.に戻りました。対象が無いときは、Nothing to prune (no auto-installed plugins at user scope).と出て終了し、これはエラーではありません。

pruneの既定のスコープはuserで、--scope projectか--scope localで変えられます。標準入力か標準出力が端末でないときは、-yを付けない限り一覧とNot a TTYの案内を出すだけで、何も消しません。自分で明示的にインストールしたプラグインは、他のプラグインの依存先と同名でも対象になりません。アンインストールと同時に済ませるならclaude plugin uninstall deploy-kit --pruneです(非対話の環境では-yが必要)。

依存のエラーメッセージから原因を探す

エラーが出る場面は2つあります。インストール時の拒否はそのコマンドのエラーとして返り、読み込み時の問題はclaude plugin listと/pluginのErrorsタブに出て、該当プラグインは解決まで無効のままです。

プログラムから読むならclaude plugin list --jsonです。問題のあるプラグインにはerrorsと、各エラーのtypeを持つerrorDetailsが付きます。typeは、最初の2行がdependency-unsatisfied、3行目がdependency-version-unsatisfiedです。

依存元と依存先を同時に開発する

両方を--plugin-dirで読み込むと、依存先をマーケットプレイスから入れ直さずに試せます。

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

ローカルコピーが依存エントリを満たします。範囲の検査はローカルコピーには行われないので、plugin.jsonにversionが無くても動きます。2つのプラグインが同じ親フォルダに並んでいるなら、親フォルダを1回渡す形でも読み込めます。フォルダ自体がプラグインでなければ、.claude-plugin/plugin.jsonを持つ子フォルダが1つずつ読み込まれ、v2.1.265以降で使えます。

依存先をマーケットプレイスからインストールしていない間は、ローカルコピーが無効または不在になると、依存元の読み込みが止まります。

• ローカルコピーを自分で無効にした: 次のプラグイン読み込みで、依存元がis disabled — enable it or remove the dependencyで終わるエラーとともに無効になる。依存先は<name>@inlineと呼ばれ、--plugin-dirで読み込んだコピーを指す
• 依存先の--plugin-dirを付けずに起動した: 依存先が未インストールとして報告される。フラグを付け直すか、マーケットプレイスからインストールする

チーム向けに依存だけのプラグインをバンドルにする

nameとdependenciesだけを持つプラグインは、それ自体が有効なプラグインで、インストールすると依存先がすべて入ります。役割別のセットを1コマンドで配る形です。

{
  "name": "backend-standard",
  "version": "1.0.0",
  "description": "Standard plugin set for backend engineers",
  "dependencies": [
    "secrets-vault",
    "deploy-kit",
    { "name": "db-migrate", "version": "^3.0" },
    "oncall-runbook"
  ]
}

セットにプラグインを足すときは、依存を増やした新しいbackend-standardを公開します。マーケットプレイスの自動更新が既定で無効なら、利用者側の反映は2通りです。マーケットプレイスの自動更新を有効にするか、手動でclaude plugin update backend-standardを実行します。手動のときは、開いているセッションで/reload-pluginsも実行すると、増えた依存先が入ります。組織全員に配るなら、管理者がmanaged settingsのenabledPluginsにバンドルを加えます。

まとめ

作る側は、範囲を書く前に依存先のタグがあるかを確かめます。タグが無い依存先に範囲を掛けても、解決も固定も働きません。使う側は、依存元を外したあとにclaude plugin prune --dry-runで残りを見る習慣があれば、使われなくなった依存先を溜めずに済みます。

Claude Codeのプラグイン配布全体はClaude Codeプラグイン完全ガイドに、信頼できないソースを弾く仕組みは「untrusted source」エラーの対処にあります。