Community寫作與編輯github.com

PR 說明員

為團隊成員解釋拉取請求、錯誤修復或本地變更,以適合初級工程師理解的單一 HTML 頁面(預設)或 Markdown 交接文件(--md)呈現。涵蓋功能(為何、架構、流程、關鍵程式碼、驗證)或錯誤修復(症狀、根本原因、修復、證明)。適用於被要求「解釋此 PR/修復/變更」、「撰寫逐步解說」、「撰寫交接文件」、「建立審查指南」時,或在移交工作前使用。支援 --concise 以產生約兩分鐘可讀完的版本,--local 用於未提交或未推送的工作,--md 則產出 HANDOVER.md 風格的 Markdown。

PR 說明員 是什麼?

PR 說明員是一項專門用於產生教學文件的 AI 技能,旨在幫助團隊成員(特別是初級工程師)理解程式碼變更。它能夠針對拉取請求、錯誤修復或本地變更,自動生成一份完整的說明文件,格式可選擇自包含的 HTML 頁面(支援明暗模式、Mermaid 圖表、程式碼高亮)或純 Markdown 文件,以滿足不同的交接與審查場景。該技能的獨特之處在於其結構化的文件骨架:對於錯誤修復,它會依序涵蓋症狀、根本原因、肇因程式碼、修復方式及驗證方法;對於功能開發,則會說明問題背景、系統架構、資料流程、重要程式碼走讀、邊界行為及驗證結果。此外,它還能智能地從 GitHub CLI 拉取 PR 資訊,或分析本地 git 差異,並自動產生驗證測試案例以證明修復的有效性。支援 --concise 參數以產出簡短版本,--md 參數以產生適合交接的 Markdown 文件,而 --local 參數則能處理未推送的本地變更。最終輸出的文件會包含檔案路徑、使用模式、視覺輔助說明以及驗證資訊,並明確標註任何未經確認的聲明。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/sahildaswani/agent-skills/tree/HEAD/skills/pr-explainer

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

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

說明文件

PR 說明員 是做什麼的?

產出一份文件,教導團隊成員關於一項變更的內容:什麼東西出錯或缺失、系統在該變更周圍如何運作、變更做了什麼,以及我們如何知道它有效。

參數

  • 目標: 一個 PR 編號或 URL,或者不指定。
    • 若提供 PR 且 gh CLI 可用,使用 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> 是預設分支或第一個提交。
  • --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 句的開場白開始。

錯誤修復

  1. 出了什麼問題:症狀、在哪裡發現、排除了什麼可能性。
  2. 根本原因:資料或流程中斷的確切位置(file:line),若有必要可配上視覺輔助。
  3. 導致錯誤的程式碼:一到兩個片段。
  4. 修復方式:一個差異片段以及為何它有效。說明它同時修復的副作用。
  5. 我們如何知道:一個在修復前失敗、修復後通過的迴歸測試,完整測試套件的計數,以及一個手動檢查。
  6. 重點歸納:2–4 個初級工程師可在其他地方重複使用的經驗教訓。

功能

  1. 為什麼:問題或目標,附有證據。
  2. 它在哪裡:架構或模組上下文(圖表),以及什麼是刻意未改變的。
  3. 流程:步驟或流程圖,連結到程式碼卡片。
  4. 程式碼走讀:每個重要檔案一張卡片,按流程順序。
  5. 需了解的行為:邊界情況、狀態、失敗模式(如果超過 3 個則使用表格)。
  6. 驗證:僅顯示最近一次執行。
  7. 審查者重點: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 主體、發布評論或推送任何內容。

相關技能