用 AI 草擬拉取要求說明：測試、風險與回退都要有真憑實據

要用 AI 草擬拉取要求說明，先凍結 base 和 head 版本，查看真實 diff，並在請 AI 寫正文前準備已核實的輸入表。要求草稿分開寫問題、範圍、非目標、行為、測試、風險、發布和回退。作者對每句話負責；新 commit 改變證據時，必須更新說明。

本流程改善的是覆核溝通，不能取代程式碼覆核。如何使用 AI介紹安全的提示方式，用 AI 輔助編碼和覆核 AI 生成程式碼涉及實作與驗證。

關鍵要點

• 撮要之前，記錄確切的 base 和 head commit。
• 查看有效 diff，包括自動產生的檔案、設定、遷移和測試改動。
• 給 AI 已核實的事實和真實指令輸出，而不是假設。
• 不要聲稱未執行的測試已通過，也不要把推斷變成保安結論。
• 令非目標、風險、部署次序和回退限制清晰可見。
• 每次有實質 commit 後，重新核對說明。

覆核者需要作出甚麼決定？

拉取要求說明應協助覆核者回答三個問題：為何需要這項變更？應檢查哪些行為和風險？有甚麼證據支持合併？逐檔案覆述很少能回答。

GitHub 支援範本、必需覆核人、擁有權規則、草稿拉取要求等方式統一貢獻與覆核。［1］ 只有欄位承載與決策相關的證據時，統一才有用；在每欄貼上同樣含糊的句子並無意義。

草擬前先寫驗收準則：確定用戶、運作人員或開發者層面的結果、預期行為、重要的不變行為和失敗條件。準則仍有爭議時，說明應如實寫出，而非呈現成已定方案。

GitHub 的覆核指引強調提供背景、清楚說明變更做了甚麼，讓覆核者集中精力。［2］ 把覆核者的注意力視為有限資源：先寫語意和風險，再指向相關程式碼。

凍結 base、head 和工作樹

記錄程式庫、目標分支或 base commit、head commit，以及說明只涵蓋已提交的變更，還是也包括一份已覆核的工作樹修補。即使託管介面顯示的是分支名稱，證據筆記也要使用不可變識別碼。

確認比較方向。由 base 到 head 的 diff，回答這項提議相對目標加入了甚麼。與錯誤的 base 比較，可能混入無關工作或遺漏必要背景。

檢查一般原始碼覆核容易遺漏的內容：自動產生的檔案、子模組、鎖定檔、遷移、設定、schema 和資源檔。如屬堆疊式 PR，寫明其依賴關係，以及哪些 commit 屬於這一層。

絕不能把秘密、權杖、私鑰、生產數據、敏感記錄、禁發期內的漏洞細節或無關的客戶資料貼進模型。建立一個有界的證據包，只放撰寫說明所需的材料。

提示 AI 前要讀懂哪些真實變更？

閱讀 diff，並透過入口點、調用方、測試和文件追蹤行為。改名函數可能只是機械改動；一行預設設定卻可能改變每個請求。檔案數目和 diff 大小都不是可靠的影響指標。

檢查程式碼是否實現了所述問題、測試是否真正涵蓋該行為。像審查新增程式碼一樣仔細審查被刪除的程式碼。覆核預設設定和發布途徑，因為休眠的程式碼可能要等開關或部署步驟改變後才影響用戶。

API 或持久化資料要記下兼容性、必需的遷移次序、重試行為和新舊版本並行運作的情況。用戶介面則描述行為，只在 PR 確實改動介面時附上真實介面證據。本文本身不需要截圖，也絕不把虛構介面當作證據。

如果憑現有證據無法判斷行為，就在輸入表寫「未知」。不要讓 AI 用一個看似合理的故事填補空白。

建立核實輸入表

產生段落前，先使用結構化的來源：

欄位	已核實輸入	證據
問題	[觀察到的問題和受影響用戶]	[Issue、重現、需求]
範圍	[包含的行為和組件]	[diff 路徑和驗收準則]
非目標	[明確排除項目]	[設計決定]
行為變化	[之前與之後]	[測試、契約、人工檢查]
涉及組件	[服務、套件、數據、UI]	[diff 清單]
測試及真實輸出	[指令、環境、結果]	[保存的執行記錄]
風險	[失敗模式和影響範圍]	[分析或測試]
遷移	[次序、兼容性、驗證]	[遷移計劃]
發佈	[開關、階段、監察、負責人]	[發佈計劃]
回退	[安全復原方法和限制]	[已測試步驟]
文件	[已更新或無需更新及原因]	[路徑]
關聯 Issue	[固定 ID]	[追蹤系統]

