feat(review): 新增 API 文件稽核技能，第 5 組擴充註解的條列、連結與標示規則 #10

2026-08-27T07:41:51Z

jiantw83 commented

2026-08-27 07:41:51 +00:00

摘要

需求描述：使用者提出的 15 條工作規則分三群，本 PR 是第二群「產出物文件品質」的四條。R5：支援 Swagger 的專案要補全控制器文件，所有可能出現的 HTTP 狀態碼都宣告回覆類型，輸入輸出參數都要有說明與真實資料範例，取不到真實資料才用推導範例並標明，參數是資料模型時每個屬性都套用、模型內含模型就遞迴。R6：XML 註解的起始標籤與結束標籤各占一行。R7：服務與存取庫的功能註解要有目的與邏輯簡述、條列式步驟與規則、內含功能的連結與用途、輸入輸出參數說明（資料模型遞迴）、回傳值說明與資料模型檔案連結。R8：註解裡的專有名詞與變數要明顯標示。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`references/smells.md`	R6 到 R8 的規則正文。第 5 組擴充：5.1 加條列式步驟與規則、5.3 加回傳型別的導向連結、新增 5.6 內含功能的導向連結、5.7 XML 標籤排版、5.8 專有名詞與變數標示；嚴重度分級補一張表逐項標明新項目的級別
`skills/api-doc/SKILL.md`	R5 的落點。新技能，六步流程，三個檢查面向各開一個 sub agent，只回報不改程式碼
`tools/swagger-detect.sh`	專案支不支援 Swagger 要由程式判定，不能交給 agent 用看的。套件與掛接雙重確認，輸出 `support=`、`stack=`、`package=`、`config=`，結束碼 0 支援、1 不支援、2 參數或路徑錯
`skills/code-review/SKILL.md`	sub agent 讀的是審查範圍表。第 5 組範圍由一句話改成 5.1 到 5.8，Notes 加一行分工，Swagger 文件歸 api-doc
`README.md`	使用者查技能與工具的入口。新增 api-doc 技能小節與工具表格
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	功能異動要升版，版本沒動各 CLI 的外掛版本護欄就分不出新舊

設計重點

落點是問過使用者才定的，決策紀錄在 wiki knowledges/QUESTION 的 QUESTION_FB8DF0B5（2026-08-27 第二節 Q1 到 Q6）。
R6 到 R8 擴充第 5 組，不新建技能：動手前先比對，code-review 的 references/smells.md 第 5 組已涵蓋 R7 大部分，另開技能會跟 code-review 的目標重疊。
R5 獨立成 jsc-review:api-doc：Swagger 文件屬性是六組沒碰過的領域，跟第 5 組的原始碼註解契約不是同一件事。
兩支技能的分工寫在雙方文件裡：api-doc 只管 Swagger 文件屬性，原始碼註解契約歸 code-review 第 5 組，同一個缺失不會被回報兩次。
Swagger 偵測採套件與設定雙重確認：只裝套件沒掛接不算支援。裝了沒啟用的專案很常見，只看套件會讓稽核跑在一個根本產不出文件的專案上。
R8 的判準依語言慣例：XML 用 <paramref>、<see cref>、<c>，JSDoc 與 docstring 用反引號；註解格式不支援導向就只寫用途，不硬造連結字串。
api-doc 的範圍是控制器加遞迴資料模型：從控制器走進去，沿著輸入與輸出型別往內層走到底。
範例優先取真實資料：資料庫、種子資料、測試夾具都算，取不到才依邏輯推導並標「推導值」。取自資料庫的範例一律去識別化，個人資料不進 Swagger 文件。

測試結果

sh -n tools/swagger-detect.sh 語法檢查通過。
swagger-detect.sh 對 dotnet、nodejs、python 三種技術棧各測「套件加掛接」與「只有套件沒掛接」兩種情境：前者 support=yes、結束碼 0，後者 support=no、結束碼 1。另測 fastify、drf-spectacular、什麼套件都沒有、參數過多（結束碼 2）、路徑不存在（結束碼 2），結果都符合預期。dotnet 的三種情境另由主 agent 獨立複驗一次，結果一致。
ste100-lint.sh 對本存取庫全綠，三份 manifest 版本一致（0.0.6）。

前置 Push Request

無

