universal-dev-standards 5.17.0 → 6.0.0

package/bundled/locales/zh-TW/docs/user/TROUBLESHOOTING.md

@@ -0,0 +1,190 @@
+---
+source: docs/user/TROUBLESHOOTING.md
+source_version: 1.0.0
+translation_version: 1.0.0
+status: current
+---
+
+# UDS 疑難排解指南
+
+> **語言**: [English](../../../../docs/user/TROUBLESHOOTING.md) | 繁體中文
+
+找到你的問題 → 照著修法做。
+
+---
+
+## 安裝問題
+
+**問題：`npm install -g` 之後出現 `uds: command not found`**
+
+```bash
+# 檢查 npm 全域 bin 是否在你的 PATH 中
+npm config get prefix
+# 在 ~/.zshrc 或 ~/.bashrc 把 <prefix>/bin 加入 PATH
+export PATH="$(npm config get prefix)/bin:$PATH"
+```
+
+**問題：`uds init` 因權限錯誤而失敗**
+
+```bash
+# 改用 Node 版本管理器（nvm/fnm），而非系統內建的 Node
+# 或修正 npm 全域目錄：https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
+```
+
+---
+
+## Claude Code 中未顯示 Skill
+
+**問題：我在 Claude Code 選單中看不到 `/sdd`、`/tdd` 或其他 UDS skill。**
+
+步驟 1 — 驗證 UDS 已初始化：
+```bash
+uds check
+```
+若回報檔案遺失，重新執行 `uds init`。
+
+步驟 2 — 驗證 `.claude/` 設定存在：
+```bash
+ls .claude/settings.json
+```
+若遺失，`uds init` 應會建立它。試試 `uds init --force`。
+
+步驟 3 — 可能超出 skill 預算（skill 太多 → 描述被截斷）：
+參閱 [skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)，將少用的 skill 降為 Tier 3。
+
+步驟 4 — 強制重新載入 Claude Code：
+關閉並重新開啟正在執行 Claude Code 的 IDE／終端機視窗。
+
+**問題：有些 skill 看得到，有些卻看不到。**
+
+這對 Tier 3 skill 而言是預期行為。Tier 3 skill 只顯示名稱（無描述）以節省 context 預算，而某些 AI 用戶端可能根本不列出它們。
+
+**Tier 3 skill 仍可直接呼叫**：輸入 `/<name>` 並按 Enter。
+
+若要讓某個 Tier 3 skill 顯示，加入你的 `.claude/settings.json`：
+```json
+{
+  "skillOverrides": {
+    "brainstorm-assistant": "on"
+  }
+}
+```
+
+---
+
+## Skill 行為不如預期
+
+**問題：Skill 有啟動，但給的是通用回應，而非 UDS 專屬的指引。**
+
+可能原因：`.standards/` 目錄為空或過時。
+```bash
+uds check       # 檢查安裝了什麼
+uds update      # 更新到最新標準
+```
+
+**問題：`/commit` 產生的 commit 訊息不符合 Conventional Commits。**
+
+commit-standards skill 會讀取你既有的 commit 來學習專案風格。若你先前沒有 Conventional Commits 格式的 commit，它可能會偏離。
+
+在 `CLAUDE.md` 加入明確指引：
+```markdown
+## Commit Format
+Always use Conventional Commits: `<type>(<scope>): <subject>`
+Types: feat, fix, docs, chore, test, refactor, style, build, ci
+```
+
+**問題：`/sdd` 建立了 spec，但我想要不同的格式。**
+
+在你的 `CLAUDE.md` 加入內容來自訂 spec 範本：
+```markdown
+## Spec Format
+When creating specs with /sdd, use this template:
+[paste your preferred template here]
+```
+
+---
+
+## 不使用 Claude Code 而使用 UDS
+
+**問題：我用的是 Cursor / GitHub Copilot / Windsurf——skill 無法運作。**
+
+Skill（`/command` 系統）為 Claude Code 專屬。對於其他 AI 工具：
+
+1. 執行 `uds init` 並選擇你的工具——它會設定 `.cursorrules`、`.github/copilot-instructions.md` 等
+2. `.standards/` 中的 Core Standards 與工具無關，能為任何讀取它們的 AI 提供 context
+3. 在你的 AI 指令檔中使用下方的快速參考表
+
+**可嵌入任何 AI 工具的快速參考：**
+
+```markdown
+## Commit Messages
+Format: <type>(<scope>): <subject>
+Types: feat, fix, docs, chore, test, refactor, style
+
+## Testing Pyramid
+Unit: 70% | Integration: 20% | System: 7% | E2E: 3%
+
+## User Stories
+As a [role], I want [feature], so that [benefit].
+INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable
+```
+
+**Skill → Core Standard 對照**（當 skill 無法使用時）：
+
+| Skill | 要參考的 Core Standard |
+|-------|------------------------|
+| `commit-standards` | `.standards/commit-message.md` |
+| `testing-guide` | `.standards/testing.md` |
+| `code-review-assistant` | `.standards/code-review.md` |
+| `requirement-assistant` | `.standards/requirement-engineering.md` |
+| `spec-driven-dev` | `.standards/spec-driven-development.md` |
+| `tdd-assistant` | `.standards/test-driven-development.md` |
+| `bdd-assistant` | `.standards/behavior-driven-development.md` |
+| `git-workflow-guide` | `.standards/git-workflow.md` |
+| `refactoring-assistant` | `.standards/refactoring-standards.md` |
+
+---
+
+## 更新問題
+
+**問題：`uds update` 失敗。**
+
+```bash
+# 檢查網路／npm registry 連線
+npm ping
+# 試試指定 registry
+npm install -g universal-dev-standards@latest
+# 然後重新初始化
+uds init --force
+```
+
+**問題：更新後，我的 skill 看起來壞掉了。**
+
+更新可能變更了 skill 格式。試試：
+```bash
+uds check
+uds init --force   # 重新安裝 skill 設定
+```
+
+---
+
+## 一般診斷
+
+執行 `uds check` 取得完整健康報告：
+```
+uds check
+```
+
+它會檢查：
+- 標準安裝狀態
+- Skill 設定
+- AI 工具相容性
+- 版本對齊
+
+---
+
+## 還是卡住？
+
+- **GitHub Issues**：[github.com/AsiaOstrich/universal-dev-standards/issues](https://github.com/AsiaOstrich/universal-dev-standards/issues)
+- **FAQ**：[FAQ.md](FAQ.md)
+- **Skill 預算調整**：[skill-budget-tuning.md](../../../../docs/skill-budget-tuning.md)

package/bundled/locales/zh-TW/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md

@@ -42,7 +42,7 @@ GitHub Copilot 不支援像 Claude Code 那樣的斜線命令。此參考提供
 
 ### 2. 程式碼審查
 
-**Claude Code**：`/review`
+**Claude Code**：`/code-review`
 
 **Copilot Chat 提示**：
 ```

package/bundled/locales/zh-TW/integrations/github-copilot/README.md

@@ -109,7 +109,7 @@ GitHub Copilot 相較於其他 AI 編程工具有一些限制：
 Claude Code: /commit
 Copilot:     "Generate a commit message following Conventional Commits..."
 
-Claude Code: /review
+Claude Code: /code-review
 Copilot:     "Review this code following the code review checklist..."
 
 Claude Code: /tdd

package/bundled/locales/zh-TW/integrations/github-copilot/skills-mapping.md

@@ -14,7 +14,7 @@ status: current
 
 ## 概述
 
-Claude Code 提供 25 個 skills 和 17 個斜線命令。GitHub Copilot 不支援斜線命令，但大部分功能可透過 Chat 提示和 `copilot-instructions.md` 檔案實現。
+Claude Code 提供 55 個 skills 和 51 個斜線命令。GitHub Copilot 不支援斜線命令，但大部分功能可透過 Chat 提示和 `copilot-instructions.md` 檔案實現。
 
 ---
 
@@ -63,7 +63,7 @@ Claude Code 提供 25 個 skills 和 17 個斜線命令。GitHub Copilot 不支
 | Claude Code | Copilot Chat 等效提示 |
 |-------------|----------------------|
 | `/commit` | "依照 Conventional Commits 格式產生 commit 訊息" |
-| `/review` | "依照程式碼審查檢查清單審查此程式碼" |
+| `/code-review` | "依照程式碼審查檢查清單審查此程式碼" |
 | `/tdd` | "使用 TDD（紅綠重構）幫我實作" |
 | `/coverage` | "使用 7 維度分析測試覆蓋" |
 | `/requirement` | "依照 INVEST 條件撰寫使用者故事" |
@@ -100,7 +100,7 @@ Claude Code 提供 25 個 skills 和 17 個斜線命令。GitHub Copilot 不支
    - Copilot：工作階段間無狀態追蹤
 
 3. **斜線命令**
-   - Claude Code：`/commit`、`/review` 等
+   - Claude Code：`/commit`、`/code-review` 等
    - Copilot：必須在 Chat 中輸入完整提示
 
 4. **MCP 工具整合**

package/bundled/locales/zh-TW/integrations/opencode/skills-mapping.md

@@ -14,7 +14,7 @@ status: current
 
 ## 概述
 
-Claude Code 提供 25 個技能和 17 個斜線指令。OpenCode 原生支援技能，且**完全相容** Claude Code 技能格式。
+Claude Code 提供 55 個技能和 51 個斜線指令。OpenCode 原生支援技能，且**完全相容** Claude Code 技能格式。
 
 ### 關鍵優勢：原生相容
 
@@ -74,7 +74,7 @@ OpenCode 支援與 Claude Code 相同的技能調用語法：
 | Claude Code | OpenCode | 備註 |
 |-------------|----------|------|
 | `/commit` | `/commit` 或 `skill("commit-standards")` | 相同 |
-| `/review` | `/review` 或 `skill("code-review-assistant")` | 相同 |
+| `/code-review` | `/code-review` 或 `skill("code-review-assistant")` | 相同 |
 | `/tdd` | `/tdd` 或 `skill("tdd-assistant")` | 相同 |
 | `/coverage` | `/coverage` 或 `skill("test-coverage-assistant")` | 相同 |
 | `/requirement` | `/requirement` 或 `skill("requirement-assistant")` | 相同 |
@@ -195,7 +195,7 @@ OpenCode 沒有像 Claude Code 那樣的官方 marketplace，但有幾個社群
 |------|-------------|----------|
 | 技能格式 | YAML frontmatter + Markdown | ✅ 相同 |
 | 技能搜索路徑 | `.claude/skills/` | ✅ + `.opencode/skill/` |
-| 斜線指令 | `/commit`、`/review` 等 | ✅ 相同 |
+| 斜線指令 | `/commit`、`/code-review` 等 | ✅ 相同 |
 | 自動觸發 | 基於關鍵字 | ✅ 相同 |
 | 技能權限 | 按技能設定 | ✅ 相同 |