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

2026-08-27T07:42:06Z

jiantw83 commented

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

摘要

需求描述：使用者提出的 15 條工作規則中，第二群「產出物文件品質」的 R5——支援 Swagger 的專案要補全控制器文件（所有可能出現的 HTTP 狀態碼都宣告回覆類型，輸入輸出參數都要有說明與真實資料範例，參數是資料模型時每個屬性都套用、模型內含模型就遞迴）。規則正文與稽核技能落在 jsc-review；本存取庫負責把這關接進實作階段的完成條件，讓工作包在 API 文件沒補齊前不算做完。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`skills/implement/SKILL.md`	第 10 步原本只呼叫 `jsc-review:code-review`，改寫成兩關並列的收尾稽核：10.1 程式碼審查、10.2 API 文件稽核（跑 `swagger-detect.sh`，退出碼 0 呼叫 `jsc-review:api-doc`、1 明確跳過算通過、2 修好重跑）。description 同步改寫
`README.md`	README 是使用者查技能做什麼的入口。implement 摘要與相關 domain 一節同步改成兩關
`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`	收尾多一關是使用者看得到的流程異動，次版號跟著進到 0.2.0

設計重點

落點是問過使用者才定的，決策紀錄在 wiki knowledges/QUESTION 的 QUESTION_FB8DF0B5（2026-08-27 第二節 Q1 到 Q6）：同一批就把 api-doc 接進 jsc-sdlc:implement 的完成條件。
兩關並列，不是一關套一關：程式碼審查過了不代表 API 文件補齊了，反過來也一樣，任何一關沒過工作包都不算完成。
支不支援 Swagger 由程式判定：跑 jsc-review/tools/swagger-detect.sh 讀退出碼分支，不由 agent 自己看程式碼判斷，同一個專案每次跑的結論才會一致。
跳過要明講：退出碼 1 就明確回報跳過，跳過算通過；沒回報的跳過跟忘記做分不出來。退出碼 2 是偵測不出結果，既不算通過也不算跳過，修好參數或路徑重跑。
失敗是修，不是放行：兩關的每一輪修正都以 sub agent 在同一個 worktree 內進行，修完再稽核一次。
稽核項目不抄一份過來：只寫「看 jsc-review:api-doc」，判準改動時不必兩邊同步。
刻意不動頂層編號：改寫只動第 10 步內部，用 10.1、10.2 子項編號，1 到 14 的頂層編號一個都不動，避免打斷其他檔案指向步驟的指標。

測試結果

步驟指標逐一 grep 驗證：頂層編號 1 到 14 連續、無重複；references/deliver-formats.md 指的「步驟 7」、references/branch.md 指的「步驟 4 與步驟 11」都還指得到正確位置。
ste100-lint.sh 對本存取庫全綠，三份 manifest 版本一致（0.2.0）。
被依賴的 swagger-detect.sh 在 jsc-review 那支 PR 已完成實測：sh -n 通過；dotnet、nodejs、python 三種技術棧各測「套件加掛接」與「只有套件沒掛接」，前者結束碼 0、後者結束碼 1；另測 fastify、drf-spectacular、什麼套件都沒有、參數過多與路徑不存在（皆為結束碼 2）。本存取庫只讀它的退出碼，不重複測腳本本身。

前置 Push Request

plugins/review#10 plugins/review#10：本 PR 的第 10.2 步依賴 jsc-review 的 tools/swagger-detect.sh 與 jsc-review:api-doc 技能，那支 PR 未合併前，這裡指到的腳本與技能都還不存在。

