Community程式設計與開發github.com

合併請求備註腳本

為合併請求/拉取請求添加審閱者面向的AI生成變更解釋——包含意圖、前後行為變化以及經過驗證的進入點圖表——作為一個總覽評論、每個變更檔案上的檔案級評論以及非明顯位置的內聯評論,並在每次推送後保持同步。

合併請求備註腳本 是什麼?

此技能旨在解決AI生成程式碼審閱中的核心痛點:審閱者需要耗費大量時間重建作者已知的資訊,例如變更原因、行為變化以及呼叫路徑。它透過三層備註結構自動化這個過程:MR級別的總覽評論提供變更全貌,每個變更檔案都有對應的檔案級評論解釋其意義,僅在非明顯的程式碼片段上添加內聯評論。支援GitLab、GitHub和Bitbucket平台,並提供`annotate`(首次執行)和`sync`(每次推送後更新)兩種模式,確保備註與最新差異保持同步。技能包含嚴謹的預檢流程(確認平台、MR身分、差異範圍)、變更清單構建(透過 `diff_inventory.py` 腳本)、基於 `references/significance-test.md` 的非明顯性判斷,以及跨評論交叉引用功能。其獨特之處在於強制覆蓋每個變更檔案(排除自動生成檔案),對測試檔案提供案例清單而非標準模板,並透過HTML標記實現後續同步,避免手動維護的重複勞動。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/kirill-kolomin/self-descriptive-merge-requests/tree/main/skills/annotate-merge-request

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

為審閱者備註合併請求

審閱者在閱讀AI生成的差異時,大部分時間都在重建作者已知的三件事:為什麼進行此變更、行為發生了什麼變化,以及誰呼叫了這段程式碼。這個技能將這三件事以純語言的形式寫下來,放在合併請求的層級——而不是作為原始碼註解。

備註分為三個層級,各有不同規則:

層級覆蓋範圍承載內容
總覽 - 一個MR級別評論總是整個變更的地圖
檔案 - 每個變更檔案一個評論總是,自動生成檔案除外此檔案變更的含義
內聯 - 錨定在差異行上僅限真正不明顯的位置,有預算限制為何這段程式碼如此寫

檔案覆蓋是無條件的:審閱者開啟差異中的任何檔案時,都必須找到該檔案的解釋。判斷什麼值得解釋、什麼是顯而易見的,在檔案內部應用於方法與個別程式碼塊,從不影響該檔案是否被覆蓋。

操作模式

模式使用時機功能
annotate首次在MR上執行構建完整的備註集合,預覽,取得同意後發布
sync每次推送至MR分支後重新檢查現有備註與新差異的對應關係;僅更新、移除或新增有變動的部分

如果此技能的備註已存在於MR上(透過標記檢測,參見§7),請執行 sync,而非 annotate - 重新執行 annotate 會重複評論。

1. 預檢

開始撰寫之前,先確定:

  1. 平台與MR身分。 git remote -v → gitlab.com/自架GitLab、github.com 或 Bitbucket。然後找到當前分支的開放MR(glab mr view、gh pr view)。如果沒有MR,則停止並說明 - 此技能是為現有MR添加備註,不會建立新的MR。
  2. 差異範圍。 始終使用 git merge-base HEAD origin/<target-branch> → <base>..HEAD。絕不要直接與目標分支頂端比較:否則目標分支上無關的提交也會被算作此MR的變更。
  3. 語言。 使用專案MR中已使用的語言來撰寫備註(檢查現有MR/PR描述與評論)。預設使用使用者與你交談的語言。
  4. 發布權限。 發布到MR是對整個團隊可見的,且會通知審閱者。預設進行乾運行預覽並在使用者同意後才發布。僅在使用者已明確表示不需詢問直接發布時才跳過預覽。

閱讀 references/platform-gitlab.md、references/platform-github.md 或 references/platform-bitbucket.md 以了解確切指令 - 評論API在檔案級別錨定、可解決性與更新語義方面的差異很重要。

