多產品、多層級規格管理

本提案建立一個階層式規格管理框架，使具有多個產品的組織能夠在不同抽象層級之間維護一致、可追溯的規格。AI 代理在生成程式碼時能夠導航此階層，理解脈絡、約束和依賴關係。

核心洞察： 現有的 AI 開發框架假設單一產品、單一團隊的環境。多產品組織需要一種結構化方法，讓規格能從組織層級的原則向下傳遞到產品特定的實作，同時維持可追溯性和一致性。

願景：意圖到規劃，瞬間完成

多層級規格管理的終極目標是實現從高階意圖即時產生完整規劃——特別是針對端到端、跨產品功能：

願景： 對於任何端到端、跨產品功能，人類只需提供高階意圖。在完全資訊透明（所有產品的規格對 AI 可見）的情況下，AI 代理立即產出完整的細部規劃，涵蓋所有受影響的產品及其整合點。

範例：跨產品功能意圖

markdown

## 高階意圖

「在 VSaaS、Vortex 和 Cloud Portal 之間啟用統一的裝置健康監控，
包含即時警報和歷史分析。」

AI 產生的跨產品規劃

規劃組成	AI 產出內容
VSaaS 變更	裝置健康資料收集 API、串流端點
Vortex 變更	健康資料聚合服務、警報規則引擎
Cloud Portal 變更	儀表板小工具、警報管理 UI、分析視圖
共享領域更新	共享領域中的 `DeviceHealth` 實體
API 契約	服務間通訊規格、事件綱要
整合規格	訊息佇列主題、資料流程圖
UX 流程	所有產品一致的健康視覺化
測試策略	橫跨三個產品的端到端測試
遷移計畫	分階段推出、各產品向後相容
依賴關係圖	哪些變更阻擋其他變更、可平行進行的工作流

人類角色： 審查完整的跨產品規劃，核准或要求調整，然後讓 AI 在所有受影響的程式碼庫中執行。

為何需要多層級規格管理

沒有階層	有階層
AI 需詢問標準相關問題	AI 從 Level 0 得知所有標準
AI 猜測產品約束	AI 從 Level 1 讀取產品規格
AI 產出不一致的設計	AI 遵循繼承的模式
人類必須指定每個細節	人類只需提供意圖
規劃需要數天來回溝通	規劃只需數秒

資訊透明原則

要實現此願景，所有脈絡必須對 AI 可見：

markdown

## AI 可見脈絡檢查清單

- [x] 組織原則在版本控制中
- [x] 產品特定約束已文件化
- [x] 共享領域有明確所有權
- [x] API 標準附有範例
- [x] 設計系統元件已編目
- [x] 既有功能規格已索引
- [x] 跨產品依賴已對應
- [x] 歷史決策已記錄（ADR）

當人類能陳述意圖，且 AI 能存取完整脈絡時，結果就是即時的完整規劃供人類審查——而非無盡的澄清循環。

問題陳述

現狀：框架不匹配

AI 開發挑戰的證據

挑戰	影響
無規格繼承	AI 代理在實作功能時缺乏組織標準的脈絡
產品孤島	相同能力在不同產品中實作不一致
層級混淆	高階業務需求與技術規格混在一起
跨產品盲點	AI 無法偵測跨產品邊界的衝突規格
審批瓶頸	多層審查延遲規格審批卻未增加價值

根本問題

使用扁平規格結構的 AI 代理：

無法繼承組織設計原則
遺漏產品特定的約束和慣例
重複已存在於其他產品的解決方案
生成與跨產品標準不一致的程式碼

提議解決方案：階層式規格管理

目標架構

規格層級

層級	名稱	範圍	負責人	AI 使用方式
0	組織原則	所有產品	架構 Guild	所有決策的脈絡
1	產品規格	單一產品	產品經理	產品特定約束
2	功能規格	單一功能	功能負責人	要建構什麼
3	平台規格	單一平台	平台負責人	如何建構（平台）
4	實作規格	單一模組	開發者	詳細設計

核心原則

