← 一覧に戻る

plan-viewer v2.0 再設計 — 15ファイル→9ファイルへ削ぎ落とす

一言でいうと

なぜこれが必要なのか

plan-viewer は段階的に機能を追加してきた結果、ファイルが分散しすぎた。色の定義だけで1ファイル、一覧ページのルールで1ファイル、用語集のテンプレートで1ファイル…。

「今必要なものだけを残す」YAGNI原則（You Aren't Gonna Need It = 今使わないものは作らない）と、「シンプルさを最優先する」KISS原則（Keep It Simple, Stupid）に沿って、不要なファイルを統合・削除する。

機能は一切減らさない。ファイルの整理だけ。引っ越しの断捨離みたいなものだと思ってほしい。

何をするのか

まず: プラグインが動いていない問題を直す

調査で発覚した重大な問題がある。plan-viewer のhook（特定の操作の前後に自動で処理を差し込む仕組み）が実は動いていなかった。

原因は登録の不整合。「有効にしてある」という設定はあるのに、実際のプラグイン置き場に plan-viewer が見つからない状態だった。住所変更届を出したのに、実際には引っ越していなかったようなもの。

修正は1行。~/.claude/plugins/local-marketplace/（プラグインの置き場フォルダ）の中に、~/plan-viewer-plugin/ を指す「ショートカット」（シンボリックリンク）を作るだけで直る。

削除するもの（6ファイル + 2ディレクトリ）

統合するもの

SKILL.md（AIへの文章ルール指示書）に2つのファイルの内容を吸収する:

• index-rules.md の一覧ページ更新ルール（カードの書き方、絵文字の選び方、相対時刻の表示スクリプト）
• glossary-template.md の用語集の作り方ルール（ただしHTMLテンプレート部分は不要。既存の glossary.html 自体が「生きた見本」になる）

page-template.md（個別ページのHTMLテンプレート）に1つのファイルの内容を吸収する:

• css-palette.md のカラーパレット定義（色の名前と値の対応表）

自動化するもの

今まで初回だけ手動で実行していた /plan-viewer:setup（フォルダ作成コマンド）を廃止。代わりに /plan-viewer:serve（サーバー起動コマンド）がフォルダを自動作成するようにする。1ステップ減る。

hook の整理

3つあったhookを2つに減らす:

hook	役割	判定
ExitPlanMode ゲート	HTML未生成なら計画の確定をブロック	残す（核心）
Write ガード	HTML書く前にルールを読んだか確認	残す（実績あり）
PostToolUse 自動促し	計画を書いたらHTML生成を催促	削除（過剰）

3つ目の「PostToolUse 自動促し」は、1つ目の「ExitPlanMode ゲート」が最終防衛線として機能しているため不要。計画を確定しようとした時点でHTMLが無ければブロックされるので、途中で催促する必要がない。

このゲートは毎回有効。計画Aを承認した後に計画Bを作る場合、計画Bの ExitPlanMode 時に再びチェックが走る。ゲートは「index.html（一覧ページ）が直近120秒以内に更新されたか」を見ているので、計画Bのために新しいHTMLを作らない限りブロックされる。

ただし、フィードバック中のHTML更新は自動では行われない。計画Aに対して承認せずに指摘を入れた場合、計画ファイルは修正されるが、plan-viewer のHTMLは古いまま。次に ExitPlanMode しようとすると120秒チェックに引っかかるので、結果的にHTMLの再生成が強制される。

運用で見つかった3つの改善 NEW

改善1: 一覧ページの自動ソート

問題: 一覧ページ（index.html）の記事が更新順に並んでいない。「先頭に追加する」というルールだが、既存の記事を更新したときに位置がずれてしまう。

対策: 一覧ページの JavaScript（相対時刻を表示するスクリプト）に「自動ソート」機能を追加する。ページを開いたとき、各記事の日時を読み取って新しい順に自動で並べ替える。手動で間違った位置に追加しても、表示は常に正しい順番になる。

改善2: FABボタンの省略防止

問題: 個別ページの右下に表示される操作ボタン（リロード・アノテーション）がたまに生成されないことがある。ルールには「省略禁止」と書いてあるのに。

対策: 3つの手を打つ:

• ルール文書（SKILL.md）の表現を強化（「省略した場合はブロックされる」等の警告を追加）
• HTMLテンプレートの該当箇所に「ここは省略するな」という目印コメントを追加
• HTMLを書き込む前の自動チェック（Write hook）に「FABセクションが含まれているか確認」を追加

改善3: 更新時刻の記載漏れ対策

問題: 記事の時刻が書かれていないことがある（日付だけで時刻が抜ける）。

対策: 改善1の自動ソートにより、時刻が無い記事は一覧の最下部に落ちる。これが「時刻を書き忘れてるよ」という視覚的な合図になる。ルール文書にも「時刻が無い場合、一覧で最下部に表示される」と明記する。

実行ステップ

ポイント