2. 建構變更清單

兩個腳本位於此檔案旁的 scripts/ 目錄中。透過絕對路徑呼叫它們,使用此技能自身目錄的路徑來建構 - 運行時的工作目錄是使用者的儲存庫,而非此技能目錄,因此單純使用 scripts/... 路徑會失敗。以下,$SKILL 代表包含此 SKILL.md 的目錄(例如,使用者層級安裝時的 ~/.claude/skills/annotate-merge-request,或從插件載入時的插件 skills/annotate-merge-request)。

python3 "$SKILL/scripts/diff_inventory.py" <base>..HEAD --json > /tmp/sdmr-inventory.json

每個變更檔案會提供:變更類型(新增/修改/刪除/重新命名)、requires_file_comment(僅對自動生成/供應商檔案為 false)、file_fingerprint、以及該檔案的程式碼塊(hunks),包含新區域行號(內聯評論必須錨定的位置)、最近的封閉符號以及不重要訊號。對於規格和測試檔案,它還會輸出 test_cases——檔案中每個案例及其狀態(unchanged / adapted / added / removed),透過比較兩個修訂版本之間的案例主體來計算,而非直接讀取差異。這是供你閱讀的啟發式地圖,不能取代你自己的閱讀——對於你將要描述的任何內容,請實際閱讀差異。

每個程式碼塊的 anchor 是一個建議(其第一個新增行);added_lines 列出該程式塊中所有你可以錨定的行。選擇解釋實際上針對的那一行。

硬性限制:內聯評論只能錨定到出現在差異中的行。 GitLab 和 GitHub 都不允許你在遠離程式碼塊的未變動程式碼上新增評論。任何你想說但MR未觸及的程式碼內容,都應放在檔案級或總覽評論中,絕不放在內聯。

3. 第1層 - 覆蓋每個變更檔案

清單中標記為 requires_file_comment: true 的每個檔案都恰好有一個檔案級評論。沒有例外,沒有預算,沒有關於它是否"足夠有趣"的判斷。

唯一的豁免是自動生成和供應商輸出——鎖定檔案、dist/、快照、程式碼生成、壓縮後的套件、vendor/。清單會標記這些;如果它遺漏了你的專案生成的檔案,也請將其豁免,並告訴使用者應加入哪個模式。

變化的是形式和長度,而不是存在與否:

  • 有實際邏輯變更的檔案使用完整模板(references/annotation-format.md):角色、變更原因、前後對比、從何處到達。
  • 規格或測試檔案改用測試案例列表——它現在包含的每個案例,每個案例都有狀態(unchanged / adapted / added / removed),對於變更過的案例,則提供簡短描述。標準模板不適用於規格:沒有人呼叫它們,所以進入點部分結構上就是空的。清單為你計算了狀態(每個檔案的 test_cases);adapted 案例是審閱者最需要的,因此它們排在最前面,並且必須說明是呼叫形式還是預期結果發生了變化。完整規則在 references/annotation-format.md 中。
  • 機械性檔案提供一行說明,讓審閱者可以自信地跳過:僅導入路徑變更 - 遵循 PricingService 的重新命名;無行為變化。
  • 刪除的檔案提供一行說明它為何被移除以及被什麼取代——這通常是MR中最有用的備註之一。

將這些錨定為檔案級評論(GitHub 上為 subject_type=file,GitLab 上為 position_type=file),而不是錨定到某一列。它們附加到檔案標題,因此不會與程式碼交錯,審閱者在開啟每個檔案時就會看到。如果平台不支援檔案級別錨定,則退回使用檔案的第一個變更行——平台參考文件提供了確切的備用方案。

精確撰寫一行備註是此技能的核心所在。備註量現在會隨著檔案數量而增長,因此用三段文字描述一個機械性檔案是缺陷,而非詳盡。

