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

package/bundled/locales/zh-TW/core/documentation-structure.md

@@ -1,8 +1,8 @@
 ---
-source: core/documentation-structure.md
-source_version: 1.2.2
-translation_version: 1.2.2
-last_synced: 2025-12-25
+source: ../../../core/documentation-structure.md
+source_version: 1.3.0
+translation_version: 1.3.0
+last_synced: 2026-01-24
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > **語言**: [English](../../../core/documentation-structure.md) | 繁體中文
 
-**版本**: 1.2.2
-**最後更新**: 2025-12-24
+**版本**: 1.3.0
+**最後更新**: 2026-01-24
 **適用範圍**: 所有需要文件的軟體專案
 
 ---
@@ -42,7 +42,14 @@ project-root/
 │   ├── api-reference.md         # API documentation
 │   ├── deployment.md            # Deployment guide
 │   ├── troubleshooting.md       # Common issues
-│   ├── flows/                   # Flow documentation (NEW)
+│   ├── specs/                   # Specification documents
+│   │   ├── README.md            # Specification index
+│   │   ├── system/              # System design specifications
+│   │   │   └── *.md             # High-level architecture designs
+│   │   └── {component}/         # Component-specific specifications
+│   │       ├── design/          # Design specifications
+│   │       └── {module}/        # Implementation specifications
+│   ├── flows/                   # Flow documentation
 │   │   ├── README.md            # Flow index (REQUIRED when >5 flows)
 │   │   ├── templates/
 │   │   │   └── flow-template.md
@@ -109,21 +116,23 @@ docs/
 
 ## 文件需求矩陣
 
