---
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` 在後（純屬建議，可依相依性調整）。