用 AI 寫 Pull Request 描述與 Code Review 回覆：把 diff 整理成 reviewer 一看就懂的 PR

一分鐘重點：把這條分支的 git diff 連同「做了什麼、為什麼改、怎麼測」一起丟給 AI，它能在幾秒內幫你把一包散亂的 diff 整理成含背景、改動摘要、測試方式、風險的完整 PR 描述，讓 reviewer 三十秒抓到重點、更快按下合併。同樣的做法也能幫你寫 review 留言、回覆別人的審查意見。但 AI 讀得懂 diff 改了什麼，讀不懂你的商業脈絡與設計意圖，更不該替你寫沒跑過的測試——描述的真假、review 的判斷，最後都得你自己扛。本篇給你可複製的 Prompt 範本與台灣團隊的實際導入做法。

一句「fix bug」為什麼會卡住整個團隊

先講一個場景。某家做電商後台的新創，新人阿哲開了一個 PR，標題寫「fix bug」，描述欄整個空白，底下是四百多行的 diff，動到了訂單狀態機、金流回呼、還有一支共用的工具函式。他覺得程式碼自己會說話，reviewer 讀 diff 就知道了。

結果資深工程師阿凱打開來，第一個反應是：這到底修的是哪個 bug？為什麼要動金流回呼？那支共用函式被改了，會不會影響到其他三個用到它的地方？他一個問題都答不出來，只能在下面留言「這個 PR 在做什麼？可以補一下描述嗎，我不知道從哪開始審」，然後把 PR 退回。阿哲隔天補了兩句話，阿凱又發現測試方式沒寫、風險沒評估，再退一次。一個其實不難的修正，來回三天才合併。

問題從來不是阿哲不會寫程式，是他沒把 reviewer 當人看。審查者打開你的 PR 時，腦袋是一片空白的，他不知道你這三天在想什麼、放棄了哪個方案、為什麼選現在這個做法。PR 描述的工作，就是把你腦袋裡的上下文，用最省對方力氣的方式搬過去。寫得好，reviewer 讀完描述就能開始審；寫得爛，他得先花半小時逆向工程你的意圖，光是這股煩躁就會讓審查品質變差、合併變慢。

這正是 AI 最能補位的地方。工程師不是不知道該寫清楚，是在趕進度的當下懶得停下來組織文字。AI 能把「懶得寫」這個藉口拿掉——你把 diff 和幾句話丟給它，它先幫你生一份結構完整的初稿，你再修。

一份好的 PR 描述長什麼樣

在叫 AI 之前，你得先知道目標長怎樣，否則它給你什麼你都收。一份讓 reviewer 舒服的 PR 描述，通常有這四塊：

• 背景（為什麼要有這個 PR）：這次改動要解決什麼問題、對應哪個需求或 issue。一兩句話，讓對方知道這件事的來龍去脈。
• 改動摘要（做了什麼）：條列這次動了哪些部分、各自做了什麼。不是把 diff 逐行複述，而是用人話講「我在訂單狀態機加了一個 refunding 中間狀態，讓退款流程不會卡在 paid」。
• 測試方式（怎麼驗證的）：你怎麼確認這改動是對的。跑了哪些自動化測試、手動測了哪些情境、在什麼環境測的。這塊讓 reviewer 知道哪些他不用重複驗、哪些還沒被蓋到。
• 風險與待辦（要注意什麼）：這次改動可能影響到誰、有沒有需要特定部署順序、有沒有已知的限制或後續要處理的事。把地雷先標出來，比出事後再解釋強一百倍。

標題也有講究。「fix bug」是最糟的，「修正退款流程」好一點，「修正退款卡在 paid 狀態導致無法退款的問題」最好——一看就知道改什麼、影響哪裡。標題是 reviewer 在一整排 PR 清單裡唯一看得到的東西，值得多花十秒。

可直接複製的 PR 描述 Prompt

知道了目標，就能請 AI 照這個結構產出。這是一份可以直接拿去用的範本，把方括號的變數換成你的內容：

你是一位資深軟體工程師，擅長寫清楚、讓 reviewer 好審的 Pull Request 描述。
請根據以下資訊，產出一份結構完整的繁體中文 PR 描述。

【這次改動做了什麼】
〔用兩三句話描述這次改了哪些部分〕

【為什麼要改】
〔說明背後要解決的問題、對應的需求或 issue 編號〕

【如何測試】
〔你跑了哪些測試、手動驗了哪些情境、在什麼環境〕

【diff】
〔貼上 git diff main...HEAD 的結果〕

