Communitygithub.com

work-brochure

以視覺化 HTML 小冊子(流程圖、實際應用程式的前後截圖、決策過程、檔案地圖、差異對照、驗證證據)引導使用者瀏覽已完成的工作,不取代聊天中的一般文字總結。適用於任何儲存庫。

work-brochure 是什麼?

「work-brochure」技能是一項專為 AI 代理(如 Claude Code、Cursor、Codex 等)設計的專業技術工具,能在開發者完成一個功能、修復或工作項目,或是開啟 Pull Request(PR)時,自動產生一份獨立的視覺化 HTML 小冊子。此小冊子以圖表、實際應用程式的螢幕截圖和註解代碼為核心,為開發者提供一個比純文字更直觀、更快速理解變更內容的途徑。其運作流程包含六個嚴謹的步驟:首先,代理仍需寫下一般的聊天總結;接著,透過提供的 `gather.sh` 腳本收集提交記錄、檔案差異統計和 PR 資訊;然後,從實際運行的應用程式中截取「之後」的畫面,必要時也會切換到基礎版本截取「之前」的畫面;接著,代理會根據變更類型(邏輯、UI、數據等)規劃要使用的視覺化元素(如 Mermaid 流程圖、序列圖、前後比較截圖、內嵌 SVG 長條圖等),並從模板產生最終的 HTML 頁面;最後,代理會進行一次預覽確認,並將成果透過文件渲染、Artifact 發布分享給使用者,同時在聊天中提供連結。此技能還包含重要的細節規則,例如要求準確性(圖表需反映真實的函式名稱與檔案路徑)、限制頁面大小(小於 8 MB)、以及將生成的小冊子檔案儲存在 `.claude/work-briefs/` 目錄中,並自動將其從 Git 追蹤中排除。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lincolncrooks/work-brochure/tree/HEAD/skills/work-brochure

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Work brochure(工作小冊子)

完成一項工作後,使用者希望得到兩件事:

  1. 聊天中的一般總結:就像您平常會寫的一樣(改了什麼、目前狀態、未完成事項)。此技能絕不取代或縮短這段總結。
  2. 一份小冊子:一個獨立的 HTML 頁面,以視覺化方式引導瀏覽相同的工作,讓使用者可以將它與聊天視窗並排打開,透過圖表、螢幕截圖和註解過的程式碼來理解變更,而不是閱讀段落文字。

小冊子必須準確反映程式碼。所有聲明、數字、檔案路徑和螢幕截圖都必須來自實際的 diff、您執行的命令以及您查看過的應用程式。切勿發明一個從未執行過的測試,或一個您未見過的結果。

步驟

1. 先撰寫聊天總結

像平常一樣完成工作,包括您的文字總結和 wrap_up(如果應用程式有的話)。然後再建立小冊子。如果使用者只要求為先前的工作建立小冊子,則直接跳到步驟 2。

在 PR 被打開後(外掛程式的 PostToolUse 鉤子,或您設定中的一個鉤子,會在 gh pr create 之後新增一個提示),在同一次互動中為該 PR 使用 gather.sh --pr <N> 建立小冊子,並在您的結尾訊息中加入小冊子連結。除非使用者要求,否則不要編輯 PR 內文來加入它。僅當 PR 是微不足道的一行程式碼變更(錯字、版本號更新)時才跳過此步驟。

2. 收集事實

從儲存庫根目錄執行輔助腳本(它會列出提交記錄、分資料夾的每個檔案差異統計、未暫存變更和 PR 資訊):

bash <skill-dir>/scripts/gather.sh            # 此分支 vs main + 未暫存變更
bash <skill-dir>/scripts/gather.sh A..B       # 任意 Git 範圍(例如已合併的工作)
bash <skill-dir>/scripts/gather.sh --pr 51    # GitHub PR

