內部規格平台

問題陳述

管理多個產品的組織面臨規格存取碎片化的問題：

規格分散 - 規格散落在不同的儲存庫、wiki 和文件中
無版本控制 - 「上個月部署時的規格是什麼？」無法回答
無跨產品可見性 - 團隊無法發現其他產品中的相關規格
AI 脈絡效率低落 - 代理每次會話都需重新取得和解析規格
無單一入口 - 開發者必須知道每個規格的存放位置

提議解決方案

建立內部規格平台，透過以下網址存取：

https://spec.{company.domain}/{date}/{product-id}/{spec-type}/specs/{spec-id}

URL 結構

區段	用途	範例
`spec.{company.domain}`	專用子網域	關注點分離
`{date}`	時間點快照	`2024-12-04`、`latest`、`head`
`{product-id}`	產品邊界	`product-a`、`product-b`、`billing`
`{spec-type}`	OpenSpec 規格類型目錄	`func`、`ux`、`api`、`infra`
`specs`	固定路徑區段	OpenSpec 慣例
`{spec-id}`	能力識別碼	`user-auth`、`order-create`

支援的規格類型

類型	路徑	說明
func	`/{product}/func/specs/{id}`	功能/能力規格
ux	`/{product}/ux/specs/{id}`	UX/UI 規格與線框圖
api	`/{product}/api/specs/{id}`	API 合約（OpenAPI、AsyncAPI）
infra	`/{product}/infra/specs/{id}`	基礎設施規格
changes	`/{product}/changes/{id}`	進行中的變更提案
archive	`/{product}/archive/{id}`	已完成/已部署的變更

URL 範例

/latest/product-a/func/specs/user-auth     # 功能規格
/latest/product-a/ux/specs/user-auth       # UX 規格
/latest/product-a/api/specs/user-auth      # API 規格
/latest/product-a/changes/add-2fa          # 變更提案

日期版本控制

日期版本控制比語意版本控制更適合規格管理：

面向	Semver (`v1.2.3`)	日期 (`2024-12-04`)
意義	破壞性/功能/修補	時間點快照
決策	主觀（「這是破壞性變更嗎？」）	客觀（今天的日期）
稽核追蹤	「Q3 上線的是哪個版本？」	「給我看 2024-09-15」
多產品同步	版本對齊很痛苦	相同日期 = 相同快照

版本別名

/latest/...        → 當前已部署狀態（指向最後部署日期的別名）
/2024-12-04/...    → 該日期的不可變快照
/head/...          → 最新狀態（main 分支，可能包含未部署的變更）

能力命名慣例

OpenSpec 使用扁平結構搭配前綴式領域分組：

specs/
├── user-auth/
├── user-profile/
├── user-preferences/
├── order-create/
├── order-fulfill/
├── order-cancel/
├── payment-capture/
├── payment-refund/
└── notification-email/

這是 OpenSpec 的慣例，不是平台的設計選擇。平台尊重並呈現 OpenSpec 現有的結構。

架構

Git-Based 解析

無儲存重複。Git 是事實來源：

/2024-12-04/...  → git show $(git rev-list -1 --before="2024-12-04" main):products/...
/latest/...      → main 分支 HEAD（或最後部署標籤）
/head/...        → main 分支 HEAD

目錄結構

spec-platform/
├── products/
│   ├── product-a/
│   │   ├── func/                       # 功能規格
│   │   │   └── specs/
│   │   │       ├── user-auth/
│   │   │       │   ├── spec.md
│   │   │       │   └── design.md
│   │   │       └── order-create/
│   │   │           └── spec.md
│   │   ├── ux/                         # UX 規格
│   │   │   └── specs/
│   │   │       ├── user-auth/
│   │   │       │   ├── spec.md
│   │   │       │   └── assets/
│   │   │       └── order-create/
│   │   │           └── spec.md
│   │   ├── api/                        # API 合約
│   │   │   └── specs/
│   │   │       ├── user-auth/
│   │   │       │   └── openapi.yaml
│   │   │       └── order-create/
│   │   │           └── openapi.yaml
│   │   └── changes/
│   │       └── add-2fa/
│   │           ├── proposal.md
│   │           ├── func/
│   │           │   └── specs/
│   │           │       └── user-auth/
│   │           │           └── spec.md
│   │           └── ux/
│   │               └── specs/
│   │                   └── user-auth/
│   │                       └── spec.md
│   └── billing/
│       └── func/
│           └── specs/
│               └── payment-capture/
│                   └── spec.md
├── shared/
│   ├── domains/
│   │   └── glossary.md
│   └── principles/
│       └── api-design.md
└── .vitepress/
    └── config.mjs

