feat(review): code-review 範圍改為 5.1 到 5.8 並補上與 api-doc 的分工

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 技能與存取庫說明文件。
This commit is contained in:
2026-08-27 15:41:38 +08:00
parent dfaa66feda
commit 51c2705667
2 changed files with 12 additions and 1 deletions
+2 -1
View File
@@ -16,6 +16,7 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
- 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.
- Swagger document auditing belongs to `jsc-review:api-doc`: response type declarations per HTTP status code, Swagger parameter descriptions, and Swagger examples down the nested data models. Group 5 here covers the source comment contract only; the two never report the same gap twice.
## Steps
@@ -28,7 +29,7 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
| 2 Obscurity | smells.md group 2, including 2.5 document reference leak — comments carrying issue ids, wiki page ids, work package ids, commit hashes, @ mentions, or external document links; the full banned and allowed lists live in `references/comment-scope.md` |
| 3 Couplers | smells.md group 3 |
| 4 Dispensables & Others | smells.md group 4 |
| 5 Comment contract | smells.md group 5 |
| 5 Comment contract | smells.md group 5, 5.1 to 5.8 — including 5.6 navigation links to the functions a method calls, 5.7 XML comment tag layout (opening and closing tag each on its own line), and 5.8 code-element markup by language convention (`<paramref>`, `<see cref>`, `<c>` in XML; backticks in JSDoc and docstrings) |
| 6 Shallow Module | smells.md group 6 |
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.