PR 示範
審查者應該在不到一分鐘內理解變更，而無需開啟 diff：變更內容、運作方式、運作證明以及審查重點。儲存庫資訊——標題語言、如何錄製變更流程、張貼位置——都放在 .claude/profiles/delivery.md（Demo、Notify）中。
簡短直接勝過完整。 30 秒內五個場景，按此順序，並省略變更沒有的部分，而不是把它們填滿：
- 變更內容——標題和最多三個要點。
- 運作方式——流程，並標記變更的節點。
- 前後對比——僅適用於可視的變更；後端變更則跳過。
- 修正執行——錄影，裁切到關鍵部分，長度不超過 12 秒。
- 證明——審查重點的檢查與測試合併在同一個
key場景中。兩者回答相同的問題，因此不各自獨立一個場景。
1. 收集素材
放入 out/demo/<pr 或 issue>/（已加入 git ignore）：
- 審查重點的證據：
out/review-key/<n>/result.json和key-reviewer的判決（review-key）。 - 使用者可見變更的螢幕截圖：相同檢視在變更前（基礎分支）和變更後的比較，尺寸和資料相同。裁切到變更的部分；1280 像素的整頁會讓變更太小而無法辨識。
- 變更流程的錄影（設定檔中的 Demo 指令，或使用 Playwright 的
browser.newContext({ recordVideo: { dir, size: { width: 1280, height: 800 } }, viewport: { width: 1280, height: 800 } })圍繞涵蓋該變更的 e2e 檢查步驟；檔案會在 context 關閉時出現）。長度保持在 20 秒以下：從關鍵畫面開始，不要錄到登入畫面。 - 變更流程：使用 Mermaid 的
flowchart LR（或TD）：五到九個節點，表示使用者或請求的路徑，並在變更處加上:::changed，新增處加上:::added，移除處加上:::removed。說明行為，而非檔案。 - 執行的測試：每個測試附上一個數字（
476 個測試、12 個流程）。
2. 撰寫 demo.json
放在素材旁邊（路徑相對於該檔案）。文字使用設定檔的標題語言；簡短——場景在其顯示的秒數內被閱讀。反引號和 **粗體** 都有效。
{
"lang": "en",
"brand": "**shop** · PR #352",
"ref": "Closes #331",
"kicker": "Bugfix",
"title": "結帳頁面在 1280 px 時正常顯示",
"subtitle": "付款按鈕遮住了購物籃，優惠券欄位只有 49 像素寬。",
"chips": [{ "text": "審查重點：通過", "ok": true }, "3 個檔案"],
"scenes": [
{ "type": "title", "seconds": 3 },
{ "type": "bullets", "items": ["…", "…", "…"], "seconds": 5 },
{ "type": "flow", "mermaid": "flowchart LR\n A[寬度] --> B{\"< 1440 px?\"}\n B -- 是 --> C[圖示]:::changed", "seconds": 6 },
{ "type": "compare", "before": "before.png", "after": "after.png", "seconds": 5 },
{ "type": "clip", "heading": "在 1280 px 下錄製", "src": "run.webm", "caption": "e2e: checkout-fit", "speed": 1.5, "maxSeconds": 12 },
{ "type": "key", "result": "../../review-key/331/result.json", "baseFails": true, "seconds": 7,
"rows": [{ "ok": true, "text": "`verify.sh` · 476 個測試" }] },
{ "type": "end", "title": "準備好進行審查", "lines": ["PR: **github.com/…/pull/352**", "3 am: …"], "seconds": 3 }
]
}
場景：title、bullets（items，最多四個）、flow（mermaid，設定 legend: false 可隱藏圖例）、compare（before、after、標籤；layout: "stack" 將它們上下排列，適用於工具列等寬條狀內容）、clip（src 為 .webm/.mp4、from/to 秒數、speed、maxSeconds 預設為 20、crop {x, y, w, h} 以錄影的像素為單位，放大到關鍵部分；其長度來自檔案）、key（result 為 keycheck 的 result.json 或一個物件；verdict、baseFails、claim、rows 和 count {value, total, label} 可覆寫——例如，一個檢查執行八個案例，顯示為 8/8 更好理解）、checks（items 包含 name、detail、ok）、end（title、lines）。每個場景都可以有 heading、kicker 和 seconds。省略變更沒有的部分——後端變更沒有 compare 或 clip；純重構只有 key 場景，顯示一致性即可。
key 場景的左側面板最多可容納八行，並會先顯示您自訂的 rows，然後才是審查重點的檢查，因此測試會以每行一個的方式放在這裡（例如 "verify.sh · 476 個測試"），而不是在它之後再用一個 checks 場景。只有在沒有審查重點可顯示時，才單獨使用 checks 場景。
措辭
標題文字在其螢幕顯示的秒數內被閱讀，因此每個字都必須有分量。從令讀者感到困擾的示範中學到的三條規則：
- 陳述結果，不要讚美結果。 判決印章和「由 key-reviewer 獨立檢查」已經表明審查重點通過並由誰檢查。加上「通過，沒有作弊」或「完全驗證」會像是作者在給自己的作業打分。切勿對判決結果發表評論。
- 計數標籤使用純名詞：
檢查通過、案例一致、測試。像失敗/失敗者這樣的動詞作為標籤會使「5/5」變成一個需要反向閱讀的句子——「5 個中的 5 個失敗」聽起來像是變更有問題，但實際意思是基礎分支有問題。如果您需要說明基礎分支失敗，那是baseFails行的作用，它會自行措辭。 - 不要填充內容。 刪除「成功」、「如預期」、「這確保了」以及任何重複標題的要點。如果一個要點會讓審查者說「是的，很明顯」，那它就不是一個要點。
3. 渲染
node <此技能目錄>/scripts/render-demo.mjs out/demo/<n>/demo.json [--webm]
它會在 Chromium 中逐幀繪製每個場景（文字清晰，無掉幀），並編碼為 demo.mp4（H.264，可在 Slack、GitHub 和瀏覽器中內嵌播放）、demo.png（預覽圖：流程圖或 key 場景），加上 --webm 時則會產生 VP9 編碼的 demo.webm。需要 ffmpeg，並使用專案中的 Playwright，否則會安裝一次到 ~/.cache/carnufex-showcase。每渲染一秒影片約需一秒鐘。
發送前先觀看一遍：從每個場景擷取影格（ffmpeg -ss <t> -i demo.mp4 -frames:v 1 f.png）並檢查。文字被裁切、圖表空白、錄到登入畫面：修正後重新渲染。
4. 張貼
張貼到設定檔中 Notify 指定的頻道，以機器人身分，這樣使用者才能收到真正的通知（透過 Slack connector 張貼的訊息會來自使用者本人，而 Slack 不會通知任何人他們自己的訊息）。每個 PR 一個討論串：示範影片開啟該 PR 的討論串；之後的所有內容——CI、審查回合、合併、部署、線上檢查、回滾——都回覆在同一個討論串中（ship 會張貼這些內容）。頻道中每個 PR 只顯示一行，橫跨所有儲存庫。將訊息寫入一個檔案；它必須能獨立存在（Slack mrkdwn 格式），並以儲存庫名稱開頭：
*<repo>* · PR #<n> · <title> — 準備好進行審查
<PR url>
• <變更內容，第 1 行>
• <第 2 行>
審查重點（<類型>）：*通過*，已獨立檢查：<判決中的一行>
3 am: <訊號>
node <此技能目錄>/scripts/post-slack.mjs --channel <id> --pr <PR url> --file out/demo/<n>/demo.mp4 --title "<repo> PR #<n>: <title>（<秒數> 秒）" --comment-file out/demo/<n>/message.md
node <此技能目錄>/scripts/post-slack.mjs --channel <id> --pr <PR url> --text-file update.md [--broadcast]
--pr 會在頻道中透過 PR 網址尋找其討論串（無需儲存狀態）：找到後，訊息會張貼到討論串中；找不到則開啟一個新討論串。--text-file 張貼不帶檔案的純文字訊息；--broadcast 也會在頻道中顯示討論串回覆（用於結果：上線或回滾）。它會列印出討論串和永久連結。機器人 token 來自 SLACK_BOT_TOKEN 或 slack-channel 插件的 ~/.claude/channels/slack/.env；機器人必須已加入頻道（not_in_channel：/invite @<bot>）。如果沒有機器人，則回退到 Slack connector（slack_get_file_upload_url → POST 檔案位元組 → slack_complete_file_upload），並說明不會發送通知。
將相同的三行摘要、Mermaid 流程圖和 Slack 連結放入 PR 描述中（GitHub 可繪製 Mermaid；透過 API 上傳的影片無法在其中播放）。