規格類型關係

規格使用包含網域的絕對 URI 參照相關規格（規格可能分散在不同儲存庫）：

yaml

---
id: user-auth
spec-type: func
related:
  ux: https://spec.{company.domain}/product-a/ux/specs/user-auth
  api: https://spec.{company.domain}/product-a/api/specs/user-auth
  # 跨產品參照
  billing: https://spec.{company.domain}/billing/func/specs/payment-capture
---

包含網域的絕對 URI 確保參照無論規格實際存放位置都能運作。

API 端點

# 核心規格存取（遵循 OpenSpec 結構）
GET /{date}/{product}/func/specs/{spec-id}      # 功能規格
GET /{date}/{product}/ux/specs/{spec-id}        # UX 規格
GET /{date}/{product}/api/specs/{spec-id}       # API 規格
GET /{date}/{product}/{spec-type}/specs         # 列出該類型所有規格

# 變更提案
GET /{date}/{product}/changes                   # 進行中的提案
GET /{date}/{product}/changes/{change-id}       # 特定提案
GET /{date}/{product}/changes/{change-id}/preview  # 合併預覽

# 跨類型查詢
GET /{date}/{product}/func/specs/{id}/related   # 相關的 ux、api 規格
GET /{date}/search?q=authentication             # 跨所有類型的全文搜尋
GET /{date}/search?q=login&type=ux              # 搜尋特定規格類型
GET /{date}/graph                               # 依賴關係視覺化
GET /products                                   # 列出所有產品

快照策略

觸發條件	建立快照
每日定時	若自上次快照後有變更則自動建立
部署	以部署日期標記
手動	`spec-platform snapshot 2024-12-04`

跨產品參照

所有參照使用包含網域的絕對 URI（規格可能分散在不同儲存庫）：

markdown

# 在 product-a/func/specs/order-payment/spec.md 中

