Community程式設計與開發github.com

code-change-review

審查程式碼變更(本地差異、暫存變更、分支、提交範圍或拉取請求)的正確性、安全性、效能、可靠性、相容性、抽象層次、重複性、簡潔性與測試品質,僅針對受影響的語言載入語言特定檢查,並為每個發現加上 [CRITICAL]、[MAJOR]、[MINOR] 或 [NIT] 標籤。

code-change-review 是什麼?

這是一個強大的 AI 代理技能,專門用於審查任何形式的程式碼變更,從本地未提交的修改到 GitHub / GitLab 的合併請求。它模擬資深工程師的審查方式:先精確定位程式碼變更集(使用 git diff、gh pr diff 等命令),然後僅載入變更所觸及語言的參考檔案(透過語言偵測腳本或對照表),以避免不相關的上下文干擾。審查時會按優先順序檢查正確性、安全性、性能、可維護性與測試覆蓋率,每個發現都必須有具體的失效場景與建議修正,並依嚴重程度標記為 [CRITICAL]、[MAJOR]、[MINOR] 或 [NIT]。支援 Cursor、GitHub Copilot、Windsurf、Codex 等 IDE / 編輯器整合,以及透過 GitHub CLI / GitLab CLI 的直接 PR 審查。最終報告以一行結論開頭,並按嚴重性排序發現,確保每條意見都有證據而非主觀偏好。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/OMG-Software/code-change-review-skill/tree/HEAD/skills/code-change-review

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

在你喜歡的 AI 中提問

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

說明文件

程式碼變更審查

像一位強硬的資深工程師那樣審查變更:找出真正重要的缺陷,證明每一個,並以讓作者能快速行動的方式回報。一次包含三個真實錯誤的簡短審查,勝過三十個「可能」的長篇大論,因為每個假陽性都會教會讀者略過你的意見。

工作流程

1. 確定變更集

在閱讀任何程式碼之前,先精確釐清要審查的內容。如果使用者沒有指定,預設為尚未在基底分支上的所有內容。

目標取得方法
未提交的工作git diff HEAD(加上 git status 取得未追蹤檔案,然後閱讀它們)
僅暫存git diff --cached
目前分支git diff $(git merge-base HEAD <base>),其中 <base> 通常是 main/master
提交範圍git diff A..B
拉取請求(編號或 URL)gh pr view <n-or-url> 取得描述、基底與頭部;gh pr diff <n-or-url> 取得差異;gh pr diff <n-or-url> --name-only 取得檔案列表
特定檔案閱讀它們;如有必要,詢問它們從什麼版本變更而來

拉取請求。 「Review PR 123」或「review PR #123」指的是目前儲存庫中的 PR 123。一個 URL(https://github.com/<owner>/<repo>/pull/<n>)可以直接傳遞給 gh,且可以從任何目錄運作,甚至是另一個儲存庫。對於 GitLab 合併請求,請使用 glab mr view / glab mr diff。僅差異本身不足以提供上下文(步驟 3),因此也要閱讀 PR 中各個檔案的版本:

  • 如果 PR 來自目前儲存庫,在不切換分支的情況下擷取它及其基底,放到一個專用參照中,該參照會被強制更新,以便 rebase 後的 PR 取代先前的審查副本。從指向 PR 基底儲存庫的遠端擷取(檢查 git remote -v);在 fork 中,這通常是 upstream,而不是 origin:

    git fetch <remote> <base> +refs/pull/<n>/head:refs/review/pr-<n>
    git rev-parse refs/review/pr-<n>    # 必須等於:gh pr view <n> --json headRefOid --jq .headRefOid
    

    如果擷取失敗或提交不符合 headRefOid,請停止並說明原因,而不是審查錯誤或過時的副本。然後使用 git show refs/review/pr-<n>:<path> 讀取檔案,並與 $(git merge-base refs/review/pr-<n> <remote>/<base>) 進行比較。僅在使用者不介意工作目錄變更時才使用 gh pr checkout <n>。

  • 對於另一個儲存庫,透過 gh api "repos/<owner>/<repo>/contents/<path>?ref=<head-sha>"(需引號,因為 ? 在 zsh 中是 glob 字元)讀取 PR 頭部的檔案,或者如果需要大量上下文,則將其克隆到暫存目錄。

  • 閱讀現有的回饋,以免重複已經提出、回答或解決的意見。gh pr view <n> --comments 僅顯示頂層評論;內聯審閱討論串、它們的回覆以及每個討論串是否已解決,則來自 GraphQL:

    gh api graphql --paginate -F owner=<owner> -F repo=<repo> -F n=<n> -f query='query($owner:String!,$repo:String!,$n:Int!,$endCursor:String){repository(owner:$owner,name:$repo){pullRequest(number:$n){reviewThreads(first:100,after:$endCursor){pageInfo{hasNextPage endCursor} nodes{id isResolved isOutdated path line comments(first:100){totalCount nodes{author{login} body}}}}}}}'
    

    --paginate 會追蹤超過前 100 個的討論串。一個 comments.totalCount 超過 100 的討論串還有更多回覆;在依賴該討論串之前,請使用 node(id:<thread id>){... on PullRequestReviewThread{comments(first:100,after:<cursor>){…}}} 來擷取它們。