然後閱讀 diff 中相關的部分(git diff <範圍> -- <路徑>),而不是全部。同時也要從此對話中收集:

  • 原因:使用者自己描述的問題或請求。
  • 決策:您權衡過的選項以及為什麼選擇這一個。
  • 驗證:已執行的命令及其真實輸出、已截取的螢幕截圖、您在瀏覽器或模擬器中檢查的項目,以及您無法驗證的項目。
  • 未竟事項:後續追蹤、風險、任何未完成的部分。
  • 需要使用者協助:任何只有他們才能決定、肉眼檢查或批准的事項。

3. 擷取真實應用程式(當變更可見時)

如果變更顯示在使用者介面中,小冊子應該展示實際的應用程式,而不是對它的描述。

  • 之後:使用預覽工具截取執行中應用程式的變更畫面(使用專案的 launch.json 伺服器啟動 preview_start,進行導航,使用 computer {action: "screenshot"}),或 iOS 模擬器的 screenshot。當版面配置變更時,同時擷取桌面和手機寬度的畫面。
  • 之前:如果差異是重點,請將基礎版本簽出到暫存區的臨時工作樹中(git worktree add <scratchpad>/before <base>),在不同的埠上提供服務,截取相同畫面的螢幕截圖,然後移除工作樹(git worktree remove)。當變更純粹是新增性質,或「之前」的畫面沒有任何價值時,請跳過此步驟。
  • 將螢幕截圖儲存為暫存區中的檔案,縮小它們(sips -Z 1400 -s format jpeg -s formatOptions 78 in.png --out out.jpg),並將它們嵌入為 data: URI。將整個頁面保持在約 8 MB 以下。
  • 對於影片/動畫變更,嵌入幾張靜止幀(ffmpeg -ss <t> -i clip.mp4 -frames:v 1 -vf scale=900:-1 still.jpg)或一條連續幀,以及測量到的數據。
  • 非視覺化變更(腳本、資料、後端)則使用圖表和真實輸出,而非螢幕截圖。

4. 規劃故事,然後選擇視覺元素

按照使用者期望的解釋方式來安排頁面順序:先展示成果,再解釋如何運作,最後是細節。根據變更的內容來選擇視覺元素。只要圖片能比文字更快解釋清楚,就優先使用圖片;將文字限制在簡短說明和一至三句的段落。

變更項目使用的視覺元素
邏輯、流程管道、決策規則新流程的 Mermaid flowchart;使用 classDef changed 標記新增/變更的節點
元件之間的請求(UI → API → 儲存)Mermaid sequenceDiagram
結構(模組、檔案、資料形狀)帶有 +/− 長條的檔案地圖;展示元件如何連接的 Mermaid graph;欄位前/後的表格
使用者介面前/後螢幕截圖對比;在圖片上放置帶編號的標註
數據(時間、大小、計數、效能)按比例繪製的內嵌 SVG 長條圖,顯示前後對比
狀態或生命週期Mermaid stateDiagram-v2
一系列工作(遷移、多步驟變更)編號步驟逐步說明(僅當順序是真實的時候)
關鍵程式碼簡短的 diff 摘錄(5–25 行),重要行標記出來,放在 <details> 中以避免佔據太多版面

對於一個功能規模的變更,至少要有三個不同的視覺元素;對於較小的變更,至少一個。圖表必須描述真實的機制(真實的函式名稱、檔案名稱、數值),而不是泛泛的方框。

5. 從模板建立頁面

