plugins/sdlc
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Merged
admin merged 4 commits from feat/api-doc-audit/main into develop 2026-08-27 08:54:33 +00:00
Conversation 0 Commits 4 Files Changed 5
+14 -7
jiantw83 commented 2026-08-27 08:52:25 +00:00
Member
Copy Link
Copy Source

PR 描述

摘要

  • 需求描述：使用者提出的 15 條工作規則中，群二（產出物文件品質）的 R5 要求 Swagger 控制器文件完整。稽核項目本身由 jsc-review:api-doc 實作，本存取庫負責的是「什麼時候跑」：implement 的第 10 步原本只有一關程式碼審查，現在改成程式碼審查與 API 文件稽核兩關並列，兩關都過工作包才算完成。決策紀錄在 wiki knowledges/QUESTION 的 QUESTION_FB8DF0B5（2026-08-27 兩節共 12 題）。本 PR 是主幹 feat/api-doc-audit/main 併回 develop 的釋出 PR，內容為已合併的子功能 PR #32。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

變更內容

檔案 為什麼改
skills/implement/SKILL.md 第 10 步從單一關卡改成 10.1 程式碼審查、10.2 API 文件稽核兩關並列，並寫明 swagger-detect.sh 三個退出碼各自怎麼走。description 同步補上兩關並列與 Swagger 偵測閘門
README.md implement 那一節的流程敘述補上兩關收尾稽核；跨存取庫關係一節把 jsc-review 的角色從「程式碼審查」改成並列兩關，並註明稽核項目只寫在該技能
plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 三份 manifest 同步升版至 0.2.0

設計重點

  • 兩關並列，不是取代。 兩關檢查的是不同東西：程式碼審查看實作與註解，API 文件稽核看呼叫端拿不拿得到足夠的文件去接。步驟寫成 10.1 與 10.2 兩個並列子項，明講「兩關都過才算工作包完成，兩者不互相取代」，避免有人跑完一關就往下走。
  • 支不支援 Swagger 在程式層判定，不由技能自己看。 第 10.2 步先跑 jsc-review/tools/swagger-detect.sh {工作樹路徑}，再依退出碼分流：0 呼叫 jsc-review:api-doc、1 明確跳過並回報（回報過的跳過算通過）、2 是參數或路徑有錯，修完再跑一次。判不出來的偵測既不算通過也不算跳過，這一條特別寫出來，因為「腳本壞了就當跳過」是最容易發生的鬆手。
  • 稽核項目不在這裡抄一份。 第 10.2 步只寫呼叫誰與怎麼分流，稽核什麼一律指向 jsc-review:api-doc。抄一份就會有兩套標準，改了 review 那邊忘了這邊，實作階段就開始照舊標準驗收。
  • 稽核不過就修，不能豁免。 每一輪修正都必須以 sub agent 在同一個工作樹內進行，修完再稽核一次，直到通過。完成條件寫成兩種可檢核狀態：api-doc 回傳通過，或是回報跳過並附上造成跳過的退出碼。
  • 完成條件是「跑過並回報退出碼」，不是「看起來沒問題」。 這符合本批同時加進 jsc-meta 稽核清單的流程檢查第 2 項與第 3 項：每個步驟以可檢核的完成條件結尾，每個外部呼叫的退出碼都有分流。

測試結果

  • tools/ste100-lint.sh 掃本存取庫全綠。
  • 三份 manifest（plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json）版本一致，皆為 0.2.0。
  • jsc-review/tools/swagger-detect.sh 的三種技術棧、兩種情境共六筆判定已在 review 那批實測過（「套件加掛接」回 0、「只有套件沒掛接」回 1），本步驟依賴的就是這三個退出碼。
  • 未測試項目：真實 Gitea 專案上的端到端 API 文件稽核沒跑過，也就是說「第 10.2 步在一個真的有控制器的專案上跑完整輪並收斂」這件事還沒有實測證據。本批只驗到偵測與分流這一層。

前置 Push Request

  • 無未結清的前置 PR。本存取庫的 implement 第 10.2 步依賴 jsc-review 的 tools/swagger-detect.sh 與 jsc-review:api-doc，那兩項已隨子功能 PR plugins/review#10 合併進 review 的主幹 feat/api-doc-audit/main，跨存取庫依賴在主幹層已結清。合併順序上仍建議 review 的釋出 PR 先進 develop，本 PR 再進，讓 develop 上任何一刻都不會出現「呼叫得到步驟、找不到腳本」的狀態。
