非エンジニアの vibe-coding に「理解」を足す Claude Code プラグインを作った

2026年2月28日 · 📝 Zenn記事ドラフト

vibe-codingを"vibe"なままにしないために

自分はエンジニアではない。でも Claude Code を使って自分でプロダクトを作っている。

いわゆる vibe-coding だ。AIに指示を出して、コードを書かせて、動くものを作る。便利な時代になった。

でも一つ、ずっと引っかかっていることがある。

「自分が今なにを作っているのか」を、自分自身がちゃんと理解できていない瞬間がある。

AIが出してくる plan（設計計画）を見ても、専門用語だらけで「まあ、いい感じにやってくれてるんだろう」で流してしまう。これが積み重なると、自分のプロダクトなのに中身がブラックボックスになる。

vibe-coding の「vibe」な部分 — つまり「雰囲気でやる」部分 — をできるだけ減らしたい。理解した上で判断したい。

plan-viewer というプラグインを作った

plan-viewer は、Claude Code の plan mode で出てきた設計計画を非エンジニアでも読める HTML への変換を自動チェックで強制し、スマホで確認できるようにするプラグインだ。

スマホで読める。Zenn のダークテーマ「っぽい」デザイン

やってることはシンプルで:

Claude Code が「こういう設計で作るよ」と plan を出す
その plan を確定する前に、自動で「非エンジニア向けの翻訳」を強制する（後述）
翻訳された HTML をスマホで読んで、理解してから GO を出す

「後で読もう」は一生読まない。自分のことは自分がよく分かっている。だから「仕組みとして強制する」のが大事だ。その仕組みについては後で詳しく書く。

なぜスマホなのか

ターミナルの前にいるときは「作業モード」で、つい「OK、進めて」と流してしまう。

スマホで読むと、物理的にターミナルから離れるので「読解モード」に切り替わる。ソファで読む、散歩中に読む。すると「ここ、なんで必要なの？」「この説明わからん」が自然に出てくる。

具体的に何が変わるか

AI が出す plan はこういう文章だ:

dependency array に userId を追加する。auth.ts の validateToken を修正する。API エンドポイントを追加する。

非エンジニアの自分にはこれが分からない。何のことだ。

plan-viewer を通すと、こうなる:

dependency array（変更を監視する対象リスト）に userId を追加する。これにより、ユーザーが切り替わったときに画面が正しく更新される。

auth.ts（ログイン認証を担当するファイル）の validateToken（トークンが正しいか検証する関数）を修正する。

API（プログラム同士が会話する窓口）エンドポイントを追加する。このエンドポイントがないとスマホアプリからデータを取得できない。

変わったのは3点:

専門用語に括弧で解説がつく
「なぜ必要か」の理由が添えられる
ファイル名・関数名に役割の説明がつく

これだけで「何をやっていて、なぜそれが必要なのか」が分かるようになる。

なぜこれが vibe-coding に効くのか

vibe-coding の問題は「理解せずに進める」ことだ。

動くものは作れる。でも:

バグが出たとき、どこが壊れたか見当がつかない
機能を追加したいとき、どこに手を入れればいいか分からない
人に説明できない（投資家、チームメンバー、外注先…）

plan-viewer を挟むことで、毎回の設計判断を「理解してから承認する」習慣が強制される。vibe が理解に変わる。

完全にコードを読めるようにはならない。それはエンジニアの仕事だ。でも「何をやっているか」「なぜそれが必要か」の概念レベルの理解は、プロダクトオーナーとして最低限必要だと思っている。

「強制」の仕組み — PreToolUse hook

さっき「翻訳を強制する」と書いた。その仕組みを説明する。

Claude Code には hook という機能がある。特定の操作が実行される直前や直後に、別の処理を自動で差し込める仕組みだ。

plan-viewer では PreToolUse hook を使っている。「Pre（前）+ ToolUse（ツール実行）」、つまり「ツールが実行される前に発火するフック」だ。具体的にはこう設定している:

監視対象: ExitPlanMode（plan を確定する操作）
やること: index.html（一覧ページ）が直近2分以内に更新されているかチェック
未生成なら: exit 2 を返してブロック。plan を確定できない

つまり「翻訳 HTML を作らないと plan を確定できない」という制約が、仕組みとして埋め込まれている。意志の力に頼らない。仕組みで解決する。

アノテーション機能 — 「分からない」を伝える

スマホで読んでいて「ここ分からない」と思ったら、テキストを選択して質問を送れる。

テキストを選択→質問を入力→送信。スマホ上で完結する

送った質問は JSON ファイルに保存される。次に Claude Code を開いたとき、そのファイルを読ませれば「ここの説明をもっと分かりやすくして」と指示できる。

一人で vibe-coding していると、分からないことを言語化する機会がない。アノテーション機能がその機会を作ってくれる。

テキスト選択でフィードバックを送るUI体験は agentation から着想を得た。

