規格撰寫指南

本指南定義專案開發所需的各類文檔撰寫規範與範本，涵蓋從產品規劃到技術規格的完整文檔體系。

實際案例參考: 花店管理系統規格包含完整的開發文檔，可作為撰寫參考。

文檔層級架構

your-project/docs/
├── README.md                     # 文檔架構說明
├── roadmap.md                    # 產品路線圖（戰略層級）
├── feature-list.md               # 功能清單（使用者能力視角）
├── domain-model.md               # 領域模型（業務實體與統一語言）
├── development-plan.md           # 軟體開發計畫（執行層級）
├── ux-guidelines.md              # UX 設計指南（互動設計原則）
│
├── research/                     # 研究資料（選用）
│   ├── README.md                 # 研究資料索引
│   ├── interviews/               # 訪談紀錄
│   │   └── interview-{N}-{description}.md
│   ├── surveys/                  # 調查數據
│   │   └── survey-{N}-{description}.md
│   └── competitive-analysis.md   # 競品分析
│
├── epics/                        # Epic 層級文檔
│   ├── README.md                 # Epic 索引與概覽
│   └── epic-{N}-{name}.md        # 各 Epic 詳細文檔
│
├── user-stories/                 # User Story 層級文檔
│   ├── README.md                 # User Story 索引與模板
│   └── epic-{N}/                 # 按 Epic 分組
│       └── US-{NNN}-{name}.md    # 各 User Story 文檔
│
├── sbe/                          # 實例化規格 (Specification by Example)
│   ├── README.md                 # SBE 概覽與模板
│   └── epic-{N}/                 # 按 Epic 分組
│       └── US-{NNN}/             # 按 User Story 分組
│           └── scenario-{N}-{description}.md
│
├── api-specs/                    # API 規格文檔
│   ├── README.md
│   └── {domain}.md               # 按領域分類
│
├── data-models/                  # 數據模型文檔
│   ├── README.md
│   └── {entity}.md               # 各 Entity 定義
│
├── decision-records/             # 架構決策記錄 (ADR)
│   ├── README.md
│   └── {NNN}-{description}.md    # 各決策記錄
│
└── progress/                     # 進度追蹤
    ├── README.md
    └── sprints/
        └── sprint-{N}.md

命名規範

類型	格式	範例
Feature ID	`F-{NN}`	`F-01`
領域模型	`domain-model.md`	`domain-model.md`
Epic 文檔	`epic-{N}-{kebab-case}.md`	`epic-2-order-lifecycle.md`
User Story ID	`US-{Epic編號}{流水號}`	`US-201`
User Story 文檔	`US-{ID}-{kebab-case}.md`	`US-201-create-order.md`
SBE Scenario 目錄	`US-{ID}-{kebab-case}/`	`US-201-create-order/`
SBE Scenario 文檔	`scenario-{N}-{description}.md`	`scenario-1-individual-customer.md`
API 文檔	`{domain}.md`	`orders.md`
數據模型	`{entity}.md`	`order.md`
ADR	`{NNN}-{description}.md`	`002-state-machine-for-orders.md`
訪談紀錄	`interview-{N}-{kebab-case}.md`	`interview-1-shop-owner.md`
調查報告	`survey-{N}-{kebab-case}.md`	`survey-1-order-workflow.md`
競品分析	`competitive-analysis.md`	`competitive-analysis.md`

1. 產品路線圖（roadmap.md）

讀者: 產品經理、技術主管、利害關係人

內容:

產品願景（核心問題、市場定位、差異化價值）
戰略主題與 Now-Next-Later 路線圖
關鍵成功指標 (KPIs)
用戶角色與權限矩陣
核心 Epics 概覽
非功能性需求

更新頻率: 每季度審視一次

實際案例: 花店管理系統 Roadmap

2. 功能清單（feature-list.md）

讀者: 客戶、利害關係人、產品經理

內容:

