pr-diagram:針對合併請求繪製圖表
目標:一張圖表,讓審查者在 10 秒內了解變更的內容與流程。 它不是整個程式碼庫的地圖。
護欄(不可違反)
- 絕不修改程式碼。 請勿編輯、建立或刪除儲存庫中的檔案,也請勿提交、推送或切換分支。
.mmd檔案應放在暫存或暫存目錄中,絕不能放在儲存庫中。 - 絕不核准、要求變更或合併。 請勿執行
gh pr review、gh pr merge或gh pr close,也請勿張貼 PR 評論。此技能唯一會進行的寫入操作是gh pr edit --body-file在描述上。 - 一個核准步驟:在相同訊息中顯示完整的新版描述並詢問是否張貼。 請勿先問「要不要我張貼?」,然後再顯示描述。這樣會形成兩個核准回合。顯示完整的內容主體,而不只是新增的區段,並在訊息結尾提問。對該訊息回覆「看起來不錯」、「張貼」或「是」視為核准。沉默、提問或要求調整則不屬核准。調整後,再次一併顯示完整主體和提問。
- 為您新增的所有內容簽名,在新增區塊的最後一行加上以下這行文字:
- 由 Claude Code 產生
引數
/pr-diagram使用目前分支的 PR,如果沒有 PR 則使用本機分支差異。/pr-diagram 123或 PR 網址則指定該 PR(也可以透過網址用於其他儲存庫)。type=td|lr|sequence|state|er強制指定圖表類型。
步驟 1:收集差異
使用 PR(皆為唯獨):
gh pr view <N> --json number,title,body,url,baseRefName,headRefName,files,additions,deletions
gh pr diff <N> --name-only
gh pr diff <N>
沒有 PR:找出基礎分支(gh repo view --json defaultBranchRef -q .defaultBranchRef.name),然後執行 git diff --stat $(git merge-base origin/<base> HEAD) 和 git diff $(git merge-base origin/<base> HEAD)。
大型差異(超過 1500 行變更或超過 30 個檔案):先讀取 --stat 和 PR 主體,然後只讀取包含邏輯的檔案。跳過鎖定檔案、產生的程式碼、快照和純粹重新命名的檔案。
步驟 2:識別流程
差異顯示的是行數,而非關係。讀取(唯獨)每個受影響檔案的最新版本,並整理出:
- 流程: 觸發條件(請求、任務、事件、使用者操作)、執行順序,以及結束位置(回應、資料庫寫入、訊息、外部呼叫)。
- 每個步驟的狀態: 新增(由此 PR 新增)、變更(已存在但經修改)或未經修改(審查者理解變更所需的上下文)。
- 一句話摘要供審查者參考(例如「在付款呼叫之前新增一個重試步驟」)。
以 PR 標題和主體作為意圖的參考,但如果程式碼與其不符,請相信程式碼。每個節點和邊緣都必須可以追溯至您讀過的程式碼。絕不為了讓圖表更整齊而憑空發明步驟。 如果不確定,就省略並說明原因。
移除的程式碼:如果移除的步驟對審查者很重要,請用灰色節點、標籤為「(removed)」並使用虛線邊緣來顯示。否則就省略。
步驟 3:選擇圖表類型
輸出始終是 Mermaid 格式的 .mmd 檔案。根據流程特性選擇類型:
| 變更主要涉及… | 圖表 |
|---|---|
| 逐步流程或決策邏輯 | flowchart TD(由上而下) |
| 元件或服務的接線方式,或管線 | flowchart LR(由左至右) |
| 3 個以上參與者之間隨時間傳遞的請求或訊息 | sequenceDiagram |
| 狀態或生命週期變更(待處理 → 核准 → …) | stateDiagram-v2 |
| 資料表、欄位或關係(遷移) | erDiagram |
使用一個圖表。僅當 PR 同時變更結構和執行時期流程時,才使用兩個。如果 PR 太小不需要圖表(1-2 個檔案,沒有新流程),請直接說明並停止。
步驟 4:建立圖表
標籤:使用簡潔的英文文字。
- 寫下步驟的作用,而非程式碼識別碼:例如
檢查卡片是否未過期,而不是CardValidator.validateExpiry()。如果名稱有幫助,可以使用簡短形式:PaymentReconciliationService變成付款協調器。 - 將網址縮短為路徑:
api.example.com/v2/orders/{id}/refunds變成POST /orders/:id/refunds。 - 矩形節點
A["..."]:每行最多 35 個字元。 - 圓角矩形
A(["..."])和圓角A("...")節點:每行最多 25 個字元。 - 如果節點需要更多細節,請使用
<br/>將其拆分成多行(每行都在其限制內)。最多使用 3 行。 - 形狀含義:矩形 = 步驟或元件,圓角矩形 = 起點或終點(觸發條件、回應),圓角 = 外部系統,菱形
A{"..."}= 決策點(最多 25 個字元),圓柱體A[("...")]= 資料儲存。 - 最多 15 個節點。當節點數量大約超過 8 個時,使用
subgraph按服務或區域進行分組。 - 簡短地為邊緣加上標籤,使用簡潔的英文文字(例如
發送、失敗時、儲存),最多 20 個字元。 - 序列圖: 參與者和演員名稱最多 25 個字元。訊息、
loop、alt和opt的標籤,以及Note文字每行最多 35 個字元(使用<br/>分行,最多 3 行)。請勿在訊息文字中使用;或#,因為它們會破壞解析。
顏色(在 GitHub 淺色和深色模式下均可閱讀)。 使用淺色填滿搭配深色文字和明顯的邊框:
classDef new fill:#d3f9d8,stroke:#2b8a3e,stroke-width:2px,color:#0b3d17
classDef changed fill:#fff3bf,stroke:#e67700,stroke-width:2px,color:#4a2b00
classDef unchanged fill:#e9ecef,stroke:#868e96,stroke-width:1px,color:#343a40
class StepA,StepB new
class StepC changed
class StepD unchanged
每個節點只有一個類別。在 stateDiagram-v2 中,使用 classDef 加上 class StateName new。
序列圖: 類別不適用。rect 只設定背景,文字顏色來自 GitHub 的主題(深色模式下為淺灰色)。不透明的淺色填滿在深色模式下會使文字無法閱讀,因此務必使用半透明色調:
- 新增:
rect rgba(46,160,67,0.18) - 變更:
rect rgba(210,153,34,0.22) - 未經修改:不使用
rect
絕對不要使用不透明的 rect rgb(...)。為關鍵變更加上 Note over。
全部是新增的 PR(沒有變更或未經修改的項目): 保留綠色色調,並在摘要中說明「此圖表中的所有內容皆為新程式碼」,因為沒有其他可對比的項目。
語法陷阱(它們會破壞 GitHub 的渲染)。請逐一檢查:
- 節點 ID 必須是純英數字元(例如
ChkCard)。標籤必須始終使用引號:ChkCard["Check card"]。 - 在標籤中使用
#quot;來表示字面意義的"。<br/>是標籤中唯一允許的 HTML。 - 絕對不要使用
end(小寫)作為 ID。在箭頭周圍務必加上空格(A --> B),因為A---oB會被解析為圓形邊緣。 subgraph Id["Label"]…end。每個子圖都需要自己的end。- 序列參與者:
participant API as Orders API(ID 沒有空格)。 erDiagram的屬性類型必須是單字(例如varchar,而不是varchar(255))。- 不要使用
%%{init}%%主題區塊。classDef顏色會處理兩種模式。
儲存圖表為 pr-<N>-diagram.mmd(或 branch-<name>-diagram.mmd),放在暫存或暫存目錄中。提供完整路徑。
步驟 5:呈現前自我檢查
- 計算每個標籤行上的字元數量,並對照其限制(矩形 35 個字元,圓角矩形、圓角和菱形節點 25 個字元,邊緣標籤 20 個字元;在序列圖中,參與者 25 個字元,訊息、區塊和註解 35 個字元)。修正任何超出的部分。
- 確保沒有標籤包含原始程式碼識別碼(駝峰式命名、
Foo.bar()、底線命名),而可以使用簡潔的英文文字取代。 - 檢查每個節點的顏色:它在差異中真的是新增、變更或未經修改嗎?
- 可選的渲染檢查:
npx -y @mermaid-js/mermaid-cli -i <file>.mmd -o <file>.svg。第一次執行會下載 Chromium(約 150 MB),因此請先詢問再執行。
步驟 6:呈現
在聊天中使用以下格式:
**<PR 功能的一句摘要>**
<2-3 句話:以文字描述的流程、變更在流程中的位置、任何省略或不確定的部分>
```mermaid
...
```
**圖例:** 綠色 = 新程式碼 · 黃色 = 變更的程式碼 · 灰色(或無色調)= 未經修改的上下文
儲存位置:<.mmd 檔案的完整路徑>
步驟 7:顯示完整描述並詢問是否張貼(與步驟 6 在同一個訊息中)
在回覆前執行此操作,以便圖表、完整的新版描述和問題一併送出:
-
將目前主體擷取到暫存檔案:
gh pr view <N> --json body -q .body > <tmp>/body-old.md -
在
<tmp>/body-new.md中建立新版主體。將區塊放在標記之間,以便重新執行時取代而非累加:<!-- pr-diagram:start --> ## 變更圖表 <摘要句子> ```mermaid ...圖例: 綠色 = 新 · 黃色 = 變更 · 灰色(或無色調)= 未經修改 (使用文字,而非彩色表情符號。表情符號在不同作業系統上會呈現不同的顏色,例如 ⬜ 在 Windows 上顯示為薰衣草色。)
- 由 Claude Code 產生
如果標記已存在,只取代它們之間的內容。否則在空白行後附加該區塊。保留原始主體的其他每個位元組不變。 -
檢查新版主體是否以完整的原始主體開頭。必須逐位元組保留。
-
以圍欄程式碼區塊顯示完整的新版描述、PR 網址和問題作為訊息結尾:「張貼到此 <PR 網址>?」 然後停止並等待(護欄 3)。
步驟 8:張貼(僅在步驟 7 的訊息得到「是」之後)
gh pr edit <N> --body-file <tmp>/body-new.md。絕對不要使用--body搭配內嵌文字,因為 Shell 的引號處理會弄亂反引號和$。- 使用
gh pr view <N> --json body -q .body驗證它是否與body-new.md相符,然後提供 PR 網址。比較時忽略尾隨空格,因為-q會加入換行。例如,在 Python 中比較兩者的.rstrip()。
還沒有 PR(僅本機分支)?提供區塊讓使用者開啟 PR 時貼上。請勿建立 PR。
禁止事項
- 不要為每個檔案繪製圖表。為所有內容繪製圖表等於什麼都沒有顯示。
- 不要在標籤中放入機密、內部主機名稱、包含 Token 或查詢字串的完整網址,或客戶資料。