next-friday/next-friday-skills

Rebut

分類 Pull Request 上的 AI 程式碼審查意見，並嚴謹地回覆它們。根據實際程式碼驗證每個發現，修復真正的問題，用證據駁回誤報，然後在每個討論串中回覆，並標記為自動化分類。人類仍需點擊「解決對話」。

這是人類審查的對應角色，而非其複製品。AI 審查者（如 CodeRabbit 或 Gemini Code Assist）會發布遠多於人類的發現，混合真實錯誤與誤報，並且對儲存庫一無所知。它們不了解您儲存庫的本機設定、慣例或工具，因此會自信地將您儲存庫中正確的模式標記為錯誤。機器人的嚴重性等級不代表其正確性：一個 CRITICAL 可能是誤報，而一個 nit 可能隱藏著真實的錯誤。

為何 AI 審查者需要其專屬的分類流程

• 對儲存庫一無所知。 機器人不載入您儲存庫的本機設定——例如 linter、格式化工具或型別檢查器的設定，無論您使用哪種技術棧——也不了解您的內部規則。它會將您自己工具要求的模式標記為錯誤。真實案例（一個 ESLint 儲存庫）：審查者將 meta.defaultOptions 標記為 CRITICAL「錯誤」，但該儲存庫的 require-meta-default-options lint 規則卻強制使用它。套用該建議會破壞建置。盲目套用與盲目忽略同樣危險。
• 誤報率高。 許多發現是推測性的或僅關乎風格。有些是人類遺漏的真實錯誤。任務是根據證據來區分它們，而非憑感覺。
• 自信地錯誤。 嚴重性標籤僅是啟發式。驗證一個 CRITICAL 需和驗證一個 nit 一樣仔細。

當審查者是人類時

對於每個審查者（機器人或人類），流程是相同的：根據當前程式碼驗證 → 修復或用證據反駁 → 在討論串中以歸因行回覆 → 證明覆蓋率。人類貢獻者或審查者也在分類循環中：當一個人要求修改時，請修復它並回覆，使用與人類審查者在合併時所讀取之稽核軌跡相同的嚴謹度。只有語氣會改變，這是因為人類了解儲存庫，發布更少但訊號更強的發現，而且粗魯的反駁可能會傷害到真人。所以當審查者是人類時：

• 捨棄機器人框架。 不要將他們的審查視為對儲存庫一無所知且充滿誤報；通常並非如此。
• 合作，而非簡短地反駁。 驗證後，修正正確的部分，並用技術性理由反駁錯誤的部分。切勿虛偽地同意，也切勿對同事使用簡短的「誤報」；以非簡短且具技術理由的語氣陳述原因。
• 由您親自發布回覆，並附上歸因行。 您自主分類人類的討論串，與機器人討論串相同：透過分類帳戶發布，並以歸因行開頭，讓讀者看到自動化分類而非維護者自己的同儕審查。將評論與維護者身分區隔開來的這一行，正是讓自動發布至人類討論串變得安全的關鍵。覆蓋率也計入人類討論串（步驟 5.5），因此若人類的發現未被回覆，該輪就不算完成。

以下步驟同時適用於機器人和人類；歸因標記和自動回覆也同時用於兩者。唯一針對審查者的調整是上述的語氣。

預檢

"${CLAUDE_SKILL_DIR}/scripts/preflight.sh"

preflight.sh 確認 gh 已通過身分驗證，且儲存庫具有 GitHub 遠端。若缺少必要條件，它會將修復方式印至 stderr 並以非零狀態碼退出；請轉發該訊息並停止。識別 PR：使用 [pr-number] 參數，否則使用當前分支的 PR（gh pr view --json number）。

步驟 1：收集所有發現

"${CLAUDE_SKILL_DIR}/scripts/gather-review.sh" <pr>

gather-review.sh 會印出一個 REVIEWS 區塊，其中包含每個審查的作者、狀態和內容；以及一個 COMMENTS 區塊，其中包含每個行內評論的作者、path:line、id=<id> 和內容（透過 gh 內建的 --jq），因此不會發明或遺漏任何東西。列出每個發現，包含其作者、path:line、回覆所需的評論 id 以及內容。包含頂層審查摘要和每個行內評論。將每個討論串的作者標記為機器人（透過收集到的輸出中顯示的 [bot] 登入後綴可識別）或人類：兩者都遵循步驟 4-6，而人類討論串則額外採用上述「當審查者是人類時」中的語氣調整。

