code/skills/code-review/SKILL.md

name, description

name	description
code-review	以 RPG 攻防對決方式審查 git diff 的程式碼審查 skill。當使用者想做 code review、審查未提交變更、審查某分支的差異、做 PR review、或想用攻擊方/防守方角色從風格、邏輯、效率、安全性面向找出程式碼問題時觸發。使用者可選擇要派哪些角色（單一角色、整個攻擊方、整個防守方、或全部）。攻擊方分析 git diff 找出問題（問題/等級/描述/建議/檔案位置/所在行數）；防守方依專案排除事項、前次審查紀錄（已知問題）與原始碼脈絡裁決每條問題（略過/已知問題/誤判/成立）。不適用於：非 diff 的整體架構評估、非程式碼的文件審查、或單純解釋程式碼。

🛡️⚔️ code-review — RPG 攻防對決式 git diff 審查

由可選擇的 RPG 角色對 git diff 進行攻防審查。攻擊方找問題，防守方裁決。 角色定義在 roles/ 資料夾（一角色一個 .md），各自有英文名稱、專案、個性、徽章與代表色。

角色一覽

角色	陣營	面向	徽章	檔案
Bard（吟遊詩人）	攻擊方	風格	🎼	roles/bard.md
Mage（法師）	攻擊方	邏輯	🔮	roles/mage.md
Rogue（盜賊）	攻擊方	效率	⚡	roles/rogue.md
Assassin（刺客）	攻擊方	安全性	🗡️	roles/assassin.md
Paladin（聖騎士）	防守方	裁決	🛡️	roles/paladin.md

每次執行前，先讀取被選到角色的 roles/<role>.md，套用其 frontmatter（徽章、代表色、個性）與 body（審查重點/裁決準則）。

---

輸出規範（所有角色共用，務必遵守）

• 語言：所有面向使用者的輸出（findings 表、裁決表、總結、附註、反問）一律使用繁體中文（台灣用語）。 僅程式碼識別字、檔名、git 指令、既有技術術語保留原文，不可使用簡體字或英文敘述句。
• 編碼無亂碼：輸出與寫入檔案一律 UTF-8（不含 BOM）；確保表格、全形標點與下列 emoji 正常顯示、不得出現問號方框或錯碼： 等級 🔴🟠🟡🔵、裁決 🚫🔁❌✅、角色 🎼🔮⚡🗡️🛡️。
• 派發 subagent 時：須把本規範一併寫入每個 subagent 的提示，確保各角色回傳的內容同樣是繁體中文、無亂碼。

---

執行流程

1. 取得 diff（必須指定來源分支與目標分支，缺一不可）

審查範圍一律是兩個分支的差異，來源分支（source）與目標分支（target）兩者缺一不可：