繼承優於複製：低層級從高層級繼承，而非複製
覆寫需有理由：低層級可覆寫高層級規格，但須有文件化的理由
跨產品可見性：AI 代理可查詢跨產品邊界的規格
層級適當的細節：每個層級只包含與其範圍相關的細節
可追溯的變更：所有規格變更都連結到父規格和下游影響

規格層級詳情

層級 0：組織原則

定義所有產品必須遵循的組織層級標準的基礎層。

markdown

# org-specs/
├── CLAUDE.md                      # AI 代理主要指令
├── README.md                      # 人類概覽
│
├── principles/
│   ├── api-design.md              # API 設計原則（RFC 2119）
│   ├── security.md                # 安全需求
│   ├── accessibility.md           # 無障礙標準
│   ├── performance.md             # 效能預算
│   └── data-privacy.md            # 資料處理需求
│
├── standards/
│   ├── naming-conventions.md      # 通用語言
│   ├── error-handling.md          # 錯誤回應標準
│   ├── logging.md                 # 日誌需求
│   └── testing.md                 # 測試標準
│
├── governance/
│   ├── review-process.md          # 規格審查需求
│   ├── change-management.md       # 破壞性變更流程
│   └── escalation.md              # 決策升級路徑
│
└── shared/
    ├── domains/                   # 跨產品領域概念
    ├── integrations/              # 共享整合模式
    └── components/                # 共享元件註冊表

組織原則範例：

markdown

id: principle-api-design
level: 0
scope: organization
status: approved
version: 1.0.0
# API 設計原則

## 核心需求

### REQ-API-001：RESTful 資源命名
所有 HTTP API 必須使用複數名詞的 RESTful 資源命名。

#### 情境：資源端點命名
- **當**定義新的 API 端點時
- **則**使用複數名詞（例如 `/devices`、`/users`、`/sites`）
- **且**多字資源使用 kebab-case（例如 `/device-groups`）

### REQ-API-002：游標式分頁
所有列表端點必須實作游標式分頁。

#### 情境：列表端點分頁
- **當**回傳資源集合時
- **則**支援 `cursor` 和 `limit` 查詢參數
- **且**在回應中回傳 `nextCursor` 和 `hasMore`

## AI 實作注意事項

@ai-hint 在設計任何 API 端點前務必檢查此文件。
@ai-hint 這些原則無例外適用於所有產品。
@ai-hint 違反需要架構 Guild 核准和文件化的理由。

層級 1：產品規格

擴展組織原則的產品特定規格。

markdown

# products/vsaas/
├── _product.md                    # 產品概覽與脈絡
├── CLAUDE.md                      # 產品特定 AI 指令
│
├── principles/
│   ├── device-handling.md         # VSaaS 如何處理裝置
│   ├── video-streaming.md         # 影片特定約束
│   └── real-time.md               # 即時需求
│
├── domains/
│   ├── device.md                  # 裝置領域模型
│   ├── site.md                    # 站點/位置模型
│   └── video.md                   # 影片/串流模型
│
├── features/                      # 層級 2 規格
│   └── ...
│
└── overrides/
    └── api-design.md              # 產品特定 API 變化

產品層級覆寫範例：

markdown

id: vsaas-api-override
level: 1
scope: product
inherits: org-specs/principles/api-design
overrides:
  - REQ-API-001  # 部分覆寫
status: approved
justification: 影片串流需要專門的端點模式
approved_by: architecture-guild@company.com
# VSaaS API 設計覆寫

## 繼承的原則

此文件繼承自 `org-specs/principles/api-design.md`。
除非以下明確覆寫，否則所有原則適用。

## 覆寫

### REQ-API-001：RESTful 資源命名（已修改）

原始需求：所有端點使用複數名詞。

**VSaaS 覆寫：** 影片串流端點可使用基於動作的路徑。

#### 情境：串流動作端點
- **當**定義影片串流控制端點時
- **則**可使用動作路徑（例如 `/devices/{id}/stream/start`）
- **因為** WebRTC 信令需要動作導向的語義

#### 情境：非串流端點
- **當**定義非串流端點時
- **則**必須遵循原始 REQ-API-001（複數名詞）

## AI 實作注意事項