4. 第2層 - 總覽評論

一個MR級別的評論,作為整個審閱的入口點,結構完全按照 references/annotation-format.md 的規定:

  • 意圖 - 此MR解決什麼問題,用兩三句純語言說明。不要重述差異。
  • 前後行為對比 - 執行中系統的觀察者會注意到什麼。對於新元件,應說"新增"而非編造一個"前"。
  • 進入點圖 - 讀者如何從真實的進入點(HTTP路由、CLI指令、事件處理器、定時任務、匯出的API)到達變更後的程式碼。限制在3層以內;每個變更區域一行,而非每個檔案一行。
  • 閱讀順序 - 應先開啟哪個檔案,哪些是機械性的後續閱讀。
  • 內聯評論索引 - 指向每個內聯備註的連結。

總覽有自己的容量限制(最多7個閱讀順序條目,最多5行行為描述,不列舉每個檔案——這是檔案評論的工作)。這些都在 references/annotation-format.md 中;請遵守它們,否則總覽會變成檔案評論本應防止的文字牆。

驗證進入點圖

切勿猜測呼叫圖。 虛構的呼叫者列表比沒有備註更糟:它自信地錯誤,且審閱者會信任它。對於每個宣稱的邊緣,透過實際搜尋來找到呼叫者(在整個儲存庫中執行 rg -n 'symbolName',包括測試和設定),然後向上追蹤直到到達進入點或3層(以先到者為準)。如果某個符號的呼叫者無法解析——動態分發、DI容器、反射、以字串為鍵的註冊表——則寫下 進入點未能解析(<原因>),而不是編造一個看似合理的鏈條。

5. 第3層 - 內聯評論,僅在程式碼非明顯時新增

這是唯一一個需要判斷的層級。對每個方法和程式碼塊執行 references/significance-test.md 中的顯著性測試。簡短版本如下:

需要備註的情況:當讀者合理會問"為什麼是這樣?"——非顯而易見的意圖、在差異中不可見的行為變化、非局部後果、刻意權衡、不常見的演算法、變通方案、來自檔案外部的限制、或與此MR中其他變更的互動。

跳過的情況:當程式碼對這個程式碼庫的勝任讀者來說不言自明:一個將字串轉為標題大小寫的5-10行輔助函數、一個 DEBOUNCE_MS = 300 常數、一個明顯的空值檢查、一個機械性的測試更新。檔案評論已經覆蓋了檔案;在這裡加內聯評論只會以較低的價值重複。

程式碼的大小不是判斷標準——它的推論距離才是。一個自訂編碼方案中的6行輔助函數需要備註;一個200行生成的快照檔案則不需要。

預算(預設值;使用者可以明確調高):

  • 每個檔案最多3個內聯評論,每個MR最多12個。
  • 這些是上限,而非配額。一個故事已由其檔案評論完全說明的檔案,不需要內聯評論,這是正常情況。
  • 超出預算是個訊號,而非許可:如果一個MR中有超過12個真正非明顯的位置,則該MR過大,或者解釋應放在總覽中,以一個故事的方式講述。請告知使用者。

每個內聯備註使用與檔案評論相同的區段,範圍限定在該程式塊,並保持簡短——3到6行,在狹窄的差異檢視中閱讀。

6. MR內的交叉引用

當一個變更只有與同一個MR中的另一個變更放在一起才有意義時,將它們連結起來。交叉引用通常屬於進入點圖,但也會出現在意圖中("需要是因為<其他檔案>現在傳遞了X")以及前後對比("舊路徑仍然存在,請參閱<其他評論>")。檔案評論是放置它們最自然的地方:此檔案的新合約由 [[ref:order-controller]] 使用。

評論網址在評論發布後才會存在,因此交叉引用需要兩個階段:

  1. 發布每個評論,並在屬於另一個備註的連結位置使用佔位符標記([[ref:<slug>]])。
  2. 收集已建立評論的ID/網址,然後編輯每個內文,將標記替換為真實連結。

