jiantw83
51c2705667
What：skills/code-review/SKILL.md 的審查範圍表，第 5 組由原本一句 「smells.md group 5」改成明確的 5.1 到 5.8，並點名 5.6、5.7、5.8 三個新項目； Notes 加一行分工，Swagger 文件稽核歸 api-doc。README.md 新增 api-doc 的技能 小節，另補一張工具表格列出 swagger-detect.sh。 Why：sub agent 讀的是 SKILL.md 的審查範圍表，範圍表沒寫清楚，新增的 5.6 到 5.8 就不會被查。使用者讀的是 README.md，新技能與新工具沒列出來就找不到。 兩支技能都碰註解與文件，界線不寫明就會對同一個缺失重複回報。 How：範圍表的第 5 組直接列出三個新項目與各自的判準重點，完整清單仍指向 references/smells.md。Notes 寫明 api-doc 負責狀態碼的回覆類型、Swagger 參數 說明與範例，第 5 組只負責原始碼註解契約。README.md 的技能小節寫明偵測先行、 只裝套件沒掛接就停手；工具表格列出 swagger-detect.sh 的用途、輸出欄位與結束碼。 Who：jsc-review 的 code-review 技能與存取庫說明文件。
53 lines
4.4 KiB
Markdown
53 lines
4.4 KiB
Markdown
# jsc-review — 程式碼審查
|
||
|
||
jsc 技能組的 review domain：基於《Refactoring》壞味道目錄的六組審查（結構與體積、可讀性與命名、耦合與設計、邏輯與壞習慣、註解規範、淺模組），套用在檔案變更完成與實作完成兩個時機。
|
||
|
||
## 安裝、更新、移除
|
||
|
||
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-review@jsc`。每個指令一行：
|
||
|
||
| CLI | 安裝 | 更新 | 移除 |
|
||
| --- | --- | --- | --- |
|
||
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.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/meta.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/meta.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/meta.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`。
|
||
|
||
> 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。
|
||
|
||
## Skills 目錄
|
||
|
||
呼叫方式：Claude / Antigravity `/jsc-review:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
|
||
|
||
<!-- JSC-SKILLS:START -->
|
||
|
||
### `code-review`
|
||
|
||
對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。第 2 組同時擋「文件編號夾帶」：註解只寫「為什麼這樣寫」，議題編號、wiki 頁編號、工作包編號、commit hash、`@` 提及、外部文件連結一律不進註解，清單看 `references/comment-scope.md`。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 review，不重複。
|
||
|
||
### `api-doc`
|
||
|
||
稽核 API 專案的 Swagger 文件：每個可能回傳的 HTTP 狀態碼都要宣告回覆類型，每個輸入與輸出都要有說明與真實資料範例，並沿著巢狀資料模型逐層遞迴。控制器改完或實作完成時執行，例如由 `jsc-sdlc:implement` 呼叫，與 `jsc-review:code-review` 並列為兩關收尾稽核。先跑 `tools/swagger-detect.sh` 偵測，套件與掛接設定要雙重命中才算支援；只裝套件沒掛接就回報未啟用並停手，不開任何 sub agent。原始碼的註解契約歸 `jsc-review:code-review` 第 5 組，這支只管 Swagger 文件屬性與範例，兩支不重複回報。回報 `檔案:行號`、嚴重度與建議修法，本技能不改程式碼。
|
||
|
||
<!-- JSC-SKILLS:END -->
|
||
|
||
## 參考
|
||
|
||
| 檔案 | 用途 |
|
||
| --- | --- |
|
||
| `references/smells.md` | 六組壞味道完整清單：定義、偵測訊號、建議重構手法、嚴重度分級；範例資料必須去識別化 |
|
||
| `references/comment-scope.md` | 程式碼註解內容界線：禁止寫進註解的文件編號清單、允許項目與白名單、命中時的改法 |
|
||
|
||
## 工具
|
||
|
||
| 檔案 | 用途 |
|
||
| --- | --- |
|
||
| `tools/swagger-detect.sh` | 判斷專案有沒有真的啟用 Swagger。套件與設定雙重確認，缺一不算支援。輸出 `support=`、`stack=`、`package=`、`config=`；結束碼 0 支援、1 不支援、2 參數或路徑錯誤 |
|
||
|
||
## 相關 domain
|
||
|
||
- [`jsc-sdlc`](https://gitea.jsc.idv.tw/plugins/sdlc)：實作階段完成後呼叫本審查
|