用 AI 寫 Git Commit 訊息與 PR 描述：Conventional Commits 實戰教學

一分鐘重點：把 git diff --staged 的內容貼給 AI，要求它依 Conventional Commits 格式產出提交訊息，你就能在三秒內得到一個格式正確、type 與 scope 都對的標題。但 AI 只看得到「改了什麼」，看不到「為什麼這樣改」——所以最值錢的那行 why，永遠要你自己補。本篇給你可複製的 Prompt 範本、PR 描述範本，以及團隊統一風格的具體做法。

打開任何一個跑了兩年的專案，git log 看下去你會看到一整排這樣的東西：「修一下」「update」「fix bug」「改好了」「再改一次」。半年後某個功能出包，你想用 git blame 找出當初為什麼這樣寫，翻到的卻是一句「調整」。提交訊息寫得爛，等於把未來的自己和同事推進坑裡。

問題是大家都知道 commit 訊息該寫好，但在趕進度的當下，沒人想停下來斟酌字句。這正是 AI 最適合補位的地方：它能在一秒內把你的 diff 翻成一條格式工整的訊息，把「懶得寫」這個藉口拿掉。這篇就教你怎麼把這件事做對，而不是讓 AI 幫你量產一堆漂亮但空洞的廢話。

先搞懂 Conventional Commits 在規範什麼

在叫 AI 之前，你自己得先知道好的提交訊息長什麼樣，否則 AI 給你什麼你都照單全收。

Conventional Commits 是目前最通用的一套提交訊息規範，結構很簡單：

<type>(<scope>): <subject>

<body>

<footer>

拆開來看：

type：這次改動的類別，是固定的幾個關鍵字。最常用的有 feat（新功能）、fix（修 bug）、docs（文件）、refactor（重構，不改行為）、test（測試）、chore（雜項、建置、依賴更新）、style（格式，不影響邏輯）、perf（效能）。
scope：選填，標出這次改動的範圍，通常是模組或功能名稱，例如 (auth)、(checkout)、(api)。
subject：標題，一句話講清楚做了什麼。建議祈使句、50 字內、結尾不加句號。
body：選填，寫「為什麼」這樣改、有什麼背景。這是整條訊息最重要的部分。
footer：選填，放關聯的 issue 編號（Closes #123）或破壞性變更標記（BREAKING CHANGE:）。

一個合格的範例：

feat(checkout): 支援 LINE Pay 結帳

原本結帳只接信用卡，行銷活動需要在七月前上線 LINE Pay，
這版接上 LINE Pay 的 SDK 並處理付款回呼。第三方金流的
逾時時間先設 30 秒，後續觀察再調。

Closes #482

為什麼要這麼講究？因為這套格式是機器可讀的。有了固定的 type，工具可以自動生成 changelog、自動決定下一個版本號（fix 升 patch、feat 升 minor、BREAKING CHANGE 升 major）。就算你沒接這些自動化工具，統一格式光是讓 git log --oneline 變得能掃讀，就值回票價了。

把 diff 丟給 AI 的正確姿勢

關鍵動作只有一個：給 AI 看的是 staged diff，不是工作目錄裡所有亂七八糟的改動。

很多人的失敗就從這裡開始——他們改了一堆東西，連順手調的格式、實驗到一半的程式碼都還在，然後把整包 git diff 丟給 AI，要它「寫個 commit」。AI 看到五個不相干的改動，只好硬擠出一個籠統的標題，於是又生出一條「更新多個檔案」這種廢話。

正確流程是：先用 git add 或 git add -p 把這次「一個邏輯單元」的改動選進暫存區，再取出 staged diff：

# 只看這次要提交的內容
git diff --staged

# 字數太多想先看改了哪些檔案
git diff --staged --stat

把這段 diff 連同規範一起貼給 AI。記住一個原則：一個 commit 只做一件事。如果你發現 diff 大到 AI 處理不動，那不是 AI 的問題，是你這個 commit 該拆了。

可複製的 Prompt 範本

下面這份範本你可以直接存起來，每次只要把 diff 換掉。它的設計重點是：明確給規範、限制 type 清單、要求多個版本、並逼 AI 區分 what 與 why。

你是一位資深工程師，請依照 Conventional Commits 規範，為以下 git diff 撰寫提交訊息。

【格式要求】
- 結構：<type>(<scope>): <subject>，必要時加 body 與 footer
- type 只能用：feat / fix / docs / refactor / test / chore / style / perf
- subject 用繁體中文、祈使句、50 字以內、結尾不加句號
- body 說明「為什麼這樣改」，每行不超過 72 字；若 diff 看不出原因，請標註「（需作者補充 why）」
- 若是破壞性變更，footer 加上 BREAKING CHANGE: 說明

