plugins/review
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge pull request 'feat/change-requests/comment-cleanup-skill' (#13) from feat/change-requests/comment-cleanup-skill into feat/change-requests/main

Browse Source 
Reviewed-on: #13
This commit was merged in pull request #13.
This commit is contained in:
admin
2026-08-28 01:47:03 +00:00
parent 5a2d5d1bab b3d8337001
commit c1d8162066
7 changed files with 58 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude-plugin/plugin.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-review",
"version": "0.0.6",
"version": "0.0.8",
"description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
"skills": "./skills",
"author": {
.codex-plugin/plugin.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-review",
"version": "0.0.6",
"version": "0.0.8",
"description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
"skills": "./skills"
}
README.md
+6 -2
View File
@@ -26,12 +26,16 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
### `code-review`
對 git diff 進行六組壞味道審查，每組一個 sub agent 平行執行；回報 `檔案:行號`、嚴重度、建議重構手法，修正與否由呼叫端決定。第 2 組同時擋「文件編號夾帶」：註解只寫「為什麼這樣寫」，議題編號、wiki 頁編號、工作包編號、commit hash、`@` 提及、外部文件連結一律不進註解，清單看 `references/comment-scope.md`。diff 是空的就直接回報「無發現」，不開任何 sub agent；六組全部回覆才進入彙整，沒東西可報的那組也要回「無發現」。安全性與 bug 審查交給 CLI 內建 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 文件屬性與範例，兩支不重複回報。回報 `檔案:行號`、嚴重度與建議修法，本技能不改程式碼。
### `comment-cleanup`
清理本次變更新增或修改的註解，把文件追蹤資訊與審查流程痕跡移除，只留下程式邏輯的實質理由。使用者要求「清一下註解」、「不要留 review 痕跡」，或 commit 前發現註解夾帶流程資訊時執行。判斷準則只看 `references/comment-scope.md`，本技能負責清理，`comment-scope.sh` 負責擋，`code-review` 第 2 組負責指出人工判讀案例。未明確要求時不動未變更的舊註解。
<!-- JSC-SKILLS:END -->
## 參考
@@ -39,7 +43,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
| 檔案 | 用途 |
| --- | --- |
| `references/smells.md` | 六組壞味道完整清單：定義、偵測訊號、建議重構手法、嚴重度分級；範例資料必須去識別化 |
| `references/comment-scope.md` | 程式碼註解內容界線：禁止寫進註解的文件編號清單、允許項目與白名單、命中時的改法 |
| `references/comment-scope.md` | 程式碼註解內容界線：禁止寫進註解的文件編號、審查流程痕跡、允許項目與白名單、命中時的改法 |
## 工具
plugin.json
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "jsc-review",
"version": "0.0.6",
"version": "0.0.8",
"description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組",
"skills": "./skills/"
}
references/comment-scope.md
+14
View File
@@ -65,6 +65,18 @@
| 產生來源署名、AI 署名 | `// 本檔由 jsc-sdlc:implement 產生` |
| 外部文件連結 | `// 見 Confluence、Notion、Google Docs 連結` |
### 審查流程痕跡
這些資訊是討論當下的座標。沒有參與那場討論的人看不懂，討論結束後也會失效。註解要留下程式邏輯的原因，不留下審查流程的路徑。
| 項目 | 命中例 |
| --- | --- |
| `review`、`code review` 字樣用來描述審查流程 | `// code review 要求改成共用函式` |
| 輪次描述 | `// 第二輪追加檢查這個分支` |
| 問題與發現編號 | `// Finding1：避免空指標`、`// 問題3 已修` |
| 審查者代稱或工具名 | `// hermes 建議保留這個判斷`、`// CodeReview bot 標出這裡` |
| 審查狀態標籤 | `// 真缺陷，已解決`、`// BLOCKING` |
## 允許寫進註解
| 項目 | 允許的理由 | 例 |
@@ -87,5 +99,7 @@
| `// 見 #123` | 把 `#123` 裡的原因寫進註解本身 |
| `// @someone 2026-08-26 修` | `// 2026-08-26 改用新費率` |
| `// PLAN_A1B2C3D4 第 2 頁的規則` | 把該頁的規則正文濃縮成一句寫進來 |
| `// Finding1：避免空指標` | `// 輸入來自外部系統，空值要直接略過` |
| `// 第二輪追加這個判斷` | `// 舊資料可能缺欄位，先補預設值再解析` |
原則一句話：把編號指向的內容**搬進註解**，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。
skills/code-review/SKILL.md
+2 -2
View File
@@ -26,7 +26,7 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
| Group | Scope |
| --- | --- |
| 1 Bloaters | smells.md group 1 |
| 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` |
| 2 Obscurity | smells.md group 2, including 2.5 comment scope leaks — comments carrying issue ids, wiki page ids, work package ids, commit hashes, @ mentions, external document links, review rounds, finding ids, reviewer aliases, or review status labels; 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.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) |
@@ -40,6 +40,6 @@ Review changed code against `references/smells.md` (from the book *Refactoring*)
## Notes
- `jsc-hooks`' `comment-scope.sh` already matches the pattern-detectable items after every file write. Group 2 here covers what patterns cannot decide — project code names and customer names — plus the overall judgment; the two never report the same finding twice.
- `jsc-hooks`' `comment-scope.sh` already matches the pattern-detectable items after every file write. Group 2 here covers what patterns cannot decide — project code names, customer names, and context-dependent review traces — plus the overall judgment; the two never report the same finding twice.
- 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.
skills/comment-cleanup/SKILL.md
+33
View File
@@ -0,0 +1,33 @@
---
name: comment-cleanup
description: Clean review traces and document-tracking noise from comments touched by the current change. Use when the user asks to clean comments, remove review traces, or when a pre-commit check finds process details in changed comments. It rewrites comments only, keeps code behavior unchanged, and uses references/comment-scope.md as the single source of banned and allowed content. Do not use for untouched legacy comments unless the user explicitly asks for that wider scope.
---
# comment-cleanup
Clean comments changed in the current diff so they explain why the code exists, without carrying review traces, issue coordinates, wiki page ids, or other process-only details.
## When to run
1. **User asks to clean comments**: examples include "clean the comments", "remove review traces", or "do not leave review artifacts".
2. **Before commit**: `jsc-hooks` reports comment scope warnings, or a changed comment clearly carries process-only details.
3. **Not for untouched legacy comments**: only widen the scope when the user explicitly asks for legacy cleanup.
## Single Source
Use `references/comment-scope.md` for the banned list, allowed list, and rewrite rules. Do not copy those lists into this skill.
## Division of Labor
- `jsc-hooks/comment-scope.sh` blocks pattern-detectable violations after writes.
- `jsc-review:code-review` group 2 reports judgment-based cases that patterns cannot decide.
- This skill cleans the changed comments. Do not report the same finding again when a hook or code review already reported it; either clean it or explain why it is outside this skill's scope.
## Steps
1. Define the scope: inspect the current diff and list only added or modified comment lines. Include untouched legacy comments only when the user explicitly requested that. Completion condition: the cleanup scope is listed by file, or the run ends with the literal 「無發現」.
2. Compare each scoped comment with `references/comment-scope.md`. Remove process-only details and keep the real reason for the code. If a whole comment is only process detail and no real reason remains, delete the whole comment. Completion condition: every scoped comment is either unchanged with a reason, rewritten, or deleted.
3. Re-read the changed area after every rewrite. Confirm the sentence is complete, the logic still reads naturally, and no dangling fragment remains after deletion. Completion condition: every touched comment reads as a complete explanation or is gone.
4. Change comments and documentation strings only. Do not change executable behavior, identifiers, control flow, data shape, or tests except when a test fixture literally asserts the old comment text. Completion condition: `git diff` shows comment-only or documentation-string-only edits.
5. Run the smallest relevant build or test command for the changed project. If no project command is available, run syntax checks for touched scripts and report the gap. Completion condition: verification passed, or the exact missing command is reported.
6. Report the cleanup by category, not by full diff. Completion condition: the report names which categories were removed, which files were touched, and whether verification passed.