← 一覧に戻る

plan-viewer 自動変換計画 — フック地獄からスクリプト自動変換へ

2026年3月9日 21:25 更新

一言でいうと

AIにHTMLを書かせるのをやめて、スクリプトが自動でMDをHTMLに変換する仕組みに切り替える。

なぜこの変更が必要なのか

t-wada（テスト駆動開発の第一人者）の考え方で問題を分析すると、フックの数が多いのは症状であって原因ではない。根本原因は「責務の置き場所」が間違っていること。

矛盾の構造

プランモード（計画を書くための専用モード）には「プランファイル以外のファイルを書かせない」という設計意図がある。ところが plan-viewer は「プランモード中に HTML ファイルを書け」と要求していた。これは設計意図と真っ向から矛盾する。

その矛盾を無理やりフック（自動ドアのセンサーのように、特定の操作に処理を差し込む仕組み）で解決しようとした結果、6層の防壁ができてしまった。

今の構造（間違い）

  • AI が MD を書く
  • フックが AI に HTML を書けと強制
  • プランモードが HTML 書き込みを拒否
  • フックとプランモードが喧嘩
  • 普通の作業まで巻き添えで止まる

あるべき構造

  • AI が MD を書く（AI の仕事はここまで）
  • スクリプトが自動で HTML に変換
  • AI はプランモードのまま何も矛盾しない
  • フックはゼロ or リマインドのみ
  • 普通の作業は一切影響なし

t-wada が好む Kent Beck の言葉に「まず変更を簡単にして、それから簡単な変更をしなさい」がある。HTML 生成の責務を AI からスクリプトに移すことで、フック問題を根本から解消する。

全体像

新しい仕組みの流れはこう：