【請給我】
- 提供 2 個版本讓我選
- 標出你推測的 type 與 scope，並簡短說明判斷依據
- 列出你「從 diff 看不出來、需要我補充」的資訊

【這次改動的目的】
（用一句話告訴 AI 你為什麼改，例如：修正購物車金額在折扣後沒重算的問題）

【git diff】
（把 git diff --staged 的內容貼在這裡）

那行「這次改動的目的」是整份 Prompt 的靈魂。只要你願意打一句話交代背景，AI 產出的品質會從「格式對但空洞」直接跳到「可以直接用」。

產 PR 描述也有專用範本，把多個 commit 和背景一起餵進去：

請根據以下資訊，產生一份 Pull Request 描述，使用繁體中文，結構如下：

## 背景與目的
（這個 PR 為了解決什麼問題、對應哪個需求或 issue）

## 主要改動
（條列，每點一句話，從技術角度說明改了什麼）

## 測試方式
（reviewer 要怎麼驗證這個 PR，列出步驟或測試指令）

## 風險與注意事項
（可能影響的範圍、需要注意的設定、待辦或已知限制）

---
【這次 PR 的目的】：（一句話）
【包含的 commit】：（貼上 git log --oneline main..your-branch）
【關鍵 diff】：（貼上重點檔案的 diff，太長就只貼核心部分）

台灣團隊實戰：一句「update」都看不懂的版本歷史，怎麼救回來

台北一家做 B2B SaaS 的新創「碼上科技」，工程團隊從三人長到九人之後，提交歷史徹底失控。技術主管陳柏宇回頭翻 log，發現過去半年的 commit 有將近四成是「update」「fix」「調整」這種無效訊息。最痛的一次是線上結帳出包，他想用 git blame 找出那段邏輯是誰、為什麼那樣寫，結果翻到的是一句「修正問題」，完全沒線索，只能整段重讀程式碼，多花了大半天。

他們的做法分三步。第一步，把規範寫死：在 CONTRIBUTING.md 裡明訂用 Conventional Commits，列出團隊允許的八個 type 和常用 scope（auth、checkout、billing、dashboard 等），不再讓大家自由發揮。第二步，把上面那份 Prompt 範本存成共用的 git 別名 git ai-commit，工程師 stage 完直接跑，AI 吐兩個版本讓他挑，省下逐字斟酌的時間。第三步，裝上 commitlint 配 husky，在 git commit 當下自動擋掉不符格式的訊息，從源頭杜絕「update」再混進來。

兩個月後的結果：新進 commit 的格式合規率從原本的六成多拉到九成八；更實際的好處是，他們第一次能用 git log --oneline 在五分鐘內生出一份給客戶看的版本更新摘要，以前這件事要一個人花半天人工整理。陳柏宇的總結很實在：「AI 不是幫我們寫出更厲害的訊息，是讓『把訊息寫好』這件事的成本低到沒人想偷懶。」

別讓 AI 只說 what 不說 why

這是整篇最重要的一段。AI 會犯的最大毛病，是給你一條讀起來很專業、實際上等於沒寫的訊息。

比方說你重構了一段付款邏輯，AI 看著 diff 寫出：

refactor(payment): 將 processPayment 函式拆成三個小函式

格式完全正確，但這條訊息只是把 diff 用人話重講一遍——任何人點開 diff 都看得到你拆了函式。它沒回答真正重要的問題：你為什麼要拆？ 是因為原本那段太難測試？還是為了之後要接第二個金流？這個「為什麼」，AI 不可能知道，因為它看不到你腦中的設計意圖、看不到你 Slack 上跟人吵過的方案、看不到那張 Jira 票的脈絡。

好的版本應該是：

refactor(payment): 拆分 processPayment 以利接入多金流

原本 processPayment 把驗證、扣款、發票綁在一起，下一階段要
接 LINE Pay 時無法重用扣款邏輯。先拆成三個獨立函式，行為
不變，為下個 sprint 接入第二金流鋪路。

記住這條鐵則：diff 已經寫了 what，commit 訊息的價值在於 why。AI 幫你搞定格式和 what，why 永遠是你的工作。看到 AI 產的 body 只是在複述改動，就是該你動手的訊號。

常見錯誤與限制

把幾個最容易踩的坑列出來，對照檢查：