在分類之前，讓該輪審查塵埃落定。 審查者是非同步觸發的：第二個機器人通常會在幾分鐘後發布其內容，因此在 PR 更新後立即執行的收集動作只會捕捉到目前為止已發布的審查者。在第一次收集之後，使用 gh pr checks <pr> --watch || true 讓該輪審查塵埃落定：它會阻塞直到 PR 的檢查完成，並且在互動式和無頭模式下行為相同，而非同步審查者正是在此視窗中發布內容的（|| true 可防止無檢查 PR 的非零退出被解讀為失敗）。然後重新執行 gather-review.sh；如果它顯示了新的發現，表示該輪仍在進行中，因此請再次監看並重新收集。（如果 PR 沒有檢查，--watch 會立即返回；而僅發布審查的機器人可能根本沒有註冊檢查執行，因此在這兩種情況下，請短暫暫停並不管檢查狀態如何都重新收集。下方關於跨輪次自動化的機制才是針對在此輪次穩定後才發布的審查者的真正後備方案。）僅在重新收集沒有新增任何內容後才開始分類。這將多審查者輪次處理為一次分類流程，而不是從審查者 A 的發現開始，而審查者 B 仍在發布過程中，這會強制進行第二次完整流程。此邊界條件可防止無限期等待；最後一個章節中的跨輪次自動化機制才是針對在此技能退出後才發布之審查者的持久解決方案。

步驟 2：驗證每個發現（此技能的核心）

對於每個發現，針對當前程式碼回答兩個問題，而不是根據機器人的框架：

1. 該問題是否可重現？ 如 ${CLAUDE_SKILL_DIR}/references/debugging.md 所述重現它：在該行開啟檔案、追蹤邏輯、建構機器人所描述的輸入，並檢查實際行為。如果是錯誤，它必須是可示範的。
2. 該建議對於此儲存庫是否正確？ 執行儲存庫定義的相關閘門（其 linter、型別檢查器或測試，以存在者為準）。檢查已記錄的慣例。一個通過機器人檢查但未通過儲存庫閘門的修正，在此處是錯誤的。

一次只更改一件事並重新驗證。不要批次處理。

步驟 3：分類

結論	含義	動作
FIX	真實錯誤，可重現	修復它（步驟 4）
REFUTE	對該儲存庫而言是誤報	回覆並附上證明其錯誤的證據
INTENTIONAL	機器人無法看到的刻意選擇	回覆並解釋該意圖
MINOR	僅關乎外觀，非強制性	記錄它；根據維護者的標準決定修復或跳過

步驟 4：修復有效的發現

• 範圍限於該發現的最小變更。對於錯誤，先撰寫會失敗的測試，觀察它失敗，修復，觀察它通過。
• 執行儲存庫的完整閘門。紅燈的閘門會阻止修復。
• 將整個輪次的所有修復合併為一個 commit 並推送，切勿每個發現一個 commit。 如步驟 2 所述，一次驗證並修復一個發現，但將所有修復暫存並一起提交，然後一次推送，使用維護者的帳戶，也就是擁有該 PR 並發布回覆的同一個帳戶。每個發現都推送一次會將一個審查週期變成好幾個：每次推送都會重新執行 CI 並重新觸發每個機器人，因此五次修復會變成五次 CI 執行和五次重新審查。每輪一個 commit 只需一次 CI 執行和一次重新審查。記錄該單一 SHA；步驟 5 中的每個修復回覆都會引用它。如果推送因非快進而被拒絕（因為遠端分支在輪次期間已移動——例如發布機器人的版本提升或 PR 的「更新分支」合併新增了 commit），請恢復，不要停止：git fetch 然後 git rebase origin/<branch>，重新執行閘門，然後再次推送，切勿使用 --force；rebase 會重寫 commit，因此請重新記錄新的 SHA，並在步驟 5 的回覆中引用它，而不是 rebase 前的舊 SHA。

步驟 5：在每個討論串中回覆

回覆原始評論，使其在行內形成討論串，切勿使用頂層 PR 評論。

