寫出好的 prompt

AI 不是把 prompt 照字面畫成圖。visualize-planner 會先讀 prompt 與筆記上下文，找出這段內容想讓讀者記住的一句話，再決定互動方式與技術。prompt 寫得越清楚，它越不用猜。

好 prompt 的要素

幾件事不用寫，生成流程本來就會做：

• 外框、類型標籤、來源檔名、caption 的位置：由 GeneratedFrame 統一提供
• 尊重 prefers-reduced-motion、動畫節制在 200–400ms
• 不用 emoji。prompt 裡寫了 ✅ ❌，成品會改成 lucide-react 圖示

type 只是提示

type 告訴 AI 你大概要哪一類，實際選型由 visualize-planner 依決策樹決定，命中第一條就停：

只有內容本質上是靜態的（純查表、單張結構快照），才會回退成靜態圖。AI 換掉你寫的 type 時，會在對話裡說明。

所以 prompt 的重點放在「要讓讀者體驗什麼」，不必糾結 type 該填哪個。拿不定就寫 free。

實例對照

以下取自現有筆記裡 status: generated 的標記。prompt 有精簡，省略了配色、reduced-motion、emoji 等通用要求，其餘意思不變。

給公式、範圍與預設值

標記 agent-reliability-compound：

{/* @ai-visualize
id: agent-reliability-compound
type: motion
prompt: |
  做一個可互動的「Agent 可靠度複利崩塌」示範。核心洞察是「換更強的模型不會修好網路逾時，
  只有 checkpoint 與 resume 可以」——要讓讀者親手拖出「單步看起來很高、全程其實很低」的張力。

  兩個 slider：
  - 步驟數（tool call 次數，1–20，預設 10）
  - 每步成功率（50%–99%，預設 85%）

  即時計算並用大字強調整體成功率 = 每步成功率 ^ 步驟數（預設 0.85^10 ≈ 20%）。
  視覺化用一條由多個小方塊組成的「步驟鏈」：每個方塊代表一步，鏈越長，末端「全程走完」的機率條越短；
  整體成功率低於某門檻（例如 50%）時機率條轉為警示色。
  可並排放「單步 85%」與「全程約 20%」兩個數字，凸顯落差。
status: generated
*/}

成品：上方三個數字並排（單步成功率、步驟數、全程走完），下方是步驟鏈，每格的深淺是走到這一步還沒失敗的機率，再下面是全程機率條和兩個 slider。全程低於 50% 轉成警示色、更低轉成危險色，底部的說明句隨數字更新，最後落在「只有 checkpoint 與 resume 可以」。

為什麼有效：

• 洞察和張力都寫成一句話，元件直接拿來當結論
• slider 的範圍、預設值、公式都給了，AI 不用編數字
• 「並排兩個數字凸顯落差」說清楚讀者要比較什麼

指定切換方式，讓差異現形

標記 time-fields-bottleneck：

{/* @ai-visualize
id: time-fields-bottleneck
type: free
prompt: |
  做一個可互動的「時間欄位 vs 瓶頸定位」對比走查，讓讀者親身體會：
  為什麼要記這麼多時間欄位——欄位愈細，愈能指出瓶頸具體卡在哪一段。

  核心洞察：同樣的「總耗時」，只記錄上線時間（合併視角）只能看到「慢」，
  卻看不出時間花在哪；把時間欄位攤開成四段後，瓶頸那一段會立刻凸顯出來。

  互動設計：
  - 一條任務生命週期時間軸：建立 → 開始 → 完成 → 驗收 → 上線，中間形成四個耗時區間
  - 「視角切換」：合併視角只顯示一條灰色長條 + 總耗時；攤開視角把同樣的長度切成四段，
    最長（瓶頸）那段以紅色強調、標上「瓶頸」徽章
  - 「情境切換」（總耗時相近但瓶頸不同）：前置壅塞、估時失準、驗收塞車、上線延宕
  - 「估時失準」情境在『開始→完成』段內畫出「預計」基準線，對照實際超出多少
  - 下方診斷卡：瓶頸段名稱 + 一行對應問題（取自內文表格）
status: generated
*/}

成品：兩組按鈕，一組切四種情境、一組切合併與攤開視角。合併時只有一條長條和「總耗時」，攤開後長條分裂成四段，最長的一段變紅並帶「瓶頸」徽章；「估時失準」情境多一條「預計 N 天」的虛線。底部一句收斂：同樣的天數，合併只看到「慢」，攤開才指得出卡在哪一段。

為什麼有效：

• 用兩個視角把張力具體化：同一份資料，看得到與看不到的差別
• 情境清單讓讀者看到「瓶頸會移動」，不是只有一個例子
• 指定診斷卡的文字「取自內文表格」，元件和筆記說的是同一件事

這個 prompt 沒給各段天數，成品裡的天數是 AI 自己配的，只保證總長相近、瓶頸段最長。數字本身重要的話，要寫進 prompt。

把資料完整列出來

標記 order-state-machine：

