---
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)
