feat/comment-scope-rule #26

2026-08-26T11:01:35Z

jiantw83 commented

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

摘要

需求描述：落地規則「程式碼註解禁止夾帶文件相關資訊」。註解只寫「為什麼這樣寫」，不寫「工作記在哪裡」。規則正文放在 jsc-review 的 references/comment-scope.md，本存放庫只放指引與完成條件，不重複清單。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`skills/implement/SKILL.md`	步驟 9 新增 9.3 註解界線規則與完成條件，原 9.3 順延為 9.4；步驟 10 交給 `code-review` 前先掃整包 diff。實作階段手上一直握著工作包編號、分析頁編號、待辦編號、分支名與 PR 編號，這些最容易被寫進註解。
`skills/maintain/SKILL.md`	步驟 3 新增 3.3 同一規則，原 3.3、3.4 順延為 3.4、3.5。維護階段常改到既有註解，議題編號、commit hash、分支名、人名與 `@` 提及容易順手留下。
`references/tdd.md`	循環規則新增第 4 項「註解只寫原因」，寫成單一待辦的完成條件，讓界線在紅綠循環當下就守住，不必等審查階段回頭清。
`README.md`	`implement` 與 `maintain` 兩段說明同步補上註解界線，避免對外說明與技能內容不一致。
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	行為變更，版本由 0.1.6 升到 0.1.7，三份保持同一版號，各 CLI 才知道要更新。

設計重點

規則正文只有一份。三處都指向 jsc-review 的 references/comment-scope.md，本存放庫不抄清單，日後改規則只改一個地方。
兩支技能各自只列自己那個階段真正握有的追蹤資訊：implement 列工作包編號、分析頁編號、待辦編號、分支名與 PR 編號；maintain 列議題編號、commit hash、分支名、人名與 @ 提及。
界線寫成完成條件，不是建議。implement 綁在單一待辦的 diff 上，maintain 綁在單一專案的 diff 上，兩者都要求把 jsc-hooks/hooks/comment-scope.sh 印出的警告當場修掉。
檢查點放兩層：寫檔當下由 hook 即時警告，交給 code-review 前再掃一次整包 diff。
步驟編號採順延，不重新編號，既有引用不會被打亂。

測試結果

meta/tools/ste100-lint.sh 對 README.md 與 references/tdd.md 皆 exit 0。
兩支 SKILL.md 掃過非 ASCII 字元，只剩刻意保留的 wiki 狀態字面，沒有其他中文混入英文正文。
三處 frontmatter 的 description 未改動。
步驟編號順延後逐項核對，implement 與 maintain 都沒有重號或跳號。
本次未處理的既有問題：references/cpm-chart.md 第 14 行有一個簡體字「出现」。該檔這次沒有動到，留待後續處理。

前置 Push Request

無

## 摘要 - 需求描述：落地規則「程式碼註解禁止夾帶文件相關資訊」。註解只寫「為什麼這樣寫」，不寫「工作記在哪裡」。規則正文放在 `jsc-review` 的 `references/comment-scope.md`，本存放庫只放指引與完成條件，不重複清單。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/implement/SKILL.md` | 步驟 9 新增 9.3 註解界線規則與完成條件，原 9.3 順延為 9.4；步驟 10 交給 `code-review` 前先掃整包 diff。實作階段手上一直握著工作包編號、分析頁編號、待辦編號、分支名與 PR 編號，這些最容易被寫進註解。 | | `skills/maintain/SKILL.md` | 步驟 3 新增 3.3 同一規則，原 3.3、3.4 順延為 3.4、3.5。維護階段常改到既有註解，議題編號、commit hash、分支名、人名與 `@` 提及容易順手留下。 | | `references/tdd.md` | 循環規則新增第 4 項「註解只寫原因」，寫成單一待辦的完成條件，讓界線在紅綠循環當下就守住，不必等審查階段回頭清。 | | `README.md` | `implement` 與 `maintain` 兩段說明同步補上註解界線，避免對外說明與技能內容不一致。 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 行為變更，版本由 0.1.6 升到 0.1.7，三份保持同一版號，各 CLI 才知道要更新。 | ## 設計重點 - 規則正文只有一份。三處都指向 `jsc-review` 的 `references/comment-scope.md`，本存放庫不抄清單，日後改規則只改一個地方。 - 兩支技能各自只列自己那個階段真正握有的追蹤資訊：`implement` 列工作包編號、分析頁編號、待辦編號、分支名與 PR 編號；`maintain` 列議題編號、commit hash、分支名、人名與 `@` 提及。 - 界線寫成完成條件，不是建議。`implement` 綁在單一待辦的 diff 上，`maintain` 綁在單一專案的 diff 上，兩者都要求把 `jsc-hooks/hooks/comment-scope.sh` 印出的警告當場修掉。 - 檢查點放兩層：寫檔當下由 hook 即時警告，交給 `code-review` 前再掃一次整包 diff。 - 步驟編號採順延，不重新編號，既有引用不會被打亂。 ## 測試結果 - `meta/tools/ste100-lint.sh` 對 `README.md` 與 `references/tdd.md` 皆 exit 0。 - 兩支 `SKILL.md` 掃過非 ASCII 字元，只剩刻意保留的 wiki 狀態字面，沒有其他中文混入英文正文。 - 三處 frontmatter 的 `description` 未改動。 - 步驟編號順延後逐項核對，`implement` 與 `maintain` 都沒有重號或跳號。 - 本次未處理的既有問題：`references/cpm-chart.md` 第 14 行有一個簡體字「出现」。該檔這次沒有動到，留待後續處理。 ## 前置 Push Request - 無