plans/*.md ──(1)──→ 変換スクリプト ──(2)──→ ~/plan-viewer/*.html AI が書く 自動で発火 スマホで読める (1) のトリガー方法（後述の案A or 案Bで選択） A: PostToolUse フック → スクリプト実行（Claude Code 連動型） B: ファイル監視デーモン → スクリプト実行（完全独立型） (2) 変換の仕組み marked（MD→HTML変換ライブラリ）でマークダウンを HTML に変換 → Zenn ダークテーマのテンプレートで包む → ~/plan-viewer/ に保存 + index.html 自動更新

案A：PostToolUse フック方式

おすすめ — 最もシンプル

考え方：今ある plan-sync-reminder フック（PostToolUse フック。ファイル書き込みの直後に発火する仕組み）を改造して、「フラグを作る」のではなく「変換スクリプトを呼ぶ」ようにする。

流れ：

  1. AI がプランモードで plans/xxx.md を書く
  2. PostToolUse フックが発火する
  3. フックが変換スクリプト convert-plan.sh を呼ぶ
  4. スクリプトが marked（マークダウンをHTMLに変換するツール）で HTML に変換
  5. Zenn ダークテーマのテンプレート（HTMLの雛形）で包んで ~/plan-viewer/ に保存
  6. index.html の一覧に自動追加

メリット：

デメリット：

必要なもの：marked（npm パッケージ。npm install -g marked で入る）

案A の実装ステップ

1 marked をインストール
npm install -g marked — MD を HTML に変換するコマンドラインツール。
2 HTML テンプレートを作成
現在の plan-viewer ページテンプレート（Zenn ダークテーマ CSS + FAB ボタン + アノテーション JS）を、{{CONTENT}} プレースホルダー付きのテンプレートファイルとして保存する。変換スクリプトがこのテンプレートの {{CONTENT}} を、marked で変換した HTML に差し替える。
3 変換スクリプト convert-plan.sh を作成
入力：MD ファイルのパス → 出力：~/plan-viewer/ に HTML ファイル + index.html 更新。ファイル名から日付とタイトルを抽出し、テンプレートに流し込む。
4 settings.json のフックを入れ替え
現在の6つの plan 関連フックを全削除し、PostToolUse の plan-sync-reminder を convert-plan.sh に差し替え。prompt hook（HTML 品質チェック）はAI が手動で plan-viewer スキルを使うときのために残す。
5 不要なスクリプトを削除
plan-impl-gate.sh、plan-bash-gate.sh、plan-exitplan-gate.sh、plan-viewer-stop-check.sh、plan-sync-reminder.sh の5ファイルを削除。

案B：ファイル監視デーモン方式

完全独立 — Claude Code に依存しない

考え方：Claude Code とは完全に切り離した「デーモン（バックグラウンドで常に動き続けるプログラム）」を立てて、ファイルの変更を監視する。

流れ：

  1. chokidar（ファイル変更を監視する Node.js ライブラリ）でプラン用ディレクトリを監視
  2. MD ファイルの追加・更新を検知
  3. 変換スクリプトで HTML 化 → ~/plan-viewer/ に保存

メリット：

デメリット：

「非エンジニア向け翻訳」はどうなるのか

これが一番大事なポイント。今の plan-viewer は AI が「プランの専門用語を噛み砕いて、非エンジニアが読める HTML を書く」という翻訳をしていた。自動変換にすると、この翻訳がなくなる。

3つの対応策

対策1：プランを最初から分かりやすく書く（おすすめ）

AI がプランを書く時点で、非エンジニアにも読めるように書かせる。CLAUDE.md に「plans/ に書く MD は非エンジニアでも理解できる文章にすること」と追記する。MDの段階で翻訳済みなら、自動変換でそのまま読めるHTMLになる。

対策2：手動スキルを併用する

重要なプラン（関係者に共有するもの）は、後から手動で「plan-viewer にまとめて」と AI に頼む。plan-viewer スキルは残すので、使いたいときにいつでも使える。自動変換は「速報版」、手動スキルは「清書版」という使い分け。

対策3：将来的にAI APIで自動翻訳する

変換スクリプトの中で Claude API（Anthropic のAIを外部から呼び出す窓口）を使って翻訳させる。ただし API 呼び出しにはコストがかかる。今すぐは不要（YAGNI）。必要になったときに追加する。

おまけ：スマホからのアクセスを楽にする

今は plan-viewer のローカルサーバーに同じ Wi-Fi 内からアクセスしているが、cloudflared（Cloudflare Tunnel のクライアント。ローカルサーバーをインターネットに公開するツール）を使えば、外出先のスマホからもアクセスできる。

コマンド1つで公開：cloudflared tunnel --url http://localhost:ポート番号

これだけで https://ランダム文字列.trycloudflare.com という URL が発行されて、どこからでもアクセスできるようになる。アカウント登録もいらない。ただし URL はコマンドを止めると無効になる（一時的な公開）。

常時公開したい場合は Cloudflare のアカウントで Named Tunnel（名前付きトンネル）を設定すれば、固定の URL でいつでもアクセスできる。

ポイント

おすすめは案A（PostToolUse フック方式）+ 対策1（プランを分かりやすく書く）の組み合わせ。

なぜ案A か：t-wada の原則「動くものを最小の変更で作る」に合致する。フック1つ + スクリプト1つ + テンプレート1つ。デーモン管理もない。問題が起きたら案Bに移行すればいい。

なぜ対策1 か：そもそもプランを書く時点で分かりやすくすれば、後工程の翻訳が不要になる。これは「問題が発生しない設計」であり、「問題を検知して対処する設計」より優れている。

見送った選択肢：案Bのデーモン方式は、plan-viewer 以外のファイル監視にも使えるので拡張性は高い。ただし「今必要か？」と問えば答えは No。chokidar は npm install すれば入るので、必要になったときに15分で追加できる。

Cloudflare Tunnel はおまけだが、外出先からスマホで見たいなら導入する価値がある。

📝 質問モード — テキストを選択してね
✓ 質問を送信しました