universal-dev-standards 4.0.0 → 4.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/bin/uds.js +75 -0
  2. package/bundled/core/ai-friendly-architecture.md +542 -0
  3. package/bundled/core/refactoring-standards.md +342 -120
  4. package/bundled/locales/zh-CN/README.md +210 -509
  5. package/bundled/locales/zh-CN/core/ai-friendly-architecture.md +306 -0
  6. package/bundled/locales/zh-CN/core/refactoring-standards.md +10 -9
  7. package/bundled/locales/zh-CN/docs/AI-AGENT-ROADMAP.md +82 -22
  8. package/bundled/locales/zh-CN/integrations/gemini-cli/GEMINI.md +35 -3
  9. package/bundled/locales/zh-CN/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +89 -3
  10. package/bundled/locales/zh-CN/integrations/github-copilot/skills-mapping.md +8 -4
  11. package/bundled/locales/zh-CN/skills/claude-code/commands/refactor.md +178 -0
  12. package/bundled/locales/zh-CN/skills/claude-code/refactoring-assistant/SKILL.md +243 -97
  13. package/bundled/locales/zh-TW/README.md +211 -490
  14. package/bundled/locales/zh-TW/core/ai-friendly-architecture.md +306 -0
  15. package/bundled/locales/zh-TW/core/refactoring-standards.md +347 -125
  16. package/bundled/locales/zh-TW/docs/AI-AGENT-ROADMAP.md +82 -22
  17. package/bundled/locales/zh-TW/integrations/gemini-cli/GEMINI.md +35 -3
  18. package/bundled/locales/zh-TW/integrations/github-copilot/COPILOT-CHAT-REFERENCE.md +89 -3
  19. package/bundled/locales/zh-TW/integrations/github-copilot/skills-mapping.md +8 -4
  20. package/bundled/locales/zh-TW/skills/claude-code/commands/refactor.md +178 -0
  21. package/bundled/locales/zh-TW/skills/claude-code/refactoring-assistant/SKILL.md +198 -52
  22. package/bundled/skills/claude-code/README.md +8 -0
  23. package/bundled/skills/claude-code/agents/README.md +305 -0
  24. package/bundled/skills/claude-code/agents/code-architect.md +259 -0
  25. package/bundled/skills/claude-code/agents/doc-writer.md +406 -0
  26. package/bundled/skills/claude-code/agents/reviewer.md +353 -0
  27. package/bundled/skills/claude-code/agents/spec-analyst.md +374 -0
  28. package/bundled/skills/claude-code/agents/test-specialist.md +364 -0
  29. package/bundled/skills/claude-code/commands/refactor.md +173 -0
  30. package/bundled/skills/claude-code/refactoring-assistant/SKILL.md +161 -63
  31. package/bundled/skills/claude-code/workflows/README.md +303 -0
  32. package/bundled/skills/claude-code/workflows/code-review.workflow.yaml +186 -0
  33. package/bundled/skills/claude-code/workflows/feature-dev.workflow.yaml +174 -0
  34. package/bundled/skills/claude-code/workflows/integrated-flow.workflow.yaml +238 -0
  35. package/bundled/skills/claude-code/workflows/large-codebase-analysis.workflow.yaml +226 -0
  36. package/package.json +11 -1
  37. package/src/commands/agent.js +417 -0
  38. package/src/commands/ai-context.js +552 -0
  39. package/src/commands/check.js +3 -3
  40. package/src/commands/init.js +6 -3
  41. package/src/commands/workflow.js +425 -0
  42. package/src/config/ai-agent-paths.js +217 -13
  43. package/src/core/constants.js +514 -0
  44. package/src/core/errors.js +398 -0
  45. package/src/core/manifest.js +473 -0
  46. package/src/core/paths.js +398 -0
  47. package/src/prompts/init.js +7 -5
  48. package/src/utils/agent-adapter.js +320 -0
  49. package/src/utils/agents-installer.js +393 -0
  50. package/src/utils/context-chunker.js +467 -0
  51. package/src/utils/copier.js +59 -99
  52. package/src/utils/hasher.js +2 -16
  53. package/src/utils/integration-generator.js +28 -52
  54. package/src/utils/workflows-installer.js +545 -0
  55. package/standards-registry.json +174 -24
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../docs/AI-AGENT-ROADMAP.md
3
- source_version: 2.2.0
4
- translation_version: 2.2.0
5
- last_synced: 2026-01-15
3
+ source_version: 2.3.0
4
+ translation_version: 2.3.0
5
+ last_synced: 2026-01-22
6
6
  status: current
