diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index bbaf569..e12a5c1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,12 +1,12 @@ { "name": "jsc", - "version": "0.0.1", + "version": "0.0.2", "description": "JSC 跨 AI 助理共用 plugin 模板（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。", "skills": "./skills", "author": { "name": "JSC" }, - "homepage": "https://gitea.jsc.idv.tw/plugins/template", - "repository": "https://gitea.jsc.idv.tw/plugins/template.git", + "homepage": "https://gitea.jsc.idv.tw/plugins/code-review", + "repository": "https://gitea.jsc.idv.tw/plugins/code-review.git", "keywords": ["template", "skills", "cross-tool", "jsc"] } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 827033e..588010b 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.0.1", + "version": "0.0.2", "description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/README.md b/README.md index 356eb5f..cfa8a9c 100644 --- a/README.md +++ b/README.md @@ -144,9 +144,9 @@ rm -rf ~/.config/opencode/skills/code-review | 助理 | headless 指令 | 執行 `code-review` skill | | --- | --- | --- | -| Claude Code | `claude -p ""` | `claude -p "/jsc:code-review main feature/login all"` | -| Codex | `codex exec ""` | `codex exec '$code-review main feature/login all'` | -| Antigravity | `agy -p ""` | `agy -p "/jsc:code-review main feature/login all"` | +| Claude Code | `claude -p ""` | `claude -p "/jsc:code-review main feature/login all --exclusions .codereview.md"` | +| Codex | `codex exec ""` | `codex exec '$code-review main feature/login all --exclusions .codereview.md'` | +| Antigravity | `agy -p ""` | `agy -p "/jsc:code-review main feature/login all --exclusions .codereview.md"` | | OpenCode | `opencode run ""` | `opencode run "用攻防角色 review main 與 feature/login 的差異"` | - Claude / Antigravity 支援 `/jsc:` 前綴，直接 `-p "/jsc:"` 即可。 @@ -165,13 +165,23 @@ 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 <排除事項檔案路徑>] [--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` -- **Codex**：`$code-review main feature/login attack`（可接參數），或用 `/skills` 選單 -- **OpenCode**：描述需求（如「用攻防角色 review main 與 feature/login 的差異」）自動觸發 +- **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」）自動觸發 + +### `archive-findings` + +將 `/jsc:code-review` 已裁決的問題保存到專案：**✅ 成立** 附加到前次審查紀錄（已知問題）檔、**❌ 誤判** 附加到排除事項檔，讓防守方下次自動標 🔁 已知問題 / 🚫 略過；🔁／🚫 已存在者僅計數不重複寫入。只吃既有裁決結果（合併攻擊方問題表＋防守方裁決表），不自己跑 review、不改程式碼，且寫檔前先取得同意。檔案格式依副檔名（`.md` / `.json`）決定。 + +參數：`--known-issues <前次審查紀錄路徑> --exclusions <排除事項檔案路徑>`（與 code-review 同名旗標，沿用同一組路徑；缺漏會反問）。 + +- **Claude Code / Antigravity**：`/jsc:archive-findings --known-issues .codereview-known-issues.md --exclusions .codereview.md` +- **Codex**：`$archive-findings --known-issues docs/known-issues.md --exclusions docs/review-rules.md`，或用 `/skills` 選單 +- **OpenCode**：描述需求（如「把剛剛 code-review 成立的問題存到 .codereview-known-issues.md、誤判存到 .codereview.md」）自動觸發 diff --git a/plugin.json b/plugin.json index 42a1b7b..0e0bdbb 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.0.1", + "version": "0.0.2", "description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。", "skills": "./skills/" } \ No newline at end of file diff --git a/skills/archive-findings/SKILL.md b/skills/archive-findings/SKILL.md new file mode 100644 index 0000000..93f35be --- /dev/null +++ b/skills/archive-findings/SKILL.md @@ -0,0 +1,169 @@ +--- +name: archive-findings +description: 將 /jsc:code-review 已裁決的問題保存到目標專案 —【✅ 成立】附加到「前次審查紀錄（已知問題）」檔、【❌ 誤判】附加到「排除事項」檔，讓 code-review 防守方下次自動標為 🔁 已知問題 / 🚫 略過。當使用者說保存／歸檔 code review 結果、把成立問題寫進已知問題、把誤判寫進排除事項、把 review 裁決落地到專案時觸發。只處理「已裁決」的列表（合併防守方裁決表與攻擊方問題表），不自己跑 review、不修改程式碼。缺裁決表時，請先用 /jsc:code-review 的防守方（paladin）產生裁決。 +argument-hint: "--known-issues <前次審查紀錄路徑> --exclusions <排除事項檔案路徑>" +--- + +# archive-findings — 保存 code-review 裁決結果到專案 + +把 `/jsc:code-review` 防守方的裁決落地成兩份專案紀錄，形成下次審查的回饋圈： + +| 裁決 | 動作 | +| --- | --- | +| ✅ 成立 | 附加到**前次審查紀錄（已知問題）檔** → 下次審查會被標 **🔁 已知問題** | +| ❌ 誤判 | 附加到**排除事項檔** → 下次審查會被標 **🚫 略過** | +| 🔁 已知問題 | 已在已知問題檔，**不重複寫入**（僅計數） | +| 🚫 略過 | 已在排除事項檔，**不重複寫入**（僅計數） | + +> 與 `/jsc:code-review` 的關係：code-review 的步驟 7 只會（在同意後）把 ✅ 成立 寫入已知問題檔； +> **誤判 → 排除事項** 它不會寫。本 skill 一次補齊兩個方向，且**只吃既有裁決結果**：不跑 review、不改程式碼。 + +## 參數（與 code-review 同名旗標，方便沿用同一組路徑） + +`--known-issues <前次審查紀錄路徑>`　`--exclusions <排除事項檔案路徑>` — **兩者皆必填，一定要指定**。 + +- **未提供任一路徑 → 必須先向使用者取得，不可自行採用預設或臆測**（與 code-review 一致：預設檔名僅作詢問時的建議選項）。 + 建議預設：已知問題 `.codereview-known-issues.md`、排除事項 `.codereview.md`（與 code-review 防守方讀的同一檔）。 +- **檔案本身允許不存在或為空內容**：若目標檔不存在、或內容為空（含只有空白）→ skill 先**依模板建立該檔**（見下方「模板」），再附加條目；既有非空檔則直接附加。 +- 寫入屬於**更動專案檔案**的行為 → **未獲使用者同意前不可寫入**；拒絕則只輸出將寫入的預覽。 +- **格式依副檔名自動決定**：`.md` → Markdown（用下方模板）；`.json` → top-level JSON array（空／不存在時初始化為 `[]`）。 + +## 執行流程 + +### 1. 取得問題表與裁決表（只吃既有結果） + +來源優先序：本次對話中上一個 `/jsc:code-review` 的輸出；若無，請使用者貼上。 + +- **問題表**（攻擊方）：`問題 | 等級 | 描述 | 建議 | 檔案位置 | 所在行數`。 +- **裁決表**（防守方）：`來源角色 | 原問題 | 裁決 | 理由 | 最終建議`，裁決 ∈ `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立`。 +- **沒有裁決表** → 無法分類，**請先跑防守方**（`/jsc:code-review paladin`）或請使用者提供裁決表。 + **只處理已裁決的列表**，不自行臆測成立或誤判。 + +### 2. 合併兩表 + +以 **`原問題` ↔ `問題`** 為鍵配對；同名問題以 **`來源角色` + `檔案位置`** 區分。 +合併後每筆 = 等級／描述／建議／檔案位置／所在行數（問題表）＋ 裁決／理由／最終建議（裁決表）。 + +- **對不上的列**（裁決表有但問題表查無，或反之）→ 列出請使用者確認，**不臆測**、不寫入。 + +### 3. 補齊欄位 + +- **日期**：`YYYY-MM-DD`（可用 `date +%F`，或取來源分支最後 commit 日期）。 +- **範圍／來源**：`...`（沿用本次 review 的分支；不確定就問或留白）。 + +### 4. 取得同意 → 去重 → 附加 + +1. 先輸出「將寫入」的預覽（各檔幾筆、條目摘要），**請使用者確認**後才動檔。 +2. **去重鍵**：`<檔案位置>|<問題標題>`。寫入前先讀目標檔，**已存在相同鍵的條目 → 略過不重複附加**。 +3. **目標檔不存在或為空（含只有空白）→ 先依「模板」建立**（`.md` 用下方模板；`.json` 初始化為 `[]`），再附加。 +4. 分流： + - **✅ 成立** → 附加到**已知問題檔**（`--known-issues`）。 + - **❌ 誤判** → 附加到**排除事項檔**（`--exclusions`）。 + - **🔁 已知問題 / 🚫 略過** → 不處理（已存在），僅計數。 + +### 5. 回報摘要 + +列出：新增成立 N 筆、新增誤判 M 筆、已知問題（略過）K 筆、排除（略過）L 筆、重複而跳過 J 筆，以及實際寫入的檔案路徑。 + +--- + +## 檔案格式 + +### Markdown（`.md`） + +目標檔不存在時先建立標題： + +- 已知問題檔：`# 前次審查紀錄（已知問題）\n\n由 /jsc:archive-findings 從 code-review【✅ 成立】問題彙整；/jsc:code-review 防守方會讀此檔並標「🔁 已知問題」。` +- 排除事項檔（`.codereview.md`）：`# Code Review 排除事項\n\n已知技術債／團隊慣例／刻意取捨／已確認的誤判；/jsc:code-review 防守方會讀此檔並標「🚫 略過」。` + +**已知問題** 每筆： + +```markdown +### [<等級>] <問題標題> + +- 檔案：`<檔案位置>:<所在行數>` +- 描述：<描述> +- 建議：<最終建議> +- 裁決：✅ 成立（<理由>）— 由 <來源角色> 提出 +- 範圍：`...`，<日期> +``` + +**排除事項** 每筆： + +```markdown +### <問題標題> + +- 檔案：`<檔案位置>` +- 排除原因（❌ 誤判）：<裁決理由> +- 範圍：`...`，<日期> +``` + +### JSON（`.json`） + +維持 **top-level array**（不要包在物件裡）；每筆一個物件，以 `key` 去重： + +```json +{ + "key": "<檔案位置>|<問題標題>", + "title": "<問題標題>", + "severity": "🔴 嚴重 | 🟠 高 | 🟡 中 | 🔵 低", + "file": "<檔案位置>", + "line": "<所在行數>", + "description": "<描述>", + "suggestion": "<最終建議>", + "verdict": "成立 | 誤判", + "reason": "<理由>", + "source": "...", + "date": "YYYY-MM-DD" +} +``` + +--- + +## 模板（空檔／新檔的初始內容） + +目標檔不存在或為空時，先寫入下列模板（同一份也隨附於本 skill 的 `templates/`），再於對應標題下附加條目。 + +### 已知問題檔（`--known-issues`，`.md`） + +```markdown +# 前次審查紀錄（已知問題 / Known Issues） + +> 本檔由 `/jsc:archive-findings` 自動維護，記錄 `/jsc:code-review` 防守方裁定 **✅ 成立** 但尚未解決的問題。 +> `/jsc:code-review` 防守方在步驟 3(b) 會讀此檔：若新發現與此處條目相符，標為 **🔁 已知問題（前次未解決）**，不重複裁決。 +> 問題修復後請刪除對應條目。每筆以 `` 去重。 + +## 待解決問題 + + +``` + +### 排除事項檔（`--exclusions`，`.md`） + +```markdown +# Code Review 排除事項（Exclusions） + +> 本檔由 `/jsc:archive-findings` 維護（也可手動編輯），列出已知技術債／團隊慣例／刻意取捨／已確認的誤判。 +> `/jsc:code-review` 防守方在步驟 3(a) 會讀此檔：若新發現命中此處條目，標為 **🚫 略過（排除事項）**，不再裁決。 +> 不再適用時請手動移除。每筆以 `` 去重。 + +## 排除項目 + + +``` + +### JSON（`.json`） + +空／不存在時初始化為空陣列，再 append 物件：`[]` + +--- + +## 呼叫方式 + +格式：`--known-issues <路徑> --exclusions <路徑>` — **兩者必填**；未提供會反問取得。需先有 `/jsc:code-review` 的問題表＋裁決表。 + +| 助理 | 呼叫 | +| --- | --- | +| Claude Code / Antigravity | `/jsc:archive-findings --known-issues .codereview-known-issues.md --exclusions .codereview.md`（或省略路徑由它反問） | +| Codex | `$archive-findings --known-issues docs/known-issues.md --exclusions docs/review-rules.md`，或用 `/skills` 選單 | +| OpenCode | 描述需求（如「把剛剛 code-review 成立的問題存到 .codereview-known-issues.md、誤判存到 .codereview.md」）自動觸發 | diff --git a/skills/archive-findings/templates/exclusions.md b/skills/archive-findings/templates/exclusions.md new file mode 100644 index 0000000..8b15d9b --- /dev/null +++ b/skills/archive-findings/templates/exclusions.md @@ -0,0 +1,9 @@ +# Code Review 排除事項（Exclusions） + +> 本檔由 `/jsc:archive-findings` 維護（也可手動編輯），列出已知技術債／團隊慣例／刻意取捨／已確認的誤判。 +> `/jsc:code-review` 防守方在步驟 3(a) 會讀此檔：若新發現命中此處條目，標為 **🚫 略過（排除事項）**，不再裁決。 +> 不再適用時請手動移除。每筆以 `` 去重。 + +## 排除項目 + + diff --git a/skills/archive-findings/templates/known-issues.md b/skills/archive-findings/templates/known-issues.md new file mode 100644 index 0000000..5d47aef --- /dev/null +++ b/skills/archive-findings/templates/known-issues.md @@ -0,0 +1,9 @@ +# 前次審查紀錄（已知問題 / Known Issues） + +> 本檔由 `/jsc:archive-findings` 自動維護，記錄 `/jsc:code-review` 防守方裁定 **✅ 成立** 但尚未解決的問題。 +> `/jsc:code-review` 防守方在步驟 3(b) 會讀此檔：若新發現與此處條目相符，標為 **🔁 已知問題（前次未解決）**，不重複裁決。 +> 問題修復後請刪除對應條目。每筆以 `` 去重。 + +## 待解決問題 + + diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index c2e7386..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,7 +37,8 @@ description: 以 RPG 攻防對決方式審查 git diff 的程式碼審查 skill ### 2. 選擇角色 -slash 參數格式：`/jsc:code-review [角色...]`（角色接在兩個分支之後）。 +slash 參數格式：`/jsc:code-review [角色...] [--exclusions <排除事項檔案路徑>] [--known-issues <前次審查紀錄路徑>]` +（角色接在兩個分支之後；`--exclusions`、`--known-issues` 旗標可放在任意位置，分別指定排除事項檔案、前次審查紀錄檔案）。 - **若已指定角色** → 直接採用。可接受： - 單一面向：`bard` / `mage` / `rogue` / `assassin` / `paladin` @@ -47,12 +48,22 @@ slash 參數格式：`/jsc:code-review [角色...]`（角色 - **若未指定角色** → **詢問使用者**要派哪些角色（Claude Code / Antigravity 用 AskUserQuestion 複選； Codex / OpenCode 直接在訊息中列選單請使用者回覆）。選項涵蓋：單一角色 / 攻擊方全員 / 防守方全員 / 全部。 -### 3. 載入排除事項（只要選到防守方就需要） +### 3. 載入排除事項與前次審查紀錄（只要選到防守方就需要） -排除事項設定檔位於**專案根目錄**（建議檔名 `.codereview.md`，列出已知技術債／團隊慣例／刻意取捨）。 +防守方需要兩份參照資料，兩者皆位於**專案根目錄**： -- **若不知道排除事項檔案的位置 → 必須詢問使用者**（提供建議預設 `.codereview.md`）。 -- **檔案允許不存在或為空** → 視為「無排除事項」，防守方直接進入原始碼判斷，**不**因缺檔而中斷。 +**(a) 排除事項設定檔**（建議檔名 `.codereview.md`，列出已知技術債／團隊慣例／刻意取捨）： + +- **若 slash 參數帶了 `--exclusions <路徑>`** → 即為使用者明確指定，直接採用該路徑，**不需再問**。 +- **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `.codereview.md` 僅作為詢問時的**建議選項**， + **不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。 +- **檔案允許不存在或為空** → 視為「無排除事項」，**不**因缺檔而中斷。 + +**(b) 前次審查紀錄檔**（已知問題＝前次審查成立但未解決的問題；建議檔名 `.codereview-known-issues.md`）： + +- **若 slash 參數帶了 `--known-issues <路徑>`** → 即為使用者明確指定，直接採用該路徑，**不需再問**。 +- **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**（規則同上，預設檔名僅為建議選項，不可自行假設）。 +- **檔案允許不存在或為空** → 視為「無已知問題」（例如首次審查），**不**因缺檔而中斷。 ### 4. 攻擊方審查 @@ -70,25 +81,41 @@ slash 參數格式：`/jsc:code-review [角色...]`（角色 ### 5. 防守方裁決（若選到防守方） -對攻擊方的**每一條** finding 依序： +**先把攻擊方的 findings 彙整去重並排序，再逐條裁決：** + +- **(0) 去重 + 排序**：合併所有攻擊方的 findings，依「同檔案位置 ＋ 同問題本質」**去除重複** + （多個角色重複提出的同一問題只保留一條，並註明由哪些角色共同提出），再依嚴重等級 + **🔴 嚴重 → 🟠 高 → 🟡 中 → 🔵 低** 排序。 + +對排序後的**每一條** finding 依序： - **(a) 先比對排除事項**：命中 → **🚫 略過（排除事項）**，引用對應排除條目，不再回答此條。 -- **(b) 否則讀原始碼判斷**：標 **❌ 誤判（false positive）**（附理由）或 **✅ 成立**（附理由與修正建議）。 +- **(b) 再比對前次審查紀錄（已知問題）**：若與前次發現但未解決的問題相符 → **🔁 已知問題（前次未解決）**，引用對應紀錄條目，不重複裁決。 +- **(c) 否則讀原始碼判斷**：標 **❌ 誤判（false positive）**（附理由）或 **✅ 成立**（附理由與修正建議）。 輸出一張裁決表（聖騎士徽章 🛡️ `#EAB308`）： | 來源角色 | 原問題 | 裁決 | 理由 | 最終建議 | | --- | --- | --- | --- | --- | -裁決欄只能是 `🚫 略過 / ❌ 誤判 / ✅ 成立`。 +裁決欄只能是 `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立`。 > **若只選了防守方、尚無攻擊方 findings** → 先自動跑攻擊方全員產生指控，再裁決（並告知使用者已自動補跑）。 ### 6. 總結 -- **有防守方**：只彙整 **✅ 成立** 的問題，依等級（🔴→🔵）排序成一份精簡待辦清單；略過/誤判不列入。 +- **有防守方**：只彙整 **✅ 成立** 的問題，依等級（🔴→🔵）排序成一份精簡待辦清單；略過（排除事項）、已知問題、誤判皆不列入； + 另以一行附註本次「🔁 已知問題（前次未解決）」的數量，提醒這些問題仍懸而未決。 - **無防守方**：直接呈現攻擊方各自的 findings 表。 +### 7. 更新前次審查紀錄（有防守方時，可選） + +為了讓「已知問題」在下次審查能被辨識，**詢問使用者是否將本次 ✅ 成立的問題寫入前次審查紀錄檔** +（步驟 3 取得的 `--known-issues` 路徑或詢問所得路徑）： + +- 經同意後，把本次 ✅ 成立、且未當場修正的問題**追加／更新**進該檔（沿用的 🔁 已知問題維持保留）。 +- 寫入屬於更動專案檔案的行為，**未獲同意前不可自行寫入**；使用者拒絕則僅輸出總結、不改檔。 + --- ## 執行方式：單選 vs 複選 @@ -104,10 +131,12 @@ slash 參數格式：`/jsc:code-review [角色...]`（角色 ## 呼叫方式 -格式：` [角色...]` — **來源/目標分支缺一不可**，缺漏會反問補齊；角色可省略（會詢問）。 +格式：` [角色...] [--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` | -| Codex | `$code-review main feature/login attack`（可接參數），或用 `/skills` 選單 | -| OpenCode | 描述需求（如「幫我用攻防角色 review main 與 feature/login 的差異」）自動觸發 | +| 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 0ea8cb3..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,21 +16,40 @@ personality: 沉穩公正、就事論事，不護短也不冤枉，只依排除 聖騎士是這座競技場的裁判：沉穩、公正、就事論事。 他不為了護短而放水，也不讓攻擊方的氣勢冤枉了無辜的程式碼。 -他手握兩件聖物——**專案排除事項**與**原始碼脈絡**——逐條審視每一項指控。 +他手握三件聖物——**專案排除事項**、**前次審查紀錄**與**原始碼脈絡**——逐條審視每一項指控。 ## 排除事項（裁決前先確認） 排除事項設定檔位於**專案根目錄**（建議檔名 `.codereview.md`，列出已知技術債／團隊慣例／刻意取捨）。 -1. **若不知道排除事項檔案的位置 → 必須先詢問使用者**（提供建議預設 `.codereview.md`）。 -2. **檔案允許不存在或為空** → 視為「無排除事項」，直接進入原始碼判斷，不因缺檔而中斷。 -3. 取得位置（或確認無檔）後，以該檔內容作為排除事項依據。 +1. **若 slash 參數帶了 `--exclusions <路徑>`** → 即為使用者明確指定，直接採用該路徑。 +2. **否則只要使用者沒有明確告知檔案路徑 → 一律先詢問**。預設檔名 `.codereview.md` 僅是詢問時的**建議選項**， + **不可**在未取得使用者明確指定前自行假設或直接採用該預設路徑。 +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）**：問題屬實 → 附理由與最終修正建議。 @@ -41,7 +60,7 @@ personality: 沉穩公正、就事論事，不護短也不冤枉，只依排除 | 來源角色 | 原問題 | 裁決 | 理由 | 最終建議 | | --- | --- | --- | --- | --- | -裁決欄只能是 `🚫 略過 / ❌ 誤判 / ✅ 成立` 三者之一。 +裁決欄只能是 `🚫 略過 / 🔁 已知問題 / ❌ 誤判 / ✅ 成立` 之一。 ## 發言風格