> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# プラグイン依存関係のバージョンを制約する

> プラグイン依存関係のバージョン制約を宣言して、キュレーションされたプラグインセットを 1 つのインストールの背後にバンドルします。

プラグインは、`plugin.json` またはマーケットプレイスエントリにリストすることで、他のプラグインに依存できます。デフォルトでは、依存関係は最新の利用可能なバージョンを追跡するため、アップストリームリリースは警告なしにプラグインの依存関係を変更できます。バージョン制約を使用すると、移動を選択するまで、依存関係をテスト済みのバージョン範囲に保つことができます。

依存関係を宣言するプラグインをインストールすると、Claude Code は依存関係を自動的に解決してインストールし、インストール出力の最後に追加された依存関係をリストします。依存関係が後で見つからなくなった場合、`/reload-plugins` とバックグラウンドプラグイン自動更新により、設定済みマーケットプレイスにそのマーケットプレイスが既にある場合は、それを再インストールします。依存プラグインで `claude plugin install` を再実行するか、`claude plugin marketplace add` でマーケットプレイスを追加することでも、未解決の依存関係が解決されます。追加していないマーケットプレイスからの依存関係は未解決のままになります。

このガイドは、`plugin.json` で依存関係を宣言するプラグイン作成者と、リリースにタグを付けるマーケットプレイス保守者向けです。依存関係を持つプラグインをインストールするには、[プラグインの検出とインストール](/docs/ja/discover-plugins) を参照してください。完全なマニフェストスキーマについては、[プラグインリファレンス](/docs/ja/plugins-reference) を参照してください。

<h2 id="why-constrain-dependency-versions">
  依存関係のバージョンを制約する理由
