jiantw83andClaude Opus 5
821261ad9d
What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。 Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。 How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。 Who：jsc-meta:skill-check 例行稽核（2026-08-25）。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
74 lines
7.9 KiB
Markdown
74 lines
7.9 KiB
Markdown
# jsc-sdlc — 開發生命週期
|
||
|
||
jsc 技能組的 sdlc domain：規劃 → 分析 → 實作 → 維護四個階段，全程以 wiki 頁追蹤（`PLAN_CONTENTS`、`PLAN_{HASH}`、`ANALYZE_CONTENTS`、`ANALYZE_{HASH}`、`REPO_CONTENTS`、`REPO_{HASH}`、`DELIVER_CONTENTS`、`DELIVER_{HASH}`、`MAINTAIN_CONTENTS`）。工作包完成即交付：實作階段會詢問交付文件要產生成 `DELIVER_{HASH}` wiki 頁或 Gitea 議題留言。hook 或流程失敗記在異常頁（`ERROR_CONTENTS`、`ERROR_{HASH}`），那組頁面與範本由 `jsc-hooks` 擁有，本 domain 不放副本。每次切換階段先過模型閘門，判定全在程式層，由 `jsc-hooks/hooks/sdlc-gate.sh lock {stage}` 執行；各階段必要標籤、阻擋與回報的鐵則見 `references/model-gate.md`。分析前先與使用者確認來源分支；實作沿用同一條來源分支作為 worktree 基準與 PR 目標。**所有參考與來源分支一律取遠端的 `origin/{branch}`，動作前先 `git fetch --prune origin`；本地分支不可作為基準，本地與遠端不一致就停下回報。**
|
||
|
||
## 安裝、更新、移除
|
||
|
||
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-sdlc@jsc`。每個指令一行：
|
||
|
||
| CLI | 安裝 | 更新 | 移除 |
|
||
| --- | --- | --- | --- |
|
||
| claude | `claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-sdlc@jsc` | `claude plugin marketplace update jsc && claude plugin update jsc-sdlc@jsc` | `claude plugin uninstall jsc-sdlc@jsc` |
|
||
| codex | `codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-sdlc@jsc` | `codex plugin marketplace upgrade jsc` | `codex plugin remove jsc-sdlc@jsc` |
|
||
| copilot | `copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-sdlc@jsc` | `copilot plugin marketplace update jsc && copilot plugin update jsc-sdlc@jsc` | `copilot plugin uninstall jsc-sdlc@jsc` |
|
||
| antigravity | `git clone https://gitea.jsc.idv.tw/plugins/sdlc.git ~/plugins/sdlc && agy plugin install ~/plugins/sdlc` | `git -C ~/plugins/sdlc pull && agy plugin uninstall jsc-sdlc && agy plugin install ~/plugins/sdlc` | `agy plugin uninstall jsc-sdlc` |
|
||
| kiro | `kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-sdlc@jsc` | `kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-sdlc@jsc` | `kiro-cli plugin uninstall jsc-sdlc@jsc` |
|
||
|
||
> antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用 `/jsc-cli:deploy`。
|
||
|
||
> 舊入口 `plugins/jsc` 已移除，marketplace 正本移到 `plugins/meta`。marketplace 名稱仍是 `jsc`（取自 marketplace.json 的 `name` 欄位，與存取庫名無關），安裝 token 不變；已從舊入口安裝過的人先執行 `claude plugin marketplace remove jsc`，再依上表重新 add。
|
||
|
||
## Skills 目錄
|
||
|
||
呼叫方式：Claude / Antigravity `/jsc-sdlc:{name}`；Codex `${name}`；Copilot / Kiro 描述需求自動觸發。
|
||
|
||
<!-- JSC-SKILLS:START -->
|
||
|
||
### `plan`
|
||
|
||
規劃：讀計畫目錄 → 補充或新建計畫 → 決策樹持續提問，補全目標、範圍、可行性到達成共識（判定規則見 `references/consensus.md`，一輪不算問完）→ 產生使用者故事 → 寫回 `PLAN_{HASH}`。純邏輯，禁止程式碼與修改檔案。
|
||
|
||
### `analyze`
|
||
|
||
分析：先確認來源分支 → 持續提問到達成共識（`references/consensus.md`）→ 搭配現況（工作目錄與 `REPO_{HASH}` 盤點複用）分析使用者故事 → WBS 產生編號工作包，`WP-01` 固定是獨立的交付、交接工作包，實作工作包相依於它 → CPM 估工時與天數 → TDD 拆待辦 → 寫回 `ANALYZE_{HASH}`。純邏輯，禁止程式碼與修改檔案。
|
||
|
||
### `implement`
|
||
|
||
實作：先確認來源分支（同時是 PR 目標）→ 產生工作證鎖定「未完成、無相依、無工作證」的工作包（交付工作包優先）→ 交付工作包開工前先確認交付內容（API 文件、由使用者輸入，見 `references/deliver-formats.md`）→ **動程式碼前先從 `origin/{source-branch}` 建立 worktree**（`.worktree/{analysis-HASH}/{repo}`，分支處理依決策樹詢問）→ 在 worktree 內逐項 TDD 實作、每完成一項立即更新 wiki → 程式碼審查 → **每完成一個工作包就 commit、push、PR 回來源分支**（一包一 PR）→ **PR 未合併就不開下一包**；每次要領工作包前先查 PR 狀態並讀留言，依決策樹問使用者要修正還是等待；合併後才移除 worktree → 詢問交付文件格式（`DELIVER_{HASH}` wiki 頁或 Gitea 議題留言）並產出 → 詢問是否加入維護目錄。
|
||
|
||
### `maintain`
|
||
|
||
維護：讀取維護期內的專案，每個專案一個 sub agent：fetch 後切 develop、master 並對齊 `origin/{branch}` → 提出至少五種維護方法，依決策樹讓使用者挑要做哪些 → commit / push / PR → 更新前次維護時間。僅適用於維護期內已交付的專案；尚在實作中或未登記於 `MAINTAIN_CONTENTS` 的專案不適用。
|
||
|
||
<!-- JSC-SKILLS:END -->
|
||
|
||
## 範本與參考
|
||
|
||
| 檔案 | 用途 |
|
||
| --- | --- |
|
||
| `templates/plan-page.md`、`templates/plan-contents.md` | 計畫頁與計畫目錄 |
|
||
| `templates/analyze-page.md`、`templates/analyze-contents.md` | 分析頁（WBS、CPM、TDD 待辦）與分析目錄 |
|
||
| `templates/repo-page.md`、`templates/repo-contents.md` | 存取庫盤點頁（功能與端點，附 commit sha）與盤點目錄 |
|
||
| `templates/deliver-page.md`、`templates/deliver-contents.md` | 交付頁（API 文件、新舊參數標示、驗證方式）與交付目錄 |
|
||
| `templates/maintain-contents.md` | 維護目錄（截止日 NULL = 永久維護） |
|
||
| `references/model-gate.md` | 模型閘門：執行順序、各階段必要標籤、阻擋與回報的鐵則 |
|
||
| `references/tdd.md` | 接縫、紅綠循環規則、反模式 |
|
||
| `references/branch.md` | 分支規則：**一律以遠端 `origin/{branch}` 為準、動作前先 fetch**、分析前確認來源分支、實作沿用同一條來源分支作為 PR 目標（一包一 PR、PR 未合併不開下一包）、實作一律在 `.worktree/{HASH}/{repo}` 內進行（建立前問分支、PR 合併後才移除）、判定遠端預設分支、不破壞未提交變更 |
|
||
| `references/consensus.md` | 規劃與分析的提問規則：一輪不算問完、共識的兩個判定條件、未決項處理 |
|
||
| `references/deliver-formats.md` | 交付內容型別：API 文件必備欄位、範例資料優先序、既有端點的新舊參數標示 |
|
||
|
||
## 環境變數
|
||
|
||
Wiki 位置：`PLAN_{HASH}` / `PLAN_CONTENTS` 只讀 `JSC_WIKI_REPO_PLAN`，再退回 `JSC_WIKI_REPO`；`ANALYZE_{HASH}` / `ANALYZE_CONTENTS` 只讀 `JSC_WIKI_REPO_ANALYZE`，再退回 `JSC_WIKI_REPO`；`REPO_{HASH}` / `REPO_CONTENTS` 只讀 `JSC_WIKI_REPO_REPO`，再退回 `JSC_WIKI_REPO`；`DELIVER_{HASH}` / `DELIVER_CONTENTS` 只讀 `JSC_WIKI_REPO_DELIVER`，再退回 `JSC_WIKI_REPO`；`MAINTAIN_CONTENTS` 只讀 `JSC_WIKI_REPO_MAINTAIN`，再退回 `JSC_WIKI_REPO`。不同類型不可互相代用；兩者都未設定才詢問（見 `jsc-gitea`）。
|
||
|
||
HASH 規則：`{owner}/{repo}` 的共用 wiki hash 一律由 `jsc-gitea/tools/hash-id` 計算（見 `jsc-gitea:wiki`），此 domain 不重複實作演算法。
|
||
|
||
## 相關 domain
|
||
|
||
- [`jsc-cli`](https://gitea.jsc.idv.tw/plugins/cli)：模型能力標籤與階段閘門判定（`tools/model-tags.sh`、`references/model-tags.md`、`jsc-cli:models`）、偏好模型鏈（`tools/model-config.sh`）
|
||
- [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：sdlc-gate 階段模型鎖定
|
||
- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫
|
||
- [`jsc-review`](https://gitea.jsc.idv.tw/plugins/review)：實作完成後的程式碼審查
|
||
- [`jsc-git`](https://gitea.jsc.idv.tw/plugins/git) / [`jsc-pkg`](https://gitea.jsc.idv.tw/plugins/pkg)：維護階段的 commit / PR 與套件更新
|
||
- [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：完工後的工作日誌
|