specify

建立功能規格書

從自然語言功能描述建立功能規格書，遵循專案標準範本格式。

模式說明

模式	觸發方式	適用情境	產出文件
標準模式	{描述}	全新功能	{功能名稱}後端功能規格書.md
調整模式	--change {描述}	原功能新功能調整	CR-BFS + CR-FFS（同時產出）

使用者輸入

$ARGUMENTS

使用者輸入的文字即為功能描述。

模式偵測

解析 $ARGUMENTS：

• 包含 --change → 調整模式，移除旗標後繼續解析描述
• 不包含 --change → 標準模式

---

核心原則：不猜測

遇到不清楚或有疑問的地方，絕不猜測，依以下順序處理：

1. 先找答案 — 在當前目錄或專案中搜尋相關文件、程式碼、DB 結構，嘗試自行找到答案
2. 找不到就問 — 使用 AskUserQuestion 詢問使用者，必須附上建議的解決方案供選擇
3. 確認後才寫 — 所有疑問解決後才開始撰寫文件
4. 寫前總清查 — 文件撰寫前，重新檢查所有已收集的資訊，確認無遺漏疑問

禁止：使用 [需要澄清] 標記帶過問題。所有問題必須在寫文件前解決。

---

標準模式執行流程

1. 解析功能描述

分析使用者輸入，提取：

• 功能名稱：2-4 個字的短名稱（中文或英文）
• 所屬模組：從描述中判斷功能所屬的業務領域
• 功能類型：CRUD API / 排程同步 / 混合類型

2. 確定儲存位置

探索專案中既有文件目錄，遵循專案慣例。若無慣例，預設使用：

docs/{模組名稱}/{功能名稱}/{功能名稱}後端功能規格書.md

3. 載入規格範本

讀取 ${CLAUDE_SKILL_DIR}/../../templates/bfs.md 以了解必要的章節結構。

4. 查詢相關資料

使用 MCP 工具查詢資料表結構：

-- 查詢資料表結構
SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, IS_NULLABLE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_NAME = '{TableName}'

5. 撰寫規格書

撰寫前，遵循以下規範：

命名規則速查

概念	命名規則	範例
主鍵	{Entity}Id	SalesOrderId
編號	{Entity}No	PurchaseOrderNo
外鍵	{Role}Id	VendorId, CustomerId
日期	{Purpose}Date	DeliveryDate
金額	{Purpose}Amount	TotalAmount
布林	Is{State}	IsCompleted

轉換規則：

• DB → Model：CUST_NO → CustNo（PascalCase）
• Model → JSON：VendorId → vendorId（camelCase）

Request/Response 規範

Request：關聯欄位使用 Id

{ "vendorId": "4AR", "currencyCode": "NTD" }

Response：使用巢狀物件

{
  "vendor": { "id": "4AR", "name": "供應商名稱" },
  "currency": { "code": "NTD", "name": "新台幣" }
}

巢狀物件標準結構：

物件	結構
vendor/customer	{ id, name }
currency	{ code, name }
{type}	{ id, code, name }
{role}Employee	{ id, name }

API 端點標準

遵循專案 API 路由規範。標準 CRUD 模式：

/{module}/{entity}           ← 列表 / 新增
/{module}/{entity}/{id}      ← 單筆查詢 / 更新 / 刪除
/{module}/{entity}/Paged     ← 分頁查詢
/{module}/{entity}/Light     ← 選擇器

操作	成功	失敗
GET	200	404
POST	201	400/409
PUT	200	400/404
DELETE	204	404

規格書內容規範

禁止程式碼：規格書中禁止包含任何程式語言框架程式碼。

允許的內容：Mermaid 圖、JSON 範例、檔案結構樹、虛擬碼

API 端點完整性：每個端點必須包含 HTTP 方法+路由、Request/Response 說明、成功 JSON 範例、錯誤回應說明。

語義化命名：Request/Response 屬性必須使用語義化業務名稱，禁止直接使用資料庫欄位名稱。

