From 5e1ac92c92496912b48891259a352a9ec6cf89e7 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 15 Jun 2026 17:08:15 +0800 Subject: [PATCH] =?UTF-8?q?=E9=98=B2=E5=AE=88=E6=96=B9=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E3=80=8C=E5=B7=B2=E7=9F=A5=E5=95=8F=E9=A1=8C=E3=80=8D=E6=B5=81?= =?UTF-8?q?=E7=A8=8B=E8=88=87=E5=8E=BB=E9=87=8D=E6=8E=92=E5=BA=8F=E5=89=8D?= =?UTF-8?q?=E8=99=95=E7=90=86?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增已知問題比對：前次審查發現但未解決的問題標 🔁 略過、不重複裁決 - 載入前次審查紀錄檔（建議 .codereview-known-issues.md），新增 --known-issues 參數， 比照排除事項規則（未指定就詢問、可不存在或為空） - 裁決欄改為四態：🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立 - 裁決前先把攻擊方 findings 去重（同位置同本質）並依嚴重等級排序 - 新增可選步驟：經同意後將本次成立問題寫入紀錄檔供下次比對 - SKILL.md / paladin.md / README 同步更新 Co-Authored-By: Claude Opus 4.8 (1M context) --- README.md | 8 ++--- skills/code-review/SKILL.md | 54 +++++++++++++++++++++-------- skills/code-review/roles/paladin.md | 34 +++++++++++++----- 3 files changed, 69 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 258cf0f..722572d 100644 --- a/README.md +++ b/README.md @@ -165,12 +165,12 @@ rm -rf ~/.config/opencode/skills/code-review ### `code-review` -以 RPG 攻防對決方式審查 `git diff` 的程式碼審查 skill。審查範圍是兩個分支的差異，**來源分支與目標分支缺一不可**（缺漏會反問補齊）。角色分**攻擊方**（吟遊詩人=風格 🎼／法師=邏輯 🔮／盜賊=效率 ⚡／刺客=安全性 🗡️）與**防守方**（聖騎士=裁決 🛡️），每個角色定義在 `skills/code-review/roles/.md`（含英文名稱／專案／個性／徽章／代表色）。攻擊方分析 diff 找出問題（問題／等級／描述／建議／檔案位置／所在行數）；防守方依專案根目錄排除事項設定檔與原始碼脈絡裁決每條問題（🚫 略過／❌ 誤判／✅ 成立）。使用者可選擇單一角色、整個攻擊方、整個防守方或全部；複選時以 sub agent 並行執行。 +以 RPG 攻防對決方式審查 `git diff` 的程式碼審查 skill。審查範圍是兩個分支的差異，**來源分支與目標分支缺一不可**（缺漏會反問補齊）。角色分**攻擊方**（吟遊詩人=風格 🎼／法師=邏輯 🔮／盜賊=效率 ⚡／刺客=安全性 🗡️）與**防守方**（聖騎士=裁決 🛡️），每個角色定義在 `skills/code-review/roles/.md`（含英文名稱／專案／個性／徽章／代表色）。攻擊方分析 diff 找出問題（問題／等級／描述／建議／檔案位置／所在行數）；防守方依專案根目錄排除事項設定檔、**前次審查紀錄（已知問題＝前次發現但未解決的問題）**與原始碼脈絡裁決每條問題（🚫 略過／🔁 已知問題／❌ 誤判／✅ 成立）。使用者可選擇單一角色、整個攻擊方、整個防守方或全部；複選時以 sub agent 並行執行。 -參數格式：` [角色...] [--exclusions <排除事項檔案路徑>]`（目標在前、來源在後；角色可省略，會詢問；`--exclusions` 指定排除事項檔案路徑，省略時若選到防守方會反問）。 +參數格式：` [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>]`（目標在前、來源在後；角色可省略，會詢問；`--exclusions`、`--known-issues` 指定對應檔案路徑，省略時若選到防守方會反問）。 -- **Claude Code / Antigravity**：`/jsc:code-review`（反問分支與角色），或帶參數 `/jsc:code-review main feature/login`、`/jsc:code-review main feature/login mage`、`/jsc:code-review main feature/login all --exclusions .codereview.md` -- **Codex**：`$code-review main feature/login attack`，或指定排除事項 `$code-review main feature/login all --exclusions docs/review-rules.md`，或用 `/skills` 選單 +- **Claude Code / Antigravity**：`/jsc:code-review`（反問分支與角色），或帶參數 `/jsc:code-review main feature/login mage`、`/jsc:code-review main feature/login all --exclusions .codereview.md --known-issues .codereview-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」）自動觸發 diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 1170ba4..2aadcd1 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -1,6 +1,6 @@ --- name: code-review -description: 以 RPG 攻防對決方式審查 git diff 的程式碼審查 skill。當使用者想做 code review、審查未提交變更、審查某分支的差異、做 PR review、或想用攻擊方/防守方角色從風格、邏輯、效率、安全性面向找出程式碼問題時觸發。使用者可選擇要派哪些角色（單一角色、整個攻擊方、整個防守方、或全部）。攻擊方分析 git diff 找出問題（問題/等級/描述/建議/檔案位置/所在行數）；防守方依專案排除事項與原始碼脈絡裁決每條問題（略過/誤判/成立）。不適用於：非 diff 的整體架構評估、非程式碼的文件審查、或單純解釋程式碼。 +description: 以 RPG 攻防對決方式審查 git diff 的程式碼審查 skill。當使用者想做 code review、審查未提交變更、審查某分支的差異、做 PR review、或想用攻擊方/防守方角色從風格、邏輯、效率、安全性面向找出程式碼問題時觸發。使用者可選擇要派哪些角色（單一角色、整個攻擊方、整個防守方、或全部）。攻擊方分析 git diff 找出問題（問題/等級/描述/建議/檔案位置/所在行數）；防守方依專案排除事項、前次審查紀錄（已知問題）與原始碼脈絡裁決每條問題（略過/已知問題/誤判/成立）。不適用於：非 diff 的整體架構評估、非程式碼的文件審查、或單純解釋程式碼。 --- # 🛡️⚔️ code-review — RPG 攻防對決式 git diff 審查 @@ -37,8 +37,8 @@ description: 以 RPG 攻防對決方式審查 git diff 的程式碼審查 skill ### 2. 選擇角色 -slash 參數格式：`/jsc:code-review [角色...] [--exclusions <排除事項檔案路徑>]` -（角色接在兩個分支之後；`--exclusions` 旗標可放在任意位置，指定排除事項檔案路徑）。 +slash 參數格式：`/jsc:code-review [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>]` +（角色接在兩個分支之後；`--exclusions`、`--known-issues` 旗標可放在任意位置，分別指定排除事項檔案、前次審查紀錄檔案）。 - **若已指定角色** → 直接採用。可接受： - 單一面向：`bard` / `mage` / `rogue` / `assassin` / `paladin` @@ -48,15 +48,22 @@ slash 參數格式：`/jsc:code-review [角色...] [--exclusio - **若未指定角色** → **詢問使用者**要派哪些角色（Claude Code / Antigravity 用 AskUserQuestion 複選； Codex / OpenCode 直接在訊息中列選單請使用者回覆）。選項涵蓋：單一角色 / 攻擊方全員 / 防守方全員 / 全部。 -### 3. 載入排除事項（只要選到防守方就需要） +### 3. 載入排除事項與前次審查紀錄（只要選到防守方就需要） -排除事項設定檔位於**專案根目錄**（建議檔名 `.codereview.md`，列出已知技術債／團隊慣例／刻意取捨）。 +防守方需要兩份參照資料，兩者皆位於**專案根目錄**： + +**(a) 排除事項設定檔**（建議檔名 `.codereview.md`，列出已知技術債／團隊慣例／刻意取捨）： - **若 slash 參數帶了 `--exclusions <路徑>`** → 即為使用者明確指定，直接採用該路徑，**不需再問**。 - **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `.codereview.md` 僅作為詢問時的**建議選項**， **不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。 -- 使用者明確指定路徑（透過 `--exclusions`，或在詢問中確認用預設 / 確認無檔）後才繼續。 -- **檔案允許不存在或為空** → 視為「無排除事項」，防守方直接進入原始碼判斷，**不**因缺檔而中斷。 +- **檔案允許不存在或為空** → 視為「無排除事項」，**不**因缺檔而中斷。 + +**(b) 前次審查紀錄檔**（已知問題＝前次審查成立但未解決的問題；建議檔名 `.codereview-known-issues.md`）： + +- **若 slash 參數帶了 `--known-issues <路徑>`** → 即為使用者明確指定，直接採用該路徑，**不需再問**。 +- **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**（規則同上，預設檔名僅為建議選項，不可自行假設）。 +- **檔案允許不存在或為空** → 視為「無已知問題」（例如首次審查），**不**因缺檔而中斷。 ### 4. 攻擊方審查 @@ -74,25 +81,41 @@ slash 參數格式：`/jsc:code-review [角色...] [--exclusio ### 5. 防守方裁決（若選到防守方） -對攻擊方的**每一條** finding 依序： +**先把攻擊方的 findings 彙整去重並排序，再逐條裁決：** + +- **(0) 去重 + 排序**：合併所有攻擊方的 findings，依「同檔案位置 ＋ 同問題本質」**去除重複** + （多個角色重複提出的同一問題只保留一條，並註明由哪些角色共同提出），再依嚴重等級 + **🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 排序。 + +對排序後的**每一條** finding 依序： - **(a) 先比對排除事項**：命中 → **🚫 略過（排除事項）**，引用對應排除條目，不再回答此條。 -- **(b) 否則讀原始碼判斷**：標 **❌ 誤判（false positive）**（附理由）或 **✅ 成立**（附理由與修正建議）。 +- **(b) 再比對前次審查紀錄（已知問題）**：若與前次發現但未解決的問題相符 → **🔁 已知問題（前次未解決）**，引用對應紀錄條目，不重複裁決。 +- **(c) 否則讀原始碼判斷**：標 **❌ 誤判（false positive）**（附理由）或 **✅ 成立**（附理由與修正建議）。 輸出一張裁決表（聖騎士徽章 🛡️ `#EAB308`）： | 來源角色 | 原問題 | 裁決 | 理由 | 最終建議 | | --- | --- | --- | --- | --- | -裁決欄只能是 `🚫 略過 / ❌ 誤判 / ✅ 成立`。 +裁決欄只能是 `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立`。 > **若只選了防守方、尚無攻擊方 findings** → 先自動跑攻擊方全員產生指控，再裁決（並告知使用者已自動補跑）。 ### 6. 總結 -- **有防守方**：只彙整 **✅ 成立** 的問題，依等級（🔴→🔵）排序成一份精簡待辦清單；略過/誤判不列入。 +- **有防守方**：只彙整 **✅ 成立** 的問題，依等級（🔴→🔵）排序成一份精簡待辦清單；略過（排除事項）、已知問題、誤判皆不列入； + 另以一行附註本次「🔁 已知問題（前次未解決）」的數量，提醒這些問題仍懸而未決。 - **無防守方**：直接呈現攻擊方各自的 findings 表。 +### 7. 更新前次審查紀錄（有防守方時，可選） + +為了讓「已知問題」在下次審查能被辨識，**詢問使用者是否將本次 ✅ 成立的問題寫入前次審查紀錄檔** +（步驟 3 取得的 `--known-issues` 路徑或詢問所得路徑）： + +- 經同意後，把本次 ✅ 成立、且未當場修正的問題**追加／更新**進該檔（沿用的 🔁 已知問題維持保留）。 +- 寫入屬於更動專案檔案的行為，**未獲同意前不可自行寫入**；使用者拒絕則僅輸出總結、不改檔。 + --- ## 執行方式：單選 vs 複選 @@ -108,11 +131,12 @@ slash 參數格式：`/jsc:code-review [角色...] [--exclusio ## 呼叫方式 -格式：` [角色...] [--exclusions <排除事項檔案路徑>]` — **來源/目標分支缺一不可**，缺漏會反問補齊； -角色可省略（會詢問）；`--exclusions` 可省略（省略時若選到防守方會反問檔案路徑）。 +格式：` [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>]` — +**來源/目標分支缺一不可**，缺漏會反問補齊；角色可省略（會詢問）；`--exclusions`、`--known-issues` 可省略 +（省略時若選到防守方會反問檔案路徑）。 | 助理 | 呼叫 | | --- | --- | -| Claude Code / Antigravity | `/jsc:code-review`（反問分支與角色），或 `/jsc:code-review main feature/login`、`/jsc:code-review main feature/login mage`、`/jsc:code-review main feature/login all --exclusions .codereview.md` | -| Codex | `$code-review main feature/login attack`，或指定排除事項 `$code-review main feature/login all --exclusions docs/review-rules.md`，或用 `/skills` 選單 | +| Claude Code / Antigravity | `/jsc:code-review`（反問分支與角色），或 `/jsc:code-review main feature/login mage`、`/jsc:code-review main feature/login all --exclusions .codereview.md --known-issues .codereview-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」）自動觸發 | diff --git a/skills/code-review/roles/paladin.md b/skills/code-review/roles/paladin.md index 6694c74..bb720b0 100644 --- a/skills/code-review/roles/paladin.md +++ b/skills/code-review/roles/paladin.md @@ -5,7 +5,7 @@ side: defend focus: verdict badge: "🛡️" color: "#EAB308" -personality: 沉穩公正、就事論事，不護短也不冤枉，只依排除事項與原始碼脈絡下判斷 +personality: 沉穩公正、就事論事，不護短也不冤枉，只依排除事項、前次審查紀錄與原始碼脈絡下判斷 --- # 🛡️ Paladin（聖騎士）· 裁決面向 @@ -16,22 +16,40 @@ personality: 沉穩公正、就事論事，不護短也不冤枉，只依排除 聖騎士是這座競技場的裁判：沉穩、公正、就事論事。 他不為了護短而放水，也不讓攻擊方的氣勢冤枉了無辜的程式碼。 -他手握兩件聖物——**專案排除事項**與**原始碼脈絡**——逐條審視每一項指控。 +他手握三件聖物——**專案排除事項**、**前次審查紀錄**與**原始碼脈絡**——逐條審視每一項指控。 ## 排除事項（裁決前先確認） 排除事項設定檔位於**專案根目錄**（建議檔名 `.codereview.md`，列出已知技術債／團隊慣例／刻意取捨）。 -1. **只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `.codereview.md` 僅是詢問時的**建議選項**， +1. **若 slash 參數帶了 `--exclusions <路徑>`** → 即為使用者明確指定，直接採用該路徑。 +2. **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `.codereview.md` 僅是詢問時的**建議選項**， **不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。 -2. **檔案允許不存在或為空** → 視為「無排除事項」，直接進入原始碼判斷，不因缺檔而中斷。 -3. 取得使用者明確指定的路徑（或在詢問中確認用預設 / 確認無檔）後，才以該檔內容作為排除事項依據。 +3. **檔案允許不存在或為空** → 視為「無排除事項」，不因缺檔而中斷。 -## 裁決準則（對攻擊方的每一條 finding 依序處理） +## 前次審查紀錄（已知問題＝前次發現但未解決的問題，裁決前先確認） + +前次審查紀錄檔位於**專案根目錄**（建議檔名 `.codereview-known-issues.md`，記錄歷次審查成立但尚未解決的問題）。 + +1. **若 slash 參數帶了 `--known-issues <路徑>`** → 即為使用者明確指定，直接採用該路徑。 +2. **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `.codereview-known-issues.md` 僅是詢問時的**建議選項**， + **不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。 +3. **檔案允許不存在或為空** → 視為「無已知問題」（例如首次審查），不因缺檔而中斷。 + +## 裁決準則 + +裁決前，先把攻擊方的所有 finding **去重並依嚴重等級排序**： + +0. **去重 + 排序** — 依「同檔案位置 ＋ 同問題本質」去除重複（多個角色重複提出的同一問題只留一條， + 註明由哪些角色共同提出），再依嚴重等級 **🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 排序。 + +接著對排序後的**每一條** finding 依序處理： 1. **先比對排除事項** — 若該問題落在排除事項範圍（已知技術債／團隊慣例等）： - 標記 **🚫 略過（排除事項）**，引用對應的排除條目，**不需再回答**此問題。 -2. **否則讀原始碼判斷** — 讀被指控檔案的相關原始碼脈絡後，標註： +2. **再比對前次審查紀錄（已知問題）** — 若該問題與前次審查發現、但尚未解決的問題相符： + - 標記 **🔁 已知問題（前次未解決）**，引用對應的紀錄條目，**不重複裁決**此問題。 +3. **否則讀原始碼判斷** — 讀被指控檔案的相關原始碼脈絡後，標註： - **❌ 誤判（false positive）**：原始碼顯示此問題不成立（例如他處已處理、語義其實正確）→ 附理由。 - **✅ 成立（confirmed）**：問題屬實 → 附理由與最終修正建議。 @@ -42,7 +60,7 @@ personality: 沉穩公正、就事論事，不護短也不冤枉，只依排除 | 來源角色 | 原問題 | 裁決 | 理由 | 最終建議 | | --- | --- | --- | --- | --- | -裁決欄只能是 `🚫 略過 / ❌ 誤判 / ✅ 成立` 三者之一。 +裁決欄只能是 `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立` 之一。 ## 發言風格