如何撰寫高品質的 PR

寫完程式碼只是第一步，真正的挑戰往往是在 PR 被合併之前。你可能遇過 PR 提交後石沉大海，或是審閱者因為看不懂你的意圖而提出一堆瑣碎的問題。

這篇指南會教你如何建立一個「好讀」的 PR，讓審閱者能快速理解你的動機、驗證行為，並放心地把變更合併進去。

需要準備的東西

在開始建立 PR 之前，請確保你已經準備好以下項目：

已經完成的程式碼變更與相關 pnpm 指令執行結果
測試證據（Logs、螢幕截圖或 UI/UX 錄影）
對程式碼庫或 GitHub 相關 Issue 的檢索記錄

快速開始

想要在 5 分鐘內提交一個高品質的 PR？跟著這些步驟走就對了：

執行基礎驗證：在建立 PR 前，確保在本地執行並修復以下指令的錯誤：
- pnpm lint
- pnpm check
- pnpm build
- pnpm test
- 如果涉及通訊協定變更：pnpm protocol:check
定一個好標題：使用 動詞 + 範圍 + 結果 的格式。
- 範例：Docs: add PR and issue templates
填寫 PR 內容：遵循「漸進式揭露」原則，從上到下依序排列：
- 最上方：摘要與意圖
- 接著：變更內容與風險
- 再來：測試與驗證結果
- 最後：具體實作細節與證據
加入暗號：如果你已經讀過這份指南，請在 PR 說明中加入 lobster-biscuit 這個詞。
保持專注：確保 PR 的變更範圍集中，避免進行大範圍的重構。

Common PR Types & Templates

根據你的變更類型，選擇最適合的 Template。這能幫助審閱者快速進入狀況。

General PR Template

如果你不確定該用哪一個，就用這個通用的：

#### Summary

#### Behavior Changes

#### Codebase and GitHub Search

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort (self-reported):
- Agent notes (optional, cite evidence):

Fix (修補錯誤)

重點在於重現步驟與根因分析。

#### Summary

#### Repro Steps

#### Root Cause

#### Behavior Changes

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

Feature (新功能)

請務必附上使用場景與 UI 示範。

#### Summary

#### Use Cases

#### Behavior Changes

#### Existing Functionality Check

- [ ] I searched the codebase for existing functionality.
      Searches performed (1-3 bullets):
  -
  -

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

Refactor (重構)

請明確聲明「無行為變更 (No behavior change)」。

#### Summary

#### Scope

#### No Behavior Change Statement

#### Tests

#### Manual Testing (omit if N/A)

### Prerequisites

-

### Steps

1.
2.

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

Docs (文件)

記得在提交前執行 pnpm format。

#### Summary

#### Pages Updated

#### Before/After

#### Formatting

pnpm format

#### Evidence (omit if N/A)

**Sign-Off**

- Models used:
- Submitter effort:
- Agent notes:

疑難排解

如果你在準備 PR 時遇到問題，可以參考以下常見狀況：

Q: pnpm lint 或 pnpm check 失敗了怎麼辦？ A: 請先修復所有的 Lint 錯誤與型別檢查錯誤再提交。這能節省審閱者的時間，也能避免 CI 流程掛掉。

Q: 我的變更沒有影響行為，還需要寫測試嗎？ A: 如果是 Refactor，請在說明中註明「No behavior change」。如果是 Docs 或 Chore，可以視情況省略測試，但仍建議執行基礎驗證指令。

Q: 找不到適合的證據（Evidence）？ A: 對於 UI 變更，截圖或錄影是必須的；對於邏輯變更，請貼上測試 Log 或執行結果。

想要自動化你的開發流程？試試 AI Setup Assistant 幫你快速上手。

下一步

OpenClaw Expert

還是卡住了？

如果這篇文件沒有解決你的情境，直接問 OpenClaw Expert，拿到可執行步驟。