慣例式提交與分支助手

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

核心功能

分支建議 (Branch Suggestion)：根據變更檔案內容自動生成語意化的 Git 分支名稱。
提交訊息 (Commit Message)：自動生成符合 Conventional Commits 規範的繁體中文提交訊息。
主分支保護 (Main Branch Protection)：防止在 main/master 直接提交，並引導切換至建議分支。
原子化拆分引導 (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

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

欄位	說明
`NewFiles`	新增的檔案（`git status` 顯示 `A`）
`ModifiedFiles`	修改的現有檔案（顯示 `M`）
`DeletedFiles`	刪除的檔案（顯示 `D`）
`RenamedFiles`	重新命名或複製的檔案（`git status` 顯示 `R`/`C`，格式 `old -> new`）

步驟 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 或多種類型變更）

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

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

步驟 5：生成 Commit Message 並確認

依據檔案狀態決定 commit type（優先使用，再搭配 diff 內容確認）：

狀況	建議類型
`NewFiles` 為主，且為功能性程式碼	`feat`
`NewFiles` 為主，且為測試檔案（`.test.`, `.spec.`）	`test`
`NewFiles` 為主，且為文件（`.md`, `.txt`）	`docs`
僅有 `ModifiedFiles`，修正問題邏輯	`fix`
僅有 `ModifiedFiles`，程式碼重構（無功能變更）	`refactor`
僅有 `RenamedFiles` 或檔案搬移	`refactor`
僅有 `DeletedFiles`（清理舊程式碼）	`chore` 或 `refactor`
混合多種狀態，涉及功能新增	`feat`（並考慮拆分）

結合 git diff 內容確認描述的精確性
依據步驟 3 選擇的模式，輸出完整的 Commit Message
輸出對應的 git commit 指令
詢問使用者：是否需要協助執行 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

commit-message

慣例式提交與分支助手

核心功能

組成結構

類型（Type）

作用範圍（Scope）- 可選

描述（Subject）

正文（Body）- 可選

頁腳（Footer）- 可選

重大變更（Breaking Changes）

執行步驟

步驟 1：取得分析資訊

步驟 2：檢查分支

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

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

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

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

步驟 5：生成 Commit Message 並確認

範例

拆分提交建議範例

注意事項

範例

注意事項

常用技術詞彙對照

參考資料