@ai-hint 對於串流端點，動作路徑是可接受的。
@ai-hint 對於所有其他 VSaaS 端點，遵循組織層級 API 原則。
@ai-hint 不確定時，預設使用組織層級原則。

層級 2：功能規格

定義要建構什麼的功能層級規格。

markdown

# products/vsaas/features/device-management/
├── requirement.md                 # 業務需求
├── api-contract.md               # API 規格
├── ux-spec.md                    # UX 需求
├── test-cases.md                 # 驗收標準
│
├── platforms/                     # 層級 3 規格
│   ├── web.md
│   ├── ios.md
│   └── android.md
│
└── modules/                       # 層級 4 規格
    ├── device-list.md
    └── device-add.md

功能規格標頭範例：

markdown

id: feature-device-management
level: 2
scope: feature
product: vsaas

inherits:
  - org-specs/principles/api-design
  - org-specs/standards/error-handling
  - products/vsaas/principles/device-handling
  - products/vsaas/domains/device

cross_product_refs:
  - shared/domains/user-identity
  - vortex/features/device-sync

status: approved
version: 2.3.0

層級 3：平台規格

平台特定的實作細節。

markdown

id: platform-web-device-management
level: 3
scope: platform
feature: device-management
platform: web

inherits:
  - products/vsaas/features/device-management/requirement
  - org-specs/shared/components/design-system

technology_stack:
  framework: vue3
  state: pinia
  components: shadcn-vue

status: approved
# 裝置管理 - Web 平台

## 元件對應

| 功能元素 | 設計系統元件 |
|----------|--------------|
| 裝置列表 | `DataTable` |
| 裝置卡片 | `Card` with `Badge` |
| 新增裝置表單 | `Dialog` with `Form` |
| 狀態指示器 | `StatusBadge` |

## 狀態管理

使用 Pinia store 模式：
```typescript
// stores/device.ts
export const useDeviceStore = defineStore('device', () => {
  // 實作遵循 org-specs/standards/state-management
})

AI 實作注意事項

@ai-hint 專門使用 Vue 3 Composition API。 @ai-hint 從 @/components/ui 導入元件（shadcn-vue）。 @ai-hint 遵循 org-specs 的 Pinia store 模式。


### 層級 4：實作規格

詳細的模組層級設計規格。

```markdown
id: impl-device-list-component
level: 4
scope: implementation
platform: web
feature: device-management
module: device-list

inherits:
  - products/vsaas/features/device-management/platforms/web
  - org-specs/standards/testing

files:
  - src/components/device/DeviceList.vue
  - src/components/device/DeviceListItem.vue
  - src/stores/device.ts
  - src/composables/useDeviceList.ts

status: approved
# 裝置列表元件實作

## 元件結構

DeviceList/ ├── DeviceList.vue # 容器元件 ├── DeviceListItem.vue # 項目渲染器 ├── DeviceListHeader.vue # 帶排序控制的表頭 └── tests/ └── DeviceList.spec.ts


## Props 介面

```typescript
interface DeviceListProps {
  siteId: string;
  initialFilters?: DeviceFilters;
  onDeviceSelect?: (device: Device) => void;
}

AI 實作注意事項

@ai-hint 此元件對大列表使用虛擬捲動。 @ai-hint 排序由 DeviceListHeader 發出排序事件處理。 @ai-hint 測試應涵蓋：載入、空白、錯誤、分頁狀態。



## 跨層級關係

### 繼承鏈

```mermaid
graph TD
    subgraph "繼承範例"
        ORG[org-specs/principles/api-design]
        PROD[products/vsaas/overrides/api-design]
        FEAT[features/device-management/api-contract]
        PLAT[platforms/web.md]
        IMPL[modules/device-list.md]

        ORG -->|繼承| PROD
        PROD -->|繼承| FEAT
        FEAT -->|繼承| PLAT
        PLAT -->|繼承| IMPL
    end

    style ORG fill:#e8f5e9
    style PROD fill:#e3f2fd
    style FEAT fill:#fff3e0
    style PLAT fill:#fce4ec
    style IMPL fill:#f3e5f5

