Community程式設計與開發github.com

PR 整理工具

在開啟或更新 Pull Request 之前、重構、重新命名、移除或設計變更後,或當被要求整理、清理分支時使用。找出 diff 遺留的內容——過時的引用與舊版措辭、缺少測試或文件的新行為、未接入驗證器/CI 或靜默通過的檢查工具、與原始來源不符的數字或範例,以及即將被提交的個人資訊或憑證——修正事實性問題,標記其餘項目,並附上證據回報。

PR 整理工具 是什麼?

此技能(pr-tidy)是一個用於 AI 編碼代理(如 Claude Code、Cursor 等)的一致性檢查工具,目標是確保分支在變成 Pull Request 前已做好準備。它會分析 diff,然後系統性地檢查整個儲存庫中因 diff 而變得過時或錯誤的地方。支援的任務包括:找出並修復已刪除、重新命名或重新設計項目的過時引用;建立新行為的測試與文件覆蓋地圖;確保檢查工具正確接入 CI/驗證器且能正確失敗;驗證數字與範例的來源;以及在提交前掃描憑證與個人資訊。此工具以不詢問就修正事實性錯誤,並標記需要判斷或設計決策的變更而聞名。它會在最後提供一份結構化報告,包含未驗證的項目與證據,從而減少人工審查的負擔,並維持程式碼品質。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/chiuhoward/skills/tree/HEAD/pr-tidy

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

在你喜歡的 AI 中提問

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

說明文件

PR 整理工具 是做什麼的?

對分支進行一致性清理,使其做好成為 Pull Request 的準備。它會查看 diff 變更了什麼,然後找出 diff 也應該一併變更的所有內容。

只處理分支自己的變更。除非 diff 使其他部分的程式碼變得錯誤,否則不碰觸儲存庫中未受影響的既有問題。

0. 範圍

  1. 先閱讀儲存庫的指示:AGENTS.md、CLAUDE.md、CONTRIBUTING*、README*,以及它們指向的任何文件。

  2. 找出基礎分支與 diff:

    base=$(git merge-base origin/main HEAD)   # 或儲存庫的預設分支
    git log --oneline "$base"..HEAD
    git diff --stat "$base"...HEAD
    git diff --name-only "$base"...HEAD
    
  3. 檢查工作目錄(git status)。保留未提交的變更。如果你要進行的編輯會與未提交的變更重疊,請停止並詢問。

  4. 如果你位於預設分支且無從比較,請停止並告知。

1. 分類 diff

將變更分類為:

  • 新增: 檔案、命令、函式、選項、旗標、設定鍵、環境變數、腳本、技能。
  • 變更: 行為、預設值、API、簽章、規則,以及設計:現在說法不同的指南或規格。
  • 移除或重新命名: 任何被刪除、重新命名、移動或取代的項目。
  • 基礎設施: 建置、CI、測試、工具。

根據以上分類,列出表面:讀者或其他檔案可能引用的每個名稱、路徑、旗標、選項、術語與規則。對於設計變更,也要列出舊觀念的關鍵詞組,而不只是名稱(被移除的「逐層檢查」可能仍被描述為「每個層級下的檢查」)。

2. 過時引用

對於每個被移除、重新命名或重新設計的項目,搜尋整個儲存庫,而不只是變更的檔案:

git grep -n -w "old_name"          # 名稱、路徑、旗標
git grep -n -i "舊設計中的詞組"

在程式碼、註解、測試、文件、README、範例、筆記本、模板、技能檔案、圖表(Mermaid 與 ASCII)以及設定檔中尋找。每個命中要不是更新,就是附上理由標記。

然後為每個新增或變更的項目建立一份覆蓋地圖:它在哪裡被文件化?

覆蓋地圖:
  項目              參考資料   教學   範例   說明
  --new-flag        README      -      -      -
  check_levels.py   scripts/    -      -      -

