universal-dev-standards 3.5.1-beta.1 → 3.5.1-beta.11

package/bundled/locales/zh-TW/skills/claude-code/checkin-assistant/SKILL.md

@@ -0,0 +1,407 @@
+---
+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 <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)

package/bundled/locales/zh-TW/skills/claude-code/code-review-assistant/SKILL.md

@@ -0,0 +1,154 @@
+---
+source: skills/claude-code/code-review-assistant/SKILL.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2025-12-25
+status: current
+name: code-review-assistant
+description: |
+  系統化的程式碼審查檢查清單和提交前品質關卡。
+  使用時機：審查 pull request、檢查程式碼品質、提交程式碼前。
+  關鍵字：review, PR, pull request, checklist, quality, commit, 審查, 檢查, 簽入。
+---
+
+# 程式碼審查助理
+
+> **語言**: [English](../../../../../skills/claude-code/code-review-assistant/SKILL.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2025-12-24
+**適用範圍**: Claude Code Skills
+
+---
+
+## 目的
+
+此技能提供系統化的程式碼審查和提交前驗證檢查清單。
+
+## 快速參考
+
+### 註解前綴
+
+| 前綴 | 意義 | 需要採取的行動 |
+|--------|---------|------------------|
+| **❗ BLOCKING** | 合併前必須修正 | 🔴 必要 |
+| **⚠️ IMPORTANT** | 應該修正，但不阻擋合併 | 🟡 建議 |
+| **💡 SUGGESTION** | 可改進之處 | 🟢 選擇性 |
+| **❓ QUESTION** | 需要釐清 | 🔵 討論 |
+| **📝 NOTE** | 資訊性質，無需行動 | ⚪ 資訊 |
+
+### 審查檢查清單類別
+
+1. **功能性** - 是否正常運作？
+2. **設計** - 架構是否正確？
+3. **品質** - 程式碼是否乾淨？
+4. **可讀性** - 是否容易理解？
+5. **測試** - 涵蓋率是否足夠？
+6. **安全性** - 是否有漏洞？
+7. **效能** - 是否高效？
+8. **錯誤處理** - 是否妥善處理？
+9. **文件** - 是否更新？
+10. **依賴項** - 是否必要？
+
+### 提交前檢查清單
+
+- [ ] 建置成功（零錯誤、零警告）
+- [ ] 所有測試通過
+- [ ] 程式碼符合專案標準
+- [ ] 無安全漏洞
+- [ ] 文件已更新
+- [ ] 分支已與目標同步
+
+## 詳細指南
+
+完整標準請參閱：
+- [審查檢查清單](./review-checklist.md)
+- [提交前檢查清單](./checkin-checklist.md)
+
+## 審查註解範例
+
+```markdown
+❗ BLOCKING: 此處有潛在的 SQL injection 漏洞。
+請使用參數化查詢而非字串串接。
+
+⚠️ IMPORTANT: 此方法做太多事情了（120 行）。
+考慮將驗證邏輯提取到獨立方法。
+
+💡 SUGGESTION: 考慮在此使用 Map 而非陣列以達到 O(1) 查找。
+
+❓ QUESTION: 為什麼這裡使用 setTimeout 而不是 async/await？
+
+📝 NOTE: 這是個聰明的解決方案！很好地運用了 reduce。
+```
+
+## 核心原則
+
+1. **保持尊重** - 審查程式碼，而非審查人
+2. **保持徹底** - 檢查功能性，而非僅檢查語法
+3. **保持及時** - 在 24 小時內完成審查
+4. **保持清晰** - 解釋「為什麼」，而非僅「是什麼」
+
+---
+
+## 配置偵測
+
+此技能支援專案特定配置。
+
+### 偵測順序
+
+1. 檢查 `CONTRIBUTING.md` 的「Disabled Skills」區段
+   - 如果此技能被列出，則在此專案中停用
+2. 檢查 `CONTRIBUTING.md` 的「Code Review Language」區段
+3. 若未找到，**預設使用英文**
+
+### 首次設定
+
+如果未找到配置且情境不明確：
+
+1. 詢問使用者：「此專案尚未配置程式碼審查語言。您想使用哪個選項？（English / 中文）」
+2. 使用者選擇後，建議在 `CONTRIBUTING.md` 中記錄：
+
+```markdown
+## Code Review Language
+
+This project uses **[chosen option]** for code review comments.
+<!-- Options: English | 中文 -->
+```
+
+### 配置範例
+
+在專案的 `CONTRIBUTING.md` 中：
+
+```markdown
+## Code Review Language
+
+This project uses **English** for code review comments.
+<!-- Options: English | 中文 -->
+
+### Comment Prefixes
+BLOCKING, IMPORTANT, SUGGESTION, QUESTION, NOTE
+```
+
+---
+
+## 相關標準
+
+- [Code Review Checklist](../../core/code-review-checklist.md)
+- [Checkin Standards](../../core/checkin-standards.md)
+- [Testing Standards](../../core/testing-standards.md)
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更內容 |
+|---------|------|---------|
+| 1.0.0 | 2025-12-24 | 新增：標準區段（目的、相關標準、版本歷史、授權） |
+
+---
+
+## 授權
+
+此技能依據 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權釋出。
+
+**來源**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)