系統從使用者角度的功能概覽，按功能領域分組
每項功能標註主要角色、交付階段、實作狀態
與 Epic/US 的交叉引用

更新頻率: 初始建立時從 Roadmap 衍生，後續每個 Sprint 更新狀態

與 roadmap.md 的關係:

roadmap.md 回答 "為什麼做"（Why）— 戰略主題、業務目標
feature-list.md 回答 "使用者能做什麼"（What）— 功能能力清單

與 epics/ 的關係:

feature-list.md 以使用者視角組織功能（我能做什麼）
epics/ 以開發視角組織工作（團隊怎麼拆分）
兩者是平行關係（M:N 交叉引用），不是上下游

產出方式:

有 Roadmap 的專案：由 /roadmap 附帶產出，或用 /feature-list 從 Roadmap 衍生
客戶委託專案（無 Roadmap）：用 /feature-list 對話式獨立建立
狀態更新：由 /sprint 在 Sprint Review 時更新

Feature List 範本

# {產品名稱}：功能清單

## 概述

本文檔列出{產品名稱}的使用者功能，按功能領域分組。
每項功能標註交付階段與實作狀態，供利害關係人掌握產品能力與開發進度。

**狀態說明**：🔲 待開發 ｜ 🚧 開發中 ｜ ✅ 已完成

## {功能領域 1}

| # | 功能 | 說明 | 主要角色 | 階段 | 狀態 | 相關 Epic | 相關 US |
|---|------|------|---------|------|------|----------|--------|
| F-01 | {功能名稱} | {一句話說明} | {角色} | {Now/Next/Later} | 🔲 | Epic {N} | — |
| F-02 | {功能名稱} | {一句話說明} | {角色} | {Now/Next/Later} | 🔲 | Epic {N}, {M} | US-{NNN} |

## {功能領域 2}

| # | 功能 | 說明 | 主要角色 | 階段 | 狀態 | 相關 Epic | 相關 US |
|---|------|------|---------|------|------|----------|--------|
| F-10 | {功能名稱} | {一句話說明} | {角色} | {Now/Next/Later} | 🔲 | Epic {N} | — |

## 範圍外（Out of Scope）

以下功能已明確排除在目前產品範圍外：

- {排除功能 1} — {排除原因}
- {排除功能 2} — {排除原因}

欄位說明

欄位	說明
#	Feature ID（`F-{NN}`），在文檔內唯一
功能	使用者可感知的功能名稱
說明	一句話描述功能的業務價值
主要角色	主要使用該功能的角色（參考 Roadmap 角色定義）
階段	交付階段（Now / Next / Later），對應 Roadmap 路線圖
狀態	🔲 待開發 / 🚧 開發中 / ✅ 已完成
相關 Epic	實作該功能的 Epic（可多個，M:N 關係）
相關 US	對應的 User Story（功能尚未拆分 US 時填 `—`）

分組原則

功能按使用者感知的功能領域分組，而非按 Epic。例如：

功能領域（Feature List）	來源 Epic（開發視角）
訂單管理	Epic 2（訂單生命週期）+ Epic 0（通知）
客戶管理	Epic 3（客戶系統）
財務管理	Epic 4（發票與支付）

同一 Epic 的功能可能分散在多個功能領域中，同一功能也可能關聯多個 Epic。

實際案例: 花店管理系統功能清單

3. 領域模型（domain-model.md）

讀者: 客戶、產品經理、開發團隊

內容:

概念層級的業務實體定義與關聯關係（Mermaid erDiagram）
實體的關鍵屬性與業務約束
實體生命週期與狀態機（Mermaid stateDiagram）
跨實體的業務規則
術語表（Ubiquitous Language）

更新頻率: 初始建模時建立，隨 Epic 撰寫過程迭代更新

與其他文檔的關係:

