universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/locales/zh-TW/skills/project-discovery/workflow.md

@@ -0,0 +1,574 @@
+---
+source: ../../../../skills/project-discovery/workflow.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-02-09
+status: current
+---
+
+# 專案現況評估工作流程指南
+
+> **語言**: [English](../../../../skills/project-discovery/workflow.md) | 繁體中文
+
+**版本**: 1.0.0
+**最後更新**: 2026-02-09
+
+---
+
+## 概覽
+
+本指南提供 Phase 0 現況評估工作流程每個步驟的詳細執行說明。請搭配[專案現況評估技能](./SKILL.md)使用。
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                Phase 0：現況評估流程                               │
+│                                                                  │
+│  輸入：既有程式碼 + 預計功能區域                                  │
+│                                                                  │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
+│  │ 0.1 程碼 │→│ 0.2 架構 │→│ 0.3 文件 │                       │
+│  │  健康度   │  │  審查    │  │  盤點    │                       │
+│  └──────────┘  └──────────┘  └──────────┘                      │
+│       │              │              │                             │
+│       ▼              ▼              ▼                             │
+│  ┌──────────┐  ┌──────────┐  ┌──────────┐                      │
+│  │ 0.4 程碼 │→│ 0.5 依賴 │→│ 0.6 影響 │                      │
+│  │  審查    │  │  安全    │  │  範圍    │                       │
+│  └──────────┘  └──────────┘  └──────────┘                      │
+│       │              │              │                             │
+│       └──────────────┴──────────────┘                            │
+│                      │                                           │
+│                      ▼                                           │
+│              現況評估報告                                         │
+│          （通過 / 不通過 / 有條件通過）                           │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 步驟 0.1：程式碼健康度檢查
+
+### 目標
+
+建立程式碼目前品質的量化基準。
+
+### 程序
+
+#### 0.1.1 執行測試套件
+
+```bash
+# 範例指令（依據你的專案調整）
+npm test                    # Node.js
+pytest --cov               # Python
+dotnet test                # .NET
+./gradlew test             # Java/Kotlin
+```
+
+記錄：
+- 測試總數、通過、失敗、跳過
+- 覆蓋率百分比（行覆蓋、分支覆蓋若有的話）
+- 執行時間
+
+#### 0.1.2 執行 Linter
+
+```bash
+# 範例指令
+npm run lint               # ESLint
+flake8 .                   # Python
+dotnet format --verify-no-changes  # .NET
+```
+
+記錄：
+- 錯誤數
+- 警告數
+- 最常違反的規則
+
+#### 0.1.3 識別程式碼異味
+
+尋找：
+- 超過 50 行的函式
+- 超過 500 行的檔案
+- 巢狀深度 > 4 層
+- 重複的程式碼區塊
+- 神級類別 / 職責過多的模組
+
+#### 0.1.4 檢查死碼
+
+- 未使用的匯出
+- 不可達的程式碼路徑
+- 被註解掉的程式碼區塊
+- 仍存在的已棄用函式
+
+### 輸出範本
+
+```markdown
+### 步驟 0.1 結果：程式碼健康度
+
+| 指標 | 值 | 門檻 | 狀態 |
+|------|-----|------|------|
+| 測試通過 | X/Y | 100% | ✅/⚠️/❌ |
+| 測試覆蓋率 | X% | ≥ 60% | ✅/⚠️/❌ |
+| Lint 錯誤 | X | 0 | ✅/⚠️/❌ |
+| Lint 警告 | X | < 20 | ✅/⚠️/❌ |
+| 主要程式碼異味 | X | < 5 | ✅/⚠️/❌ |
+| 死碼檔案 | X | 0 | ✅/⚠️/❌ |
+
+**健康度分數**: [良好 / 需要關注 / 嚴重]
+```
+
+### 品質閘門
+
+| 條件 | 行動 |
+|------|------|
+| 測試通過率 < 70% | ❌ 標記為高風險。建議先修復測試。 |
+| 覆蓋率 < 30% | ⚠️ 建議在新增功能前先補測試。 |
+| 嚴重的 lint 錯誤 | ⚠️ 繼續前先處理。 |
+
+### 引用規範
+
+- [測試標準](../../core/testing-standards.md) — 覆蓋率目標、測試金字塔
+- [反向工程標準](../../core/reverse-engineering-standards.md) — 程式碼掃描方法論
+
+---
+
+## 步驟 0.2：架構理解
+
+### 目標
+
+繪製系統結構、識別模式並評估可維護性。
+
+### 程序
+
+#### 0.2.1 識別進入點
+
+- 主應用程式檔案（如 `index.ts`、`main.py`、`Program.cs`）
+- API 路由定義
+- 事件處理器 / 訊息消費者
+- 排程任務 / cron 任務
+- CLI 進入點
+
+#### 0.2.2 繪製模組依賴
+
+追蹤依賴圖：
+```
+進入點 → 路由 → 控制器 → 服務 → 儲存庫 → 資料庫
+                              → 外部 API
+                              → 訊息佇列
+```
+
+尋找：
+- 循環依賴
+- 過度廣泛的匯入
+- 不相關模組之間的緊耦合
+
+#### 0.2.3 識別架構模式
+
+| 模式 | 指標 |
+|------|------|
+| MVC | controllers/、models/、views/ 目錄 |
+| DDD | domain/、application/、infrastructure/ 目錄 |
+| 微服務 | 多個服務目錄、API 閘道 |
+| 單體式 | 單一大型應用程式目錄 |
+| 六角形架構 | ports/、adapters/ 目錄 |
+| 事件驅動 | 事件處理器、訊息佇列、發布/訂閱 |
+
+#### 0.2.4 評估 AI 友善度
+
+對照 [AI 友善架構](../../core/ai-friendly-architecture.md) 檢查：
+- 模組邊界清晰嗎？
+- 專案結構可發現嗎？
+- 命名慣例一致嗎？
+- 介面有文件化嗎？
+
+### 輸出範本
+
+```markdown
+### 步驟 0.2 結果：架構
+
+**已識別模式**: [模式名稱] [Confirmed/Inferred]
+**模組數**: X 個模組橫跨 Y 個套件
+**進入點**: [清單]
+
+#### 依賴概覽
+[簡化依賴圖]
+
+#### 問題
+- [Confirmed/Inferred] [描述附來源：file:line]
+
+#### AI 友善度分數
+| 維度 | 評分 | 備註 |
+|------|------|------|
+| 可發現性 | ✅/⚠️/❌ | ... |
+| 模組邊界 | ✅/⚠️/❌ | ... |
+| 命名一致性 | ✅/⚠️/❌ | ... |
+| 介面清晰度 | ✅/⚠️/❌ | ... |
+```
+
+### 品質閘門
+
+| 條件 | 行動 |
+|------|------|
+| 無清晰模組邊界 | ⚠️ 建議制定架構重構計畫。 |
+| 循環依賴 | ⚠️ 記錄並規劃解決方案。 |
+| 無法辨識模式 | 標記為 [Unknown] — 需要利害關係人確認。 |
+
+### 引用規範
+
+- [AI 友善架構](../../core/ai-friendly-architecture.md)
+- [反向工程標準](../../core/reverse-engineering-standards.md)
+
+---
+
+## 步驟 0.3：文件盤點
+
+### 目標
+
+評估現有文件、其完整性和新鮮度。
+
+### 程序
+
+#### 0.3.1 檢查標準文件
+
+| 文件 | 檢查項目 |
+|------|----------|
+| README.md | 存在？安裝說明？是否最新？ |
+| CONTRIBUTING.md | 存在？涵蓋工作流程？ |
+| CHANGELOG.md | 存在？格式？最後一筆？ |
+| LICENSE | 存在？正確？ |
+| API 文件 | 存在？自動生成？是否最新？ |
+| ADR（架構決策記錄） | 存在？有組織？ |
+
+#### 0.3.2 評估內嵌文件
+
+- 函式/方法 JSDoc/docstring 覆蓋率
+- 模組級文件
+- 複雜演算法說明
+- TODO/FIXME/HACK 註解數量
+
+#### 0.3.3 評估文件新鮮度
+
+比較文件日期與近期程式碼變更：
+- 如果文件超過 6 個月未更新但程式碼有重大變更 → 過期
+- 如果文件引用已移除的功能或舊 API → 已過時
+
+### 輸出範本
+
+```markdown
+### 步驟 0.3 結果：文件
+
+| 文件 | 存在 | 最後更新 | 狀態 |
+|------|------|----------|------|
+| README.md | ✅/❌ | YYYY-MM-DD | ✅ 最新 / ⚠️ 過期 / ❌ 遺失 |
+| CONTRIBUTING.md | ✅/❌ | ... | ... |
+| CHANGELOG.md | ✅/❌ | ... | ... |
+| API 文件 | ✅/❌ | ... | ... |
+| ADR | ✅/❌ | ... | ... |
+| 內嵌文件 | ⚠️ 部分 | ... | ... |
+
+**文件分數**: [良好 / 需要關注 / 嚴重]
+**TODO/FIXME 數量**: X
+```
+
+### 品質閘門
+
+| 條件 | 行動 |
+|------|------|
+| 無 README | ❌ 繼續前先建立 README。 |
+| 文件嚴重過期（> 1 年） | ⚠️ 標記為文件債。 |
+| 無 CHANGELOG | ⚠️ 建議新增變更日誌追蹤。 |
+
+### 引用規範
+
+- [文件結構](../../core/documentation-structure.md)
+- [變更日誌標準](../../core/changelog-standards.md)
+
+---
+
+## 步驟 0.4：程式碼審查快照
+
+### 目標
+
+對最關鍵的程式碼路徑進行定向品質稽核。
+
+### 程序
+
+#### 0.4.1 識別關鍵路徑
+
+根據以下條件選擇 3-5 條路徑：
+- 業務關鍵度（認證、支付、資料存取）
+- 複雜度（最複雜的模組）
+- 變更頻率（最常修改的檔案）
+- 與計畫功能開發的相關性
+
+#### 0.4.2 套用程式碼審查清單
+
+對每條關鍵路徑評估：
+
+| 類別 | 檢查項目 |
+|------|----------|
+| 功能 | 運作正確嗎？邊界情況已處理？ |
+| 安全性 | 輸入驗證？SQL 注入？XSS？認證檢查？ |
+| 錯誤處理 | try/catch？優雅降級？錯誤日誌？ |
+| 可讀性 | 命名清晰？函式長度合理？ |
+| 效能 | 明顯瓶頸？N+1 查詢？記憶體洩漏？ |
+
+#### 0.4.3 套用反幻覺標籤
+
+**重要**：只報告你實際讀過的內容。
+
+- `[Confirmed]` — 從程式碼中直接驗證
+- `[Inferred]` — 從模式進行邏輯推斷
+- `[Unknown]` — 未驗證，需要調查
+
+### 輸出範本
+
+```markdown
+### 步驟 0.4 結果：程式碼審查快照
+
+#### 關鍵路徑 1：[名稱]
+[Confirmed] 已審查：[檔案清單附行號範圍]
+
+| 面向 | 評分 | 備註 |
+|------|------|------|
+| 功能 | ✅/⚠️/❌ | ... |
+| 安全性 | ✅/⚠️/❌ | ... |
+| 錯誤處理 | ✅/⚠️/❌ | ... |
+| 可讀性 | ✅/⚠️/❌ | ... |
+| 效能 | ✅/⚠️/❌ | ... |
+
+**發現**: [附確定性標籤的清單]
+```
+
+### 品質閘門
+
+| 條件 | 行動 |
+|------|------|
+| 發現安全漏洞 | ❌ 必須在新增功能前修復。 |
+| 關鍵錯誤處理缺口 | ⚠️ 繼續前先處理。 |
+
+### 引用規範
+
+- [反幻覺指南](../../core/anti-hallucination.md)
+- [程式碼審查清單](../../core/code-review-checklist.md)
+
+---
+
+## 步驟 0.5：依賴與安全檢查
+
+### 目標
+
+識別有漏洞、過期或不必要的依賴。
+
+### 程序
+
+#### 0.5.1 執行安全稽核
+
+```bash
+# Node.js
+npm audit
+
+# Python
+pip-audit
+safety check
+
+# .NET
+dotnet list package --vulnerable
+
+# Go
+govulncheck ./...
+```
+
+#### 0.5.2 檢查過期套件
+
+```bash
+# Node.js
+npm outdated
+
+# Python
+pip list --outdated
+
+# .NET
+dotnet list package --outdated
+```
+
+#### 0.5.3 識別未使用依賴
+
+```bash
+# Node.js
+npx depcheck
+
+# Python
+pip-extra-reqs --requirements-file=requirements.txt .
+```
+
+#### 0.5.4 評估授權合規
+
+檢查依賴樹中是否有不相容的授權。
+
+### 輸出範本
+
+```markdown
+### 步驟 0.5 結果：依賴
+
+| 類別 | 數量 | 詳情 |
+|------|------|------|
+| 嚴重漏洞 | X | [列出 CVE 編號] |
+| 高風險漏洞 | X | ... |
+| 過期（主要版本） | X | ... |
+| 過期（次要/修補） | X | ... |
+| 未使用依賴 | X | [列出套件名稱] |
+| 授權疑慮 | X | ... |
+
+**安全分數**: [良好 / 需要關注 / 嚴重]
+```
+
+### 品質閘門
+
+| 條件 | 行動 |
+|------|------|
+| 嚴重 CVE | ❌ 必須在新增功能前修補。 |
+| > 5 個高風險漏洞 | ⚠️ 規劃修復衝刺。 |
+| 未使用依賴 | ℹ️ 清理以降低攻擊面。 |
+
+### 引用規範
+
+- [安全標準](../../../../core/security-standards.md)
+- [簽入標準](../../core/checkin-standards.md)
+
+---
+
+## 步驟 0.6：影響範圍分析
+
+### 目標
+
+繪製提議變更在系統中的傳播方式並評估風險。
+
+### 程序
+
+#### 0.6.1 定義變更目標
+
+明確陳述：
+- 要修改什麼功能區域？
+- 會直接觸及哪些模組？
+- 預期的變更類型是什麼（新增、修改、重構）？
+
+#### 0.6.2 追蹤依賴
+
+對每個直接修改的模組：
+1. 列出匯入/依賴它的模組
+2. 列出它匯入/依賴的模組
+3. 統計總影響模組數（直接 + 間接）
+
+#### 0.6.3 建構風險矩陣
+
+| 風險 | 可能性 | 影響 | 緩解措施 |
+|------|--------|------|----------|
+| [描述] | 低/中/高 | 低/中/高/嚴重 | [行動] |
+
+可能性因素：
+- 受影響區域的程式碼複雜度
+- 受影響區域的測試覆蓋率
+- 觸及的模組數量
+
+影響因素：
+- 受影響功能的業務關鍵度
+- 面向使用者 vs. 內部
+- 資料完整性影響
+
+#### 0.6.4 決定判定
+
+| 爆炸半徑 | 建議 |
+|----------|------|
+| < 10% 模組 | ✅ 通過 — 低風險，正常進行 |
+| 10-30% 模組 | ⚠️ 有條件通過 — 先新增整合測試 |
+| > 30% 模組 | ❌ 不通過 — 拆分為較小的變更 |
+
+### 輸出範本
+
+```markdown
+### 步驟 0.6 結果：影響範圍
+
+**變更目標**: [功能/模組名稱]
+**爆炸半徑**: X 個模組直接，Y 個間接（佔總數的 Z%）
+
+#### 風險矩陣
+
+| 風險 | 可能性 | 影響 | 緩解措施 |
+|------|--------|------|----------|
+| ... | ... | ... | ... |
+
+**判定**: [通過 / 有條件通過 / 不通過]
+**理由**: [1-2 句]
+```
+
+### 引用規範
+
+- [需求工程](../../../../core/requirement-engineering.md)
+
+---
+
+## 彙整現況評估報告
+
+完成全部 6 個步驟後，將發現合併為單一報告。
+
+### 報告結構
+
+```markdown
+# 現況評估報告：[專案名稱]
+
+**日期**: YYYY-MM-DD
+**評估者**: [AI 助手 / 開發者姓名]
+**範圍**: [功能區域或完整專案]
+
+## 執行摘要
+[2-3 句：整體健康度、主要風險、建議]
+
+## 判定：[通過 / 不通過 / 有條件通過]
+
+## 分數摘要
+
+| 區域 | 分數 | 嚴重問題數 |
+|------|------|-----------|
+| 程式碼健康度 (0.1) | ✅/⚠️/❌ | X |
+| 架構 (0.2) | ✅/⚠️/❌ | X |
+| 文件 (0.3) | ✅/⚠️/❌ | X |
+| 程式碼品質 (0.4) | ✅/⚠️/❌ | X |
+| 依賴 (0.5) | ✅/⚠️/❌ | X |
+| 影響範圍 (0.6) | ✅/⚠️/❌ | X |
+
+## 阻塞項目
+[列出繼續前必須解決的項目]
+
+## 建議
+[按優先順序排列]
+
+## 後續步驟
+- [ ] 處理阻塞項目
+- [ ] /reverse — 若舊程式碼需要 SDD 規格
+- [ ] /sdd — 為新功能撰寫規格
+- [ ] 開始實作
+```
+
+### 判定決策矩陣
+
+| 阻塞項目 | 高風險 | 判定 |
+|----------|--------|------|
+| 0 | 0-2 | ✅ 通過 |
+| 0 | 3+ | ⚠️ 有條件通過 — 先處理風險 |
+| 1+ | 任意 | ❌ 不通過 — 解決阻塞項目 |
+
+---
+
+## 版本歷史
+
+| 版本 | 日期 | 變更 |
+|------|------|------|
+| 1.0.0 | 2026-02-09 | 初始發布 |
+
+---
+
+## 授權
+
+本指南採用 [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/project-structure-guide → project-structure-guide}/SKILL.md

