Claude Codeプラグインのリリースチャネルとバージョン解決

プラグインのバージョンはどう決まるか

Claude Codeは、プラグインの「バージョン」をキャッシュのキーとして扱います。/plugin update や自動更新が動くたび、この値を計算し直します。手元のキャッシュと一致すれば、更新はスキップされます。バージョンの決まり方を理解していないとどうなるか。更新したつもりのプラグインが古いまま残ったり、意図せず全員に更新が配られたりする事故が起きます。

社内マーケットプレイスを運用していると、よくある問い合わせが2つあります。「プラグインを更新したのに /plugin update が最新ですと返す」。逆に「触っていないのに全員へ更新が飛んだ」というものです。原因の大半は、後述する優先順位のどの段階でバージョンが決まっているかを把握していないことにあります。

command ソース以外のプラグインでは、次の優先順位でバージョンが解決されます。上から順に値が見つかった時点で確定し、下の候補は無視されます。

command ソースだけは別枠です。コマンドが出力した内容の12文字ハッシュを常に使い、plugin.json に version があれば <version>-<hash> の形で連結します。マーケットプレイスエントリ側の version は無視されるため、コマンドの出力が変わればバージョン文字列を変えていなくても新バージョン扱いになります。

3通りのバージョン管理方法を使い分ける

command 以外のソースでは、実質的に3つの運用パターンがあります。プラグインの性格に応じてどれを選ぶかが、更新の効き方を左右します。

明示バージョンを使う場合は、セマンティックバージョニング(MAJOR.MINOR.PATCH)に従うのが基本です。破壊的変更でMAJOR、機能追加でMINOR、バグ修正でPATCHを上げます。変更内容は CHANGELOG.md に残しておきましょう。利用者側が更新のたびに差分を追いやすくなります。

どの方式を選ぶかは「誰が、いつ更新を受け取るべきか」で決まります。社内で数人が使う開発中のツールなら、コミットSHA版でこまめに更新を届けるほうが運用の手間が省けます。逆に複数チームが依存する基盤プラグインは、明示バージョンが向いています。意図したタイミングだけ更新を届けられ、依存側の破壊を防ぎやすくなるからです。

version を plugin.json とマーケットプレイスエントリの両方に書かないのも実務上重要な注意点です。Claude Codeは警告なしに plugin.json 側の値を優先するため、マーケットプレイス側で新しいバージョンを設定しても、plugin.json の値が古いままだと更新が届きません。バージョンは片方だけで管理します。

リリースチャネルでstable/latestを使い分ける

社内プラグインを「安定版だけ使いたいチーム」と「最新を試したいチーム」に分けて配りたい場合があります。Claude Code自体に専用のチャネル機能があるわけではありません。同じリポジトリの異なるref・SHAを指す2つのマーケットプレイスを用意するという設計で実現します。

{
  "name": "stable-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": { "source": "github", "repo": "acme-corp/code-formatter", "ref": "stable" }
    }
  ]
}

{
  "name": "latest-tools",
  "plugins": [
    {
      "name": "code-formatter",
      "source": { "source": "github", "repo": "acme-corp/code-formatter", "ref": "latest" }
    }
  ]
}

同じプラグイン名 code-formatter を、stable ブランチを指す stable-tools マーケットプレイスと、latest ブランチを指す latest-tools マーケットプレイスの両方に登録しておきます。あとはユーザーグループごとに、見せるマーケットプレイスを切り替えるだけです。グループへの割り当ては、次のいずれかで行います。

• グループごとに別々のエンドポイント管理設定(managed settingsファイルやMDMプロファイル)を配布する
• グループごとに1つ、Claude appsゲートウェイ(gateway)のポリシーを定義する(ゲートウェイは条件に最初に一致したポリシーを適用するため、各ユーザーが自分のグループのポリシーに届く順序で並べる必要がある)

管理コンソールのサーバー管理設定は組織内の全ユーザーに一律適用されます。グループ別の出し分けには使えません。エンドポイント管理設定かゲートウェイポリシーのどちらかを選ぶ必要があります。

エンドポイント管理設定とゲートウェイポリシー、どちらを選ぶか

2つの配布方法は、細部の挙動が異なります。選ぶ前に押さえておきたい注意点がそれぞれにあります。

エンドポイント管理設定(managed settingsファイルやMDMプロファイル)を使う場合、グループ別のファイルと組織全体のファイルが同じ端末に両方存在するケースが起こり得ます。どちらが優先されるかはmanaged settingsの合成ルールに従います。グループ別ファイルを配る前に、その端末が組織共通のファイルも同時に受け取る構成になっていないかを確認しておく必要があります。

