requesting-code-review

概觀

這個技能的用途

requesting-code-review 技能定義了一套清楚、可重複使用的流程，讓你可以在程式碼變更進入主線前，請一個 AI 程式碼審查子代理幫你檢查。它是為 Git 專案設計，並協助你：

• 判斷在什麼時機點應該發起審查（任務完成後、功能完成後、合併前）
• 用 Git SHA 和需求資訊，打包給審查者一份精準的脈絡
• 讓審查者專注在 code diff 上，而不是你的私人對話紀錄
• 按嚴重程度分類回饋，讓你知道現在要修什麼、哪些可以之後再處理

核心理念是：requesting-code-review 強調 早點審查、常常審查，在問題還沒在程式碼庫裡擴散前就先攔截。

適用對象

如果你符合以下情況，這個技能會很適合你：

• 使用 Git 並且經常建立 feature branches 或 PR
• 想要一套 有結構、可重複 的流程來請求 AI 協助程式碼審查
• 採用 subagent-driven development（例如專用的 code-reviewer agent）
• 在乎上線品質：正確性、架構設計、測試與規格一致性

特別適合：

• 想要一個可靠「安全網」的個人開發者
• 沒有專職 code reviewer 的小型團隊
• 以 commit 歷史與 diffs 作為主要真實來源的專案

何時不適合使用

以下情況 requesting-code-review 可能不太適合：

• 沒有使用 Git，或無法取得 commit SHA
• 想要的是一般程式碼產生或重構協助，而不是針對特定變更的審查
• 無法提供清楚的計畫、規格或變更需求

遇到這些情況時，你可能會需要的是更一般性的寫碼或規劃類技能，而不是以審查為中心的流程。

它解決的問題

如果沒有穩定一致的審查流程，開發者常常會：

• 忘記在關鍵節點發起審查
• 提供給審查者的脈絡不足（或塞入過多對話歷史）
• 收到的回饋沒有結構，也很難付諸行動

requesting-code-review 透過以下方式解決這些問題：

• 定義 必經與選擇性審查檢查點
• 標準化審查的輸入資料（Git 範圍、需求、摘要）
• 搭配專用的 code-reviewer 子代理，回傳依嚴重程度排序的結構化回饋

使用方式

安裝

要從 obra/superpowers repository 安裝 requesting-code-review 技能，請使用 Skills CLI：

npx skills add https://github.com/obra/superpowers --skill requesting-code-review
``

這個指令會拉下技能定義以及相關支援檔案，其中包含 `code-reviewer` 子代理模板。

安裝完成後，打開技能目錄，先快速看過以下檔案：

- `SKILL.md` – 請求程式碼審查的高層說明與流程步驟
- `code-reviewer.md` – 真正執行程式碼審查的 agent prompt／模板

### 核心流程一覽
`requesting-code-review` 整體流程分成三個主要階段：

1. **決定什麼時候要審查**
   - 在 subagent-driven workflow 中，每完成一個任務後
   - 完成一個重大功能後
   - 合併到主分支之前
2. **準備審查脈絡**
   - 使用 `BASE_SHA` 和 `HEAD_SHA` 捕捉 Git commit 範圍
   - 摘要你實作了什麼，以及它應該達成什麼行為
   - 填寫 `code-reviewer.md` 中定義的 placeholders
3. **執行審查並依回饋行動**
   - 呼叫 `superpowers:code-reviewer` 子代理
   - 立即修正 Critical 問題，進一步處理前解決 Important 問題，並記錄 Minor 問題

### 步驟一：找出正確的審查時機
依照 `SKILL.md` 的建議，在以下情境使用 `requesting-code-review`：

**必經檢查點：**

- 在 subagent-driven development 中，**每個任務完成後**
- **完成重大功能之後**
- 在 **合併到主分支之前**（例如 `main`、`master`）

**選用但有價值的檢查點：**