• slash 參數提供兩者：/jsc:code-review <target> <source>（順序：目標在前、來源在後），例如 /jsc:code-review main feature/login。指令為 git diff <target>...<source>（比對 source 自分岔點以來的變更）。
• 若來源或目標分支任一缺漏 → 必須詢問使用者補齊，兩個都拿到才繼續； 可用 git branch 列出可選分支輔助使用者選擇。不可自行臆測或預設某一分支。
• 取得兩個分支後執行 git diff <target>...<source>，並排除下列不納入審查的路徑：

  • 任何以 . 開頭的資料夾內的所有內容（如 .git/、.github/、.claude-plugin/、.codex-plugin/、.agents/ 等）。

  • 排除事項檔與前次審查紀錄檔本身（--exclusions / --known-issues 指定的路徑；未指定時連同預設檔名 exclusions.md、known-issues.md 一併排除）。

  • 用 git pathspec 一次完成，例如：

    git diff <target>...<source> -- . \
      ':(exclude,glob)**/.*/**' \
      ':(exclude)<排除事項檔路徑>' \
      ':(exclude)<前次審查紀錄檔路徑>'
    

    （**/.*/** 排除任意層級的 . 開頭資料夾內容；. 開頭的檔案不在此列，只有上述兩個設定檔被指名排除。）

• 過濾後 diff 為空 → 回報「無變更可審查」並結束。

2. 選擇角色

slash 參數格式：/jsc:code-review <target> <source> [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>] （角色接在兩個分支之後；--exclusions、--known-issues 旗標可放在任意位置，分別指定排除事項檔案、前次審查紀錄檔案）。

• 若已指定角色 → 直接採用。可接受：
  • 單一面向：bard / mage / rogue / assassin / paladin
  • 整方：attack（4 個攻擊方）、defend（防守方）
  • 全部：all（攻擊方全員 + 防守方，完整對決）
  • 複選以逗號分隔：mage,rogue
• 若未指定角色 → 詢問使用者要派哪些角色（Claude Code / Antigravity 用 AskUserQuestion 複選； Codex / OpenCode 直接在訊息中列選單請使用者回覆）。選項涵蓋：單一角色 / 攻擊方全員 / 防守方全員 / 全部。

3. 載入排除事項與前次審查紀錄（只要選到防守方就需要）

防守方需要兩份參照資料，兩者皆位於專案根目錄：

(a) 排除事項設定檔（建議檔名 exclusions.md，列出已知技術債／團隊慣例／刻意取捨）：

• 若 slash 參數帶了 --exclusions <路徑> → 即為使用者明確指定，直接採用該路徑，不需再問。
• 否則只要使用者沒有明確告知檔案路徑 → 一律先詢問。預設檔名 exclusions.md 僅作為詢問時的建議選項， 不可在未取得使用者明確指定前自行假設或直接採用該預設路徑。
• 檔案允許不存在或為空 → 視為「無排除事項」，不因缺檔而中斷。

(b) 前次審查紀錄檔（已知問題＝前次審查成立但未解決的問題；建議檔名 known-issues.md）：

• 若 slash 參數帶了 --known-issues <路徑> → 即為使用者明確指定，直接採用該路徑，不需再問。
• 否則只要使用者沒有明確告知檔案路徑 → 一律先詢問（規則同上，預設檔名僅為建議選項，不可自行假設）。
• 檔案允許不存在或為空 → 視為「無已知問題」（例如首次審查），不因缺檔而中斷。

4. 攻擊方審查

被選到的每個攻擊方角色，依其 focus 與個性掃描 diff，各自輸出一張 findings 表 （表前加上該角色的徽章＋名稱，並標註代表色）：

🔮 Mage（法師）· 邏輯　#3B82F6

問題	等級	描述	建議	檔案位置	所在行數

• 等級：🔴 嚴重 / 🟠 高 / 🟡 中 / 🔵 低。
• 檔案位置 / 所在行數：取自 diff 新檔（+ 側）的路徑與行號。
• 只針對本次 diff 的變更，不對無關舊碼開砲。
• 攻擊方審查的是步驟 1 過濾後的 diff（已排除 . 開頭資料夾內容、排除事項檔與前次審查紀錄檔），不得把這些被排除的路徑列入問題。

5. 防守方裁決（若選到防守方）

先把攻擊方的 findings 彙整去重並排序，再逐條裁決：

• (0) 去重 + 排序：合併所有攻擊方的 findings，依「同檔案位置 ＋ 同問題本質」去除重複 （多個角色重複提出的同一問題只保留一條，並註明由哪些角色共同提出），再依嚴重等級 🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低 排序。

對排序後的每一條 finding 依序：

• (a) 先比對排除事項：命中 → 🚫 略過（排除事項），引用對應排除條目，不再回答此條。
• (b) 再比對前次審查紀錄（已知問題）：若與前次發現但未解決的問題相符 → 🔁 已知問題（前次未解決），引用對應紀錄條目，不重複裁決。
• (c) 否則讀原始碼判斷：標 ❌ 誤判（false positive）（附理由）或 ✅ 成立（附理由與修正建議）。

輸出一張裁決表（聖騎士徽章 🛡️ #EAB308）：

來源角色	原問題	裁決	理由	最終建議

裁決欄只能是 🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立。

若只選了防守方、尚無攻擊方 findings → 先自動跑攻擊方全員產生指控，再裁決（並告知使用者已自動補跑）。

6. 總結

• 有防守方：只彙整 ✅ 成立 的問題，依等級（🔴→🔵）排序成一份精簡待辦清單；略過（排除事項）、已知問題、誤判皆不列入； 另以一行附註本次「🔁 已知問題（前次未解決）」的數量，提醒這些問題仍懸而未決。
• 無防守方：直接呈現攻擊方各自的 findings 表。

7. 更新前次審查紀錄（有防守方時，可選）

為了讓「已知問題」在下次審查能被辨識，詢問使用者是否將本次 ✅ 成立的問題寫入前次審查紀錄檔 （步驟 3 取得的 --known-issues 路徑或詢問所得路徑）：

• 經同意後，把本次 ✅ 成立、且未當場修正的問題追加／更新進該檔（沿用的 🔁 已知問題維持保留）。
• 寫入屬於更動專案檔案的行為，未獲同意前不可自行寫入；使用者拒絕則僅輸出總結、不改檔。

---

執行方式：單選 vs 複選

• 單一角色 → 模型直接扮演該角色執行，不需 subagent。
• 複選（多個角色 / 整方 / 全部） → 以 sub agent 方式執行：
  • Claude Code / Antigravity：用 Agent/Task 工具，每個被選到的攻擊方角色派一個 subagent 並行執行 （subagent 帶該角色 roles/<role>.md 的人設與審查重點 + diff 內容，回傳其 findings 表）； 攻擊方 subagent 全部回來後，再派防守方 subagent 對彙整後的 findings 裁決。
  • Codex / OpenCode（無對等 subagent 機制）：退化為模型依序扮演各角色，行為等價、僅非並行。

無論哪種路徑，最終輸出格式（findings 表、裁決表、總結）一致。

呼叫方式

格式：<target> <source> [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>] — 來源/目標分支缺一不可，缺漏會反問補齊；角色可省略（會詢問）；--exclusions、--known-issues 可省略 （省略時若選到防守方會反問檔案路徑）。

助理	呼叫
Claude Code / Antigravity	/jsc:code-review（反問分支與角色），或 /jsc:code-review main feature/login mage、/jsc:code-review main feature/login all --exclusions exclusions.md --known-issues known-issues.md
Codex	$code-review main feature/login attack，或 $code-review main feature/login all --exclusions docs/review-rules.md --known-issues docs/known-issues.md，或用 /skills 選單
OpenCode	描述需求（如「用攻防角色 review main 與 feature/login 的差異，排除事項看 docs/review-rules.md、已知問題看 docs/known-issues.md」）自動觸發