jiantw83 added 5 commits 2026-08-26 11:01:35 +00:00

feat(implement): implement 步驟加上註解界線規則 cd95c22bd4

What：步驟 9 新增 9.3「註解只寫原因」，原 9.3 順延為 9.4；步驟 10 交給 code-review 前先掃整包 diff。
Why：實作階段手上一直握著工作包編號、分析頁編號、待辦編號、分支名與 PR 編號，這些追蹤資訊很容易被寫進程式碼註解，讓註解變成文件索引。
How：規則正文放在 jsc-review 的 references/comment-scope.md，本技能只寫指引與完成條件，不重複清單；並指向 jsc-hooks 的 comment-scope.sh 當寫檔後的即時警告。
Who：jsc-sdlc 的 implement 技能。

feat(maintain): maintain 步驟加上註解界線規則 e6e3e176ef

What：步驟 3 新增 3.3「註解只寫原因」，原 3.3、3.4 順延為 3.4、3.5。
Why：維護階段常改到既有註解，議題編號、commit hash、分支名、人名與 @ 提及很容易順手留在註解裡，讓註解變成追蹤記錄。
How：規則正文放在 jsc-review 的 references/comment-scope.md，本技能只寫指引與完成條件，不重複清單；並指向 jsc-hooks 的 comment-scope.sh 當寫檔後的即時警告。
Who：jsc-sdlc 的 maintain 技能。

feat(tdd): TDD 循環規則新增註解只寫原因 31ba3f490a

What：references/tdd.md 的循環規則新增第 4 項「註解只寫原因」，並寫成單一待辦的完成條件。
Why：註解界線要在紅綠循環當下就守住，不能等到審查階段才回頭清，否則追蹤編號早已散進整包 diff。
How：規則只寫一句界線加完成條件，完整清單與白名單指向 jsc-review 的 references/comment-scope.md。
Who：jsc-sdlc 的 TDD 參考文件，implement 與 maintain 兩支技能共用。

feat(readme): README 同步 implement 與 maintain 的註解界線 f503091655

What：README 的 implement 與 maintain 兩段說明各補一句註解界線，點出各自禁止寫進註解的追蹤資訊。
Why：README 是技能的對外說明，兩支技能已加規則，說明沒跟上就會讓使用者誤以為註解沒有限制。
How：兩段各補一句，內容與 SKILL.md 的指引一致，完整清單指向 jsc-review 的 references/comment-scope.md。
Who：jsc-sdlc 的 README 技能說明區塊。

feat(manifest): 三份 manifest 版本升到 0.1.7 868e4345e9

What：plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 的 version 由 0.1.6 改為 0.1.7。
Why：本次為 implement、maintain 與 TDD 參考文件新增註解界線規則，屬於行為變更，版本要跟著往上走，各 CLI 才知道要更新。
How：三份 manifest 只改 version 一個欄位，其餘內容不動，三份保持同一版號。
Who：jsc-sdlc 外掛的套件描述檔。

admin merged commit b37476277d into develop

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

admin deleted branch feat/comment-scope-rule

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/sdlc#26