feat(comment-scope): 擴充審查流程痕跡規則
This commit is contained in:
@@ -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` | 程式碼註解內容界線：禁止寫進註解的文件編號、審查流程痕跡、允許項目與白名單、命中時的改法 |
|
||||
|
||||
## 工具
|
||||
|
||||
|
||||
@@ -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：避免空指標` | `// 輸入來自外部系統，空值要直接略過` |
|
||||
| `// 第二輪追加這個判斷` | `// 舊資料可能缺欄位，先補預設值再解析` |
|
||||
|
||||
原則一句話：把編號指向的內容**搬進註解**，再刪掉編號。搬不動就代表那件事不該用註解表達，改寫進文件。
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user