@@ -1,5 +1,5 @@
 ---
-source: ../../../../../skills/claude-code/project-structure-guide/SKILL.md
+source: ../../../../skills/project-structure-guide/SKILL.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2025-12-30
@@ -8,7 +8,7 @@ status: current
 
 # 專案結構指南
 
-> **Language**: [English](../../../../../skills/claude-code/project-structure-guide/SKILL.md) | 繁體中文
+> **Language**: [English](../../../../skills/project-structure-guide/SKILL.md) | 繁體中文
 
 **版本**：1.0.0
 **最後更新**：2025-12-30
@@ -139,5 +139,5 @@ project/
 
 ## 相關標準
 
-- [核心：專案結構](../../../core/project-structure.md)
-- [AI：專案結構選項](../../../ai/options/project-structure/)
+- [核心：專案結構](../../core/project-structure.md)
+- [AI：專案結構選項](../../../../options/project-structure/)

package/bundled/locales/zh-TW/skills/{claude-code/project-structure-guide → project-structure-guide}/language-patterns.md

@@ -1,5 +1,5 @@
 ---
-source: ../../../../../skills/claude-code/project-structure-guide/language-patterns.md
+source: ../../../../skills/project-structure-guide/language-patterns.md
 source_version: 1.0.0
 translation_version: 1.0.0
 last_synced: 2025-12-30