domain-model.md 回答 "業務中有什麼"（Static Model）— 實體、關聯、術語
epics/ 回答 "業務怎麼運作"（Dynamic Model）— 功能、流程、場景
design/data-models/ 是技術層級的 DB Schema，與 Domain Model 是不同抽象層級

產出方式:

使用 /domain-model 對話式建立，始終採用 Level 2 澄清循環

Domain Model 範本摘要

# {產品名稱}：領域模型

## 概述
## 實體關聯圖（Mermaid erDiagram）
## 核心實體
### {實體名稱} ({English Name})
  - 業務描述
  - 關鍵屬性表（屬性、說明、約束）
  - 狀態機（若有，Mermaid stateDiagram）
## 關聯關係（來源、關係類型、目標、說明）
## 業務規則（跨實體規則）
## 術語表 (Ubiquitous Language)
  - 核心術語表（術語、定義、英文對應、相關實體）
  - 易混淆術語對照
## 與其他文檔的關聯

4. 軟體開發計畫（development-plan.md）

讀者: 開發團隊、Tech Lead、Scrum Master、QA

內容:

專案概覽與成功標準
開發階段規劃
Sprint 規劃與 Backlog
技術棧與應用架構
Git 工作流程與分支策略
測試策略
CI/CD Pipeline
部署策略與回滾計畫

更新頻率: 每個 Sprint 檢視並調整

與 roadmap.md 的關係:

roadmap.md 回答 "為什麼做"（Why）— 產品願景、戰略方向
feature-list.md 回答 "使用者能做什麼"（What）— 功能能力清單
development-plan.md 回答 "怎麼做"（How）— 開發流程、技術實作

實際案例: 花店管理系統開發計畫

5. 研究資料（research/）

讀者: 產品經理、開發團隊

用途: 記錄產品發現階段的研究成果，為 Roadmap、Epic、User Story 提供決策依據。

選用性: 此目錄為選用。團隊可在撰寫 Roadmap 或 Epic 前進行研究，也可跳過直接撰寫。AI Skill（/roadmap、/epic）會自動偵測 research/ 目錄，若存在則讀取作為澄清循環的額外脈絡。

更新頻率: 研究完成時建立，後續作為唯讀參考

訪談紀錄範本

# 訪談紀錄 {N}: {受訪者描述}

## 基本資訊

| 項目 | 內容 |
|------|------|
| 日期 | YYYY-MM-DD |
| 受訪者 | {角色/職稱}（匿名化） |
| 訪談者 | {姓名} |
| 時長 | {N} 分鐘 |

## 關鍵發現
- {發現 1}
- {發現 2}

## 痛點
- {痛點 1}
- {痛點 2}

## 需求與期望
- {需求 1}

## 代表性引述
> "{受訪者原話}"

## 與產品的關聯
- 相關 Epic: {Epic N}
- 相關面向: {功能/流程}

調查報告範本

# 調查報告 {N}: {調查主題}

## 調查概要

| 項目 | 內容 |
|------|------|
| 調查期間 | YYYY-MM-DD ~ YYYY-MM-DD |
| 樣本數 | {N} |
| 目標族群 | {描述} |
| 方法 | 線上問卷 / 電話 / 面對面 |

## 關鍵數據
- {數據點 1}：{數值與意義}
- {數據點 2}：{數值與意義}

## 分析結論
- {結論 1}
- {結論 2}

## 與產品的關聯
- 相關 Epic: {Epic N}
- 相關面向: {功能/流程}

競品分析範本

# 競品分析

## 分析目的
{為什麼做這個分析、關注哪些面向}

## 競品列表

| 競品 | 類型 | 目標市場 | 定價模式 |
|------|------|---------|---------|
| {名稱} | {類型} | {市場} | {定價} |

## 功能對比矩陣

| 功能 | 我們的產品 | 競品 A | 競品 B |
|------|----------|--------|--------|
| {功能} | {狀態} | {狀態} | {狀態} |

