requesting-code-review

requesting-code-review 技能總覽

requesting-code-review skill 是一套輕量的工作流程，重點是在對的時間、用對的 diff，並附上足夠的實作背景，來觸發一次聚焦的程式碼審查，讓 reviewer agent 能提出真正有用的回饋。它不是讓你模糊地丟一句「please review my code」，而是要求你提供 commit 範圍、變更摘要，以及原本打算達成的需求。

requesting-code-review skill 實際上會做什麼

requesting-code-review 的核心做法，是要你使用 code-reviewer.md 裡準備好的模板，派發 superpowers:code-reviewer subagent。它的差異化不在花俏的自動化，而在於「怎麼框定 review」。reviewer 看到的是這次工作的成果和原始計畫，而不是你整段對話歷史，這會讓審查範圍更聚焦、回饋也更容易採取行動。

誰適合安裝 requesting-code-review

這個 skill 特別適合以下開發者與 AI agent 使用者：

• 採用以 commit 為單位的工作流程
• 習慣分階段交付功能
• 希望有一個可重複使用的「先 review 再繼續」檢查點
• 會使用 subagent，且需要比一般 prompt 更乾淨的交接方式

如果你常常是在太晚的時候才請人 review，等到多個任務都堆進同一個大 diff 才一起看，那它尤其有幫助。

真正要解決的工作需求

使用者安裝 requesting-code-review，不只是為了「拿到一次 review」。更實際的目的，是降低那些本來可以避免的返工成本：

• 在 merge 前先抓出問題
• 對照原始計畫驗證實作
• 取得依嚴重程度排序的回饋
• 在 reviewer agent 獨立檢查程式碼時，保留主工作流程的上下文

為什麼這個 skill 比一般 review prompt 更有用

requesting-code-review skill 補上了很多臨時 ad hoc prompt 常缺少的實務結構：

• review 時機指引：每完成一個 task 後、重大功能完成後、merge 前
• 明確要求輸入 BASE_SHA 與 HEAD_SHA
• review 模板涵蓋 code quality、architecture、testing、requirements、production readiness 檢查
• 以嚴重程度分桶，後續追蹤更容易

因此，它產出的結果通常會比一句「幫我看看最近改了什麼」更可執行。

採用前最重要的判斷點

要不要用，最大關鍵在於適不適合你的工作方式：這個 skill 最適合用在能清楚用 git range 表示工作的情境，而且你也能簡短說明預期行為。如果你的 branch 很亂、計畫本身不清楚，或變更混進了不相關的修改，review 品質就會明顯下降。

一開始就該知道的重要限制

requesting-code-review for Code Review 本身不是完整的 review system。它不包含腳本、強制規則，也沒有針對特定 repository 的檢查器。它的本質是一種有紀律的 prompting 與 handoff 模式。這很有價值，但你也要預期：品質很大程度取決於 commit 範圍選得好不好，以及需求描述是否清楚。

如何使用 requesting-code-review skill

在你的 skills 設定中安裝 requesting-code-review

如果你使用的是這個 repository 一貫採用的 Skills CLI 模式，可以這樣安裝：

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

如果你的環境裡已經有 obra/superpowers collection，那就直接啟用或引用其中的 requesting-code-review skill 即可。

先看這兩個檔案

如果你想快速評估，建議先從這兩個檔案開始：

1. skills/requesting-code-review/SKILL.md
2. skills/requesting-code-review/code-reviewer.md

SKILL.md 會說明什麼時候該觸發 review。若你更在意輸出品質，code-reviewer.md 其實更重要，因為它明確列出 reviewer 會被要求檢查哪些內容。

先理解它預期的觸發時機

這個 skill 設計上適合在以下時點使用：

• 在 subagent 驅動開發中，每完成一個 task 之後
• 完成一個重大功能之後
• merge 到 main 之前

另外幾個「非必要但很值得用」的時機包括：

• 卡住時，想換一個角度看問題
• 做高風險 refactor 之前
• 修完複雜 bug 之後

如果你只在一條大型 branch 的最後才用它，會失去它很多核心價值。

呼叫前先準備最基本的輸入

這個 skill 在你提供以下資訊時效果最好：

• 實作了什麼
• 計畫或需求是什麼
• BASE_SHA
• HEAD_SHA
• 一段簡短的變更說明

常見的 git 指令如下：

BASE_SHA=$(git rev-parse HEAD~1)
HEAD_SHA=$(git rev-parse HEAD)

如果你是在 feature branch 上工作，而你想讓 review 範圍更完整，origin/main 有時會比 HEAD~1 更適合作為 base。

用乾淨的 diff 範圍，不要只說「最近的修改」

這是 requesting-code-review usage 裡槓桿最高的一個做法。把 review 綁定在 BASE_SHA..HEAD_SHA，遠比叫 agent 自己從 working tree 或對話歷史猜測你改了什麼來得有效。

好的寫法：

• 「Review commits from feature start to current head against the signup flow requirements.」

