PR 說明員 是做什麼的?
產出一份文件,教導團隊成員關於一項變更的內容:什麼東西出錯或缺失、系統在該變更周圍如何運作、變更做了什麼,以及我們如何知道它有效。
參數
- 目標: 一個 PR 編號或 URL,或者不指定。
- 若提供 PR 且
ghCLI 可用,使用gh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,files取得詳細資料,並使用gh pr diff <url>取得差異。在 PR 的頭部提交 (git show <headRefOid>:<path>) 處讀取周圍程式碼,而非本地HEAD。 - 若未提供 PR 或無
gh:則解釋本地變更。使用git diff <base>...HEAD處理已提交的變更,以及git diff加上git status處理未提交的工作,其中<base>是預設分支或第一個提交。
- 若提供 PR 且
--local:即使存在 PR,也使用本地檢出(未推送的工作)。在頁面上註明它反映的是本地變更。--concise:一個簡短版本,約兩分鐘可讀完。最多一個視覺輔助、最多 3 個程式碼片段、無目錄、每節 1–3 句話。--md:撰寫 Markdown 而非 HTML(預設檔案為儲存庫根目錄下的HANDOVER.md,除非使用者指定其他名稱)。適用於交接文件以及當瀏覽器不易取得時。
目標讀者與語氣
- 讀者是團隊中的初級工程師。使用短句、簡單動詞、每段一個想法。
- 不定義基礎知識(REST, SQL, JWT, React hooks),也不使用非技術類比。保持技術性,使用真實的模組、函式、路由和欄位名稱以及真實數字。
- 讓措辭簡單,而不是內容。在遇到不常見的函式庫呼叫或模式時,在首次出現處解釋它。
- 以最終稿的形式撰寫。直接描述當前狀態。不使用變更日誌或「之前我們認為」的措辭。
- 對確定性要誠實。將未經證實的主張標註為「可能,尚未確認」。
範圍:解釋變更,而非差異
- 挑選能說明故事的檔案,並且只挑選其中重要的行。
- 每個檔案使用 1–3 個程式碼片段,每個片段約 25 行以內,用
...表示省略的部分。為每個片段提供檔案路徑,並用 2–4 句話說明其作用與原因。 - 對於修復,顯示導致錯誤的程式碼以及修復的差異。
- 按照執行流程而非差異順序排列程式碼。
- 跳過管道、重新命名和格式化。如果審查者在差異中會看到它們,則用一行提及。
1. 了解變更
- 閱讀差異和周圍程式碼。決定模式:
- 功能:新的行為或大型重構。
- 錯誤修復:症狀、根本原因和修復。
- 找到最新的驗證執行:測試命令和計數,最好能證明新的迴歸測試在沒有修復的情況下會失敗,在有修復的情況下會通過。如果該證明不存在且成本低廉,則自行產出:
git stash push -- <src files>,執行測試,然後git stash pop。同時尋找手動或端到端檢查(CLI 輸出、請求、螢幕截圖)。每個類型僅顯示最近一次執行。 - 利用對話中的發現(根本原因分析、QA 報告、工單),如果它們存在的話。
2. 文件骨架
每份文件都以一行眉線(repo · PR #n · ticket 或 repo · local changes)、一個白話標題,以及 1–2 句的開場白開始。
錯誤修復
- 出了什麼問題:症狀、在哪裡發現、排除了什麼可能性。
- 根本原因:資料或流程中斷的確切位置(
file:line),若有必要可配上視覺輔助。 - 導致錯誤的程式碼:一到兩個片段。
- 修復方式:一個差異片段以及為何它有效。說明它同時修復的副作用。
- 我們如何知道:一個在修復前失敗、修復後通過的迴歸測試,完整測試套件的計數,以及一個手動檢查。
- 重點歸納:2–4 個初級工程師可在其他地方重複使用的經驗教訓。
功能
- 為什麼:問題或目標,附有證據。
- 它在哪裡:架構或模組上下文(圖表),以及什麼是刻意未改變的。
- 流程:步驟或流程圖,連結到程式碼卡片。
- 程式碼走讀:每個重要檔案一張卡片,按流程順序。
- 需了解的行為:邊界情況、狀態、失敗模式(如果超過 3 個則使用表格)。
- 驗證:僅顯示最近一次執行。
- 審查者重點:2–3 行的心智模型,以及差異中最應仔細檢查的地方。
交接文件附加內容(使用 --md 時總是包含;HTML 中可選):
- 如何執行 / 測試:確切指令。
- 所做的假設:在規格未明確之處所做的決定及其原因。
- 待確認的業務問題:按影響程度排序。
- 風險與回滾:生產環境中可能出錯的情況以及如何還原。
- 後續步驟:如果有更多時間,你會做什麼。
簡潔版: 僅包含出了什麼問題 / 做了什麼與為什麼、根本原因 / 如何運作、修復方式 / 關鍵程式碼以及我們如何知道。
3. 視覺輔助:僅當它們能用文字無法說明的東西時使用
| 內容 | 使用方式 |
|---|---|
| 模組或服務架構、誰呼叫誰、請求順序 | Mermaid flowchart / sequenceDiagram(≤ ~12 個節點) |
| 在之前和之後表現不同的分支 | 之前/之後表格或一個小型靜態 SVG |
| 資料通過各個階段、被過濾器丟棄的值 | 範例輸入 → 輸出表格,之前 vs 之後 |
| 狀態、指令、風險、合約 | 表格 |
在 Markdown 中,使用 fence 起來的 ```mermaid 區塊(GitHub 會渲染)。僅在使用者要求時才添加動畫。
4. 建置
- HTML: 從
references/page-template.html開始(自包含、支援明暗模式、Mermaid 和 highlight.js 從 CDN 載入)。儲存到.pr-review/<name>.html,以工單或 PR 命名,或命名為local-<short-desc>。保持其不在 git 中:如果git check-ignore -q .pr-review/失敗,則將.pr-review/追加到.git/info/exclude。除非被要求,否則不要編輯.gitignore。- 程式碼片段:
<pre><code class="language-<lang>">…</code></pre>,HTML 跳脫。對於修復差異,使用language-diff搭配-/+行。 - Mermaid:
<pre class="mermaid">…</pre>。切勿硬編碼顏色。
- 程式碼片段:
- Markdown(
--md): 純 GitHub 風格 Markdown,同樣的骨架,無 HTML。
5. 檢查一次
- HTML:如果瀏覽器工具可用,分別在桌面寬度和約 400px 寬度下開啟頁面一次。檢查 Mermaid 是否渲染以及程式碼是否高亮,在一次遍歷中修正發現的問題,不要循環。否則,說明未經預覽,並提供開啟指令(macOS 用
open,Windows 用start,Linux 用xdg-open)。 - 重新檢查頁面上的每一個
file:line、數字和指令是否與程式碼一致。事實必須準確。
6. 回報結果
回覆時提供:
- 檔案路徑
- 模式以及涵蓋的章節
- 使用的視覺輔助及其解釋的內容
- 文件顯示的是哪個驗證執行
- 任何標註為「尚未確認」的內容
未經請求,切勿編輯 PR 主體、發布評論或推送任何內容。