## 差異化分析
- **我們的優勢**：{描述}
- **競品的優勢**：{描述}
- **機會點**：{描述}

## 與產品的關聯
- 相關戰略主題: {主題}
- 差異化策略影響: {說明}

6. Epic 文檔

讀者: 產品經理、技術架構師、Team Lead

內容: 從 roadmap 拆分出的詳細 Epic 描述

Epic 範本

# Epic N: {Epic 名稱}

## 業務目標
（為什麼要做這個 Epic？解決什麼問題？）

## 成功指標
（如何衡量 Epic 的成功？）

## 功能範疇
（Epic 包含哪些主要功能？）

## User Stories 列表
（鏈接到 user-stories/ 目錄）

## 技術依賴
（依賴其他 Epic 或外部系統）

## 多租戶考量
（Multi-tenancy 設計要點）

## 安全性考量
（如有特殊安全需求）

實際案例: 花店管理系統 Epics

7. User Story 文檔

讀者: 開發人員、測試人員、產品經理

內容: 使用者故事（遵循 INVEST 原則）

INVEST 原則

Independent: 獨立的（盡量減少依賴）
Negotiable: 可協商的（非合約，可調整）
Valuable: 有價值的（對用戶有明確價值）
Estimable: 可估算的（團隊能估算工作量）
Small: 小的（1-2 個 Sprint 內可完成）
Testable: 可測試的（有明確驗收標準）

User Story 範本

完整範本（含所有區段）定義在 User Stories 目錄索引，以下是核心結構摘要：

# US-{NNN}: {User Story 標題}

## User Story
**作為** {角色}
**我想要** {功能}
**以便** {業務價值}

## 驗收標準 (Acceptance Criteria)
### Scenario 1: {場景名稱}
- **Given** {前置條件}
- **When** {執行操作}
- **Then** {預期結果}

## 業務規則
## UI/UX 需求
## 技術規格
## 驗收檢查清單（Prototype 階段 / 整合階段）
## Story Points

實際案例: 花店管理系統 User Stories

8. SBE 實例化規格 (Specification by Example)

讀者: 開發人員、測試人員

內容: 具體的測試場景與範例數據

格式選擇:

使用者互動流程使用 Gherkin (Given-When-Then)
API 輸入/輸出使用 Markdown 表格

Given-When-Then 格式

Given: 描述前置條件與系統初始狀態
When: 描述執行的操作
Then: 描述預期的結果

SBE 範本

# Scenario N: {場景名稱}

## Given: 系統初始狀態
### 已登入用戶
（JSON 範例數據）

### 現有資料
（資料庫中的預存數據）

## When: 執行操作
### API 請求
（完整的 HTTP 請求範例）

### UI 操作
（如適用，描述用戶介面操作步驟）

## Then: 預期結果
### 系統響應
（API 響應範例）

### 數據庫變更
（哪些表新增/修改了記錄）

### 副作用
（發送通知、觸發事件等）

## 邊界條件
### 錯誤場景 1: {錯誤類型}
（錯誤輸入與預期錯誤響應）

## 自動化測試範例
（可執行的測試代碼片段）

Gherkin 範例

Feature: 建立訂單

  Scenario: 客戶成功建立花束訂單
    Given 客戶已登入系統
    And 購物車中有「經典玫瑰花束」1 件
    When 客戶填寫配送資訊
      | 欄位 | 值 |
      | 收件人 | 王小明 |
      | 電話 | 0912345678 |
      | 地址 | 台北市信義區信義路五段7號 |
      | 配送日期 | 2024-02-14 |
      | 配送時段 | 14:00-16:00 |
    And 客戶點擊「確認訂單」按鈕
    Then 系統顯示訂單確認頁面
    And 訂單狀態為「待確認」

  Scenario: 選擇的配送日期已額滿
    Given 客戶已登入系統
    And 購物車中有商品
    When 客戶選擇配送日期「2024-02-14」
    And 該日期配送名額已滿
    Then 系統顯示「此日期配送已額滿，請選擇其他日期」
    And 客戶無法提交訂單