複製 <skill-dir>/template.html 並填入內容。它已經包含了草稿本的外觀(特意採用單一淺色主題:方格紙背景、手寫風格標題、鉛筆草稿卡片、手繪圖表)、版面配置以及上面列出的每個元件。除非使用者要求,否則不要加入深色模式或更換外觀。規則如下:

  • 保留 <style> 區塊和 Mermaid 載入腳本;取代範例內容。刪除不適用的章節,而不是讓它們內容空泛(例如,純重構就不需要「前 → 後」)。
  • <title>:功能的名稱,二到四個詞(例如「結帳重試邏輯」),而不是「工作總結:...」。
  • Hero 區:一句話說明成果、中繼行(分支、PR 連結、日期),以及統計條(檔案數、行數 +/−、提交數、檢查通過數)。從 gather.sh 計算數字,不要估算。
  • 需要您的輸入(Hero 區下的便利貼):僅顯示真正需要等待使用者的要求,每個一行,並指出查看位置。最多三個。如果完全沒有,則刪除整個便條;切勿為了填充而加入無關內容。
  • 為何這樣做(決策表):二到四個在本次會議中真正權衡過的選項,其中一個標記為「已選」,每個選項附帶一行優缺點。不要為了填滿表格而虛構替代方案;如果沒有真正做過選擇,請刪除該章節。
  • 保持頁面精簡:只有這些以及適用的章節。不要加入模板之外的章節。
  • 檔案地圖:每個有意義的檔案一行(將自動生成/二進位檔案合併為一行),+/- 長條的寬度以最大檔案總變更數的百分比計算,加上一行白話說明為何變更。
  • Diff 摘錄:跳脫 <、>、&。使用 class="add"、class="del" 或 class="hl"(重要的未變更行)來標記行。
  • Mermaid 程式碼放在 <pre class="mermaid"> 中,在標籤之後直接從模板開始放置配置區塊(--- / config: / look: handDrawn / theme: neutral / ---),以便在本地檔案和 claude.ai 上都能以手繪風格渲染。保留模板中的 classDef changed fill:#dfe7ff,stroke:#1f4fd1,stroke-width:2px 這一行。在標籤內將 </> 跳脫為 &lt;/&gt;,並對本次工作新增或變更的項目使用 class <ids> changed。將每個圖表保持在約 5–9 個節點,以便能容納在一個畫面中:將連續的步驟合併到一個節點中,並使用 <br/> 詳細行;將較長的流程拆分成兩個圖表。對短鏈使用 flowchart LR,對分支結構使用 TD。
  • 驗證:列出每項檢查,並附上通過/失敗/未檢查的標籤及其證據(輸出摘錄或螢幕截圖)。當存在「未檢查」的項目時,它們是必需的。
  • 書寫要簡潔明瞭:使用簡短的句子、使用者的術語、不要廢話。

將其儲存為 <repo-root>/.claude/work-briefs/<YYYY-MM-DD>-<slug>.html。透過將其加入本機排除檔案中一次,即可在不修改每個儲存庫的 .gitignore 的情況下,將該資料夾排除在 Git 之外:

mkdir -p .claude/work-briefs && x="$(git rev-parse --git-common-dir)/info/exclude" && (grep -qxF '.claude/work-briefs/' "$x" 2>/dev/null || echo '.claude/work-briefs/' >> "$x")

6. 檢查一次,然後交付

  1. 在瀏覽器窗格中打開它一次(使用 url: file://<path> 的 preview_start,或專案的靜態伺服器),並截取一張螢幕截圖以確認圖表已渲染且沒有內容溢出。修正那次查看顯示的問題;不要重複循環。
  2. 在側面板中顯示它:使用 display: "render" 的 SendUserFile。
  3. 將其發布為私有 Artifact(使用檔案路徑的 Artifact 發布、icon: "document" 和一句話描述),以便在工作樹被清理後仍能保留。這是持久性副本;Artifact 預設為私有。如果沒有可用的 Artifact 工具(例如純終端機工作階段),則跳過此步驟並提供本機路徑。
  4. 在聊天中,在您的一般總結之後,加入一行包含小冊子連結和本機檔案路徑的文字。

更新:如果使用者要求變更,請編輯同一個檔案並重新發布到相同路徑,以便連結保持不變。

一份好的小冊子看起來是什麼樣子

  • 一個沒有參與該工作階段的人,在滾動瀏覽兩分鐘內就能理解發生了什麼變更以及為什麼。
  • 第一個畫面無需滾動就能回答「現在有什麼不同?」。
  • 每個圖表、圖表和螢幕截圖都是針對這次變更的。
  • 真實狀態一目了然:哪些已驗證、哪些未驗證、還有哪些遺留問題。

相關技能