rmsaitam/程式碼審查

程式碼審查 是做什麼的？

擔任資深審查者。審查 HEAD 與使用者提供的固定基準之間的差異。產出一個可追溯的產出物：

• CODE-REVIEW.md：審查背景、摘要、規格軸、標準軸、建議驗證、證據、假設、開放問題與可追溯性。

在兩個軸向上分別審查：

• 標準：程式碼是否遵循此儲存庫的慣例、安全政策、測試標準與架構決策？
• 規格：程式碼是否忠實實作了 issue、PRD 或規格？

絕不混合兩個結果。一個變更可以遵循所有慣例，但仍實作了錯誤的需求。

請勿發出自動核准。僅報告風險與必要的驗證。

使用時機

當使用者出現以下情況時使用此技能：

• 要求審查分支、PR、合併請求或進行中的工作；
• 要求審查自某個分支、提交、標籤、日期或 HEAD~N 以來的變更；
• 想知道變更是否遵循儲存庫標準；
• 想知道變更是否實作了 issue、PRD 或規格；
• 想要一份可追溯的審查產出物，並附有證據與建議的驗證。

不使用時機

請勿將此技能用於：

• 完整的、包含 CVSS、CWE 與 OWASP 對應的安全性稽核；請改用 security-audit；
• 產品探索、PRD、SPEC、里程碑或任務分解；請改用 techlead；
• 設計標記、元件庫或無障礙稽核；請改用 design-system；
• 無差異且無固定基準的單行變更；請直接審查或要求提供基準；
• 執行測試、建置、Linter 或部署。此技能負責審查並建議驗證，除非使用者明確要求，否則不會執行它們。

不可協商的規則

• 在審查前先固定基準。當基準缺失時詢問使用者。絕不假設為 main。
• 使用 git rev-parse --verify 驗證參考，並審查 git diff <base>...HEAD。
• 當基準不存在或差異為空時，停止並回報。不要繼續進行專門審查。
• 在分析、發現與報告中，保持規格與標準兩個軸向分離。
• 儲存庫中記錄的標準優先於通用啟發式規則。
• 忽略已由 lint、格式化工具、類型檢查器或 CI 檢測並攔截的問題。
• 區分客觀違規與改進建議。
• 除非涉及安全性、正確性或回歸風險，否則不提出差異範圍之外的重構建議。
• 每項發現都必須有證據：差異片段、檔案與行號、規格要求或可重現的觀察。
• 請勿編造行數、行為或需求。如果證據不足，請寫下備註或開放問題。
• 編輯機密、令牌、個人資料與客戶資料。將值替換為 [REDACTED]。
• 預設為唯讀：請勿修改應用程式程式碼、依賴項、配置、提交或 Pull Request。
• 除非使用者明確要求，否則不要執行測試、Linter、建置或部署。
• 請勿為了加速發布而降低嚴重性。請記錄風險。
• 請勿發出自動核准判定。報告風險與仍需要的驗證。
• 預設以英文撰寫產出物。將 ID、標記、嚴重性值、軸向值與狀態值保留為英文。
• 保留報告範本中的每個機器可讀標記。
• 當剩餘問題不會改變發現、嚴重性或驗證計畫時，停止審查。

模式

在開始前選擇模式，並記錄在產出物中。

• 審查：固定基準、讀取差異、審查兩個軸向，撰寫或更新 CODE-REVIEW.md。
• 驗證：在不重新進行審查的情況下，根據報告合約驗證現有的 CODE-REVIEW.md。

工作流程

按順序遵循以下閘門。請勿跳過任何閘門。

閘門 1：固定審查基準

1. 確定固定點：分支、提交 SHA、標籤、main、origin/main、HEAD~N 或其他明確參考。

2. 如果使用者未提供基準，請詢問應使用哪個基準。請勿猜測。

3. 驗證參考：

   git rev-parse --verify <base>
   

4. 當合併基準可能缺失時，檢查儲存庫是否為淺克隆：

   git rev-parse --is-shallow-repository
   

5. 針對合併基準產生差異：

   git diff <base>...HEAD
   

6. 列出包含的提交：

   git log <base>..HEAD --oneline
   

7. 收集差異大小與變更的檔案：

   git diff --stat <base>...HEAD
   git diff --name-status <base>...HEAD
   

