図解＋フィードバックツール

わからない言葉やしくみを AI に伝えるだけで、初めて聞く人にもわかるように噛み砕いた図解ページを自動で作り、フィードバック機能付きで公開できるツールです。

• 前提知識がなくても読める — 専門用語は出てきた場所で必ずわかりやすく解説されます
• 文字の壁にならない — カード・ステップ図・比較表など、目で見てわかる構成です
• テキストを選んでコメント — 公開した図解で、気になる箇所をマウスで選択するとコメント入力欄が出ます
• 優先度が色でわかる — Must（赤）・Better（黄）・Want（緑）の 3 段階で重要度を伝えられます
• セットアップは 1 回だけ — 一度設定すれば、以降は図解を公開するたびにフィードバック機能が自動で付きます
• 無料で使える — Vercel と Surge の無料プランだけで動きます

しくみ

  「○○を図解して」と AI に依頼
    │
    ▼
  AI が図解 HTML を output/ に生成
    │
    ▼
  deploy-diagram.sh が自動で実行
    ├─ fb-tool-url.txt から FB ツール URL を取得
    ├─ </body> の直前に widget.js の <script> を注入
    └─ Surge にデプロイ
    │
    ▼
  公開 URL をブラウザで開く（FB 機能付き）
    ├─ widget.js    … 画面右のサイドバー・コメント入力・ハイライト表示
    └─ /api/comments … コメントの保存・取得
         │
         ▼
  Neon Postgres（無料DB）
    └─ comments テーブル … コメントデータを永続化

セキュリティについて

API はトークンで保護されています。セットアップ時に自動で生成・設定されるため、追加の操作は不要です。

• コメント API（/api/comments）とページ取得 API（/api/fetch-page）はトークンなしではアクセスできません
• 図解のデプロイ時に、トークンが自動で埋め込まれます
• fb-api-token.txt はトークンを保存するファイルです。Git にはコミットされません

セットアップ

初回だけ必要な設定です。AI が順番に案内してくれます。

  ① Node.js を確認
        ↓
  ② Vercel CLI をインストール
        ↓
  ③ 依存関係をインストール
        ↓
  ④ Vercel にログイン
        ↓
  ⑤ API トークンを生成
        ↓
  ⑥ Vercel にデプロイ
        ↓
  ⑦ データベースを追加（ブラウザで操作）
        ↓
  ⑧ マイグレーション実行
        ↓
  ⑨ 完了（fb-tool-url.txt と fb-api-token.txt が生成される）

やり方

Cursor のチャット欄で次のように伝えてください。

セットアップして

AI がステップごとに案内してくれます。

必要なもの

必要なもの	説明	費用
Node.js	パソコン上でプログラムを動かすための土台。AI が自動でインストールを案内します	無料
Vercel アカウント	フィードバックツールを動かすサーバー。メールアドレスで登録できます	無料（Hobby プラン）
Neon Postgres	コメントデータを保存するデータベース。Vercel の画面から追加します	無料
Surge アカウント	図解を公開するサービス。初回にメールアドレスとパスワードで登録します	無料

クレジットカードの登録は不要です。

使い方

図解を作る

Cursor のチャット欄に、知りたいことを書いて送信します。

APIについて図解して

AI が図解を作り、フィードバック機能付きで自動デプロイします。

コメントを付ける

  ① 図解ページで気になるテキストをマウスで選択
        ↓
  ② ポップアップが表示される
        ↓
  ③ 優先度を選ぶ（Must / Better / Want）
        ↓
  ④ コメントを入力して「送信」

初回だけ名前の入力を求められます（次回以降は自動で記憶されます）。

優先度の意味

優先度	色	使いどころ
Must	赤	必ず直すべき箇所（事実の間違い、重大なわかりにくさ）
Better	黄	直すとよくなる箇所（表現の改善、構成の入れ替え）
Want	緑	余裕があれば対応（細かい表現、好みの範囲）

コメントを確認する

画面右端の小さなボタンをクリックすると、サイドバーが開きます。

• 未解決 / 解決済 / すべて のフィルタで絞り込めます
• コメントカードをクリックすると、本文の該当箇所にジャンプします
• 本文のハイライトをクリックすると、サイドバーの対応カードにジャンプします

コメントを管理する

