 admin
|
5a2d5d1bab
|
Merge pull request 'feat(review): 新增 API 文件稽核技能，第 5 組擴充註解的條列、導向與標示規則' (#11) from feat/api-doc-audit/main into develop
Reviewed-on: #11
|
2026-08-27 08:54:28 +00:00 |
|
|
admin
|
8eb330a62f
|
Merge pull request 'feat(review): 新增 API 文件稽核技能，第 5 組擴充註解的條列、連結與標示規則' (#10) from feat/api-doc-audit/api-doc-and-comment-rules into feat/api-doc-audit/main
Reviewed-on: #10
Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
|
2026-08-27 07:45:15 +00:00 |
|
 jiantw83
|
8b5cc602dc
|
chore(manifest): 三份 manifest 同步升版至 0.0.6
What：plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份
manifest 的 version 由 0.0.5 改為 0.0.6。
Why：這批新增了 api-doc 技能與 swagger-detect.sh，也擴充了第 5 組的審查項目，
屬於功能異動。版本沒跟著升，各 CLI 端的外掛版本護欄就分不出新舊，已安裝的
使用者也收不到更新。
How：三份 manifest 只改 version 欄位，其餘欄位維持原樣，三處版本號保持一致。
Who：jsc-review 外掛的安裝與更新流程。
|
2026-08-27 15:41:38 +08:00 |
|
|
jiantw83
|
51c2705667
|
feat(review): code-review 範圍改為 5.1 到 5.8 並補上與 api-doc 的分工
What：skills/code-review/SKILL.md 的審查範圍表，第 5 組由原本一句
「smells.md group 5」改成明確的 5.1 到 5.8，並點名 5.6、5.7、5.8 三個新項目；
Notes 加一行分工，Swagger 文件稽核歸 api-doc。README.md 新增 api-doc 的技能
小節，另補一張工具表格列出 swagger-detect.sh。
Why：sub agent 讀的是 SKILL.md 的審查範圍表，範圍表沒寫清楚，新增的 5.6 到
5.8 就不會被查。使用者讀的是 README.md，新技能與新工具沒列出來就找不到。
兩支技能都碰註解與文件，界線不寫明就會對同一個缺失重複回報。
How：範圍表的第 5 組直接列出三個新項目與各自的判準重點，完整清單仍指向
references/smells.md。Notes 寫明 api-doc 負責狀態碼的回覆類型、Swagger 參數
說明與範例，第 5 組只負責原始碼註解契約。README.md 的技能小節寫明偵測先行、
只裝套件沒掛接就停手；工具表格列出 swagger-detect.sh 的用途、輸出欄位與結束碼。
Who：jsc-review 的 code-review 技能與存取庫說明文件。
|
2026-08-27 15:41:38 +08:00 |
|
|
jiantw83
|
dfaa66feda
|
feat(api-doc): 新增 API 文件稽核技能
What：新增 skills/api-doc/SKILL.md。六步流程：偵測 Swagger 支援、不支援就回報
並停手、列出稽核範圍、分三個面向各開一個 sub agent 稽核、彙整去重排序、回報
發現。三個面向分別是狀態碼的回覆類型、參數說明與範例、資料模型遞迴。本技能
只回報「檔案:行號」、嚴重度與建議修法，不改程式碼。
Why：支援 Swagger 的專案要把控制器文件補全：所有可能出現的狀態碼都宣告回覆
類型，輸入輸出都要有說明與真實資料範例，參數是資料模型就每個屬性都套用、內含
模型再往下遞迴。這是 code-review 六組沒碰過的領域，跟第 5 組的原始碼註解契約
也不是同一件事，所以獨立成一支技能，不塞進既有的六組裡。
How：第一步跑 tools/swagger-detect.sh，讀結束碼決定走下去還是停手，不支援時
一個 sub agent 都不開，直接回報未啟用。範例優先取專案的真實資料，資料庫、
種子資料、測試夾具都算；真的取不到才依邏輯推導，並在文件裡標上「推導值」，
讓後面讀的人知道這個值沒被觀察過。取自資料庫的範例一律去識別化，個人資料不
進 Swagger 文件。分工另立一節：本技能只管 Swagger 文件屬性，原始碼註解契約
歸 code-review 第 5 組，同一個缺失不會被回報兩次。
Who：jsc-review 新增的 api-doc 技能，由 jsc-sdlc 的 implement 收尾時呼叫。
|
2026-08-27 15:41:38 +08:00 |
|
|
jiantw83
|
57ac9cdcd9
|
feat(swagger-detect): 新增判斷專案有沒有啟用 Swagger 的工具
What：新增 tools/swagger-detect.sh，判斷一個專案有沒有真的啟用 Swagger 文件。
涵蓋 dotnet、nodejs、python 三種技術棧，輸出 support=、stack=、package=、
config= 四類欄位；結束碼 0 支援、1 不支援、2 參數個數不對或專案路徑不存在。
Why：API 文件稽核只對產得出 Swagger 文件的專案有意義。支不支援如果交給 agent
自己看程式碼判斷，同一個專案可能這次說支援、下次說不支援。判定寫成腳本，呼叫端
讀結束碼分支就好，不必自己猜。
How：雙重確認，套件與設定缺一不算支援。第一關在套件宣告檔裡找已知的 Swagger
套件，第二關在原始碼裡找真的把 Swagger 接上去的呼叫或裝飾子。設定關鍵字一律
挑接線動作，不挑 import 或 require——光是引入套件不代表文件真的掛上去了。裝了
套件卻沒啟用的專案很常見，只看套件會誤判，讓稽核跑在一個根本產不出文件的專案
上。輸出刻意做成一行一個 key=value，呼叫端逐行讀就好。
Who：jsc-review 的 api-doc 技能，以及 jsc-sdlc 實作階段的收尾稽核。
|
2026-08-27 15:41:38 +08:00 |
|
|
jiantw83
|
dbaf81005b
|
feat(smells): 第 5 組擴充條列式步驟、導向連結與標示語法
What：references/smells.md 第 5 組擴充。5.1 的方法描述後面要接條列式的處理步驟
與規則，5.3 的回傳值是自訂資料模型時要附上型別定義的導向連結；新增 5.6 內含
功能的導向連結、5.7 XML 註解標籤各占一行、5.8 註解裡的專有名詞與變數依語言
慣例標示。文末的嚴重度分級補上一張表，逐項標明這五個新項目的級別與理由。
Why：使用者提出的產出物文件品質規則裡，有三條講的都是原始碼註解要寫到什麼
程度。動手前先比對過既有內容，第 5 組已經涵蓋大部分，缺的是條列步驟、導向
連結與標示語法這三塊。另開一支技能會跟 code-review 的目標重疊，所以直接擴充
第 5 組。新項目多半屬於可讀性層級，混在原本「註解缺漏」一句話裡分不出輕重，
所以級別另外列。
How：5.1 與 5.3 在原有定義後面接上新要求，偵測訊號與建議重構手法同步補列，
原本的判準一個都不動。5.6 到 5.8 照既有小節的四段結構寫：定義、偵測訊號、
建議重構手法、注意事項。5.8 的標示語法用表格對照 XML 與 JSDoc、docstring
兩類格式。5.6 與 5.7 都寫明註解格式不支援時不適用，避免硬造連結字串，也避免
把 XML 的排版規則套到沒有結束標籤的格式上。
Who：jsc-review 的壞味道參考清單，第 5 組註解契約。
|
2026-08-27 15:41:38 +08:00 |
|