如何用 AI 根據程式碼變更撰寫發佈說明，並由負責人對照交付物批准

要用 AI 根據程式碼變更撰寫發佈說明，先凍結上一版和目前版本的發布界線，建立已核實的變更帳本，並把用戶影響與實作細節分開。只給 AI 已批准的證據，要求每項說明都能對應到拉取要求、commit、Issue、測試或文件。最終文字由發布負責人對照實際交付物核對。

本流程產出面向用戶的發布溝通，不是 commit 撮要。如何使用 AI介紹安全的輸入方式，用 AI 輔助編碼和覆核 AI 生成程式碼則涉及實作工作。發佈說明要在變更界線和證據清楚後才開始寫。

關鍵要點

• 草擬前凍結上一版和目前版本的確切 tag 或 commit。
• 建立帳本，區分程式碼證據與已核實的用戶影響。
• 不要根據檔案名稱、diff 大小或 commit 標題推斷行為。
• 一致地把變更歸為新增、變更、修正、保安、棄用或移除。
• 清楚寫出遷移、已知問題和披露限制。
• 要求發布負責人對照實際交付物和版本批准。

凍結發佈邊界

確定要描述的交付物及其取代的交付物。記錄程式庫、產品或組件、上一版本或 commit、目前版本或 commit、建置識別碼、目標渠道和發布日期。main 這類分支名稱不是穩定界線，草擬期間它可能仍在移動。

盡量用不可變的 tag 或完整 commit 識別碼。一次發布由多個程式庫組成時，為每個程式庫記錄界線，並指出連接它們的組成清單或建置記錄。部署交付物與計劃 tag 不符時，停下來解決。

GitHub Releases 把說明和資源連繫到 tag，能把發布與一般程式庫歷史區分。［2］ GitHub 亦可根據兩個 tag 之間合併的拉取要求和貢獻者自動產生發佈說明。［1］ 這些是有用的輸入，但不能證明哪些行為真正到達用戶，也不能證明拉取要求的標題準確。

驗收準則也要凍結：界定受眾、支援的升級途徑、分發渠道，以及甚麼算用戶可見。內部重構可不寫；預設設定改變、新權限、移除欄位或運作要求，即使 diff 很小也可能必須寫入。

建立變更證據帳本

撰寫正文前，每項候選說明先佔一行：

版本	Commit 範圍	PR 或 commit	關聯 Issue	用戶可見行為	Breaking	Migration	Security	Deprecation	測試證據	文件	負責人
x.y.z	[base..head]	[不可變 ID]	[Issue ID]	[已核實行為]	是/否/未知	[步驟或無]	公開/私密/無/未知	[時間線]	[指令與結果產物]	[頁面]	[姓名]

PR 或 commit 和關聯 Issue 從程式庫記錄填寫，但結果要在程式碼、測試、文件或建置產品中核實。已合併的提議可能被部分回退；Issue 描述的可能是最初問題而非最終方案。

用戶可見行為應回答：誰會察覺、在何種條件下、改了甚麼、需要做甚麼。「重構了快取層」是實作細節；「重複請求現在會在五分鐘內重用有效的快取結果」是行為主張，仍需證據。

測試證據須寫明指令、環境、相關輸出和日期。說不清是哪些測試、針對哪個 commit、失敗項目有否略過時，「測試通過」不足夠。讓環境缺口保持可見；本地成功不等於生產環境成立。

如何從證據判斷用戶影響？

閱讀實際的 diff、變更的契約、遷移、設定、功能開關和文件。變更間接影響行為時，追蹤入口點和調用點。資料或 API 變更要檢查兼容性、預設設定、序列化和升級次序。

別憑檔案名稱推斷行為。名為 fix_login.py 的檔案不能證明登入問題已修正。很大的 diff 可能只是重新格式化自動產生的程式碼，一行預設設定改動卻可能影響每個請求。commit 標題和標籤是索引工具，不是證據。

每項候選說明至少需要一個行為層面的來源：驗收測試、重現的前後對比、獲批規格、可觀察的契約變更或人手驗證記錄。實作證據可作支持，但不能取代面向用戶的主張。

行為未核實時標為「未知」，解決前不寫入公開說明。不要把開發者的預期變成面向客戶的事實。藏在關閉的功能開關後的計劃功能，並不算普遍可用。

