From aaa0227464d4cf6cd331f3286ebf30db7ef7f73c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 28 Aug 2026 09:30:33 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(comment-scope):=20=E6=93=B4=E5=85=85?= =?UTF-8?q?=E5=AF=A9=E6=9F=A5=E6=B5=81=E7=A8=8B=E7=97=95=E8=B7=A1=E8=A6=8F?= =?UTF-8?q?=E5=89=87?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 8 ++++++-- references/comment-scope.md | 14 ++++++++++++++ skills/code-review/SKILL.md | 4 ++-- 3 files changed, 22 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 4cf69ab..9c7e625 100644 --- a/README.md +++ b/README.md @@ -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 組負責指出人工判讀案例。未明確要求時不動未變更的舊註解。 + ## 參考 @@ -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` | 程式碼註解內容界線：禁止寫進註解的文件編號、審查流程痕跡、允許項目與白名單、命中時的改法 | ## 工具 diff --git a/references/comment-scope.md b/references/comment-scope.md index 1b3a0b5..75fec02 100644 --- a/references/comment-scope.md +++ b/references/comment-scope.md @@ -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：避免空指標` | `// 輸入來自外部系統，空值要直接略過` | +| `// 第二輪追加這個判斷` | `// 舊資料可能缺欄位，先補預設值再解析` | 原則一句話：把編號指向的內容**搬進註解**，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。 diff --git a/skills/code-review/SKILL.md b/skills/code-review/SKILL.md index fdb9cff..748212a 100644 --- a/skills/code-review/SKILL.md +++ b/skills/code-review/SKILL.md @@ -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 (``, ``, `` 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. -- 2.53.0 From b3d83370019acbf9d8cffef9780e8041a456f17c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 28 Aug 2026 09:30:37 +0800 Subject: [PATCH 2/2] =?UTF-8?q?feat(comment-cleanup):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E8=A8=BB=E8=A7=A3=E6=B8=85=E7=90=86=E6=8A=80=E8=83=BD?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- skills/comment-cleanup/SKILL.md | 33 +++++++++++++++++++++++++++++++++ 4 files changed, 36 insertions(+), 3 deletions(-) create mode 100644 skills/comment-cleanup/SKILL.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 9d93fdf..2f669f1 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.0.6", + "version": "0.0.8", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index e7b88cd..8a20ebb 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.0.6", + "version": "0.0.8", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills" } diff --git a/plugin.json b/plugin.json index 8bfae14..c33b90e 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-review", - "version": "0.0.6", + "version": "0.0.8", "description": "程式碼審查：Refactoring 壞味道六組 + 註解規範 + 淺模組", "skills": "./skills/" } diff --git a/skills/comment-cleanup/SKILL.md b/skills/comment-cleanup/SKILL.md new file mode 100644 index 0000000..96239d2 --- /dev/null +++ b/skills/comment-cleanup/SKILL.md @@ -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. -- 2.53.0