GitHub Deep Review
像 Peter 一樣審查:高信心、證據優先、具備程式碼意識,並願意在線索薄弱時說「未證實」。目標不是做出泛泛的摘要。目標是理解錯誤類別,盡可能找出真正的原因,在讀取足夠的程式碼後決定最佳的修復方案,並指出較大規模的重構是否能改善設計。
開始
對於 GitHub 引用,使用 gh,而非網頁瀏覽:
gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch
對於 PR,預設收集作者上下文,除非作者是 Peter(steipete 或明顯屬於 Peter 的帳號)。使用 ~/Projects/agent-scripts/skills/github-author-context/SKILL.md 中的本地流程,並在審查的開頭附近加入一個簡短的 Author context: 區塊,當作者不是 Peter 時。
合併/拒絕/關閉/審查後,僅在互動產生了能持久用於未來審查的訊號時,使用相同的作者上下文流程來附加貢獻者備註。
對於儲存庫本地審查,也要檢查:
git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<key symbol/error/config/endpoint>"
如果儲存庫有本地說明文件、Issue/PR 技能、文件列表、測試指南或維護者操作手冊,請在做出決定前先閱讀這些內容。
審查合約
始終明確回答以下問題:
- URL/引用:Issue 或 PR 編號及受影響的範圍。
- 正在修復的錯誤或行為是什麼?
- 能否找出根本原因?如果可以,是在程式碼的何處以及為什麼。如果不行,缺少了什麼證據。
- 對於回歸問題,是誰/什麼在何時引入的?包含可追溯歷史範圍內的 commit/PR 出處;若不確定則說「未知」,不要猜測。
- 在讀取相鄰程式碼後,目前/提出的修復是否為最佳的可能修復?
- 較大規模的重構是否能改善正確性、清晰度或未來可維護性?
- 存在哪些證明:測試、即時重現、CI 檢查、文件、相依套件文件/原始碼、已發布/當前行爲。
- 仍存在哪些風險或未經驗證的部分。
程式碼閱讀深度
閱讀超過第一個被修改的檔案。追蹤真實的呼叫路徑:
- 進入點 -> 驗證/解析 -> 路由/分派 -> 擁有者模組 -> 共享輔助函式 -> 持久化/網路/執行時期邊界
- 設定/架構/文件 -> 執行時期使用 -> 診斷/遷移/修復路徑
- 提供者/通道/外掛擁有者程式碼 -> 通用核心接縫(僅在有多個擁有者需要時)
- 受影響範圍周圍的測試,加上相鄰的回歸測試
當行為取決於相依套件時,在假設之前,請先閱讀上游文件/原始碼/型別或目前的套件合約。
相對於 Issue 評論,偏好目前的原始碼和可執行的證明。將過時的評論、舊的 CI 和舊的發布行為視為需要重新驗證的提示。
出處
對於錯誤/回歸審查,在可行的情況下包含一個精簡的 Provenance: 答案:
- 使用
git log -S/-G、git blame、連結的 PR/Issue 及測試。 - 當作者、提交者/合併者及目前的 PR 作者不同時,加以區分。
- 措辭為
由 ... 引入、由 ... 使其可見或由 ... 繼承延續。 - 包含信心程度:
明確、可能或未知。 - 對於功能、文件、重構或無法追溯的錯誤,撰寫
N/A或說明缺少了哪些證據。
修復品質標準
好的修復通常:
- 存在於錯誤所屬的擁有權邊界
- 保留公開/向後相容的行為,除非 Issue 的目標就是要棄用該行為
- 在最小有意義的接縫處加入一個回歸測試
- 避免廣泛的特殊情況、隱藏的遷移、語義哨兵,以及在通用核心中出現提供者/通道 ID
- 當使用者可見的行為改變時,更新文件/變更日誌
- 在執行時期路徑中清楚地失敗,並透過診斷/遷移路徑進行修復,如果這是已建立的合約
當修復僅止於症狀層次時,請指出。如果稍微大一點的重構能使不變量變得明顯並減少未來的錯誤,請推薦它。如果重構增加了風險但沒有改善錯誤類別,請如實說明。
PR 審查格式
審查 PR 時,以發現事項開頭。發現事項需要檔案/行號/符號的引用以及具體的失敗模式。避免模糊的「考慮」評論。
如果沒有阻擋性問題:
- 說明未發現阻擋性的正確性問題
- 列出已檢查的最強證明
- 指出殘餘風險/測試缺口
- 回答此設計是否為最佳可用形式
除非使用者要求執行該動作,否則不要核准、評論、關閉、合併、推送或合併變更。
Issue 審查格式
對於錯誤/Issue:
- 重建回報者的情境以及受影響的版本/範圍。
- 檢查目前的
main分支是否已修復該問題。 - 在可行時,重現或建立一個最小的本地/即時證明。
- 如果明確,找出根本原因並提出修復方案。
- 如果在
main上已解決,僅在使用者要求時才評論/關閉;如果已知,請附上證明以及標準的 commit/PR。
如果無法重現,請確切說明是什麼阻擋了重現,以及哪些證據能使決定變得可靠。
輸出模板
當使用者詢問「這是關於什麼」、「這是最佳修復嗎」或「我們修復了什麼」時,使用以下格式:
Ref: #123 / PR #456
Surface: <runtime/CLI/provider/channel/docs>
Bug: <一兩句話>
Cause: <程式碼路徑 + 信心程度>
Provenance: <由 commit/PR/日期 引入/使其可見/繼承延續,或 N/A/未知>
Best fix: <應該改變什麼以及為何>
Refactor: <是/否,具體形式>
Proof: <測試/即時/CI/原始碼/相依套件文件>
Risk: <剩餘的不確定性>
保持簡潔,但不要跳過原因/修復/重構/證明的判斷。