## 依賴
- [payment-capture](https://spec.{company.domain}/billing/func/specs/payment-capture)
- [user-auth](https://spec.{company.domain}/product-a/func/specs/user-auth)
- [order-flow](https://spec.{company.domain}/product-a/ux/specs/order-create)

平台根據請求的日期解析這些 URI：

請求 /latest/product-a/func/specs/order-payment
參照 https://spec.{company.domain}/billing/func/specs/payment-capture 解析為 /latest/billing/func/specs/payment-capture

需求池整合

規格可追溯回全域需求儲存庫中的來源需求：

yaml

---
id: user-auth
spec-type: func
# 連結到來源需求
requirements:
  - https://req.{company.domain}/product-a/REQ-001  # 登入功能
  - https://req.{company.domain}/product-a/REQ-002  # Session 管理
  - https://req.{company.domain}/shared/SEC-012    # 安全基準
---

可追溯性鏈

需求池                    規格平台                    實作
─────────────────────────────────────────────────────────────────────
REQ-001 (登入)      →     func/specs/user-auth   →   src/auth/login.ts
                    →     ux/specs/user-auth     →   src/components/LoginForm.tsx
                    →     api/specs/user-auth    →   openapi.yaml

可追溯性 API 端點

# 從規格到需求
GET /{date}/{product}/{type}/specs/{id}/requirements

# 從需求到規格（反向查詢）
GET /{date}/specs?requirement=REQ-001

# 覆蓋率報告：哪些需求有規格？
GET /{date}/{product}/coverage

需求參照欄位

欄位	說明	範例
`requirements`	此規格實作的來源需求	`https://req.{company.domain}/product-a/REQ-001`
`partial`	部分涵蓋的需求	規格僅涵蓋需求的子集時使用
`derived_from`	分解後的父需求	階層式需求追溯

實施路線圖

階段 1：靜態網站（第 1-2 月）

目標： 具日期版本的基本規格託管

[ ] VitePress/Docusaurus 設定與產品路由
[ ] Git-based 日期解析支援 /latest 和 /head
[ ] 合併到 main 時自動部署
[ ] 基本搜尋功能

交付物：

spec.{company.domain}/latest/{product}/specs/{spec-id} 可運作
規格更新的 CI/CD 管線

階段 2：快照（第 2-3 月）

目標： 不可變的日期存取

[ ] 每日快照自動化
[ ] 部署標籤整合
[ ] 歷史導航 UI
[ ] 日期間差異比較

交付物：

/{date}/... 端點可運作
「比較版本」UI 功能

階段 3：API 層（第 3-4 月）

目標： AI 代理的程式化存取

[ ] 規格查詢的 REST API
[ ] MCP 資源提供者
[ ] 變更通知的 Webhook 整合
[ ] JSON/YAML 匯出格式

交付物：

GET /api/v1/{product}/specs 端點
Claude Code 整合的 MCP 伺服器

階段 4：平台功能（第 4-6 月）

目標： 完整平台能力

[ ] 變更提案工作流程 UI
[ ] 跨產品依賴追蹤
[ ] 具嵌入向量的語意搜尋
[ ] 合規/覆蓋率儀表板
[ ] 版本間規格差異比較

交付物：

提案管理的 Web UI
分析儀表板

CLAUDE.md 整合

markdown

## 規格平台

存取規格：https://spec.{company.domain}

### 快速參考
- 最新規格：`/latest/{product}/specs/{spec-id}`
- 歷史規格：`/{date}/{product}/specs/{spec-id}`
- 搜尋：`/latest/search?q=query`

### 實作前
1. 檢查現有規格：`/latest/{product}/specs`
2. 審查進行中的變更：`/latest/{product}/changes`
3. 驗證與其他產品無衝突

### 跨產品依賴
實作跨產品功能時，檢查：
- `/latest/billing/specs/payment-*` 用於支付整合
- `/latest/product-a/specs/user-*` 用於使用者身份

### MCP 存取
使用 spec-platform MCP 伺服器進行程式化存取：
- `spec://product-a/user-auth` - 讀取規格內容
- `spec://search?q=authentication` - 跨產品搜尋

成功指標

指標	目標	如何測量
規格可發現性	<30 秒找到任何規格	使用者測試
歷史存取	100% 日期查詢成功	API 監控
跨產品可見性	所有依賴都已文件化	連結驗證
AI 脈絡效率	重新取得減少 50%	代理會話分析
稽核合規	5 年內任何日期可查詢	保留政策

應避免的反模式

規格重複

錯誤： 在產品間複製規格 正確： 透過 URI 參照共享規格

過度巢狀

錯誤： 深層階層如 /product/domain/subdomain/feature/spec正確： 扁平加命名慣例：domain-feature

版本擴散

錯誤： 每次 commit 都建立快照 正確： 有意義的快照（每日、部署、手動里程碑）

平台複雜度

錯誤： 在證明價值前就建構完整 CMS 正確： 從靜態網站開始，逐步增加功能

工作流程框架

指導原則

治理

文化

執行

內部規格平台

問題陳述

提議解決方案

URL 結構

支援的規格類型

URL 範例

日期版本控制

版本別名

能力命名慣例

架構

Git-Based 解析

目錄結構

規格類型關係

API 端點

快照策略

跨產品參照

需求池整合

可追溯性鏈

可追溯性 API 端點

需求參照欄位

實施路線圖

階段 1：靜態網站（第 1-2 月）

階段 2：快照（第 2-3 月）

階段 3：API 層（第 3-4 月）

階段 4：平台功能（第 4-6 月）

CLAUDE.md 整合

成功指標

應避免的反模式

規格重複

過度巢狀

版本擴散

平台複雜度

相關提案

內部規格平台 ​

問題陳述 ​

提議解決方案 ​

URL 結構 ​

支援的規格類型 ​

URL 範例 ​

日期版本控制 ​

版本別名 ​

能力命名慣例 ​

架構 ​

Git-Based 解析 ​

目錄結構 ​

規格類型關係 ​

API 端點 ​

快照策略 ​

跨產品參照 ​

需求池整合 ​

可追溯性鏈 ​

可追溯性 API 端點 ​

需求參照欄位 ​

實施路線圖 ​

階段 1：靜態網站（第 1-2 月） ​

階段 2：快照（第 2-3 月） ​

階段 3：API 層（第 3-4 月） ​

階段 4：平台功能（第 4-6 月） ​

CLAUDE.md 整合 ​

成功指標 ​

應避免的反模式 ​

規格重複 ​

過度巢狀 ​

版本擴散 ​

平台複雜度 ​

相關提案 ​

內部規格平台

問題陳述

提議解決方案

URL 結構

支援的規格類型

URL 範例

日期版本控制

版本別名

能力命名慣例

架構

Git-Based 解析

目錄結構

規格類型關係

API 端點

快照策略

跨產品參照

需求池整合

可追溯性鏈

可追溯性 API 端點

需求參照欄位

實施路線圖

階段 1：靜態網站（第 1-2 月）

階段 2：快照（第 2-3 月）

階段 3：API 層（第 3-4 月）

階段 4：平台功能（第 4-6 月）

CLAUDE.md 整合

成功指標

應避免的反模式

規格重複

過度巢狀

版本擴散

平台複雜度

相關提案