ゲートウェイポリシーを使う場合の注意点は、もう一段具体的です。ゲートウェイは、あるユーザーに最初にマッチしたポリシーだけを適用します。各グループのポリシーは、そのグループのユーザーが確実にたどり着ける順序で並べておく必要があります。加えて見落としやすい点があります。グループ用ポリシーの extraKnownMarketplaces は、全体向けのcatch-allポリシーが持つマップをマージせず置き換えるのです。つまり、catch-allポリシーで登録していた別のマーケットプレイス(たとえば社内共通ツール用の1本)があっても、グループ用ポリシー側にそのエントリを書いていなければ、そのグループのユーザーからは見えなくなります。チャネル用のマーケットプレイスだけでなく、グループが必要とするマーケットプレイスは毎回グループ側のポリシーに全部書き出しましょう。それが安全な運用です。

チャネルごとに異なるバージョンへ解決されることが前提条件です。明示バージョンを使うなら、固定先のrefごとに plugin.json の version を変えます。version を省略しているなら、コミットSHAの違いがそのままチャネルの違いになります。2つのrefが同じバージョン文字列に解決されてしまうとどうなるか。Claude Codeは両者を同一とみなし、更新をスキップします。

グループへの実際の割り当て例

stableグループには次の設定を配ります。

{
  "extraKnownMarketplaces": {
    "stable-tools": {
      "source": { "source": "github", "repo": "acme-corp/stable-tools" }
    }
  }
}

早期アクセスグループには latest-tools を配ります。

{
  "extraKnownMarketplaces": {
    "latest-tools": {
      "source": { "source": "github", "repo": "acme-corp/latest-tools" }
    }
  }
}

extraKnownMarketplaces はmanaged settingsの一部として配布する設定項目です。managed settingsそのものの構造や配布経路はClaude Code組織管理ガイドで扱っています。

この設計はどこまで有効か

リリースチャネルの実体は「同じプラグイン名を複数のマーケットプレイスに登録し、見せる相手を設定で分ける」だけです。Claude Code側にstable/latestという概念が組み込まれているわけではありません。この単純さには利点と限界の両方があります。

利点は、既存のgit運用(ブランチやタグでの管理)をそのまま流用できることです。新しい概念を覚える必要がなく、ref を変えるだけでチャネルを増やせます。3本目のチャネル(たとえば canary)を足すのも、3つ目のマーケットプレイスとrefを用意するだけで済みます。

限界は、チャネルの数だけマーケットプレイス定義とグループ割り当て設定が増えることです。数チームの社内ツールなら管理は容易です。しかし数十のプラグインを複数チャネルで配る規模になると、marketplace.json とmanaged settingsの整合を保つ運用コストが無視できなくなります。プラグインの依存関係を特定バージョン範囲に固定する仕組みも、別途用意されています。チャネル運用と組み合わせる場面では、両方を意識してください。

よくある質問

リリースチャネルはClaude Code本体の専用機能ですか

いいえ。stable / latestのような概念自体がClaude Codeに組み込まれているわけではなく、同じプラグインを異なるref・SHAで指す複数のマーケットプレイスを用意し、ユーザーグループごとに見せる設定を切り替える、という設計パターンです。名前も stable-tools / latest-tools のように任意に付けられます。

3つ目のチャネルを増やすにはどうすればよいですか

3つ目のref(たとえば canary)を指す3つ目のマーケットプレイスを用意し、対応するユーザーグループにそのマーケットプレイスを割り当てるだけです。チャネル数に技術的な上限はありません。増やすたびに、マーケットプレイス定義とグループ割り当てが1組ずつ増えていきます。

2つのrefが同じバージョンに解決されてしまったらどうなりますか

Claude Codeはその2つを同一バージョンとみなします。更新は検知されません。明示バージョンを使っているなら、固定先のref・SHAごとに plugin.json の version を必ず変える必要があります。version を省略してコミットSHA運用にしている場合はどうか。参照先のコミットさえ異なっていれば、自動的に区別されます。

まとめ

Claude Codeプラグインのバージョンは、plugin.json → マーケットプレイスエントリ → gitのコミットSHA(またはアーカイブのダイジェスト)→ unknown の順で解決されます。version は片方にだけ書きます。コミットSHA運用と明示バージョン運用、どちらが自分のプラグインに合うかを先に決めましょう。この優先順位さえ押さえておけば、「更新が届かない」という問い合わせの原因を、ソースコードを追わずに設定ファイルだけで切り分けられるようになります。

リリースチャネルは、同じプラグインを異なるref・SHAで指す複数のマーケットプレイスを用意し、managed settingsやゲートウェイポリシーでユーザーグループごとに見せる先を切り替えることで実現します。マーケットプレイス自体の作り方はClaude Codeプラグイン完全ガイドで扱っています。配布前の検証はマーケットプレイスのstrict modeとvalidateもあわせて確認してください。公開までの流れが一通りつかめます。