package/bundled/locales/zh-TW/skills/refactoring-assistant/SKILL.md

@@ -0,0 +1,67 @@
+---
+source: ../../../../skills/refactoring-assistant/SKILL.md
+source_version: 2.0.0
+translation_version: 2.0.0
+last_synced: 2026-02-10
+status: current
+description: |
+  引導重構決策、推薦策略，並提供逐步執行工作流程。
+  使用時機：重構程式碼、評估重構 vs 重寫、處理遺留程式碼。
+  關鍵字：refactor, strategy, legacy, technical debt, 重構, 策略, 遺留程式碼, 技術債。
+---
+
+# 重構助手
+
+> **語言**: [English](../../../../skills/refactoring-assistant/SKILL.md) | 繁體中文
+
+引導重構決策、推薦策略，並提供逐步執行工作流程。
+
+## 使用方式
+
+| 命令 | 用途 |
+|------|------|
+| `/refactor` | 啟動互動式重構引導 |
+| `/refactor decide` | 執行重構 vs 重寫決策樹 |
+| `/refactor tactical` | 建議戰術性（日常）策略 |
+| `/refactor strategic` | 引導戰略性/架構重構 |
+| `/refactor legacy` | 遺留程式碼安全策略 |
+| `/refactor debt` | 技術債評估 |
+
+## 策略快速參考
+
+### 戰術性策略（日常）
+
+| 策略 | 使用時機 |
+|------|---------|
+| **準備式重構** | 新增被阻擋的功能之前 |
+| **童子軍法則** | 任何維護工作中 |
+| **紅-綠-重構** | TDD 開發循環 |
+
+### 戰略性策略（架構）
+
+| 策略 | 使用時機 |
+|------|---------|
+| **絞殺者無花果** | 逐步替換整個系統 |
+| **防腐層** | 與遺留系統整合 |
+| **抽象分支** | 在主幹上重構共享程式碼 |
+
+### 安全防護策略（遺留程式碼）
+
+| 策略 | 使用時機 |
+|------|---------|
+| **特徵化測試** | 任何遺留程式碼重構之前 |
+| **草稿式重構** | 理解黑盒程式碼 |
+| **尋找接縫** | 在遺留程式碼中注入測試替身 |
+
+## 工作流程
+
+1. **評估** - 識別要重構的程式碼，評估測試覆蓋率
+2. **決策** - 需要時執行決策樹（重構 vs 重寫）
+3. **選擇策略** - 根據範圍和風險選擇適當策略
+4. **執行** - 遵循逐步工作流程，包含安全檢查
+5. **驗證** - 執行測試以確認行為未被改變
+
+## 參考
+
+- 詳細指南：[guide.md](./guide.md)
+- 核心規範：[refactoring-standards.md](../../../../core/refactoring-standards.md)