操作	できること
返信	コメントにスレッド形式で返信
解決	対応済みのコメントを解決済みにする（再開もできます）
編集	自分のコメントの内容・優先度を変更
削除	自分のコメントを削除
優先度変更	自分のコメントのバッジをクリックで Must → Better → Want を切り替え

コメントをダウンロードする

サイドバーのヘッダーにあるボタンでエクスポートできます。

• JSON — プログラムで処理したいとき
• MD — Markdown 形式。優先度ごとに分類されて出力されます

図解の削除

チャット欄で「この図解を削除して」と伝えてください。AI がデプロイ履歴から URL を特定し、削除を実行します。

以前の図解ツールとの違い

以前は「図解ツール」と「フィードバックツール」が別々のフォルダでした。

	旧（別々のツール）	新（このツール）
フォルダ	図解ツール + fb-tool-v2 の 2 つ	図解コメントツールの 1 つだけ
FB 機能	図解ツールの base.html に手動で widget を埋め込み	デプロイ時に自動注入（base.html はクリーン）
再 DL 時	base.html が上書きされて widget 設定が消える	fb-tool-url.txt で管理。base.html に影響なし
セットアップ	図解ツール側で base.html を編集する手順が必要	「セットアップして」だけで完了

旧図解ツールをすでに使っている場合は、このフォルダに切り替えるだけで移行できます。output/ 内の既存の図解はそのまま使えます（再デプロイすれば FB 機能が自動で付きます）。

フォルダの中身

図解コメントツール/
├── .claude/skills/
│   ├── creating-visual-explainers/  ← 図解生成スキル
│   │   ├── SKILL.md
│   │   ├── references/
│   │   │   ├── base.html           ← 図解テンプレート（widget なし）
│   │   │   ├── model-answer.html   ← 模範回答
│   │   │   └── node-install-guide.md
│   │   └── scripts/
│   │       └── deploy-diagram.sh   ← デプロイ＋widget 注入
│   └── setup-fb-tool/               ← セットアップスキル
│       ├── SKILL.md
│       └── references/
│           └── node-install-guide.md
├── output/                           ← 図解の保存先
├── public/
│   └── widget.js                     ← フィードバック UI 本体
├── src/
│   ├── app/api/comments/             ← コメント CRUD API
│   └── lib/
│       ├── db.ts                     ← データベース接続
│       └── types.ts                  ← 型定義
├── scripts/
│   └── migrate.ts                    ← DB テーブル作成
├── fb-tool-url.txt                   ← セットアップ完了後に生成
├── fb-api-token.txt                  ← API トークン（セットアップ完了後に生成）
├── deploy-history.log                ← 図解デプロイ履歴
├── package.json
└── README.md                         ← この説明書

ファイル / フォルダ	説明	触る必要
output/	図解の保存先	見るだけ
public/widget.js	フィードバック UI 本体	なし
src/app/api/comments/	コメントの CRUD API	なし
scripts/migrate.ts	DB テーブル作成スクリプト（セットアップ時に 1 回だけ実行）	なし
fb-tool-url.txt	FB ツールの URL（セットアップ完了後に自動生成）	なし
fb-api-token.txt	API トークン（セットアップ完了後に自動生成）	なし
deploy-history.log	図解の公開履歴（自動生成）	なし

あなたが直接触る必要があるファイルはありません。 セットアップも図解の作成も、AI がすべて案内してくれます。

困ったとき

「セットアップして」と言っても反応しない

このフォルダ（図解コメントツール）を Cursor で開いているか確認してください。 フォルダの中の個別ファイルではなく、フォルダごと開く必要があります。

Vercel へのデプロイが失敗する

チャット欄で「デプロイが失敗しました」と伝えてください。AI がエラーの内容を読み取り、対処法を案内してくれます。

コメントが保存されない

データベースのセットアップが完了しているか確認してください。 チャット欄で「コメントが保存されません」と伝えると、AI が原因を調べてくれます。

フィードバック欄が図解に表示されない

セットアップが完了していれば、新しく作る図解には自動で付きます。 すでに公開済みの図解には反映されないので、再デプロイしてください。

その他のトラブル

何が起きても、まずはチャット欄で AI に状況を伝えてください。 AI がエラーの内容を読み取り、次にやるべきことを教えてくれます。

---

Mac / Windows どちらでも使えます。AI-Driven School 運営が動作確認済みです。