feat/comment-scope-rule #8

2026-08-26T11:01:20Z

jiantw83 commented

2026-08-26 11:01:20 +00:00

摘要

需求描述：新增規則「程式碼註解禁止夾帶文件相關資訊」。註解只寫「為什麼這樣寫」，不寫「這件事記在哪份文件」。編號會過期、會搬家、會落在存取權限外，讀程式碼的人查不到，最後只剩一串無意義的代號。本存取庫是規則正文的單一真實來源，jsc-hooks 的 comment-scope.sh 依本規則比對。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`references/comment-scope.md`	新檔，規則正文。列出適用範圍、禁止清單、白名單與命中時的改法，供技能與 hook 共用
`references/smells.md`	第 2 組新增 `2.5 文件編號夾帶`，並在嚴重度分級「低」列補上本項，讓新規則在壞味道清單裡有位置
`skills/code-review/SKILL.md`	第 2 組 Obscurity 的審查範圍納入 2.5，Notes 補上與 `comment-scope.sh` 的分工，sub agent 才會查這一項
`README.md`	技能說明與參考檔表格同步，使用者才找得到新的參考檔
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	功能異動，三份 manifest 同步由 0.0.4 升至 0.0.5

設計重點

適用範圍只限程式碼註解。docstring、API 文件註解、README、其他 markdown、commit 訊息與 PR 描述都不受限。
禁止清單三十項分四組：追蹤系統編號、jsc wiki 頁面編號、需求與規格編號、流程與人事資訊。
白名單七項：日期與時間戳、需求變更歷程、RFC 與 ISO 標準、CVE、第三方套件 issue 連結、授權標頭與 SPDX、語言原生標記。這些項目穩定、可自證，留在註解裡有用。
與 jsc-hooks 分工明確：comment-scope.sh 在寫檔後自動比對樣式判定得了的項目，code-review 第 2 組負責樣式判定不了的專案代號與客戶名稱，兩邊不重複回報同一筆。
與既有項目分工明確：2.4 刪解釋性廢話，第 5 組補介面契約，2.5 刪文件編號。
嚴重度定為「低」，歸在可讀性與一致性，不擋合併。

測試結果

meta/tools/ste100-lint.sh 對 README.md 與 references/ 執行，皆 exit 0。
四個異動檔案的 UTF-8 解碼皆通過。
skills/code-review/SKILL.md 的非 ASCII 字元只剩刻意保留的繁中字面：「無發現」與高、中、低。
frontmatter 的 description 未改動。

前置 Push Request

無

## 摘要 - 需求描述：新增規則「程式碼註解禁止夾帶文件相關資訊」。註解只寫「為什麼這樣寫」，不寫「這件事記在哪份文件」。編號會過期、會搬家、會落在存取權限外，讀程式碼的人查不到，最後只剩一串無意義的代號。本存取庫是規則正文的單一真實來源，`jsc-hooks` 的 `comment-scope.sh` 依本規則比對。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `references/comment-scope.md` | 新檔，規則正文。列出適用範圍、禁止清單、白名單與命中時的改法，供技能與 hook 共用 | | `references/smells.md` | 第 2 組新增 `2.5 文件編號夾帶`，並在嚴重度分級「低」列補上本項，讓新規則在壞味道清單裡有位置 | | `skills/code-review/SKILL.md` | 第 2 組 Obscurity 的審查範圍納入 2.5，Notes 補上與 `comment-scope.sh` 的分工，sub agent 才會查這一項 | | `README.md` | 技能說明與參考檔表格同步，使用者才找得到新的參考檔 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 功能異動，三份 manifest 同步由 0.0.4 升至 0.0.5 | ## 設計重點 - 適用範圍只限程式碼註解。docstring、API 文件註解、README、其他 markdown、commit 訊息與 PR 描述都不受限。 - 禁止清單三十項分四組：追蹤系統編號、jsc wiki 頁面編號、需求與規格編號、流程與人事資訊。 - 白名單七項：日期與時間戳、需求變更歷程、RFC 與 ISO 標準、CVE、第三方套件 issue 連結、授權標頭與 SPDX、語言原生標記。這些項目穩定、可自證，留在註解裡有用。 - 與 `jsc-hooks` 分工明確：`comment-scope.sh` 在寫檔後自動比對樣式判定得了的項目，`code-review` 第 2 組負責樣式判定不了的專案代號與客戶名稱，兩邊不重複回報同一筆。 - 與既有項目分工明確：2.4 刪解釋性廢話，第 5 組補介面契約，2.5 刪文件編號。 - 嚴重度定為「低」，歸在可讀性與一致性，不擋合併。 ## 測試結果 - `meta/tools/ste100-lint.sh` 對 `README.md` 與 `references/` 執行，皆 exit 0。 - 四個異動檔案的 UTF-8 解碼皆通過。 - `skills/code-review/SKILL.md` 的非 ASCII 字元只剩刻意保留的繁中字面：「無發現」與高、中、低。 - frontmatter 的 `description` 未改動。 ## 前置 Push Request - 無

