CloudyWing/generate-commit

產生 Git Commit 訊息

當使用者的意圖是「建立一個 git commit」時，無論措辭為何，都必須透過本技能執行，不得直接用 Bash 執行 git 指令。涵蓋但不限於以下語意：

• 明確提及 commit：「幫我 commit」「commit 一下」「commit 這些變更」「建立 commit」「產生 commit 訊息」。
• 提交動作：「幫我提交」「把這些提交上去」「存成一個版本」。
• 詢問 commit 訊息寫法：「commit message 怎麼寫」「這段變更的 commit 訊息」。

執行步驟

1. 取得全量變更（強制）

在產生 commit 訊息前，必須先看過真實的變更內容，不得僅憑對話記憶：

1. 執行 git status --short 一次掌握所有變更（staged、unstaged、untracked 一併呈現）。
2. 對所有有變更的檔案逐一取得實際差異（追蹤中的檔案用 git diff HEAD -- <file>，untracked 檔直接讀內容），不得因「檔名已能說明意圖」而略過。不分檔案是否已 staged，全部都要看。
3. 若無任何變更，告知使用者目前沒有可 commit 的內容，流程終止，不產生 commit 訊息。

🚨 此規則只約束「訊息措辭」，不約束「commit 範圍」。 Subject 與 Body 中對「改了什麼」的描述必須 100% 來自 git diff 的實際輸出，絕對禁止根據對話或記憶推斷、編造 diff 以外的變更。對話上下文僅可用於補充 Body 的動機說明（為什麼改），且須與當次 diff 直接關聯；若無把握，略去動機即可。

範圍判定見步驟 2，與本條無關，不得因某變更「沒在對話提過」就排除它。

2. 判定 commit 範圍（預設全包，減去雜訊）

預設將所有實際變更納入本次 commit，再扣除雜訊，而非只挑對話提過的檔案：

• 高信心雜訊自動排除：*.bak、*.tmp、CONTEXT.local.md、明確的除錯或一次性暫存腳本，直接不納入，不需逐一詢問。被自動排除的項目須在最後一併列出，讓使用者可推翻。
• 模糊檔案才提示確認：無法判定是否為過渡產物時，列出並請使用者裁決，不自行決定。
• 對話未提及不等於要排除：只要某變更的內容與本次工作主題一致，即使對話沒談到也一律納入並如實描述。對話只決定「動機怎麼寫」，不決定「該 commit 哪些檔」。
• 手動 staged 是縮範圍的訊號，但不可默默丟：若使用者已自行 stage 一個子集，視為刻意指定範圍；仍須列出未 staged 的相關變更並問一句是否一併納入，不得直接忽略。

3. 評估是否拆分 Commit

依「語意關聯」判斷：

1. 所有變更圍繞同一主題（功能、修正、重構）→ 單一 commit，進入步驟 4。
2. 變更明顯涵蓋兩個以上不相關主題，且可依檔案切開（無單一檔案橫跨多主題）→ 建議檔案級拆分，輸出拆分計畫後依序執行。
3. 使用者選擇不拆分 → 合併為單一 commit，標題涵蓋主要變更。

hunk 級拆分（同一檔案內含不相關主題、需 git add -p 逐塊 stage）成本高且需使用者來回操作，僅在使用者明確要求時才執行，預設不主動提出。

檔案級拆分計畫格式：

建議拆分為 N 個 commit：

Commit 1：<commit message>
  - file_a.cs
  - file_b.md

Commit 2：<commit message>
  - file_c.cs

4. 執行 Commit

確定範圍後，先 stage 範圍內的檔案（git add <files>），再依下方規範產生訊息並 commit，不需另外詢問確認：

• 單一 commit：stage 範圍內檔案後執行 git commit。
• 檔案級拆分：依序「stage 該組檔案 → commit」，逐組完成。
• hunk 級拆分（僅使用者要求時）：輸出拆分計畫後暫停，請使用者以 git add -p 完成 staging 並回報，再執行對應的 commit。

訊息傳遞方式（強制）：含 Body 的多行訊息一律以 git commit -F 從檔案或 stdin 讀取，逐字保留換行與空行。不得用多個 -m 逐行傳遞；git 會將每個 -m 視為獨立段落並在段落間插入空行，使 Body 的條列之間出現多餘空行。

• PowerShell：用單引號 here-string 接 git commit -F -。
• Bash：用 here-doc 接 git commit -F -，或先將訊息寫入暫存檔再以 git commit -F <檔案> 提交。