在發布前規劃好 slug——每個 [[ref:...]] 標記必須在第二階段解析成功,而發布後評論中殘留的標記是可見的缺陷。第二階段不是可選的。

7. 發布,帶有身分標記

此技能建立的每個評論都以一個在渲染後的Markdown中不可見的標記行結尾:

<!-- sdmr:v1 kind=overview -->
<!-- sdmr:v1 kind=file slug=<slug> anchor=<file> ffp=<file-fingerprint> -->
<!-- sdmr:v1 kind=inline slug=<slug> anchor=<file>@<new-line> fp=<hunk-fingerprint> -->

使用清單中的 file_fingerprint 作為 ffp=,以及程式碼塊 fingerprint 作為 fp=。這個標記是實現 sync 的關鍵:它識別技能自己的評論、每個評論所附加的內容,以及它所描述的程式碼的指紋。絕不要發布沒有這個標記的備註;絕不要編輯人類的評論。

保持備註未解決。 已解決的討論串會摺疊顯示,因此審閱者必須一個一個地展開每個備註——這恰恰隱藏了備註原本要顯示的內容。以開放狀態發布它們,讓審閱者在閱讀時自行解決每個備註;那個點擊是他們自己的"已閱讀"標記。

這種選擇的代價:當專案要求所有討論串在合併前必須解決時(GitLab 的 所有討論串必須解決,GitHub 的 要求對話解決),備註必須在合併按鈕解鎖前解決。每個檔案一個檔案評論現在意味著實際的點擊次數,因此當你檢測到這種設定時,請告知使用者,並提供在最後批量解決的選項。兩個平台的指令都在平台參考檔案中。

8. 每次推送後同步

新的提交會悄悄地使備註失效:評論所描述的程式碼可能已移動、改變含義或消失——而新檔案完全沒有任何覆蓋。每次推送至MR分支後,以 sync 模式重新執行此技能。

python3 "$SKILL/scripts/sync_state.py" --inventory /tmp/sdmr-inventory.json --comments /tmp/sdmr-comments.json

--comments 是可重複使用的參數,接受平台原始 JSON——在 GitHub 上這是兩個呼叫(審閱評論和議題評論),因此需傳入兩個檔案。

它將每個現有備註分類為 ok(錨點和指紋未變 - 保持不變)、moved(程式碼相同,但行號變了 - 重新錨定)、stale(它描述的程式碼已變更 - 重新閱讀並重寫)、或 orphaned(檔案或程式碼塊已不存在 - 刪除)。它還會報告**file coverage**——哪些變更檔案仍無檔案級評論,哪些被豁免——以及現在可以作為內聯評論候選的未覆蓋程式碼塊。

然後:只修復它標記的內容,始終就地改寫總覽評論(它總結整個MR,任何推送都可能使其失效),並重新執行§6的第二階段,使交叉引用連結仍指向有效的評論。檔案覆蓋中的 MISSING 行不是可選工作——一個沒有評論的新檔案正是此技能旨在防止的缺口。請遵循 references/sync-after-push.md 處理強制推送情況、每個平台的已刪除評論處理,以及如何避免攪動實際上未變更的評論。

向使用者提及一次,這需要在每次推送後執行,並且 references/sync-after-push.md 有一個可選的 pre-push 鉤子介紹。

參考文件

  • references/annotation-format.md - 備註結構與預算
  • references/significance-test.md - 計算推論距離以決定內聯評論必要性
  • references/platform-gitlab.md / references/platform-github.md / references/platform-bitbucket.md - 平台特定的 API 指令與限制
  • references/sync-after-push.md - 同步邏輯、強制推送處理與已刪除評論
  • scripts/diff_inventory.py - 變更清單腳本
  • scripts/sync_state.py - 同步狀態腳本

相關技能