commit-message（提交消息）

慣例式提交與分支助手

根據 Conventional Commits 1.0.0-beta.4 規範，分析 git staged changes 並自動生成繁體中文 commit message 與建議的分支名稱。

核心功能

1. 分支建議 (Branch Suggestion)：根據變更檔案內容自動生成語意化的 Git 分支名稱。
2. 提交訊息 (Commit Message)：自動生成符合 Conventional Commits 規範的繁體中文提交訊息。
3. 主分支保護 (Main Branch Protection)：防止在 main/master 直接提交，並引導切換至建議分支。
4. 原子化拆分引導 (Atomic Split Guide)：偵測高複雜度變更，引導使用者分批提交。

完整規範請參考 references/conventional-commits-spec.md

組成結構

<類型>[可選的作用範圍]: <描述>

[可選的正文]

[可選的頁腳]

類型（Type）

根據官方規範，以下兩種類型具有語意化版本意義：

以下類型由 @commitlint/config-conventional 推薦使用：

作用範圍（Scope）- 可選

• 作用範圍必須由描述程式區段的名詞組成，並用括號包覆
• 範例：feat(parser):、fix(api):、chore(eslint):

描述（Subject）

• 必須緊接在類型/作用範圍的冒號與空格之後
• 本 Skill 要求使用繁體中文撰寫
• 限制在 50 字元以內
• 使用祈使句（如：「新增」、「修正」、「更新」）
• 不加句號
• 清楚描述變更的核心內容

正文（Body）- 可選

• 必須在描述後的一個空行之後開始
• 本 Skill 要求使用繁體中文撰寫
• 使用項目符號列表（- 開頭）
• 每個項目描述一個具體變更
• 優先說明做了什麼，必要時補充原因
• 使用台灣常用技術詞彙（如：「套件」、「設定」、「腳本」）

頁腳（Footer）- 可選

• 包含關於提交的詮釋資訊
• 範例：相關的拉取請求、審核者、重大變更
• 每個詮釋資訊一行

重大變更（Breaking Changes）

根據官方規範，重大變更對應到 SemVer 的 MAJOR 版本。標示方式：

方式一：在類型後加 !

feat(api)!: 變更使用者認證機制

BREAKING CHANGE: 移除舊版 API 端點，所有用戶端需更新至新版 SDK

方式二：僅在頁腳標示

feat: 變更使用者認證機制

- 實作新版 OAuth 2.0 流程
- 移除舊版 session 認證

BREAKING CHANGE: 移除舊版 API 端點，所有用戶端需更新至新版 SDK

規範要求：

• BREAKING CHANGE 必須大寫
• 使用 ! 提示時，正文或頁腳內必須包含 BREAKING CHANGE: description

執行步驟

步驟 1：取得分析資訊

首先執行輔助腳本，自動檢查分支與計算複雜度評分：

python scripts/analyze_git.py

腳本輸出除了原有欄位外，現在也包含每個 staged 檔案的變更類型：

步驟 2：檢查分支

根據腳本輸出的 IsMain 與 Branch 欄位判斷：

情況 A（安全分支）： 若 IsMain: false

• 繼續執行步驟 3

情況 B（主分支）： 若 IsMain: true

• 停止後續操作
• 依據變更內容，建議符合規範的新分支名稱（範例：feat/login-form-validation、fix/payment-bug）
• 回報錯誤：請先切換至建議的分支（或自訂分支）後，再執行 commit。

步驟 3：分析複雜度與模式

根據腳本輸出的 Score 與 RiskFactors 決定模式：

情況 A：簡單模式（Score < 4）

• 直接使用 -m 參數生成 commit message
• 適用於小型、低風險的變更

git commit -m "feat: 新增使用者登入功能"

情況 B：複雜模式（Score >= 4）

• 重要：若 Score 顯著過高（如 Score > 8），強烈建議拆分提交。
• 建議使用者使用檔案方式生成詳細的 commit message，或協助進行原子化拆分。

步驟 4：原子化拆分提交（針對 Score > 8 或多種類型變更）

若決定拆分提交，請引導使用者執行以下步驟：

1. 撤銷目前的所有 add：git reset
2. 第一階段 add：選擇相關性強的檔案，例如 git add src/auth.ts src/security.ts
3. 執行第一階段 commit：生成對應的 commit message
4. 第二階段 add：例如 git add package-lock.json
5. 執行第二階段 commit：生成對應的 commit message

步驟 5：生成 Commit Message 並確認

1. 依據檔案狀態決定 commit type（優先使用，再搭配 diff 內容確認）： 狀況 建議類型 NewFiles 為主，且為功能性程式碼 feat NewFiles 為主，且為測試檔案（*.test.*, *.spec.*） test NewFiles 為主，且為文件（.md, .txt） docs 僅有 ModifiedFiles，修正問題邏輯 fix 僅有 ModifiedFiles，程式碼重構（無功能變更） refactor 僅有 RenamedFiles 或檔案搬移 refactor 僅有 DeletedFiles（清理舊程式碼） chore 或 refactor 混合多種狀態，涉及功能新增 feat（並考慮拆分）
2. 結合 git diff 內容確認描述的精確性
3. 依據步驟 3 選擇的模式，輸出完整的 Commit Message
4. 輸出對應的 git commit 指令
5. 詢問使用者：是否需要協助執行 commit？

範例

拆分提交建議範例

### ⚠️ 偵測到高複雜度變更 (Score: 10)

本次變更涉及認證邏輯重構與套件更新，建議拆分為兩個提交以符合原子化原則：

#### 第一步：重構認證邏輯
1. 執行：`git reset`
2. 執行：`git add src/auth.ts src/security.ts`
3. Commit Message：`refactor(auth): 重構認證模組安全性邏輯`

#### 第二步：更新套件
1. 執行：`git add pnpm-lock.yaml`
2. Commit Message：`build: 更新相依性鎖定檔`

注意事項

• Lock 檔案偵測範圍：包含 package-lock.json、yarn.lock、pnpm-lock.yaml、bun-lock.json、Cargo.lock、go.sum、poetry.lock、Gemfile.lock 等。
• 只有 staged 狀態的變更會被考慮。
• 若變更過於複雜，建議拆分為多個獨立的 commit。
• 當提交符合一或多種提交類型時，應盡可能切成多個提交。

範例

詳細範例請參考 references/examples.md，涵蓋：

• 基礎範例：feat、fix、docs、style、refactor、perf、test、build、ci、chore、revert
• 進階範例：含作用範圍、破壞性變更、問題編號、共同作者、複雜變更
• 不良範例：常見錯誤寫法與修正建議

快速參考：

feat: 新增使用者登入功能

- 實作 JWT 認證機制
- 新增登入表單驗證

fix(cart): 修正購物車金額計算錯誤

- 修正折扣碼套用順序問題

注意事項

• 只有 staged 狀態的變更會被考慮
• 未 staged 的變更不會包含在 commit message 分析中
• 建議先使用 git add 選擇性地 stage 要提交的變更
• 若變更過於複雜，建議拆分為多個獨立的 commit
• 當提交符合一或多種提交類型時，應盡可能切成多個提交

常用技術詞彙對照

參考資料

• references/conventional-commits-spec.md - 慣例式提交 1.0.0-beta.4 完整規範
• references/examples.md - 各類型 commit message 範例集
• Conventional Commits 官方網站
• SemVer 語意化版本
• @commitlint/config-conventional