Commit 執行完畢後，輸出最終的 commit 訊息內容（含本次自動排除的檔案清單），供使用者確認是否需要至 git 調整。

---

Commit 訊息規範

Header Format

Pattern: <type>([scope]): <subject>

Type Whitelist

• feat: 新增過去不存在的功能或能力。
• fix: 修正既有功能的錯誤，使曾經正確、後來故障的行為恢復正常。
• refactor: 程式碼重構，對外可觀察行為不變。
• style: 格式調整（如括號位置、分號，不影響邏輯）。
• docs: 僅文件異動。
• perf: 在行為不變的前提下改善效能（不含行銷詞彙）。
• ci: CI 設定與腳本異動（如 GitHub Actions, GitLab CI, scripts）。
• test: 新增或修正測試。
• chore: 建置流程、相依性套件更新、雜項（如 .gitignore）。

分類判定基準

feat / fix / refactor / perf 的判定，以可觀察行為的變化為準，不以變更動機為準。

Tie-breaker（動機 vs 行為）：當變更的動機是「解決某個問題」，但達成手段是新增一條過去不存在的程式路徑時，以「能力是否為新增」為準歸 feat，不因動機像在補洞就歸 fix。唯有該行為曾經正確運作、後來才故障（屬回歸修復）時才歸 fix。

判定範例：

• 為結帳流程加入折價券套用 → feat（新增過去不存在的能力）。
• 修正訂單金額在特定幣別下的計算錯誤 → fix（既有行為故障後恢復）。
• 將使用者登入驗證邏輯抽成獨立服務、對外行為不變 → refactor（只動內部結構）。
• 商品列表查詢改批次載入以消除 N+1、結果相同 → perf（行為不變、效能改善）。

Scope Rules（建議省略）

• 預設省略：Scope 為非必填項目，對於多數一般性修改，強烈建議直接省略。
• 白名單機制：若確實需要說明影響範圍，僅允許填寫專案的第一層目錄名稱（依當前專案結構判斷，如 src, tests, docs 等）。不在專案目錄結構內的名稱一律不寫 Scope。
• 禁止隨意創造：不接受 all, update, config 等無明確邊界的無效 Scope。

Subject Rules

• Language: 台灣用語正體中文 (Traditional Chinese, Taiwan)。
• Style: 命令式動詞開頭（例如：新增, 修正, 移除, 重構）。
• Length: 不限制長度，以完整表達變更重點為優先。
• Forbidden:
  • 結尾不加句號。
  • 避免使用模糊字眼（如「更新程式碼」、「修改檔案」、「調整邏輯」），必須具體說明變更內容。

Body Rules

• Trigger: 僅在 「變更邏輯複雜」 或 「包含 Breaking Change」 時生成。若標題已能充分說明變更，即使涉及多個檔案亦無需 Body。
• Format:
  • Header 與 Body 之間空一行。
  • 使用連字號 - 加一個空格作為條列點。
  • 每一點條列必須以句號 。 結尾。
  • 描述應保持客觀簡潔，不解釋實作細節，僅說明「變更內容」與「必要原因」。
  • 動機說明可參考對話上下文補充「為什麼改」，但必須與當次 diff 直接相關；若無把握，略去動機說明。

Forbidden Footer

• 禁止加入 Co-Authored-By：commit 訊息不得附加任何 Co-Authored-By: 行，包含 AI 工具的署名。
• 禁止加入執行摘要：不得在 commit 訊息任何位置附加 AI 產生的執行狀態資訊，包含但不限於測試通過數、任務完成進度、建置結果等（如「共執行 X 個測試」、「已完成 N 項」、「Build 成功」）。Commit 訊息僅描述程式碼變更本身。

Core Principles

• Atomic Focus: 標題應反映最核心的邏輯變更。
• Objective Language: 描述使用客觀、具體的詞語，不使用「大幅提升效能」、「改善使用者體驗」、「顯著最佳化」等主觀修飾語。
• Precision: 描述應中性且具體，避免過度描述瑣碎細節。

範例

✅ 正確範例：

feat(skills): 新增 check-markdown 技能

- 實作段落空白與全半形符號的自動校對規則。
- 新增技能說明與測試範例。

fix: 修正 commit 規範格式錯誤

- 補齊遺漏的 Body 標題。
- 修正列表縮排層級。

❌ 錯誤範例：

# 模糊動詞 + 不必要的自創 Scope
fix(all): 修改程式碼

# 行銷用語 + 主觀修飾
refactor(prompts): 大幅提升 Prompt 效能與使用者體驗

# 結尾加句號+大陸用語
feat: 添加新的配置項。