覆寫追蹤

markdown

# 覆寫鏈範例

## REQ-API-001：資源命名

| 層級 | 文件 | 狀態 | 理由 |
|------|------|------|------|
| 0 | org-specs/principles/api-design | 原始 | - |
| 1 | products/vsaas/overrides/api-design | 已修改 | 串流端點需要動作路徑 |
| 2 | features/device-management/api-contract | 繼承 | 使用 VSaaS 覆寫 |

影響分析

多產品協調

跨產品規格可見性

markdown

# 情境：實作已存在於另一產品的功能

## AI 代理工作流程

1. 代理讀取功能需求
2. 偵測類似功能存在於另一產品：

cross_product_refs: - vortex/features/device-sync # 類似功能

3. 代理查詢 vortex 規格取得模式
4. 應用一致模式同時尊重產品差異
5. 在實作規格中註記任何差異

共享領域管理

跨產品變更協議

變更類型	流程	審查者
層級 0 變更	RFC + 所有產品審查	架構 Guild + 所有產品負責人
層級 1 變更	產品 RFC	產品負責人 + 架構 Guild
共享領域變更	跨產品 RFC	所有消費產品負責人
有跨產品參照的功能	影響通知	被參照產品負責人

AI 代理整合

多層級導航的 CLAUDE.md

markdown

# 多層級規格導航 - AI 指令

## 理解階層

規格組織為 5 個層級：
- **層級 0**：組織原則（永遠適用）
- **層級 1**：產品規格（在產品內適用）
- **層級 2**：功能規格（要建構什麼）
- **層級 3**：平台規格（如何建構）
- **層級 4**：實作規格（詳細設計）

## 任何實作之前

識別功能：products/{product}/features/{feature}/
閱讀層級 2 規格（requirement.md）
向上追溯繼承鏈：
- 檢查功能繼承自
- 檢查產品覆寫
- 檢查組織層級原則
檢查 cross_product_refs 找相關工作
閱讀目標平台的平台規格（層級 3）
如果存在，閱讀實作規格（層級 4）


## 解決衝突

當不同層級的規格似乎有衝突時：
1. 低層級只有在明確文件化時才能覆寫高層級
2. 查看 frontmatter 中的 `overrides:`
3. 如果沒有明確覆寫，高層級獲勝
4. 不確定時，註記衝突並請求澄清

## 跨產品意識

實作功能時：
1. 永遠檢查 cross_product_refs
2. 查詢其他產品中的類似功能找模式
3. 使用 org-specs/shared/ 的共享領域
4. 不要為跨產品概念建立產品特定的解決方案

## 層級適當的輸出

將輸出匹配到規格層級：
- 層級 2 提示 → 功能層級設計決策
- 層級 3 提示 → 平台特定實作
- 層級 4 提示 → 詳細程式碼生成

規格導航的 MCP 工具

typescript

const multiLevelSpecServer = {
  tools: {
    // 追溯規格的完整繼承鏈
    traceInheritance: async ({ specPath }) => {
      const spec = await readSpec(specPath);
      const chain = [];
      let current = spec;

      while (current.inherits) {
        for (const parent of current.inherits) {
          const parentSpec = await readSpec(parent);
          chain.push({
            path: parent,
            level: parentSpec.level,
            overrides: parentSpec.overrides || []
          });
        }
        current = await readSpec(current.inherits[0]);
      }

      return chain;
    },

    // 找出受變更影響的所有規格
    impactAnalysis: async ({ specPath, changeType }) => {
      const spec = await readSpec(specPath);
      const level = spec.level;

      // 找出繼承此規格的所有規格
      const affected = await findInheritingSpecs(specPath);

      return {
        directlyAffected: affected.filter(s => s.level === level + 1),
        transitivelyAffected: affected.filter(s => s.level > level + 1),
        crossProductRefs: await findCrossProductRefs(specPath)
      };
    },

    // 考慮所有繼承後解析有效規格
    resolveEffectiveSpec: async ({ specPath }) => {
      const chain = await this.traceInheritance({ specPath });
      const merged = {};

      // 從最高層級到最低層級應用（覆寫獲勝）
      for (const ancestor of chain.reverse()) {
        const ancestorSpec = await readSpec(ancestor.path);
        Object.assign(merged, ancestorSpec.requirements);
      }

      const currentSpec = await readSpec(specPath);
      Object.assign(merged, currentSpec.requirements);

      return {
        effectiveRequirements: merged,
        overrideChain: chain.filter(c => c.overrides.length > 0)
      };
    },

    // 檢查跨產品一致性
    validateCrossProduct: async ({ product, feature }) => {
      const spec = await readSpec(`products/${product}/features/${feature}/requirement.md`);
      const refs = spec.cross_product_refs || [];

      const validation = {
        terminology: await validateTerminologyConsistency(spec, refs),
        apiCompatibility: await validateApiCompatibility(spec, refs),
        domainAlignment: await validateDomainUsage(spec)
      };

      return validation;
    }
  }
};