diff 太大塞爆 AI：一個 commit 包了五件事，AI 只能給籠統標題。解法是 git add -p 拆成多個邏輯獨立的 commit，分開請 AI 寫。commit 該拆的訊號，往往就是「一句話講不完這次改了什麼」。
只說 what 不說 why：如上一段，最常見也最致命。養成在 Prompt 裡先打一句「這次改動的目的」的習慣。
盲信 AI 判的 type：AI 偶爾會把一個其實改了行為的修改判成 refactor，或把修 bug 寫成 chore。type 牽動自動版本號，判錯會讓 release 出錯，務必自己過一遍。
把私有程式碼貼到公開 AI：涉及金鑰、客戶資料、未公開的核心邏輯，用公開網頁版 AI 等於外洩。改用公司核可的方案或編輯器內建工具，並確認資料政策。
AI 看不到設計意圖：這是根本限制，不是用法問題。AI 沒參與你的設計討論、不知道你放棄了哪些方案、不清楚這次改動在整個 roadmap 的位置。這些脈絡只能人工補，AI 補不了。
訊息一致性靠人記不可靠：團隊要的不是每個人都記得規範，而是工具強制。commitlint 擋格式、共用 Prompt 範本統風格、CONTRIBUTING 文件講原則，三者缺一，半年後又會回到「update」滿天飛。

從今天的下一個 commit 開始

不用大張旗鼓改流程。你下一次要 commit 時，做一件事就好：git add 完，把 git diff --staged 貼進上面那份 Prompt，順手打一句「為什麼改」，看看 AI 給你的兩個版本。你會立刻感受到差別——原本要想三十秒的標題，現在三秒就有，而且格式還更工整。

如果你是團隊負責人，今天就把 Conventional Commits 規範寫進 CONTRIBUTING、把 Prompt 範本存成共用 snippet，下週裝上 commitlint。讓「把提交訊息寫好」這件事，從靠自律變成靠工具，你的版本歷史半年後會謝謝你。

想再往上一層，把 AI 整段接進你的開發流程，可以接著看〈寫程式的 Prompt 技巧〉、〈Cursor 怎麼用？〉與〈在終端機部署 Claude Code〉。更多 AI 開發實戰教學，都在 AgentAI 智庫。

常見問題 FAQ

把整個 git diff 貼給 AI 安全嗎？會不會外洩程式碼？

看你用哪個服務。用公開的網頁版 AI 貼公司私有程式碼，等於把原始碼送出公司，多數企業的資安政策不允許。建議改用公司核可的企業版方案、本機模型，或在編輯器內整合的工具（如 Cursor、Claude Code）並確認其資料政策。涉及金鑰、密碼、客戶個資的 diff 絕對不要貼。

Conventional Commits 一定要遵守嗎？不寫 type 會怎樣？

它不是 Git 的硬性規定，而是一套社群慣例。好處是機器可解析：能自動產生 changelog、自動決定版本號（feat 進 minor、fix 進 patch、BREAKING CHANGE 進 major）。如果你的團隊有用 semantic-release 之類的工具，type 就是必填；就算沒有，統一格式也讓歷史好讀好搜尋。

AI 產的 commit 訊息可以直接用嗎？

標題格式、用字可以信，但『為什麼這樣改』這層幾乎都要人工補。AI 只看得到 diff 改了什麼（what），看不到你的設計取捨、放棄了哪個方案、為什麼選現在這個做法（why）。把 why 補上，這個 commit 半年後才救得了人。

diff 很大，AI 說太長處理不了怎麼辦？

這通常是訊號：你這次 commit 包太多東西了。理想的 commit 是一個邏輯單元。先用 git add -p 把無關的改動拆成多個 commit，每個分開請 AI 寫。真的無法拆（例如大量自動格式化），就只貼關鍵檔案的 diff，其餘用文字摘要告訴 AI。

團隊要怎麼統一 commit 風格？

三件事：一是把 Conventional Commits 規範與允許的 type、scope 清單寫進 CONTRIBUTING 文件；二是把產 commit 的 Prompt 範本存成共用 snippet 或 git 別名，大家用同一份；三是裝 commitlint 在 commit 時自動擋掉不合格式的訊息。工具擋格式，Prompt 統風格，文件講原則。

用中文還是英文寫 commit 訊息？

看團隊與專案讀者。對外開源、可能有國際協作者的專案建議英文；純內部、團隊都是台灣人的專案，用繁體中文描述完全可以，type（feat/fix）保持英文即可。重點是團隊一致，不要一行中文一行英文混著來。

延伸閱讀

這篇對你有幫助嗎？

AgentAI 智庫團隊 ✓ 台灣實作團隊

我們是一群專注於 AI Agent、Prompt 與自動化工作流的台灣實作者。每篇教學都附可複製配方、誠實標示實測程度與限制，只分享真正能落地、可直接套用的方法——與其介紹工具，不如教你把事情做完。

關於我們 →看更多教學 →訂閱情報週報 →

每週把這類實戰教學寄給你

訂閱 AgentAI 智庫情報週報，新的 Prompt、AI Skills、工作流與教學第一時間收到。

免費 · 隨時取消