</h2>

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` バージョンを公開することで、独自のスケジュールでアップグレードします。

<h2 id="declare-a-dependency-with-a-version-constraint">
  バージョン制約を使用して依存関係を宣言する
</h2>

プラグインの `.claude-plugin/plugin.json` の `dependencies` 配列に依存関係をリストします。各エントリは、プラグイン名またはバージョン制約を持つオブジェクトのいずれかです。

次のマニフェストは、1 つのバージョン指定なしの依存関係と 1 つの制約付き依存関係を宣言しています。

```json .claude-plugin/plugin.json theme={null}
{
  "name": "deploy-kit",
  "version": "3.1.0",
  "dependencies": [
    "audit-logger",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}
```

エントリは、上記の例の `"audit-logger"` のようにプラグイン名のみを含む単純な文字列にすることができます。これは、そのプラグインのマーケットプレイスが提供するバージョンに依存します。より詳細に制御するには、次のフィールドを持つオブジェクトを使用します。

| フィールド         | 型      | 説明                                                                                                                                                                                                       |
| :------------ | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | プラグイン名。宣言するプラグインと同じマーケットプレイス内で解決されます。必須。                                                                                                                                                                 |
| `version`     | string | `~2.1.0`、`^2.0`、`>=1.4`、または `=2.1.0` などの [semver 範囲](https://github.com/npm/node-semver#ranges)。依存関係は、この範囲を満たす最高のタグ付きバージョンで取得されます。                                                                       |
| `marketplace` | string | `name` を解決する別のマーケットプレイス。クロスマーケットプレイス依存関係は、ターゲットマーケットプレイスがルートマーケットプレイスの `marketplace.json` の [`allowCrossMarketplaceDependenciesOn`](#depend-on-a-plugin-from-another-marketplace) にリストされていない限り、ブロックされます。 |

`version` フィールドは、キャレット、チルダ、ハイフン、比較演算子範囲を含む、Node の `semver` パッケージでサポートされている任意の式を受け入れます。`^2.0.0-0` のようなプレリリースサフィックスで範囲がオプトインしない限り、`2.0.0-beta.1` などのプレリリースバージョンは除外されます。

<h2 id="bundle-plugins-for-a-team">
  チームのプラグインをバンドルする
</h2>

必須の `name` の他に、プラグインマニフェストは `dependencies` 配列のみで構成することができます。これをインストールすると、すべての依存関係がプルされます。これにより、キュレーションされたプラグインセットを 1 つのインストールの背後にパッケージ化する方法になります。

例えば、プラットフォームチームは内部マーケットプレイスでロール固有のバンドルを公開できるため、エンジニアは各ツールを個別にインストールする代わりに、1 つの `claude plugin install` を実行できます。

```json .claude-plugin/plugin.json theme={null}
{
  "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` をインストールすると、4 つの依存関係すべてが解決され、インストールされます。

後で標準セットにツールを追加するには、追加の依存関係を含む新しい `backend-standard` バージョンを公開します。非 Anthropic マーケットプレイスではデフォルトで自動更新がオフになっているため、エンジニアは次の 2 つの方法のいずれかで新しいバージョンを取得します。

* `/plugin` でマーケットプレイスの自動更新を有効にします。次の自動更新によってバンドルが新しいバージョンに移動し、追加される依存関係がインストールされます。
* `claude plugin update backend-standard` を実行してから、`/reload-plugins` を実行して、新しく追加された依存関係をインストールします。

組織全体にバンドルをロールアウトするには、バンドルプラグインを [管理設定](/docs/ja/settings#enabledplugins) の `enabledPlugins` に追加します。

<h2 id="depend-on-a-plugin-from-another-marketplace">
  別のマーケットプレイスからプラグインに依存する
</h2>

デフォルトでは、Claude Code は、それを宣言するプラグインとは異なるマーケットプレイスに存在する依存関係の自動インストールを拒否します。これにより、1 つのマーケットプレイスが、確認していないソースからプラグインを静かにプルインするのを防ぎます。

これを許可するには、ルートマーケットプレイスの保守者が、ターゲットマーケットプレイス名を `marketplace.json` の `allowCrossMarketplaceDependenciesOn` に追加します。ルートマーケットプレイスは、ユーザーがインストールしているプラグインをホストするマーケットプレイスです。そのアローリストのみが参照されるため、信頼は中間マーケットプレイスを通じてチェーンされません。

次の `marketplace.json` は、`deploy-kit` が `acme-shared` からプラグインに依存することを許可しています。

```json .claude-plugin/marketplace.json theme={null}
{
  "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` エラーで失敗し、設定するフィールドに名前を付けます。ユーザーは依然として依存関係を手動で最初にインストールできます。これにより、アローリストを変更することなく制約が満たされます。

<h2 id="tag-plugin-releases-for-version-resolution">
  バージョン解決のためのタグプラグインリリース
</h2>

バージョン制約は、マーケットプレイスリポジトリの git タグに対して解決されます。Claude Code が依存関係の利用可能なバージョンを見つけるには、アップストリームプラグインのリリースが特定の命名規則を使用してタグ付けされている必要があります。

各リリースを `{plugin-name}--v{version}` としてタグ付けします。ここで、`{version}` はそのコミットの `plugin.json` の `version` フィールドと一致します。プラグインディレクトリから、以下を実行します。

```bash theme={null}
claude plugin tag --push
```

`claude plugin tag` コマンドは、プラグインのマニフェストとそれを囲むマーケットプレイスエントリからタグ名を導出します。タグを作成する前に、プラグインの内容を検証し、`plugin.json` とマーケットプレイスエントリがバージョンについて一致していることを確認し、プラグインディレクトリの下でクリーンな作業ツリーを要求し、タグが既に存在する場合は拒否します。`--dry-run` を追加して、タグを作成せずにタグ付けされるものを確認します。`plugin.json` とマーケットプレイスエントリを自分で同期させておけば、`git tag secrets-vault--v2.1.0` を直接実行することと同等です。

プラグイン名プレフィックスにより、1 つのマーケットプレイスリポジトリが独立したバージョン行を持つ複数のプラグインをホストできます。`--v` セパレータは、完全なプラグイン名のプレフィックスマッチとして解析されるため、ハイフンを含むプラグイン名は正しく処理されます。

`{ "name": "secrets-vault", "version": "~2.1.0" }` を宣言するプラグインをインストールすると、Claude Code はマーケットプレイスのタグをリストし、`secrets-vault--v` で始まるタグにフィルタリングし、`~2.1.0` を満たす最高バージョンを取得します。一致するタグが存在しない場合、依存プラグインは利用可能なバージョンをリストするエラーで無効になります。

ローカルフォルダパスとして追加されたマーケットプレイスは、フォルダが git リポジトリである場合、同じ方法でタグを解決します。これには Claude Code v2.1.196 以降が必要です。2 つのケースでは、Claude Code は依存関係をフォルダの現在の内容からインストールします。

* 以前のバージョンはローカルフォルダマーケットプレイスからタグを読み取らないため、制約付き依存関係はそのコピーが範囲を満たす場合にのみロードされます。
* git リポジトリではないローカルフォルダには、バージョンに関係なくタグがありません。

解決されたタグの semver は `plugin.json` の `version` とは別に記録されるため、制約チェックは `plugin.json` がそのコミットで古い値を持っていても、実際に取得されたタグを使用します。タグ解決インストールのキャッシュディレクトリ名には 12 文字のコミット SHA サフィックスが含まれるため、メンテナーがタグを別のコミットに強制移動した場合、次のインストールは古いコンテンツを再利用する代わりに新しいキャッシュディレクトリを取得します。

<Note>
  `npm` マーケットプレイスソースの場合、タグベースの解決は git バックアップソースにのみ適用されるため、制約はどのバージョンが取得されるかを制御しません。制約は依然としてロード時にチェックされ、インストールされたバージョンが満たさない場合、依存プラグインは `dependency-version-unsatisfied` で無効になります。
</Note>

<h2 id="how-constraints-interact">
  制約がどのように相互作用するか
</h2>

複数のインストール済みプラグインが同じ依存関係を制約する場合、Claude Code はそれらの範囲を交差させ、依存関係をすべての範囲を満たす最高バージョンに解決します。下の表は、一般的な組み合わせがどのように解決されるかを示しています。

| プラグイン A が必要 | プラグイン B が必要 | 結果                                                                |
| :---------- | :---------- | :---------------------------------------------------------------- |
| `^2.0`      | `>=2.1`     | `2.1.0` 以上の最高 `2.x` タグで 1 つのインストール。両方のプラグインが読み込まれます。              |
| `~2.1`      | `~3.0`      | プラグイン B のインストールが `range-conflict` で失敗します。プラグイン A と依存関係は以前のままです。   |
| `=2.1.0`    | なし          | 依存関係は `2.1.0` に留まります。プラグイン A がインストールされている間、自動更新は新しいバージョンをスキップします。 |

自動更新は、制約付き依存関係を、マーケットプレイスの最新バージョンではなく、インストール済みプラグインのすべての範囲を満たす最高 git タグで取得するため、依存関係は許可された範囲内で更新を受け続けます。すべての範囲を満たすタグがない場合、自動更新はその依存関係をスキップし、スキップを `/plugin` エラータブに表示し、制約するプラグインに名前を付けます。

依存関係を制約する最後のプラグインをアンインストールすると、依存関係は保持されなくなり、次の更新でマーケットプレイスエントリの追跡を再開します。

<h2 id="enable-or-disable-a-plugin-with-dependencies">
  依存関係を持つプラグインを有効または無効にする
</h2>

プラグインを有効にすると、それが依存するプラグインも有効になり、別の有効なプラグインがまだそれを必要としている場合、プラグインを無効にすることはブロックされます。両方の動作には Claude Code v2.1.143 以降が必要です。以前のバージョンは、名前付きプラグインのみを有効または無効にし、次のロード時に `dependency-unsatisfied` エラーを表示します。

プラグインを有効にすると、Claude Code は同じスコープでその依存関係も有効にします。依存関係が独自の依存関係を持つ場合、Claude Code はそれらも有効にします。成功メッセージは、名前を付けたプラグインと一緒に有効になったものをリストします。依存関係を有効にできない場合、コマンドは拒否され、何がブロックしているか、およびそれを修正する方法が表示されます。

| 条件                                            | 結果                                                            |
| :-------------------------------------------- | :------------------------------------------------------------ |
| 依存関係がインストールされていない                             | 有効化が失敗し、各欠落している依存関係の `claude plugin install` コマンドを出力します。      |
| 依存関係が組織のプラグインポリシーによってブロックされている                | 有効化が失敗し、ブロックされた依存関係に名前を付けます。                                  |
| 依存関係が、ターゲットスコープより優先度の高いスコープで `false` に設定されている | 有効化が失敗します。そのスコープで依存関係を有効にするか、`--scope` を渡してそこに書き込みます。         |
| すべての依存関係がインストールされ、許可されている                     | 有効化が成功し、プラグインと、ターゲットスコープでまだ有効になっていない各依存関係に対して `true` を書き込みます。 |

これは、依存関係がマニフェストで [`defaultEnabled: false`](/docs/ja/plugins-reference#default-enablement) を設定している場合でも当てはまります。Claude Code はそれに対して明示的な `true` を書き込むためです。同じことがインストール時にも適用されます。アクティブなプラグインを満たすために取得された依存関係は、独自のデフォルトに関係なく `true` でインストールされます。

プラグインを無効にすると、別の有効なプラグインがまだそれに依存している場合、Claude Code は拒否します。エラーはそれに依存するプラグインに名前を付け、正しい順序でそれらを無効にする連鎖コマンドを提供します。

たとえば、`deploy-kit` が `secrets-vault` に依存している場合、`secrets-vault` だけを無効にすると、次のような出力で失敗します。

```text theme={null}
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
```

エラーから連鎖コマンドをコピーして、1 つのステップで完全なセットを無効にします。

<h2 id="remove-orphaned-auto-installed-dependencies">
  孤立した自動インストール依存関係を削除する
</h2>

自動インストール依存関係は、それらをインストールしたプラグインがアンインストールされた後もディスク上に留まります。これは、依存プラグインを再インストールしたい場合や、依存関係を直接使用し続けたい場合に備えてです。それらをクリーンアップするには、`claude plugin prune` を実行して、インストール済みプラグインがもう必要としない自動インストール依存関係をリストし、確認プロンプトの後に削除します。これには Claude Code v2.1.121 以降が必要です。

```bash theme={null}
claude plugin prune
```

デフォルトでは、prune はユーザースコープで動作します。別のスコープをターゲットにするには、`--scope project` または `--scope local` を使用します。`--dry-run` を渡して、何が削除されるかをリストし、何も変更しません。`-y` を渡して確認プロンプトをスキップします。stdin または stdout がターミナルでない場合、prune は孤立したものをリストして終了し、`-y` が渡されない限り削除しません。

アンインストールの一部として prune するには、`claude plugin uninstall` に `--prune` を渡します。名前付きプラグインを削除した後、Claude Code は自動インストール依存関係をスキャンして、現在孤立しているものを削除します。自分でインストールしたプラグインは決して prune されません。別のプラグインの `dependencies` 配列を通じて自動的にインストールされたものだけです。

たとえば、`deploy-kit` をアンインストールし、それが残す依存関係をクリーンアップするには、以下を実行します。

```bash theme={null}
claude plugin uninstall deploy-kit --prune
```

<h2 id="resolve-dependency-errors">
  依存関係エラーを解決する
</h2>

依存関係の問題は、`claude plugin list` と `/plugin` インターフェイスに表示されます。Claude Code は、エラーを解決するまで影響を受けたプラグインを無効にします。以下の表は、最も一般的なエラーとその解決方法を示しています。

| エラー                              | 意味                                                                                                               | 解決方法                                                                                                                                                                               |
| :------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dependency-unsatisfied`         | 宣言された依存関係がインストールされていないか、インストールされていますが無効になっています。                                                                  | エラーメッセージに表示されている `claude plugin install` コマンドを実行してください。依存関係のマーケットプレイスがまだ設定されていない場合は、`claude plugin marketplace add` で追加すると、Claude Code が依存関係を自動的に解決します。依存関係が無効になっている場合は、有効にしてください。 |
| `range-conflict`                 | 依存関係のバージョン要件を組み合わせることができません。エラーメッセージは原因に名前を付けます。バージョンがすべての範囲を満たさない、範囲が有効な semver 構文ではない、または結合された範囲が複雑すぎて交差できません。 | 競合するプラグインの 1 つをアンインストールまたは更新し、無効な `version` 文字列を修正し、長い `\|\|` チェーンを簡略化するか、アップストリーム作成者に制約を広げるよう依頼してください。                                                                            |
| `dependency-version-unsatisfied` | インストール済み依存関係のバージョンがこのプラグインの宣言された範囲外です。                                                                           | `claude plugin install <dependency>@<marketplace>` を実行して、すべての現在の制約に対して依存関係を再解決します。                                                                                                 |
| `no-matching-tag`                | 依存関係のリポジトリに、範囲を満たす `{name}--v*` タグがありません。                                                                        | アップストリームが上記の規則を使用してリリースにタグを付けていることを確認するか、範囲を緩和してください。                                                                                                                              |

これらのエラーをプログラムで確認するには、`claude plugin list --json` を実行し、各プラグインの `errors` フィールドを読みます。

<h2 id="see-also">
  関連項目
</h2>

* [プラグインの作成](/docs/ja/plugins): スキル、エージェント、フックを使用してプラグインを構築します
* [プラグインマーケットプレイスの作成と配布](/docs/ja/plugin-marketplaces): チーム向けのプラグインをホストします
* [プラグインリファレンス](/docs/ja/plugins-reference#plugin-manifest-schema): 完全な `plugin.json` スキーマ
* [バージョン管理](/docs/ja/plugins-reference#version-management): プラグイン独自のバージョンがどのように解決され、キャッシュキーとして使用されるか