治理模型

審批矩陣

規格層級	作者	審查者	核准者
層級 0	架構 Guild	所有產品負責人	架構 Guild
層級 1	產品負責人	架構 Guild	產品負責人
層級 2	功能負責人	產品負責人	功能負責人
層級 3	平台負責人	功能負責人	平台負責人
層級 4	開發者	平台負責人	開發者

變更傳播

AI 工作流程的扁平化審批

規格審批應：

消除冗餘審查 - 如果層級 2 未變更地繼承自層級 1，不需要層級 1 重新審查
平行審查 - 跨產品參照平行審查，而非順序
自動化驗證 - CI 驗證繼承鏈正確性
負責人自主權 - 每個層級負責人在其範圍內有完全權限

實施路線圖

階段 1：基礎（第 1 個月）

[ ] 定義層級 0 組織原則
[ ] 建立規格階層目錄結構
[ ] 在 frontmatter 中實作繼承追蹤
[ ] 建立繼承鏈驗證器（CI）

階段 2：產品遷移（第 2-3 個月）

[ ] 將一個產品遷移到新階層
[ ] 建立產品層級覆寫文件
[ ] 實作規格導航的 MCP 工具
[ ] 訓練 AI 代理多層級導航

階段 3：跨產品（第 4-5 個月）

[ ] 建立共享領域規格
[ ] 實作跨產品一致性驗證
[ ] 建立影響分析工具
[ ] 文件化治理模型

階段 4：全面推出（第 6 個月）

[ ] 遷移剩餘產品
[ ] 整合 CI/CD 流水線
[ ] 測量和優化 AI 導航效率
[ ] 根據經驗精煉治理

成功指標

指標	目標	測量方式
規格繼承覆蓋率	>90%	繼承組織原則的功能
跨產品一致性	>95%	共享概念使用審計
覆寫文件化	100%	所有覆寫都有理由
AI 導航準確度	>85%	正確層級識別
變更影響準確度	>95%	預測 vs 實際受影響規格
審查週期時間	L4 <24h、L3 <48h、L2 <72h	從提交到核准的時間

應避免的反模式

1. 複製貼上而非繼承

問題： 將層級 0 內容複製到層級 2 規格。

為何失敗： 層級 0 的變更不會傳播；規格會分歧。

替代方案： 使用 inherits: frontmatter；參照而非複製。

2. 過深的階層

問題： 建立 8+ 層的規格。

為何失敗： 導航變得複雜；繼承鏈斷裂。

替代方案： 堅持 5 層；扁平化不必要的中間規格。

3. 跨層級捷徑

問題： 層級 4 規格直接參照層級 0，跳過層級 1-3。

為何失敗： 遺漏產品/功能特定的約束。

替代方案： 永遠透過鏈繼承；使用 cross_product_refs 進行橫向參照。

4. 未文件化的覆寫

問題： 低層級與高層級矛盾但沒有 overrides: 宣告。

為何失敗： AI 代理無法偵測衝突；生成不一致的程式碼。

替代方案： 所有覆寫必須在 frontmatter 中宣告並有理由。

CLAUDE.md 整合範例

markdown

# 產品：VSaaS - AI 指令

## 規格階層脈絡