7
7
  ---
8
8
 
@@ -10,8 +10,8 @@ status: current
10
10
 
11
11
  > **語言**: [English](../../../docs/AI-AGENT-ROADMAP.md) | 繁體中文 | [简体中文](../../zh-CN/docs/AI-AGENT-ROADMAP.md)
12
12
 
13
- **版本**: 2.2.0
14
- **最後更新**: 2026-01-15
13
+ **版本**: 2.3.0
14
+ **最後更新**: 2026-01-22
15
15
 
16
16
  本文件提供 Universal Development Standards (UDS) 對 AI Agent 支援的完整參考。
17
17
 
@@ -19,16 +19,57 @@ status: current
19
19
 
20
20
  ## 目錄
21
21
 
22
- 1. [快速參考](#1-快速參考)
23
- 2. [整合深度](#2-整合深度)
24
- 3. [Skills 系統](#3-skills-系統)
25
- 4. [配置參考](#4-配置參考)
26
- 5. [資源](#5-資源)
27
- 6. [附錄:未來發展](#附錄未來發展)
22
+ 1. [UDS CLI 實作狀態](#1-uds-cli-實作狀態)
23
+ 2. [快速參考](#2-快速參考)
24
+ 3. [整合深度](#3-整合深度)
25
+ 4. [Skills 系統](#4-skills-系統)
26
+ 5. [配置參考](#5-配置參考)
27
+ 6. [資源](#6-資源)
28
+ 7. [附錄:未來發展](#附錄未來發展)
28
29
 
29
30
  ---
30
31
 
31
- ## 1. 快速參考
32
+ ## 1. UDS CLI 實作狀態
33
+
34
+ > **重要**: 本節描述的是 UDS CLI 對各工具的實作狀態,而非工具的原生能力。關於原生能力,請參閱[快速參考](#2-快速參考)。
35
+
36
+ ### 狀態定義
37
+
38
+ | 狀態 | 定義 |
39
+ |------|------|
40
+ | `complete` | Skills + Commands 完整支援,已測試且生產就緒 |
41
+ | `partial` | Skills 可用,Commands 受限或不支援 |
42
+ | `preview` | 功能可用但為預覽版,可能有邊緣案例 |
43
+ | `planned` | CLI 中程式碼存在但未完整測試 |
44
+ | `minimal` | 僅生成規則檔,不支援 Skills/Commands |
45
+
46
+ ### 實作矩陣
47
+
48
+ | AI 工具 | UDS 狀態 | Skills | Commands | 設定檔 | 備註 |
49
+ |---------|:--------:|:------:|:--------:|--------|------|
50
+ | **Claude Code** | ✅ complete | ✅ | 內建 | `CLAUDE.md` | Marketplace + User + Project 三層級 |
51
+ | **OpenCode** | ✅ complete | ✅ | ✅ | `AGENTS.md` | 完整實作,可讀取 Claude 規則 |
52
+ | Cline | 🔶 partial | ✅ | - | `.clinerules` | Skills 透過 fallback,Commands 使用 Workflow |
53
+ | GitHub Copilot | 🔶 partial | ✅ | ✅ | `copilot-instructions.md` | 補充 Copilot Chat |
54
+ | OpenAI Codex | 🔶 partial | ✅ | - | `AGENTS.md`(共用) | Skills 可用 |
55
+ | Gemini CLI | 🧪 preview | ✅ | ✅ (TOML) | `GEMINI.md` | Commands 自動轉換為 TOML |
56
+ | Roo Code | ⏳ planned | ✅ | ✅ | - | 實作存在,待測試 |
57
+ | Cursor | 📄 minimal | - | - | `.cursorrules` | 僅規則檔 |
58
+ | Windsurf | 📄 minimal | - | - | `.windsurfrules` | 僅規則檔 |
59
+ | Antigravity | 📄 minimal | - | - | `INSTRUCTIONS.md` | 僅規則檔 |
60
+
61
+ ### 兩種「支援」的區別
62
+
63
+ | 概念 | 定義 | 記錄位置 |
64
+ |------|------|----------|
65
+ | **工具原生能力** | AI 工具本身支援什麼功能 | [快速參考](#2-快速參考) |
66
+ | **UDS CLI 實作** | UDS CLI 對該工具的實作程度 | 本節 |
67
+
68
+ 範例:Cursor 原生不支援 SKILL.md(工具能力),但 UDS CLI 可以為它生成 `.cursorrules`(實作狀態 = minimal)。
69
+
70
+ ---
71
+
72
+ ## 2. 快速參考
32
73
 
33
74
  ### 配置檔
34
75
 
@@ -43,6 +84,7 @@ status: current
43
84
  | Windsurf | `.windsurfrules` | 設定 UI | 6K/檔,總計 12K |
44
85
  | Gemini CLI | `.gemini/GEMINI.md` | `~/.gemini/GEMINI.md` | 支援 `@import` |
45
86
  | Cursor | `.cursor/rules/*.mdc` | `~/.cursor/rules/` | 需要 YAML frontmatter |
87
+ | Antigravity | `.antigravity/` | `~/.antigravity/` | 最低支援,手動模式 |
46
88
 
47
89
  ### Skills 路徑
48
90
 
@@ -57,6 +99,7 @@ status: current
57
99
  | Windsurf | ✅ 完整 | `.windsurf/rules/` | 設定 UI | 2026/01 起支援 Skills |
58
100
  | Gemini CLI | ✅ 預覽 | `.gemini/skills/` | `~/.gemini/skills/` | v0.23+ 預覽版 |
59
101
  | Cursor | ❌ 否 | `.cursor/rules/` | `~/.cursor/rules/` | 僅 Rules,不支援 SKILL.md |
102
+ | Antigravity | ❌ 否 | `.antigravity/skills/` | `~/.antigravity/skills/` | 不支援 SKILL.md |
60
103
 
61
104
  ### 斜線命令
62
105
 
@@ -71,6 +114,7 @@ status: current
71
114
  | Windsurf | ✅ | Rulebook | 自動產生 | 從 `.windsurfrules` |
72
115
  | Gemini CLI | ✅ | 系統 + 自訂 | `/clear`, `/memory`, `/mcp` | `.gemini/commands/*.toml` |
73
116
  | Cursor | ✅ | 內建 + 自訂 | `/summarize`, `/models` | `.cursor/commands/*.md` |
117
+ | Antigravity | ❌ | N/A | N/A | N/A |
74
118
 
75
119
  ### 平台支援
76
120
 
@@ -82,7 +126,7 @@ status: current
82
126
 
83
127
  ---
84
128
 
85
- ## 2. 整合深度
129
+ ## 3. 整合深度
86
130
 
87
131
  > **說明**: 截至 2026 年 1 月,Agent Skills (SKILL.md) 已成為業界標準。大多數主流 AI 程式碼工具現在都支援相同的 Skills 格式。
88
132
 
@@ -111,11 +155,20 @@ status: current
111
155
  - 尚未支援 SKILL.md 格式
112
156
  - 社群已提出功能請求
113
157
 
158
+ ### 最低支援
159
+
160
+ **工具**: Antigravity
161
+
162
+ - 不支援 SKILL.md
163
+ - 不支援 AGENT.md
164
+ - 僅手動執行模式
165
+ - 為完整性而收錄
166
+
114
167
  ---
115
168
 
116
- ## 3. Skills 系統
169
+ ## 4. Skills 系統
117
170
 
118
- ### 3.1 UDS Skills 相容性
171
+ ### 4.1 UDS Skills 相容性
119
172
 
120
173
  | # | Skill | 斜線命令 | Claude | OpenCode | Cursor | Copilot |
121
174
  |---|-------|----------|:------:|:--------:|:------:|:-------:|
@@ -138,7 +191,7 @@ status: current
138
191
  | 17 | project-structure-guide | `/config` | 完整 | 完整 | 部分 | 無 |
139
192
  | 18 | logging-guide | - | 完整 | 完整 | 完整 | 完整 |
140
193
 
141
- ### 3.2 Skills 路徑與啟用
194
+ ### 4.2 Skills 路徑與啟用
142
195
 
143
196
  #### Skills 探索路徑
144
197
 
@@ -153,6 +206,7 @@ status: current
153
206
  | Windsurf | `.windsurf/rules/` | 設定 UI | ✅ 是 |
154
207
  | Gemini CLI | `.gemini/skills/` | `~/.gemini/skills/` | ✅ 是 |
155
208
  | Cursor | `.cursor/rules/` | `~/.cursor/rules/` | ❌ 否 |
209
+ | Antigravity | `.antigravity/skills/` | `~/.antigravity/skills/` | ❌ 否 |
156
210
 
157
211
  #### 啟用方式
158
212
 
@@ -167,10 +221,11 @@ status: current
167
221
  | Windsurf | 手動(@提及)、始終開啟、模型決定 |
168
222
  | Gemini CLI | 自動觸發、透過設定啟用/停用 |
169
223
  | Cursor | Glob 模式、`alwaysApply` 旗標(僅 rules) |
224
+ | Antigravity | 僅手動 |
170
225
 
171
226
  **建議**:使用 `.claude/skills/` 作為預設安裝路徑 — 大多數工具都可讀取以獲得跨工具相容性。
172
227
 
173
- ### 3.3 跨平台可攜性
228
+ ### 4.3 跨平台可攜性
174
229
 
175
230
  > **業界標準**: 截至 2025 年 12 月,SKILL.md 已被 OpenAI、GitHub、Google 及更廣泛的 AI 程式碼生態系統採用。
176
231
 
@@ -185,6 +240,7 @@ status: current
185
240
  | Windsurf | ✅ 完整 | 2026/01/09 |
186
241
  | Gemini CLI | ✅ 預覽版 | 2026/01/07 |
187
242
  | Cursor | ❌ 尚未 | 已請求 |
243
+ | Antigravity | ❌ 否 | N/A |
188
244
 
189
245
  **跨平台安裝器**:
190
246
  - [skilz](https://github.com/skilz-ai/skilz) - 通用 Skills 安裝器(14+ 平台)
@@ -193,9 +249,9 @@ status: current
193
249
 
194
250
  ---
195
251
 
196
- ## 4. 配置參考
252
+ ## 5. 配置參考
197
253
 
198
- ### 4.1 配置檔
254
+ ### 5.1 配置檔
199
255
 
200
256
  | AI Agent | 專案配置 | 全域配置 | 字元限制 |
201
257
  |----------|----------|----------|----------|
@@ -208,8 +264,9 @@ status: current
208
264
  | GitHub Copilot | `.github/copilot-instructions.md` | 個人設定 | ~8KB |
209
265
  | OpenAI Codex | `AGENTS.md` | `~/.codex/AGENTS.md` | 32KB |
210
266
  | Gemini CLI | `GEMINI.md` | `~/.gemini/GEMINI.md` | 1M tokens |
267
+ | Antigravity | N/A | `~/.antigravity/` | N/A |
211
268
 
212
- ### 4.2 配置合併行為
269
+ ### 5.2 配置合併行為
213
270
 
214
271
  | AI Agent | 合併策略 | 優先順序(高到低) |
215
272
  |----------|----------|-------------------|
@@ -221,8 +278,9 @@ status: current
221
278
  | GitHub Copilot | 組合 | 個人 > 儲存庫 > 組織 |
222
279
  | OpenAI Codex | 串接 | 覆寫檔 > 基礎,較近者優先 |
223
280
  | Gemini CLI | 串接 | 所有檔案支援 `@import` |
281
+ | Antigravity | N/A | N/A |
224
282
 
225
- ### 4.3 Skills 檔案格式
283
+ ### 5.3 Skills 檔案格式
226
284
 
227
285
  > **標準格式**: 帶有 YAML frontmatter 的 SKILL.md 是大多數工具支援的通用格式。
228
286
 
@@ -237,10 +295,11 @@ status: current
237
295
  | Windsurf | ✅ SKILL.md | `.windsurfrules` | YAML |
238
296
  | Gemini CLI | ✅ SKILL.md | `GEMINI.md` | YAML |
239
297
  | Cursor | ❌ `.mdc` | `.cursor/rules/` | YAML (globs, alwaysApply) |
298
+ | Antigravity | ❌ N/A | N/A | N/A |
240
299
 
241
300
  ---
242
301
 
243
- ## 5. 資源
302
+ ## 6. 資源
244
303
 
245
304
  ### 官方文件
246
305
 
@@ -304,6 +363,7 @@ status: current
304
363
 
305
364
  | 版本 | 日期 | 變更 |
306
365
  |------|------|------|
366
+ | 2.3.0 | 2026-01-21 | 新增 Antigravity 至所有表格以與 CLI 保持一致 |
307
367
  | 2.2.0 | 2026-01-15 | 新增多 Agent 安裝、Gemini CLI TOML 轉換 |
308
368
  | 2.1.0 | 2026-01-15 | 更新所有工具的 Skills 支援狀態(業界廣泛採用) |
309
369
  | 2.0.0 | 2026-01-15 | 重大重構:整合內容、減少表格 |
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../../integrations/gemini-cli/GEMINI.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
5
- last_synced: 2026-01-13
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ last_synced: 2026-01-24
6
6
  status: current
7
7
  ---
8
8
 
@@ -89,10 +89,42 @@ status: current
89
89
 
90
90
  ---
91
91
 
92
+ ## 重構指南
93
+
94
+ 參考:`core/refactoring-standards.md`
95
+
96
+ ### 三層策略
97
+
98
+ | 層級 | 策略 | 時間尺度 |
99
+ |------|------|----------|
100
+ | **戰術** | 童子軍法則、準備性重構、紅綠重構 | 分鐘 |
101
+ | **戰略** | 絞殺者無花果、防腐層、分支抽象 | 週至月 |
102
+ | **安全** | 特徵測試、草稿重構、尋找接縫 | 前置作業 |
103
+
104
+ ### 決策樹
105
+
106
+ 1. 在生產環境?否 → 考慮重寫
107
+ 2. 理解程式碼?否 → 先寫特徵測試
108
+ 3. 覆蓋率 >60%?否 → 先加測試
109
+ 4. 架構可挽救?否 → 絞殺者無花果;是 → 漸進重構
110
+
111
+ ### 快速參考
112
+
113
+ | 情況 | 策略 |
114
+ |------|------|
115
+ | 功能被雜亂程式碼阻擋 | **準備性重構** |
116
+ | 修 bug 的機會 | **童子軍法則** |
117
+ | 替換遺留系統 | **絞殺者無花果** |
118
+ | 與遺留系統共存 | **防腐層** |
119
+ | 未測試的遺留程式碼 | **先寫特徵測試** |
120
+
121
+ ---
122
+
92
123
  ## 版本歷史
93
124
 
94
125
  | 版本 | 日期 | 變更 |
95
126
  |------|------|------|
127
+ | 1.1.0 | 2026-01-21 | 新增重構指南章節 |
96
128
  | 1.0.0 | 2026-01-09 | 初始 Gemini CLI 指令檔案 |
97
129
 
98
130
  ---
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../../integrations/github-copilot/COPILOT-CHAT-REFERENCE.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
5
- last_synced: 2026-01-13
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ last_synced: 2026-01-24
6
6
  status: current
7
7
  ---
8
8
 
@@ -204,6 +204,88 @@ INVEST 檢查清單:
204
204
 
205
205
  ---
206
206
 
207
+ ### 9. 重構指導
208
+
209
+ **Claude Code**:`/refactor`
210
+
211
+ **Copilot Chat 提示(決策樹)**:
212
+ ```
213
+ 幫我決定是否應該重構或重寫此程式碼。回答這些問題:
214
+
215
+ 1. 程式碼目前在生產環境運行?[Y/N]
216
+ → N:考慮重寫(風險較低)
217
+ 2. 我理解程式碼做什麼?[Y/N]
218
+ → N:先寫特徵測試
219
+ 3. 測試覆蓋率 > 60%?[Y/N]
220
+ → N:先加測試
221
+ 4. 核心架構可挽救?[Y/N]
222
+ → N:使用絞殺者無花果模式(漸進替換)
223
+ → Y:使用漸進式重構
224
+
225
+ 根據我的回答,推薦適當的策略。
226
+ ```
227
+
228
+ **Copilot Chat 提示(戰術重構)**:
229
+ ```
230
+ 為此程式碼建議戰術重構改進:
231
+
232
+ **童子軍法則**(小規模、機會性清理):
233
+ - 重新命名混淆的變數
234
+ - 提取方法
235
+ - 移除死碼
236
+ - 分鐘級,非小時級
237
+
238
+ **準備性重構**(新增功能前):
239
+ - 「先讓變更變容易,再做容易的變更」- Kent Beck
240
+ - 重組以適應新需求
241
+ - 與功能工作分開提交
242
+
243
+ 哪種方式適合我的情況?
244
+ ```
245
+
246
+ **Copilot Chat 提示(遺留程式碼安全)**:
247
+ ```
248
+ 幫我安全地重構此遺留程式碼:
249
+
250
+ 1. **特徵測試**(先做這個):
251
+ - 呼叫程式碼,寫預期失敗的斷言
252
+ - 更新斷言以符合實際行為
253
+ - 重複直到行為被捕捉
254
+
255
+ 2. **尋找接縫**:
256
+ - 物件接縫(多型)
257
+ - 連結接縫(依賴注入)
258
+
259
+ 3. **萌芽/包裝技術**:
260
+ - 萌芽方法:新邏輯在新的可測試方法中
261
+ - 包裝方法:在現有程式碼前/後加行為
262
+
263
+ 先幫我寫特徵測試。
264
+ ```
265
+
266
+ **Copilot Chat 提示(戰略重構)**:
267
+ ```
268
+ 我需要做大規模重構。幫我在以下之間選擇:
269
+
270
+ 1. **絞殺者無花果**:逐步替換遺留系統
271
+ - 使用時機:替換整個系統,需持續運作
272
+ - 方法:攔截 → 遷移 → 完成
273
+
274
+ 2. **防腐層 (ACL)**:在新舊之間轉譯
275
+ - 使用時機:必須與遺留系統共存
276
+ - 方法:建立 Facade + Adapter + Translator 層
277
+
278
+ 3. **分支抽象**:在主幹上重構共享程式碼
279
+ - 使用時機:長期重構,無功能分支
280
+ - 方法:引入抽象 → 加新實作 → 切換 → 移除舊的
281
+
282
+ 哪種模式適合我的情況?我的限制是:[描述情況]
283
+ ```
284
+
285
+ 參考:`core/refactoring-standards.md`
286
+
287
+ ---
288
+
207
289
  ## 快速參考卡
208
290
 
209
291
  | 任務 | Copilot Chat 提示開頭 |
@@ -216,6 +298,9 @@ INVEST 檢查清單:
216
298
  | 簽入前 | "在提交前驗證這些品質關卡..." |
217
299
  | 發布 | "依照語義化版本準備發布..." |
218
300
  | 文件 | "為此撰寫文件..." |
301
+ | 重構 | "幫我決定是否應該重構或重寫..." |
302
+ | 戰術 | "建議戰術重構改進..." |
303
+ | 遺留 | "幫我安全地重構此遺留程式碼..." |
219
304
 
220
305
  ---
221
306
 
@@ -260,6 +345,7 @@ INVEST 檢查清單:
260
345
 
261
346
  | 版本 | 日期 | 變更 |
262
347
  |------|------|------|
348
+ | 1.1.0 | 2026-01-21 | 新增重構指導提示(決策樹、戰術、遺留、戰略) |
263
349
  | 1.0.0 | 2026-01-13 | 初始發布 |
264
350
 
265
351
  ---
@@ -1,8 +1,8 @@
1
1
  ---
2
2
  source: ../../../../integrations/github-copilot/skills-mapping.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
5
- last_synced: 2026-01-13
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ last_synced: 2026-01-24
6
6
  status: current
7
7
  ---
8
8
 
@@ -36,7 +36,7 @@ Claude Code 提供 18 個 skills 和 16 個斜線命令。GitHub Copilot 不支
36
36
  | **git-workflow-guide** | 僅 Chat 提示 | ⚠️ 部分 |
37
37
  | **documentation-guide** | 僅 Chat 提示 | ⚠️ 部分 |
38
38
  | **methodology-system** | 不可用 | ❌ 無 |
39
- | **refactoring-assistant** | Chat 提示 | ⚠️ 部分 |
39
+ | **refactoring-assistant** | COPILOT-CHAT-REFERENCE.md §9 | 完整 |
40
40
  | **error-code-guide** | 僅 Chat 提示 | ⚠️ 部分 |
41
41
  | **project-structure-guide** | 僅 Chat 提示 | ⚠️ 部分 |
42
42
  | **logging-guide** | 僅 Chat 提示 | ⚠️ 部分 |
@@ -65,6 +65,9 @@ Claude Code 提供 18 個 skills 和 16 個斜線命令。GitHub Copilot 不支
65
65
  | `/changelog` | "以 Keep a Changelog 格式產生 CHANGELOG 條目" |
66
66
  | `/docs` | "為此函式/模組撰寫文件" |
67
67
  | `/spec` | "為此功能建立規格文件" |
68
+ | `/refactor` | "幫我決定是否應該重構或重寫..." |
69
+ | `/refactor tactical` | "建議戰術重構改進..." |
70
+ | `/refactor legacy` | "幫我安全地重構此遺留程式碼..." |
68
71
  | `/methodology` | ❌ 不可用 |
69
72
  | `/bdd` | "幫我用 Gherkin 格式撰寫 BDD 情境" |
70
73
  | `/config` | "為此類型應用程式建議專案結構" |
@@ -183,6 +186,7 @@ gh repo create my-project --template my-org/project-template
183
186
 
184
187
  | 版本 | 日期 | 變更 |
185
188
  |------|------|------|
189
+ | 1.1.0 | 2026-01-21 | 更新 refactoring-assistant 為完整狀態,新增 /refactor 命令對照 |
186
190
  | 1.0.0 | 2026-01-13 | 初始發布 |
187
191
 
188
192
  ---
@@ -0,0 +1,178 @@
1
+ ---
2
+ source: skills/claude-code/commands/refactor.md
3
+ source_version: 1.0.0
4
+ translation_version: 1.0.0
5
+ last_synced: 2026-01-21
6
+ status: current
7
+ description: 引導重構決策與策略選擇
8
+ allowed-tools: Read, Write, Grep, Glob, Bash(npm test:*), Bash(npx:*)
9
+ argument-hint: "[scope: tactical | strategic | legacy | decide | debt]"
10
+ status: stable
11
+ ---
12
+
13
+ # /refactor 命令
14
+
15
+ > **語言**: [English](../../../../../skills/claude-code/commands/refactor.md) | 繁體中文
16
+
17
+ 引導重構決策,推薦適合的重構策略。
18
+
19
+ ## 使用方式
20
+
21
+ | 命令 | 用途 |
22
+ |------|------|
23
+ | `/refactor` | 啟動互動式重構引導 |
24
+ | `/refactor decide` | 執行重構 vs 重寫決策樹 |
25
+ | `/refactor tactical` | 建議戰術性(日常)策略 |
26
+ | `/refactor strategic` | 引導戰略性/架構重構 |
27
+ | `/refactor legacy` | 遺留程式碼安全策略 |
28
+ | `/refactor debt` | 技術債評估 |
29
+
30
+ ## 工作流程
31
+
32
+ ### 1. 評估階段
33
+
34
+ - 識別要重構的程式碼
35
+ - 評估測試覆蓋率
36
+ - 判定範圍(戰術/戰略)
37
+
38
+ ### 2. 策略選擇
39
+
40
+ - 必要時執行決策樹
41
+ - 根據情境推薦適合的策略
42
+
43
+ ### 3. 執行引導
44
+
45
+ - 提供步驟式工作流程
46
+ - 建議安全措施
47
+ - 追蹤進度
48
+
49
+ ## 決策樹
50
+
51
+ 執行 `/refactor decide` 時:
52
+
53
+ ```
54
+ ┌─────────────────────────────────────────────────────────────────┐
55
+ │ 重構 vs 重寫決策樹 │
56
+ ├─────────────────────────────────────────────────────────────────┤
57
+ │ │
58
+ │ 1. 程式碼目前在生產環境運行嗎? [Y/N] │
59
+ │ └─ N → 考慮重寫(風險較低) │
60
+ │ │
61
+ │ 2. 你了解程式碼在做什麼嗎? [Y/N] │
62
+ │ └─ N → 先寫特徵測試,再決定 │
63
+ │ │
64
+ │ 3. 測試覆蓋率 > 60%? [Y/N] │
65
+ │ └─ N → 先補測試,再決定 │
66
+ │ │
67
+ │ 4. 核心架構可以挽救嗎? [Y/N] │
68
+ │ └─ N → Strangler Fig(漸進替換) │
69
+ │ └─ Y → 漸進式重構 ✓ │
70
+ │ │
71
+ └─────────────────────────────────────────────────────────────────┘
72
+ ```
73
+
74
+ ## 策略快速參考
75
+
76
+ ### 戰術性策略(日常)
77
+
78
+ | 策略 | 使用時機 |
79
+ |------|---------|
80
+ | **預備性重構** | 新增被阻擋的功能之前 |
81
+ | **童子軍規則** | 任何維護工作中 |
82
+ | **紅-綠-重構** | TDD 開發循環 |
83
+
84
+ ### 戰略性策略(架構級)
85
+
86
+ | 策略 | 使用時機 |
87
+ |------|---------|
88
+ | **絞殺榕** | 替換整個系統 |
89
+ | **防腐層** | 與遺留系統整合 |
90
+ | **抽象分支** | 在主幹上重構共享程式碼 |
91
+ | **平行變更** | 變更廣泛使用的介面 |
92
+
93
+ ### 安全防護策略(遺留)
94
+
95
+ | 策略 | 使用時機 |
96
+ |------|---------|
97
+ | **特徵測試** | 任何遺留程式碼重構之前 |
98
+ | **探針式重構** | 理解黑盒程式碼 |
99
+ | **找尋接縫** | 注入測試替身 |
100
+ | **Sprout/Wrap** | 在遺留程式碼中新增邏輯 |
101
+
102
+ ## 範例
103
+
104
+ ### 範例 1:功能被混亂程式碼阻擋
105
+
106
+ ```
107
+ 使用者: /refactor tactical
108
+
109
+ AI: 讓我協助你選擇戰術性重構策略。
110
+
111
+ 你的情況是?
112
+ 1. 功能開發被程式碼結構阻擋 → **預備性重構**
113
+ 2. 在 Bug 修復中接觸程式碼 → **童子軍規則**
114
+ 3. 用 TDD 撰寫新程式碼 → **紅-綠-重構**
115
+
116
+ 哪個最符合你的情況?
117
+ ```
118
+
119
+ ### 範例 2:決策樹
120
+
121
+ ```
122
+ 使用者: /refactor decide
123
+
124
+ AI: 讓我協助你決定應該重構還是重寫。
125
+
126
+ **問題 1:** 程式碼目前在生產環境運行嗎?
127
+ □ 是 - 繼續下一個問題
128
+ □ 否 - 考慮重寫(沒有生產依賴,風險較低)
129
+
130
+ 請回答...
131
+ ```
132
+
133
+ ### 範例 3:遺留程式碼
134
+
135
+ ```
136
+ 使用者: /refactor legacy
137
+
138
+ AI: 處理遺留程式碼需要安全優先的策略。
139
+
140
+ **在任何重構之前:**
141
+ 1. ✅ 撰寫特徵測試以捕獲當前行為
142
+ 2. ✅ 如果不理解程式碼,使用探針式重構
143
+ 3. ✅ 找尋接縫以注入測試替身
144
+
145
+ **新增新邏輯時:**
146
+ - 使用 Sprout Method/Class 處理新功能
147
+ - 使用 Wrap Method/Class 處理前後行為
148
+
149
+ 需要我協助你開始撰寫特徵測試嗎?
150
+ ```
151
+
152
+ ## 整合
153
+
154
+ 此命令整合:
155
+
156
+ - **重構助手技能** 提供詳細引導
157
+ - **方法論系統** 追蹤重構進度
158
+ - **TDD 助手** 用於紅-綠-重構循環
159
+
160
+ ## 參考
161
+
162
+ - [重構標準](../../../core/refactoring-standards.md) - 核心標準
163
+ - [重構助手技能](../refactoring-assistant/SKILL.md) - 完整技能
164
+ - [TDD 助手](../tdd-assistant/SKILL.md) - TDD 工作流程
165
+
166
+ ---
167
+
168
+ ## 版本歷史
169
+
170
+ | 版本 | 日期 | 變更 |
171
+ |------|------|------|
172
+ | 1.0.0 | 2026-01-21 | 初始發布 |
173
+
174
+ ---
175
+
176
+ ## 授權
177
+
178
+ 本文件以 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 授權發布。