變更應如何一致地分類？

使用受控的分類體系：

• 新增（Added）： 新提供的用戶功能。
• 變更（Changed）： 現有行為、預設設定、流程或要求有變。
• 修正（Fixed）： 已核實的缺陷在所述條件下不再重現。
• 保安（Security）： 按披露政策處理的保安相關變更。
• 棄用（Deprecated）： 仍可使用，但已有移除或替代途徑。
• 移除（Removed）： 不再提供。

把分類與語意化版本的決定分開。語意化版本規範針對已聲明的公共 API 界定主、次和修補版本的變化，包括不兼容的變更，以及向後兼容的功能或修正。［3］ 產品可採用其他方案，但應寫明版本號承諾甚麼。

不要只因改了很多檔案就稱為「破壞性變更」。檢查公共契約、持久化資料、設定、自動化、受支援的客戶端和運作程序。相反，新增必填欄位或修改預設設定，即使可以編譯，也可能具破壞性。

棄用說明須寫明受影響的介面、替代方案、首次棄用版本、預計移除的版本或條件和遷移指引。只寫「棄用舊端點」而沒有後續途徑，毫無用處。

用 AI 根據程式碼變更撰寫發佈說明前準備受限證據包

準備一個有界的證據包，包含發布界線、已批准的帳本行、受眾和風格指南、過往用語及要求的輸出結構。排除秘密、憑證、私人客戶資料、敏感記錄、禁發期內的漏洞細節和無關的原始碼。

不要把整個程式庫無限制地交給 AI，問「改了甚麼？」。模型可能偏重易讀檔案，漏掉自動產生或設定帶來的行為，或憑名稱推斷意圖。帳本應先由人和確定性工具建立。

一個可重用的提示詞是：

只用已批准的帳本行草擬發佈說明。保留確切的版本、受眾、條件、遷移步驟、已知限制和證據 ID。不要根據檔案名稱、commit 標題、標籤或 diff 大小推斷行為。該行沒有驗證證據時，不要聲稱已修正。分開寫新增、變更、修正、升級／遷移、已知問題和保安披露界線。用戶影響為「未知」時，略去該主張，並為發布負責人列出證據缺口。

撰寫正文前，要求先交回可追溯表：

說明 ID	草稿陳述	帳本行	受眾	必需動作	驗證狀態
RN-01	[有界的面向用戶陳述]	CH-04	管理員	[步驟或無]	已核實

否決合併無關帳本行或擴大範圍的說明。修好一個邊緣情況，未必推得出「可靠性提升」；「更快」亦需明確指標和實測對比。

怎樣面向用戶而非 diff 草擬？

先寫目標讀者認得出的結果，寫明受影響的功能、條件和需採取的行動。除非類別名稱屬於受支援的公共介面，否則不寫內部類別名稱。

寫「重新打開匯出檔案時，現在會保留所選時區」，而非「更新了序列化器的時區處理」。描述修正時，寫出之前的症狀及在甚麼條件下不再出現。不要透露不必要的利用細節，也不要承諾相關故障不會再發生。

使用以下結構：

1. 重點： 少量重要、已核實的結果。
2. 變更： 新增、變更、棄用和移除的行為。
3. 修正： 已核實的缺陷及其邊界條件。
4. 升級／遷移： 前提、次序、備份和驗證。
5. 已知問題： 已確認的限制和安全的變通方法。
6. 保安披露界線： 現在能說甚麼，獲批的保安公告在哪裏發布。

並非每次發布都需要所有章節。空類別不出現在公開說明，但在帳本保留覆核狀態，令「沒有」屬刻意而非遺漏。

核實升級與遷移

遷移說明應可照做：寫明誰必須操作、適用哪些起始版本、按甚麼次序、需要哪些權限，以及如何確認成功。備份和回退指引只在經測試並受支援時提供。

區分應用程式遷移、資料庫遷移、設定改名、客戶端升級和運作重啟。推出期間新舊版本並存時，說明兼容性限制。不清楚安全次序時，停止發布，向負責人取得指引。

絕不能虛構回退方法。有些資料轉換不可逆，有些保安變更亦不應輕易回退。寫明已批准的復原途徑和上報聯絡人，而非編一條令人安心的指令。

