---
source: ../../../../skills/checkin-assistant/SKILL.md
source_version: 1.0.0
translation_version: 1.0.0
last_synced: 2026-01-12
status: current
description: |
  引導提交前品質關卡和簽入工作流程。
  使用時機：提交程式碼、準備提交、品質關卡驗證。
  關鍵字：commit, checkin, pre-commit, quality gate, git add, 提交, 簽入, 品質關卡.
---

# 簽入助手

> **語言**：[English](../../../../skills/checkin-assistant/SKILL.md) | 繁體中文

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

---

## 目的

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

**注意**：此技能專注於**何時以及如何提交**。有關 PR 期間的程式碼審查，請參閱[程式碼審查助手](../code-review-assistant/SKILL.md)。

---

## 快速參考（YAML 壓縮格式）

```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                             │
│  □ 已與目標分支同步（無衝突）                                    │
└─────────────────────────────────────────────────────────────────┘
```

---

## 簽入觸發點

### 何時提示提交

| 觸發條件 | 狀況 | 提醒強度 |
|---------|------|----------|
| 階段完成 | 完成一個開發階段 | 建議 |
| 檢查點 | 達到定義的檢查點 | 建議 |
| 變更累積 | 檔案 ≥5 或行數 ≥200 | 建議 |
| 連續跳過 | 連續跳過提交 3 次 | 警告 |
| 工作完成 | 完成前有未提交的變更 | 強烈建議 |

### 提醒格式

```
┌────────────────────────────────────────────────┐
│ 🔔 簽入檢查點                                   │
├────────────────────────────────────────────────┤
│ 階段 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：提示使用者

```markdown
## 請確認簽入

已完成：[簡短描述]

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

建議的提交訊息：
```
feat(auth): 新增 OAuth2 Google 登入支援

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

Refs #123
```

是否繼續提交？
```

### 步驟 4：等待確認

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

**AI 不得**：
- ❌ 自動執行 `git add`
- ❌ 自動執行 `git commit`
- ❌ 自動執行 `git push`

---

## 常見違規

### ❌ WIP 提交

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

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

### ❌ 註解的程式碼

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

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

### ❌ 混合關注點

```bash
# 不好：一個提交包含多個不相關的變更
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 匯出"
```

---

## 目錄衛生

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

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

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

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

### 常見應排除的產出物

| 模式 | 來源 | 處理方式 |
|------|------|----------|
| `.idea/` | JetBrains | gitignore |
| `.vs/` | Visual Studio | gitignore |
| `.DS_Store` | macOS | gitignore |
| `Thumbs.db` | Windows | gitignore |

---

## 配置偵測

### 偵測順序

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

### 首次設定

如果沒有找到配置：

1. 建議在 `CONTRIBUTING.md` 中記錄：

```markdown
## 簽入標準

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

### 測試指令
```bash
npm test
```

### 品質指令
```bash
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)