## 摘要 - 需求描述：使用者提出的 15 條工作規則中，第二群「產出物文件品質」的 R5——支援 Swagger 的專案要補全控制器文件（所有可能出現的 HTTP 狀態碼都宣告回覆類型，輸入輸出參數都要有說明與真實資料範例，參數是資料模型時每個屬性都套用、模型內含模型就遞迴）。規則正文與稽核技能落在 `jsc-review`；本存取庫負責把這關接進實作階段的完成條件，讓工作包在 API 文件沒補齊前不算做完。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/implement/SKILL.md` | 第 10 步原本只呼叫 `jsc-review:code-review`，改寫成兩關並列的收尾稽核：10.1 程式碼審查、10.2 API 文件稽核（跑 `swagger-detect.sh`，退出碼 0 呼叫 `jsc-review:api-doc`、1 明確跳過算通過、2 修好重跑）。description 同步改寫 | | `README.md` | README 是使用者查技能做什麼的入口。implement 摘要與相關 domain 一節同步改成兩關 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 收尾多一關是使用者看得到的流程異動，次版號跟著進到 0.2.0 | ## 設計重點 - **落點是問過使用者才定的**，決策紀錄在 wiki `knowledges/QUESTION` 的 `QUESTION_FB8DF0B5`（2026-08-27 第二節 Q1 到 Q6）：同一批就把 api-doc 接進 `jsc-sdlc:implement` 的完成條件。 - **兩關並列，不是一關套一關**：程式碼審查過了不代表 API 文件補齊了，反過來也一樣，任何一關沒過工作包都不算完成。 - **支不支援 Swagger 由程式判定**：跑 `jsc-review/tools/swagger-detect.sh` 讀退出碼分支，不由 agent 自己看程式碼判斷，同一個專案每次跑的結論才會一致。 - **跳過要明講**：退出碼 1 就明確回報跳過，跳過算通過；沒回報的跳過跟忘記做分不出來。退出碼 2 是偵測不出結果，既不算通過也不算跳過，修好參數或路徑重跑。 - **失敗是修，不是放行**：兩關的每一輪修正都以 sub agent 在同一個 worktree 內進行，修完再稽核一次。 - **稽核項目不抄一份過來**：只寫「看 `jsc-review:api-doc`」，判準改動時不必兩邊同步。 - **刻意不動頂層編號**：改寫只動第 10 步內部，用 10.1、10.2 子項編號，1 到 14 的頂層編號一個都不動，避免打斷其他檔案指向步驟的指標。 ## 測試結果 - 步驟指標逐一 grep 驗證：頂層編號 1 到 14 連續、無重複；`references/deliver-formats.md` 指的「步驟 7」、`references/branch.md` 指的「步驟 4 與步驟 11」都還指得到正確位置。 - `ste100-lint.sh` 對本存取庫全綠，三份 manifest 版本一致（0.2.0）。 - 被依賴的 `swagger-detect.sh` 在 `jsc-review` 那支 PR 已完成實測：`sh -n` 通過；dotnet、nodejs、python 三種技術棧各測「套件加掛接」與「只有套件沒掛接」，前者結束碼 0、後者結束碼 1；另測 fastify、drf-spectacular、什麼套件都沒有、參數過多與路徑不存在（皆為結束碼 2）。本存取庫只讀它的退出碼，不重複測腳本本身。 ## 前置 Push Request - plugins/review#10 https://gitea.jsc.idv.tw/plugins/review/pulls/10：本 PR 的第 10.2 步依賴 `jsc-review` 的 `tools/swagger-detect.sh` 與 `jsc-review:api-doc` 技能，那支 PR 未合併前，這裡指到的腳本與技能都還不存在。

jiantw83 added 3 commits 2026-08-27 07:42:06 +00:00

feat(implement): 收尾改成程式碼審查與 API 文件稽核兩關並列 9b48d16422

What：skills/implement/SKILL.md 第 10 步改寫。原本只呼叫 code-review，現在拆成
並列的兩關：10.1 程式碼審查維持原判準，10.2 新增 API 文件稽核——先跑
jsc-review/tools/swagger-detect.sh，退出碼 0 就呼叫 jsc-review:api-doc，1 就
明確跳過並回報，2 就修好參數或路徑重跑。技能的 description 同步改寫。

Why：支援 Swagger 的專案，控制器文件沒補全就等於工作包沒做完。兩關並列而不是
一關套一關，是因為程式碼審查過了不代表 API 文件補齊了，反過來也一樣，任何一關
沒過工作包都不算完成。跳過一定要講出來：沒回報的跳過跟忘記做分不出來。退出碼
2 是偵測不出結果，既不算通過也不算跳過，硬當跳過會讓真的支援 Swagger 的專案
漏掉稽核。

How：改寫刻意只動第 10 步內部，用 10.1、10.2 子項編號，1 到 14 的頂層編號一個
都不動——references/deliver-formats.md 指的「步驟 7」、references/branch.md 指的
「步驟 4 與步驟 11」都還指得到原來的位置。稽核項目不抄一份過來，只寫「看
jsc-review:api-doc」，判準改動時不必兩邊同步。兩關的失敗都是修，不是放行：每一
輪修正都以 sub agent 在同一個 worktree 內進行，修完再稽核一次。

Who：jsc-sdlc 的 implement 技能，工作包的收尾稽核。

docs(sdlc): README 同步兩關收尾稽核與 jsc-review 的分工 981cda6adf

What：README.md 的 implement 摘要，把原本一句「程式碼審查」換成兩關並列的收尾
稽核，寫明偵測、呼叫、跳過三條路徑與各自的退出碼；相關 domain 一節的 jsc-review
說明同步改成兩關，並註明專案支不支援 Swagger 由 swagger-detect.sh 判定、稽核
項目只寫在該技能。

Why：README 是使用者查一支技能做什麼的入口。技能正文改了流程，README 還停在
只有程式碼審查那版，讀的人會以為 API 文件稽核不存在，或以為那是另一支技能自己
的事。

How：只改 implement 摘要那一段的收尾環節，以及相關 domain 的那一行，其餘流程
敘述維持原樣。稽核項目在這裡一樣不重複列，指向 jsc-review:api-doc，避免同一份
判準散在三個檔案裡。

Who：jsc-sdlc 的存取庫說明文件。

chore(manifest): 三份 manifest 同步升版至 0.2.0 39c087b31f

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

Why：implement 的收尾多了一關 API 文件稽核，是使用者看得到的流程異動，次版號
要跟著進。版本沒跟著升，各 CLI 端的外掛版本護欄就分不出新舊，已安裝的使用者
也收不到更新。

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

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

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

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

admin merged commit ac3c4e3aa2 into feat/api-doc-audit/main

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

admin deleted branch feat/api-doc-audit/implement-api-doc-gate

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

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Depends on

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

plugins/review

Reference: plugins/sdlc#32