jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
60 lines
4.5 KiB
Markdown
60 lines
4.5 KiB
Markdown
---
|
||
name: spec-conventional-commit
|
||
description: JSC plugins 共用「Conventional Commit 分類提交規範」：以 git status --porcelain=v1 -uall 完整盤點工作區變更、9 種 commit 類型對照（feat／fix／docs／style／refactor／perf／test／chore／revert）、commit 訊息格式為 type(範圍)：一句總結、範圍不得重述 type 本身、依邏輯分組後逐組以精準檔案路徑分別 git add（不用 git add -A 或 git add .）分類提交。當其他 skill 內文引用 spec-conventional-commit 或 /jsc-shared:spec-conventional-commit、或需要把工作區變更依 conventional commit 分類提交時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-conventional-commit — 共用 Conventional Commit 分類提交規範
|
||
|
||
工作區有變更需要 commit 時，一律遵守以下規範：先完整盤點、依實際異動內容歸類，再依邏輯分組並逐組精準提交。
|
||
|
||
## 盤點工作區變更
|
||
|
||
- 一律以 `git status --porcelain=v1 -uall` 為主，不可只看 `git diff` —— 那會漏掉未追蹤檔。`git diff`（已追蹤檔未暫存變更）、`git diff --staged`（已暫存變更）、`git ls-files --others --exclude-standard`（未追蹤檔）只作輔助核對。
|
||
- 盤點範圍必須包含**所有**變更：已修改檔、新增檔（`??` 未追蹤檔）、刪除檔、改名檔，以及已暫存與未暫存的變更。
|
||
- **無任何變更** → 回報「工作區無變更可提交」，跳過提交。
|
||
|
||
## commit 類型對照表
|
||
|
||
逐一檢視每個變更檔的**實際異動內容**（不只看路徑），歸入下列其一；所有 `??` 未追蹤檔都必須納入分類，不能因為不在 `git diff` 裡就漏掉。
|
||
|
||
| type | 適用情境 |
|
||
| --- | --- |
|
||
| `feat` | 新增功能／新行為／新 API／新 skill |
|
||
| `fix` | 修正錯誤、修掉 bug |
|
||
| `docs` | 只改文件（README、註解、`*.md`、說明） |
|
||
| `style` | 不影響邏輯的格式調整（排版、空白、分號、命名一致化） |
|
||
| `refactor` | 重構：不改外部行為的內部結構調整 |
|
||
| `perf` | 效能優化 |
|
||
| `test` | 新增或修改測試 |
|
||
| `chore` | 雜項：建置、設定、相依套件、版本號 bump、忽略檔等 |
|
||
| `revert` | 還原先前的提交 |
|
||
|
||
- **同一檔案橫跨多型** → 以該檔主要異動性質歸類；難以拆分時就近歸入影響最大的一類，並在總結註記。
|
||
- **未追蹤新檔**：必須照實際內容歸入對應 type，必要時在提交前明確 `git add -- <path>`，不可因為是新檔就略過。
|
||
|
||
## commit 訊息格式
|
||
|
||
`type(範圍): 一句總結`
|
||
|
||
- `type`：上表其中一個英文類型。
|
||
- **範圍**（括號內）：必須是這組異動實際牽涉的功能／模組／元件名稱，**不得重述 type 本身**。取名規則：優先沿用程式碼／專案中既有的識別名（檔名、模組名、skill 名、功能名，可中可英、保持與原碼一致），讓人一眼看出「改到哪個東西」。
|
||
- ✅ 對：`feat(使用者登入)`、`fix(結帳流程)`、`perf(物件查詢)`、`docs(README)`、`refactor(訂單服務)`、`chore(plugin 版本)`。
|
||
- ❌ 錯（只是重述 type，禁止）：`feat(新增功能)`、`fix(修正錯誤)`、`perf(優化效能)`、`docs(文件)`、`chore(雜項)`。
|
||
- 一組異動橫跨多個功能而無單一主體時，才退而取最貼近的上層範圍（例如多個 manifest → `plugin 設定`）。
|
||
- **一句總結**：把這個 commit 內所有異動總結成一句繁體中文，簡短、聚焦做了什麼。
|
||
- 範例：`feat(使用者登入): 新增帳密登入與 token 簽發`、`fix(結帳流程): 修正空購物車導致的結帳例外`、`perf(物件查詢): 改用批次查詢降低 DB 往返`、`docs(README): 補上安裝與呼叫方式說明`、`chore(ai-review 狀態): 更新 findings 與 exclusions.json`。
|
||
|
||
## 分組與提交順序
|
||
|
||
1. 依 commit 類型把變更檔分組，**每個 type 一個 commit**；提交計畫必須完整對應盤點出的所有變更項目，不能遺漏任何 `??` 未追蹤檔。
|
||
2. 逐組執行，每次僅暫存該組檔案：
|
||
|
||
```bash
|
||
git add -- <該組檔案...> # 僅暫存該組檔案，逐組精準 add
|
||
git commit -m "type(範圍): 一句總結"
|
||
```
|
||
|
||
3. **不用 `git add -A` 或 `git add .`**，避免把不同類型的異動混進同一個 commit。
|
||
4. 改名／刪除檔一併納入對應組的 `git add`（`git add -A -- <路徑>` 或明確列出該路徑）。
|
||
5. **提交順序建議**：`fix`／`feat` 等核心異動在前，`docs`／`style`／`chore` 在後（純屬建議，可依相依性調整）。
|