From 83e7a1113e95552fb2d538f28f4794b542708a4e Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 13:08:18 +0800 Subject: [PATCH 01/10] =?UTF-8?q?chore(review):=20=E4=BF=AE=E6=AD=A3?= =?UTF-8?q?=E7=AF=84=E6=9C=AC=20manifest=20=E8=88=87=E7=A7=BB=E9=99=A4=20h?= =?UTF-8?q?ello=20=E7=AF=84=E4=BE=8B=E7=AC=A6=E5=90=88=20review=20?= =?UTF-8?q?=E9=A0=98=E5=9F=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .agents/plugins/marketplace.json | 6 ++--- .claude-plugin/marketplace.json | 8 +++---- .claude-plugin/plugin.json | 17 +++++++++----- .codex-plugin/plugin.json | 6 ++--- plugin.json | 8 +++---- skills/hello/SKILL.md | 38 -------------------------------- 6 files changed, 25 insertions(+), 58 deletions(-) delete mode 100644 skills/hello/SKILL.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index 2c2dafc..823cc7d 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -1,11 +1,11 @@ { - "name": "template", + "name": "review", "plugins": [ { - "name": "jsc-template", + "name": "jsc-review", "source": { "source": "url", - "url": "https://gitea.jsc.idv.tw/plugins/template.git" + "url": "https://gitea.jsc.idv.tw/plugins/review.git" } } ] diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index e3d2436..e20cc0a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,14 +1,14 @@ { - "name": "template", - "description": "JSC 跨 AI 助理共用 skills 的 Claude Code marketplace。", + "name": "review", + "description": "jsc 技能組 review domain 的 marketplace。", "owner": { "name": "JSC" }, "plugins": [ { - "name": "jsc-template", + "name": "jsc-review", "source": "./", - "description": "JSC 共用 skills（跨 AI 助理）" + "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index a5c2dd3..b7a7ab4 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,12 +1,17 @@ { - "name": "jsc-template", - "version": "0.0.3", - "description": "JSC 跨 AI 助理共用 plugin 模板（Claude Code / Codex / Antigravity / OpenCode）。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc-template: 前綴呼叫。", + "name": "jsc-review", + "version": "0.2.0", + "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills", "author": { "name": "JSC" }, - "homepage": "https://gitea.jsc.idv.tw/plugins/template", - "repository": "https://gitea.jsc.idv.tw/plugins/template.git", - "keywords": ["template", "skills", "cross-tool", "jsc"] + "homepage": "https://gitea.jsc.idv.tw/plugins/review", + "repository": "https://gitea.jsc.idv.tw/plugins/review.git", + "keywords": [ + "jsc", + "review", + "skills", + "cross-tool" + ] } diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 71a3c32..e345038 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { - "name": "jsc-template", - "version": "0.0.3", - "description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準。", + "name": "jsc-review", + "version": "0.2.0", + "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 4873395..05d28f6 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { - "name": "jsc-template", - "version": "0.0.3", - "description": "JSC 跨 AI 助理共用 plugin 模板。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc-template: 前綴呼叫。", + "name": "jsc-review", + "version": "0.2.0", + "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills/" -} \ No newline at end of file +} diff --git a/skills/hello/SKILL.md b/skills/hello/SKILL.md deleted file mode 100644 index c5be22f..0000000 --- a/skills/hello/SKILL.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: hello -description: 範例 skill，用來驗證 jsc plugin 是否安裝成功，也是新增 skill 的範本。當使用者輸入 hello、想測試 plugin、或想看 skill 模板長什麼樣子時觸發；回覆一句問候並簡述此 plugin 的用途。 ---- - -# hello（範例 skill） - -這是 `jsc-template` plugin 的範例 skill。它有兩個用途： - -1. **驗證安裝** — 跨各家 AI 助理確認 skill 已被正確載入。 -2. **作為範本** — 複製這個資料夾即可新增一個新的 skill。 - -## 呼叫方式 - -| 助理 | 呼叫方式 | -| --- | --- | -| Claude Code | `/jsc-template:hello` | -| Antigravity | `/jsc-template:hello`，或描述需求自動觸發 | -| Codex | 在提示詞輸入 `$hello`，或用 `/skills` 選單 | -| OpenCode | 直接描述需求，模型會透過 skill 工具自動呼叫 | -| GitHub Copilot CLI | 直接描述需求，Copilot 會讀取已安裝 plugin 的 skills | - -## 行為 - -當這個 skill 被觸發時： - -1. 回覆「Hello from **jsc** 👋」。 -2. 用一句話說明 `jsc-template` 是一個跨 AI 助理的共用 skill 集合。 -3. 提示使用者可以在 README 的「Skills 目錄」查看所有可用的 skills。 - -## 如何以此為範本新增 skill - -1. 複製 `skills/hello/` 為 `skills//`。 -2. 修改 `SKILL.md` 的 frontmatter： - - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這個名稱會成為 Claude Code / Antigravity 的 `/jsc-template:` 指令**。 - - `description`：第三人稱，寫清楚「什麼時候該用、什麼時候不該用」與觸發關鍵字 — 各家助理靠這段文字決定是否自動載入。 -3. 在內文寫下 skill 的具體步驟。 -4. 手動把新 skill 補進 README 的「Skills 目錄」區塊。 From e1cc4ed6c43c8a5191e27df0620df2a03257985d Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 13:08:43 +0800 Subject: [PATCH 02/10] =?UTF-8?q?feat(review):=20=E5=8C=AF=E5=85=A5=20jsc-?= =?UTF-8?q?review=20=E6=8A=80=E8=83=BD=E7=B5=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- references/smells.md | 158 ++++++++++++++++++++++++++++++++++++ skills/code-review/SKILL.md | 41 ++++++++++ 2 files changed, 199 insertions(+) create mode 100644 references/smells.md create mode 100644 skills/code-review/SKILL.md diff --git a/references/smells.md b/references/smells.md new file mode 100644 index 0000000..5d8abfc --- /dev/null +++ b/references/smells.md @@ -0,0 +1,158 @@ +# 程式碼壞味道審查清單 + +來源：《Refactoring》（Martin Fowler）與《A Philosophy of Software Design》（John Ousterhout，第 6 組）。 +`code-review` 技能依此清單分六組審查，每組由一個 sub agent 執行。 +每項格式：**定義 / 偵測訊號 / 建議重構手法**。 + +## 第 1 組：結構與體積問題（Bloaters） + +### 1.1 巨型類別（Large Class） + +- **定義**：單一 Class 數千行，包山包海，違反單一職責原則。 +- **偵測訊號**：類別行數過大（> 500 行需注意、> 1000 行必列）；欄位過多；方法分成多個互不相干的群組；類別名稱含 Manager、Util、Helper 等萬用字。 +- **建議重構手法**：Extract Class、Extract Subclass、Extract Interface；依職責拆分後以組合取代繼承。 + +### 1.2 臃腫函式（Long Method） + +- **定義**：一個 Function 寫了幾百行，邏輯複雜到沒人敢動。 +- **偵測訊號**：函式行數 > 50 行需注意、> 100 行必列；一個函式內有多段以空行或註解分隔的「段落」；區域變數過多；圈複雜度高。 +- **建議重構手法**：Extract Function（每個段落抽成具名函式）、Replace Temp with Query、Decompose Conditional、Replace Function with Command。 + +### 1.3 過長參數列（Long Parameter List） + +- **定義**：傳入超過 4、5 個以上的參數，呼叫時極易傳錯。 +- **偵測訊號**：參數 ≥ 5 個必列、4 個需注意；連續同型別參數（例：三個 string 相鄰）；boolean 旗標參數；呼叫端常以固定組合傳值。 +- **建議重構手法**：Introduce Parameter Object、Preserve Whole Object、Replace Parameter with Query、Remove Flag Argument。 + +### 1.4 基本型態偏執（Primitive Obsession） + +- **定義**：不用物件包裝，全部用字串或數字代替（金額、電話、狀態碼、範圍…）。 +- **偵測訊號**：以 string/int 表達有格式或規則的概念；同一組基本型態欄位在多處一起出現；以字串常數當型別碼；到處重複的驗證邏輯。 +- **建議重構手法**：Replace Primitive with Object、Replace Type Code with Subclasses、Introduce Parameter Object、Extract Class。 + +## 第 2 組：可讀性與命名問題（Obscurity） + +### 2.1 神秘命名（Mysterious Name） + +- **定義**：使用毫無意義的變數名（a、tmp、data2、doStuff）。 +- **偵測訊號**：單字母或縮寫命名（迴圈索引除外）；名稱與實際行為不符；需要讀實作才知道用途；名稱含編號（data1、data2）。 +- **建議重構手法**：Rename Variable、Rename Function、Rename Field；名稱表達「意圖」而非「實作」。 + +### 2.2 魔術數字（Magic Numbers） + +- **定義**：程式碼中直接出現沒人知道代表什麼的字面值。 +- **偵測訊號**：條件式或運算中出現裸數字/裸字串（0、1、-1、空字串與明顯單位換算除外需判斷）；同一字面值在多處出現。 +- **建議重構手法**：Replace Magic Literal（抽成具名常數或 enum）；有行為就升級為 Replace Type Code with Class。 + +### 2.3 死碼（Dead Code） + +- **定義**：已經不用卻不刪除的註解掉程式碼、變數、函式或類別。 +- **偵測訊號**：被註解掉的程式碼區塊；無人呼叫的函式/類別（grep 全庫零引用）；永遠不成立的條件分支；未使用的 import、參數、變數。 +- **建議重構手法**：Remove Dead Code（直接刪除，歷史交給版本控制）。 + +### 2.4 過度註解（Comments） + +- **定義**：因為程式碼寫太爛，只好寫一堆註解來解釋邏輯；好的程式碼應該能「自我解釋」。 +- **偵測訊號**：註解在解釋「這段在做什麼」而非「為什麼這樣做」；註解與程式碼不同步；每隔幾行就一條註解；用註解分段的長函式（同時列 1.2）。 +- **建議重構手法**：Extract Function（用函式名取代註解）、Rename（用命名取代註解）、Introduce Assertion；保留「為什麼」與外部限制類註解。 +- **注意**：本項與「註解問題」（第 5 組）互補：刪除解釋性廢話註解，補齊第 5 組要求的介面契約註解，兩者不衝突。 + +## 第 3 組：耦合與設計問題（Couplers） + +### 3.1 依賴嫉妒（Feature Envy） + +- **定義**：A 類別的函式不斷去存取、修改 B 類別的資料，顯示該函式放錯地方。 +- **偵測訊號**：函式內對別的物件的 getter/setter 呼叫次數多於對自身成員的使用；連續鏈式取值後運算（`order.customer.address.city`）。 +- **建議重構手法**：Move Function（搬到資料所在的類別）、Extract Function 後再 Move。 + +### 3.2 散彈式修改（Shotgun Surgery） + +- **定義**：每當要修改一個小功能，就必須同時修改多個不同的檔案。 +- **偵測訊號**：本次 diff 為了單一需求橫跨多檔做同質小改動；同一常數/規則散落多處；歷史上同組檔案總是一起被改。 +- **建議重構手法**：Move Function / Move Field 集中職責、Combine Functions into Class、Inline Function 後重新抽取。 + +### 3.3 發散式變化（Divergent Change） + +- **定義**：一個類別因為各種完全不相關的原因需要被修改。 +- **偵測訊號**：類別的修改歷史來自多種不相干需求；類別內方法可依「變更原因」分成多群；「如果要加 X 就改這裡，要加 Y 也改這裡」。 +- **建議重構手法**：Split Phase、Extract Class、Move Function，讓每個模組只有一個變更理由。 + +### 3.4 親密關係（Inappropriate Intimacy） + +- **定義**：兩個類別過度了解彼此的私有實作細節。 +- **偵測訊號**：存取對方的 private/internal 成員或繞過封裝（反射、friend、直接操作內部集合）；雙向依賴；子類別依賴父類別實作細節。 +- **建議重構手法**：Move Function / Move Field、Change Bidirectional to Unidirectional、Hide Delegate、Replace Subclass with Delegate。 + +## 第 4 組：邏輯與壞習慣（Dispensables & Others） + +### 4.1 重複程式碼（Duplicated Code） + +- **定義**：到處複製貼上（Copy-Paste），改一個 Bug 要改好幾個地方。 +- **偵測訊號**：相同或僅參數不同的程式片段出現 ≥ 2 處；兄弟類別有相同方法；diff 中新增的程式碼與既有程式碼雷同。 +- **建議重構手法**：Extract Function、Pull Up Method、Form Template Method、Slide Statements 後合併。 + +### 4.2 巢狀地獄（Nested If Hell） + +- **定義**：If-Else 或 Loop 疊了 5、6 層以上，箭頭型程式碼（Arrow Anti-pattern）。 +- **偵測訊號**：縮排深度 ≥ 4 層需注意、≥ 5 層必列；else 鏈過長；條件式中混合多個否定。 +- **建議重構手法**：Replace Nested Conditional with Guard Clauses（衛語句早退）、Decompose Conditional、Replace Conditional with Polymorphism、Extract Function。 + +### 4.3 誇誇其談未來性（Speculative Generality） + +- **定義**：為了解決「未來可能」會用到的功能，寫了一堆現在用不到的複雜架構。 +- **偵測訊號**：只有一個實作的抽象層/介面；從未被覆寫的 hook 方法；只在測試中使用的參數或彈性；「以後可能會需要」的註解。 +- **建議重構手法**：Collapse Hierarchy、Inline Function / Inline Class、Remove Dead Code、移除未用參數（Change Function Declaration）。 + +### 4.4 吞掉異常（Swallowed Exceptions） + +- **定義**：try-catch 裡面留白，發生錯誤時直接隱瞞，導致難以 Debug。 +- **偵測訊號**：空的 catch 區塊；catch 後只留註解或 `// ignore`；catch 住廣義 Exception 後回傳 null/預設值而不記錄；錯誤訊息被丟棄後重包。 +- **建議重構手法**：最少要記錄（log）並保留原始例外鏈；能處理才 catch，不能處理就往上拋；以 Introduce Special Case 取代以 null 掩蓋錯誤。 + +## 第 5 組：註解問題（介面契約註解） + +此組檢查「該有而沒有」的註解，與 2.4（該刪的註解）互補。 + +### 5.1 方法描述 + +- **定義**：每個公開方法要有一句話描述，並標明所屬層級：**顯示層 / 邏輯層 / 存取層**。 +- **偵測訊號**：公開方法無描述；描述未標層級；描述與方法實際行為不符。 +- **建議重構手法**：補上單句描述 + 層級標記；若一個方法橫跨多層，先依 Split Phase 拆分再各自標註。 + +### 5.2 輸入參數說明 + +- **定義**：所有輸入參數都要有用途說明。 +- **偵測訊號**：參數無說明；說明只是重複參數名稱；可選參數未說明預設行為。 +- **建議重構手法**：逐參數補「用途」說明；參數多到說明困難時同時列 1.3 並建議 Introduce Parameter Object。 + +### 5.3 輸出說明 + +- **定義**：輸出（回傳值）要說明回傳的資料內容概要。 +- **偵測訊號**：無回傳說明；未說明 null/空集合/錯誤時的回傳；回傳布林但未說明 true/false 意義。 +- **建議重構手法**：補回傳內容概要與邊界情況說明。 + +### 5.4 輸入與輸出範例 + +- **定義**：輸入與輸出參數都必須有範例；範例內容**優先嘗試從資料庫取得真實資料，失敗才透過邏輯推理**產生。 +- **偵測訊號**：註解缺範例；範例與型別不符；範例顯然是佔位假資料而環境可取得真實資料。 +- **建議重構手法**：以可用的連線查詢一筆代表性資料當範例（去識別化，不可含個資）；無法連線才以邏輯推理造出合理範例並標明為推理值。 + +### 5.5 巢狀結構註解 + +- **定義**：如果參數有巢狀結構（例如 class 內還有 class），就必須完全補齊每一層的註解。 +- **偵測訊號**：DTO/ViewModel 僅頂層有註解；內層類別、集合元素型別的欄位無說明或無範例。 +- **建議重構手法**：逐層補齊 5.1–5.4；巢狀過深（≥ 3 層）時同時評估 Extract Class 是否被濫用。 + +## 第 6 組：淺模組（Shallow Module） + +- **定義**：介面複雜度相對於功能深度過高的模組——使用它要懂的事，跟自己寫差不多（出自《A Philosophy of Software Design》：好模組要「介面簡單、實作深」）。 +- **偵測訊號**：只有一行轉呼叫（pass-through）的方法或類別；包裝層與被包裝者介面幾乎相同；參數原封不動往下傳的層層委派；為每個底層方法都開一個對應方法的「殼」。 +- **建議重構手法**：Inline Class / Inline Function 移除殼層；或反向加深模組——把散在呼叫端的邏輯（驗證、轉換、錯誤處理）收進模組內，讓介面吸收複雜度。 + +## 嚴重度分級 + +| 級別 | 意義 | 例 | +| --- | --- | --- | +| 高 | 會造成錯誤或已阻礙修改 | 吞掉異常、重複程式碼改漏、死碼誤導 | +| 中 | 持續增加維護成本 | 巨型類別、臃腫函式、巢狀地獄、Couplers 全組 | +| 低 | 可讀性與一致性 | 命名、魔術數字、註解缺漏、淺模組 | diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md new file mode 100644 index 0000000..8962083 --- /dev/null +++ b/skills/code-review/SKILL.md @@ -0,0 +1,41 @@ +--- +name: code-review +description: Review changed code against the Refactoring smell catalog in six groups (bloaters, obscurity, couplers, dispensables, comment contract, shallow modules). Run when a file change is complete or an implementation is complete, e.g. from jsc-sdlc implement. Each group runs as a sub agent over the git diff; findings are reported with file:line, severity, and refactoring, and the caller decides whether to fix. Not a replacement for the CLI's built-in security or bug review. +--- + +# code-review — 壞味道分組審查 + +依 `references/smells.md`（來自《Refactoring》）審查變更的程式碼。 + +## 審查時機 + +1. **檔案變更完成時**：單檔或一組相關檔案改完。 +2. **實作完成時**：一個工作包的所有待辦完成（`jsc-sdlc:implement` 步驟 6 呼叫）。 + +## 分工 + +- 本技能專注《Refactoring》壞味道與註解契約（第 5 組）與淺模組（第 6 組）。 +- 安全性、邏輯 bug、測試涵蓋率交給 CLI 內建的 review 能力（例：claude 的 `/security-review`），不重複實作。 + +## 流程 + +1. 取得審查範圍：`git diff`（未 commit 變更）或 `git diff {base}...HEAD`（實作完成時對基準分支）；列出變更檔案清單。 +2. 六組檢查分組進行，**每組必須以 sub agent 執行**，六組可平行： + + | 組 | 範圍 | + | --- | --- | + | 1 結構與體積（Bloaters） | smells.md 第 1 組 | + | 2 可讀性與命名（Obscurity） | smells.md 第 2 組 | + | 3 耦合與設計（Couplers） | smells.md 第 3 組 | + | 4 邏輯與壞習慣（Dispensables & Others） | smells.md 第 4 組 | + | 5 註解問題（介面契約） | smells.md 第 5 組 | + | 6 淺模組（Shallow Module） | smells.md 第 6 組 | + + 每個 sub agent 的指示：只讀不改；依該組的「定義 / 偵測訊號」逐檔檢查變更行與其所在函式/類別；每筆發現回報 `檔案:行號`、壞味道名稱、嚴重度（高/中/低，依 smells.md 分級）、一句話證據、建議重構手法。 +3. 彙整六組發現：去除重複（同位置多組命中時合併並列出所有壞味道）、依嚴重度排序。 +4. 回報審查結果清單。**本技能不修改程式碼**；是否修正由呼叫端決定（實作流程中通常高、中必修，低擇要修）。 + +## 注意 + +- 第 5 組範例資料若查詢資料庫取得，必須去識別化，不可含個資。 +- 無任何發現時明確回報「無發現」，不可留白。 From c318917b1e472f624b5d0b62e8662e5272866c12 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 13:08:43 +0800 Subject: [PATCH 03/10] =?UTF-8?q?docs(review):=20=E4=BB=A5=E7=B5=B1?= =?UTF-8?q?=E4=B8=80=E6=A0=BC=E5=BC=8F=E6=94=B9=E5=AF=AB=E7=B9=81=E9=AB=94?= =?UTF-8?q?=E4=B8=AD=E6=96=87=20README=20=E8=88=87=20AGENTS?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- AGENTS.md | 20 ++--- README.md | 226 ++++-------------------------------------------------- 2 files changed, 26 insertions(+), 220 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a86a1f1..6479cbb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,15 +1,15 @@ -# jsc-template — 共用 Skills（跨 AI 助理） +# jsc-review — 給 AI 助理的指引 -本 repo 是一組以 **Agent Skills（`SKILL.md`）** 標準撰寫的共用 skills，可同時被 Claude Code、Codex、Antigravity、OpenCode 使用。 +本 repo 是 jsc 技能組的 `review` domain（程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組），可同時被 Claude Code / Codex / Copilot / Antigravity / Kiro 使用。 -## 給 AI 助理的指引 +## 規則 -- 所有可用的 skills 位於本 repo 的 `skills//SKILL.md`。 -- 在處理任務前，先比對使用者需求與各 skill `SKILL.md` frontmatter 的 `description`，若相符請載入並依其步驟執行。 -- **呼叫慣例**：在 Claude Code 與 Antigravity 中，這些 skill 以 `/jsc-template:` 呼叫；Codex 以 `$`、OpenCode 由模型依描述自動觸發 — 兩者沒有 `/jsc-template:` 前綴，不需強制加。 -- 完整清單與每個 skill 的用途，請見 `README.md` 的「Skills 目錄」。 +1. 所有交談與輸出內容基於 STE100 使用繁體中文：短句、一句一指令、主動語態、術語一致、UTF-8 無亂碼。 +2. 技能位於 `skills/{name}/SKILL.md`；處理任務前先比對需求與各技能的 `description`，相符就載入並依其步驟執行。 +3. 技能準則的唯一來源：`plugins/meta` 存取庫的 `references/guidelines.md`。 +4. 所有 hook 只放在 `jsc-hooks`；gitea 操作一律經由 `jsc-gitea` 的 `tools/gitea.sh`；問使用者一律依 `jsc-ask:ask` 的決策樹規則。 +5. 主 agent 不需要處理細節的流程，一律建立 sub agent 處理。 -## 慣例 +## 呼叫慣例 -- 新增 skill 一律放在 `skills//`，且 `` 使用小寫與連字號。 -- `description` 要寫清楚觸發條件（何時用、何時不用），這是跨助理自動載入的唯一依據。 +Claude Code / Antigravity：`/jsc-review:{name}`；Codex：`$name`；Copilot / Kiro / OpenCode：描述需求自動觸發。 diff --git a/README.md b/README.md index 6c6669e..ac171d3 100644 --- a/README.md +++ b/README.md @@ -1,228 +1,34 @@ -# jsc-template — 跨 AI 助理 Plugin 模板 +# jsc-review — 程式碼審查 -一個可同時被 **Claude Code、Codex、Antigravity、OpenCode、GitHub Copilot** 安裝的 plugin 模板。 -核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`）， -搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。 -在 Claude Code 與 Antigravity 中，skill 以 **`/jsc-template:` 前綴**呼叫（例如 `/jsc-template:hello`）。 +jsc 技能組的 review domain：基於《Refactoring》壞味道目錄的六組審查（結構與體積、可讀性與命名、耦合與設計、邏輯與壞習慣、註解規範、淺模組），套用在檔案變更完成與實作完成兩個時機。 ---- - -## 前綴與呼叫方式 - -| 助理 | 安裝方式 | 呼叫 | `/jsc-template:` 前綴 | -| --- | --- | --- | --- | -| Claude Code | `claude plugin`（marketplace） | `/jsc-template:` 或自動觸發 | ✅ | -| Codex | `codex plugin`（marketplace） | `$` 或 `/skills` 選單 | ❌（用 `$name`） | -| Antigravity | `agy plugin install` | `/jsc-template:` 或自動觸發 | ✅ | -| OpenCode | skills 目錄（複製/clone） | 描述需求自動觸發 | ❌（依名稱） | -| GitHub Copilot CLI | `copilot plugin`（marketplace） | 自然語言或 plugin skills | ❌（無 `/jsc-template:` 前綴） | - -> Codex 不支援自訂前綴（skill 以 `$name` 呼叫）；OpenCode 由模型依描述自動呼叫；Copilot CLI 透過原生 plugin 安裝後以自然語言或 plugin skills 使用。三者皆**不強制**前綴。 - ---- - -## 目錄結構 - -同一個 repo 同時帶四種 manifest，彼此以路徑隔離、互不干擾；各助理都讀同一份 `skills/`。 - -``` -template/ -├── .claude-plugin/ -│ ├── plugin.json # Claude 外掛定義（name: "jsc-template"） -│ └── marketplace.json # Claude marketplace（name: "template"，source 指向本 repo） -├── .codex-plugin/ -│ └── plugin.json # Codex 外掛定義（name: "jsc-template"，skills: "./skills"） -├── .agents/plugins/ -│ └── marketplace.json # Codex marketplace（name: "template"，url source 指向本 repo） -├── plugin.json # Antigravity 外掛定義（name: "jsc-template"，skills: "./skills/"） -├── skills/ # ★ 唯一真實來源：所有 skills -│ └── hello/SKILL.md -├── AGENTS.md # 跨助理共用指引 -└── README.md -``` - ---- - -## 安裝 / 更新 / 移除（各助理） - -> 指令中的 repo 網址換成你的：`https://gitea.jsc.idv.tw/plugins/template.git` -> -> **Claude / Codex 從 git URL 安裝（會 clone 遠端），請先把本 repo `push` 到 gitea。** -> **Antigravity 的 `agy plugin install ` 目前只支援 github.com**；gitea 請改用「clone + 本地路徑」（見 Antigravity 節）。 -> 本機/離線：Claude 可用本地路徑加 marketplace；Antigravity 用本地路徑安裝。 - -> **⚠ 從 0.0.1 升上來的人請先移除再安裝。** 0.0.2 起 marketplace 名由 `jsc-plugins` 改為 `template` -> （舊名與 `jsc-persona` 的 marketplace 撞名）。各助理以 `@` 當安裝識別鍵， -> 改名後是兩筆獨立條目，**不能用 update 遷移**： -> -> ```bash -> claude plugin uninstall jsc-template@jsc-plugins -> claude plugin marketplace remove jsc-plugins # 若你沒有裝 jsc-persona 才移除，它也用這個名字 -> claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git -> claude plugin install jsc-template@template -> ``` -> -> 移除後記得清掉 `~/.claude/settings.json` 裡 `enabledPlugins` 的舊鍵 `jsc-template@jsc-plugins`， -> 並重開工作階段。Codex／Copilot 同理（`remove`／`uninstall` 後重新 `add`＋`install`）。 - -### Claude Code +## 安裝 ```bash -# 安裝 -claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git -claude plugin install jsc-template@template - -# 更新 -claude plugin marketplace update template -claude plugin update jsc-template@template - -# 移除 -claude plugin uninstall jsc-template@template -claude plugin marketplace remove template +claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/review.git +claude plugin install jsc-review@review ``` -- 工作階段內 slash 版（等價）：把 `claude plugin` 換成 `/plugin`。 -- 本機開發（免 push）：`claude plugin marketplace add C:\Users\h3285\source\repos.plugins\template`（本地路徑）後再 install。 -- **呼叫**：`/jsc-template:`（例 `/jsc-template:hello`）。 - -### Codex - -```bash -# 安裝 -codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git -codex plugin add jsc-template@template - -# 更新（重新抓取 marketplace 的 git 快照） -codex plugin marketplace upgrade template - -# 移除 -codex plugin remove jsc-template@template -codex plugin marketplace remove template -``` - -- 安裝 token `jsc-template@template` = plugin 名（`.codex-plugin/plugin.json` 的 `name`）@ marketplace 名（`.agents/plugins/marketplace.json` 的 `name`）。 -- 本 repo 的 Codex marketplace 以 `url` 來源指向自己，故 Codex **一律從 gitea 安裝**（需先 push）；安裝後重啟 Codex。 -- **呼叫**：`$`（例 `$hello`），或用 `/skills` 選單。 - -### Antigravity（`agy`） - -> `agy plugin install ` 目前**只支援 github.com**；gitea 等自架 git 不支援 URL 安裝，請先 `git clone` 再用**本地路徑**安裝。 - -```bash -# 安裝：clone 後用本地路徑 -git clone https://gitea.jsc.idv.tw/plugins/template.git ~/plugins/template -agy plugin install ~/plugins/template - -# 更新（agy 無 update 子指令 → git pull 後重裝） -git -C ~/plugins/template pull -agy plugin uninstall jsc-template -agy plugin install ~/plugins/template - -# 移除 -agy plugin uninstall jsc-template -``` - -- 若把 skills 放到 GitHub，則可直接 `agy plugin install https://github.com//`。 -- 其他：`agy plugin list`、`agy plugin enable jsc-template` / `disable jsc-template`、`agy plugin validate `。安裝後重啟工作階段。 -- **呼叫**：`/jsc-template:`（例 `/jsc-template:hello`）或依描述自動觸發。 - -### OpenCode - -OpenCode 的「plugin」是 TypeScript/npm 套件，不適用於 skill 包；skills 改用**目錄安裝**。 -OpenCode 會讀 `~/.config/opencode/skills/`（也會讀 `~/.claude/skills/`、`~/.agents/skills/`）。 - -```bash -# 安裝 -git clone https://gitea.jsc.idv.tw/plugins/template.git ~/plugins/template -mkdir -p ~/.config/opencode/skills -cp -r ~/plugins/template/skills/* ~/.config/opencode/skills/ - -# 更新 -git -C ~/plugins/template pull -cp -r ~/plugins/template/skills/* ~/.config/opencode/skills/ - -# 移除 -rm -rf ~/.config/opencode/skills/hello -``` - -> **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。 - -- **呼叫**：直接描述需求，模型會依 skill 描述自動透過 skill 工具呼叫。 - -### GitHub Copilot CLI - -Copilot CLI 支援與 Claude Code 類似的原生 plugin / marketplace 指令，可直接從 marketplace 安裝、更新與移除本 plugin。 - -```bash -# 安裝 -copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/template.git -copilot plugin install jsc-template@template - -# 更新 -copilot plugin marketplace update template -copilot plugin update jsc-template@template - -# 移除 -copilot plugin uninstall jsc-template@template -copilot plugin marketplace remove template -``` - -- 安裝 token `jsc-template@template` = plugin 名（plugin manifest 的 `name`）@ marketplace 名。 -- `copilot plugin marketplace add` 支援 GitHub `owner/repo`、git URL 與本地路徑；Gitea repo 可用上方 HTTPS URL。 -- **呼叫**：在 Copilot CLI 中用自然語言描述需求，例如 `copilot -i "跑 hello 確認 plugin 裝好了"`。 - ---- - -## 用 CLI 直接執行 skill（headless / 一次性） - -安裝好之後，不必進互動介面，一行指令就能叫某個 skill 跑完並印出結果： - -| 助理 | headless 指令 | 執行 `hello` skill | -| --- | --- | --- | -| Claude Code | `claude -p ""` | `claude -p "/jsc-template:hello"` | -| Codex | `codex exec ""` | `codex exec '$hello'` | -| Antigravity | `agy -p ""` | `agy -p "/jsc-template:hello"` | -| OpenCode | `opencode run ""` | `opencode run "用 hello skill 打個招呼"` | -| GitHub Copilot CLI | `copilot -p ""` | `copilot -p "用 hello skill 打個招呼"` | - -- Claude / Antigravity 支援 `/jsc-template:` 前綴，直接 `-p "/jsc-template:"` 即可。 -- Codex 以 `$` 觸發；在 shell 請用**單引號**避免 `$` 被展開：`codex exec '$hello'`。 -- OpenCode 與 Copilot 沒有前綴，用自然語言描述需求；Copilot CLI 會讀取已安裝 plugin 提供的 skills。 -- 帶引數就接在後面，例如 `claude -p "/jsc-template:hello 參數"`、`codex exec '$hello 參數'`。 - ---- +其他 CLI（codex / copilot / antigravity / kiro）與批次安裝、更新、解除安裝：使用 `/jsc-cli:deploy`。 ## Skills 目錄 -> 此區塊列出本 plugin 內含的所有 skills（名稱／描述／使用方法）。 -> 新增或修改 skill 後，請同步手動更新標記之間的內容。 +呼叫方式：Claude / Antigravity `/jsc-review:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。 -### `hello` +### `code-review` -範例 skill，用來驗證 jsc plugin 是否安裝成功，也是新增 skill 的範本。當使用者輸入 hello、想測試 plugin、或想看 skill 模板長什麼樣子時觸發；回覆一句問候並簡述此 plugin 的用途。 - -- **Claude Code / Antigravity**：`/jsc-template:hello` -- **Codex**：`$hello`，或用 `/skills` 選單 -- **OpenCode / GitHub Copilot CLI**：描述需求自動觸發 +對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號` + 嚴重度 + 建議重構手法，修正與否由呼叫端決定。安全性與 bug 審查交給 CLI 內建 review，不重複。 ---- +## 參考 -## 新增一個 skill +| 檔案 | 用途 | +| --- | --- | +| `references/smells.md` | 六組壞味道完整清單：定義、偵測訊號、建議重構手法、嚴重度分級；範例資料必須去識別化 | -1. 複製範本：`cp -r skills/hello skills/` -2. 編輯 `skills//SKILL.md` 的 frontmatter： - - `name`：小寫、數字、連字號（`-`），最長 64 字元。**這就是 Claude Code / Antigravity 的 `/jsc-template:`**。 - - `description`：第三人稱，寫清楚「何時用、何時不用」與觸發關鍵字 — 這是各助理自動載入的唯一依據。 -3. 在內文寫下 skill 的具體步驟。 -4. 手動把這個 skill 補進上方「Skills 目錄」區塊。 -5. **bump 版本並 push**：各助理都以 git 內容/版本判斷更新，請把 `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` 三個 manifest 的 `version` 一起 bump，commit 後 push 到 gitea。 -6. 讓各助理更新： - - Claude：`claude plugin update jsc-template@template` - - Codex：`codex plugin marketplace upgrade template` - - Antigravity：`git -C ~/jsc-plugin pull && agy plugin uninstall jsc-template && agy plugin install ~/jsc-plugin` - - OpenCode：`git pull` 後重新複製 `skills/` - - Copilot：`copilot plugin marketplace update template && copilot plugin update jsc-template@template` +## 相關 domain + +- `jsc-sdlc`：實作階段完成後呼叫本審查 From 19da66d0ba076420b88a94c75578f6e4f8d549a6 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 14:03:39 +0800 Subject: [PATCH 04/10] =?UTF-8?q?chore(review):=20=E7=89=88=E6=9C=AC?= =?UTF-8?q?=E8=99=9F=E6=94=B9=E7=82=BA=200.0.1=20=E4=B8=A6=E7=A7=BB?= =?UTF-8?q?=E9=99=A4=E5=80=8B=E5=88=A5=20marketplace=EF=BC=88=E7=B5=B1?= =?UTF-8?q?=E4=B8=80=E7=82=BA=20jsc=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .agents/plugins/marketplace.json | 12 ------------ .claude-plugin/marketplace.json | 14 -------------- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 5 files changed, 3 insertions(+), 29 deletions(-) delete mode 100644 .agents/plugins/marketplace.json delete mode 100644 .claude-plugin/marketplace.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json deleted file mode 100644 index 823cc7d..0000000 --- a/.agents/plugins/marketplace.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "name": "review", - "plugins": [ - { - "name": "jsc-review", - "source": { - "source": "url", - "url": "https://gitea.jsc.idv.tw/plugins/review.git" - } - } - ] -} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json deleted file mode 100644 index e20cc0a..0000000 --- a/.claude-plugin/marketplace.json +++ /dev/null @@ -1,14 +0,0 @@ -{ - "name": "review", - "description": "jsc 技能組 review domain 的 marketplace。", - "owner": { - "name": "JSC" - }, - "plugins": [ - { - "name": "jsc-review", - "source": "./", - "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組" - } - ] -} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index b7a7ab4..0e77fd8 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.2.0", + "version": "0.0.1", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index e345038..e02cee1 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.2.0", + "version": "0.0.1", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 05d28f6..7bec8ee 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.2.0", + "version": "0.0.1", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills/" } From 914e17eed88de52302ccf9d09610acdef43354b9 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 14:03:39 +0800 Subject: [PATCH 05/10] =?UTF-8?q?docs(review):=20README=20=E5=AE=89?= =?UTF-8?q?=E8=A3=9D/=E6=9B=B4=E6=96=B0/=E7=A7=BB=E9=99=A4=E6=94=B9?= =?UTF-8?q?=E7=82=BA=E6=AF=8F=E6=8C=87=E4=BB=A4=E4=B8=80=E8=A1=8C=EF=BC=88?= =?UTF-8?q?=E4=BA=94=E5=80=8B=20CLI=EF=BC=89=E4=B8=A6=E7=82=BA=E7=9B=B8?= =?UTF-8?q?=E9=97=9C=20domain=20=E5=8A=A0=E4=B8=8A=20repo=20=E9=80=A3?= =?UTF-8?q?=E7=B5=90?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- README.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index ac171d3..70c2100 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,19 @@ jsc 技能組的 review domain：基於《Refactoring》壞味道目錄的六組審查（結構與體積、可讀性與命名、耦合與設計、邏輯與壞習慣、註解規範、淺模組），套用在檔案變更完成與實作完成兩個時機。 -## 安裝 +## 安裝 / 更新 / 移除 -```bash -claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/review.git -claude plugin install jsc-review@review -``` +Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安裝 token 為 `jsc-review@jsc`。每個指令一行： -其他 CLI（codex / copilot / antigravity / kiro）與批次安裝、更新、解除安裝：使用 `/jsc-cli:deploy`。 +| CLI | 安裝 | 更新 | 移除 | +| --- | --- | --- | --- | +| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/jsc.git && claude plugin install jsc-review@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-review@jsc` | `claude plugin uninstall jsc-review@jsc` | +| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/jsc.git && codex plugin add jsc-review@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-review@jsc` | +| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/jsc.git && copilot plugin install jsc-review@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-review@jsc` | `copilot plugin uninstall jsc-review@jsc` | +| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/review.git ~/plugins/review && agy plugin install ~/plugins/review` | `git -C ~/plugins/review pull && agy plugin uninstall jsc-review && agy plugin install ~/plugins/review` | `agy plugin uninstall jsc-review` | +| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/jsc.git && kiro-cli plugin install jsc-review@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-review@jsc` | `kiro-cli plugin uninstall jsc-review@jsc` | + +> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。 ## Skills 目錄 @@ -31,4 +36,4 @@ claude plugin install jsc-review@review ## 相關 domain -- `jsc-sdlc`：實作階段完成後呼叫本審查 +- [`jsc-sdlc`](https://gitea.jsc.idv.tw/plugins/sdlc)：實作階段完成後呼叫本審查 From 5896f09f689bc15881f3f0866fd9ab2db9650aae Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 14:13:27 +0800 Subject: [PATCH 06/10] =?UTF-8?q?docs(review):=20AGENTS=20=E8=AA=9E?= =?UTF-8?q?=E8=A8=80=E8=A6=8F=E5=89=87=E6=94=B9=E6=8C=87=E5=90=91=20jsc-me?= =?UTF-8?q?ta=20=E7=9A=84=20references/ste100.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 6479cbb..f15ccc2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ ## 規則 -1. 所有交談與輸出內容基於 STE100 使用繁體中文：短句、一句一指令、主動語態、術語一致、UTF-8 無亂碼。 +1. 所有交談與輸出內容使用 STE100 繁體中文，帶擬人台灣感：短句、一句一指令、台灣用語、全形標點、去 AI 味、直接講重點。完整規則的唯一來源：`plugins/meta` 的 `references/ste100.md`。 2. 技能位於 `skills/{name}/SKILL.md`；處理任務前先比對需求與各技能的 `description`，相符就載入並依其步驟執行。 3. 技能準則的唯一來源：`plugins/meta` 存取庫的 `references/guidelines.md`。 4. 所有 hook 只放在 `jsc-hooks`；gitea 操作一律經由 `jsc-gitea` 的 `tools/gitea.sh`；問使用者一律依 `jsc-ask:ask` 的決策樹規則。 From 2c03779e41bace05d2e6765f481cec5f6157e5e1 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 14:17:32 +0800 Subject: [PATCH 07/10] =?UTF-8?q?style(review):=20=E4=BE=9D=20STE100=20?= =?UTF-8?q?=E6=93=AC=E4=BA=BA=E5=8F=B0=E7=81=A3=E6=84=9F=E8=A6=8F=E5=89=87?= =?UTF-8?q?=E6=94=B9=E5=AF=AB=E8=AA=9E=E6=84=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- AGENTS.md | 2 +- README.md | 2 +- references/smells.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f15ccc2..eb7df0b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # jsc-review — 給 AI 助理的指引 -本 repo 是 jsc 技能組的 `review` domain（程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組），可同時被 Claude Code / Codex / Copilot / Antigravity / Kiro 使用。 +本 repo 是 jsc 技能組的 `review` domain（程式碼審查：Refactoring 壞味道六組、註解規範、淺模組），可同時被 Claude Code / Codex / Copilot / Antigravity / Kiro 使用。 ## 規則 diff --git a/README.md b/README.md index 70c2100..dffc6f7 100644 --- a/README.md +++ b/README.md @@ -24,7 +24,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安 ### `code-review` -對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號` + 嚴重度 + 建議重構手法，修正與否由呼叫端決定。安全性與 bug 審查交給 CLI 內建 review，不重複。 +對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。安全性與 bug 審查交給 CLI 內建 review，不重複。 diff --git a/references/smells.md b/references/smells.md index 5d8abfc..4e1bc54 100644 --- a/references/smells.md +++ b/references/smells.md @@ -26,7 +26,7 @@ ### 1.4 基本型態偏執（Primitive Obsession） -- **定義**：不用物件包裝，全部用字串或數字代替（金額、電話、狀態碼、範圍…）。 +- **定義**：不用物件包裝，全部用字串或數字代替（金額、電話、狀態碼、範圍等）。 - **偵測訊號**：以 string/int 表達有格式或規則的概念；同一組基本型態欄位在多處一起出現；以字串常數當型別碼；到處重複的驗證邏輯。 - **建議重構手法**：Replace Primitive with Object、Replace Type Code with Subclasses、Introduce Parameter Object、Extract Class。 @@ -117,7 +117,7 @@ - **定義**：每個公開方法要有一句話描述，並標明所屬層級：**顯示層 / 邏輯層 / 存取層**。 - **偵測訊號**：公開方法無描述；描述未標層級；描述與方法實際行為不符。 -- **建議重構手法**：補上單句描述 + 層級標記；若一個方法橫跨多層，先依 Split Phase 拆分再各自標註。 +- **建議重構手法**：補上單句描述與層級標記；若一個方法橫跨多層，先依 Split Phase 拆分再各自標註。 ### 5.2 輸入參數說明 From ccf83badbb4493fb416e6d7c0898fdb83efffdd7 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 14:29:47 +0800 Subject: [PATCH 08/10] docs(review): translate SKILL.md into English per guidelines Co-Authored-By: Claude Fable 5 --- skills/code-review/SKILL.md | 48 ++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index 8962083..b416ed8 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -3,39 +3,39 @@ name: code-review description: Review changed code against the Refactoring smell catalog in six groups (bloaters, obscurity, couplers, dispensables, comment contract, shallow modules). Run when a file change is complete or an implementation is complete, e.g. from jsc-sdlc implement. Each group runs as a sub agent over the git diff; findings are reported with file:line, severity, and refactoring, and the caller decides whether to fix. Not a replacement for the CLI's built-in security or bug review. --- -# code-review — 壞味道分組審查 +# code-review -依 `references/smells.md`（來自《Refactoring》）審查變更的程式碼。 +Review changed code against `references/smells.md` (from the book *Refactoring*). The reference is written in Traditional Chinese; read it as-is. -## 審查時機 +## When to run -1. **檔案變更完成時**：單檔或一組相關檔案改完。 -2. **實作完成時**：一個工作包的所有待辦完成（`jsc-sdlc:implement` 步驟 6 呼叫）。 +1. **When a file change is complete**: one file or one related group of files is done. +2. **When an implementation is complete**: all todos of a work package are done (called by `jsc-sdlc:implement` step 6). -## 分工 +## Division of labor -- 本技能專注《Refactoring》壞味道與註解契約（第 5 組）與淺模組（第 6 組）。 -- 安全性、邏輯 bug、測試涵蓋率交給 CLI 內建的 review 能力（例：claude 的 `/security-review`），不重複實作。 +- This skill covers the *Refactoring* smells, the comment contract (group 5), and shallow modules (group 6). +- Security, logic bugs, and test coverage belong to the CLI's built-in review (e.g. claude's `/security-review`); do not duplicate them. -## 流程 +## Steps -1. 取得審查範圍：`git diff`（未 commit 變更）或 `git diff {base}...HEAD`（實作完成時對基準分支）；列出變更檔案清單。 -2. 六組檢查分組進行，**每組必須以 sub agent 執行**，六組可平行： +1. Get the review scope: `git diff` (uncommitted changes) or `git diff {base}...HEAD` (against the base branch when an implementation is complete); list the changed files. +2. Review in six groups, and every group **MUST run as a sub agent**; the six groups may run in parallel: - | 組 | 範圍 | + | Group | Scope | | --- | --- | - | 1 結構與體積（Bloaters） | smells.md 第 1 組 | - | 2 可讀性與命名（Obscurity） | smells.md 第 2 組 | - | 3 耦合與設計（Couplers） | smells.md 第 3 組 | - | 4 邏輯與壞習慣（Dispensables & Others） | smells.md 第 4 組 | - | 5 註解問題（介面契約） | smells.md 第 5 組 | - | 6 淺模組（Shallow Module） | smells.md 第 6 組 | + | 1 Bloaters | smells.md group 1 | + | 2 Obscurity | smells.md group 2 | + | 3 Couplers | smells.md group 3 | + | 4 Dispensables & Others | smells.md group 4 | + | 5 Comment contract | smells.md group 5 | + | 6 Shallow Module | smells.md group 6 | - 每個 sub agent 的指示：只讀不改；依該組的「定義 / 偵測訊號」逐檔檢查變更行與其所在函式/類別；每筆發現回報 `檔案:行號`、壞味道名稱、嚴重度（高/中/低，依 smells.md 分級）、一句話證據、建議重構手法。 -3. 彙整六組發現：去除重複（同位置多組命中時合併並列出所有壞味道）、依嚴重度排序。 -4. 回報審查結果清單。**本技能不修改程式碼**；是否修正由呼叫端決定（實作流程中通常高、中必修，低擇要修）。 + Instructions for each sub agent: read only, change nothing; check every changed line and its enclosing function or class against the group's definitions and detection signals in smells.md; report each finding as `file:line`, smell name, severity (高、中、低 per the smells.md scale), one sentence of evidence, and the suggested refactoring. Findings are reported in Traditional Chinese. +3. Merge the six groups' findings: deduplicate (when one location hits several groups, merge and list every smell), then sort by severity. +4. Report the finding list. **This skill never modifies code**; the caller decides what to fix (inside the implementation flow, 高 and 中 are normally mandatory, 低 is judgment). -## 注意 +## Notes -- 第 5 組範例資料若查詢資料庫取得，必須去識別化，不可含個資。 -- 無任何發現時明確回報「無發現」，不可留白。 +- If group 5 examples are fetched from a database, they must be de-identified; never include personal data. +- When there are no findings, report the literal 「無發現」 explicitly; never leave the report empty. From 3692c9e915a8d14bfd5009f0e4852f1a59acf7d0 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 14:29:47 +0800 Subject: [PATCH 09/10] =?UTF-8?q?style(review):=20=E4=B8=AD=E6=96=87?= =?UTF-8?q?=E4=B8=A6=E5=88=97=E6=94=B9=E9=A0=93=E8=99=9F?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- README.md | 2 +- references/smells.md | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index dffc6f7..3e9a0b4 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ jsc 技能組的 review domain：基於《Refactoring》壞味道目錄的六組審查（結構與體積、可讀性與命名、耦合與設計、邏輯與壞習慣、註解規範、淺模組），套用在檔案變更完成與實作完成兩個時機。 -## 安裝 / 更新 / 移除 +## 安裝、更新、移除 Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/jsc.git），安裝 token 為 `jsc-review@jsc`。每個指令一行： diff --git a/references/smells.md b/references/smells.md index 4e1bc54..b1d801d 100644 --- a/references/smells.md +++ b/references/smells.md @@ -2,7 +2,7 @@ 來源：《Refactoring》（Martin Fowler）與《A Philosophy of Software Design》（John Ousterhout，第 6 組）。 `code-review` 技能依此清單分六組審查，每組由一個 sub agent 執行。 -每項格式：**定義 / 偵測訊號 / 建議重構手法**。 +每項格式：**定義、偵測訊號、建議重構手法**。 ## 第 1 組：結構與體積問題（Bloaters） @@ -41,13 +41,13 @@ ### 2.2 魔術數字（Magic Numbers） - **定義**：程式碼中直接出現沒人知道代表什麼的字面值。 -- **偵測訊號**：條件式或運算中出現裸數字/裸字串（0、1、-1、空字串與明顯單位換算除外需判斷）；同一字面值在多處出現。 +- **偵測訊號**：條件式或運算中出現裸數字、裸字串（0、1、-1、空字串與明顯單位換算除外需判斷）；同一字面值在多處出現。 - **建議重構手法**：Replace Magic Literal（抽成具名常數或 enum）；有行為就升級為 Replace Type Code with Class。 ### 2.3 死碼（Dead Code） - **定義**：已經不用卻不刪除的註解掉程式碼、變數、函式或類別。 -- **偵測訊號**：被註解掉的程式碼區塊；無人呼叫的函式/類別（grep 全庫零引用）；永遠不成立的條件分支；未使用的 import、參數、變數。 +- **偵測訊號**：被註解掉的程式碼區塊；無人呼叫的函式、類別（grep 全庫零引用）；永遠不成立的條件分支；未使用的 import、參數、變數。 - **建議重構手法**：Remove Dead Code（直接刪除，歷史交給版本控制）。 ### 2.4 過度註解（Comments） @@ -68,7 +68,7 @@ ### 3.2 散彈式修改（Shotgun Surgery） - **定義**：每當要修改一個小功能，就必須同時修改多個不同的檔案。 -- **偵測訊號**：本次 diff 為了單一需求橫跨多檔做同質小改動；同一常數/規則散落多處；歷史上同組檔案總是一起被改。 +- **偵測訊號**：本次 diff 為了單一需求橫跨多檔做同質小改動；同一常數或規則散落多處；歷史上同組檔案總是一起被改。 - **建議重構手法**：Move Function / Move Field 集中職責、Combine Functions into Class、Inline Function 後重新抽取。 ### 3.3 發散式變化（Divergent Change） @@ -100,13 +100,13 @@ ### 4.3 誇誇其談未來性（Speculative Generality） - **定義**：為了解決「未來可能」會用到的功能，寫了一堆現在用不到的複雜架構。 -- **偵測訊號**：只有一個實作的抽象層/介面；從未被覆寫的 hook 方法；只在測試中使用的參數或彈性；「以後可能會需要」的註解。 +- **偵測訊號**：只有一個實作的抽象層或介面；從未被覆寫的 hook 方法；只在測試中使用的參數或彈性；「以後可能會需要」的註解。 - **建議重構手法**：Collapse Hierarchy、Inline Function / Inline Class、Remove Dead Code、移除未用參數（Change Function Declaration）。 ### 4.4 吞掉異常（Swallowed Exceptions） - **定義**：try-catch 裡面留白，發生錯誤時直接隱瞞，導致難以 Debug。 -- **偵測訊號**：空的 catch 區塊；catch 後只留註解或 `// ignore`；catch 住廣義 Exception 後回傳 null/預設值而不記錄；錯誤訊息被丟棄後重包。 +- **偵測訊號**：空的 catch 區塊；catch 後只留註解或 `// ignore`；catch 住廣義 Exception 後回傳 null 或預設值而不記錄；錯誤訊息被丟棄後重包。 - **建議重構手法**：最少要記錄（log）並保留原始例外鏈；能處理才 catch，不能處理就往上拋；以 Introduce Special Case 取代以 null 掩蓋錯誤。 ## 第 5 組：註解問題（介面契約註解） @@ -115,7 +115,7 @@ ### 5.1 方法描述 -- **定義**：每個公開方法要有一句話描述，並標明所屬層級：**顯示層 / 邏輯層 / 存取層**。 +- **定義**：每個公開方法要有一句話描述，並標明所屬層級：**顯示層、邏輯層、存取層**。 - **偵測訊號**：公開方法無描述；描述未標層級；描述與方法實際行為不符。 - **建議重構手法**：補上單句描述與層級標記；若一個方法橫跨多層，先依 Split Phase 拆分再各自標註。 @@ -128,7 +128,7 @@ ### 5.3 輸出說明 - **定義**：輸出（回傳值）要說明回傳的資料內容概要。 -- **偵測訊號**：無回傳說明；未說明 null/空集合/錯誤時的回傳；回傳布林但未說明 true/false 意義。 +- **偵測訊號**：無回傳說明；未說明 null、空集合、錯誤時的回傳；回傳布林但未說明 true/false 意義。 - **建議重構手法**：補回傳內容概要與邊界情況說明。 ### 5.4 輸入與輸出範例 From 0a5ad4f75f6e17b0e783948333b4d1c053f2f53b Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 21 Aug 2026 14:37:50 +0800 Subject: [PATCH 10/10] =?UTF-8?q?chore(review):=20=E5=8A=A0=E5=85=A5?= =?UTF-8?q?=E7=B5=B1=E4=B8=80=20jsc=20marketplace=20=E5=89=AF=E6=9C=AC?= =?UTF-8?q?=EF=BC=88=E8=88=87=E6=AD=A3=E6=9C=AC=E4=B8=80=E8=87=B4=EF=BC=8C?= =?UTF-8?q?=E4=BB=BB=E4=B8=80=20repo=20=E5=8F=AF=E4=BD=9C=E8=A8=BB?= =?UTF-8?q?=E5=86=8A=E5=85=A5=E5=8F=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- .agents/plugins/marketplace.json | 75 +++++++++++++++++++++++++++ .claude-plugin/marketplace.json | 89 ++++++++++++++++++++++++++++++++ 2 files changed, 164 insertions(+) create mode 100644 .agents/plugins/marketplace.json create mode 100644 .claude-plugin/marketplace.json diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..12df680 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,75 @@ +{ + "name": "jsc", + "plugins": [ + { + "name": "jsc-ask", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/ask.git" + } + }, + { + "name": "jsc-cli", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/cli.git" + } + }, + { + "name": "jsc-git", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/git.git" + } + }, + { + "name": "jsc-gitea", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/gitea.git" + } + }, + { + "name": "jsc-hooks", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/hooks.git" + } + }, + { + "name": "jsc-log", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/log.git" + } + }, + { + "name": "jsc-meta", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/meta.git" + } + }, + { + "name": "jsc-pkg", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/pkg.git" + } + }, + { + "name": "jsc-review", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/review.git" + } + }, + { + "name": "jsc-sdlc", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/sdlc.git" + } + } + ] +} diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..28bb223 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,89 @@ +{ + "name": "jsc", + "description": "jsc 跨 AI 助理技能組的統一 marketplace（claude / codex / copilot / antigravity / kiro）。", + "owner": { + "name": "JSC" + }, + "plugins": [ + { + "name": "jsc-ask", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/ask.git" + }, + "description": "決策樹問詢與問詢紀錄（QUESTION_* wiki 頁）" + }, + { + "name": "jsc-cli", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/cli.git" + }, + "description": "CLI 偵測、模型能力標籤與技能庫批次部署" + }, + { + "name": "jsc-git", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/git.git" + }, + "description": "Commit 分組認可與 Push Request 建立" + }, + { + "name": "jsc-gitea", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/gitea.git" + }, + "description": "Gitea API 工具、Wiki 讀寫與存取庫批次同步" + }, + { + "name": "jsc-hooks", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/hooks.git" + }, + "description": "跨 CLI hooks：STE100 語言強制、工時計時、技能用量記錄" + }, + { + "name": "jsc-log", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/log.git" + }, + "description": "工作日誌（LOG_* wiki 頁）與技能使用統計" + }, + { + "name": "jsc-meta", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/meta.git" + }, + "description": "技能組自我管理：新建/更新/刪除技能與技能準則" + }, + { + "name": "jsc-pkg", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/pkg.git" + }, + "description": "套件批次更新（nodejs/python/dotnet），失敗還原" + }, + { + "name": "jsc-review", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/review.git" + }, + "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組" + }, + { + "name": "jsc-sdlc", + "source": { + "source": "url", + "url": "https://gitea.jsc.idv.tw/plugins/sdlc.git" + }, + "description": "開發生命週期：規劃/分析/實作/維護（wiki 追蹤）" + } + ] +}