8. 檢查工作目錄：

   git status --short
   

9. 如果存在未提交的變更，詢問它們是否在範圍內。如果是，將 git diff 與 git diff --cached 作為額外的審查範圍包含進來，並記錄此決定。

10. 如果基準不存在、合併基準無法解析或差異為空，則停止並通知使用者。請勿繼續執行閘門 2。

11. 在報告證據部分記錄每個命令、其目標與相關輸出。

當使用者提供日期而非參考時，請明確解析該日期之前的最後一個提交：

git rev-list -1 --before=<date> HEAD

僅在使用者確認後，才將結果提交用作基準。

閘門 2：尋找規格

按以下順序尋找需求來源：

1. 提交、分支名稱或 PR 描述中的 issue 參考（#123、Closes #45、Fixes #78）。
2. 使用者提供的規格路徑。
3. docs/、specs/、.scratch/ 或 tasks/ 中與分支名稱或功能相關的檔案。
4. 詢問使用者規格在哪裡。

讀取來源並提取：

• 問題與預期結果；
• 驗收標準；
• 明確的範圍內與範圍外項目；
• 約束、邊界情況與非功能需求；
• 差異未觸及但必須保留的需求。

將每個需求對應到實作它的檔案、行為與測試。

如果使用者表示沒有規格，請準確記錄：

No specification available; Spec review was skipped.

設定 Spec review: skipped，並且不審查規格軸或編造需求。

閘門 3：載入儲存庫標準

如果存在，請讀取：

• CONTRIBUTING.md；
• CODING_STANDARDS.md；
• ARCHITECTURE.md；
• SECURITY.md；
• docs/adr/ 中的 ADR；
• lint、格式化工具、測試與 CI 配置；
• 儲存庫中近期已核准的範例。

規則：

• 已記錄的儲存庫標準優先於通用啟發式規則。
• 忽略 lint、格式化工具、類型檢查器或 CI 已檢測並攔截的問題。
• 區分客觀違規與改進建議。
• 引用支撐每個標準發現的標準。
• 如果沒有記錄任何標準，則使用通用啟發式規則，並在發現參考中標記為如此。
• 如果標準模稜兩可，請記錄一個開放問題，而不是編造規則。

閘門 4：按類別審查

審查每個變更的檔案與每個有意義的區塊。請勿僅審查新增的行數；請考慮周圍的程式碼以及變更行為的使用者。

規格軸

• 需求滿足：將每個驗收標準對應到其實作與測試。
• 差距或不正確的實作：遺失的需求、部分實作、錯誤行為、與規格矛盾或未測試的需求。
• 額外範圍：在規格之外新增的行為、未經請求的重構、變更的公共合約或範圍蔓延。
• 對於每個差距，請引用確切的需求以及實作失敗的檔案與行號。

標準軸

• 正確性：錯誤、邊界情況、錯誤處理、並行、null/undefined、類型與非預期行為。
• 安全性：注入、身分驗證與授權、輸入驗證、資料暴露、機密、SSRF、XSS、CSRF、不安全的檔案處理與權限邊界。
• 測試：新增或變更路徑的覆蓋率、負面案例、回歸、斷言品質與不穩定性。
• API 與相容性：重大變更、公共合約、版本控管、遷移與消費者相容性。
• 效能：N+1 查詢、不必要的迴圈、分配、快取行為、索引與可避免的同步工作。
• 可維護性：命名、重複、耦合、責任、過早抽象化與領域一致性。
• 可觀測性：日誌、指標、追蹤、警報與影響生產營運的變更中的有用錯誤訊息。

如需詳細檢查清單，請參閱 references/review-checklist.md。

閘門 5：撰寫報告

使用 references/report-template.md 建立或更新 CODE-REVIEW.md。預設位置為目前的工作目錄根目錄。當使用者提供不同路徑時接受。

要求：