在每個回覆的開頭使用相同的歸因行，毫無例外地應用於每個討論串。 您透過維護者的 gh token 發布，因此 GitHub 會顯示他們的頭像，讀者會假定是他們寫的。歸因行會指明代理程式的名稱，並將評論與維護者區分開來，這樣自動化分類就不會被誤認為是維護者自己的審查：

🤖 由 Claude Code 進行的自動化分類，透過維護者的帳戶發布，並非個人審查。

當儲存庫有機器人或機器帳戶時，請改用該身分發布，這樣作者本身就不具個人色彩；歸因行是個人 token 的備案。

將回覆內容寫入一個檔案。歸因行使內容成為多行，這會破壞內嵌的 -f body="..." 引用。一個修復回覆範例：

> 🤖 由 Claude Code 進行的自動化分類，透過維護者的帳戶發布，並非個人審查。

**rebut** 已在 <sha> 中修復：<關於此變更的一行說明>。

一個反駁回覆需陳述證據：

> 🤖 由 Claude Code 進行的自動化分類，透過維護者的帳戶發布，並非個人審查。

**rebut** 不更改此項：<具體原因，例如儲存庫的 lint 規則要求如此；閘門通過>。

每次使用 post-reply.sh 發布一個回覆，一次一個發現：

"${CLAUDE_SKILL_DIR}/scripts/post-reply.sh" <pr> <comment_id> /tmp/reply.md

post-reply.sh 會控制發文節奏以避免 GitHub 的次要速率限制，然後透過從 API 回應中讀取已建立的回覆 ID 來確認它已持久化，並在發文被限流時使用退避策略重試。成功時，它會印出回覆 ID 並以退出碼 0 退出；退出碼 1 表示回覆未發布（不要繼續，請修復並重新執行），退出碼 2 表示參數錯誤。請勿在迴圈中手動撰寫原始的 gh api .../replies 呼叫：連續發文會觸發速率限制並導致回覆消失，這正是此腳本旨在防止的確切失敗。一個發現，一次 post-reply.sh 呼叫，依序進行。

僅回覆，切勿點擊「解決對話」。 透過 API 發布回覆；絕不點擊綠色的「解決對話」按鈕。綠色解決按鈕是供人類審查者使用的，他們透過此按鈕來驗證此技能的工作成果：他們閱讀每個討論串，確認已有回覆，確認摘要評論存在，然後才解決。如果技能自行解決，人類將無法分辨是自己還是代理程式關閉了討論串，這種混淆會導致他們重新檢查或重新執行分類。此技能的完整輸出是回覆加上一個摘要評論；「解決」按鈕始終屬於他們。

不要留下任何空白討論串。 步驟 1 中收集的每個發現都必須獲得回覆：FIX 附帶其 SHA，或 REFUTE / INTENTIONAL / MINOR 附帶其理由。無論來自機器人還是人類，沒有回應的發現都與未分類的工作無異：審查者無法判斷技能是否已執行，因此他們會重新叫用它，導致輪次循環。沉默絕非結論。即使不同意某個發現，仍需要陳述理由，絕不能留下空討論串。

步驟 5.5：斷言覆蓋率、重新驗證 CI，然後捕捉您的修復推送所引發的新一輪

在總結之前：

• 斷言覆蓋率（始終執行）。 發布後，重新查詢 PR 並確認每個發現（無論是機器人還是人類）都已從分類帳戶獲得回覆：

  "${CLAUDE_SKILL_DIR}/scripts/verify-coverage.sh" <pr>
  

  它會為每個發現印出一行（answered / MISSING），然後是 answered N / M。退出碼 0 表示每個發現都有回覆（該輪已覆蓋）；退出碼 1 會列出每個 MISSING 的發現，因此請使用 post-reply.sh 重新發布這些回覆並重新執行，直到它報告 answered N / N 為止；退出碼 2 是讀取/參數錯誤，這不屬於覆蓋率問題，因此請將它傳遞出去。無論結論為何，包括所有發現都是 REFUTE 且未推送任何修復的輪次，都會執行此步驟：一個被忽略的反駁回覆和一個被忽略的修復回覆一樣不可見。在任何發現處於 MISSING 狀態時，切勿繼續進行步驟 6。

• 重新驗證 CI。 當檢查仍在進行中時，使用 gh pr checks <pr> --watch 等待，然後使用 `