同時取得意圖:PR 描述、提交訊息、連結的 issue,或者如果不存在,則用一行詢問使用者。如果不了解程式碼預期要做什麼,就無法判斷它是否正確。

對於非常大的變更(超過約 1,500 行變更),請先進行分類。按風險對檔案進行排序(認證、支付、資料遷移、並發、公開 API 以及任何被刪除的內容優先於文件、生成的程式碼和鎖定檔案),並說明哪些檔案得到了較輕微的檢查。

2. 為變更觸及的內容載入語言指南

僅載入變更集中語言和檔案類型的參考檔案,絕不載入全部。每個檔案都會增加上下文,從而排擠您正在審查的程式碼。

如果 Python 可用(python 或 python3),請執行偵測器:

python <skill-dir>/scripts/detect_languages.py --git <base>   # 分支 vs 基底
python <skill-dir>/scripts/detect_languages.py --git HEAD     # 未提交的工作
python <skill-dir>/scripts/detect_languages.py --git <remote>/<base> --head refs/review/pr-<n>   # 已擷取的 PR
git diff --name-only ... | python <skill-dir>/scripts/detect_languages.py   # 任何檔案列表

對於拉取請求,請使用 --head 搭配步驟 1 中擷取的參照。偵測器隨後會從 PR 的提交中讀取 shebang,而不是從您的工作目錄讀取,因為工作目錄可能缺少 PR 的新腳本或包含不同版本。對於另一個儲存庫中的 PR,gh pr diff <url> --name-only | python <skill-dir>/scripts/detect_languages.py 會提供檔案列表,但無法查看檔案內容。檢查列表中每個無副檔名檔案的第一行,無論是否已對應(migrations/ 下的 Python 腳本已對應到 sql.md,但仍需要 python.md):在 PR 頭部讀取它,或者如果 PR 刪除了它,則在基底讀取它,並使用下面的 shebang 表格進行路由。

它會列印要讀取的參考檔案以及觸發每個參考檔案的已變更檔案。如果沒有 Python,請使用此表格,它與偵測器完全匹配。檔名比對不區分大小寫。

已變更的檔案讀取
.py, .pyi, .pyw, .ipynb, pyproject.toml, setup.py, setup.cfg, requirements.txt, Pipfile, Pipfile.lock, poetry.lock, uv.lockreferences/languages/python.md
.js, .jsx, .mjs, .cjs, .ts, .tsx, .mts, .cts, .vue, .svelte, .astro, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, tsconfig.jsonreferences/languages/javascript-typescript.md
.go, go.mod, go.sum, go.workreferences/languages/go.md
.rs, Cargo.toml, Cargo.lockreferences/languages/rust.md
.java, .kt, .kts, .scala, .sc, .groovy, .gradle, pom.xml, build.gradle, settings.gradle, gradle.propertiesreferences/languages/java-kotlin.md
.cs, .fs, .fsx, .vb, .csproj, .fsproj, .vbproj, .sln, .razor, .cshtml, Directory.Build.props, Directory.Packages.props, NuGet.config, global.jsonreferences/languages/csharp-dotnet.md
.c, .h, .cc, .cpp, .cxx, .c++, .hpp, .hh, .hxx, .inl, .ipp, .m, .mm, CMakeLists.txt, Makefile, meson.build, conanfile.txt, vcpkg.jsonreferences/languages/c-cpp.md
.rb, .erb, .rake, .gemspec, .ru, Gemfile, Gemfile.lock, Rakefile, config.rureferences/languages/ruby.md
.php, .phtml, composer.json, composer.lockreferences/languages/php.md
.swift, .pbxproj, Package.swift, Package.resolved, Podfilereferences/languages/swift.md
.sql, .psql, .pgsql, .ddl, 以及任何位於 migration/, migrations/, migrate/, alembic/versions/, flyway/, liquibase/ 下的檔案references/languages/sql.md
.sh, .bash, .zsh, .ksh, .fish, .ps1, .psm1, .psd1, .bat, .cmdreferences/languages/shell.md
.tf, .tfvars, .hcl, .dockerfile, Dockerfile, Dockerfile*, Containerfile, .dockerignore, compose*.yml, compose*.yaml, docker-compose*.yml, docker-compose*.yaml, Chart.yaml, values.yaml, kustomization.yaml, .gitlab-ci.yml, azure-pipelines.yml, bitbucket-pipelines.yml, Jenkinsfile, 任何位於 .circleci/ 下的檔案,以及 .github/workflows/, .github/actions/, k8s/, kubernetes/, helm/, charts/, manifests/, deploy/, deployment/, kustomize/, argocd/ 下的 YAML 檔案references/languages/infrastructure.md

