メインコンテンツへスキップ
プラグインは、plugin.json またはマーケットプレイスエントリにリストすることで、他のプラグインに依存できます。デフォルトでは、依存関係は最新の利用可能なバージョンを追跡するため、アップストリームリリースは警告なしにプラグインの依存関係を変更できます。バージョン制約を使用すると、移動を選択するまで、依存関係をテスト済みのバージョン範囲に保つことができます。 依存関係を宣言するプラグインをインストールすると、Claude Code は依存関係を自動的に解決してインストールし、インストール出力の最後に追加された依存関係をリストします。 このガイドは、plugin.json で依存関係を宣言するプラグイン作成者と、リリースにタグを付けるマーケットプレイス保守者向けです。依存関係を持つプラグインをインストールするには、プラグインの検出とインストール を参照してください。完全なマニフェストスキーマについては、プラグインリファレンス を参照してください。
依存関係のバージョン制約には、Claude Code v2.1.110 以降が必要です。

​
依存関係のバージョンを制約する理由

2 つのチームがプラグインを公開する内部マーケットプレイスを考えてみてください。プラットフォームチームは、シークレットバックエンドをラップする MCP サーバーである secrets-vault を保守しています。デプロイチームは、デプロイ中に認証情報を取得するために secrets-vault を呼び出す deploy-kit を保守しています。 deploy-kit は secrets-vault v2.1.0 に対してテストされています。バージョン制約がない場合、プラットフォームチームが MCP ツールの名前を変更するリリースにタグを付けると、次回の自動更新により、すべてのエンジニアの secrets-vault が新しいバージョンに移動し、deploy-kit が破損します。 バージョン制約を使用すると、deploy-kit は secrets-vault が ~2.1.0 範囲内にあることが必要であることを宣言します。deploy-kit がインストールされているエンジニアは、最高の一致する 2.1.x パッチに留まります。デプロイチームは、より広い制約を持つ新しい deploy-kit バージョンを公開することで、独自のスケジュールでアップグレードします。

​
バージョン制約を使用して依存関係を宣言する

プラグインの .claude-plugin/plugin.json の dependencies 配列に依存関係をリストします。各エントリは、プラグイン名またはバージョン制約を持つオブジェクトのいずれかです。 次のマニフェストは、1 つのバージョン指定なしの依存関係と 1 つの制約付き依存関係を宣言しています。
.claude-plugin/plugin.json
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
エントリは、上記の例の "audit-logger" のようにプラグイン名のみを含む単純な文字列にすることができます。これは、そのプラグインのマーケットプレイスが提供するバージョンに依存します。より詳細に制御するには、次のフィールドを持つオブジェクトを使用します。
フィールド型説明
namestringプラグイン名。宣言するプラグインと同じマーケットプレイス内で解決されます。必須。
versionstring~2.1.0、^2.0、>=1.4、または =2.1.0 などの semver 範囲。依存関係は、この範囲を満たす最高のタグ付きバージョンで取得されます。
marketplacestringname を解決する別のマーケットプレイス。クロスマーケットプレイス依存関係は、ターゲットマーケットプレイスがルートマーケットプレイスの marketplace.json の allowCrossMarketplaceDependenciesOn にリストされていない限り、ブロックされます。
version フィールドは、キャレット、チルダ、ハイフン、比較演算子範囲を含む、Node の semver パッケージでサポートされている任意の式を受け入れます。^2.0.0-0 のようなプレリリースサフィックスで範囲がオプトインしない限り、2.0.0-beta.1 などのプレリリースバージョンは除外されます。

​
別のマーケットプレイスからプラグインに依存する