禁止	正確	說明
custNo	vendorId	使用角色語義
date1	outsourceDate	使用用途語義
qty1	quantity	使用業務語義

流程圖格式

使用 Mermaid：flowchart、erDiagram、stateDiagram-v2

注意：ER 圖不使用 PK_FK 複合角色，正確寫法：{type} {FieldName} PK "FK to OtherTable"

操作後續動作（若操作需觸發其他業務）

某些操作完成後可能需觸發副作用（如審計日誌、通知、其他模組更新）。規格書應明確定義：

• 哪些操作完成後需要後續處理
• 後續處理的內容與目標
• 是否需要在同一交易中完成

---

根據功能類型填寫對應章節：

功能類型	必填章節	選填章節
CRUD API	1-6, 8-15	7（排程）
排程同步	1-3, 7, 9-15	4-6（可簡化）
混合類型	1-15	-

6. 疑問點總清查（寫文件前必做）

在開始撰寫規格書前，逐一檢查以下面向是否仍有未解決的疑問：

面向	檢查問題
資料表	所有涉及的資料表結構都已確認？
API 端點	每個端點的 Request/Response 結構都明確？
業務規則	每條規則的判斷條件和處理方式都清楚？
驗證規則	每個欄位的驗證條件（型態、長度、必填）都確認？
關聯	外鍵關聯和參照表都已識別？
計算	所有計算公式和邏輯都已定義？

若仍有任何疑問：回到步驟 1-4 重新搜尋或詢問使用者，直到全部解決。 全部解決後：才進入步驟 7 撰寫規格書。

7. 驗證規格品質

確保規格書符合以下標準：

• 無實作細節（語言、框架、API）
• 需求可測試且明確
• 成功標準可衡量
• 所有驗收場景已定義
• 範圍清楚界定
• 無任何未解決的疑問（已全部在寫前釐清）

8. 自動驗證與修復（寫完即驗證）

規格書寫入磁碟後，必須自動執行驗證修復循環：

• 若同目錄有 FRD 文件，同時驗證 FRD↔BFS 追溯性
• 若文件來自舊系統分析，自動觸發舊系統交叉比對

流程與修復策略詳見 ${CLAUDE_SKILL_DIR}/../../references/auto-verification-loop.md（BFS 修復策略段落）。

9. 報告完成

報告：

• 規格書路徑
• 章節完成狀態
• 所有疑問已釐清確認
• 下一步建議（開始規劃實作）

文件範本

撰寫規格書時，必須參考以下範本確保格式一致：

範本	用途	路徑
功能需求文件範本	業務需求與使用者故事	${CLAUDE_SKILL_DIR}/../../templates/frd.md
後端功能規格書範本	後端 API 規格書	${CLAUDE_SKILL_DIR}/../../templates/bfs.md
前端功能規格書範本	前端 UI 規格書	${CLAUDE_SKILL_DIR}/../../templates/ffs.md

---

調整模式執行流程

適用：原功能的新功能調整，同時產出 CR-BFS + CR-FFS

B1. 識別調整內容

分析使用者描述，提取：

• 功能名稱：對應哪個既有功能
• 所屬模組：從描述中判斷
• 異動票號：從描述或 $ARGUMENTS 中提取（如 ticket ID）

B2. 查詢原始文件

使用 Task 工具（subagent_type=Explore）同時定位：

• 原始後端規格書（BFS）
• 原始前端規格書（FFS）
• 功能調整需求文件（CR-FRD，若已存在）

若找不到原始文件：詢問使用者原始文件路徑，或確認是否要改用標準模式。

B3. 確定儲存位置

探索專案中既有文件目錄，遵循專案慣例。若無慣例，預設使用：

docs/{模組名稱}/{功能名稱}/{功能名稱}_功能調整後端規格書_{ticket}.md  ← CR-BFS
docs/{模組名稱}/{功能名稱}/{功能名稱}_功能調整前端規格書_{ticket}.md  ← CR-FFS

若無票號，使用日期：{功能名稱}_功能調整後端規格書_{YYYYMMDD}.md