# PR 描述 ## 摘要 - 需求描述：使用者提出的 15 條工作規則中，群二（產出物文件品質）的 R5 要求 Swagger 控制器文件完整。稽核項目本身由 `jsc-review:api-doc` 實作，本存取庫負責的是「什麼時候跑」：`implement` 的第 10 步原本只有一關程式碼審查，現在改成程式碼審查與 API 文件稽核兩關並列，兩關都過工作包才算完成。決策紀錄在 wiki `knowledges/QUESTION` 的 `QUESTION_FB8DF0B5`（2026-08-27 兩節共 12 題）。本 PR 是主幹 `feat/api-doc-audit/main` 併回 `develop` 的釋出 PR，內容為已合併的子功能 PR #32。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `skills/implement/SKILL.md` | 第 10 步從單一關卡改成 10.1 程式碼審查、10.2 API 文件稽核兩關並列，並寫明 `swagger-detect.sh` 三個退出碼各自怎麼走。description 同步補上兩關並列與 Swagger 偵測閘門 | | `README.md` | `implement` 那一節的流程敘述補上兩關收尾稽核；跨存取庫關係一節把 `jsc-review` 的角色從「程式碼審查」改成並列兩關，並註明稽核項目只寫在該技能 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 三份 manifest 同步升版至 0.2.0 | ## 設計重點 - **兩關並列，不是取代。** 兩關檢查的是不同東西：程式碼審查看實作與註解，API 文件稽核看呼叫端拿不拿得到足夠的文件去接。步驟寫成 10.1 與 10.2 兩個並列子項，明講「兩關都過才算工作包完成，兩者不互相取代」，避免有人跑完一關就往下走。 - **支不支援 Swagger 在程式層判定，不由技能自己看。** 第 10.2 步先跑 `jsc-review/tools/swagger-detect.sh {工作樹路徑}`，再依退出碼分流：`0` 呼叫 `jsc-review:api-doc`、`1` 明確跳過並回報（回報過的跳過算通過）、`2` 是參數或路徑有錯，修完再跑一次。判不出來的偵測既不算通過也不算跳過，這一條特別寫出來，因為「腳本壞了就當跳過」是最容易發生的鬆手。 - **稽核項目不在這裡抄一份。** 第 10.2 步只寫呼叫誰與怎麼分流，稽核什麼一律指向 `jsc-review:api-doc`。抄一份就會有兩套標準，改了 review 那邊忘了這邊，實作階段就開始照舊標準驗收。 - **稽核不過就修，不能豁免。** 每一輪修正都必須以 sub agent 在同一個工作樹內進行，修完再稽核一次，直到通過。完成條件寫成兩種可檢核狀態：`api-doc` 回傳通過，或是回報跳過並附上造成跳過的退出碼。 - **完成條件是「跑過並回報退出碼」，不是「看起來沒問題」。** 這符合本批同時加進 `jsc-meta` 稽核清單的流程檢查第 2 項與第 3 項：每個步驟以可檢核的完成條件結尾，每個外部呼叫的退出碼都有分流。 ## 測試結果 - `tools/ste100-lint.sh` 掃本存取庫全綠。 - 三份 manifest（`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`）版本一致，皆為 0.2.0。 - `jsc-review/tools/swagger-detect.sh` 的三種技術棧、兩種情境共六筆判定已在 review 那批實測過（「套件加掛接」回 `0`、「只有套件沒掛接」回 `1`），本步驟依賴的就是這三個退出碼。 - 未測試項目：真實 Gitea 專案上的端到端 API 文件稽核沒跑過，也就是說「第 10.2 步在一個真的有控制器的專案上跑完整輪並收斂」這件事還沒有實測證據。本批只驗到偵測與分流這一層。 ## 前置 Push Request - 無未結清的前置 PR。本存取庫的 `implement` 第 10.2 步依賴 `jsc-review` 的 `tools/swagger-detect.sh` 與 `jsc-review:api-doc`，那兩項已隨子功能 PR `plugins/review#10` 合併進 review 的主幹 `feat/api-doc-audit/main`，跨存取庫依賴在主幹層已結清。合併順序上仍建議 review 的釋出 PR 先進 `develop`，本 PR 再進，讓 `develop` 上任何一刻都不會出現「呼叫得到步驟、找不到腳本」的狀態。
jiantw83 added 4 commits 2026-08-27 08:52:26 +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 外掛的安裝與更新流程。
Merge pull request 'feat(sdlc): implement 收尾新增 API 文件稽核，與程式碼審查並列' (#32) from feat/api-doc-audit/implement-api-doc-gate into feat/api-doc-audit/main ac3c4e3aa2 
Reviewed-on: #32
admin merged commit 7d8a8d527d into develop 2026-08-27 08:54:33 +00:00
admin deleted branch feat/api-doc-audit/main 2026-08-27 08:54:33 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: plugins/sdlc#33