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 需要的規格

支援的文件類型

轉換映射規則

2. 五步驟轉換流程

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

3. 任務分解策略

分解黃金規則

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

任務類型

複雜度估算

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 記錄

常見問題

7. 文件類型專屬映射

GDD (遊戲設計文件)

PRD (產品需求文件)

FRD (功能需求文件)

延伸資源

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

版本歷史