--- source: skills/claude-code/checkin-assistant/SKILL.md source_version: 1.0.0 translation_version: 1.0.0 last_synced: 2026-01-12 status: current name: checkin-assistant description: | 引導提交前品质关卡和簽入工作流程。 使用时机：提交程序码、准备提交、品质关卡验证。 关鍵字：commit, checkin, pre-commit, quality gate, git add, 提交, 簽入, 品质关卡. --- # 簽入助手 > **语言**：[English](../../../../../skills/claude-code/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 ``` ### 常見应排除的产出物 | 模式 | 來源 | 处理方式 | |------|------|----------| | `.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)