規格相關工件

本文件建立管理補充文件的慣例，這些文件伴隨 OpenSpec 變更提案。這些產出物記錄了影響變更的研究、決策和溝通，但不屬於正式規格的一部分。

問題陳述

在規格提案的生命週期中，團隊會產生各種支援文件：

• 比較實作方案的研究筆記
• 架構審查結論
• PM 範圍討論與優先級決策
• 與利害關係人的會議記錄
• 廠商 API 分析
• 安全審查發現

這些文件對於理解為什麼做出決策至關重要，但它們不是由 OpenSpec 工具產生的。如果沒有明確的慣例，這些檔案可能會：

1. 散落在不同位置，失去可追溯性
2. 與 OpenSpec 產生的檔案混在一起，造成混淆
3. 在歸檔時遺失，失去組織知識

解決方案：artifacts/ 目錄

將所有補充文件放在每個變更的 artifacts/ 子目錄中：

openspec/
└── changes/
    └── bulk-device-import/
        ├── proposal.md              # OpenSpec 產生
        └── artifacts/               # 補充文件
            ├── research.md
            ├── arch-review.md
            └── pm-discussion.md

為什麼選擇 artifacts/

替代方案	問題
context/	在 AI/LLM 工作流程中術語過載
docs/	太籠統，與專案層級的 docs 衝突
notes/	暗示非正式、臨時的內容
supporting/	冗長

artifacts/ 清楚傳達：變更過程中產生的輸出。

Frontmatter 參考

在提案的 frontmatter 中參考產出物以便發現：

id: change-bulk-device-import
title: Bulk Device Import
status: active

artifacts:
  - artifacts/research.md
  - artifacts/arch-review.md
  - artifacts/pm-discussion.md

類型化參考（可選）

若需更結構化的追蹤：

id: change-bulk-device-import
title: Bulk Device Import
status: active

artifacts:
  research:
    - path: artifacts/research.md
      description: 批次處理方案比較

  architecture:
    - path: artifacts/arch-review.md
      description: 架構公會審查結論

  communication:
    - path: artifacts/pm-discussion.md
      description: 與 PM 的範圍和優先級討論

常見產出物類型

類型	用途	檔名範例
研究	技術調查、選項分析	research.md、poc-results.md
架構	設計審查、ADR 參考	arch-review.md、adr-summary.md
溝通	利害關係人討論、範圍決策	pm-discussion.md、stakeholder-feedback.md
安全	安全審查發現、威脅分析	security-review.md
外部	廠商文件、第三方規格	vendor-api-notes.md

生命週期

開發期間

隨著變更進展，產出物逐漸累積：

changes/bulk-device-import/
├── proposal.md
└── artifacts/
    ├── research.md           # 第 1 週：初始研究
    ├── arch-review.md        # 第 2 週：架構審查
    ├── pm-discussion.md      # 第 3 週：範圍精煉
    └── security-review.md    # 第 4 週：安全批准

歸檔期間

當變更完成並歸檔時，整個目錄一起移動：

# 整個變更目錄移至 archive
mv openspec/changes/bulk-device-import openspec/archive/bulk-device-import

artifacts/ 目錄保留完整的決策歷史：

archive/bulk-device-import/
├── proposal.md
└── artifacts/
    ├── research.md
    ├── arch-review.md
    ├── pm-discussion.md
    └── security-review.md

延後/取消的變更

產出物保留在 changes/ 中的變更：

changes/bulk-device-import/       # status: postponed
├── proposal.md
└── artifacts/
    ├── research.md
    └── arch-review.md            # 保留以備工作恢復時使用

效益

效益	說明
清楚分離	OpenSpec 檔案 vs. 補充文件
可追溯性	產出物隨變更在其生命週期中移動
AI 可讀	Frontmatter 參考讓代理能發現
工具相容	不干擾 OpenSpec CLI 操作
完整歷史	歸檔的變更保留完整決策理由

參考資料

• OpenSpec - 規格驅動開發框架