較弱的寫法：

• 「Can you review my recent auth changes?」

前者能明確縮小範圍，減少 reviewer 靠猜測補上下文。

把模糊目標變成強而有力的 review 請求

像下面這樣的請求太單薄：

Please review my new feature.

根據這個 skill，較強的請求會長這樣：

Review the password reset implementation for production readiness.

What was implemented:
- Added reset token generation and validation
- Added reset email endpoint
- Added UI flow for requesting and completing reset

Plan/requirements:
- Tokens expire after 30 minutes
- Single-use tokens only
- No user enumeration from the request endpoint
- Existing login flow must remain unchanged

Base SHA: abc1234
Head SHA: def5678
Description:
Task 2 of auth hardening. Main changes are in API handlers, email service, and reset form.

這樣 reviewer 才有足夠背景去判斷「做得對不對」，而不只是評論風格。

按照 requesting-code-review 預期的方式派發 reviewer subagent

repository 的指引是：使用 Task tool，指定 superpowers:code-reviewer 類型，並填入 code-reviewer.md 裡的模板。這份模板會要求 reviewer：

• 比對實作與原始計畫
• 檢查 git diff
• 檢查 quality、architecture、testing 與 production readiness
• 依嚴重程度回傳 findings

如果你的 agent 平台支援 subagent，最好讓 review 獨立進行，不要混在同一段工作對話裡。

reviewer 模板最擅長抓出哪些問題

內建 checklist 最擅長浮現這幾類問題：

• 遺漏的需求
• 明顯的 production readiness 缺口
• 測試覆蓋不足
• 架構層面的疑慮
• 危險的 edge case
• 向後相容性或 migration 遺漏

但如果你沒有額外補充，它對特定領域的 compliance、repo-specific 慣例，或更深入的 runtime 驗證就沒那麼專精。

真實專案中建議的 requesting-code-review 工作流

一套實際可行的 requesting-code-review guide 可以這樣跑：

1. 完成一個邊界清楚的 task
2. 找出精確的 diff 範圍
3. 摘要說明意圖與 acceptance criteria
4. 用模板派發 reviewer
5. 先修 critical 和 important 問題
6. 如果修正幅度不小，就再跑一次 review
7. 然後再繼續開發或直接 merge

這個 skill 最有效的用法，是把它當成實作步驟之間的 checkpoint，而不只是最後一道 gate。

能明顯提升輸出品質的小技巧

如果你想拿到更好的 review 結果：

• 使用只包含一個邏輯變更的 diff 範圍
• 不只給功能名稱，也提供 acceptance criteria
• 主動指出高風險區域，例如 migrations、auth、concurrency、caching 或 API contracts
• 說明是否有補測試，以及是哪些類型的測試
• 清楚註明 breaking changes 是預期內還是完全不允許

這些資訊能幫 reviewer 分辨哪些是有意識的取捨，哪些只是意外漏掉。

常見誤用會怎麼拉低價值

如果你的團隊平常就是這樣工作，那 requesting-code-review install 的意義會比較低：

• 一個範圍裡混進很多不相干的變更
• 沒有書面需求
• 幾乎沒有有意義的 git 邊界
• 把這個 skill 當成要取代人工審查或 CI

這些情況下，最好先整理工作流程，不然 review 很容易變得雜訊很多。

requesting-code-review skill 常見問題

requesting-code-review 適合新手嗎？

適合，但前提是你已經懂基本 git 概念，例如 commits 與 SHAs。這個 skill 本身不複雜，但它預設你能說清楚改了什麼、原本預期要做到什麼。新手如果省略這些上下文，還是會拿到回饋，只是可靠度會差一些。

這個 skill 會 review 尚未 commit 的變更嗎？

設計上不是。這個 workflow 是圍繞 BASE_SHA 和 HEAD_SHA 建立的，所以最適合已經 commit 的工作。你可以硬把它改用在 unstaged 或 uncommitted changes 上，但那就偏離了 skill 的核心結構，通常也會讓 review 較難重現。

requesting-code-review 跟直接叫 AI 幫我 review 程式碼有什麼不同？

一般 prompt 很容易產出泛泛而談的 review，因為模型得自己推斷範圍、意圖與 acceptance criteria。requesting-code-review 之所以更好，是因為它要求你明確提供：

• 清楚的 diff
• 實作摘要
• 原始計畫或需求
• 依嚴重程度輸出的格式

因此結果通常更容易信任，也更容易採取後續行動。

什麼情況下不該用 requesting-code-review？

以下情況建議先不要用：

• 你的變更還沒完整到足以評估
• diff 混了好幾個不相干的功能
• 你自己都還不知道預期行為是什麼
• 你現在更需要的是 repo-specific 靜態檢查，而不是判斷型 review

如果你的團隊根本不會依 git commit range 工作，它也不太適合。

它能取代人工 code review 嗎？

