使用時機
當你需要決定每個提交或 PR 應包含哪些內容時，載入此技能。
適用於：
- 將一個功能拆分為可審查的工作單元。
- 在開啟 PR 前準備提交。
- 將大型變更轉換為鏈結或堆疊式 PR。
- 保持審查者的認知負荷在健康範圍內。
- 應用 SDD 工作時，避免意外產生超過 400 行變更的 PR。
關鍵規則
| 規則 | 要求 |
|---|---|
| 依工作單元提交 | 一個提交代表一個可交付的行為、修正、遷移或文件單元。 |
| 不要依檔案類型提交 | 避免先送 models，再送 services，然後 tests，如果單獨看沒有一個能獨立運作。 |
| 將測試隨附於程式碼 | 測試應與其所驗證的行為在同一次提交中。 |
| 將文件隨附於使用者可見的變更 | 文件應與其所說明的功能或流程放在一起。 |
| 說一個故事 | 審查者應能從 diff 與提交訊息中理解每個提交存在的原因。 |
| 可作為未來 PR 的基礎 | 當變更規模擴大時，每個提交應可成為一個鏈結 PR 的候選。 |
| SDD 工作量防護 | 如果 SDD 工作預測將產生超過 400 行的變更，請在實作前將提交分組為鏈結 PR 的切片。 |
| 預算不是程式碼精簡賽 | 切記不要為了符合審查預算（預設 400 行，或 session 中的 review_budget_lines），而刪除註解、空行、文件或測試，或壓縮程式碼。請依工作單元切片，或回報超量情況。 |
工作單元檢查清單
提交前，請確認：
- 該提交只有一個明確目的。
- 僅套用此提交後，儲存庫仍然合理。
- 若相關，該單元的測試或文件已包含在內。
- 回退此提交時，不會一併回復無關的內容。
- 提交訊息說明的是結果，而非檔案列表。
分割範例
| 不佳的分割 | 較佳的工作單元分割 |
|---|---|
add models | feat(auth): add token validation domain model and tests |
add services | feat(auth): wire token validation into login flow |
add tests | 測試已包含在每個行為提交中 |
update docs | 文件已包含在使用者可見的變更中 |
PR 關係
將工作單元提交作為鏈結 PR 的基礎：
- 建立最小的獨立工作單元。
- 包含該單元的驗證。
- 使用 Conventional Commit 訊息提交。
- 如果 PR 接近 400 行變更，將提交或提交群組提升為鏈結 PR。
SDD 關係
當 sdd-tasks 產出審查工作量預測時：
- 低風險：將工作單元提交保留在單一 PR 中。
- 中風險：依工作單元提交，並在 PR 建立前監控變更行數。
- 高風險：遵循 SDD
delivery_strategy— 在ask-on-risk時詢問，在auto-chain時自動切片，在超預算的single-pr上要求size:exception，或在exception-ok時記錄已接受的size:exception。 - 分割有界限：經過一次誠實的切片嘗試後，如果找不到能符合預算的連貫工作單元分割，請停止並回報最小誠實數量，附上
size:exception建議。不要為了達到數字而反覆壓縮程式碼。
每個 SDD 工作單元應清晰地對應到一個提交或 PR，並具備：
- 明確的起始狀態，
- 明確的完成狀態，
- 驗證位於同一單元內，
- 回退時不會移除無關的內容。
指令
# 提交前檢視故事線
git diff --stat
git diff --cached --stat
# 查看近期提交風格
git log --oneline -5