簽入助手

語言：English | 繁體中文

版本：1.0.0 最後更新：2026-01-12 適用範圍：Claude Code Skills

目的

此技能引導開發人員完成提交前的品質關卡，確保每次提交都能維護程式碼庫的穩定性並遵循最佳實踐。

注意：此技能專注於何時以及如何提交。有關 PR 期間的程式碼審查，請參閱程式碼審查助手。

快速參考（YAML 壓縮格式）

# === 核心理念 ===
每次提交應該:
  - "是一個完整的邏輯工作單元"
  - "讓程式碼庫保持可運行狀態"
  - "可以回滾而不破壞功能"
  - "包含自己的測試（新功能）"
  - "讓未來的開發者能夠理解"

# === 強制檢查清單 ===
checklist:
  建置:
    - "程式碼編譯成功（零錯誤）"
    - "所有相依套件已滿足"
    驗證: "執行建置指令，退出碼為 0"

  測試:
    - "所有現有測試通過（100%）"
    - "新程式碼有對應測試"
    - "覆蓋率沒有下降"
    驗證: "執行測試套件，檢查覆蓋率"

  品質:
    - "遵循編碼標準"
    - "無程式碼異味（方法≤50行，巢狀≤3層，複雜度≤10）"
    - "無寫死的密鑰"
    - "無安全漏洞"
    驗證: "執行 linter、安全掃描器"

  文件:
    - "API 文件已更新"
    - "README 已更新（如需要）"
    - "CHANGELOG 已更新（使用者可見變更 → [Unreleased]）"

  工作流程:
    - "分支命名正確（feature/, fix/, docs/, chore/）"
    - "提交訊息格式正確（conventional commits）"
    - "已與目標分支同步"

# === 絕不在以下情況提交 ===
阻擋條件:
  - "建置有錯誤"
  - "測試失敗"
  - "功能不完整（會破壞功能）"
  - "關鍵邏輯中包含 WIP/TODO"
  - "包含除錯程式碼（console.log, print）"
  - "包含被註解的程式碼區塊"

# === 提交時機 ===
好的時機:
  - 完成單元: "功能完整實作並附帶測試"
  - 修復錯誤: "錯誤已修復並有迴歸測試"
  - 獨立重構: "重構完成，所有測試通過"
  - 可運行狀態: "程式碼編譯通過，應用程式可執行"

不好的時機:
  - "建置失敗"
  - "測試失敗"
  - "功能不完整"
  - "實驗性程式碼散佈著 TODO"

# === 粒度 ===
理想提交:
  檔案數: "1-10（超過 10 則考慮拆分）"
  行數: "50-300"
  範圍: "單一關注點"

拆分原則:
  合併: ["功能 + 其測試", "緊密相關的多檔案變更"]
  分開: ["功能 A + B", "重構 + 新功能", "錯誤修復 + 順便重構"]

# === 特殊情境 ===
緊急離開:
  建議: "git stash save 'WIP: 描述'"
  替代方案: "建立 wip/ 分支"
  禁止: "直接在功能分支上提交 WIP"

實驗性開發:
  分支: "experiment/主題名稱"
  規則: "自由提交（無嚴格格式）"
  成功: "清理、壓縮、合併到功能分支"
  失敗: "記錄教訓、刪除分支"

緊急修復:
  分支: "hotfix/問題名稱，從 main 分出"
  規則: "最小化變更，只修復問題"
  訊息: "fix(scope): [URGENT] 描述"

檢查清單視覺格式

每次提交前使用此檢查清單：

┌─────────────────────────────────────────────────────────────────┐
│  📋 提交前檢查清單                                               │
├─────────────────────────────────────────────────────────────────┤
│  🔨 建置                                                        │
│  □ 程式碼編譯成功（零錯誤）                                      │
│  □ 所有相依套件已滿足                                           │
├─────────────────────────────────────────────────────────────────┤
│  🧪 測試                                                        │
│  □ 所有現有測試通過（100%）                                      │
│  □ 新程式碼有對應測試                                           │
│  □ 測試覆蓋率沒有下降                                           │
├─────────────────────────────────────────────────────────────────┤
│  ✨ 程式碼品質                                                   │
│  □ 遵循專案編碼標準                                              │
│  □ 無寫死的密鑰或憑證                                           │
│  □ 無安全漏洞                                                   │
├─────────────────────────────────────────────────────────────────┤
│  📝 文件                                                        │
│  □ API 文件已更新（如適用）                                      │
│  □ CHANGELOG 已更新（使用者可見變更）                            │
├─────────────────────────────────────────────────────────────────┤
│  🔄 工作流程                                                     │
│  □ 分支命名遵循規範                                              │
│  □ 提交訊息遵循 conventional commits                             │
│  □ 已與目標分支同步（無衝突）                                    │
└─────────────────────────────────────────────────────────────────┘

簽入觸發點

何時提示提交

提醒格式

