plan-viewer — OSSプラグイン化

2026年2月27日 23:30 更新（Codexレビュー反映済み）

📌 一言でいうと

plan-viewerを誰でもインストールできる公開プラグインにする

🎯 なぜこれが必要なのか

plan-viewer は今、自分のパソコンの設定ファイルのあちこちにバラバラに置いてある。具体的には、スキル定義（AIへの指示書）、自動チェックの仕組み、サーバーの3つが別々の場所に散らばっている状態。

このままだと自分しか使えない。Claude Code のプラグイン（拡張機能パッケージ）として1つのフォルダにまとめれば、他のユーザーも使えるようになる。

設計方針は「今必要なものだけ作る」（YAGNI）と「とにかくシンプルに」（KISS）。余計な機能は後回しにして、まず動くものを公開することを優先する。

インストール方法（公式仕様に基づく）

v1.0（今回）: GitHub に公開 → claude --plugin-dir でローカル利用。これは公式にサポートされた「単一セッション向け」の方法。

v1.1以降: Marketplace（プラグインの配布ストア）に登録して、claude plugin install plan-viewer で永続インストール可能にする。

Codex（GPT-5.3）によるレビュー結果

プランをCodexにレビューさせた結果、8件の指摘を受けた。うち5件を採用、3件を却下した：

採用した指摘:

移行時に「バックアップ → 並行稼働 → 段階削除」のロールバック設計を追加
自動チェック設定（フック）の完全な定義例を明記
OS判定を uname ベースに変更（よりポータブル）
セットアップ処理をスクリプトに分離（コマンド文書は呼び出しのみ）
スクリプトの実行権限設定を明記

却下した指摘:

Marketplace必須 → v1.0では不要。--plugin-dir は公式ドキュメントに明記あり
--plugin-dir が非推奨 → 誤り。公式に「単一セッション向け」として記載あり
使い方LP（docs/）が過剰 → リポジトリ作成時のルールで必須と定められている

🏗️ 何をするのか

Before / After

Before（今）

設定ファイルが3箇所に散らばっている
自分のMacでしか動かない
他の人が使うにはファイルを手動コピー
スキル定義が800行の1ファイル

After（完成後）

1つのフォルダに全て集約
macOSでもLinuxでも動く
コマンド一発でインストール可能
必要な部分だけ読む効率的な構造

フォルダ構成

新しく作るリポジトリ（プロジェクトフォルダ）の中身はこうなる：

.claude-plugin/plugin.json — マニフェスト（プラグインの名刺。名前・バージョン・中身の一覧を記載）

skills/ — AIへの指示書。HTML生成ルール、デザイン定義など

hooks/ — 自動チェックの仕組み。「plan完了前にHTMLを作りましたか？」と確認するフック

scripts/ — スマホからアクセスするためのサーバー

commands/ — /plan-viewer:setup や /plan-viewer:serve で使えるコマンド

assets/ — アイコンやPWA設定ファイル

📊 ステップ

1 リポジトリ作成 + マニフェスト

新しいフォルダを作り、プラグインの「名刺」となる plugin.json を置く。ライセンスはMIT（誰でも自由に使ってOK）。

2 スキル定義を分割

今は800行もある1つの巨大ファイルを、役割ごとに5つに分割する。AIが毎回800行全部読む無駄がなくなり、必要な部分だけ参照できるようになる。

3 自動チェック（フック）をポータブル化

今はmacOS専用のコマンドを使っているので、uname ベースのOS判定に書き換えてLinuxでも動くようにする。保存先フォルダも環境変数（パソコンの設定値）で変更可能に。さらにフックの完全な設定定義（JSON）をプランに明記して、実装時のブレをなくす。

4 サーバーをポータブル化

ポート番号（通信の窓口番号）や保存先フォルダを起動時に指定できるようにする。今のサーバーは49行・外部ライブラリゼロなので、プラグインにそのまま同梱する。

5 コマンド + セットアップスクリプト作成

/plan-viewer:setup（初期設定）と /plan-viewer:serve（サーバー起動）の2つのコマンドを作る。初期設定の実処理は scripts/setup.sh に集約し、コマンド文書はその呼び出しだけにする。これにより環境差による手順のブレを防ぐ。

6 アセット + ドキュメント

アイコン画像やPWA設定をプラグインに同梱。README（開発者向け説明書）と使い方LPページも作成する。

7 Git初期化 + 個人設定の段階移行

GitHubに公開した後、個人設定をプラグインに移行する。いきなり削除はしない。まずバックアップを取り、プラグイン版と並行稼働でテスト。問題なければ段階的に旧ファイルを削除する。失敗してもバックアップから即復旧できる。

📐 設計判断

判断ポイント	決定	理由
保存先フォルダ	環境変数で変更可能、初期値は `~/plan-viewer/`	全プロジェクト横断で一覧表示するため、プロジェクトごとではなくホーム直下
サーバー	プラグインに同梱	49行・外部ライブラリなし。分ける理由がない
自動チェック	デフォルトで有効	plan-viewerの核心機能。設定しないと誰も使わない
多言語対応	しない（日本語のみ）	今は不要。必要になってから対応すればいい（YAGNI）

✅ 検証方法

claude --plugin-dir ~/plan-viewer-plugin でプラグイン起動し、plan mode → HTMLが正しく生成されるか
自動チェック（フック）が ExitPlanMode の前にちゃんと止めてくれるか
サーバーが起動してスマホからアクセスできるか
/plan-viewer:setup → scripts/setup.sh が実行され、アイコンなどが正しくコピーされるか
移行テスト: プラグイン版と個人設定版が並行稼働して干渉しないか

💡 ポイント

ゼロ依存がカギ — plan-viewer は外部ライブラリを一切使っていない。Python標準ライブラリだけのサーバー、インラインCSS/JSだけのHTML。この「何もインストールしなくていい」特性がプラグイン化と相性がいい。

スキル分割で効率化 — 800行を5ファイルに分けることで、AIが毎回全部読む必要がなくなる。HTML生成時はテンプレートだけ、色を変えたいときはパレットだけ参照すればいい。

段階移行でリスク回避 — Codex のレビューで指摘された「移行の破壊的リスク」に対応。バックアップ → 並行稼働 → 段階削除の3フェーズで、いつでもロールバック（元に戻す）できる。

MIT ライセンス — 最も自由度が高いオープンソースライセンス。誰でも使える・改変できる・商用利用もOK。