package/bundled/locales/zh-TW/skills/{claude-code/refactoring-assistant/SKILL.md → refactoring-assistant/guide.md}

@@ -1,10 +1,9 @@
 ---
-source: skills/claude-code/refactoring-assistant/SKILL.md
+source: ../../../../skills/refactoring-assistant/SKILL.md
 source_version: 2.0.0
 translation_version: 2.0.0
 last_synced: 2026-01-21
 status: current
-name: refactoring-assistant
 description: |
   引導重構決策和大規模程式碼改進。
   使用時機：重構程式碼、遺留系統現代化、技術債、重寫決策。
@@ -13,7 +12,7 @@ description: |
 
 # 重構助手
 
-> **語言**: [English](../../../../../skills/claude-code/refactoring-assistant/SKILL.md) | 繁體中文
+> **語言**: [English](../../../../skills/refactoring-assistant/SKILL.md) | 繁體中文
 
 **版本**: 2.0.0
 **最後更新**: 2026-01-21
@@ -278,16 +277,16 @@ selection_guide:
 ## 詳細指南
 
 完整標準請參閱：
-- [重構標準](../../../core/refactoring-standards.md)
+- [重構標準](../../core/refactoring-standards.md)
 
 ---
 
 ## 相關標準
 
-- [重構標準](../../../core/refactoring-standards.md) - 核心標準
-- [測試驅動開發](../../../core/test-driven-development.md) - TDD 重構階段
-- [程式碼審查檢查清單](../../../core/code-review-checklist.md) - 重構 PR 審查
-- [簽入標準](../../../core/checkin-standards.md) - 提交前要求
+- [重構標準](../../core/refactoring-standards.md) - 核心標準
+- [測試驅動開發](../../core/test-driven-development.md) - TDD 重構階段
+- [程式碼審查檢查清單](../../core/code-review-checklist.md) - 重構 PR 審查
+- [簽入標準](../../core/checkin-standards.md) - 提交前要求
 - [TDD 助手](../tdd-assistant/SKILL.md) - TDD 工作流程
 
 ---