jiantw83
d4fea890c7
What： 在既有的 `references/` 目錄新增 `behaviors.md`。 文件分 api-doc、code-review、comment-cleanup 三節。 每節一張五列表：觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象。 Why： 技能驗證缺一份共同的比對基準。 以前只能重讀技能本文推敲行為，判斷因人而異。 清單放在本 repo，技能改動與清單就落在同一個 PR，不會漂移。 也不用為了一次改動跨 repo 開兩條 PR 互卡。 How： 逐支技能盤點行為，再把結果填進五列表。 稽核時修正 comment-cleanup 的外部呼叫敘述。 原本寫成 write-guard.sh 條件式涵蓋這支技能。 實際上那支腳本一律豁免它，而且這支技能根本不呼叫它，已據實改寫。 格式交由 `meta/tools/check-behaviors.sh` 在程式層檢查。 Who： jsc-review 技能的維護者。 執行技能驗證的人。 日後異動這三支技能的人，都要同步更新這一頁。
34 lines
7.1 KiB
Markdown
34 lines
7.1 KiB
Markdown
# jsc-review 技能行為清單
|
||
|
||
本頁記錄 jsc-review 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
|
||
|
||
## api-doc
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 觸發時機 | 控制器改完之後叫用，或工作包實作完成之後叫用。`jsc-sdlc:implement` 在收尾時與 `jsc-review:code-review` 並排叫用它。專案沒有啟用 Swagger 就不跑，這一點由步驟 1 的腳本判定，不由人判斷。原始碼註解合約歸 `jsc-review:code-review` 第 5 組，這支技能只看 Swagger 文件屬性。資安、邏輯錯誤、測試涵蓋率歸 CLI 內建審查。 |
|
||
| 關鍵步驟 | 跑 `tools/swagger-detect.sh` 偵測 Swagger 套件與掛載，讀退出碼 0、1、2 分流、退出碼 1 回報「本專案未啟用 Swagger 文件，略過 API 文件稽核」並停止、退出碼 2 照三種原因回報並停止、列出稽核範圍（全專案控制器，或 `git diff` 指定的變更控制器）、`git diff` 失敗就原文回報 git 的 stderr 並停止、開兩個 sub agent 平行稽核兩個面向（面向 1 狀態碼與回應型別宣告、面向 2 描述與範例並遞迴走訪資料模型）、每個面向回傳六欄 TSV 或「無發現」、把兩個面向的 TSV 依序餵給 `tools/merge-findings.sh` 合併、依退出碼 0、1、2、3 分流、繁體中文逐列回報、跑 `jsc-hooks/hooks/write-guard.sh release` 解鎖。 |
|
||
| 外部呼叫 | `tools/swagger-detect.sh`、`tools/merge-findings.sh`、`jsc-hooks/hooks/write-guard.sh`（`review` 模式擋寫入工具、`release` 模式解鎖）、`git diff`、`references/smells.md` 的嚴重度分級、2 個稽核 sub agent。沒有 Gitea API 呼叫。 |
|
||
| 完成條件 | 偵測結果、範圍清單、兩個面向的回傳、合併結果四段都有結論。合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以腳本錯誤收尾。報告交給呼叫方，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路，修不修由呼叫方決定。 |
|
||
| 可驗證跡象 | 不改任何程式碼。唯一的環境寫入是解鎖：`$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可以直接檢查該檔是否還在。舊版 `jsc-hooks` 不認得 `release`，該檔會留到逾時，這也是可檢查的狀態。除此之外沒有寫入跡象，只有回報內容。 |
|
||
|
||
## code-review
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 觸發時機 | 一個檔案或一組相關檔案改完之後叫用，或工作包的所有待辦做完之後叫用。`jsc-sdlc:implement` 在工作包最後一項待辦之後、提交與開 PR 之前叫用它。資安、邏輯錯誤、測試涵蓋率不在範圍內，那些歸 CLI 內建審查。Swagger 文件稽核歸 `jsc-review:api-doc`，兩支技能不重複回報同一個缺口。 |
|
||
| 關鍵步驟 | 用一道指令把 `git diff`（未提交變更）或 `git diff {base}...HEAD`（比對基底分支）導進 `${TMPDIR:-/tmp}/jsc-code-review.$$.diff` 快照檔並印出展開後的路徑、git 非零退出碼就原文回報 stderr 並停止、快照檔空的就刪檔並回報「無發現」、開六個 sub agent 平行審查六組氣味（1 膨脹、2 晦澀、3 耦合、4 冗贅與其他、5 註解合約、6 淺模組）、六組都只讀步驟 1 的同一份快照、每組回傳六欄 TSV 或「無發現」、六組全數回傳後才把 TSV 依組序餵給 `tools/merge-findings.sh`、依退出碼 0、1、2、3 分流、繁體中文逐列回報、刪掉快照檔、跑 `jsc-hooks/hooks/write-guard.sh release` 解鎖。 |
|
||
| 外部呼叫 | `git diff`、`tools/merge-findings.sh`、`jsc-hooks/hooks/write-guard.sh`（`review` 模式擋寫入工具、`release` 模式解鎖）、`references/smells.md`、`references/comment-scope.md`（第 2 組的禁列與允列來源）、6 個審查 sub agent。沒有 Gitea API 呼叫。 |
|
||
| 完成條件 | 六組全部回傳，合併清單每個位置只出現一次，或整輪以「無發現」收尾，或以 git 或腳本的錯誤收尾。報告交給呼叫方，快照檔已刪除，`release` 指令已經執行，報告內說明 `JSC_WRITE_GUARD_TTL` 逾時解鎖與 `JSC_WRITE_GUARD=off` 兩條退路。修不修由呼叫方決定，實作流程內高與中通常必修，低看情況。 |
|
||
| 可驗證跡象 | 不改任何程式碼。過程中產生 `${TMPDIR:-/tmp}/jsc-code-review.$$.diff` 快照檔，收尾時刪除，跑完該檔不應該還在，殘留就代表沒收尾。解鎖後 `$JSC_HOME/sessions/{sid}.lastskill` 被清掉，可直接檢查。除這兩個檔案狀態外沒有寫入跡象，只有回報內容。 |
|
||
|
||
## comment-cleanup
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 觸發時機 | 使用者要求清註解、移除審查痕跡、不要留審查產物時叫用。提交前 `jsc-hooks` 回報註解範圍警告時叫用，或變更的註解明顯帶著流程細節時叫用。預設只處理這次變更碰到的註解，使用者明講要清舊註解才擴大範圍。 |
|
||
| 關鍵步驟 | 在待清的儲存庫內跑 `tools/changed-comments.sh` 取得範圍（不帶參數看未提交變更，帶 `{base}` 比對基底分支）、依退出碼 0、1、2 分流、退出碼 1 回報「無發現」並停止、退出碼 2 原文回報 stderr 並停止且不手讀 diff 代替、一個檔案開一個 sub agent 平行改寫、每個 sub agent 拿到自己的檔案路徑與該檔的註解列並比對 `references/comment-scope.md`、移除流程細節並保留程式碼存在的理由、只剩流程細節的註解整段刪除、每個 sub agent 回傳前重讀自己改過的區域確認句子完整且沒有殘句、只改註解與文件字串不動行為、全部 sub agent 回傳後跑一次最小的建置或測試指令、失敗就判斷是否本輪造成並依規則重跑一次或還原、依類別回報清理結果。 |
|
||
| 外部呼叫 | `tools/changed-comments.sh`、`references/comment-scope.md`、專案自己的建置或測試指令（沒有就改跑受影響腳本的語法檢查）、`git diff`、每個檔案一個改寫 sub agent。這支技能不呼叫 `jsc-hooks/hooks/write-guard.sh`，也不在它的 `review` 模式擋下範圍內：那支腳本的檔頭寫明 comment-cleanup 一律放行，因為精確判定註解列要解析整份新內容再逐語言判斷，判錯會擋掉合法清理。寫入範圍改由步驟 4 與後續審查把關。沒有 Gitea API 呼叫。 |
|
||
| 完成條件 | 範圍內每一列註解都有結果：維持原樣並說明理由、改寫、或刪除。每個 sub agent 都確認過自己的檔案且沒有未解決的殘句。`git diff` 只顯示註解與文件字串的變更。驗證指令退出碼 0，或報告寫明指令、退出碼與失敗歸屬，或寫明缺哪一個指令。報告說明移除了哪些類別、動了哪些檔案、驗證有沒有過。 |
|
||
| 可驗證跡象 | 這是三支技能裡唯一會改檔的。跑完在工作區留下實際的檔案修改，`git diff` 看得到被清理的註解列，且變更只涵蓋註解與文件字串，不涉及識別字、控制流程、資料結構。還原情境下 `git diff` 會看到該檔的本輪修改被撤回。不寫 wiki 頁、不開 PR、不改狀態檔。 |
|