Work brochure(工作小冊子)
完成一項工作後,使用者希望得到兩件事:
- 聊天中的一般總結:就像您平常會寫的一樣(改了什麼、目前狀態、未完成事項)。此技能絕不取代或縮短這段總結。
- 一份小冊子:一個獨立的 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這一行。在標籤內將</>跳脫為</>,並對本次工作新增或變更的項目使用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. 檢查一次,然後交付
- 在瀏覽器窗格中打開它一次(使用
url: file://<path>的preview_start,或專案的靜態伺服器),並截取一張螢幕截圖以確認圖表已渲染且沒有內容溢出。修正那次查看顯示的問題;不要重複循環。 - 在側面板中顯示它:使用
display: "render"的SendUserFile。 - 將其發布為私有 Artifact(使用檔案路徑的
Artifact發布、icon: "document"和一句話描述),以便在工作樹被清理後仍能保留。這是持久性副本;Artifact 預設為私有。如果沒有可用的 Artifact 工具(例如純終端機工作階段),則跳過此步驟並提供本機路徑。 - 在聊天中,在您的一般總結之後,加入一行包含小冊子連結和本機檔案路徑的文字。
更新:如果使用者要求變更,請編輯同一個檔案並重新發布到相同路徑,以便連結保持不變。
一份好的小冊子看起來是什麼樣子
- 一個沒有參與該工作階段的人,在滾動瀏覽兩分鐘內就能理解發生了什麼變更以及為什麼。
- 第一個畫面無需滾動就能回答「現在有什麼不同?」。
- 每個圖表、圖表和螢幕截圖都是針對這次變更的。
- 真實狀態一目了然:哪些已驗證、哪些未驗證、還有哪些遺留問題。