# Claude Code プラグインの配布とマーケットプレイス運用
プラグインを書くことと、組織に安全に配布することはまったく別の仕事である。開発が終わったあとに待っているのは、バージョン管理・検証・署名・権限設計という地味で重要な作業だ。本稿では我々が社内マーケットプレイスを立ち上げて分かった実践的な勘所をまとめる。
marketplace.json の役割
マーケットプレイスの実体は、`marketplace.json` という単純な索引ファイルである。ここに含まれるのはプラグインのメタデータの一覧で、ソースリポジトリ、バージョン、説明、タグなどを持つ。重要なのは、マーケットプレイス自体は配布物を持たず、各プラグインのソースへの参照だけを管理するという点だ。
```json { "name": "kga-internal", "owner": { "name": "KGA IT" }, "plugins": [ { "name": "kga-review", "source": "./plugins/kga-review" }, { "name": "kga-deploy", "source": "github:kga-it/[email protected]" } ] } ```
社内プラグインはモノレポ内の相対パス、外部依存は GitHub 参照という分け方で運用している。これにより検証のサイクルが短く保てる。
配布チャネルの三層構造
我々は配布を三層に分けている。開発用の `dev` チャネル、社内共有の `internal` チャネル、そして広く公開する `public` チャネルだ。`/plugin marketplace add` でユーザー側が好きなチャネルを購読する形をとる。dev は main ブランチの HEAD を指し、internal は社内レビュー済みのタグ、public は署名済みのリリースのみを含む。
この分離により、壊れかけのプラグインが全社に波及する事故を防げる。開発者は自分のマシンで dev を購読し、安定して動くようになってから internal に昇格させる。
GitHub リポジトリをマーケットプレイスにする
最も手軽なのは、GitHub リポジトリそのものをマーケットプレイスとして使う方法である。リポジトリのルートに `.claude-plugin/marketplace.json` を置くだけで、ユーザーは次のコマンドで購読できる。
```bash /plugin marketplace add kga-it/plugins /plugin install kga-review@kga-it ```
社内 GitLab や GitHub Enterprise でも同じ仕組みが使えるため、既存の認可基盤に相乗りできるのが利点だ。
署名と改ざん検知
公開チャネルに昇格させる前に、署名を必ず付与する。我々のパイプラインでは、リリース時に `cosign` で各プラグインディレクトリのハッシュに署名し、`marketplace.json` の対応エントリに署名ファイルのパスを記録する。インストール時にクライアント側で検証するスクリプトを hook として挿入し、署名が合わない場合は読み込みを中止する。
検証失敗時の挙動は厳格にする必要がある。警告だけでは形骸化するため、install を完全に中止し、理由を明示するのが鉄則だ。
バージョン管理の実務
プラグインのバージョンは semver に厳密に従う。hook の契約変更や commands の削除は必ず major バージョンの更新を伴い、新規追加は minor、バグ修正のみ patch とする。ユーザーには `/plugin update` による自動更新を推奨しているが、major 更新は明示的な確認を入れる設計にしている。
依存するプラグインがある場合は、`plugin.json` の `dependencies` に記述する。マーケットプレイスが依存解決を行い、不足があればインストール前に警告する。
運用で学んだこと
一年運用して得た教訓は三つある。第一に、マーケットプレイスの README を手厚く書くこと。プラグインの一覧だけでは使い方が伝わらず、利用率が上がらない。第二に、更新通知を別チャネルで出すこと。インストールしたまま放置されるプラグインは脆弱性の温床になる。第三に、削除ポリシーを最初に決めること。廃止されたプラグインをどう扱うかを文書化しておかないと、後で互換性問題が噴出する。
まとめ
配布は開発の終点ではなく、別の工程の始まりである。marketplace.json の単純さを武器に、チャネル分離と署名を組み合わせれば、小さなチームでも堅牢な配布基盤を維持できる。