簽入助手

语言：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)