--- source: skills/checkin-assistant/SKILL.md source_version: 1.0.0 translation_version: 1.0.0 last_synced: 2026-01-12 status: current name: checkin 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 ``` ### 常見應排除的產出物 | 模式 | 來源 | 處理方式 | |------|------|----------| | `.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)