沒有覆蓋的項目就是缺口;請回報。未經要求,不要撰寫全新的文件頁面。

3. 新行為的測試與文件

對於每個新增或變更的行為:

  • 測試要能驗證該行為,由擁有該行為的層級負責測試,並且涵蓋其失敗路徑(如果相關)。優先採用儲存庫既有的測試模式,以及最能捕捉回歸的最小測試。
  • 文件要在描述舊行為的地方描述新行為:參考資料、範例,以及任何教導舊方式的指南。
  • 僅當你能說出測試會具體捕捉到哪個失敗時,才回報缺少測試。跳過推測性內容與未受影響的既有測試覆蓋缺口。

4. 檢查工具要能明確失敗

對於每個新增或變更的檢查工具、linter、驗證器或檢查腳本:

  1. 接入系統。 找出儲存庫使用的所有進入點:.pre-commit-config.yaml、.github/workflows/*、Makefile、justfile、noxfile.py、tox.ini、pyproject.toml 或 package.json 中的腳本,以及任何會呼叫其他檢查的驗證器。確認該檢查工具至少從其中一個進入點被呼叫。如果沒有,請以與其同類工具相同的方式接入,或將此問題標記。
  2. 對錯誤輸入失敗。 在刻意製造的錯誤輸入上執行該檢查工具;它必須回傳非零退出碼。
  3. 對空輸入失敗。 在空或缺少的輸入(沒有檔案、沒有匹配、沒有解析內容)上執行該檢查工具;它必須回傳非零退出碼,或清楚表示它檢查了但什麼也沒找到,絕不能靜默通過。
  4. 具備測試涵蓋第 2 點和第 3 點。

為了保持此狀態,請加入接入測試,例如 references/test_checkers_wired.py。

5. 數字、版本與範例

列出 diff 觸及的檔案或描述它們的文件中出現的每個數字、版本、日期、URL、引用、命令與程式碼範例。對於每一項:

  • 指出其來源: 產生該數字或資訊的程式碼或命令、設定值、資料集,或是一篇論文及其確切版本(arXiv v3、DOI)。
  • 重新驗證: 重新執行該命令或重新讀取來源。修正它,或如果你無法驗證就標記它。
  • 附帶其條件: 該數字所適用的資料集、設定、機器或時間(例如「機器 M 上 T 小時內的 N 個點」,而不是「N 個點」)。
  • 將外部來源固定到一個版本。
  • 會持續變動的數字最好由程式碼產生(例如使用 cog,並由 cog --check 檢查),而不是手動輸入;建議這麼做。

6. 個人資訊與憑證

檢查分支新增的所有內容,以及即將被新增的每個未追蹤檔案,在它們離開機器之前。這是阻斷性的:以下任何項目都不能「繼續處理就不管了」。

git diff "$base"...HEAD          # 分支上已提交的內容
git diff; git diff --cached      # 尚未提交的內容
git status --short               # 可能會被新增的未追蹤檔案

尋找:

  • 憑證: API 金鑰、令牌、密碼、包含密碼的連線字串、私鑰(-----BEGIN … PRIVATE KEY-----)、雲端與 CI 機密、Session Cookie。
  • 存放它們的檔案: .env*、*.pem、*.key、id_rsa*、credentials*、secrets*、*.p12、服務帳號 JSON、包含令牌的 .npmrc 或 .pypirc、本地設定檔案。
  • 個人資訊: 電子郵件地址、電話號碼、住家或郵寄地址、在範例或測試資料中的真實姓名、帳號或 ID 號碼,以及關於他人的識別資料。
  • 機器詳細資料: 絕對的家目錄路徑(/Users/<name>、/home/<name>、C:\Users\<name>)、內部主機名稱、私有 IP 位址、日誌或筆記本輸出中的使用者名稱。
  • 隱藏位置: 筆記本輸出與元資料、日誌、螢幕截圖、測試固件、產生的報告、提交訊息,以及分支的完整歷史,而不只是最終狀態。

如果儲存庫有掃描工具(gitleaks、detect-secrets、pre-commit run --all-files),請執行它;同時親自閱讀 diff,因為掃描工具會漏掉個人資料。

當你發現問題時:

  • 切勿在回報或提交訊息中重複該值。 指出檔案、行號,以及項目類型(例如 AWS 金鑰、電子郵件地址)。
  • 尚未提交: 移除它,將其移到被忽略的檔案或環境變數中,並在 .gitignore 中加入該模式(如果是檔案的話)。
  • 已在分支上提交: 停止並通知使用者。曾經被提交過的憑證即使改寫歷史也必須撤銷並更換,因為它可能已被複製。未經使用者同意,不要改寫共享歷史。
  • 使用者刻意放置的個人資訊(例如他們自己的公開姓名在授權條款中):請詢問,不要直接移除。

7. 修正或標記

以最小的改動進行編輯,保持檔案的既有語氣、結構與術語。在編輯前完整閱讀檔案。

不經詢問直接修正:

  • 直接來自 diff 的事實性更正;
  • 過時的名稱、路徑、計數、版本與交叉引用;
  • 將新項目加入現有表格或清單;
  • 以其同類工具的模式接入檢查工具。

標記,或先詢問再修改:

  • 敘述性、設計性或政策性的文字,以及任何與分支明顯意圖矛盾之處;
  • 移除與大規模重寫;
  • 安全性敏感的變更;
  • CHANGELOG 條目與版本號更新;
  • 屬於其他人或團隊的檔案;
  • 需要設計決策的新測試。

絕對不要: 改寫或重新產生現有的 changelog 條目、默默地更新版本號、手動編輯產生的檔案(請使用其產生器)、或貼上機密或真實憑證。

8. 用證據驗證

所有主張都必須來自本次工作階段、在最後一次相關編輯之後的最新證據:

  1. 指出證明該主張的命令。
  2. 完整執行它。
  3. 讀取完整輸出與退出碼。
  4. 附上該證據陳述結果,或陳述實際狀態。

執行儲存庫已有的內容:其測試、linter、pre-commit run --all-files、文件建置與連結檢查。未安裝的工具或無法使用的服務是驗證缺口,應如實回報,絕不能當作通過。「應該會通過」與代理的「完成」都不是證據。

9. 回報

範圍:<base>..HEAD,N 個檔案,M 個提交

阻斷性問題
- 路徑:行號 — 憑證或個人資訊的類型(不顯示值),以及需要做的事

已變更
- 路徑:行號 — 變更內容,以及為何 diff 需要此變更

已標記(未修正)
- 路徑:行號 — 問題、未修正的原因、建議的修正

覆蓋缺口
- 項目 — 應被文件化或測試的位置

已驗證
- `命令` → 結果(退出碼)

未驗證
- 什麼項目,以及原因(缺少工具、外部服務、需要決策)

機械層

第 2–6 節的大部分需要判斷力,但其中一部分可以在每次提交時執行。對於沒有此機制的儲存庫,提供 references/pre-commit-config.yaml 中的入門設定:檔案衛生、ruff、codespell、私鑰與機密偵測(gitleaks),以及在推送時執行的 pytest 搭配 diff-cover。lychee 連結檢查與路徑閘控的 CI 更適合放在工作流程中,而不是提交鉤子中。

致謝

本工具經修改後改編自 MIT 授權的技能:docs-sync 和 review-test-coverage,作者 Jakub Merta(jMerta/codex-skills);document-release 中的 diff 分類、覆蓋地圖及修正或標記規則,作者 Garry Tan(garrytan/gstack);以及 verification-before-completion 中的證據規則,作者 Jesse Vincent(obra/superpowers)。來自 Anthropic 的 pr-review-toolkit 代理(anthropics/claude-plugins-official)提供了想法,而非文字。授權條款:THIRD_PARTY_NOTICES.md。

相關技能