輸出要求：
1. 先給一個精準的標題，點出改了什麼、影響哪個範圍，不要只寫 fix 或 update。
2. 內文用以下四個小標分段：## 背景、## 改動摘要、## 測試方式、## 風險與待辦。
3. 改動摘要用條列，每一點用人話講清楚這段程式碼在做什麼，不要逐行複述 diff。
4. 測試方式只寫我提供的內容，不要自己編出我沒提到的測試。
5. 風險與待辦如果我沒特別說，就根據 diff 推測可能受影響的範圍並標為「待確認」，不要當成事實寫。
6. 全程繁體中文、台灣用語，技術名詞保留原文。

幾個關鍵設計說明一下。第一，強制它分成固定四段，你每個 PR 的描述就會長得一致，團隊讀起來省力。第二，第 4 條特別叮嚀「不要編測試」，這是 AI 最愛闖的禍——它會很自然地寫出「已通過單元測試與整合測試」，但你根本沒跑，這種假話一旦被 reviewer 抓到，你整份描述的信任度就歸零了。第三，第 5 條要它把推測標成「待確認」，區分開哪些是事實、哪些是它猜的，你複核時一眼就知道要補哪裡。

產出後別直接送。你自己讀一遍，把 AI 猜不到的東西補上：這個 PR 要先部署後端還是前端、有沒有改到環境變數、跟隔壁同事那條分支會不會衝突。這些只有你知道，也正是描述裡最值錢的部分。

用 AI 寫好 review 留言

PR 的另一半是審查。你當 reviewer 時，心裡明明覺得哪裡怪怪的，但要把它寫成一則對方看了願意改、又不會覺得被冒犯的留言，其實不容易。留言寫得兇，對方防禦心一起，本來三分鐘能改的變成一場拉鋸。

AI 在這裡能幫你把「我覺得這樣不好」翻譯成建設性的表達。給它一個簡單的框架就行：

你是一位資深工程師，正在做 code review。
以下是我想對某段程式碼提出的意見，請幫我改寫成一則專業、對事不對人、
讓對方願意接受的 review 留言。用繁體中文。

我的原始想法：〔例如：這個函式太長了，而且沒處理 null〕

要求：
1. 具體指出問題在哪、為什麼是問題（會有什麼後果）。
2. 給一個可行的建議方向，不要只批評。
3. 語氣客氣但明確，區分「一定要改」和「建議可考慮」。

比方你原本想寫「這寫得也太亂了吧」，透過這個框架，AI 會幫你變成「這個函式包了三件事（驗證、轉換、寫入），之後要改其中一段會不好抽測。建議可以拆成三個小函式，各自好測一點。這點不擋合併，但趁現在拆會比較省事。」同樣的意思，後者對方會照做，前者只會讓人不爽。

要提醒的是，AI 幫你潤飾語氣，但「這段程式碼到底有沒有問題」的判斷是你的。別把整段 code 丟給 AI 說「幫我 review」，然後把它吐的清單原封不動貼上去——那些通用建議很多跟你們的架構脈絡無關，貼上去只會讓被審的人覺得你根本沒認真看。

用 AI 回覆別人的 review

角色反過來，當你的 PR 被退回、底下一長串意見時，AI 也能幫你把回覆整理得有條理。情緒管理是重點：被人一條條挑毛病，難免想反駁，但衝動回覆只會讓討論失焦。

做法是把對方所有意見貼給 AI，請它先幫你分類：哪些你同意、直接改就好；哪些需要進一步討論；哪些你技術上有不同看法、要好好講理由。分完類，每一類的回覆語氣就不一樣——同意的簡短道謝並說會改，討論的把你的顧慮講清楚，不同意的把理由講具體。

阿哲後來就是這樣救回自己的 PR。他把阿凱那串退回意見丟給 AI 分類，發現十條裡有七條是他確實漏掉的（同意就改），兩條是溝通誤會（補一句說明），只有一條是他刻意的設計決定。他針對那一條寫清楚「這裡我故意不用快取，因為退款金額必須讀即時資料，用舊值會退錯錢」——阿凱一看就懂，回了個讚。原本劍拔弩張的來回，變成一次有效的技術對齊。

commit 前的自我檢查清單

在開 PR 之前，很多問題其實可以先自己攔下來。你可以請 AI 拿你的 diff 跑一份上車前檢查：

以下是我準備提交的 diff，請以資深工程師的角度，在我開 PR 之前幫我檢查：
1. 有沒有不小心留下的 console.log、除錯用程式碼、被註解掉的舊碼？
2. 有沒有寫死的密碼、金鑰、測試用網址忘了拿掉？
3. 命名、格式跟這個檔案原本的風格是否一致？
4. 有沒有明顯少處理的邊界情境（空值、錯誤、邊界數值）？
5. 這包 diff 是不是混了不相關的改動，該拆成多個 PR？

