166 lines
11 KiB
Markdown
166 lines
11 KiB
Markdown
---
|
||
name: code-review
|
||
description: 以 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 一次完成，例如：
|
||
|
||
```bash
|
||
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」）自動觸發 |
|