universal-dev-standards 6.8.0 → 6.9.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.
- package/bin/uds.js +12 -2
- package/bundled/ai/standards/acceptance-criteria-traceability.ai.yaml +14 -2
- package/bundled/ai/standards/adr-standards.ai.yaml +14 -2
- package/bundled/ai/standards/code-review.ai.yaml +13 -3
- package/bundled/ai/standards/commit-message.ai.yaml +8 -4
- package/bundled/ai/standards/deferred-item-exit.ai.yaml +225 -0
- package/bundled/ai/standards/feature-discovery-standards.ai.yaml +14 -2
- package/bundled/ai/standards/governance-layer.ai.yaml +128 -2
- package/bundled/ai/standards/logging.ai.yaml +2 -2
- package/bundled/ai/standards/retrospective-standards.ai.yaml +14 -2
- package/bundled/ai/standards/reverse-engineering-standards.ai.yaml +73 -2
- package/bundled/ai/standards/security-standards.ai.yaml +2 -2
- package/bundled/ai/standards/spec-driven-development.ai.yaml +14 -2
- package/bundled/ai/standards/tech-debt-standards.ai.yaml +87 -3
- package/bundled/ai/standards/turn-completion-integrity.ai.yaml +131 -0
- package/bundled/core/acceptance-criteria-traceability.md +5 -2
- package/bundled/core/adr-standards.md +26 -2
- package/bundled/core/code-review-checklist.md +5 -2
- package/bundled/core/context-aware-loading.md +1 -1
- package/bundled/core/deferred-item-exit.md +254 -0
- package/bundled/core/feature-discovery-standards.md +5 -1
- package/bundled/core/governance-layer.md +114 -2
- package/bundled/core/retrospective-standards.md +4 -2
- package/bundled/core/reverse-engineering-standards.md +81 -2
- package/bundled/core/spec-driven-development.md +8 -2
- package/bundled/core/tech-debt-standards.md +67 -8
- package/bundled/core/turn-completion-integrity.md +196 -0
- package/bundled/hooks/check-dangerous-cmd.mjs +60 -0
- package/bundled/hooks/check-logging-standard.mjs +59 -0
- package/bundled/hooks/check-turn-completion.mjs +233 -0
- package/bundled/hooks/inject-standards.mjs +183 -0
- package/bundled/hooks/telemetry-wrapper.mjs +77 -0
- package/bundled/hooks/turn-completion/detect.mjs +99 -0
- package/bundled/hooks/turn-completion/locales/en.mjs +159 -0
- package/bundled/hooks/turn-completion/locales/zh-TW.mjs +166 -0
- package/bundled/hooks/validate-commit-msg.mjs +104 -0
- package/bundled/locales/zh-CN/CHANGELOG.md +47 -3
- package/bundled/locales/zh-CN/CLAUDE.md +1 -1
- package/bundled/locales/zh-CN/README.md +2 -2
- package/bundled/locales/zh-CN/SECURITY.md +1 -1
- package/bundled/locales/zh-CN/core/adr-standards.md +1 -1
- package/bundled/locales/zh-CN/core/governance-layer.md +118 -6
- package/bundled/locales/zh-CN/core/retrospective-standards.md +1 -1
- package/bundled/locales/zh-CN/core/tech-debt-standards.md +71 -4
- package/bundled/locales/zh-CN/core/turn-completion-integrity.md +190 -0
- package/bundled/locales/zh-CN/docs/CHEATSHEET.md +8 -1
- package/bundled/locales/zh-CN/docs/CLI-INIT-OPTIONS.md +29 -68
- package/bundled/locales/zh-CN/docs/FEATURE-REFERENCE.md +25 -15
- package/bundled/locales/zh-CN/docs/USAGE-MODES-COMPARISON.md +1 -2
- package/bundled/locales/zh-CN/integrations/google-antigravity/{INSTRUCTIONS.md → AGENTS.md} +1 -1
- package/bundled/locales/zh-CN/integrations/google-antigravity/README.md +3 -3
- package/bundled/locales/zh-CN/skills/atdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/bdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/brainstorm-assistant/SKILL.md +22 -12
- package/bundled/locales/zh-CN/skills/brainstorm-assistant/guide.md +12 -9
- package/bundled/locales/zh-CN/skills/code-review-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/commands/brainstorm.md +17 -13
- package/bundled/locales/zh-CN/skills/commands/config.md +0 -1
- package/bundled/locales/zh-CN/skills/commands/init.md +1 -2
- package/bundled/locales/zh-CN/skills/commit-standards/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/contract-test-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/dev-methodology/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/observability-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/project-structure-guide/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/release-standards/SKILL.md +3 -0
- package/bundled/locales/zh-CN/skills/requirement-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-CN/skills/reverse-engineer/SKILL.md +3 -0
- package/bundled/locales/zh-CN/skills/runbook-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/slo-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-CN/skills/tdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/CHANGELOG.md +47 -3
- package/bundled/locales/zh-TW/CLAUDE.md +1 -1
- package/bundled/locales/zh-TW/README.md +2 -2
- package/bundled/locales/zh-TW/SECURITY.md +1 -1
- package/bundled/locales/zh-TW/core/acceptance-criteria-traceability.md +2 -0
- package/bundled/locales/zh-TW/core/adr-standards.md +26 -5
- package/bundled/locales/zh-TW/core/code-review-checklist.md +2 -0
- package/bundled/locales/zh-TW/core/container-image-standards.md +2 -2
- package/bundled/locales/zh-TW/core/contract-testing-standards.md +2 -2
- package/bundled/locales/zh-TW/core/cross-flow-regression.md +8 -7
- package/bundled/locales/zh-TW/core/data-contract.md +2 -2
- package/bundled/locales/zh-TW/core/data-migration-testing.md +2 -2
- package/bundled/locales/zh-TW/core/data-pipeline.md +2 -2
- package/bundled/locales/zh-TW/core/deferred-item-exit.md +251 -0
- package/bundled/locales/zh-TW/core/documentation-writing-standards.md +228 -3
- package/bundled/locales/zh-TW/core/full-coverage-testing.md +15 -2
- package/bundled/locales/zh-TW/core/governance-layer.md +118 -5
- package/bundled/locales/zh-TW/core/iac-design-principles.md +2 -2
- package/bundled/locales/zh-TW/core/incident-response.md +2 -2
- package/bundled/locales/zh-TW/core/model-provenance.md +4 -2
- package/bundled/locales/zh-TW/core/pii-classification.md +42 -6
- package/bundled/locales/zh-TW/core/prd-standards.md +4 -2
- package/bundled/locales/zh-TW/core/product-metrics-standards.md +4 -2
- package/bundled/locales/zh-TW/core/release-readiness-gate.md +2 -2
- package/bundled/locales/zh-TW/core/resource-cost-boundary.md +2 -2
- package/bundled/locales/zh-TW/core/retrospective-standards.md +5 -3
- package/bundled/locales/zh-TW/core/reverse-engineering-standards.md +83 -5
- package/bundled/locales/zh-TW/core/runbook.md +2 -2
- package/bundled/locales/zh-TW/core/schema-evolution.md +2 -2
- package/bundled/locales/zh-TW/core/secret-management-standards.md +2 -2
- package/bundled/locales/zh-TW/core/slo-sli.md +2 -2
- package/bundled/locales/zh-TW/core/spec-driven-development.md +2 -0
- package/bundled/locales/zh-TW/core/tech-debt-standards.md +71 -4
- package/bundled/locales/zh-TW/core/turn-completion-integrity.md +190 -0
- package/bundled/locales/zh-TW/core/user-journey-testing.md +2 -2
- package/bundled/locales/zh-TW/core/user-story-mapping.md +2 -2
- package/bundled/locales/zh-TW/core/verification-oracle.md +2 -2
- package/bundled/locales/zh-TW/docs/CHEATSHEET.md +8 -1
- package/bundled/locales/zh-TW/docs/CLI-INIT-OPTIONS.md +29 -68
- package/bundled/locales/zh-TW/docs/FEATURE-REFERENCE.md +25 -15
- package/bundled/locales/zh-TW/docs/USAGE-MODES-COMPARISON.md +1 -2
- package/bundled/locales/zh-TW/integrations/google-antigravity/{INSTRUCTIONS.md → AGENTS.md} +1 -1
- package/bundled/locales/zh-TW/integrations/google-antigravity/README.md +3 -3
- package/bundled/locales/zh-TW/skills/adr-assistant/SKILL.md +1 -1
- package/bundled/locales/zh-TW/skills/atdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/bdd-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/brainstorm-assistant/SKILL.md +22 -12
- package/bundled/locales/zh-TW/skills/brainstorm-assistant/guide.md +12 -9
- package/bundled/locales/zh-TW/skills/code-review-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/commands/brainstorm.md +17 -13
- package/bundled/locales/zh-TW/skills/commands/config.md +0 -1
- package/bundled/locales/zh-TW/skills/commands/init.md +1 -2
- package/bundled/locales/zh-TW/skills/commit-standards/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/contract-test-assistant/SKILL.md +2 -1
- package/bundled/locales/zh-TW/skills/dev-methodology/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/dev-workflow-guide/SKILL.md +1 -1
- package/bundled/locales/zh-TW/skills/knowledge-graph/guide.md +2 -2
- package/bundled/locales/zh-TW/skills/migration-assistant/SKILL.md +1 -1
- package/bundled/locales/zh-TW/skills/observability-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/project-discovery/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/project-structure-guide/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/release-standards/SKILL.md +3 -0
- package/bundled/locales/zh-TW/skills/requirement-assistant/SKILL.md +2 -0
- package/bundled/locales/zh-TW/skills/reverse-engineer/SKILL.md +3 -0
- package/bundled/locales/zh-TW/skills/runbook-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/slo-assistant/SKILL.md +1 -0
- package/bundled/locales/zh-TW/skills/tdd-assistant/SKILL.md +2 -0
- package/bundled/skills/atdd-assistant/SKILL.md +2 -0
- package/bundled/skills/bdd-assistant/SKILL.md +2 -0
- package/bundled/skills/brainstorm-assistant/SKILL.md +31 -13
- package/bundled/skills/brainstorm-assistant/guide.md +9 -6
- package/bundled/skills/code-review-assistant/SKILL.md +1 -0
- package/bundled/skills/commands/brainstorm.md +12 -9
- package/bundled/skills/commands/config.md +0 -1
- package/bundled/skills/commands/init.md +2 -3
- package/bundled/skills/commit-standards/SKILL.md +2 -0
- package/bundled/skills/contract-test-assistant/SKILL.md +1 -0
- package/bundled/skills/dev-methodology/SKILL.md +4 -0
- package/bundled/skills/observability-assistant/SKILL.md +1 -0
- package/bundled/skills/project-discovery/SKILL.md +1 -0
- package/bundled/skills/project-structure-guide/SKILL.md +1 -0
- package/bundled/skills/release-standards/SKILL.md +3 -0
- package/bundled/skills/requirement-assistant/SKILL.md +2 -0
- package/bundled/skills/reverse-engineer/SKILL.md +3 -0
- package/bundled/skills/runbook-assistant/SKILL.md +1 -0
- package/bundled/skills/slo-assistant/SKILL.md +1 -0
- package/bundled/skills/tdd-assistant/SKILL.md +2 -0
- package/bundled/templates/.ai-context.yaml.template +194 -0
- package/bundled/templates/CLAUDE.md.template +145 -0
- package/bundled/templates/DESIGN.md +237 -0
- package/bundled/templates/SKILL-BRIEF-TEMPLATE.md +57 -0
- package/bundled/templates/SKILL-CANDIDATES.md +39 -0
- package/bundled/templates/gates/check-error-exit.mjs +309 -0
- package/bundled/templates/mcp-config.json +10 -0
- package/bundled/templates/methodology-template.yaml +209 -0
- package/bundled/templates/migration-template.md +408 -0
- package/bundled/templates/requirement-checklist.md +410 -0
- package/bundled/templates/requirement-document-template.md +591 -0
- package/bundled/templates/requirement-template.md +881 -0
- package/bundled/templates/reverse-spec-template.md +409 -0
- package/bundled/templates/test-case-template.md +74 -0
- package/bundled/templates/test-plan-template.md +74 -0
- package/package.json +7 -5
- package/src/commands/audit.js +82 -0
- package/src/commands/check.js +66 -10
- package/src/commands/init.js +161 -16
- package/src/commands/update.js +286 -14
- package/src/compilers/claude-code-compiler.js +4 -1
- package/src/config/ai-agent-paths.js +62 -17
- package/src/core/constants.js +42 -11
- package/src/core/manifest.js +201 -3
- package/src/core/paths.js +2 -2
- package/src/i18n/messages.js +6 -29
- package/src/installers/hooks-installer.js +167 -75
- package/src/installers/integration-installer.js +9 -5
- package/src/prompts/init.js +14 -14
- package/src/utils/detector.js +21 -1
- package/src/utils/effect-boundary.js +1093 -0
- package/src/utils/hasher.js +166 -1
- package/src/utils/hook-stats.js +1 -1
- package/src/utils/integration-generator.js +79 -1
- package/src/utils/reference-sync.js +4 -1
- package/src/utils/yaml-generator.js +51 -9
- package/standards-registry.json +31 -8
|
@@ -125,6 +125,9 @@ description: |
|
|
|
125
125
|
|
|
126
126
|
## 参考
|
|
127
127
|
|
|
128
|
+
- [BDD 提取工作流程指南](./bdd-extraction.md) — 要从既有规格里萃取 BDD 场景时读它。
|
|
129
|
+
- [TDD 分析工作流程指南](./tdd-analysis.md) — 要对照场景分析测试覆盖率、找出缺口时读它。
|
|
130
|
+
- 分步流程:[workflow.md](./workflow.md) — 逆向工程的各阶段与顺序(代码扫描、数据模型、配置、测试分析、覆盖率)。真的要跑一次逆向时读它。
|
|
128
131
|
- 详细指南:[guide.md](./guide.md)
|
|
129
132
|
- 核心规范:[reverse-engineering-standards.md](../../../../core/reverse-engineering-standards.md)
|
|
130
133
|
|
|
@@ -45,6 +45,7 @@ description: |
|
|
|
45
45
|
|
|
46
46
|
## 参考
|
|
47
47
|
|
|
48
|
+
- 详细指南:[guide.md](./guide.md) — 运维手册的编写、组织与验证。要写手册、审查运维流程、规划演练或评估覆盖范围时读它。
|
|
48
49
|
- 核心规范:[runbook-standards.md](../../../../core/runbook-standards.md)
|
|
49
50
|
- 相关:[alerting-standards.md](../../../../core/alerting-standards.md)
|
|
50
51
|
- 相关:[postmortem-standards.md](../../../../core/postmortem-standards.md)
|
|
@@ -45,6 +45,7 @@ description: |
|
|
|
45
45
|
|
|
46
46
|
## 参考
|
|
47
47
|
|
|
48
|
+
- 详细指南:[guide.md](./guide.md) — SLI/SLO/错误预算的定义与管理。要定义 SLO、选择 SLI、计算错误预算或设定可靠性目标时读它。
|
|
48
49
|
- 核心规范:[slo-standards.md](../../../../core/slo-standards.md)
|
|
49
50
|
- 相关:[observability-standards.md](../../../../core/observability-standards.md)
|
|
50
51
|
- 相关:[alerting-standards.md](../../../../core/alerting-standards.md)
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../CHANGELOG.md
|
|
3
|
-
source_version: 6.
|
|
4
|
-
translation_version: 6.
|
|
5
|
-
last_synced: 2026-
|
|
3
|
+
source_version: 6.9.0
|
|
4
|
+
translation_version: 6.9.0
|
|
5
|
+
last_synced: 2026-09-14
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -17,6 +17,50 @@ status: current
|
|
|
17
17
|
|
|
18
18
|
## [Unreleased]
|
|
19
19
|
|
|
20
|
+
## [6.9.0] - 2026-09-14
|
|
21
|
+
|
|
22
|
+
### 採用者升級注意
|
|
23
|
+
|
|
24
|
+
- **uds update 不再自動刪除檔案;會列出可移除的 UDS 舊檔,加 --prune 才會刪,且只刪 UDS 自己寫過的檔案。原本依賴自動清檔的流程請加上 --prune。**(#168、#165,詳見「修正」)
|
|
25
|
+
- **--content-mode 給了不認得的值,現在會印出警告並照舊使用 index(6.8.0 也是產生 index 的內容);7.0.0 起會改成直接報錯。** `--content-mode full` 已棄用,會解析為 `index` 並附說明。(詳見「棄用」)
|
|
26
|
+
- **以 `uds init -y` 安裝的 Codex、OpenCode 等非 Claude 工具,技能現在會裝進它們自己的目錄**(例如 Codex 是 `.agents/skills/`),不再裝進 `.claude/skills/`。既有安裝跑 `uds update` 會自動遷移。(詳見「修正」)
|
|
27
|
+
- **Antigravity 現在會拿到 `.agents/skills/` 與 `.agents/AGENTS.md`**,以前是什麼都沒有、指示檔寫成 `INSTRUCTIONS.md`。Antigravity 只在該目錄是已登記的專案時才會讀 `.agents/`,`uds init` 會印出這個提示。
|
|
28
|
+
- **6.8.0 以前 uds init --with-hooks 寫進 .claude/settings.json 的 hook 是從未執行的字串格式,uds update 不會處理 hook,重跑 uds init --with-hooks 也不會刪掉舊項目與 scripts/hooks/*.js。要取得可用的 hook,請重跑 uds init --with-hooks,並可手動刪除舊的 .js 項目。**
|
|
29
|
+
|
|
30
|
+
### 修正
|
|
31
|
+
|
|
32
|
+
- **`uds update` 不再靠「查一張雜湊表」來決定檔案是誰的(XSPEC-384,issue [#165](https://github.com/AsiaOstrich/universal-dev-standards/issues/165) 與 [#168](https://github.com/AsiaOstrich/universal-dev-standards/issues/168))。** 兩位使用者對同一支指令回報了方向相反的缺陷:它刪掉了使用者手寫放在 `.standards/` 下的專案文件,沒有警告、沒有 diff、沒有詢問、沒有備份(#168,是逐行比對 `git status` 才發現的);同時它把 registry 已經移除的標準留在 manifest 與磁碟上,而 `upstream.version` 照樣前進到「最新」(#165)。兩者都源自同一個布林值在回答兩個彼此獨立的問題——**這個檔是不是 UDS 寫的**、**它現在還是不是現行標準**——而每個 issue 各撞上這個超載軸的一端。所有權現在改成在 UDS 寫入的當下記錄,存進 manifest 新增的 `provenance` 欄位,並以複製動作實際回傳的路徑為鍵,而不是從來源檔名重新推算的路徑(正是那個重新推算,讓 `fileHashes` 裡出現五筆 `.standards/options/<name>.ai.yaml`,而真正的檔案住在 `options/<category>/<name>.ai.yaml`)。provenance 是唯增的,`fileHashes` 是當前狀態;若兩者同進同退,provenance 會在同一刻一起失效,也就毫無作用。刪除現在必須兩件事同時成立,其餘每一種組合一律保留,**並印出保留的理由**。無法判定所有權時歸向保留——那正是舊程式不肯選的那一邊。既有安裝沒有 provenance,因此首次升級無從歸屬、也不會刪任何東西;provenance 只在一次完整寫入全套標準的執行結束時才建立。刪除另外需要新的 `--prune` 旗標,刻意不用 `--yes`:`--yes` 會被設在 CI 裡,讓它一併授權刪除,等於正好在沒有人看得到的地方把破壞性路徑打開。「預設就刪」的分階段策略放在單一具名常數(`PRUNE_POLICY`),因為 XSPEC-384 §4 尚未裁決。每一份刪除報告都印出分母——檢查了幾個、我方擁有幾個、非我方幾個、判不了幾個、排除幾個以及為什麼——因為一份只列出動作對象的報告,與「它只看到這幾個」無從分辨。兩個 issue 都由先證明會紅的測試釘住。
|
|
33
|
+
- **九個工具裡有八個,技能被裝進它們不會讀的目錄。** 非互動路徑(`uds init -y`)下,除了 Claude Code 以外每個能裝技能的工具,技能都被寫進 `.claude/skills/`;一個 codex repo 下 `--mode skills -y` 會得到零個技能、零則訊息。現在「能不能裝技能」與「要不要走 marketplace」都改成問路徑表;偵測到、但沒有查證路徑的工具什麼都不裝而且會出聲;`uds update` 轉換舊 manifest 時會重新推導工具,不再假設 `claude-code`。Codex 那句未經查證的 `fallbackSkillsPath: '.claude/skills/'` 已移除。互動流程從來沒有這個問題。
|
|
34
|
+
- **Roo Code 永遠裝不起來。** 路徑表裡有它,偵測器裡沒有;它的識別字在一張表叫 `roo`、其他地方都叫 `roo-code`,於是 `uds init` 把指示寫進根目錄的 `roo-code.md`。偵測改用 `.roo/` 與 `.roorules`(刻意不用 `.clinerules`,那是 Cline 自己的標記);技能也不再退回 `.claude/skills/`,因為 Roo Code 文件列出的位置裡沒有它。依據是 Roo Code 的文件,沒有在真的 Roo Code 上實測。
|
|
35
|
+
- **Antigravity:UDS 六個月來什麼都沒幫它裝,而且寫的指示檔是它不會讀的那一份(XSPEC-355 OQ6)。** 技能改裝進 `.agents/skills/`、指示改寫進 `.agents/AGENTS.md`,由工具的二進位檔、隨附說明文件、以及一次帶誘餌路徑的實跑三方確認。它的 tier 從 `minimal` 升為 `partial`。
|
|
36
|
+
- **UDS 至今出貨的每一支 hook 都是死的,而採用者拿到四支壞掉的 hook。** hook 項目寫成裸字串(只有物件形式會跑);`scripts/hooks` 沒有進 npm 套件;hook 是 ESM `.js`,在 `"type": "commonjs"` 下會失敗(改為 `.mjs`);commit message 驗證掛在 `UserPromptSubmit`,每打一句話就跑一次、每次 exit 1(改掛 `PreToolUse(Bash)`,只看真正的 `git commit -m`)。
|
|
37
|
+
- **`uds check` 的還原會拿一份過期模板蓋掉生成的整合檔。** Claude Code 那份是 140 行、最後修改於 2026-03-25 的檔案。還原現在改用安裝器記下的設定重新生成,受管區塊外的內容不動;Antigravity 與 Gemini CLI 第一次有了還原路徑,Codex 的後備來源也不再指向不存在的目錄。
|
|
38
|
+
- **Codex/OpenCode 的 `AGENTS.md` 沒有揭露句。** 2026-08-18 的揭露修正只到了兩個產生器中的一個;選 codex 或 opencode 時,`AGENTS.md` 走的是另一個。兩種語言、兩種輸出格式都已修正。
|
|
39
|
+
- **cline、windsurf、roo-code 與 Antigravity 的整合檔只寫「照 commit-message 規則」,沒有寫出規則本身。** 格式與合法型別現在直接寫在檔案裡,與 Codex 那份原本的做法相同。
|
|
40
|
+
|
|
41
|
+
### 新增
|
|
42
|
+
|
|
43
|
+
- **`turn-completion-integrity`——agent 不得在說了下一步之後、沒做就結束回合。** 由 Stop hook 在回合結束時執法,而不是寫成指令。偵測器附英文與 zh-TW 語言包及做過突變測試的語料;它會讀使用者的最後一則訊息,所以被叫停不會被當成未兌現的承諾;逐項列出「誰卡在誰身上」的清單被認得是合法的結束方式;「做完跟我說,我再驗」被當成條件式。`uds init --with-hooks` 現在會在你的語言沒有語言包時警告,因為在未列出的語言下,hook 裝好了卻不可能觸發。含 zh-TW 與 zh-CN 翻譯。
|
|
44
|
+
- **`deferred-item-exit`——六條標準會產出延後項目,而沒有一條說那些項目要去哪(XSPEC-391)。** 一位採用者的一次設計工作產出了一份 ADR 與一份規格,其中帶有五個標為「待決定」/「另案處理」/「不在 v1」的項目,而**五項全都沒有進入任何追蹤系統**。原因不是健忘。對會產出這類項目的六條標準——`adr-standards`、`spec-driven-development`、`retrospective-standards`、`feature-discovery-standards`、`code-review-checklist`、`acceptance-criteria-traceability`——grep `issue|tracker|backlog|task id|work item` 共 13 個命中,而**沒有任何一個是出口**:ADR 的 `Technical Story` 是輸入參照、retrospective 把 tracker 當指標來源、feature-discovery 把工單當需求輸入、AC-traceability 只對外部阻塞的覆蓋要求連結,而 code-review 的 8 個命中全是英文單字 "issues",意思是「問題」。每條標準都說明如何把自己的文件寫好;文件寫完就是終點。新標準把缺少的那個關係陳述一次——延後項目在文件之外有一個可追溯的出口,而文件帶著那個出口的識別碼——六條產出端標準加上 `brainstorm-assistant` skill 各自取得**一行指向它的指標,而不是一份副本**,因為同一條規則的六份副本會往六個方向腐壞。**載體刻意不指定**:issue、受追蹤的 TODO、manifest 的一列、backlog 檔案裡的一行都符合,判準是「這個項目離開文件了嗎」,永遠不是「用了哪個工具」。三個發現決定了條文。第一,出口必須在產出該文件的那次變更落地*之後*仍然解析得到——兩個觀察到的洩漏滿足其他所有條件,仍然遺失了項目(待辦寫進一個會被本次合併關閉的 issue;待辦寫進出口的留言,被後續留言推出視線)。第二,**連結存在不等於連結有效**:回報者自己的閘門會放行他最強的那個例子——一份寫著「與 issue #19 一併決定」的文件,而 #19 裡根本沒有這件事——所以 DEX-005/006 要求「有連結且內容已驗證」與「有連結、內容未驗證」永遠不得印出同一個綠,因為一個被回報成通過的未知,比一個被回報成未知的未知更糟。第三,錨點是文件的**結構**(ADR 的 `Consequences`、規格的範圍外章節、retrospective 的 `Action Items`),不是它的措辭:結構可以窮舉,措辭清單不行,所以 DEX-008 要求任何措辭清單都要宣告其涵蓋率未知,DEX-009 要求任何窗口大小(「3 行以內」)都要載明來歷,否則標為未校準。依 DEC-049,這條標準完全寫成「必須存在的關係」,絕不寫成「必須維持它的機制」——而且它在自己的本文裡明白寫出 **UDS 不為它提供任何閘門**,因為一條陳述了規則卻沒有東西執行它的標準,不承認這一點時比承認時更糟。`adr-standards` 另外補上一條它從未陳述過的邊界(對它 grep `acceptance criteria|\bAC\b|驗收` 得到**零**命中,對照組 `acceptance-criteria-traceability` 為 84 個命中):**驗收標準只在一處維護——SPEC**,ADR 以連結指向它——被複製的清單有兩個擁有者,其中一個永遠不會被更新,實測後果是工作出貨後 ADR 裡的勾選框全部仍是未勾選,而只讀規格的覆蓋率工具看不到它。
|
|
45
|
+
- **`AUTH_SCOPE_EXTRACTION`——租戶界限是一個 `WHERE` 子句,而遷移流程裡沒有任何東西強迫你去找它(`reverse-engineering-standards` 1.3.0,issue [#166](https://github.com/AsiaOstrich/universal-dev-standards/issues/166))。** 一次真實的 PHP → C# 遷移中,一個以租戶為界的帳號列表 endpoint 在重寫過程中弄丟了它的隔離述詞:依角色限縮範圍被換成粗糙的「這個帳號是不是任何一個已啟用的管理員?」檢查,於是不論是誰在問,它都回傳資料庫裡的每一個帳號。它出貨了、通過了所有既有測試(那個方法一個測試都沒有),最後是客戶回報「我看到了不該看到的帳號資訊」才浮現。`test-completeness-dimensions` 的維度 4 早就點名跨租戶存取,所以缺的從來不是維度,缺的是一個在遷移當下強迫想起它的步驟。有三個性質讓這一類缺陷穿過每一道閘門:那條安全關鍵的程式碼因為住在查詢裡而非請求/回應契約裡,讀起來就像眾多過濾條件之一;基於形狀的斷言看不見範圍,所以「200 加非空清單」在子句被刪掉之後照樣通過;而程式庫別處存在一支共用 scope resolver 會被讀成覆蓋,同時一個新的 call site 正在不呼叫它地重寫這個查詢。新階段與隱含規則掃描並行,機械化地推導出每一個以操作者自身身分為界的述詞——包含由 ORM global scope、repository 基底類別、RLS 政策、注入過濾條件的 middleware 在 SQL 之外執行的範圍,因為只 grep SQL 會回報一個比實際更小的集合,而在這裡更小的集合讀起來恰好就像更安全的集合。每個命中都記下 `file:line`、自我綁定與觸發分支;oracle 是「每個角色分支、逐 call site 的述詞等價性」,不是輸出形狀。RE-AUTH-001 要求一個斷言另一操作者紀錄**不存在**的負向測試(附自我檢查:在暫存副本裡把述詞刪掉,若測試還是通過,那它從來就不是在測範圍);RE-AUTH-002 則對任何「移植後等價物未經驗證」的述詞 block cutover。
|
|
46
|
+
- **寫下來的日期現在必須代表某件事(`tech-debt-standards` 1.1.0、`governance-layer` 1.1.0)。** 登記表範本從 1.0.0 起就要求 `Owner` 與 `Target Resolution Date`,而兩份標準裡沒有任何一處說那個日期過了會怎樣——對 `core/tech-debt-standards.md` grep `overdue|past due|expired|exceed` 零命中,而對照組 grep `Owner` 有命中,證明那個「查無」是真的、不是查詢工具壞掉。更嚴重的是 `Registry Storage Options` 把「專用試算表」列為完全合法:一份沒有任何程式讀得到的表格滿足本節其餘每一條要求,它沒有任何地方是錯的——直到日期過了,然後什麼都沒發生。`tech-debt-standards` 新增**到期處置**——到期時只有三種合法處置(做掉/撤銷/延期並寫明理由)、TD-EXP-001..006、明文禁止把到期實作成自動延期或自動關閉(兩者都讓時鐘停止,且都不留下停了的痕跡),以及給跑不動檢查的團隊的合規替代方案**無人看管宣告**。每個儲存選項現在都帶著「在什麼條件下它才合法」;試算表刻意保留,因為它常是出錢的人唯一會打開的格式。`governance-layer` 新增風險接受條款的 `review_by`(`review_by` 已過的接受不是有效條款,pipeline 必須 fail closed,與沒有條款時一樣)、**待裁決事項**(GOV-PD-001..004——待裁決是一種帶時鐘、帶固定列舉標記的受治理狀態,不是自由書寫的散文)、**匯總報告**(GOV-RPT-001..005——通過/失敗/**判不了**分開印出、寫出分母與其推導方式、不得合併成單一分數,因為一個「什麼都不做」與「把工作做完」得分相同的指標,量的不是那份工作),以及**新鮮度指標**(GOV-FRESH-001..004——指標必須指名自己讀的是編輯時間還是對帳時間,兩者不得共用欄位;一份今天剛編輯、從未與現實對過的文件,在其中一個時鐘上是零天、在另一個上是無上限)。兩份標準都在標準本文裡明白寫出 UDS 對這些規則不提供任何檢查器:最低標準不是「去建一支檢查器」,而是「絕不讓一筆記載在無聲中變成無人看管」。
|
|
47
|
+
- **`uds audit --effects` —— 一道去問「這個回報成功的元件,到底做了什麼沒有」的閘門(XSPEC-383 R8)。** 形狀 D:可達、被呼叫、跑得動、回傳 `{ok: true}`,而它什麼都沒碰。R3 的可達性閘門看不見它——**可達性問的是入邊(誰呼叫它),形狀 D 的病灶在出邊(它最終碰到什麼),方向相反**。根因是**宣稱與證據共用同一個作者**:回傳值既是「我做了什麼」也是唯一的證據,而型別系統驗的那個形狀,對真實作與空殼**完全同構**。本閘門走訪每個宣告的實作的呼叫圖,量它是否觸及跨程序邊界。**邊界集合從 runtime 自讀**——由家族根名規則走訪 `builtinModules` 展開(`fs`、`child_process`、`net`/`dgram`/`tls`、`http`/`https`/`http2`、`dns`、`worker_threads`),不是手打清單,因此 `fs/promises` 與未來任何子路徑都不需要改程式;且**每條規則都印出自己展開了幾個**,展開 0 個就是規則過期了。免 import 的全域 API(`fetch`、`WebSocket`、`process.dlopen`)先探測當前 runtime 才納入,這個 Node 沒有的那些也一併印出來。家族**用 glob 宣告**在 `.uds/effect-boundary.json`,**不用檔名清單**——檔名清單在有人加上第七個 adapter 的那一刻就不再為真,而那正是本閘門存在的理由。判定三態:零命中判 RED(家族中位數 > 0 時帶「兄弟有對照組」的佐證;整個家族全為零時**組內比較集體沉默**,報告會明說這個 RED 只由絕對零判準支撐);零命中但帶著無法分類的外部相依則是 **UNDECIDABLE 並 exit 2**——判成綠是 fail-open,判成紅是誣告。依 R7-b,**宣告 `NOT_IMPLEMENTED` 且從不回傳成功形狀的實作是合法的,不需要白名單**——這個連言很重要:只認關鍵字的話,那個字就是每個空殼將來要走的洞,而兩者同時出現的檔案會被**指名判 RED**。R7-c 抽出字串拼接產生的網域(模板內插與 `+` 串接一律折成 `*`,所以 `` `https://${env}.api.acme.example` `` 仍可判定,`` `https://api.${tld}` `` 不可判定),對照**來源可插拔**的持有清單:檔案、環境變數,或**指令**——那正是接註冊商或雲帳戶 DNS zone API 的位置。**宣告了卻讀不到 → exit 2**,絕不當成「清單為空所以什麼都合法」。基線是 **TSV,每列一個到期日**(§7.11.2),格式壞掉的列 exit 2,因為**壞掉的基線不是「沒有基線」**。做的過程中它第一次自測就抓到自己的真缺陷:**type-only import 被當成呼叫圖的邊**,於是空殼繼承了介面檔的邊界命中而判綠——型別 import 編譯後整行消失,把它算成命中是**憑空多出來的綠燈**。那個案例現在由一支專屬對照臂釘住。**它證明不了什麼**:碰到的那個邊界是不是**對的**那一個——打一發裝飾性 log 請求就能過關。那是 R9,本輪未做。UDS 自己沒有效果家族,所以不帶 config 直接跑會 exit 2,這是設計而非故障;CI 跑的是 `--self-test`,十七臂(五個探針對照組、分母、綠、紅、R7-b 濫用、R7-b 豁免、跨檔呼叫圖、邊界金絲雀、網域金絲雀、讀不到清單、空集合、不可判定、探針失效)在一份為本 repo 自己寫的合成語料上各自證明得出來。
|
|
48
|
+
- **一道採用者跑得動的錯誤出口閘門。** `templates/gates/check-error-exit.mjs` 現在隨套件出貨。`uds check` 會在有 `src/` 卻沒有這道閘門的專案上報告,但從不寫入;`uds update` 會說明它是什麼並提議寫入,預設答案是**不要**,檔案已存在時絕不覆蓋。閘門容許一個檔案格式化錯誤訊息,第二個出現時才判紅;設定好之前一律 exit 2。
|
|
49
|
+
- **`brainstorm-assistant`:判官現在需要心智,不只需要座位(XSPEC-388)。** BQS D4 必須同時有獨立 context 與宣告的模型層級才算通過,模型層級只能用 `core/model-selection.md` 的廠商中立標籤表達,指名具體廠商模型即違規。CONVERGE 評審提示改寫為「目標+約束」。沒有移除任何 v3 機制。
|
|
50
|
+
- **`llms.txt` 改為生成,不再手寫。** 由 `uds-manifest.json`、`core/`、`skills/`、`integrations/REGISTRY.json` 與 `cli/package.json` 推導,`--check` 在已提交的檔案差一個位元組時就失敗。
|
|
51
|
+
|
|
52
|
+
### 變更
|
|
53
|
+
|
|
54
|
+
- **P1 與 P3 回到探針集,而它們當初被砍的理由,現在成了另一種錯誤的實例(XSPEC-408)。** 兩者都在 2026-07-23 以「基線已通過」為由退役:在沒有安裝 UDS 的情況下對 Antigravity CLI 1.0.14 執行,模型會先讀檔再回答(P1),也會主動給出自己的推薦(P3)。這些觀察仍然成立;站不住的是退役這個結論。**每一支探針量的是兩件事——一個行為與一個宣告的標記——而被推翻的只有行為。** P1 的退役紀錄自己就寫出了這一點(「剩下的是:UDS 要求明確的 `[Source: <path>]` 標註,而基線用的是 markdown 檔案連結」),接著卻引用 §2.2「探針斷言結構,不斷言用詞」把剩下的部分丟掉。那個讀法不可能正確,因為 **P2 正是靠比對四個字面標籤存活**,而且是整組裡最耐用的探針;§4 自己的總結也早已得出「always-read 層耐用的部分看起來是宣告的形式與內部慣例,而不是知識」,而兩支宣告形式的探針就被砍在它下面幾段。§2.2 現在寫出它本來就該承載的區分:比對模型碰巧寫出的句子,量到的是運氣;比對**標準要求模型印出的標記**,量到的是標準有沒有送達。P1 與 P3 改寫成只問這個較窄的問題,而且兩者現在都會在答案*事實正確但沒有標記*時明確失敗——那正是它們存在要抓的情形。它們的 §2.3 入場基線不花任何一次新執行:留存的 2026-07-23 逐字稿重新計分後,`[Source:` 出現 **0 次**、`[Recommended]` 出現 **0 次**,各自都對照同一個讀取器在同一份檔案裡找到的陽性控制字串,所以那個 0 是「不存在」,而不是搜尋壞掉。`scripts/check-reinstated-probe-baselines.ts` 在每次 CI 執行時重新推導這兩個數字——一個讀過一次就打進文件的 0 是一枚戳,而這個 repo 已經記錄過戳會發生什麼事——其 `--self-test` 臂涵蓋標記出現(紅)、控制字串缺失(判不了,絕不是綠)與空逐字稿(判不了),三者皆經突變確認。**這件事沒有做到的**:提高 n。每支探針一次執行、一個工具、一個前沿模型、重讀一遍。`DELTA-TREND.md` 把這次重新計分記在它自己的子表裡,並明文禁止併入上方的總表;Codex 那一列加註其 50% 指的是*已退役*的 P1/P3——Codex 沒有留存任何 P1/P3 逐字稿,所以不像 Antigravity 有東西可以重新計分。當初讓這些探針被退役的那群對象——採用者在 aider 與 continue-dev 下執行的本機與量化模型——至今仍未被量測過,而一支探針的全部價值,就是在那群對象不再需要這條規則時告訴你。復原探針是把感測器裝回去;它沒有說它會讀到什麼。
|
|
55
|
+
- **技能:每一個兄弟檔現在都能從自己的 `SKILL.md` 一跳到達。** 原本有 13 個兄弟檔(3,193 行)沒有任何東西指向它們,另有 56 個只能經由另一個兄弟檔到達;`skills/` 與各語系樹的 168 個兄弟檔現在全部是一跳,每一條指路都寫明檔案內容與何時該讀。這消除的是結構風險,並不證明兄弟檔真的會被讀。
|
|
56
|
+
- **出貨的 `.ai.yaml` 的 `meta.updated` 改取自來源檔的 git 歷史**;git 查無紀錄時直接省略該欄位,不再用手打的日期或 transform 執行當天。
|
|
57
|
+
- **`governance-layer`:Enforcement Reality 一節現在也點名較舊的風險接受欄位**(`review_by`、`risks_accepted`、`gates_bypassed`)沒有任何程式在讀。
|
|
58
|
+
- **相依套件:** `chalk` 5.6.2 → 6.0.0、`js-yaml` 5.2.1 → 5.2.3(CLI 執行期);`eslint`、`globals`、`lint-staged`、`tsx`(開發用)。
|
|
59
|
+
- **repo 內部驗證(不影響採用者拿到的內容):** 實跑 `uds init` 的採用者指示檔檢查;走訪路徑表每個工具的安裝路徑閘門;實際執行已安裝 Stop hook 的 hook 投遞閘門;比對內容的 bundle parity;skill 觸發面閘門;出貨戳一致性檢查器;翻譯 `source_hash` 棘輪;名稱提及分類器;STATUS.md 矛盾閘門;本 repo 的 `.claude/skills` 副本改為生成;skill 金絲雀儀器(XSPEC-408 R2)與它的首批真跑;P7 探針砍除;bump/sync 往返檢查移到每次 CI;測試套件不再受機器語系影響。
|
|
60
|
+
|
|
61
|
+
### 棄用
|
|
62
|
+
|
|
63
|
+
- **`contentMode: 'full'`——一個既有模式的第二個名字(XSPEC-357 R7)。** manifest schema 接受它、`--content-mode` 提供它、init 提示把它包裝成「拿 context 預算換合規」的取捨(「完整嵌入所有規則、約 10-15 KB、合規率最高」),而且每一個 `partial` 層級的工具都被自動指派它。這些一項都沒有被實作:產生器對模式的唯一判斷是 `=== 'minimal'`,因此 `full` 與 `index` 走同一條分支,**在實測的 24 組(工具 × 語言)組合中寫出逐位元相同的檔案**,且對照組證明該比較確實抓得到差異(`full` 對 `minimal` 在 24 組中全部不同)。它也不可能照宣稱的方式運作——`.standards/` 約 248k token,遠超過任何整合檔案裝得下的量。採用者是在兩個標籤之間選擇同一種行為,而那個標籤承諾了一個不存在的差異;文件甚至以法規理由建議銀行核心系統採用 `full`。**這次棄用對採用者的代價是零**:`--content-mode full` 仍然接受並解析為 `index`(附說明),manifest 中記錄的 `full` 會在下次讀取時改寫為 `index`,而由於兩個模式本來就產生相同的位元組,**任何專案產生的檔案都不會改變**。不認得的模式仍然解析為 `index`,但現在會印出警告並寫明那個值;7.0.0 起會改成直接報錯。`check-adopter-instruction-files.ts` 裡的 `content-mode=full` 情境——正是它「8 個檔案全部逐位元相同」的發現促成了這次移除——一併移除,而不是留著拿 `index` 跟 `index` 比、然後永遠回報「相同」。
|
|
20
64
|
## [6.8.0] - 2026-08-20
|
|
21
65
|
|
|
22
66
|
### 新增
|
|
@@ -14,7 +14,7 @@ status: current
|
|
|
14
14
|
|
|
15
15
|
Universal Development Standards 是一個語言無關、框架無關的文件化標準框架。它提供:
|
|
16
16
|
|
|
17
|
-
- **核心規範** (`core/`):
|
|
17
|
+
- **核心規範** (`core/`):152 個基礎開發標準
|
|
18
18
|
- **AI 技能** (`skills/`):用於 AI 輔助開發的 Claude Code 技能
|
|
19
19
|
- **CLI 工具** (`cli/`):用於採用標準的 Node.js CLI
|
|
20
20
|
- **整合** (`integrations/`):各種 AI 工具的配置
|
|
@@ -15,7 +15,7 @@ status: current
|
|
|
15
15
|
|
|
16
16
|
> **語言**: [English](../../README.md) | 繁體中文 | [简体中文](../zh-CN/README.md)
|
|
17
17
|
|
|
18
|
-
**版本**: 6.
|
|
18
|
+
**版本**: 6.9.0 | **發布日期**: 2026-09-14 | **授權**: [雙重授權](../../LICENSE) (CC BY 4.0 + MIT)
|
|
19
19
|
|
|
20
20
|
語言無關、框架無關的軟體專案文件標準。透過 AI 原生工作流,確保不同技術堆疊之間的一致性、品質和可維護性。
|
|
21
21
|
|
|
@@ -76,7 +76,7 @@ npx universal-dev-standards init
|
|
|
76
76
|
<!-- UDS_STATS_TABLE_START -->
|
|
77
77
|
| 類別 | 數量 | 說明 |
|
|
78
78
|
|----------|-------|-------------|
|
|
79
|
-
| **核心標準** |
|
|
79
|
+
| **核心標準** | 152 | 通用開發準則 |
|
|
80
80
|
| **AI Skills** | 55 | 互動式技能 |
|
|
81
81
|
| **斜線命令** | 51 | 快速操作 |
|
|
82
82
|
| **CLI 指令** | 23 | 專案設定與維護 |
|
|
@@ -195,6 +195,8 @@ Coverage = (5 + 2×0.5) / 8 = 6/8 = 75%
|
|
|
195
195
|
| 基礎設施限制 | 測試環境限制 | 解決方案計畫 |
|
|
196
196
|
| 延後至下一迭代 | 已與利害關係人確認 | Ticket 參照 |
|
|
197
197
|
|
|
198
|
+
> 本標準產出的**延後項目**(`Gaps` 的 Uncovered AC/Partial AC、上表的例外、報告的 `Action Items`)適用 [deferred-item-exit](deferred-item-exit.md)。
|
|
199
|
+
|
|
198
200
|
---
|
|
199
201
|
|
|
200
202
|
## AC 覆蓋率報告格式
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/adr-standards.md
|
|
3
|
-
source_version: 1.
|
|
4
|
-
translation_version: 1.
|
|
5
|
-
last_synced: 2026-
|
|
3
|
+
source_version: 1.1.0
|
|
4
|
+
translation_version: 1.1.0
|
|
5
|
+
last_synced: 2026-08-24
|
|
6
6
|
status: current
|
|
7
7
|
---
|
|
8
8
|
|
|
@@ -10,8 +10,8 @@ status: current
|
|
|
10
10
|
|
|
11
11
|
> **語言**: [English](../../../core/adr-standards.md) | 繁體中文
|
|
12
12
|
|
|
13
|
-
**版本**: 1.
|
|
14
|
-
**最後更新**: 2026-
|
|
13
|
+
**版本**: 1.1.0
|
|
14
|
+
**最後更新**: 2026-08-24
|
|
15
15
|
**適用範圍**: 所有進行架構決策的軟體專案
|
|
16
16
|
**範疇**: universal
|
|
17
17
|
**產業標準**: ISO/IEC/IEEE 42010(架構描述)、TOGAF ADR
|
|
@@ -89,6 +89,23 @@ status: current
|
|
|
89
89
|
- [相關 ADR、SPEC、PR 或外部參考]
|
|
90
90
|
```
|
|
91
91
|
|
|
92
|
+
> 此範本中記下的**延後項目**(`Consequences` 下的既受風險與負面後果、被考慮而未採用的選項)適用 [deferred-item-exit](deferred-item-exit.md)。
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## 驗收標準只在 SPEC 維護一份
|
|
97
|
+
|
|
98
|
+
一份 ADR 記錄的是**決策**,它不帶自己的一份驗收標準。當一個決策有驗收標準時,
|
|
99
|
+
它們**只在一處維護——SPEC**,而 ADR 以連結(`Technical Story` 或 `Links`)指向它。
|
|
100
|
+
|
|
101
|
+
一份被複製的 AC 清單有兩個擁有者,而只有其中一個會被更新。實測後果是:
|
|
102
|
+
實作完成、SPEC 的勾選框打勾,ADR 那一份**整份留在未勾選狀態**——
|
|
103
|
+
讀 ADR 的人於是認為什麼都沒做,而讀 SPEC 的 AC 覆蓋率工具**根本看不到 ADR 裡那一份**。
|
|
104
|
+
|
|
105
|
+
> 本條是關於 **AC 在哪裡維護**的邊界規則,不涉及 AC 的寫法或標註慣例。
|
|
106
|
+
> AC 格式見 [spec-driven-development](spec-driven-development.md);
|
|
107
|
+
> AC 對驗證項的可追溯性見 [acceptance-criteria-traceability](acceptance-criteria-traceability.md)。
|
|
108
|
+
|
|
92
109
|
---
|
|
93
110
|
|
|
94
111
|
## ADR 編號
|
|
@@ -187,6 +204,8 @@ docs/adr/
|
|
|
187
204
|
- [ ] **狀態**設定正確
|
|
188
205
|
- [ ] **連結**到相關工件
|
|
189
206
|
- [ ] 檔案存放在 `docs/adr/` 且命名正確
|
|
207
|
+
- [ ] **沒有任何驗收標準被複製進 ADR** — 一律連結到維護它們的那份 SPEC
|
|
208
|
+
- [ ] 每一個**延後項目**都載明其出口的識別字([deferred-item-exit](deferred-item-exit.md))
|
|
190
209
|
|
|
191
210
|
---
|
|
192
211
|
|
|
@@ -200,6 +219,8 @@ docs/adr/
|
|
|
200
219
|
| 沒有後果分析 | 分析不完整 | 一定要列出正面和負面結果 |
|
|
201
220
|
| 背景模糊 | 對未來讀者無用 | 包含具體的限制條件和驅動因素 |
|
|
202
221
|
| 編輯已接受的 ADR | 歷史遺失 | 改用取代(Supersede)而非編輯 |
|
|
222
|
+
| 把 SPEC 的驗收標準複製進 ADR | 兩個擁有者、只有一個會更新;ADR 那份留在未勾選,覆蓋率工具也看不到它 | 只在 SPEC 保留一份,並以連結指向 |
|
|
223
|
+
| 既受風險沒有出口 | ADR 是唯一的載體,而它現在已被核准 | 給它一個出口,並在此載明該出口 |
|
|
203
224
|
|
|
204
225
|
---
|
|
205
226
|
|
|
@@ -286,6 +286,8 @@ Is there a specific reason for this approach?
|
|
|
286
286
|
|
|
287
287
|
> 此評論前綴方式與 [Conventional Comments](https://conventionalcomments.org/) 規範一致,該規範在團隊和工具間標準化了審查回饋格式。
|
|
288
288
|
|
|
289
|
+
> Review 產出的**延後項目**(本次未改而被接受的非阻斷留言:`⚠️ IMPORTANT`、`💡 SUGGESTION`、`[SUGGESTION]`、`[NIT]`)適用 [deferred-item-exit](deferred-item-exit.md)。
|
|
290
|
+
|
|
289
291
|
### 替代方案:文字標籤
|
|
290
292
|
|
|
291
293
|
對於偏好純文字標籤(無 emoji)的團隊:
|
|
@@ -1,20 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
source: ../../../core/cross-flow-regression.md
|
|
3
|
-
source_version: 1.0.
|
|
4
|
-
translation_version: 1.0.
|
|
5
|
-
last_synced: 2026-
|
|
6
|
-
source_hash:
|
|
7
|
-
status:
|
|
3
|
+
source_version: 1.0.1
|
|
4
|
+
translation_version: 1.0.1
|
|
5
|
+
last_synced: 2026-07-23
|
|
6
|
+
source_hash: 33da58d89648
|
|
7
|
+
status: current
|
|
8
8
|
---
|
|
9
9
|
|
|
10
10
|
# 跨流程回歸(Cross-Flow Regression)
|
|
11
11
|
|
|
12
12
|
> **語言**:[English](../../../core/cross-flow-regression.md) | 繁體中文
|
|
13
13
|
|
|
14
|
-
**版本**:1.0.
|
|
15
|
-
**最後更新**:2026-
|
|
14
|
+
**版本**:1.0.1
|
|
15
|
+
**最後更新**:2026-06-18
|
|
16
16
|
**適用範圍**:所有具有多個 user flow 或業務流程的軟體專案
|
|
17
17
|
**Scope**:universal
|
|
18
|
+
**Owning Spec**:XSPEC-294(與 flow-based-testing 互補;不重疊)
|
|
18
19
|
**業界標準**:ISTQB Advanced Test Analyst(Regression Test Strategy)
|
|
19
20
|
**參考資料**:`core/flow-based-testing.md`、`core/testing-standards.md`
|
|
20
21
|
|
|
@@ -0,0 +1,251 @@
|
|
|
1
|
+
---
|
|
2
|
+
source: ../../../core/deferred-item-exit.md
|
|
3
|
+
source_version: 1.0.0
|
|
4
|
+
translation_version: 1.0.0
|
|
5
|
+
last_synced: 2026-08-24
|
|
6
|
+
source_hash: e76ef99c88a5
|
|
7
|
+
status: current
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# 延後項目出口標準
|
|
11
|
+
|
|
12
|
+
> **Language**: [English](../../../core/deferred-item-exit.md) | 繁體中文
|
|
13
|
+
|
|
14
|
+
**版本**: 1.0.0
|
|
15
|
+
**最後更新**: 2026-08-24
|
|
16
|
+
**適用**: 任何標準要求產出、且可能記下延後項目的文件
|
|
17
|
+
**範圍**: universal
|
|
18
|
+
|
|
19
|
+
---
|
|
20
|
+
|
|
21
|
+
## 目的
|
|
22
|
+
|
|
23
|
+
有一批標準會要求產出**會產生延後項目**的文件——ADR 的既受風險與「之後再決定」、
|
|
24
|
+
規格的未納入清單、retrospective 的 action items、探索矩陣裡未確認的候選、
|
|
25
|
+
review 的非阻斷建議、AC 報告的缺口。每一條標準都規定了那份文件要怎麼寫好,
|
|
26
|
+
**沒有一條規定那些項目之後去哪**。
|
|
27
|
+
|
|
28
|
+
於是它們哪裡也沒去。項目被記下、文件被核准,**那筆紀錄就是終點**。
|
|
29
|
+
沒有東西會再提起它,因為承載它的只有一份已被視為完成的檔案裡的一段文字。
|
|
30
|
+
|
|
31
|
+
**本標準補上那個缺失的關係:延後項目必須離開文件。**
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
35
|
+
## 本標準的寫法,以及為什麼這樣寫
|
|
36
|
+
|
|
37
|
+
**讀下面任何一條要求之前先讀這一段。它拘束它們全部。**
|
|
38
|
+
|
|
39
|
+
UDS 定義**活動**,採用層負責**編排**(DEC-049;見 [MIGRATION-v6](../../../docs/MIGRATION-v6.md) §2)。
|
|
40
|
+
6.0.0 依該決策移除八條機器可讀標準,其中七條正是工作流狀態協定。
|
|
41
|
+
**一份寫成編排協定的標準屬於採用層,不屬於這裡。**
|
|
42
|
+
|
|
43
|
+
本標準受此拘束的分界:
|
|
44
|
+
|
|
45
|
+
| 這裡容許——**what** | 這裡不容許——**how** |
|
|
46
|
+
|---|---|
|
|
47
|
+
| artefact 之間必須存在的關係 | artefact 必須通過的狀態機 |
|
|
48
|
+
| 一項宣稱要算作證據所必須具備的性質 | 必須產出該宣稱的 pipeline 階段 |
|
|
49
|
+
| 一份回報必須保留的區別 | 回報格式、工具或 schema |
|
|
50
|
+
| 延後項目必須有出口 | 哪一個 issue tracker/看板/檔案是那個出口 |
|
|
51
|
+
|
|
52
|
+
**下面每一條要求都寫成「必須存在什麼關係」,絕不寫成「應使用什麼機制維持它」。**
|
|
53
|
+
UDS 本來就有一整類這個形狀的標準——[acceptance-criteria-traceability](acceptance-criteria-traceability.md)
|
|
54
|
+
要求每一條 AC 都能被某個測試到達,而不規定用什麼維持那條可達性。
|
|
55
|
+
本標準是同一個形狀,套用在延後項目上。
|
|
56
|
+
|
|
57
|
+
**直說它的後果**:本標準**不附帶任何閘門**。它只說什麼必須為真。
|
|
58
|
+
有沒有東西在檢查,是採用專案的決定——而 DEX-004 是用來讓那個決定沒辦法被默默做掉的。
|
|
59
|
+
|
|
60
|
+
---
|
|
61
|
+
|
|
62
|
+
## 不變量
|
|
63
|
+
|
|
64
|
+
**一個記錄在文件裡的延後項目,必須在該文件之外有一個可追蹤的出口,而該出口的識別字必須寫在文件裡、緊鄰該項目。**
|
|
65
|
+
|
|
66
|
+
### 什麼算延後項目
|
|
67
|
+
|
|
68
|
+
任何被該文件記錄為**現在不做、不由這份文件做**的項目。措辭變化無窮——
|
|
69
|
+
「待決定」「第一版未納入」「另案處理」「尚未實作」「之後再看」「既受風險」「這個我們先放著」。
|
|
70
|
+
**措辭不是定義**;定義是該項目相對於「這份文件所了結的那份工作」的狀態。見[錨點](#錨點走訪結構不走訪措辭)。
|
|
71
|
+
|
|
72
|
+
### 什麼算出口
|
|
73
|
+
|
|
74
|
+
**刻意不指定。** issue、tracked TODO、manifest 條目、backlog 檔案的一列、
|
|
75
|
+
專案已經在跑的任何工單系統——全都算。判準是**「這個項目離開文件了嗎」**,不是「用了什麼工具」。
|
|
76
|
+
|
|
77
|
+
一個出口要滿足不變量,下列三條必須同時成立:
|
|
78
|
+
|
|
79
|
+
| # | 關係 | 何時失敗 |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| 1 | 出口存在於這份文件之外 | 該項目唯一的紀錄就是這份文件的文字 |
|
|
82
|
+
| 2 | 出口可由一個寫在文件裡的識別字定址 | 文件寫著「之後再處理」而沒有任何可定址的東西 |
|
|
83
|
+
| 3 | 產出該文件的那次變更落地**之後**,出口仍然解析得到 | 出口被同一次變更關閉、刪除或取代 |
|
|
84
|
+
|
|
85
|
+
第 3 條不是假想。兩個實際觀察到的洩漏,都同時滿足第 1、2 條而仍然遺失項目:
|
|
86
|
+
|
|
87
|
+
- 待辦寫進**會被本次合併關閉的 issue**。文件指向一筆在工作被接受的當下就停止存在的紀錄。
|
|
88
|
+
- 待辦寫進出口的**留言而非本體**,被後續留言推走。出口解析得到;讀出口卻讀不到那個項目。
|
|
89
|
+
|
|
90
|
+
---
|
|
91
|
+
|
|
92
|
+
## 要求
|
|
93
|
+
|
|
94
|
+
| ID | 要求 | 嚴重度 |
|
|
95
|
+
|---|---|---|
|
|
96
|
+
| **DEX-001** | 文件裡記下的延後項目,在文件之外有可追蹤的出口,且文件在該項目旁載明出口識別字 | error |
|
|
97
|
+
| **DEX-002** | 產出該文件的變更落地之後,出口仍然解析得到,且仍承載該項目 | error |
|
|
98
|
+
| **DEX-003** | 本標準的每一條要求都可表述為 artefact 之間可判定的關係。不能如此表述的要求不得進入本標準 | error |
|
|
99
|
+
| **DEX-004** | 被提出作為本標準證據的檢查,已被觀察到對刻意違規的樣本回報失敗。從未紅過的檢查不是可採信的證據 | error |
|
|
100
|
+
| **DEX-005** | 驗證確立「那個出口**承載這個項目**」——而不只是「識別字解析得到」 | error |
|
|
101
|
+
| **DEX-006** | 「有連結且已驗證內容」與「有連結但內容未驗證」回報為兩個相異狀態。合併為單一通過狀態即不滿足 DEX-005 | error |
|
|
102
|
+
| **DEX-007** | 「這裡有一個延後項目」的錨點,是可由該文件自身既定結構窮舉出來的位置 | error |
|
|
103
|
+
| **DEX-008** | 以措辭清單補充結構錨點時,明示其涵蓋率未知,且其綠燈不被回報為完整 | warning |
|
|
104
|
+
| **DEX-009** | 該判定所用的任何窗口或閾值,載明來歷,或標為未校準 | warning |
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## 一條無法被檢查的要求,不是這裡的要求
|
|
109
|
+
|
|
110
|
+
**DEX-003 是對本標準自身內容的約束。** 上面每一條都指名了 artefact 與它們之間的關係,
|
|
111
|
+
使得讀的人——或專案自己建的東西——可以判定它成不成立。
|
|
112
|
+
**一條無法被判定的要求不屬於這裡**,不論它聽起來多正確。
|
|
113
|
+
|
|
114
|
+
理由是量出來的,不是美學:在這一類規則之下第一次大批產出文件,**五項延後項目全部漏掉**。
|
|
115
|
+
規則被理解了,人也稱職。缺的是任何一個能分辨「滿足它的文件」與「不滿足它的文件」的東西。
|
|
116
|
+
|
|
117
|
+
### 一支從未紅過的檢查
|
|
118
|
+
|
|
119
|
+
**DEX-004 講的是什麼算證據,不是要你去建什麼。**
|
|
120
|
+
**一支從未失敗過的檢查,與一支不可能失敗的檢查,輸出一模一樣。**
|
|
121
|
+
在它被觀察到「對一個刻意違規的樣本回報失敗」之前,它不是「規則成立」的證據,
|
|
122
|
+
只是「有東西跑過」的證據。
|
|
123
|
+
|
|
124
|
+
證明檢查非空跑的做法、以及為何必須逐子集而非整體進行,見 [class-level-fix](class-level-fix.md);
|
|
125
|
+
「exit 0」為何不等於「它在工作」,見 [verification-evidence](verification-evidence.md)。
|
|
126
|
+
**兩者都不在此複述。**
|
|
127
|
+
|
|
128
|
+
---
|
|
129
|
+
|
|
130
|
+
## 連結存在,不等於連結有效
|
|
131
|
+
|
|
132
|
+
一個寫在延後項目旁邊的識別字,製造出「有出口」的外觀。
|
|
133
|
+
那個出口**有沒有承載**這個項目,是另一個問題,而兩個答案不能互換。
|
|
134
|
+
|
|
135
|
+
命名這條規則的實例:文件寫著「與 issue #19 一併決定」,而 #19 裡根本沒有這件事。
|
|
136
|
+
上面第 1、2、3 條全部成立,項目照樣不見了。
|
|
137
|
+
**一道只問識別字在不在的閘門會放行這份文件**,而它印出的綠燈,
|
|
138
|
+
與它印在出口都為真的文件上的綠燈,逐位元相同。
|
|
139
|
+
|
|
140
|
+
### 兩態,不得合併為一
|
|
141
|
+
|
|
142
|
+
確立 DEX-005 需要讀出口的內容,成本明顯高於讀文件。
|
|
143
|
+
**DEX-005 不要求一步到位做到每一處。** 它要求的是「差別必須看得見」:
|
|
144
|
+
|
|
145
|
+
| 狀態 | 意義 |
|
|
146
|
+
|---|---|
|
|
147
|
+
| **有連結且已驗證內容** | 讀過出口,它承載這個項目 |
|
|
148
|
+
| **有連結但內容未驗證** | 識別字在;它有沒有承載這個項目,未知 |
|
|
149
|
+
| **無出口** | 違反 DEX-001 |
|
|
150
|
+
|
|
151
|
+
把前兩態合併成單一通過數,不是通往規則的捷徑——那正是這條規則要防的缺陷,
|
|
152
|
+
被制度化並給了一個編號。**一個被回報成通過的未知,比一個被回報成未知的未知更糟**,
|
|
153
|
+
因為後者還找得到。
|
|
154
|
+
|
|
155
|
+
若一個專案今天只做得起便宜的那一半,那屬於 [verification-evidence](verification-evidence.md) VE-012
|
|
156
|
+
與 [class-level-fix](class-level-fix.md) CLF-008 已經在管的涵蓋缺口:
|
|
157
|
+
**必須帶日期登記,不能只在文字裡揭露一次。** 此處不複述。
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## 錨點:走訪結構,不走訪措辭
|
|
162
|
+
|
|
163
|
+
判定「這裡有沒有延後項目」時,**走訪文件的結構**。
|
|
164
|
+
結構由「要求產出這份文件的那條標準」所定義,因此可窮舉。
|
|
165
|
+
**措辭不可窮舉,而且沒有任何一張措辭清單能被證明是完整的。**
|
|
166
|
+
|
|
167
|
+
| 文件 | 延後項目出現的結構位置 |
|
|
168
|
+
|---|---|
|
|
169
|
+
| ADR | `Consequences` → **Bad**/**Accepted risk**;`Links`;被考慮而未採用的選項 |
|
|
170
|
+
| 規格 | 未納入/不在本版的段落;open questions;待確認的 assumptions |
|
|
171
|
+
| Retrospective | `Action Items`;`Previous Action Items Review` 中仍為 Open 的列;附理由 Cancelled 的項目 |
|
|
172
|
+
| 功能探索 | 零打勾候選;`dead_code_candidates`;升級為人工觀察的候選 |
|
|
173
|
+
| Code review | 本次未改而被接受的非阻斷留言類別(`⚠️ IMPORTANT`、`💡 SUGGESTION`、`[SUGGESTION]`、`[NIT]`)|
|
|
174
|
+
| AC 覆蓋率報告 | `Gaps` → **Uncovered AC**/**Partial AC**;`Threshold Exceptions`;`Action Items` |
|
|
175
|
+
|
|
176
|
+
### 仍然要用措辭清單時
|
|
177
|
+
|
|
178
|
+
合法——結構走訪抓得到待在自己段落裡的項目,抓不到被丟進一段敘述文字裡的那一個。
|
|
179
|
+
但此時 **DEX-008 隨即適用**:該清單的涵蓋率未知,這件事必須明說,
|
|
180
|
+
而它的綠燈不得被讀成「沒有漏掉任何延後項目」。
|
|
181
|
+
一張含「待決定」與「未納入」的清單,對「這一點我們先放著」這句話**什麼也沒說**。
|
|
182
|
+
|
|
183
|
+
**一道自行列舉範圍的閘門,正確到有人新增第四個成員為止**——
|
|
184
|
+
[class-level-fix](class-level-fix.md) 是這個失敗的通則形式。
|
|
185
|
+
措辭清單在構造上就是那個失敗;它可以用,但不能信。
|
|
186
|
+
|
|
187
|
+
### 閾值必須帶著來歷
|
|
188
|
+
|
|
189
|
+
**DEX-009。** 「識別字必須出現在項目後 3 行內」這類判準,決定了建立其上的一切的召回率。
|
|
190
|
+
若沒有東西記下 3 是怎麼來的,就沒有人能評估把它改成 2 或 5,
|
|
191
|
+
也沒有人分得出它是量出來的還是猜的。
|
|
192
|
+
**寫下那個數字的來歷,或標為未校準。** 兩者都可接受;沉默不行。
|
|
193
|
+
|
|
194
|
+
**一個沒有來歷的閾值,是一個沒有人能檢查的決定。**
|
|
195
|
+
|
|
196
|
+
---
|
|
197
|
+
|
|
198
|
+
## 反模式
|
|
199
|
+
|
|
200
|
+
| 反模式 | 為什麼失敗 |
|
|
201
|
+
|---|---|
|
|
202
|
+
| 記下延後項目,然後核准文件 | 文件是唯一的載體,而它現在被視為完成了 |
|
|
203
|
+
| 出口被產出該文件的同一次變更關閉 | 指標在工作進行中解析得到,工作結束後就不再解析得到 |
|
|
204
|
+
| 項目寫進出口的留言,不是出口本體 | 出口解析得到;讀出口卻讀不到那個項目 |
|
|
205
|
+
| 檢查識別字在不在 | 「在」與「對」印出同一個綠 |
|
|
206
|
+
| 已驗證與未驗證的連結共用一個通過狀態 | 把上一列的缺陷變成永久的,還給了它一個編號 |
|
|
207
|
+
| 把措辭清單當成「延後」的定義 | 正確到有人換一種寫法為止,而沒有東西會說 |
|
|
208
|
+
| 沒有記下來歷的窗口大小 | 它決定整個判定的召回率,而沒有人能檢查它 |
|
|
209
|
+
| 從未被觀察到失敗的檢查 | 與一支不可能失敗的檢查無從分辨 |
|
|
210
|
+
|
|
211
|
+
---
|
|
212
|
+
|
|
213
|
+
## 什麼在執行本標準
|
|
214
|
+
|
|
215
|
+
**UDS 側沒有任何東西在執行,而這件事是被記錄的,不是被暗示的。**
|
|
216
|
+
UDS 陳述關係;有沒有東西去判定它,依上面的[寫法約束](#本標準的寫法以及為什麼這樣寫),是採用專案的決定。
|
|
217
|
+
|
|
218
|
+
本標準做的事,是讓那個決定顯形:DEX-003 保證這裡每一條**能**被判定,
|
|
219
|
+
DEX-004 固定「一次判定要算數需要什麼」,DEX-006/DEX-008 固定「一次不完整的判定容許印出什麼」。
|
|
220
|
+
一個採用本標準而什麼都沒建的專案**並未違反它**——
|
|
221
|
+
但它同樣不能宣稱自己的延後項目有出口,因為它沒有任何可採信的證據說明有。
|
|
222
|
+
|
|
223
|
+
**重啟條件**:若 UDS 開始出貨那些文件本身,而不只是出貨要求產出它們的標準,
|
|
224
|
+
走訪[錨點](#錨點走訪結構不走訪措辭)那張表所列的結構位置就在本 repo 內變得可能,
|
|
225
|
+
屆時誠實的做法是去跑它。
|
|
226
|
+
|
|
227
|
+
---
|
|
228
|
+
|
|
229
|
+
## 會產出延後項目的標準
|
|
230
|
+
|
|
231
|
+
下列各條都指回這裡;**沒有一條複述規則**,因為同一條規則的六份副本會往六個方向腐壞。
|
|
232
|
+
|
|
233
|
+
- [adr-standards](adr-standards.md) — 既受風險、負面後果、被考慮而未採用的選項
|
|
234
|
+
- [spec-driven-development](spec-driven-development.md) — 未納入項目、open questions、待確認的 assumptions
|
|
235
|
+
- [retrospective-standards](retrospective-standards.md) — action items,以及仍為 Open 的上期項目
|
|
236
|
+
- `feature-discovery-standards` — 未確認候選與 `dead_code_candidates`
|
|
237
|
+
- [code-review-checklist](code-review-checklist.md) — 本次未改而被接受的非阻斷留言
|
|
238
|
+
- [acceptance-criteria-traceability](acceptance-criteria-traceability.md) — 涵蓋缺口、閾值例外、報告的 action items
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
## 與其他標準的關係
|
|
243
|
+
|
|
244
|
+
- [acceptance-criteria-traceability](acceptance-criteria-traceability.md) — 上一層的同一個形狀:
|
|
245
|
+
它要求每條 AC 都能被驗證項到達,而不規定用什麼維持。本標準要求每個延後項目都能被出口到達。
|
|
246
|
+
- [class-level-fix](class-level-fix.md) — 提供 DEX-004 所要求證據的產生程序;
|
|
247
|
+
也是 DEX-008 所揭露之措辭清單失敗的通則形式。
|
|
248
|
+
- [verification-evidence](verification-evidence.md) — VE-012 的帶到期日例外清冊,
|
|
249
|
+
正是 DEX-006 那群「未驗證」項目該被登記進去的地方,而不是揭露一次就放著。
|
|
250
|
+
- [self-review-protocol](self-review-protocol.md) — 自我複查抓得到矛盾、抓不到缺漏;
|
|
251
|
+
沒有出口的延後項目正是缺漏。
|