## 摘要 - 需求描述：使用者提出的 15 條工作規則分三群，本 PR 是第二群「產出物文件品質」的四條。R5：支援 Swagger 的專案要補全控制器文件，所有可能出現的 HTTP 狀態碼都宣告回覆類型，輸入輸出參數都要有說明與真實資料範例，取不到真實資料才用推導範例並標明，參數是資料模型時每個屬性都套用、模型內含模型就遞迴。R6：XML 註解的起始標籤與結束標籤各占一行。R7：服務與存取庫的功能註解要有目的與邏輯簡述、條列式步驟與規則、內含功能的連結與用途、輸入輸出參數說明（資料模型遞迴）、回傳值說明與資料模型檔案連結。R8：註解裡的專有名詞與變數要明顯標示。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `references/smells.md` | R6 到 R8 的規則正文。第 5 組擴充：5.1 加條列式步驟與規則、5.3 加回傳型別的導向連結、新增 5.6 內含功能的導向連結、5.7 XML 標籤排版、5.8 專有名詞與變數標示；嚴重度分級補一張表逐項標明新項目的級別 | | `skills/api-doc/SKILL.md` | R5 的落點。新技能，六步流程，三個檢查面向各開一個 sub agent，只回報不改程式碼 | | `tools/swagger-detect.sh` | 專案支不支援 Swagger 要由程式判定，不能交給 agent 用看的。套件與掛接雙重確認，輸出 `support=`、`stack=`、`package=`、`config=`，結束碼 0 支援、1 不支援、2 參數或路徑錯 | | `skills/code-review/SKILL.md` | sub agent 讀的是審查範圍表。第 5 組範圍由一句話改成 5.1 到 5.8，Notes 加一行分工，Swagger 文件歸 api-doc | | `README.md` | 使用者查技能與工具的入口。新增 api-doc 技能小節與工具表格 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 功能異動要升版，版本沒動各 CLI 的外掛版本護欄就分不出新舊 | ## 設計重點 - **落點是問過使用者才定的**，決策紀錄在 wiki `knowledges/QUESTION` 的 `QUESTION_FB8DF0B5`（2026-08-27 第二節 Q1 到 Q6）。 - **R6 到 R8 擴充第 5 組，不新建技能**：動手前先比對，`code-review` 的 `references/smells.md` 第 5 組已涵蓋 R7 大部分，另開技能會跟 `code-review` 的目標重疊。 - **R5 獨立成 `jsc-review:api-doc`**：Swagger 文件屬性是六組沒碰過的領域，跟第 5 組的原始碼註解契約不是同一件事。 - **兩支技能的分工寫在雙方文件裡**：api-doc 只管 Swagger 文件屬性，原始碼註解契約歸 code-review 第 5 組，同一個缺失不會被回報兩次。 - **Swagger 偵測採套件與設定雙重確認**：只裝套件沒掛接不算支援。裝了沒啟用的專案很常見，只看套件會讓稽核跑在一個根本產不出文件的專案上。 - **R8 的判準依語言慣例**：XML 用 `<paramref>`、`<see cref>`、`<c>`，JSDoc 與 docstring 用反引號；註解格式不支援導向就只寫用途，不硬造連結字串。 - **api-doc 的範圍是控制器加遞迴資料模型**：從控制器走進去，沿著輸入與輸出型別往內層走到底。 - **範例優先取真實資料**：資料庫、種子資料、測試夾具都算，取不到才依邏輯推導並標「推導值」。取自資料庫的範例一律去識別化，個人資料不進 Swagger 文件。 ## 測試結果 - `sh -n tools/swagger-detect.sh` 語法檢查通過。 - `swagger-detect.sh` 對 dotnet、nodejs、python 三種技術棧各測「套件加掛接」與「只有套件沒掛接」兩種情境：前者 `support=yes`、結束碼 0，後者 `support=no`、結束碼 1。另測 fastify、drf-spectacular、什麼套件都沒有、參數過多（結束碼 2）、路徑不存在（結束碼 2），結果都符合預期。dotnet 的三種情境另由主 agent 獨立複驗一次，結果一致。 - `ste100-lint.sh` 對本存取庫全綠，三份 manifest 版本一致（0.0.6）。 ## 前置 Push Request - 無

jiantw83 added 5 commits 2026-08-27 07:41:52 +00:00

feat(smells): 第 5 組擴充條列式步驟、導向連結與標示語法 dbaf81005b

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 組註解契約。

feat(swagger-detect): 新增判斷專案有沒有啟用 Swagger 的工具 57ac9cdcd9

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 實作階段的收尾稽核。

feat(api-doc): 新增 API 文件稽核技能 dfaa66feda

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 收尾時呼叫。

feat(review): code-review 範圍改為 5.1 到 5.8 並補上與 api-doc 的分工 51c2705667

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 技能與存取庫說明文件。

chore(manifest): 三份 manifest 同步升版至 0.0.6 8b5cc602dc

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 外掛的安裝與更新流程。

jiantw83 referenced this pull request from plugins/sdlc

2026-08-27 07:42:06 +00:00

feat(sdlc): implement 收尾新增 API 文件稽核，與程式碼審查並列 #32

jiantw83 added a new dependency 2026-08-27 07:42:20 +00:00

plugins/sdlc#32 - feat(sdlc): implement 收尾新增 API 文件稽核，與程式碼審查並列

admin approved these changes 2026-08-27 07:45:11 +00:00

admin merged commit 8eb330a62f into feat/api-doc-audit/main

2026-08-27 07:45:16 +00:00

admin deleted branch feat/api-doc-audit/api-doc-and-comment-rules

2026-08-27 07:45:16 +00:00

jiantw83 referenced this pull request

2026-08-27 08:52:25 +00:00