〔貼上 diff〕

請條列你發現的問題，每點標明在哪個檔案、為什麼要處理。

這份檢查抓的都是低級但常見的失誤，先自己清一遍，reviewer 就不用浪費力氣挑這些，能把注意力放在真正重要的設計問題上。這也是對審查者最基本的尊重。

常見錯誤

把整包本機改動全丟給 AI。 你 git diff 沒指定範圍，把還沒整理、混了好幾件事的變更全貼進去，AI 產出的描述當然也是一團亂。先確定這條分支的改動範圍乾淨，一個 PR 只做一件邏輯上完整的事。

讓 AI 寫出你沒做過的測試。 這是最傷信任的一種。AI 很會寫「已通過完整測試」，你沒攔就送出去，reviewer 照著審、事後出包，追下來發現測試根本沒跑，你這個人的 PR 以後都會被當成不可信。Prompt 裡一定要禁止它編測試，送出前也要親自確認測試那段是真的。

把 AI 的通用 review 建議整包貼上去。 審別人的 code 時圖快，把 diff 丟給 AI 讓它列一堆「建議加註解、建議寫測試、建議拆函式」的罐頭意見貼上去。被審的人一看就知道你沒動腦，這比不 review 還糟。

送出前不讀。 AI 產的初稿有它的盲點——漏掉部署順序、腦補相依關係、風險評估寫得像模板。你不讀就送，等於把自己的名字掛在一份你沒檢查過的文件上。

AI 幫不上的界線

講清楚哪些事 AI 做不到，比講它能做什麼更重要。

它讀不懂改動的真實意圖與商業脈絡。 AI 看得到 diff 把 if (a) 改成了 if (a && b)，但它不知道你為什麼加這個 b——那是因為上週客訴發現某個 edge case 會多扣一次款。這層「為什麼」永遠要你來補，而它恰恰是整份 PR 描述最值錢的部分。

它不該替你寫沒發生的事實。 測試、部署狀態、與其他 PR 的相依，這些是客觀事實，只能由你陳述。AI 一旦開始幫你「補齊」這些，它產出的就不是描述，是虛構。

機密程式碼不要上傳公用 AI。 含金鑰、客戶個資、公司核心邏輯的程式碼，貼到免費網頁版 AI 等於送出公司。用公司核可的方案、本機模型，或資料政策清楚的整合工具，這是底線不是建議。

最終的審查判斷還是要人。 這段設計合不合團隊的架構方向、這個取捨值不值得、這個 PR 該不該合，都是需要脈絡與經驗的判斷，AI 給不了。它是幫你省下組織文字的力氣，好讓你把腦力花在真正需要判斷的地方，而不是替你做判斷。

把它變成團隊的習慣

單靠一個人寫得好沒用，PR 品質是團隊的事。三個具體做法：一是把上面的 PR 描述 Prompt 存成團隊共用範本，最好做成 PR 樣板（GitHub 的 pull_request_template.md），讓每個 PR 一開就有背景／改動／測試／風險的骨架。二是把「不要讓 AI 編測試」「機密程式碼不上傳」寫進團隊的協作守則，讓新人一進來就知道界線。三是 review 時把 AI 當輔助清單而非結論，人的判斷永遠是最後一關。工具產初稿，規範定底線，判斷靠人——這三件事湊齊，整個團隊的 PR 就會從「猜謎大會」變成「三十秒上手」。

寫 commit、寫 PR、寫 review，其實是同一套能力的不同切面：把腦袋裡的上下文，用最省對方力氣的方式交出去。AI 讓這件事的門檻降到幾乎為零，剩下的就看你願不願意多讀那一遍、多補那一句 why。

下一步

想把整套工程協作流程都用 AI 補起來，可以接著讀 用 AI 寫 Git commit 訊息，把提交歷史也一起整乾淨；如果你的專案還缺一份像樣的說明文件，用 AI 寫 GitHub README 和 用 AI 寫技術文件 能幫你補上；想讓程式碼本身更好審，用 AI 重構程式碼 教你在開 PR 前先把結構理順。更多工程師實戰的 AI 用法，都收在 AgentAI 智庫的教學中心，歡迎逛逛，把每一個開發環節都變順一點。

常見問題 FAQ

延伸閱讀

• 用 AI 寫 Git commit 訊息
• 用 AI 寫 GitHub README
• 用 AI 重構程式碼
• 用 AI 寫技術文件