沒有副檔名的檔案會根據其 shebang 行(#!/usr/bin/env deno, #!/usr/bin/python3)上的直譯器進行路由。版本後綴會被忽略。

Shebang 直譯器讀取
pythonreferences/languages/python.md
node, deno, bun, ts-node, tsxreferences/languages/javascript-typescript.md
rubyreferences/languages/ruby.md
phpreferences/languages/php.md
sh, bash, zsh, ksh, dash, fish, pwshreferences/languages/shell.md

一個檔案可能需要兩個參考。Rails 或 Alembic 遷移需要其語言檔案和 sql.md,偵測器會報告兩者。沒有參考檔案的語言仍會得到完整的審查。下面的通用角度涵蓋了它,您應該應用您對該語言常見陷阱的了解。嵌入式語言也計算在內:Python 中的 SQL 字串,或以 Go 建構的 shell 命令,是載入 sql.md 或 shell.md 的理由。

3. 建立差異之外的上下文

差異顯示了變更的內容,而不是它影響的內容。在判斷任何事之前:

  • 閱讀每個區塊的周圍程式碼,而不僅僅是已變更的行。許多錯誤存在於新行與舊行之間的互動方式。
  • 尋找每個已變更函式、型別、架構、配置鍵或端點的呼叫者和依賴者(grep, LSP 查找引用)。爆炸半徑從差異中是看不見的。
  • 了解專案慣例: linter 和格式化工具配置、CLAUDE.md/CONTRIBUTING.md,以及附近程式碼處理錯誤、記錄和測試的方式。根據這個程式碼庫來判斷一致性,而不是根據一般的品味。
  • 在接受新的實用程式碼之前搜尋現有的輔助函式。 重複實作儲存庫中已有的內容,只有在檢視差異外部時才會顯現出來。

4. 按角度審查,依優先順序

從這個清單的頂部開始往下進行。第一層的錯誤比任何數量的第三層註記都更重要。references/review-angles.md 有每個角度的完整檢查清單;對於任何非平凡的審查,請閱讀它。

  1. 是否正確? 正確性與邊界情況、意圖忠實度(它是否完全按照其所聲明的那樣做?)、錯誤處理與失敗模式、並發與共享狀態、對呼叫者的爆炸半徑。
  2. 是否安全發布? 安全性、API/架構/有線協定相容性、資料完整性與遷移、可操作性(部署、回滾、可觀測性)、新的依賴項、隱私。
  3. 是否是好程式碼? 效能與效率、抽象層次(修正是否在正確的層級?)、重複性與重用、簡潔性 vs 過度設計、與慣例的一致性、可讀性。
  4. 是否經過驗證? 實際上會因缺少變更而失敗的測試、保持同步的文件與註解。

在這些角度內應用已載入語言檔案的檢查。它們是這些問題在該語言中的具體形式。

5. 在報告之前驗證每個發現

對於每個候選發現:

  • 寫下失敗情境: 具體的輸入或狀態,然後是錯誤的結果。如果您無法做到,那很可能不是一個錯誤。
  • 重新閱讀程式碼以檢查問題是否已經被處理:上游的保護、驗證器、排除該問題的型別、涵蓋該問題的測試。
  • 執行它,如果成本低且安全(單元測試、REPL 片段、型別檢查器或 linter)且發現不確定。
  • 評定信心: 已確認(已追蹤或重現)或 合理(可信的路徑但無法完全證明)。放棄任何更弱的結果。如果某些事不明確但提出來無害,則以問題的形式提出,而不是斷言一個錯誤。

6. 報告

使用 references/reporting.md 中的嚴重性標籤、評論格式和輸出模板。簡而言之:

  • 以一行結論開頭:是否安全合併,以及(如果有的話)最大的問題。
  • 每個發現都以它的嚴重性標籤開頭:[CRITICAL], [MAJOR], [MINOR] 或 [NIT],然後是一行主張及其 file:line。主體按此順序解釋:問題是什麼,為什麼它是個問題(具體的失敗情境),以及(只要您能提供)建議的修正或改進。
  • 將發現按最嚴重的優先列出。預設上限約為 10 個。提及您省略了多少較低嚴重性的項目,並在使用者要求時列出它們。
  • 除非沒有真正的缺陷,或者使用者要求進行徹底檢查,否則不要包含 [NIT]。
  • 以您未涵蓋的內容結束(略過的檔案、無法執行的內容)。誠實的範圍說明是審查的一部分。

在拉取請求上發布評論時,使用相同的標籤優先格式,以便發現項在報告和 PR 上看起來一致。僅在使用者要求時才發布到 PR;references/reporting.md 顯示瞭如何將它們作為一個帶有內聯評論的審查來發布。

如果主機提供了結構化的發現工具,請以相同的順序透過它報告,而不是列印列表,並且仍然以每個發現摘要的標籤開頭。

原則

  • 證據重於意見。 每個發現都引用程式碼。沒有理由的「考慮 X」是雜訊。
  • 審查變更,而不是程式碼庫。 僅在變更使既有問題變得更糟或依賴它們時才標記既有問題,並將其標記為既有的。
  • 尊重作者的選擇。 一個不同但同樣有效的方法不是一個發現。只有在您能指出具體成本時才提出異議。
  • 除非被要求,否則不要在審查期間修復。 建議修正;讓使用者決定是否應用它們。

相關技能