インストール

# リポジトリをクローン（ホームディレクトリに）
cd ~ && git clone https://github.com/ramenumaiwhy/plan-viewer-plugin

# プラグインを指定して起動
claude --plugin-dir ~/plan-viewer-plugin

# 初回セットアップ（Claude Code 内で実行）
/plan-viewer:setup

# サーバー起動（スマホからアクセスするため）
/plan-viewer:serve

4行で使い始められる。外部ライブラリのインストールは不要で、Python の標準機能だけで動く。

スマホからのアクセス方法

サーバーを起動すると、同じ WiFi に繋がったスマホのブラウザから http://<PCのIPアドレス>:8765/ でアクセスできる。特別なツールは不要だ。PCのIPアドレスはターミナルで ipconfig getifaddr en0 を実行すれば分かる（macOS の場合。Wi-FiのIPだけが表示される）。

ただし、カフェなど公共の WiFi に繋がっている状態だと、同じ WiFi に繋いでいる人なら plan を読めてしまう。

だからサーバーはデフォルトで PIN 認証がかかるようになっている。起動するとランダムな4桁 PIN がターミナルに表示されるので、スマホで初回アクセス時にテンキーで入力するだけだ。

--pin 1234 で好きな PIN を固定することもできるし、自宅 WiFi なら --no-pin で解除もできる。

外出先から自宅にある PC にアクセスしたい場合は、Tailscale（個人なら無料で使えるVPN。通信の盗聴も防げる）を入れておくと、WiFi が違ってもスマホから PC にアクセスできる。カフェや移動中でも plan を読めるようになる。

セキュリティの話 — 非エンジニアこそ気にすべき

OSS 公開にあたって、2つの AI（OpenAI の Codex と Claude）に独立してセキュリティ監査をさせた。実際に使ったプロンプトはこんな感じだ:

このリポジトリを「ネット上で見つけてインストールする第三者」の視点でセキュリティ監査してください。Critical/High/Medium/Low で分類し、具体的な修正案を出してください。

「え、自分で作ったものを自分で監査できるの？」と思うかもしれないが、AI を2つ使って「ダブルチェック」させるのがポイントだ。1つの AI だけだと見落としがある。2つが独立して同じ問題を指摘したら、優先的に対処すべき問題だと判断できる。ただし両方が見落とす可能性もある点は留意が必要だ。

実際に見つかった問題の例:

HTTP サーバーが「データを無制限に受け取れる」状態だった → メモリを使い果たす攻撃が可能
サーバーが自分の PC 以外からもアクセスできる状態だった → PIN 認証オプションを追加

非エンジニアが vibe-coding で作ったものをそのまま公開すると、こういうセキュリティ穴が残る。「AI に監査させる」は、非エンジニアでもできる品質管理の手段だ。

/plan-viewer:serve はデフォルトで PIN 認証がかかる（5回間違えると1分間ロック）。PIN はカジュアルなアクセス防止であり、通信の盗聴までは防げない。確実に守りたいなら Tailscale 経由で使おう。自宅 WiFi なら --no-pin で解除できる。

文章ルールが本質

正直、このプラグインの価値は技術じゃなくて文章ルールにある。

AI に「非エンジニア向けに書いて」と指示するだけでは、出力は毎回ブレる。ルールを具体化しないと AI は「なんとなく優しい文章」しか書かない。

plan-viewer の SKILL.md（AI への指示書）に書いたルールの一部:

・専門用語は初出時に括弧で簡潔に解説し、用語集ページへリンクする

・括弧解説の後に「なぜ必要か」を1文で補足する

・比喩で終わらず、比喩から実際の概念への橋渡しをする

・ファイル名・関数名が出てきた場合、その役割を括弧で解説する

・実装の説明は概念レベルに留める（コードは見せない）

「括弧解説 + なぜ必要か」。このパターンを徹底するだけで、AI の出力が劇的に変わる。plan-viewer を使わなくても、CLAUDE.md にこのルールを書くだけで効果がある。

まとめ

plan-viewer は、Claude Code の設計計画を非エンジニアでも読める HTML への変換を自動チェックで強制し、スマホで確認できるプラグイン
「理解せずに進める」vibe-coding の弱点を、毎回の設計承認で補う
スマホで読むことで「作業モード」から「読解モード」に切り替える
アノテーション機能で「分からない」を言語化する
セキュリティ監査は AI 2つのダブルチェックで非エンジニアでも可能
本質は文章ルール。「括弧解説 + なぜ必要か」のパターンが鍵

GitHub: https://github.com/ramenumaiwhy/plan-viewer-plugin

「雰囲気で作る」を卒業したい非エンジニアの方、ぜひ試してみてほしい。

まずはこの記事のURLをあなたの Claude Code に読ませて、「このプラグインを分析して」と聞いてみてほしい。それ自体が vibe-coding に「理解」を足す第一歩になるはずだ。