---
title: "PR 摘要工作流"
description: "用 GitHub Copilot 生成 PR 摘要草稿，再由作者補齊背景、風險、測試和回復。"
verifiedAt: "2026-05-06"
---

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

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

## 1. 摘要結構

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

```md
## What changed
- ...

## Why
- ...

## Risk
- ...

## Tests
- ...

## Rollback
- ...
```

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

## 2. 工作流

```mermaid
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 生成後，作者逐項補齊：

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

示例補充 prompt：

```txt
把这份 PR 摘要改成
reviewer 可用版本。

要求：
- 保留 Copilot 生成的事实。
- 不要编造未发生的测试。
- 按 5 段结构重排。
- 覆盖断点、权限和回滚。
- 测试只写我提供过的命令。
```

## 5. Reviewer 視角檢查

提交前按 reviewer 視角讀一遍：

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

<details>
<summary>深讀：什麼時候用 comment field</summary>

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

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

## 本章自檢

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

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

## 官方來源

- [Creating a pull request summary with GitHub Copilot](https://docs.github.com/en/copilot/how-tos/copilot-on-github/copilot-for-github-tasks/create-a-pr-summary) —— GitHub 官方 PR summary 使用說明。
- [GitHub Copilot documentation](https://docs.github.com/en/copilot) —— GitHub 官方 Copilot 文件總入口。

## 接下來去哪

<Cards>
  <Card title="程式碼審查工作流" description="摘要完成後，用 Copilot review 預篩風險。" href="/zh-Hant/docs/github-copilot/official/10-practical-playbooks/code-review" />
  <Card title="Cloud Agent review" description="非同步任務完成後也要做 PR 摘要和 review 閉環。" href="/zh-Hant/docs/github-copilot/official/04-cloud-agent/review-output" />
</Cards>
