tech-spec-gen

name	tech-spec-gen
version	2.0.0
description	設計文件 → 技術規格生成器 — 將任何設計文件轉換為 AI 可執行的技術實作規格
triggers	["tech-spec","技術規格","spec-gen","implementation-spec","設計轉規格","design-to-spec"]
keywords	["technical-specification","design-document","implementation","tasks","worktree","prd","gdd","frd"]
author	claude-domain-skills

Tech Spec Generator v2.0.0

將 GDD/PRD/FRD 等設計文件轉換為 AI 可執行的技術規格

快速開始

/tech-spec-gen [設計文件路徑]           # 完整轉換
/tech-spec-gen [路徑] --type gdd        # 指定文件類型
/tech-spec-gen module [模組名稱]        # 單一模組轉換
/tech-spec-gen tasks                    # 顯示待實作任務
/tech-spec-gen worktree [task-id]       # 為任務建立 worktree

---

1. 核心理念

設計文件 vs AI 需要的規格

設計文件特徵	AI 需要的規格
敘事性描述	明確的輸入/輸出定義
概念性說明	可驗證的完成標準 (Given-When-Then)
整體願景	獨立可執行的任務切分
靈活的解讀空間	技術決策的明確指引

支援的文件類型

類型	代碼	適用場景
遊戲設計文件	gdd	遊戲開發
產品需求文件	prd	產品開發
功能需求文件	frd	功能實作
系統設計文件	sdd	系統開發
通用設計文件	generic	自動解析

轉換映射規則

設計文件內容	技術規格對應
願景/目標	驗收標準 (Acceptance Criteria)
功能描述	系統架構 + API 設計
業務規則/遊戲機制	資料模型 + 業務邏輯
數值/配置	常數定義 + 配置結構
UI/UX 流程	狀態機 + 畫面規格
實體/角色/用戶	Entity Schema + 行為定義
限制/約束	架構決策記錄 (ADR)

---

2. 五步驟轉換流程

Step 1: 文件解析 → 讀取文件、偵測類型、提取結構
    ↓ [確認點：文件類型]
Step 2: 技術分析 → 分析技術棧、識別模組、標記決策點
    ↓ [確認點：技術棧選擇]
Step 3: 架構設計 → 設計架構、定義模組邊界、設計資料模型
    ↓ [確認點：架構設計]
Step 4: 任務分解 → 依模組分解、建立依賴圖、估算複雜度
    ↓ [確認點：任務分解預覽]
Step 5: 規格產出 → 產生 tech-spec.md + tasks/*.md + ADR

---

3. 任務分解策略

分解黃金規則

• 單一職責：一個任務只做一件事
• 可獨立測試：不需其他任務完成也能測試
• 明確邊界：輸入/輸出有清楚定義
• 適當粒度：一個 session 可完成
• 依賴清晰：依賴關係明確、無循環

任務類型

類型	代碼	說明
基礎建設	INFRA	專案設定、環境配置
資料模型	MODEL	實體定義、Schema
核心邏輯	CORE	業務邏輯、演算法
API 層	API	介面定義、端點
UI 元件	UI	畫面、互動
整合	INTG	模組整合、流程
測試	TEST	單元/整合測試

複雜度估算

複雜度	特徵
S	單一檔案、邏輯簡單
M	多檔案、需要設計
L	多模組互動、需測試
XL	核心架構、複雜邏輯

Phase 劃分

Phase 1: Foundation → 專案初始化、核心資料模型、基礎配置
Phase 2: Core       → 核心業務邏輯、主要 API、資料存取層
Phase 3: Features   → 功能模組實作
Phase 4: Integration → 模組整合、流程串接、整合測試
Phase 5: Polish     → UI 優化、效能調校、文件完善

---

4. Worktree 整合

為什麼用 Worktree?

• 每個任務獨立分支，避免衝突
• 可平行開發多個任務
• 完成即 merge，失敗即刪除
• 保持主分支穩定

工作流程

# 1. 查看可用任務
/tech-spec-gen tasks

# 2. 為任務建立 worktree
/tech-spec-gen worktree T002
# → git worktree add ../[project]-T002 -b feature/T002-xxx

# 3. 在 worktree 中完成實作

# 4. 合併並清理
git checkout main && git merge feature/T002-xxx
git worktree remove ../[project]-T002

Worktree 產生的檔案

../[project]-[task-id]/
├── TASK-SPEC.md          # 任務詳細規格
├── ACCEPTANCE.md         # 驗收標準清單
└── .claude/context.md    # AI Agent 上下文

---

5. 產出結構

docs/tech-spec/
├── tech-spec.md         # 主規格文件
├── tasks/               # 任務規格
│   ├── README.md        # 任務索引與依賴圖
│   ├── T001-xxx.md
│   └── ...
└── adr/                 # 架構決策記錄
    └── ADR-001-xxx.md

---

6. 品質檢查

規格完整性檢查

架構

• 技術棧明確且有依據
• 模組職責清晰不重疊
• 依賴關係明確無循環

資料模型

• 所有實體有完整定義
• 欄位類型和約束明確
• 關係和索引已定義

API 設計

• 所有公開 API 有簽名
• 參數和回傳值有說明
• 錯誤處理已定義

任務分解

• 每個任務有驗收標準
• 依賴關係無循環
• 複雜度估算合理

設計文件對應

• 所有功能有對應任務
• 所有數值有常數定義
• 約束條件有 ADR 記錄

常見問題

問題	解決方案
任務粒度太大	分解為子任務（< 15 驗收標準）
隱含假設	明確列出所有假設
循環依賴	重新設計模組邊界
驗收標準模糊	改為 Given-When-Then 格式
技術棧不明	加入技術決策流程

---

7. 文件類型專屬映射

GDD (遊戲設計文件)

GDD 章節	技術規格對應
設計支柱	ADR (架構約束)
核心玩法	系統架構 + 狀態機
遊戲機制	API 設計 + 業務邏輯
數值設計	常數定義
角色設計	Entity Schema

PRD (產品需求文件)

PRD 章節	技術規格對應
問題定義	驗收標準
用戶故事	功能模組 + API
功能列表	任務分解
成功指標	效能驗收標準

FRD (功能需求文件)

FRD 章節	技術規格對應
功能描述	API 設計
業務規則	業務邏輯 + 驗證規則
數據要求	資料模型
例外處理	錯誤處理策略

---

延伸資源

• 完整模板：extended/templates.md
• 使用範例：extended/examples.md
• 遊戲設計：搭配 /game-planner 產生 GDD
• 通用 Galgame：搭配 /galgame-master 創作內容

---

版本歷史

版本	日期	變更
2.0.0	2026-01-15	通用化：支援 GDD/PRD/FRD/SDD/Generic
1.0.0	2026-01-15	初版：GDD 專用轉換器