PR 摘要工作流

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
PR summary	PR 摘要	讓 Copilot 生成變更說明。
準確性	accuracy	摘要必須如實反映改動。
可讀性	readable	讓審查者快速理解。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你用 Copilot 生成準確、好讀的 PR 摘要。

你是 Copilot PR 摘要顧問。

【角色】
Copilot PR 摘要顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。

【輸入】
- 這個 PR 改了什麼：___
- 審查者最需要知道的：___
- 是否有破壞性變更：___
- 團隊 PR 模板：___
- 經驗水平：___

【工作流程】
1. 引導生成結構化摘要
2. 確保如實反映改動
3. 突出破壞性變更和影響面
4. 對接 PR 模板
5. 給核對

【輸出規範】
▌一、結構化摘要
▌二、如實反映
▌三、突出破壞性變更
▌四、對接模板 + 核對

【硬約束】
- 摘要如實，不誇大不漏關鍵變更
- 生成後人工核對
- 破壞性變更必須顯式標出
- 不要替我臆測情況或編造不存在的功能，資訊不全先問清
- 不確定的設定或許可權一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

PR 摘要不是給作者看的，是給 reviewer、未來排障的人和釋出負責人看的。Copilot 可以生成第一版，但作者必須把業務背景、風險和驗證補全——把 Copilot 摘要原樣提交，等於把"使用者影響 / 風險 / 測試 / 回復"四件事甩給下一個看 PR 的人。

GitHub 官方說明：PR summary 可以在 description field 或 comment field 裡生成；為了更好結果，最好從空白描述開始，因為 Copilot 不會把已有描述內容納入生成依據。

1. 摘要結構

一份能用的 PR 摘要至少包含 5 塊：

## What changed
- ...

## Why
- ...

## Risk
- ...

## Tests
- ...

## Rollback
- ...

如果團隊只允許短摘要，也至少保留 What changed、Risk、Tests。沒有風險和測試說明的摘要，只是 changelog。

2. 工作流

flowchart TD
    Diff["PR diff"] --> Blank["保持 description 空白"]
    Blank --> Generate["Copilot Summary"]
    Generate --> Author["作者人工補充"]
    Author --> Verify{"對照 issue / diff / tests"}
    Verify -->|缺背景| Author
    Verify -->|缺風險| Author
    Verify -->|透過| Publish["Create PR / Update comment"]
    Publish --> Reviewer["Reviewer 快速進入上下文"]

    style Generate fill:#dbeafe,stroke:#2563eb,stroke-width:2px
    style Author fill:#fef3c7,stroke:#d97706,stroke-width:2px
    style Publish fill:#dcfce7,stroke:#16a34a,stroke-width:2px

3. 生成前準備

先確認 PR 本身已經有基本衛生：

分支只包含本次任務相關提交。
PR 標題說明具體行為，不寫“fix”或“update”。
diff 沒有混入格式化、除錯記錄、臨時檔案。
測試命令已經跑過，失敗項有解釋。
issue、設計說明或截圖已經準備好。

Copilot summary 是壓縮上下文，不是清理混亂 diff 的工具。diff 越雜，摘要越容易泛化。

4. 生成後人工補齊

Copilot 生成後，作者逐項補齊：

What changed：按使用者可感知行為、介面、資料、UI 或設定說，不按檔案流水賬說。
Why：連結 issue 或說明業務原因，避免 reviewer 重新猜需求。
Risk：寫可能受影響的路徑、相容性、資料遷移、許可權、效能和斷點。
Tests：寫真實執行過的命令、手動驗證和沒有覆蓋的項。
Rollback：說明能否 revert、是否涉及資料回復、是否需要設定開關。

示例補充 prompt：

把這份 PR 摘要改成
reviewer 可用版本。

要求：
- 保留 Copilot 生成的事實。
- 不要編造未發生的測試。
- 按 5 段結構重排。
- 覆蓋斷點、許可權和回復。
- 測試只寫我提供過的命令。

5. Reviewer 視角檢查

提交前按 reviewer 視角讀一遍：

我能否 30 秒內知道這次改了什麼？
我能否知道應該重點 review 哪些風險？
我能否找到測試證據？
如果上線出問題，摘要能否幫助快速 revert 或定位？
摘要有沒有把 Copilot 猜測當事實？

深讀：什麼時候用 comment field

如果 PR description 已經包含團隊模板、釋出說明或人工寫好的完整內容，可以讓 Copilot 在 comment field 生成摘要草稿，再手動摘取有價值的部分。

不要讓 Copilot 覆蓋已經人工確認過的釋出資訊。

本章自檢

是否從空白描述生成，或在 comment field 裡生成草稿？
是否人工補齊背景、風險、測試和回復？
是否對照 diff、issue 和測試結果核驗事實？
是否刪除了“看起來合理但沒有證據”的句子？
是否讓 reviewer 知道重點看哪裡？

透過標準：摘要能縮短 reviewer 進入上下文的時間，同時不犧牲事實準確性。

官方來源

Creating a pull request summary with GitHub Copilot —— GitHub 官方 PR summary 使用說明。
GitHub Copilot documentation —— GitHub 官方 Copilot 文件總入口。

PR 摘要工作流

1. 摘要結構

2. 工作流

3. 生成前準備

4. 生成後人工補齊

5. Reviewer 視角檢查

本章自檢

官方來源

接下來去哪

程式碼審查工作流

Cloud Agent review

本頁目錄