jiantw83 added 3 commits 2026-08-26 11:01:20 +00:00

feat(review): 新增程式碼註解禁止夾帶文件資訊的規則正文 fd70ce3bc2

What：新增 references/comment-scope.md 規則正文，並在 references/smells.md
第 2 組加入 2.5 文件編號夾帶，嚴重度分級「低」列補上本項。

Why：註解寫「這件事記在哪份文件」，讀程式碼的人查不到。編號會過期、會搬家、
會落在存取權限外，最後只剩一串無意義的代號。註解該寫的是「為什麼這樣寫」。

How：規則正文限定適用範圍只到程式碼註解，docstring、README、commit 訊息不受限。
禁止清單三十項分四組：追蹤系統編號、jsc wiki 頁面編號、需求與規格編號、
流程與人事資訊。白名單七項：日期與時間戳、需求變更歷程、RFC 與 ISO 標準、CVE、
第三方套件 issue 連結、授權標頭與 SPDX、語言原生標記。

Who：jsc-review 的 code-review 技能，第 2 組可讀性審查。

feat(review): 技能與說明文件納入文件編號夾帶審查 df81eec8fb

What：skills/code-review/SKILL.md 的第 2 組 Obscurity 審查範圍納入 2.5，
Notes 補上與 jsc-hooks 的 comment-scope.sh 分工說明；README.md 的技能說明
與參考檔表格同步。

Why：規則正文放進 references 還不夠，sub agent 讀的是 SKILL.md 的審查範圍表。
範圍表沒寫，第 2 組就不會查這一項。使用者讀的是 README.md，參考檔沒列出來就找不到。

How：審查範圍表的第 2 組直接列出六類命中樣式，並指向 references/comment-scope.md
取完整清單。Notes 寫明 comment-scope.sh 負責樣式判定得了的項目，第 2 組負責
樣式判定不了的專案代號與客戶名稱，兩邊不重複回報。README.md 表格新增一列。

Who：jsc-review 的 code-review 技能與存取庫說明文件。

feat(review): 三份 manifest 同步升版至 0.0.5 0df99db512

What：plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json
三份 manifest 的 version 由 0.0.4 改為 0.0.5。

Why：本次新增了註解內容界線規則，屬於功能異動。版本沒跟著升，各 CLI 端的
外掛版本護欄就分不出新舊，已安裝的使用者也收不到更新。

How：三份 manifest 只改 version 欄位，其餘欄位維持原樣，三處版本號保持一致。

Who：jsc-review 外掛的安裝與更新流程。

admin merged commit 8b8f23a17b into develop

2026-08-27 00:56:41 +00:00

admin deleted branch feat/comment-scope-rule

2026-08-27 00:56:42 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/review#8