證據要精確：「單元測試通過」應寫成「command 在 head [commit]、[environment] 中執行完成；[count] 個測試通過；[已知排除項目]」。輸出太長時，存入獲批的產物，只引述相關撮要。

非目標保護覆核界線，例如「不遷移歷史記錄」「不改變公共 schema」「不在生產環境啟用該功能」。逐項核實；與 diff 矛盾的非目標，本身就是說明的缺陷。

風險應寫明失敗模式、觸發條件、影響、緩解措施、偵測方式和負責人。「低風險」是結論，不是證據。仍有不確定時就寫出來，並把覆核者引向相關程式碼或測試。

怎樣按結構用 AI 草擬拉取要求說明？

提供已核實的輸入表、選定的 diff 摘錄或撮要、程式庫用語和 PR 範本。把任務限定為組織和措辭。

一個可重用的提示詞是：

只使用所提供的輸入表和證據草擬拉取要求說明。保留確切的 base/head 識別碼、範圍、非目標、行為、指令、輸出、風險、遷移、發布、回退、文件和 Issue ID。不要聲稱未執行的測試已通過。不要根據檔案名稱或 diff 大小推斷保安、效能、兼容性、部署或用戶影響。欠缺證據時標為 Unknown，並向覆核者提問。不要包含秘密、敏感記錄或未公開的漏洞細節。

要求草稿附上主張記錄：

聲明 ID	草稿陳述	證據	狀態	覆核重點
PR-01	[有邊界的陳述]	T-02、D-04	已核實	[路徑或行為]

潤飾前先覆核記錄，刪除證據不足以支持其全部範圍的陳述。一個錯誤路徑的測試不能證明整體可靠；在手提電腦上執行的基準測試，也不能證明生產環境的延遲。

使用面向覆核者的結構

實用的說明結構是：

1. 問題： 觀察到的行為、受影響對象和決策背景。
2. 方案與範圍： 語意層面的做法和包含的組件。
3. 非目標： 刻意的排除項目和後續工作的界線。
4. 行為變化： 之前、之後、條件和兼容性。
5. 驗證： 真實的指令、環境、輸出和人工檢查。
6. 風險與保安： 失敗模式、信任界線、緩解措施和未知項目。
7. 遷移、發布與回退： 次序、負責人、監察和限制。
8. 文件與相關工作： 更新的頁面、Issue 和依賴的 PR。

逐檔案細節只放在有助導航之處。把覆核者引向最重要的路徑或 commit，並說明為何重要。不要把破壞性變更埋在冗長的實作過程敘述之中。

Google 的工程實務指引認為，細小而自成一體的變更更易覆核，也更不易引入缺陷。［3］ 如果說明需要講好幾個不相關的故事，就考慮拆分變更。AI 可改善組織，卻無法令雜亂的範圍變得容易驗證。

怎樣如實報告測試？

區分「已執行並通過」「已執行但失敗」「未執行」和「不適用」，並寫明 head 版本和環境。指令被中斷、結果不穩定、使用了 mock 或無法連接外部依賴時，要說明這個界線。

不要聲稱未執行的測試已通過。行為改變後，不要沒有重新執行相關檢查就照搬早前 commit 的綠色結果。生成的說明可能使用肯定的過去式措辭，因此要把每句驗證描述與保存的輸出對照。

說明某項重要測試為何沒有執行，以及仍有甚麼證據。「未執行，因本機缺少所需平台；必需的 CI 工作是 X」比直接略過缺口有用得多。本地測試、CI、預備環境和生產觀察是不同層次的證據。

AI 輔助產生的測試同樣需要一般覆核。AI 生成測試流程可協助提出測試個案，但只有針對凍結的 head 執行並作語意檢查，才能形成有用的證據。

描述風險而不虛構保證

找出 diff 影響的信任界線、授權改動、敏感資料流、外部調用、背景工作、重試和狀態轉換，既說明改了甚麼，也說明保留了甚麼。

不要只因沒有改動保安相關檔案，就寫「無保安影響」。反過來，也不要在沒有驗證證據時聲稱有漏洞或給出嚴重程度。寫明已覆核的界線：「驗證程式碼未改；本變更修改的是驗證之後的格式化」，這樣更窄，也可檢查。