- 當你開發到一半覺得自己卡住，需要新的觀點時
- **重構前**，先做一次現有行為的基準檢查
- 修正一個 **複雜 bug 之後**，確認沒有回歸或衍生新問題

把在這些時間點觸發此技能養成習慣，讓程式碼審查變成自動流程，而不是事後才想到。

### 步驟二：取得 Git commit 範圍
審查者需要一份乾淨、範圍明確的 diff。使用 Git SHA 來指定範圍：

```bash
BASE_SHA=$(git rev-parse HEAD~1)  # or origin/main
HEAD_SHA=$(git rev-parse HEAD)

• BASE_SHA 應指向變更的起點 commit，例如前一個 commit 或 origin/main 的 tip。
• HEAD_SHA 則是包含你最新工作成果的 commit。

你可以依照分支策略調整 HEAD~1 或換成其他 base，只要這個範圍能準確涵蓋你想被審查的變更即可。

步驟三：準備審查請求模板

code-reviewer.md 定義了如何與 Code Review Agent 溝通。裡面使用多個 placeholders，在派送子代理前需要先填好。

主要 placeholders：

• {WHAT_WAS_IMPLEMENTED} – 精簡說明你剛完成或修改了什麼
• {PLAN_OR_REQUIREMENTS} – 此實作應該符合的規格、ticket 或商業需求
• {BASE_SHA} – diff 的起始 commit SHA
• {HEAD_SHA} – diff 的結束 commit SHA
• {DESCRIPTION} – 對這次變更的簡短摘要（例如："Add verification function and tests for user signups"）
• {PLAN_REFERENCE} – 指向你的計畫或需求文件的參考資訊

在你自己的工具鏈中，先把這些 placeholders 填好，再用 Task tool 派送 superpowers:code-reviewer 子代理。

步驟四：派送 code-reviewer 子代理

當 Git SHA 與模板都準備完成後：

1. 在你的 orchestration 環境中，使用 Task tool（依 superpowers framework 說明），type 設為 superpowers:code-reviewer。

2. 傳入已填好 placeholders 的 code-reviewer.md 內容。

3. 確認 agent 能取得該範圍的 Git diff：

   git diff --stat {BASE_SHA}..{HEAD_SHA}
   git diff {BASE_SHA}..{HEAD_SHA}
   

   模板會指示使用這些指令，讓審查者專注在 BASE_SHA 與 HEAD_SHA 之間的變更。

這個技能的設計確保審查 agent 只會看到你的實際工作成果（commits 與 diff），而不是整個對話歷史或不相關的脈絡。

步驟五：解讀並採取行動

code-reviewer.md 模板會指示 agent 檢查：

• 程式碼品質（關注點分離、錯誤處理、DRY 原則、邊界案例）
• 架構設計（設計品質、可擴充性、效能、安全性）
• 測試（涵蓋率、整合點、測試品質）
• 需求符合度（是否符合規格、沒有不必要範圍擴張、是否清楚說明破壞性變更）
• 上線準備度（資料遷移、相容性、文件）

回饋會分成幾個等級：

• Critical (Must Fix) – bug、安全性問題、資料遺失風險、功能損壞
• Important (Should Fix) – 架構問題、缺漏的功能、不佳的錯誤處理、測試缺口
• Minor (Nice to Have) – 程式風格、最佳化建議、文件改善

SKILL.md 中對應的處理流程是：

• 先修正所有 Critical 問題再繼續
• 在進一步開發或合併前，解決 Important 問題
• 將 Minor 問題記錄下來，之後整理或安排後續工作
• 如果你認為審查者誤判或缺乏脈絡，要明確提出你的理由並回應

透過這樣的分級，你可以把 AI 回饋轉成具體的待辦清單，而不是一堆模糊的建議。

使用範例流程

一次典型的 requesting-code-review 使用方式可能如下：

1. 你在 feature branch 完成了「Task 2: Add verification function」。

2. 抓取 SHAs：

   BASE_SHA=$(git rev-parse origin/main)
   HEAD_SHA=$(git rev-parse HEAD)
   

3. 在 code-reviewer.md 中填入以下 placeholders：

   • {WHAT_WAS_IMPLEMENTED} = "Verification function for user email flow"
   • {PLAN_OR_REQUIREMENTS} = 對應 ticket／需求的連結或摘要
   • {BASE_SHA} 和 {HEAD_SHA} = 從 Git 取得的值
   • {DESCRIPTION} = "Implement email verification and add tests for edge cases"

4. 使用你的 Task tool 派送 superpowers:code-reviewer 子代理。

5. 你會收到依 Critical、Important、Minor 分組的結構化回饋。

6. 修正 Critical 與 Important 問題後，如有需要，可以在合併前再跑一次流程。

常見問題（FAQ）

requesting-code-review 只能用在 GitHub repository 嗎？

不是。requesting-code-review 是 Git-based，但不綁定 GitHub。它仰賴 commit SHA 與 git diff 指令，只要你能提供 BASE_SHA 和 HEAD_SHA，就能在任何 Git remote（GitHub、GitLab、Bitbucket 或自架）上使用。

我需要把整個開發對話歷史都分享出去嗎？

不需要。requesting-code-review 的一個重要設計原則是：審查者只會收到範圍很明確的脈絡——你實作了什麼、相關需求，以及 Git diff。你的整體對話歷史與思考過程會保持私人，而審查者會專注在實際的程式碼變更。

我應該在工作流程的哪些時間點觸發 requesting-code-review？

建議在以下時機使用 requesting-code-review：

• 在 subagent-driven development 中，每完成一個任務之後
• 完成一個重大功能之後
• 合併到主分支之前

你也可以在卡關時、進行大型重構前、或修完複雜 bug 之後觸發，以提早發現潛在風險。

這跟我現有的 pull request 審查怎麼整合？

requesting-code-review 是用來補強而不是取代人工 PR 審查。你可以：

• 在開 PR 之前先跑這個技能，先抓出明顯問題
• 在人工審查的同時使用，以提升覆蓋率與一致性
• 把這個技能的結構化分類（Critical／Important／Minor）套用到你的 PR 評論風格

因為它是建立在 Git 範圍之上，所以自然可以嵌入 PR 為中心的工作流程中。

我可以自訂 code-reviewer agent 的行為嗎？

可以。code-reviewer.md 是可以調整的模板，你可以：

• 修改針對程式碼品質、架構、測試或安全性的檢查清單
• 加入專案特有的關注點（例如網域規則、效能預算）
• 調整輸出格式，如果你希望不同的嚴重程度分級或額外區塊

只要保留核心結構（明確任務、Git 範圍、嚴重度分類），就能維持審查結果的聚焦與可執行性。

如果審查者給的建議是錯的怎麼辦？

這個技能在設計上就鼓勵你在審查者判斷錯誤或缺乏脈絡時提出理由反駁。把審查視為強而有力的建議，而不是不可質疑的裁決。你可以說明限制條件、設計取捨，或更新你的計畫，讓後續的審查更符合實際情況。

requesting-code-review 會幫我產生測試或直接改程式碼嗎？

不會。這個技能專注在審查而不是產生程式碼。它可以幫你：

• 對特定變更發出有目標性的審查請求
• 收到包含品質、架構與測試等面向的結構化回饋

實際修正與撰寫測試仍由你負責，不過你可以在工具鏈中搭配其他寫碼或測試產生類技能一起使用。

我要如何快速開始？

1. 安裝技能：

   npx skills add https://github.com/obra/superpowers --skill requesting-code-review
   

2. 閱讀 SKILL.md，了解審查檢查點。

3. 查看 code-reviewer.md，確認 agent 的檢查清單與輸出格式。

4. 進行下一個任務或功能開發，取得 BASE_SHA 與 HEAD_SHA，並派送 superpowers:code-reviewer 子代理。

之後，你可以依團隊習慣與品質標準，逐步調整模板與流程，讓 requesting-code-review 更貼合你的開發模式。