Tech Spec Gen

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 專用轉換器 |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: miles990
• Source: miles990/claude-domain-skills
• License: MIT

Install and usage instructions live in the source repository linked above.