universal-dev-standards 6.14.0-beta.5 → 6.14.0-beta.7

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 (99) hide show
  1. package/README.md +13 -3
  2. package/bin/uds.js +32 -7
  3. package/bundled/ai/options/code-review/pr-review.ai.yaml +20 -1
  4. package/bundled/ai/standards/code-review.ai.yaml +15 -2
  5. package/bundled/ai/standards/commit-message.ai.yaml +6 -2
  6. package/bundled/ai/standards/developer-memory.ai.yaml +12 -2
  7. package/bundled/ai/standards/full-coverage-testing.ai.yaml +44 -6
  8. package/bundled/ai/standards/open-work-tracking.ai.yaml +191 -11
  9. package/bundled/ai/standards/pipeline-security-gates.ai.yaml +48 -3
  10. package/bundled/ai/standards/project-context-memory.ai.yaml +12 -2
  11. package/bundled/core/code-review-checklist.md +20 -2
  12. package/bundled/core/developer-memory.md +12 -2
  13. package/bundled/core/full-coverage-testing.md +44 -4
  14. package/bundled/core/open-work-tracking.md +156 -16
  15. package/bundled/core/pipeline-security-gates.md +63 -0
  16. package/bundled/core/project-context-memory.md +10 -2
  17. package/bundled/locales/zh-CN/CHANGELOG.md +75 -3
  18. package/bundled/locales/zh-CN/README.md +1 -1
  19. package/bundled/locales/zh-CN/SECURITY.md +1 -1
  20. package/bundled/locales/zh-CN/adoption/ADOPTION-GUIDE.md +13 -4
  21. package/bundled/locales/zh-CN/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  22. package/bundled/locales/zh-CN/adoption/checklists/enterprise.md +7 -1
  23. package/bundled/locales/zh-CN/adoption/checklists/minimal.md +13 -3
  24. package/bundled/locales/zh-CN/adoption/checklists/recommended.md +7 -1
  25. package/bundled/locales/zh-CN/core/code-review-checklist.md +17 -0
  26. package/bundled/locales/zh-CN/core/developer-memory.md +9 -0
  27. package/bundled/locales/zh-CN/core/full-coverage-testing.md +48 -8
  28. package/bundled/locales/zh-CN/core/pipeline-security-gates.md +64 -4
  29. package/bundled/locales/zh-CN/core/project-context-memory.md +5 -0
  30. package/bundled/locales/zh-CN/docs/AVAILABLE-STANDARDS.md +70 -0
  31. package/bundled/locales/zh-CN/docs/CHEATSHEET.md +5 -4
  32. package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +25 -23
  33. package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +15 -12
  34. package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +6 -6
  35. package/bundled/locales/zh-CN/docs/WINDOWS-GUIDE.md +7 -1
  36. package/bundled/locales/zh-CN/docs/user/GETTING-STARTED.md +44 -0
  37. package/bundled/locales/zh-CN/options/code-review/pr-review.md +13 -2
  38. package/bundled/locales/zh-TW/CHANGELOG.md +75 -3
  39. package/bundled/locales/zh-TW/README.md +1 -1
  40. package/bundled/locales/zh-TW/SECURITY.md +1 -1
  41. package/bundled/locales/zh-TW/adoption/ADOPTION-GUIDE.md +13 -4
  42. package/bundled/locales/zh-TW/adoption/STATIC-DYNAMIC-GUIDE.md +7 -1
  43. package/bundled/locales/zh-TW/adoption/checklists/enterprise.md +7 -1
  44. package/bundled/locales/zh-TW/adoption/checklists/minimal.md +13 -3
  45. package/bundled/locales/zh-TW/adoption/checklists/recommended.md +7 -1
  46. package/bundled/locales/zh-TW/core/code-review-checklist.md +17 -0
  47. package/bundled/locales/zh-TW/core/developer-memory.md +9 -0
  48. package/bundled/locales/zh-TW/core/full-coverage-testing.md +48 -8
  49. package/bundled/locales/zh-TW/core/open-work-tracking.md +90 -14
  50. package/bundled/locales/zh-TW/core/pipeline-security-gates.md +64 -4
  51. package/bundled/locales/zh-TW/core/project-context-memory.md +5 -0
  52. package/bundled/locales/zh-TW/docs/AVAILABLE-STANDARDS.md +70 -0
  53. package/bundled/locales/zh-TW/docs/CHEATSHEET.md +5 -4
  54. package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +25 -23
  55. package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +15 -12
  56. package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +6 -6
  57. package/bundled/locales/zh-TW/docs/WINDOWS-GUIDE.md +7 -1
  58. package/bundled/locales/zh-TW/docs/user/GETTING-STARTED.md +44 -0
  59. package/bundled/locales/zh-TW/options/code-review/pr-review.md +13 -2
  60. package/bundled/skills/SKILL_NAMING.md +9 -0
  61. package/bundled/templates/gates/check-anti-fake-tests.mjs +305 -5
  62. package/package.json +3 -1
  63. package/src/commands/audit.js +9 -2
  64. package/src/commands/check.js +17 -0
  65. package/src/commands/deps.js +31 -1
  66. package/src/commands/init.js +41 -21
  67. package/src/commands/open-work.js +65 -6
  68. package/src/commands/simulate.js +20 -8
  69. package/src/commands/skills.js +59 -33
  70. package/src/commands/spec.js +14 -8
  71. package/src/commands/update.js +106 -66
  72. package/src/core/manifest.js +12 -10
  73. package/src/core/marketplace-sentinel.js +5 -0
  74. package/src/core/open-work-config.js +103 -0
  75. package/src/core/project-config.js +58 -38
  76. package/src/flows/init-flow.js +10 -0
  77. package/src/i18n/messages.js +264 -60
  78. package/src/installers/skills-installer.js +3 -1
  79. package/src/prompts/init.js +148 -13
  80. package/src/reconciler/backup-locations.js +75 -0
  81. package/src/reconciler/backup-manager.js +29 -45
  82. package/src/reconciler/index.js +62 -8
  83. package/src/utils/available-standards-report.js +144 -0
  84. package/src/utils/available-standards.js +216 -0
  85. package/src/utils/commit-message-judge.js +137 -0
  86. package/src/utils/copier.js +5 -4
  87. package/src/utils/deps-applicability.js +25 -0
  88. package/src/utils/friction-detector.js +27 -0
  89. package/src/utils/installed-names-ownership.js +114 -0
  90. package/src/utils/open-work-tracking.mjs +919 -48
  91. package/src/utils/sdd-header.js +65 -0
  92. package/src/utils/skill-frontmatter.js +102 -0
  93. package/src/utils/skill-name-collision.js +169 -0
  94. package/src/utils/skills-install-paths.js +114 -0
  95. package/src/utils/skills-installer.js +63 -105
  96. package/src/utils/standard-validator.js +98 -27
  97. package/src/utils/transient-fs.js +113 -0
  98. package/src/vibe/micro-spec.js +15 -0
  99. package/standards-registry.json +9 -9