{/* @ai-visualize
id: order-state-machine
type: diagram
prompt: |
  繪製電商訂單的狀態機圖（手寫 SVG，狀態節點 + 有向箭頭）。
  狀態節點：待付款、已付款、已出貨、已完成、已取消、已退款。
  轉移（箭頭上標註觸發事件）：
    - 待付款 --完成付款--> 已付款
    - 待付款 --逾時/買家取消--> 已取消
    - 已付款 --出貨--> 已出貨
    - 已付款 --買家取消--> 已退款
    - 已出貨 --簽收/鑑賞期結束--> 已完成
    - 已出貨 --退貨--> 已退款
  視覺要求：
    - 三個終態（已完成、已取消、已退款）用不同樣式標示為終態
    - 待付款為起始狀態，加一個進入箭頭
    - 箭頭清楚標註事件名稱，避免線條交叉
status: generated
*/}

成品：六個節點、六條轉移和事件名稱都和 prompt 一字不差。prompt 沒要求互動，AI 仍依「互動優先」加上點擊：點一個狀態，只留下它和它能直接轉移到的狀態，其餘淡化；點空白處重置。

為什麼有效：

• 狀態和轉移用 A --事件--> B 一條一行列出，AI 不需要從內文推敲，也不會漏掉或多畫
• 起始狀態、終態的樣式要求明確，讀者一眼分得出哪裡是終點
• type: diagram 只是提示：AI 照樣用手寫 SVG，但多加了一層能「試走」轉移的互動

相關的標記會被合併

筆記裡兩個相鄰的標記，hook-lifecycle-events 和 why-stop-event：

{/* @ai-visualize
id: hook-lifecycle-events
type: diagram
prompt: |
  手寫 SVG 畫一條 Claude Code session 生命週期橫線，由左到右標出 7 個 hook 事件節點：
  SessionStart → UserPromptSubmit → PreToolUse → PostToolUse → Notification → Stop → SubagentStop。
  Stop 節點放大、加星星標記與「使用中」徽章，其餘節點灰階。
  純靜態 SVG，無需互動。
status: generated
*/}

{/* @ai-visualize
id: why-stop-event
type: diagram
prompt: |
  三張並排卡片，每張上方一個 icon、中間粗體標題、下方一句說明：
  1. 「一次性檢查」— 不像 PostToolUse 每改檔就觸發
  2. 「避免無限迴圈」— 不會因為改 PRD 又觸發自己
  3. 「時機自然」— Claude 講完話的瞬間，使用者剛好看到提醒
merged-into: hook-lifecycle-events
status: generated
*/}

成品：一個元件。上方是七個事件節點的生命週期線，Stop 放大並有光暈；每個節點都能點，點 Stop 時下方顯示「為什麼用 Stop」的三張卡，點其他節點顯示該事件何時觸發。why-stop-event 被併入，只留標記、沒有自己的元件。

這組說明了什麼：

• 兩個 prompt 都只描述版面，沒寫洞察，但內容是同一件事：「為什麼選 Stop」就是在解釋「生命週期上的 Stop」
• 合併後，第一個 prompt 寫的「純靜態、無需互動」被換掉了，因為點節點才能把兩段內容接起來
• 你想要的若真的是兩張分開的靜態圖，要在 prompt 裡說明理由，或在 AI 提議合併時回絕。合併的標記長什麼樣見 @ai-visualize 標記欄位

常見問題寫法

以下的「改寫前」是依原則寫的示範，不是取自現有筆記。

太籠統

改寫前（示範）：做一個關於快取的互動圖表。

AI 不知道你要讀者記住什麼，只能從上下文猜。改成先寫洞察與張力：

改寫後（示範）：核心洞察是「TTL 設越長，命中率越高，但讀到舊資料的時間也越長」。做一個 TTL slider（1 秒～1 小時，預設 60 秒），即時顯示命中率與「最久會讀到多舊的資料」兩個數字並排，讓讀者拖出兩者的拉扯。

只說「畫張圖」

「畫一張流程圖」「做成表格」只描述形式。形式 AI 會自己選，它需要的是內容：有哪些步驟、哪一步是重點、讀者看完該懂什麼。要指定形式時，同時寫理由，例如「純查表、不需要互動」。

資料不給

數字、節點、轉移沒寫，AI 會自己配一組合理的值。對示意用途可能沒問題，但：

• 需要準確的數字，就把數值、範圍、公式寫進 prompt，或指明「取自上方表格」
• 數字本來就只是示意，請 AI 在元件上標明。embedding-dimension-tradeoff 的 prompt 寫了「明確標註非實測基準、僅供直覺」，成品的相對品質與速度就以示意係數計算，caption 也註明「非實測基準」

一次要太多

一個 prompt 塞進三個概念、五種互動，成品容易變成擠在一起的控制面板。拆成幾個標記，各自放在對應的段落旁邊。

反過來，幾個標記其實是同一組對比的不同切面時，AI 可能提議用 tab 或 stepper 合併成一個元件，並在對話裡說明合併了哪些；它也可能建議把過載的標記拆開。不確定時它會先問你。

不如預期時

先判斷是哪裡不對，再改 prompt：

改完 prompt 後，在 Claude Code 對話裡指名重做，例如「重新生成 time-fields-bottleneck」。generated 的標記會覆寫原元件；failed 的標記要改過 prompt 再明確要求；locked 的要先自己改掉狀態。各狀態的做法見狀態與重新生成。