AI 生成測試流程只能作為另一項經覆核的工程活動。生成的測試只有針對凍結版本執行，並有人確認其確實測試了所聲稱的行為後，才算證據。

公開發佈說明可以寫多少安全細節？

與保安和發布負責人協調保安字句。公開說明可以寫「依賴項或防護已更新」，但詳細漏洞資料可能需要獨立的保安公告、協調好的披露日期或針對特定客戶的溝通。

不要把秘密、利用步驟、私下報告或未公布的漏洞細節貼進外部模型，也不要讓 AI 決定嚴重程度、可利用性、受影響版本或披露時間；這些是高度依賴證據、由負責的人作出的決定。

NIST 的生成式 AI 風險概況強調虛構、私隱、資訊完整性和人工監督等風險。［4］ 有界的證據包、逐項主張的可追溯性、存取控制和發布負責人批准，正是在此直接應對這些風險。

「保安披露界線」一節應說明公開說明刻意包括甚麼、哪些留給獲批的保安公告，以及由誰批准這個劃分。沉默不應令人誤以為沒有做過任何保安相關工作。

對照實際交付物覆核

逐行對照確切的發布交付物覆核草稿，而非只對照原始碼分支。確認版本字串、功能開關、打包的依賴項、遷移檔案、文件連結和支援的平台。打包可能排除某項變更時，核實安裝套件本身。

檢查清單：

• base 和 head 識別碼與交付物一致；
• 每項說明都對應到已批准的帳本行；
• 用戶可見行為經過示範，而非推斷；
• 版本和分類標籤符合產品政策；
• 遷移步驟、次序和復原方法已核實；
• 已知問題只含已確認的限制；
• 保安字句符合披露決定；
• 測試寫明實際指令、環境和結果；
• 連結和特定版本文件在本地可解析；
• 發布負責人批准了確切的最終文字。

需要發布負責人批准，因為負責人了解打包、推出和披露背景；作者或模型無法單憑 diff 推斷。

發佈後維護說明

把獲批帳本、提示詞輸入、草稿和最終說明隨發布記錄存檔。主張需要更正時，發布註明日期的更正，而非悄悄改寫歷史，並保留改了甚麼及原因。

新 commit 進入發布時，原有界線即告失效。為新範圍重新產生候選帳本，找出新增和受影響的說明，重新驗證並再次取得批准。不要在已覆核的草稿後追加一句猜測。

發布後覆核回饋。用戶的問題可能揭示遷移步驟不清、條件欠缺或用戶不認識的用語。改進日後範本，但每份歷史說明都與其實際發布版本綁定。

常見問題

可以直接從 Git 歷史生成發佈說明嗎？

它能產生候選清單，但單憑歷史無法證明用戶影響或實際發布的行為。公開草擬前，先建立並核實變更帳本。

GitHub 自動發佈說明夠用嗎？

它適合列出兩個 tag 間合併的工作；發布負責人仍需核實交付物、受眾、行為、遷移、已知問題和披露界線。

每個 commit 都要公開嗎？

不需要。只寫重要的用戶可見行為和必需的運作行動；內部可追溯性另行保存，供審計和除錯。

如何安全描述缺陷修復？

寫出觀察到的症狀、受影響條件和已核實的結果。除非證據支持，不要聲稱整類問題都不會再出現。

變更沒有測試怎麼辦？

使用其他已批准的行為層面驗證，或標為未核實；不要把開發者意圖當作已確認的發布結果。

AI 能選擇語意版本號嗎？

它可按書面政策整理證據，但公共契約有否改變，須由發布負責人判斷並批准版本號。

安全修復要公開嗎？

遵從獲批的披露流程。公開字句、時間、受影響版本和技術細節，都需保安和發布負責人覆核。

Commit 範圍變化怎麼辦？

凍結新範圍，重建受影響的帳本行，重查每項說明並再次取得批准。之前的草稿已不再描述這個確切的交付物。

來源

1. GitHub Docs, Automatically generated release notes — https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes
2. GitHub Docs, About releases — https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases
3. Semantic Versioning 2.0.0 — https://semver.org/
4. National Institute of Standards and Technology, Artificial Intelligence Risk Management Framework: Generative Artificial Intelligence Profile — https://www.nist.gov/publications/artificial-intelligence-risk-management-framework-generative-artificial-intelligence

Sources checked 2026 年 8 月 30 日。