• 保留產出物標記與每個必要的章節標記。
• 記錄基準、HEAD、合併基準、提交數量、變更的檔案、標準來源與規格來源。
• 保持規格與標準章節分離。切勿將規格發現移至標準，反之亦然。
• 使用穩定的發現 ID：CR-001、CR-002，依此類推。未記錄變更時，請勿對已核准的發現重新編號。
• 每個發現使用一個嚴重性：blocking、recommended 或 note。請遵循 references/severity-baseline.md。
• 每個發現都必須包含軸向、類別、位置、問題、證據、建議、參考與驗證步驟。
• 計數標記必須與發現完全相符。
• 摘要計數必須與計數標記相符。
• 在可追溯性章節中，將每個發現對應到證據與建議的驗證。
• 說明規格審查是已執行還是已跳過。當跳過時，包含閘門 2 中的確切句子。
• 在沒有發現的類別中寫入 No findings。請勿留下空章節。
• 請勿包含機密、個人資料或客戶資料。將它們編輯為 [REDACTED]。
• 請勿包含核准判定、LGTM 或 Ship it。

閘門 6：驗證

解析驗證器相對於此 SKILL.md 的路徑，並執行：

python3 skills/code-review/scripts/validate_review.py CODE-REVIEW.md

選項：

--strict                     將警告視為失敗。
--json                       發出機器可讀報告。
--min-findings N             要求至少 N 個發現。預設為 0。
--require-spec               當規格審查被跳過時失敗。
--require-standards-sources  當未列出標準來源時失敗。

修復每個錯誤並重新執行驗證器。請勿交付驗證失敗的報告。

如果 Python 不可用，請執行 references/validation-checklist.md 中的手動檢查清單。

閘門 7：交接

報告：

• CODE-REVIEW.md 寫入的位置；
• 審查的基準、合併基準、提交數量與變更的檔案；
• 按嚴重性與軸向分類的發現計數；
• 規格審查狀態與最高風險的規格差距；
• 最高風險的標準發現及其影響；
• 驗證結果；
• 限制、排除的檔案與未執行的檢查；
• 未修改任何應用程式碼、依賴項或配置。

提議修復或補救計畫，但除非使用者明確要求，否則請勿修改程式碼、提交、推送或開啟 Pull Request。

雙軸規則

兩個軸向回答不同的問題，必須保持分離：

軸向	問題	典型證據
規格	變更是否實作了請求的需求？	Issue、PRD、規格、驗收標準
標準	變更是否遵循儲存庫慣例與工程標準？	CONTRIBUTING、ADR、lint/test/CI 配置、程式碼審查

一個發現可能僅在根本原因不同並且補救措施也不同時，才存在於兩個軸向上。否則，將其記錄在擁有根本原因的軸向下一次，並在參考欄位中交叉引用另一個軸向。

範例：

• 變更遵循所有慣例，但遺漏了一個驗收標準：一個規格 blocking 發現，無標準發現。
• 變更實作了需求，但引入了授權繞過：一個標準 blocking 發現，以及一個規格備註，說明需求已實作但不安全。
• 變更使用了一種已記錄但不佳的模式實作了需求：一個標準 recommended 發現，以及一個規格「需求滿足」條目。

產出物合約

CODE-REVIEW.md 以以下內容開頭：

<!-- code-review:artifact type=review version=1 -->

必要的章節使用標記：

<!-- code-review:section id=summary -->
<!-- code-review:section id=context -->
<!-- code-review:section id=spec -->
<!-- code-review:section id=standards -->
<!-- code-review:section id=validation -->
<!-- code-review:section id=evidence -->
<!-- code-review:section id=assumptions -->
<!-- code-review:section id=traceability -->

規格章節也使用狀態標記：

<!-- code-review:spec status=performed -->
<!-- code-review:spec status=skipped -->

計數標記必須與發現相符：

<!-- code-review:counts blocking=1 recommended=2 note=0 -->

每個發現在其標題前立即使用一個標記：

<!-- code-review:finding id=CR-001 axis=standards severity=blocking category=security status=open -->
### CR-001：簡短的發現標題

每個發現主體包含：

• Axis：Spec 或 Standards
• Severity：Blocking、Recommended 或 Note
• Category：spec-gap、scope、correctness、security、tests、api、performance、maintainability 或 observability
• Location：path/to/file.ext:42、path/to/file.ext 或無程式碼位置的規格發現使用 n/a
• Problem：缺陷、風險或差距
• Evidence：差異片段、檔案與行號、規格要求或可重現的觀察

……

[為翻譯而截斷]