此產品遵循多層級規格管理：

org-specs/ # 層級 0 - 永遠先檢查 └── principles/ └── api-design.md # 你的 API 設計必須遵循這個

products/vsaas/ # 層級 1 - 產品約束 ├── _product.md # 閱讀產品脈絡 ├── overrides/ # 檢查組織層級覆寫 └── domains/ # 產品領域模型

products/vsaas/features/ # 層級 2 - 功能規格 └── {feature}/ └── requirement.md # 你正在建構的東西


## 實作工作流程

1. 閱讀層級 0 原則（永遠適用）
2. 檢查層級 1 覆寫（產品特定）
3. 閱讀層級 2 功能規格（你的任務）
4. 遵循層級 3 平台規格（你的平台）
5. 如果複雜，生成層級 4 實作規格

## 繼承規則

- 除非明確覆寫，否則高層級適用
- 檢查 frontmatter 中的 `overrides:` 找例外
- 不確定時，預設使用高層級規格
- 文件化任何模糊之處供人類審查

相關連結： 工作流程框架 | 全域需求儲存庫

參考資料

工作流程框架 - 多層級規格概覽
OpenSpec - 規格驅動開發框架
RFC 2119 - 需求層級關鍵詞
全域需求儲存庫 - 產品導向需求管理

多產品、多層級規格管理 ​

願景：意圖到規劃，瞬間完成 ​

範例：跨產品功能意圖 ​

AI 產生的跨產品規劃 ​

為何需要多層級規格管理 ​

資訊透明原則 ​

問題陳述 ​

現狀：框架不匹配 ​

AI 開發挑戰的證據 ​

根本問題 ​

提議解決方案：階層式規格管理 ​

目標架構 ​

規格層級 ​

核心原則 ​

規格層級詳情 ​

層級 0：組織原則 ​

層級 1：產品規格 ​

層級 2：功能規格 ​

層級 3：平台規格 ​

AI 實作注意事項 ​

AI 實作注意事項 ​

覆寫追蹤 ​

影響分析 ​

多產品協調 ​

跨產品規格可見性 ​

共享領域管理 ​

跨產品變更協議 ​

AI 代理整合 ​

多層級導航的 CLAUDE.md ​

規格導航的 MCP 工具 ​

治理模型 ​

審批矩陣 ​

變更傳播 ​

AI 工作流程的扁平化審批 ​

實施路線圖 ​

階段 1：基礎（第 1 個月） ​

階段 2：產品遷移（第 2-3 個月） ​

階段 3：跨產品（第 4-5 個月） ​

階段 4：全面推出（第 6 個月） ​

成功指標 ​

應避免的反模式 ​

1. 複製貼上而非繼承 ​

2. 過深的階層 ​

3. 跨層級捷徑 ​

4. 未文件化的覆寫 ​

CLAUDE.md 整合範例 ​

參考資料 ​

多產品、多層級規格管理

願景：意圖到規劃，瞬間完成

範例：跨產品功能意圖

AI 產生的跨產品規劃

為何需要多層級規格管理

資訊透明原則

問題陳述

現狀：框架不匹配

AI 開發挑戰的證據

根本問題

提議解決方案：階層式規格管理

目標架構

規格層級

核心原則

規格層級詳情

層級 0：組織原則

層級 1：產品規格

層級 2：功能規格

層級 3：平台規格

AI 實作注意事項

AI 實作注意事項

覆寫追蹤

影響分析

多產品協調

跨產品規格可見性

共享領域管理

跨產品變更協議

AI 代理整合

多層級導航的 CLAUDE.md

規格導航的 MCP 工具

治理模型

審批矩陣

變更傳播

AI 工作流程的扁平化審批

實施路線圖

階段 1：基礎（第 1 個月）

階段 2：產品遷移（第 2-3 個月）

階段 3：跨產品（第 4-5 個月）

階段 4：全面推出（第 6 個月）

成功指標

應避免的反模式

1. 複製貼上而非繼承

2. 過深的階層

3. 跨層級捷徑

4. 未文件化的覆寫

CLAUDE.md 整合範例

參考資料