┌────────────────────────────────────────────────┐
│ 🔔 簽入檢查點                                   │
├────────────────────────────────────────────────┤
│ 階段 1 已完成                                   │
│                                                │
│ 變更統計：                                      │
│   - 檔案數：5                                   │
│   - 新增：180 行                                │
│   - 刪除：12 行                                 │
│                                                │
│ 測試狀態：✅ 通過                               │
│                                                │
│ 建議的提交訊息：                                │
│   feat(module): 完成階段 1 設定                 │
│                                                │
│ 選項：                                          │
│   [1] 現在提交（會顯示 git 指令）               │
│   [2] 稍後提交，繼續下一階段                    │
│   [3] 查看詳細變更                              │
└────────────────────────────────────────────────┘

跳過警告

連續跳過 3 次後：

⚠️ 警告：您已連續跳過簽入 3 次
目前累積變更：15 個檔案，+520 行
建議盡快提交，避免變更過大難以審查

AI 助手工作流程

當 AI 完成程式碼變更時，遵循此工作流程：

步驟 1：評估時機

✅ 完整："實作了使用者註冊，包含驗證、測試和文件"
⚠️ 不完整："新增了註冊表單，但後端驗證尚未完成"
❌ 未就緒："開始處理註冊功能，還有多個 TODO"

步驟 2：執行檢查清單

### 檢查清單結果

✅ 建置：npm run build 成功
✅ 程式碼品質：遵循專案標準
⚠️ 測試：單元測試通過，整合測試需要驗證
✅ 文件：已新增 JSDoc 註解
✅ 提交訊息：已按照 conventional commits 格式準備

步驟 3：提示使用者

## 請確認簽入

已完成：[簡短描述]

### 檢查清單結果
✅ 建置通過
✅ 測試通過
✅ 程式碼品質已驗證
✅ 文件已更新

建議的提交訊息：

feat(auth): 新增 OAuth2 Google 登入支援

• 實作 Google 提供者的 OAuth2 流程
• 新增使用者工作階段管理
• 包含 auth 服務的單元測試

Refs #123

是否繼續提交？

步驟 4：等待確認

AI 必須：

• ✅ 等待使用者明確同意
• ✅ 提供清晰的檢查清單摘要
• ✅ 允許使用者拒絕或要求修改

AI 不得：

• ❌ 自動執行

  git add

• ❌ 自動執行

  git commit

• ❌ 自動執行

  git push

常見違規

❌ WIP 提交

# 不好
git commit -m "WIP"
git commit -m "save work"

# 解決方案：使用 git stash
git stash save "WIP: 功能描述"

❌ 註解的程式碼

// 不好：提交被註解的舊程式碼
// const oldValue = calculate(x);
const newValue = calculateV2(x);

// 解決方案：刪除註解的程式碼，依賴 git 歷史
const newValue = calculateV2(x);

❌ 混合關注點

# 不好：一個提交包含多個不相關的變更
git commit -m "fix bug and refactor and add feature"

# 解決方案：分開提交
git commit -m "fix(module-a): 解決空指標問題"
git commit -m "refactor(module-b): 提取驗證邏輯"
git commit -m "feat(module-c): 新增 CSV 匯出"

目錄衛生

提交前，驗證沒有不需要的檔案：

# 檢查暫存區中的 IDE 產出物
git diff --cached --name-only | grep -E '\.idea|\.vs/|\.DS_Store'

# 檢查異常目錄
git ls-files | grep -E '^\$'

# 取消暫存不需要的檔案
git reset HEAD <file>

常見應排除的產出物

.idea/

.vs/

.DS_Store

Thumbs.db

配置偵測

偵測順序

1. 檢查

   CONTRIBUTING.md

   的「Disabled Skills」區段
2. 檢查

   CONTRIBUTING.md

   的「Check-in Standards」區段
3. 檢查 pre-commit hooks 配置
4. 如果都沒找到，使用標準檢查清單

首次設定

如果沒有找到配置：

1. 建議在

   CONTRIBUTING.md

   中記錄：

## 簽入標準

### 建置指令
```bash
npm run build

測試指令

npm test

品質指令

npm run lint

最低覆蓋率

• 行覆蓋率：80%
• 分支覆蓋率：75%

---

## 詳細指南

完整標準請參見：
- [簽入標準](../../core/checkin-standards.md)

---

## 相關標準

- [簽入標準](../../core/checkin-standards.md) - 核心標準
- [提交訊息指南](../../core/commit-message-guide.md) - 訊息格式
- [程式碼審查檢查清單](../../core/code-review-checklist.md) - PR 審查
- [程式碼審查助手](../code-review-assistant/SKILL.md) - 審查技能
- [提交標準技能](../commit-standards/SKILL.md) - 提交訊息技能

---

## 版本歷史

| 版本 | 日期 | 變更 |
|------|------|------|
| 1.0.0 | 2026-01-12 | 初始發布 |

---

## 授權

此技能以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權釋出。

**來源**：[universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)