實際案例: 花店管理系統 SBE

9. API 規格文檔

讀者: 前端開發者、後端開發者

內容: REST API 端點詳細規格

格式: 使用 /api-spec Skill 產生 Bruno (.bru) 格式的 API 規格，存放在 api-specs/ 目錄。

API 規格可透過兩種方式產生：

正向設計 — 從 US/SBE 設計 API 合約（Prototype 階段）
反向萃取 — 從 Spring Controller 提取已實作的 API 規格（整合階段）

實際案例: 花店管理系統 API 規格

10. 數據模型文檔

讀者: 後端開發者、DBA

內容: Entity 定義、關聯關係、欄位說明

數據模型範本

# {Entity 名稱}

## 表名
`{table_name}`

## 用途
（這個 Entity 的業務用途）

## 欄位定義

| 欄位名 | 類型 | 必填 | 說明 | 索引 |
|-------|------|------|------|------|
| id | UUID | Yes | 主鍵 | PK |
| tenant_id | UUID | Yes | 租戶 ID | FK, Index |
| ... | ... | ... | ... | ... |

## 關聯關係
- 一對多: Order → OrderItems
- 多對一: Order → Customer

## 約束條件
（Unique、Check、Default 等）

## 多租戶隔離
（如何確保數據隔離）

## 索引策略
（哪些欄位需要索引，為什麼）

## 範例數據
（JSON 格式的範例記錄）

實際案例: 花店管理系統數據模型

11. 架構決策記錄 (ADR)

讀者: 技術主管、架構師、資深開發者

內容: 重要的技術決策與取捨理由

ADR 範本（MADR 格式）

# ADR-{NNN}: {決策標題}

## 狀態
{已提議 | 已接受 | 已棄用 | 已取代} (日期)

## 背景
（為什麼需要做這個決策？遇到什麼問題？）

## 決策
（我們決定採用什麼方案？）

## 替代方案
1. 方案 A（為什麼被拒絕）
2. 方案 B（為什麼被拒絕）

## 後果
- 優點
- 缺點/權衡
- 需要注意的事項

## 參考資料
（相關文章、技術文檔鏈接）

實際案例: 花店管理系統架構決策

最佳實踐

先寫規格再寫程式碼：確保需求明確再開始開發
保持規格與程式碼同步：API 變更時同步更新 SBE
使用具體範例：避免抽象描述，使用實際的輸入輸出值
涵蓋邊界條件：除了 happy path，也要描述錯誤情境
關聯測試案例：明確標示對應的測試位置
多租戶意識：所有文檔都應考慮數據隔離

文檔	說明
開發流程指南	Step 1–4 開發流程、文檔工作流程、SBE 與後端的對應關係
AI 協助規格撰寫指南	AI Skill 的介入模式、蘇格拉底式閉環、Skill 鏈
Claude Code Skills 總覽	所有 Skill 快速參考索引

文檔層級架構​

命名規範​

1. 產品路線圖（roadmap.md）​

2. 功能清單（feature-list.md）​

Feature List 範本​

欄位說明​

分組原則​

3. 領域模型（domain-model.md）​

Domain Model 範本摘要​

4. 軟體開發計畫（development-plan.md）​

5. 研究資料（research/）​

訪談紀錄範本​

調查報告範本​

競品分析範本​

6. Epic 文檔​

Epic 範本​

7. User Story 文檔​

INVEST 原則​

User Story 範本​

8. SBE 實例化規格 (Specification by Example)​

Given-When-Then 格式​

SBE 範本​

Gherkin 範例​

9. API 規格文檔​

10. 數據模型文檔​

數據模型範本​

11. 架構決策記錄 (ADR)​

ADR 範本（MADR 格式）​

最佳實踐​

相關文檔​