B4. 查詢資料庫結構

只查詢有異動的資料表：

SELECT COLUMN_NAME, DATA_TYPE, CHARACTER_MAXIMUM_LENGTH, IS_NULLABLE
FROM INFORMATION_SCHEMA.COLUMNS
WHERE TABLE_NAME = '{有異動的TableName}'
ORDER BY ORDINAL_POSITION

B5. 同時撰寫 CR-BFS + CR-FFS

使用並行方式（Task 工具）同時產出兩份文件：

CR-BFS 撰寫重點

參考 ${CLAUDE_SKILL_DIR}/../../templates/cr-bfs.md，必填章節：

章節	重點
參照文件	原始 BFS、FFS、CR-FRD 的路徑與版本
1. 變更摘要	異動清單（[+]/[~]/[-]）+ Breaking Change 評估
2. 影響分析	受影響的原始端點列表
3. 資料模型變更	只寫有異動的 Entity/Table，含 ER 差異圖
4. API 異動規格	每個異動端點的完整規格（含 JSON 範例）
5. 驗證規則異動	只寫新增/修改的 VR/BR
6. 讀寫邏輯異動	新增/修改的查詢邏輯、業務操作方法
7. 測試案例補充	含迴歸測試

命名規則（同標準 BFS）：

• 屬性名稱：PascalCase（表格）→ camelCase（JSON）
• 異動標記：[+] 新增 / [~] 修改 / [-] 移除

CR-FFS 撰寫重點

參考 ${CLAUDE_SKILL_DIR}/../../templates/cr-ffs.md，必填章節：

章節	重點
參照文件	原始 FFS、BFS、CR-FRD、CR-BFS 的路徑與版本
1. 變更摘要	畫面/元件異動清單（[+]/[~]/[-]）
2. 畫面異動	只描述有變更的畫面，含異動後示意圖
3. 操作流程異動	新增/修改的操作流程 Mermaid 圖
4. 欄位驗證異動	只寫新增/修改的驗證規則
5. API 對接異動	對應 CR-BFS 的端點，含 Request/Response 異動
6. 業務邏輯異動	連動、計算、狀態控制的變更

B6. 疑問點總清查（調整模式）

與標準模式步驟 6 相同：所有疑問必須在寫文件前解決，不使用 [需要澄清] 標記。 特別注意：向後相容性影響、Breaking Change 範圍是否都已確認。

B7. 自動驗證（調整模式）

兩份文件寫入後，執行規格書驗證：

• CR-BFS：驗證格式完整性 + DB 欄位交叉驗證（只含異動欄位）
• CR-FFS：驗證格式完整性
• 交叉驗證：CR-BFS 的異動端點在 CR-FFS 的 API 對接清單中有對應

B8. 報告完成（調整模式）

## 功能調整規格書完成報告

**後端規格書（CR-BFS）**：`docs/{模組}/{功能}/{功能}_功能調整後端規格書_{ticket}.md`
**前端規格書（CR-FFS）**：`docs/{模組}/{功能}/{功能}_功能調整前端規格書_{ticket}.md`

### 異動摘要

| 類型 | CR-BFS | CR-FFS |
|------|--------|--------|
| [+] 新增 | {N} 個端點 | {N} 個元件 |
| [~] 修改 | {N} 個端點 | {N} 個元件 |
| [-] 移除 | {N} 個端點 | {N} 個元件 |
| ⚠️ Breaking Change | {N} 個 | {N} 個 |

### 下一步建議

- 規格書已完成 → 規劃實作（複雜功能）或直接開始實作

---

完整開發流程

詳見 ${CLAUDE_SKILL_DIR}/../../references/upstream-workflow.md。

---

下一步（Pipeline 銜接）

規格書產出後，建議執行：

sdlc:verifying-specs {規格書路徑}

驗證通過後再進入實作計畫階段。完整 pipeline 見 ${CLAUDE_SKILL_DIR}/../../references/pipeline.md。 | 執行實作 | 兩者 | 後續 | 依規格書進行開發 |