-不同專案類型需要不同的文件：
+> **另見**：完整的文件需求矩陣及詳細內容需求與專案類型說明，請參閱 [documentation-writing-standards.md](documentation-writing-standards.md#文件需求矩陣)。
 
-| Document | New Project | Refactor | Migration | Maintenance | Description |
-|----------|:-----------:|:--------:|:---------:|:-----------:|-------------|
-| **README.md** | ✅ | ✅ | ✅ | ✅ | Project entry point |
-| **ARCHITECTURE.md** | ✅ | ✅ | ✅ | ⚪ | System architecture |
-| **API.md** | ⚪ | ✅ | ✅ | ⚪ | External API specs |
-| **DATABASE.md** | ⚪ | ✅ | ✅ | ⚪ | Database structure |
-| **DEPLOYMENT.md** | ✅ | ✅ | ✅ | ⚪ | Deployment guide |
-| **MIGRATION.md** | ❌ | ✅ | ✅ | ❌ | Migration plan |
-| **ADR/** | ⚪ | ✅ | ✅ | ⚪ | Decision records |
-| **CHANGELOG.md** | ✅ | ✅ | ✅ | ✅ | Change history |
-| **flows/README.md** | ⚪ | ✅ | ✅ | ⚪ | Flow index (when >5 flows) |
+本標準定義文件「放在哪裡」（檔案結構）。撰寫標準定義每個文件「應包含什麼內容」。
 
-**圖例**: ✅ Required | ⚪ Recommended | ❌ Not needed
+**快速參考**（完整矩陣請參閱撰寫標準）：
+
+| 文件 | 主要位置 |
+|------|---------|
+| README.md | 專案根目錄 |
+| ARCHITECTURE.md | `docs/` |
+| API.md | `docs/` |
+| DATABASE.md | `docs/` |
+| DEPLOYMENT.md | `docs/` |
+| MIGRATION.md | `docs/` |
+| ADR/ | `docs/adr/` |
+| CHANGELOG.md | 專案根目錄 |
+| flows/ | `docs/flows/` |
 
 ---
 
@@ -228,7 +237,7 @@ docs/flows/
 
 1. **Define centrally** in `flows/README.md` or `DATABASE.md`
 2. **Reference in flow docs**: List only relevant codes, with note:
-   > Complete definitions at [flows/README.md](../README.md#status-codes)
+   > Complete definitions at [flows/README.md](../README.md)
 3. **Version control**: Status code changes must be recorded in CHANGELOG.md
 
 **狀態碼定義格式**:
@@ -245,7 +254,89 @@ docs/flows/
 
 ---
 
-## 索引文件規範 (NEW)
+## 規格文件
+
+### 目的
+
+規格文件定義**實作前**的設計與實作細節。它們與一般文件的差異：
+
+| 類型 | 目的 | 受眾 | 撰寫時機 | 位置 |
+|------|------|------|----------|------|
+| **規格** | 定義要建什麼及如何建 | 開發者 | 實作前 | `docs/specs/` |
+| **文件** | 說明建了什麼 | 使用者、開發者 | 實作後 | `docs/` |
+
+### 規格目錄結構
+
+```
+docs/specs/
+├── README.md               # 規格索引（必要）
+├── system/                 # 系統層級設計規格
+│   └── {feature}.md        # 高階架構設計
+└── {component}/            # 元件特定規格
+    ├── design/             # 設計規格（實作前）
+    ├── shared/             # 跨模組共用規格
+    └── {module}/           # 實作規格
+```
+
+### 規格類型
+
+| 層級 | 說明 | 範例 | 位置 |
+|------|------|------|------|
+| **系統規格** | 跨領域架構 | agents-workflows-system.md | `specs/system/` |
+| **設計規格** | 元件設計決策 | ui-language-option.md | `specs/{component}/design/` |
+| **實作規格** | 模組實作細節 | init/00-init-overview.md | `specs/{component}/{module}/` |
+| **共用規格** | 跨模組工具 | manifest-schema.md | `specs/{component}/shared/` |
+
+### 何時建立規格
+
+| 情境 | 建立規格？ | 類型 |
+|------|----------|------|
+| 具有多個元件的新功能 | 是 | 系統或設計 |
+| 新 CLI 命令 | 是 | 實作 |
+| 跨領域工具 | 是 | 共用 |
+| 錯誤修復 | 否 | - |
+| 重構（相同行為） | 否 | - |
+
+### 規格檔案格式
+
+每份規格文件應包含：
+
+```markdown
+# 功能名稱規格
+
+**Feature ID**: COMPONENT-FEATURE-NNN
+**Version**: 1.0.0
+**Last Updated**: YYYY-MM-DD
+**Status**: Draft | In Review | Approved | Implemented
+
+## 概述
+[此規格涵蓋內容的簡要說明]
+
+## 驗收條件
+[AC-1、AC-2、... 使用 Given-When-Then 格式]
+
+## 技術設計
+[實作細節]
+
+## 參考資料
+[相關規格和文件]
+```
+
+### specs/README.md 要求
+
+規格索引（`specs/README.md`）必須包含：
+
+| 章節 | 說明 | 必要 |
+|------|------|:----:|
+| 目錄結構 | 規格樹狀圖 | ✅ |
+| 系統規格 | 含說明和狀態的清單 | ✅ |
+| 元件規格 | 按元件組織 | ✅ |
+| 規格類型 | 類型定義和位置 | ⚪ |
+| 相關文件 | 連結至 docs/ | ✅ |
+
+---
+
+## 索引文件規範
 
 ### docs/index.md 必要章節
 
@@ -1097,6 +1188,7 @@ git push origin gh-pages
 - [Documentation Writing Standards](documentation-writing-standards.md) - 文件撰寫規範
 - [Changelog Standards](changelog-standards.md) - 變更日誌標準
 - [Project Structure Standard](project-structure.md) - 專案結構標準
+- [Spec-Driven Development](spec-driven-development.md) - 規格驅動開發
 
 ---
 
@@ -1104,6 +1196,7 @@ git push origin gh-pages
 
 | Version | Date | Changes |
 |---------|------|---------|
+| 1.3.0 | 2026-01-24 | Added: 規格文件標準與 specs/ 目錄結構 |
 | 1.2.2 | 2025-12-24 | Added: Related Standards section |
 | 1.2.1 | 2025-12-12 | Added: Physical DFD layer, Flows vs Diagrams separation clarification |
 | 1.2.0 | 2025-12-11 | Added: Flow documentation standards, Cross-reference standards, Index document standards, CHANGELOG documentation integration, Document requirements matrix, DFD standards |

package/bundled/locales/zh-TW/core/documentation-writing-standards.md

@@ -1,8 +1,8 @@
 ---
 source: ../../../core/documentation-writing-standards.md
-source_version: 1.0.1
-translation_version: 1.0.1
-last_synced: 2025-12-30
+source_version: 1.1.0
+translation_version: 1.1.0
+last_synced: 2026-01-24
 status: current
 ---
 
@@ -10,8 +10,8 @@ status: current
 
 > [English](../../../core/documentation-writing-standards.md) | **繁體中文**
 
-**版本**: 1.0.1
-**最後更新**: 2025-12-24
+**版本**: 1.1.0
+**最後更新**: 2026-01-24
 **適用範圍**: 所有軟體專案（新建、重構、遷移、維護）
 
 ---
@@ -405,6 +405,116 @@ status: current
 
 ---
 
+## AI 協作文件
+
+### 概述
+
+現代文件必須同時為人類讀者和 AI 助手最佳化。本節提供撰寫 AI 工具能有效解析和利用的文件指南。
+
+### Token 感知的文件設計
+
+AI 模型有上下文視窗限制。結構化文件以提高 LLM 消費效率：
+
+| 原則 | 說明 | 範例 |
+|------|------|------|
+| **前置關鍵資訊** | 將重要資訊放在前面 | 摘要先於細節 |
+| **使用清晰標題** | 階層結構有助導航 | H1 > H2 > H3 |
+| **保持章節原子化** | 每個章節自成一體 | 可獨立閱讀 |
+| **減少冗餘** | 避免重複資訊 | 引用而非複製 |
+| **使用結構化格式** | 表格和清單優於散文 | 易於解析和提取 |
+
+**建議文件大小**:
+
+| 文件類型 | 目標大小 | 理由 |
+|---------|---------|------|
+| README | 500-1000 字 | 快速概覽 |
+| API 端點文件 | 每端點 200-400 字 | 聚焦且可掃描 |
+| 架構文件 | 每章節 1000-2000 字 | 詳細但分塊 |
+| ADR | 300-600 字 | 決策導向 |
+
+### AI 友善的文件模式
+
+**模式 1：結構化中繼資料區塊**
+
+```markdown
+---
+title: 使用者認證 API
+version: 2.1.0
+last_updated: 2026-01-24
+owner: auth-team
+status: stable
+---
+```
+
+**模式 2：清晰的章節標記**
+
+```markdown
+## Overview / 概述
+## Quick Start / 快速開始
+## API Reference / API 參考
+## Configuration / 配置
+## Troubleshooting / 故障排除
+```
+
+### 為 AI 程式碼生成撰寫
+
+**包含明確限制**:
+
+```markdown
+## 驗證規則
+
+| 欄位 | 類型 | 限制 |
+|------|------|------|
+| email | string | 必填，有效電子郵件格式，最多 255 字元 |
+| age | integer | 必填，範圍 0-150 |
+| role | string | 列舉: "admin", "user", "guest" |
+```
+
+**明確業務邏輯**:
+
+```markdown
+## 折扣計算邏輯
+
+1. 基礎折扣 = 0%
+2. 若客戶類型為 "VIP"，加 20%
+3. 若訂單總額 > $100，加 5%
+4. 最大總折扣 = 50%
+```
+
+---
+
+## API 文件標準
+
+### OpenAPI 3.1 合規性
+
+對於 REST API，使用 OpenAPI 3.1（完全對齊 JSON Schema draft 2020-12）：
+
+**OpenAPI 3.1 主要功能**:
+
+| 功能 | 說明 |
+|------|------|
+| JSON Schema 對齊 | 與 JSON Schema 完全相容 |
+| Webhooks 支援 | 一級 webhook 文件 |
+| `type` 陣列 | 支援 `"type": ["string", "null"]` |
+
+### AsyncAPI 2.6 用於事件驅動 API
+
+對於訊息/事件驅動 API，使用 AsyncAPI 2.6：
+
+```yaml
+asyncapi: 2.6.0
+info:
+  title: 訂單事件
+  version: 1.0.0
+channels:
+  orders/created:
+    publish:
+      message:
+        $ref: '#/components/messages/OrderCreated'
+```
+
+---
+
 ## 品質標準
 
 ### 格式要求
@@ -481,10 +591,21 @@ project-root/
 
 ---
 
+## 參考資料
+
+- [OpenAPI 3.1 規格](https://spec.openapis.org/oas/v3.1.0) - 最新 OpenAPI 規格
+- [AsyncAPI 2.6 規格](https://www.asyncapi.com/docs/reference/specification/v2.6.0) - 事件驅動 API 文件
+- [JSON Schema 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html) - JSON Schema 規格
+- [Diátaxis 文件框架](https://diataxis.fr/) - 文件結構方法論
+- [Write the Docs](https://www.writethedocs.org/guide/) - 文件社群最佳實踐
+
+---
+
 ## 版本歷史
 
 | 版本 | 日期 | 變更內容 |
 |---------|------|---------|
+| 1.1.0 | 2026-01-24 | 新增：AI 協作文件章節、Token 感知文件設計、API 文件標準（OpenAPI 3.1、AsyncAPI 2.6） |
 | 1.0.1 | 2025-12-24 | 新增：相關標準章節 |
 | 1.0.0 | 2025-12-10 | 初版文件撰寫標準 |
 

package/bundled/locales/zh-TW/core/forward-derivation-standards.md

@@ -413,9 +413,9 @@ spec-review → forward-derivation → discovery
 
 - [反向工程標準](reverse-engineering-standards.md) - 對稱對應（程式碼 → 規格）
 - [規格驅動開發](spec-driven-development.md) - 輸入規格格式
-- [行為驅動開發](behavior-driven-development.md) - BDD 輸出格式
+- [行為驅動開發](../../../core/behavior-driven-development.md) - BDD 輸出格式
 - [測試驅動開發](test-driven-development.md) - TDD 輸出用法
-- [驗收測試驅動開發](acceptance-test-driven-development.md) - ATDD 輸出格式
+- [驗收測試驅動開發](../../../core/acceptance-test-driven-development.md) - ATDD 輸出格式
 - [反幻覺指南](anti-hallucination.md) - 生成合規
 
 ---