NIST 的生成式 AI 風險概況涵蓋虛構、私隱、資訊完整性和人工監督。［4］ 對 PR 說明而言，相應的控制是：最少輸入、刪節、不可變的版本 ID、主張與證據的對應，以及有人負責的覆核。

按程式庫的披露流程處理未公開的漏洞資料。公開的 PR 說明可能只需一句有限的陳述，或一條只供獲授權覆核者存取的連結。絕不能讓 AI 決定甚麼可以披露。

發佈和回退應如何如實說明？

如果變更在合併後即時生效，就直接說明。如果它依賴功能開關、設定、遷移、套件發布或多項服務按次序協調，寫明確切的前提和負責人。

以可觀察的訊號和決策門檻界定監察。「密切監察」不是計劃；寫明檢查哪項指標、記錄、警報或用戶回報、檢查多久，以及誰有權叫停發布。

回退必須顧及資料和兼容性。回退程式碼未必能撤銷遷移、外部副作用或已發出的事件。回退不安全時，寫明向前復原、隔離或關閉開關的方法，而非虛構一個簡單的撤銷。

不要在合併前的說明中聲稱已在生產環境驗證。把部署後的檢查列為計劃中的驗收步驟，只有在正確環境實際完成後才更新記錄。

對照 diff 覆核草稿

AI 草擬後，把說明放在確切的 diff 旁閱讀。就每句話判斷它屬事實、推斷、計劃還是未知。事實需要證據，計劃需要負責人，未知需要解決途徑。

檢查清單：

• base 和 head 識別碼是最新的；
• 問題和驗收準則與 Issue 及實作一致；
• 範圍包含每個與行為相關的檔案；
• 非目標沒有被程式碼或設定推翻；
• 前後行為已經示範；
• 測試引述真實指令和實際輸出；
• 風險、遷移、發布和回退都有界線和負責人；
• 文件狀態準確；
• 沒有秘密和敏感細節；
• 覆核者的問題保持可見，沒有被猜測抹去。

作者對說明負責（the author owns it）。覆核者可以質疑，但 AI 無法為遺漏、證據質素或程式庫政策承擔責任。

新提交後要更新哪些內容？

PR 說明與特定版本綁定。有新 commit 時，比較新舊 head，找出哪些主張改變，並重新執行受影響的測試。再次請求覆核前，更新範圍、風險和發布部分。

不要盲目重新產生而丟失覆核背景。保留仍然有效的解釋，清楚標出實質改動，並回覆已解決的問題。範圍大幅擴大時，考慮另開 PR，而不是把原有敘述越拉越長。

合併前最後做一次說明與 head 的核對。部署後，除非程式庫明確以 PR 記錄這類回讀，否則把生產驗證放進相應的發布或運作記錄。

常見問題

AI 可以直接讀 diff 寫完整說明嗎？

它可以根據有界的 diff 草擬，但作者必須追蹤行為、提供真實測試證據，並覆核每項主張。單看 diff 文字，可能看不出執行時或部署背景。

是否列出所有檔案？

不必。先解釋行為和風險，再指出有助覆核的檔案。自動產生的檔案清單不能取代語意層面的範圍說明。

未運行的測試怎麼寫？

標為「未執行」，說明原因，並指出所需環境或後續步驟。絕不能以早前版本或不同平台的結果暗示已經通過。

PR 非目標應該寫甚麼？

列出人們可能合理期待、但這項變更刻意不滿足的內容，並核實 diff 確實守住這些界線。

AI 能評估 PR 安全風險嗎？

它可以整理所提供的證據和問題，但不應虛構保安結論、嚴重程度或披露決定。

PR 說明需要截圖嗎？

只有變更影響可見介面、而且真實證據有助覆核時才需要。使用來自正確版本和環境的真實截圖，並移除敏感資料。

有遷移但不能回退怎麼辦？

清楚寫明這項限制，並記錄已批准的復原或向前修正途徑。不要承諾回退程式碼便能撤銷資料改動。

何時必須更新說明？

任何改變行為、證據、測試、風險、遷移、發布或範圍的 commit 之後都要更新，並在合併候選版本上作最後核對。

來源

1. GitHub Docs, Managing and standardizing pull requests — https://docs.github.com/en/pull-requests/reference/managing-and-standardizing-pull-requests
2. GitHub Docs, Helping others review your changes — https://docs.github.com/en/pull-requests/concepts/helping-others-review-your-changes
3. Google Engineering Practices, Small CLs — https://google.github.io/eng-practices/review/developer/small-cls.html
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 日。