デフォルトでは、Claude Code は、それを宣言するプラグインとは異なるマーケットプレイスに存在する依存関係の自動インストールを拒否します。これにより、1 つのマーケットプレイスが、確認していないソースからプラグインを静かにプルインするのを防ぎます。 これを許可するには、ルートマーケットプレイスの保守者が、ターゲットマーケットプレイス名を marketplace.json の allowCrossMarketplaceDependenciesOn に追加します。ルートマーケットプレイスは、ユーザーがインストールしているプラグインをホストするマーケットプレイスです。そのアローリストのみが参照されるため、信頼は中間マーケットプレイスを通じてチェーンされません。 次の marketplace.json は、deploy-kit が acme-shared からプラグインに依存することを許可しています。
.claude-plugin/marketplace.json
{
  "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 が依存関係の利用可能なバージョンを見つけるには、アップストリームプラグインのリリースが特定の命名規則を使用してタグ付けされている必要があります。 各リリースを {plugin-name}--v{version} としてタグ付けします。ここで、{version} はそのコミットの plugin.json の version フィールドと一致します。 
git tag secrets-vault--v2.1.0
git push origin secrets-vault--v2.1.0
プラグイン名プレフィックスにより、1 つのマーケットプレイスリポジトリが独立したバージョン行を持つ複数のプラグインをホストできます。--v セパレータは、完全なプラグイン名のプレフィックスマッチとして解析されるため、ハイフンを含むプラグイン名は正しく処理されます。 { "name": "secrets-vault", "version": "~2.1.0" } を宣言するプラグインをインストールすると、Claude Code はマーケットプレイスのタグをリストし、secrets-vault--v で始まるタグにフィルタリングし、~2.1.0 を満たす最高バージョンを取得します。一致するタグが存在しない場合、依存プラグインは利用可能なバージョンをリストするエラーで無効になります。
npm マーケットプレイスソースの場合、タグベースの解決は git バックアップソースにのみ適用されるため、制約はどのバージョンが取得されるかを制御しません。制約は依然としてロード時にチェックされ、インストールされたバージョンが満たさない場合、依存プラグインは dependency-version-unsatisfied で無効になります。

​
制約がどのように相互作用するか

複数のインストール済みプラグインが同じ依存関係を制約する場合、Claude Code はそれらの範囲を交差させ、依存関係をすべての範囲を満たす最高バージョンに解決します。下の表は、一般的な組み合わせがどのように解決されるかを示しています。
プラグイン A が必要プラグイン B が必要結果
^2.0>=2.12.1.0 以上の最高 2.x タグで 1 つのインストール。両方のプラグインが読み込まれます。
~2.1~3.0プラグイン B のインストールが range-conflict で失敗します。プラグイン A と依存関係は以前のままです。
=2.1.0なし依存関係は 2.1.0 に留まります。プラグイン A がインストールされている間、自動更新は新しいバージョンをスキップします。
自動更新は、更新を適用する前に、インストール済みプラグインのすべての範囲に対して各制約付き依存関係をチェックします。マーケットプレイスが依存関係を任意の範囲外のバージョンに移動する場合、更新はスキップされ、スキップメッセージは制約するプラグインに名前を付けます。 依存関係を制約する最後のプラグインをアンインストールすると、依存関係は保持されなくなり、次の更新でマーケットプレイスエントリの追跡を再開します。

​
依存関係エラーを解決する

依存関係の問題は、claude plugin list、/plugin インターフェイス、および /doctor に表示されます。影響を受けるプラグインは、エラーを解決するまで無効になります。最も一般的なエラーとその修正は以下にリストされています。
エラー意味解決方法
range-conflict依存関係のバージョン要件を組み合わせることができません。エラーメッセージは原因に名前を付けます。バージョンがすべての範囲を満たさない、範囲が有効な semver 構文ではない、または結合された範囲が複雑すぎて交差できません。競合するプラグインの 1 つをアンインストールまたは更新し、無効な version 文字列を修正し、長い || チェーンを簡略化するか、アップストリーム作成者に制約を広げるよう依頼してください。
dependency-version-unsatisfiedインストール済み依存関係のバージョンがこのプラグインの宣言された範囲外です。claude plugin install <dependency>@<marketplace> を実行して、すべての現在の制約に対して依存関係を再解決します。
no-matching-tag依存関係のリポジトリに、範囲を満たす {name}--v* タグがありません。アップストリームが上記の規則を使用してリリースにタグを付けていることを確認するか、範囲を緩和してください。
これらのエラーをプログラムで確認するには、claude plugin list --json を実行し、各プラグインの errors フィールドを読みます。

​
関連項目