@@ -1,7 +1,7 @@
1
1
  # UDS 功能參考手冊
2
2
 
3
3
  > Universal Development Standards - 完整功能文件
4
- > Auto-generated | Last updated: 2026-10-06
4
+ > Auto-generated | Last updated: 2026-10-08
5
5
 
6
6
  **Language**: [English](../../../docs/reference/FEATURE-REFERENCE.md) | 繁體中文 | [简体中文](../../zh-CN/docs/FEATURE-REFERENCE.md)
7
7
 
@@ -15,9 +15,9 @@
15
15
  4. [代理](#agents) (5)
16
16
  5. [工作流程](#workflows) (5)
17
17
  6. [核心規範](#core-standards) (153)
18
- 7. [腳本](#scripts) (64)
18
+ 7. [腳本](#scripts) (65)
19
19
 
20
- **Total Features: 358**
20
+ **Total Features: 359**
21
21
 
22
22
  ---
23
23
 
@@ -48,7 +48,7 @@
48
48
  | `--lang` | Language extension (csharp, php) |
49
49
  | `--framework` | Framework extension (fat-free) |
50
50
  | `--locale` | Locale extension (zh-tw) |
51
- | `--skills-location` | Skills location (marketplace, user, project, none) [default: marketplace] |
51
+ | `--skills-location` | Skills location (project, user, marketplace, none) [default: project] |
52
52
  | `--content-mode` | Content mode for integration files (minimal, index) [default: index]; full is retired and resolves to index |
53
53
  | `--agents-md` | Generate AGENTS.md universal summary |
54
54
  | `--no-agents-md` | Skip AGENTS.md generation |
@@ -116,7 +116,7 @@
116
116
 
117
117
  ### `uds simulate`
118
118
 
119
- **說明**: Simulate a standard check with input (Predictive Validation)
119
+ **說明**: Simulate a standard check with input (Predictive Validation). Exit 0 = passes, 1 = does not comply, 2 = no verdict (cannot simulate; not a pass). Only commit-message defines a simulator today
120
120
 
121
121
  **選項**:
122
122
  | Option | 說明 |
@@ -156,6 +156,7 @@
156
156
  | `--force` | Force update all files, ignoring hash comparison |
157
157
  | `--prune` | Delete .standards/ files UDS wrote but no longer ships (listed without this flag; never touches files UDS did not write) |
158
158
  | `--rollback` | Rollback to the most recent backup |
159
+ | `--add-standard` | With --plan or --apply: also install this standard UDS ships and the project lacks, and record it in the manifest (repeatable; `uds update --plan` lists what is available) |
159
160
  | `--claude-target` | Switch an existing install to a different Claude Code integration target: project (CLAUDE.md) or local (CLAUDE.local.md) — moves the UDS block, keeps your content, no reinstall |
160
161
  | `--locale` | Override locale for skills install (zh-tw, zh-cn, en); also reads .uds/install.yaml + UDS_LOCALE env |
161
162
  | `--with-hooks` | Install the enforcement hooks that are missing from this already-initialized project (re-detects tools; hooks already there and your own hooks are not touched; with --plan, writes nothing; --force also overwrites edited hook scripts) |
@@ -201,6 +202,7 @@
201
202
  | `--path` | Directory containing package.json (default: cwd) |
202
203
  | `--json` | Output raw JSON |
203
204
  | `--concurrency` | Parallel registry lookups (default: 8) |
205
+ | `--if-present` | Exit 0 and say that nothing was checked when there is no package.json or no runtime dependency (default: exit 1) |
204
206
 
205
207
  ### `uds uninstall`
206
208
 
@@ -281,7 +283,7 @@
281
283
 
282
284
  ### `uds open-work`
283
285
 
284
- **說明**: Reference checks for open-work-tracking (OWT-017/018/019). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass)
286
+ **說明**: Reference checks for open-work-tracking (OWT-017 to OWT-028). Exit 0 no violation, 1 violation, 2 cannot decide (not a pass)
285
287
 
286
288
  ### `uds run`
287
289
 
@@ -469,7 +471,7 @@
469
471
  | `checkin-standards` | 1.8.0 | This standard defines quality gates that MUST be passed before committing code t |
470
472
  | `circuit-breaker` | - | |
471
473
  | `class-level-fix` | 1.1.0 | A defect is almost never alone. It is one member of a set — one flag in a dispat |
472
- | `code-review-checklist` | 1.5.0 | This standard provides a comprehensive checklist for reviewing code changes, ens |
474
+ | `code-review-checklist` | 1.6.0 | This standard provides a comprehensive checklist for reviewing code changes, ens |
473
475
  | `commit-message-guide` | 1.3.0 | Standardized commit messages improve code review efficiency, facilitate automate |
474
476
  | `container-image-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
475
477
  | `container-security` | - | |
@@ -486,7 +488,7 @@
486
488
  | `deployment-standards` | 1.1.0 | This standard defines guidelines for safely deploying software to production, co |
487
489
  | `deprecation-standards` | 1.1.0 | |
488
490
  | `design-document-standards` | 1.0.0 | |
489
- | `developer-memory` | 1.2.0 | This standard defines a structured system for capturing, retrieving, and surfaci |
491
+ | `developer-memory` | 1.2.1 | This standard defines a structured system for capturing, retrieving, and surfaci |
490
492
  | `disaster-recovery-drill` | - | |
491
493
  | `documentation-lifecycle` | 1.0.0 | This standard defines **when** to update documentation, **when** to check it, an |
492
494
  | `documentation-structure` | 1.5.0 | This standard defines a consistent documentation structure for software projects |
@@ -524,18 +526,18 @@
524
526
  | `mutation-testing` | 1.1.0 | Mutation testing evaluates test suite effectiveness by injecting artificial bugs |
525
527
  | `no-cicd-deployment` | - | |
526
528
  | `observability-standards` | 1.0.0 | |
527
- | `open-work-tracking` | 1.1.0 | The deferred-item-exit standard requires that a deferred item leave its document |
529
+ | `open-work-tracking` | 1.4.0 | The deferred-item-exit standard requires that a deferred item leave its document |
528
530
  | `packaging-standards` | 1.1.0 | This standard defines a Recipe-based packaging framework that enables user proje |
529
531
  | `performance-standards` | 1.2.0 | This standard defines comprehensive guidelines for software performance engineer |
530
532
  | `pii-classification` | 1.1.0 | **Status**: Active | **Updated**: 2026-06-19 | |
531
533
  | `pipeline-integration-standards` | - | |
532
- | `pipeline-security-gates` | - | |
534
+ | `pipeline-security-gates` | 1.1.0 | |
533
535
  | `policy-as-code-testing` | - | |
534
536
  | `postmortem-standards` | 1.0.0 | |
535
537
  | `prd-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
536
538
  | `privacy-standards` | 1.1.0 | |
537
539
  | `product-metrics-standards` | 1.0.0 | **Status**: Active | **Updated**: 2026-06-17 | |
538
- | `project-context-memory` | 1.2.0 | This standard defines a structured system for capturing, retrieving, and enforci |
540
+ | `project-context-memory` | 1.2.1 | This standard defines a structured system for capturing, retrieving, and enforci |
539
541
  | `project-structure` | 1.2.0 | This standard defines conventions for project directory structure beyond documen |
540
542
  | `prompt-regression` | - | |
541
543
  | `property-based-testing` | - | |
@@ -619,7 +621,7 @@
619
621
  | `check-error-exit.mjs` | 🔴 沒填就是沒設定,而沒設定會 exit 2, |
620
622
  | `check-external-references.mjs` | External Reference Checker (SPEC-SELFDIAG-001 REQ-5, AC-7) |
621
623
  | `check-home-untouched.mjs` | check-home-untouched — did this run write anywhere UDS writes under HOME? |
622
- | `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 / OWT-018 / OWT-019 — repo entry point. |
624
+ | `check-open-work-tracking.mjs` | Open-work-tracking reference checks for OWT-017 to OWT-028 — repo entry point. |
623
625
  | `check-orphan-specs.ps1` | Check Orphan Specs |
624
626
  | `check-orphan-specs.sh` | Orphan Spec Detection Script |
625
627
  | `check-prompt-footprint.mjs` | Prompt Footprint Ratchet — DEC-117 D2/L2 |
@@ -642,6 +644,7 @@
642
644
  | `check-version-sync.ps1` | Check Version Sync |
643
645
  | `check-version-sync.sh` | Version Sync Checker |
644
646
  | `check-workflow-compliance.sh` | Thin wrapper — scripts/check-workflow-compliance.ts is the only copy of the |
647
+ | `ci-vitest-summary.mjs` | ci-vitest-summary — say how many tests ran, passed, failed and were skipped (dev-platform XSPEC-469 R4). |
645
648
  | `commitlint-bilingual-rule.mjs` | commitlint-bilingual-rule.mjs — custom commitlint rules enforcing the |
646
649
  | `convert-md-to-yaml.mjs` | Markdown to AI-YAML Conversion Script |
647
650
  | `fix-manifest-paths.ps1` | Fix Manifest Paths |
@@ -35,7 +35,7 @@ status: current
35
35
 
36
36
  **配置方式**:
37
37
  - 安裝時選擇 `standardsScope: minimal`
38
- - Skills 位置:Plugin Marketplace(推薦)
38
+ - Skills 位置:裝進專案(`--skills-location project`,預設);外掛市集是有限制的替代方式(只支援 Claude Code、只有英文技能文字、只跟正式版)
39
39
  - 最小化規範文件複製到專案
40
40
 
41
41
  **包含內容**:
@@ -147,7 +147,7 @@ status: current
147
147
  | 團隊同步 | 需各自安裝 | Git 同步 | 混合 |
148
148
 
149
149
  **說明**:
150
- - Skills 在 Plugin Marketplace 集中管理,但無法版本控制
150
+ - 裝進專案的 Skills(預設)可以提交到 Git;來自外掛市集的 Skills 由 Claude Code 管理,不在專案內
151
151
  - 規範文件可放入 Git,團隊自動同步
152
152
  - 自訂規則需要修改規範文件
153
153
 
@@ -180,7 +180,7 @@ status: current
180
180
 
181
181
  **配置方式**:
182
182
  ```bash
183
- uds init -y --skills-location marketplace
183
+ uds init -y --skills-location project
184
184
  # standardsScope 將自動設為 minimal
185
185
  ```
186
186
 
@@ -195,7 +195,7 @@ uds init -y --skills-location marketplace
195
195
 
196
196
  **配置方式**:
197
197
  ```bash
198
- uds init -y --skills-location marketplace --content-mode index
198
+ uds init -y --skills-location project --content-mode index
199
199
  # 在互動提示中選擇多個 AI 工具
200
200
  ```
201
201
 
@@ -296,11 +296,11 @@ uds init -y --skills-location none --content-mode index
296
296
  ```
297
297
  個人開發者 + Claude Code
298
298
  └─ 推薦:僅 Skills(模式 A)
299
- └─ 配置:standardsScope: minimal + Plugin Marketplace
299
+ └─ 配置:standardsScope: minimal + 技能裝進專案
300
300
 
301
301
  團隊開發 + 混合工具
302
302
  └─ 推薦:Skills + 規範文件(模式 C)
303
- └─ 配置:standardsScope: full + Plugin Marketplace
303
+ └─ 配置:standardsScope: full + 技能裝進專案
304
304
  └─ 規範文件納入 Git 管理
305
305
 
306
306
  企業環境 + 合規要求
@@ -59,7 +59,13 @@ npm link
59
59
 
60
60
  ## 安裝 Claude Code Skills
61
61
 
62
- **推薦:Plugin Marketplace**
62
+ **主要路徑:裝進專案**(支援多種 AI 工具、有繁體與簡體中文文字、跟著你裝的 UDS 版本)
63
+ ```bash
64
+ npx universal-dev-standards init # 新專案
65
+ npx universal-dev-standards update --apply --skills # 已設定好的專案
66
+ ```
67
+
68
+ **替代方式(有限制):Claude Code 外掛市集**(只支援 Claude Code、只有英文技能文字、只跟正式版、專案內不放檔案)
63
69
  ```bash
64
70
  /plugin marketplace add AsiaOstrich/universal-dev-standards
65
71
  /plugin install universal-dev-standards@asia-ostrich
@@ -57,6 +57,50 @@ CLAUDE.md ← 已更新 UDS 指引(Claude Code)
57
57
 
58
58
  ---
59
59
 
60
+ ## 技能怎麼裝
61
+
62
+ 取得 UDS 技能有兩種方式,兩種都受支援。主要路徑是裝進專案;Claude Code 外掛市集是有限制的替代方式。
63
+
64
+ > **預設是裝進專案。** `uds init` 與不帶 `--skills-location` 的 `uds init --yes` 會把技能裝進專案(Claude Code 是 `.claude/skills/`)。6.14 之前它們一個技能檔都不裝,把 Claude Code 的技能留給外掛。要改用外掛,請加 `--skills-location marketplace`:專案內不會寫入任何技能檔,安裝結尾會說明技能從哪裡來。
65
+
66
+ | | 裝進專案(主要路徑) | Claude Code 外掛市集(替代方式) |
67
+ |---|---|---|
68
+ | 指令 | 新專案:`uds init`(這是預設)<br>已設定過的專案:`uds update --apply --skills` | `/plugin marketplace add AsiaOstrich/universal-dev-standards`,再 `/plugin install universal-dev-standards@asia-ostrich` |
69
+ | AI 工具 | Claude Code、OpenCode、Cursor、Codex、Copilot、Windsurf 等 | 只支援 Claude Code |
70
+ | 技能文字的語言 | 英文、繁體中文、簡體中文。中文文字放在 npm 套件內,所以安裝它們不需要網路;缺少這些文字的 UDS 會改裝英文並明說 | 只有英文:外掛設定沒有語系選擇 |
71
+ | UDS 版本 | 你裝的那個版本,包含測試版 | 只跟正式版 |
72
+ | 專案內的檔案 | 有,例如 `.claude/skills/`;`uds check` 會逐檔驗證 | 沒有 |
73
+ | 更新 | 升級 UDS 後,自己再跑一次 `uds update --apply --skills` | 由 Claude Code 管理外掛(`/plugin`) |
74
+
75
+ **請二擇一。** Claude Code 執行外掛技能是 `/<外掛名>:<技能名>`,執行專案技能是 `/<技能名>`,所以兩種都裝時每個技能會出現兩次(例如 `/commit` 與 `/universal-dev-standards:commit`),而且每個技能的名稱與描述每回合都會放進脈絡,重複裝等於重複占用。`uds check` 發現專案內有 UDS 技能、同時又裝了 UDS 外掛時,會印出警告;警告只是資訊,不改變判定與結束碼。要留專案這份,在 Claude Code 執行 `/plugin uninstall universal-dev-standards@asia-ostrich`。要留外掛,刪掉 `.claude/skills/` 底下的 UDS 技能資料夾。
76
+
77
+ **為什麼 `uds check` 與 `uds update` 叫你跑 `uds update --apply --skills`。** `uds check` 在專案裡的技能檔遺失或被改過時說這句,`uds update` 在已裝的技能版本落後時說這句。只有裝進專案的技能有檔案,UDS 才能拿它和當初裝的內容比對、放回去,所以修法就是那個指令。外掛不在你的專案裡放檔案,`uds check` 沒有東西可比對,也就沒有這類訊息。
78
+
79
+ `uds skills` 會列出裝了什麼、裝在哪裡,並印出同樣的兩種方式與各自的限制。
80
+
81
+ ### 個人技能與 UDS 技能同名時
82
+
83
+ Claude Code 對同一個名稱只執行一個技能,而且漏掉另一個時不會告訴你。哪一個執行,取決於各自從哪裡來(Claude Code 技能文件,2026-10-07 讀取):
84
+
85
+ | 同名出現在 | 執行哪一個 |
86
+ |---|---|
87
+ | 企業層(組織下發的 managed settings 目錄)、個人層(`~/.claude/skills/<名稱>/`)、專案層(`.claude/skills/<名稱>/`) | 企業層高於個人層,個人層高於專案層 |
88
+ | 專案技能與子目錄裡的巢狀技能 | 兩個都載入:`/<名稱>` 執行專案根目錄那個,巢狀那個是 `/<目錄>:<名稱>` |
89
+ | 外掛技能與上面任一處的技能 | 兩個都載入:外掛技能是 `/<外掛名>:<名稱>` |
90
+ | 技能與 `.claude/commands/<名稱>.md` 檔 | 技能 |
91
+
92
+ 技能的名稱是 `SKILL.md` frontmatter 裡的 `name:`,沒有就用資料夾名稱;資料夾名稱同樣能叫出該技能,所以兩者任一撞名都算。
93
+
94
+ **對 UDS 的意思。** `uds init --skills-location project` 與 `uds update --apply --skills` 寫進去的是專案技能。你若已有同名的個人技能,執行的是你的,UDS 那個永遠不會執行,而且沒有任何訊息說明。UDS 有幾個技能名稱短而通用(`plan`、`push`、`sweep`、`orchestrate`,以及資料夾叫 `commit-standards` 的 `/commit`),所以有個人技能庫的人都可能遇到。UDS 不為此改名:改名會破壞所有既有的呼叫。
95
+
96
+ **怎麼看見。** `uds check` 會拿專案裡的 UDS 技能與 `~/.claude/skills/` 的技能比對,印出一則警告並點名每一組;`uds init` 與 `uds update --apply --skills` 在安裝結尾印同一則警告。它只是資訊,不改變判定也不改變結束碼。它有限制,而且**沒有警告不等於沒有撞名**:它看不到組織以企業層下發的技能(優先序高於個人層),也看不到它執行之後你才新增的個人技能,所以新增之後請再跑一次 `uds check`。
97
+
98
+ **怎麼解。** 二擇一。兩個都留:把你的個人技能改名(資料夾名稱,以及 `SKILL.md` 裡的 `name:`)。只留你的:刪掉 `.claude/skills/` 底下那個 UDS 技能資料夾。
99
+
100
+ 替新的 UDS 技能取名以避免撞名,屬於貢獻者的事:見 `skills/SKILL_NAMING.md`。
101
+
102
+ ---
103
+
60
104
  ## 步驟 3 — 你的第一份 Spec(`/sdd`)
61
105
 
62
106
  在寫程式碼之前,先建立一份 spec:
@@ -1,7 +1,8 @@
1
1
  ---
2
2
  source: options/code-review/pr-review.md
3
- source_version: 1.0.0
4
- translation_version: 1.0.0
3
+ source_version: 1.1.0
4
+ translation_version: 1.1.0
5
+ source_hash: 3fafa7b1a9c3
5
6
  status: current
6
7
  ---
7
8
 
@@ -35,6 +36,7 @@ Pull Request(PR)審查是傳統的非同步程式碼審查流程,在合併
35
36
  - 連結相關 issue
36
37
  - 指派適當的 reviewer
37
38
  - 確保 CI 檢查通過
39
+ - 寫明合併風險:門(雙向或單向)與影響範圍,一個詞;單向門要在合併前讓決策者知情
38
40
 
39
41
  ### 2. 審查
40
42
 
@@ -127,6 +129,15 @@ Brief description of changes
127
129
  - [ ] Unit tests added/updated
128
130
  - [ ] Manual testing performed
129
131
 
132
+ ## Merge Danger
133
+ Door (tick one):
134
+ - [ ] Two-way door: after merging, it can be taken back easily
135
+ - [ ] One-way door: irreversible or hard to take back (data migration, deletion, changed default behavior, changed exit code, renamed public interface)
136
+
137
+ Blast radius (one word, e.g. docs, cli, adopters):
138
+
139
+ A one-way door must be made known to whoever decides to merge before the merge.
140
+
130
141
  ## Checklist
131
142
  - [ ] Code follows project style guidelines
132
143
  - [ ] Self-review completed
@@ -51,6 +51,14 @@
51
51
  - `/borrow` ❌ → 借什麼?
52
52
  - `/derive` ⚠️ → 可接受(SDD 脈絡下清楚),但 `/spec-derive` 更明確
53
53
 
54
+ ### 規則 6:新技能避免單一通用單字(XSPEC-465)
55
+
56
+ Claude Code 對同名技能只執行一個,優先序是企業層 > 個人層 > 專案層(官方技能文件,2026-10-07 讀取),而 UDS 技能裝進採用者專案後屬專案層。所以採用者個人層若有同名技能,UDS 的技能會被靜默蓋掉(`uds check` 會警告,但只看得到本機個人層)。**單一通用單字(`plan`、`push`、`test`、`review`)最容易撞名**:
57
+
58
+ - **新技能**:`name:` 優先用兩個詞以上、帶領域的名稱(`spec-derive`、`api-design`、`ac-coverage`),避免只有一個常見英文單字。
59
+ - **既有技能**:已出貨的 `plan`、`push`、`sweep`、`orchestrate` 等通用名稱**不為此改名**——改名會破壞所有既有呼叫;風險靠 `uds check` 的撞名警告與使用者文件說明處理。
60
+ - 撞名的檢查會同時比對 `name:` 與目錄名,所以兩者都要考慮。
61
+
54
62
  ---
55
63
 
56
64
  ## 命名範例對照表
@@ -76,6 +84,7 @@
76
84
  - [ ] 後綴:引導式用 `-assistant`,工具型無後綴
77
85
  - [ ] 只用業界公認縮寫;專案特定縮寫需在 README 補說明
78
86
  - [ ] `name:` 欄位比目錄名短,且能預測功能
87
+ - [ ] `name:` 與目錄名都不是單一通用單字(規則 6)
79
88
  - [ ] 更新 `skills/README.md` 加入新 Skill 的縮寫說明
80
89
 
81
90
  ---