不能。最好的定位，是 pre-review，或流程步驟之間的品質關卡。它能提早抓出問題，讓後續的人類 review 更順，但無法取代領域知識、團隊慣例，或組織內必要的審核流程。

requesting-code-review 只適合大型功能嗎？

不是。事實上，小範圍 diff 才是它最能發揮的地方。這個 skill 明確鼓勵及早且頻繁地 review，而這通常比等到最後一次看一個大 diff 更有效。

這個 skill 適合什麼樣的生態系？

這個 skill 最適合放在 obra/superpowers 工作流中，尤其是你已經有在用 subagents 的情況。它比完整的 review framework 輕量，也比自建 review automation 更容易採用，但相對地，防呆與 guardrails 也會少一些。

如何改進 requesting-code-review skill

給 reviewer 更好的需求，不只是更好的程式碼

最常見的失敗模式，其實不是 code 差，而是 plan context 太弱。如果你只寫「implemented notifications」，reviewer 根本無法判斷缺少 retry path 到底是 bug，還是本來就不在範圍內。你應該補上更具體的期待，例如：

• 觸發條件
• 錯誤處理行為
• 向後相容性的預期
• 效能或安全性需求

需求寫得越清楚，review 判斷就越準。

盡量把 review 切成最小但仍有意義的範圍

requesting-code-review skill 在單一 task 或高度相關的一組變更上表現最好。如果同一個 diff 同時包含 schema work、API 變更、UI 更新，還混著不相干的 cleanup，review findings 就會變得很散，也比較難落地。只要有可能，就把工作切成可 review 的單位。

選對 base commit

選錯 BASE_SHA 會導致回饋失真。如果你用 HEAD~1，但整個功能其實跨了六個 commits，reviewer 看到的就太少；如果 base 選得太舊，又會讓 reviewer 看到太多雜訊。你要選的是能對應「這次想被評估的邏輯工作單位」的 base。

不要用空泛佔位內容，改成 reviewer 能在腦中驗證的具體資訊

內建模板使用了這些 placeholders：

• {WHAT_WAS_IMPLEMENTED}
• {PLAN_OR_REQUIREMENTS}
• {BASE_SHA}
• {HEAD_SHA}
• {DESCRIPTION}

如果這次變更有風險，就不要只用一行摘要帶過。請直接寫出預期行為。例如，「prevents user enumeration and invalidates token after first successful reset」就比「added password reset」強很多。

直接告訴 reviewer 風險在哪裡

如果你已經知道高風險面向，請直接講明：

• 「Please pay special attention to race conditions around token reuse.」
• 「Check backward compatibility for existing API consumers.」
• 「Focus on whether tests cover the error path and expiry boundary.」

這樣能幫助 reviewer 集中注意力，更有機會提出真正有價值的 findings。

第一輪 review 後，再把審查強度往上拉

收到第一輪結果後，可以這樣做：

1. 先修掉那些明顯正確的 critical 問題
2. 對看起來不對的 findings 提出質疑
3. 補充原本缺失的需求說明
4. 如果更新後的 diff 變動不小，再跑第二輪 review

這個 skill 本身就鼓勵你在 reviewer 判斷錯誤時提出反駁。這其實是好事，代表它的定位是輔助判斷，而不是取代判斷。

需要時加入 repo-specific 的 review 標準

預設的 code-reviewer.md 已經能涵蓋常見 review 面向，但很多團隊還會需要更多。若想提升 requesting-code-review for Code Review 的實用性，可以加入專案特定的檢查項，例如：

• migration rollout 規則
• observability 要求
• accessibility 預期
• security review 要點
• 特定語言或 framework 的慣例

如果你希望輸出少一點泛化、多一點貼近專案，這通常是最值得做的升級。

注意這些反覆出現的失敗模式

常見的品質下滑，多半來自以下幾個原因：

• 需求缺漏或描述含糊
• commit range 雜訊太多
• 沒有說明預期的非功能性行為
• 累積太多 tasks 之後才一次請求 review
• 把次要建議當成必修項，卻漏看了關鍵設計問題

如果你覺得輸出太淺，先回頭檢查輸入內容，通常就能找到原因。

想提升輸出品質，不只要問缺陷，也要請 reviewer 幫你做判斷

更強的 requesting-code-review usage 方式，是請 reviewer 一起評估取捨，而不只列缺點。像是：

• 「Flag any unnecessary complexity.」
• 「Call out if this should be split before merge.」
• 「Assess whether current tests justify production readiness.」

這會讓 review 從類似 lint 的評論，提升到更接近 release quality 的判斷。

在自己的環境中演進 requesting-code-review 的實際做法

如果你打算認真導入這個 skill，最先該客製化的通常有三件事：

1. 你偏好的 base-commit 選擇規則
2. 一套標準化的 requirements 與 acceptance criteria 格式
3. 針對你的技術棧與 release 流程補充的 checklist 項目

這些補強可以保留 requesting-code-review 的簡潔性，同時讓它在日常交付流程中變得實用得多。