慣例式提交與分支助手

根據 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）

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

類型	SemVer	說明
feat	MINOR	新增功能
fix	PATCH	修正臭蟲

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

類型	說明
docs	文件更新
style	程式碼格式調整（不影響功能）
refactor	重構程式碼
perf	效能優化
test	測試相關
build	建置系統或外部相依性
ci	CI 設定檔案
chore	其他雜項（工具、配置等）
revert	撤銷先前的 commit

作用範圍（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

步驟 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. 分析變更類型和影響範圍
2. 根據變更內容決定最適合的 commit type
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
• 當提交符合一或多種提交類型時，應盡可能切成多個提交

常用技術詞彙對照

英文	繁體中文（台灣慣用）
package	套件
config/configuration	設定
script	腳本
dependency	相依性
component	元件
module	模組
function	函式
variable	變數
parameter	參數
implement	實作
initialize	初始化
optimize	優化
refactor	重構
validate	驗證
authentication	認證
authorization	授權
bug	臭蟲
pull request	拉取請求

參考資料

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