| name | vibe-sdlc-spec |
| description | Vibe-SDLC Phase 1：定義規格文件與計畫，協助撰寫與審查 PRD、SRD、SDD、API Spec、Dev Plan。 使用時機：專案啟動需要建立規格文件與計畫，或需要審查既有規格的完整性與一致性。
|
| user_invocable | true |
Phase 1：定義規格文件與計畫
目的
建立專案的完整真相來源（Single Source of Truth）。此階段應充分與開發者討論，生成高品質規格文件與計畫，所有後續工作皆以此為依據。
你的角色
你是 AI 助手（執行者）。在此階段你的職責是：
- 協助開發者撰寫與完善規格文件
- 交叉比對四份規格文件，找出不一致或遺漏
- 產出完整性審查報告
你不應該：在需求定義階段自行決定商業需求或技術選型，這些應該在需求完成後與開發者討論後進行決策。
前置條件
- 工作目錄已確立（可為空目錄；若本地 git 倉庫、
CLAUDE.md、/docs 目錄皆不存在，skill 會自動進入「空專案初始化」流程）
- GitHub 倉庫可選（若缺，會在初始化面板中提示由使用者手動建立）
交付物
| 文件 | 檔名 | 存放路徑 | 類型 | 說明 |
|---|
| 文件入口與導航 | 00-Docs_Index.md | /docs/00-Docs_Index.md | 必要 | 規格文件導航索引，列出所有文件清單、建立/更新時機、依賴關係 |
| 產品需求文件 (PRD) | 01-1-PRD.md | /docs/01-1-PRD.md | 必要 | 偏重產品面或客戶的需求及要求，可能衍生 UI/UX 需求 |
| 系統需求文件 (SRD) | 01-2-SRD.md | /docs/01-2-SRD.md | 必要 | 非功能性需求（NFR）、部署要求、約束與安全合規 |
| 系統設計文件 (SDD) | 01-3-SDD.md | /docs/01-3-SDD.md | 必要 | 系統架構、元件設計、數據模型、技術決策記錄（ADR） |
| 遊戲設計文件 (GDD) | 01-4-GDD.md | /docs/01-4-GDD.md | 領域選用 | 遊戲專案專用：核心機制、數值設計、關卡設計。僅遊戲類專案需要 |
| API 介面規格 | 01-5-API_Spec.md | /docs/01-5-API_Spec.md | 必要 | API 規格說明 |
| API 介面合約 | API_Spec.yaml | /docs/API_Spec.yaml | 必要 | OpenAPI 規格 |
| UI/UX 設計文件 | 01-6-UI_UX_Design.md | /docs/01-6-UI_UX_Design.md | 選用 | UI/UX 設計規格（視覺風格、互動流程、Design Tokens），若 PRD 衍生 UI/UX 需求時建立。撰寫前 必須 先讀 references/UI_UX_Writing_Guidelines.md |
| UI Wireframe | ui/{page}.html | /docs/ui/*.html | 選用 | 每個頁面一檔的 HTML + Tailwind CDN 視覺參考，由 01-6-UI_UX_Design.md 以 link 引用（規則詳見 UI_UX_Writing_Guidelines.md §9） |
| 開發執行計畫 | 02-Dev_Plan.md | /docs/02-Dev_Plan.md | 必要 | 里程碑、任務拆解、依賴關係 |
| 規格審查報告 | 03-Docs_Review_Report.md | /docs/03-Docs_Review_Report.md | 必要 | 交叉比對結果、不一致與遺漏項目 |
| CI/CD 規格文件 | 04-CI_CD_Spec.md | /docs/04-CI_CD_Spec.md | 選用 | CI Workflow 定義、品質閘門、Docker 部署配置（複雜專案建議獨立，Dev Plan 以連結引用） |
重要：
- 每項規格都應賦予規格編號以利後續追蹤與討論。
- 每個任務都應賦予任務編號以利後續追蹤與討論。
UI/UX 設計文件撰寫準則
若需建立 01-6-UI_UX_Design.md，AI 助手必須先讀取 references/UI_UX_Writing_Guidelines.md 並遵循該指引的 9 條準則撰寫。指引重點：
- 結構、狀態、欄位、呈現邏輯、元件庫指名：以 markdown 表格結構化描述（準則 1–8）
- 流程圖：頁面跳轉、對話流、狀態機一律使用 Mermaid flowchart，不使用 ASCII 箭頭或圖片（準則 2）
- 視覺空間感：使用 HTML + Tailwind CDN 獨立檔案，放置於
/docs/ui/，由 markdown 規格書以 relative link 引用（準則 9）
- 每條準則均附自檢方法，AI 產出後必須對照指引末段 checklist 自檢
UI/UX 產出物結構：
/docs/01-6-UI_UX_Design.md — 規格權威（markdown，AI 實作時以此為準）/docs/ui/{page}.html — 視覺參考（每個 §3.x 頁面對應一檔，低保真 wireframe 使用灰階 palette）
核心原則：markdown 規格書是實作權威，HTML wireframe 是視覺輔助。兩者衝突時以 markdown 為準。
版本修訂記錄格式規範
所有 /docs 規格文件皆須包含版本管理資訊，格式如下：
文件開頭（必要）
> **版本**：v{major}.{minor}
> **最後更新**：{YYYY-MM-DD}
文件結尾 — 版本修訂說明表格（必要）
---
## 版本修訂說明
| 版本 | 日期 | 修訂內容 |
|------|------|---------|
| v1.0 | 2026-03-16 | 初版定稿 |
| v1.1 | 2026-03-21 | {修訂摘要，列出新增/修改的章節與內容} |
版本號規則
| 變更類型 | 版本遞進 | 範例 |
|---|
| 新增功能需求（如新增 PRD-F-XXX） | minor +1 | v1.0 → v1.1 |
| 修正錯誤、補充遺漏、格式調整 | minor +1 | v1.1 → v1.2 |
| 重大架構變更、破壞性修改 | major +1 | v1.2 → v2.0 |
修改規格文件時的必要動作
每次修改 /docs 下的規格文件時，必須同步更新以下三處：
- 文件開頭的 版本號（遞進）
- 文件開頭的 最後更新日期（改為當天）
- 文件結尾的 版本修訂說明表格（新增一行，摘要說明本次修訂內容）
注意：OpenAPI YAML 檔（如 API_Spec.yaml）的版本號寫在 info.version 欄位，修訂說明寫在 info.description 欄位中。
參考範例
請參考 examples/docs/ 目錄下的文件。
操作步驟
| 步驟 | 執行者 | 操作 | 產出 |
|---|
| 0 | 開發者 | 建立文件入口：初始化 Docs Index，登錄預計建立的文件清單 | 00-Docs_Index.md |
| 1 | 開發者 | 撰寫 PRD：定義功能清單、使用者故事、資料欄位，並與開發者討論並優化 PRD | 01-1-PRD.md |
| 2 | 開發者 | 撰寫 SRD：當 PRD 定義完成後，定義非功能性需求（NFR）、部署要求、約束與安全合規 | 01-2-SRD.md |
| 3 | 開發者 | 撰寫 SDD：當 SRD 定義完成後，定義系統架構、技術棧選型、數據模型、設計決策記錄（ADR） | 01-3-SDD.md |
| 4 | 開發者 | 定義 API Spec：以 OpenAPI 格式定義所有端點、請求/回應結構 | 01-5-API_Spec.md, API_Spec.yaml |
| 5 | 開發者 | 撰寫 Dev Plan：當 PRD、SRD、SDD、API Spec 定義完成後，拆解里程碑、任務清單、任務間依賴關係 | 02-Dev_Plan.md |
| 6 | 開發者 | 確認以上文件均已提交至 /docs 目錄並推送至倉庫 | Git commit & push to Github (or Gitlab) |
| 7 | AI 助手 | 交叉比對 /docs 下規格文件，產出完整性審查報告 | 審查報告 |
| 8 | 開發者 | 審閱報告，修正規格缺漏後重新提交 | 最終版規格 |
SRD 與 SDD 的分工：SRD 定義「系統應該達到的需求與約束」（如性能目標、安全要求），SDD 負責描述「如何設計系統來滿足這些需求」（如架構選型、元件設計）。
領域專用文件：遊戲類專案應在步驟 1 之後額外建立 01-4-GDD.md（遊戲設計文件），定義核心機制、數值設計與關卡設計。其他領域專用文件（如資料設計文件）可視需求於適當步驟加入。
Dev Plan 格式規範
可依需求規格相關文件(包含PRD、SRD、API Spec、...等)生成 Dev Plan(開發計畫)，然後與開發者討論並優化。
範例文件：02-Dev_Plan.md
核心設計原則
- 面向 AI Agentic Coding：計畫以 Main Agent + Sub Agents (子代理) 為執行單位，非傳統人類團隊。
- API First 契約驅動：前後端透過
API_Spec.yaml 解耦，Sub Agents 可高度並行開發。
- Human Gate 機制：每個 Milestone 設有人類驗收門，由人類導演決定是否進入下一階段。
文件結構 (必須包含以下章節)
- 角色定義 (Role Registry)：全文唯一角色定義來源（含 GitHub 帳號與認證配置）
- 項目概況與時間表：里程碑 Gantt 圖 (Mermaid)、工作量估算
- 里程碑定義：每個 Milestone 的目標、AI 執行策略、交付物、人類決策點
- 任務清單：任務總覽表格 + 任務詳細描述 + 並行群組視覺化 (Mermaid)
- 技術實施方案：前後端技術棧、數據庫與部署配置
- 風險識別與應對：AI 開發視角的風險 (如 Regression、上下文不同步、除錯迴圈)
- 質量保證計畫 (Vibe Check)：CI/CD 閘口、Human-in-the-Loop 審查
- 溝通與協作：狀態同步中心、文件存取約定 (Single Source of Truth)
角色定義格式
必須在文件最開頭以表格定義所有角色，包含：角色代號、角色名稱、類別 (🧑 人類 / 🤖 AI)、GitHub 帳號、Git Author、說明。後續全文引用角色時必須使用此處定義的代號，禁止前後不一致。
建議角色配置：
| 類別 | 建議角色 | GitHub 帳號 | 說明 |
|---|
| 🧑 人類 | H-Director (導演) | @owner | 最高決策、規格審查、Milestone 驗收、PR 合併 |
| 🧑 人類 | H-Reviewer (審查員) | (同 Director 或獨立帳號) | 特定領域審查（安全/合規性），可由 Director 兼任 |
| 🧑 人類 | H-UxReviewer (UX 審查員) | (同 Director 或獨立帳號) | UX 相關審查，可由 Director 兼任或由 AI Agent 代理 |
| 🤖 AI | A-Main (主代理) | (同 Director 或獨立帳號) | 統籌拆解 Issue、協調 Sub Agents、整合驗證 |
| 🤖 AI | A-Backend (後端子代理) | @ext-dev 或 @owner | 專注後端 API、DB、ORM |
| 🤖 AI | A-Frontend (前端子代理) | @ext-dev 或 @owner | 專注 UI 組件、頁面、狀態管理 |
| 🤖 AI | A-QA (測試子代理) | (同 Director 或獨立帳號) | E2E 測試、覆蓋率 |
| 🤖 AI | A-DevOps (部署子代理) | (同 Director 或獨立帳號) | CI/CD、Docker、監控 |
多帳號協作：多個角色可共用同一 GitHub 帳號（單人專案），也可每個角色使用獨立帳號（多人或外部成員協作）。角色表中需填寫 GitHub 帳號 與 Git Author，並在 §1.5 中配置認證方式與 Repo 權限。詳細配置步驟請參考 帳號配置指南。
任務總覽表格格式
| ID | 任務名稱 | 優先級 | 負責角色 | 前置任務 | PR 策略 | 預估耗時 |
|----|---------|-------|---------|---------|--------|----------|
| T-101 | [任務名稱] | P0 | A-Backend | — | 與 T-102 合併 | ~N AI Sessions |
| T-102 | [任務名稱] | P0 | A-Backend | — | 與 T-101 合併 | ~N AI Sessions |
| T-103 | [任務名稱] | P0 | A-Frontend | — | 獨立 PR | ~N AI Sessions |
| T-104 | [任務名稱] | P0 | A-DevOps | T-102, T-103 | 獨立 PR | ~N AI Sessions |
| ⛳ M1 | M1 驗收門 | P0 | H-Director | T-103, T-104 | — | ~N HRH |
- 前置任務：直接在總覽表中列出依賴關係，使依賴鏈一目了然，無需翻閱詳細描述。若無前置任務填
—。
- PR 策略：標記任務的 PR 提交方式。同一 Agent 的多個無依賴任務應合併為一個 PR（如「與 T-102 合併」），其餘填「獨立 PR」。驗收門填
—。
- 預估耗時：AI 角色用
AI Sessions (一次完整 Agent 對話執行)；人類角色用 HRH (Human Review Hours)。
- 優先級：
P0 為關鍵路徑必須完成、P1 為重要但非阻塞、P2可選任務但建議完成(時間允許時應該完成此任務)、P3可選任務(可做可不做，但若完成對專案可能有加分效果)。
任務詳細描述格式
每個任務以下列結構描述：
**T-{ID}：{任務名稱}**
- **任務描述**：概述該任務的目標
- **主要步驟**：
1. 步驟一：具體操作描述
2. 步驟二：具體操作描述
3. ...
- **前置任務**：前置任務 ID，若無填 `（無）`
- **輸入**：依賴或參考的文件，若無填 `（無）`
- **產出**：此任務的輸出/產出文件或源碼，若無填 `（無）`
- **驗證**：
- ✅ 自動：可在 CI 中自動執行的驗證（單元測試、lint、type check、build）
- 👁️ 手動：需人工操作的驗證（視覺效果、裝置測試、外部 API 整合）
- **優先級**：任務的優先等級
主要步驟：以 numbered list 條列該任務的具體執行步驟，便於 Sub Agent 逐步對照執行。步驟應具體到可操作的程度（如「安裝依賴 X」、「實作 Y 端點」），而非抽象描述。
驗證分類：每個驗證條件必須標記為 ✅ 自動 或 👁️ 手動，明確區分 CI 可執行與需人工操作的項目。
並行與依賴規則
- 使用「並行群組 (G)」標記可同時執行的任務
- 同一群組內的任務可由不同 Sub Agents 同時開發
- 群組之間依序進行，以 ⛳ 驗收門 (Human Gate) 作為分界
- 使用 Mermaid
flowchart 的 fork/join 語法視覺化並行關係
同 Agent 並行任務處理
- 當同一並行群組內有多個任務分配給同一 Agent（如 T-101、T-102 都是 A-Backend），這些任務在該 Agent 內部為依序執行（單一 Worktree 限制），但與其他 Agent 的任務仍為跨 Agent 並行。
- 同一 Agent 的多個無依賴任務，應合併為一個 PR 提交，避免同目錄多次 PR 造成合併衝突。
- Mermaid 並行圖中，應使用
subgraph 標示同 Agent 的依序執行關係，與跨 Agent 並行區分。
Dev Plan 常見錯誤防範
CI/CD 時序原則
- CI Workflow 必須在 M1 建立，不可延遲到最後的 Milestone。CI 是所有 PR 品質閘門的基礎，若 CI 只在最後才建立，前面所有 Milestone 的 PR 都沒有自動檢查保護，與「每次 PR 觸發 CI Gate」的品質保證計畫自相矛盾。
- CI 任務依賴前後端骨架（需要
package.json 和 npm scripts），但所有功能開發任務必須依賴 CI 就緒，確保功能 PR 提交時已有自動品質閘門。
- 正確的依賴鏈：
骨架任務 → CI 任務 → 功能開發任務。
- 任務編號應反映此順序：CI 任務排在骨架之後、功能開發之前（例如骨架為 T-101~T-103、CI 為 T-104、功能開發為 T-105 起）。
- 當 CI/CD 配置較複雜（多 Job、E2E、Service Container 等），應獨立為
04-CI_CD_Spec.md，Dev Plan 以連結引用，避免 Dev Plan 過於冗長。
驗證條件設計原則
- 每個任務的驗證條件必須區分
✅ 自動（CI 可執行）與 👁️ 手動（需人工操作），不可混為一談。
- 禁止將以下項目列為自動驗證條件：
- 依賴外部 API Key 的測試（LLM、第三方服務）→ 單元測試必須使用 Mock Provider
- 視覺效果驗證（動畫、顏色漸變、佈局）→ 自動驗證僅確認 CSS class 正確套用，視覺效果標記為手動驗證
- 裝置特定功能（手機安裝 PWA、語音辨識、特定瀏覽器行為）→ 標記為手動驗證
- 外部 API 回應時間（不可控因素）→ 改為驗證已配置 timeout 與重試機制，實際延遲在 staging 環境手動觀測
任務拆分原則
- 功能性質不同的工作不應合併為同一任務。例如「CI/CD + Docker + PWA」包含三種不同性質的工作，應拆為獨立任務並放到合理的 Milestone。
- 判斷標準：若一個任務的子項目屬於不同 Milestone 的時間點，則應拆分。
Bootstrap 階段 PR 規則
- M1 中 CI 任務（如 T-104）就緒前的初始化任務，其 PR 無法通過 CI 閘門。Dev Plan 應明確標注這些任務為「Bootstrap PR」，由 H-Director 直接審查合併，不經過 A-Main 初審與 CI 檢查。
- CI 就緒的分界點（通常是 CI 任務合併之後）必須在 Dev Plan 的 M1 里程碑說明中明確標示。
同 Agent 多任務合併原則
- 當同一並行群組中有多個任務分配給同一 Agent（如 T-101 + T-102 都是 A-Backend），由於單一 Agent 只有一個 Worktree，這些任務實際上為依序執行。
- 應在任務總覽表的「PR 策略」欄位中標注「與 T-XXX 合併為一個 PR」，並在 Mermaid 並行圖中使用
subgraph 標示 Agent 內部的依序關係。
手動驗證任務原則
- 當任務的驗證條件中包含
👁️ 手動 項目時，每個手動驗證項應建立獨立的 Issue，指派給對應的人類審查角色。
- 手動驗證 Issue 的前置任務為其對應的功能開發 Issue（功能完成後才能驗證）。
- 手動驗證 Issue 必須在 ⛳ 驗收門之前完成。
指派原則：
| 驗證類型 | 指派角色 | 範例 |
|---|
| 視覺效果、互動體驗、UI 佈局、動畫、裝置相容性 | H-UxReviewer | 預算血條顏色漸變、PWA 安裝體驗、語音按鈕手動測試 |
| 安全性、合規性、API 整合、資料正確性 | H-Reviewer | LLM 引擎整合測試（需真實 API Key）、權限驗證 |
| 端到端業務流程、功能驗收 | H-Director | 完整記帳流程操作驗證 |
命名規範：手動驗證 Issue 標題格式為 [驗證] T-{ID} {驗證項目簡述}，例如：
[驗證] T-201 Gemini/OpenAI 引擎整合測試[驗證] T-203 語音辨識瀏覽器相容性測試[驗證] T-302 預算血條視覺效果驗收
繪圖規範
文件中所有流程圖、時間表、依賴關係圖，一律使用 Mermaid 語法，禁止使用 ASCII Art。建議圖表：
- 里程碑時間表：
gantt
- 任務分發流程：
flowchart LR
- 並行群組視覺化：
flowchart TB (fork/join 模式)
Git 協作策略 (Multi Sub Agent)
當多個 Sub Agents 並行開發時，Dev Plan 應包含以下 Git 協作規範：
Worktree 使用
- 每個 Sub Agent 應使用獨立的 Git Worktree 在各自的分支上開發，避免
checkout 切換衝突。
- Worktree 建立命令：
git worktree add ../worktree-<agent> <branch>
- 主 Worktree 保留給 A-Main 執行整合工作。
分支命名規範
⛔ 嚴格禁止直接 push 至 main，所有變更一律透過分支 + PR 流程。main 為唯讀基準分支，dev/main-agent 為 A-Main 的快照分支（不承接任何工作 commit）。
| 條件 | 分支命名 | 生命週期 | 說明 |
|---|
| 有 Issue | feat/<agent>/issue-N-簡述 | 短期 | 所有 Issue-based 開發，PR 合併後刪除 |
| 無 Issue（小修） | chore/main-agent/<YYYYMMDD>-<簡述> | 短期 | typo、文案、聯調連續小修；從 origin/main 建出，PR 合併後刪除 |
| A-Main 快照 | dev/main-agent | 永久（允許 force-update） | 由 /vibe-sdlc-status 管理，僅承載 STATUS / dashboard 快照 commit。嚴禁承接工作 commit 或從其分出新分支 |
Per-issue 分支範例：
feat/backend/issue-12-auth-apifeat/frontend/issue-15-login-uifeat/devops/issue-20-docker-setup
Chore 分支範例：
chore/main-agent/20260410-typo-readmechore/main-agent/20260410-integration-fixes
dev/main-agent 快照分支生命週期：
- 首次建立：
git checkout -b dev/main-agent origin/main && git push -u origin dev/main-agent
- 後續維護：由
/vibe-sdlc-status 在彙整 STATUS 時 git reset --hard origin/main + 重新 commit + git push --force-with-lease
- 永遠不刪除，但不保證歷史線性（這是設計上的合約）
- 詳細規則見
/vibe-sdlc-status 的「A-Main 快照分支」章節與 /vibe-sdlc-dev 的「分支策略」
Bootstrap 階段（CI 建立前的 PR 處理）
M1 中，CI Pipeline 本身就是開發任務之一（如 T-104），在 CI 就緒前提交的初始化 PR 無法經過 CI 閘門檢查：
- Bootstrap PR（CI 建立前的任務）直接由 H-Director 審查合併，不經過 CI 閘門與 A-Main 初審。
- Sub Agent 建立 PR 時直接指定 reviewer：
gh pr create --reviewer <H-Director-username>
- CI 就緒後（如 T-104 合併後），所有後續 PR 必須通過 CI 檢查，恢復標準雙層審查流程。
H-Director 通知機制
| 場景 | 通知方式 |
|---|
| Bootstrap 階段 | gh pr create --reviewer <H-Director-username>，GitHub 自動發送 Review Request 通知 |
| 標準流程 | A-Main 初審通過後執行 gh pr edit --add-reviewer <H-Director-username>，GitHub 自動通知 |
| Milestone 驗收 | A-Main 在 GitHub Issue 中 @H-Director 並附上驗收檢查清單 |
PR 審查流程（標準流程，CI 就緒後適用）
flowchart LR
SUB["Sub Agent<br/>gh pr create"] --> CI["GitHub Actions<br/>CI 檢查"]
CI -->|通過| MAIN["A-Main 初審"]
CI -->|失敗| SUB
MAIN -->|通過| REQ["A-Main 執行<br/>gh pr edit<br/>--add-reviewer H-Director"]
REQ --> DIR["H-Director<br/>收到 GitHub 通知<br/>終審 & Merge"]
MAIN -->|駁回| SUB
- Sub Agent 完成開發後提交 PR，目標分支為
main（或指定的整合分支）。
- A-Main 進行初審：確認 PR 範圍僅限該 Agent 負責的目錄、CI 通過、無型別錯誤。
- A-Main 初審通過後，執行
gh pr edit --add-reviewer <H-Director-username> 通知 H-Director。
- H-Director 進行終審：Code Review 後決定 Merge 或要求修改。
合併順序與衝突處理
- 同一並行群組內的 PR，無依賴關係者 可依完成先後合併。
- 若合併後產生衝突，由 A-Main 負責 rebase 並解決衝突。
- 禁止 Sub Agent 直接修改其他 Agent 負責範圍內的檔案。
PR 範圍限制
| Sub Agent 角色 | 允許修改的路徑 |
|---|
| A-Backend | /backend/** |
| A-Frontend | /frontend/** |
| A-QA | /tests/** |
| A-DevOps | .github/**, docker/**, Dockerfile, docker-compose.yml |
| A-Main | 全專案 (整合與修復用) |
審查報告格式
當執行步驟「交叉比對規格文件」時，按以下格式產出報告至 /docs/03-Docs_Review_Report.md：
# 規格完整性審查報告
## 審查範圍
- 比對文件：00-Docs_Index.md, 01-1-PRD.md, 01-2-SRD.md, 01-3-SDD.md, 01-5-API_Spec.md, 02-Dev_Plan.md, ...
## 不一致項目
| 編號 | 文件 | 不一致描述 | 建議修正 |
|------|------|------------|----------|
> 註： 「文件」可以列出多個文件，若包含多個文件之間存在不一致，請將所有不一致項目列於此表格中。
## 遺漏項目
| 編號 | 文件 | 遺漏描述 | 應補充至 |
|------|------|----------|----------|
## 結論
- 不一致項目：N 項
- 遺漏項目：N 項
- 建議：[通過 / 需修正後重新審查]
完成條件
空專案初始化（Bootstrap）
當使用者呼叫此 skill 時，必須先偵測專案是否為空，依下列層次判定並引導：
偵測層次
| 層次 | 偵測指令 | 缺什麼 |
|---|
| L1 | test -d .git | 本地 git 倉庫 |
| L2 | git remote -v 輸出為空 | GitHub / GitLab 遠端 |
| L3 | test -f README.md && test -f .gitignore | 專案基礎檔 |
| L3.5 | test -f CLAUDE.md（且檔案非空） | Claude Code 專案指引 |
| L4 | test -d docs | /docs 目錄 |
| L5 | test -f docs/00-Docs_Index.md | Docs Index 與規格文件 |
觸發條件
僅在 L4 與 L5 皆缺失（即 /docs 目錄不存在或完全沒有規格文件）時觸發初始化面板。若使用者已有 /docs 內容，直接進入「行為指引」既有流程，不打擾。
初始化面板
偵測到空專案時，輸出下列面板並等待使用者選擇，禁止自動執行：
🌱 偵測到這是新專案，Vibe-SDLC 可協助初始化以下項目：
──────────────────────────────────────────────────
{✅/❌} L1 git init（本地倉庫）
{✅/❌} L2 GitHub remote 設定
{✅/❌} L3 .gitignore / README.md
{✅/❌} L3.5 CLAUDE.md（專案指引）
{✅/❌} L4 /docs 目錄
{✅/❌} L5 /docs/00-Docs_Index.md 骨架
{✅/❌} A-Main 快照分支 dev/main-agent
請選擇：
1️⃣ 全部執行（推薦，新專案一鍵 bootstrap）
2️⃣ 只建立 /docs 骨架 + Docs Index（已有 git 時）
3️⃣ 我想逐項確認
4️⃣ 跳過初始化，直接進入規格撰寫流程
請選擇（1/2/3/4）：
{✅/❌} 依實際偵測結果填入（已存在為 ✅，缺失為 ❌）。
各選項行為
選項 1 — 全部執行：依下列順序執行，每一步執行前以一句話備註用途，執行失敗則停下報告：
- L1 git init：若
.git/ 不存在，執行 git init 並建立初始 commit 佔位（空 commit 或含 README）
- L3 基礎檔：若缺
.gitignore 或 README.md，建立最小骨架：
.gitignore：至少包含 .env, .env.*, node_modules/, dist/, build/, *.log, .DS_Store, docs/status/（若採用 STATUS 模式 B/C）README.md：含專案名稱 + 一句話描述 + Vibe-SDLC 連結
- L3.5 CLAUDE.md：呼叫下方「CLAUDE.md 初始化」流程
- L4/L5 docs 骨架：建立
/docs/ 目錄，並從 examples/docs/00-Docs_Index.md 複製一份作為 /docs/00-Docs_Index.md，將「專案名稱」與文件清單改為占位符待使用者填寫
- 快照分支：
git checkout -b dev/main-agent（A-Main 快照分支，從 main 分出；若尚無 commit，先完成 step 1 的初始 commit）。建立後不立即在其上做任何 commit；後續由 /vibe-sdlc-status 管理
- L2 GitHub remote：呼叫下方「GitHub Remote 建立流程」，讓使用者選擇由 AI 代為建立或自行手動
完成後輸出下一步建議：「初始化完成，接下來會協助你撰寫 PRD，請先告訴我專案要解決什麼問題。」
選項 2 — 只建 docs 骨架：只執行上方步驟 3、4（CLAUDE.md + docs 骨架），跳過 git 與基礎檔相關動作。適合已有 git repo 但剛從別的 SDLC 切換過來的專案。
選項 3 — 逐項確認：依序對每個 ❌ 項目詢問「是否執行？(y/N)」，使用者答 y 才執行該項。
選項 4 — 跳過：不做任何初始化動作，直接進入既有的「行為指引」流程（由使用者自行決定從哪份規格開始）。
CLAUDE.md 初始化流程
本 skill 提供骨架模板：templates/CLAUDE.md.template（含 {PROJECT_NAME}、{PROJECT_DESCRIPTION}、{BACKEND_STACK} 等占位符）。
情境 A：CLAUDE.md 不存在
- 互動詢問三個最小必要資訊（其餘占位符保留，由使用者後續自行補）：
- 「這個專案叫什麼名字？」→ 填入
{PROJECT_NAME}
- 「一句話描述專案做什麼？」→ 填入
{PROJECT_DESCRIPTION}
- （技術棧、STATUS 模式為選填，若使用者當下想好就填，否則保留占位符）
- 從
templates/CLAUDE.md.template 讀取內容，置換占位符
- 寫入
<project_root>/CLAUDE.md
- 提示使用者「技術棧與 STATUS 版控策略的占位符請後續補上」
情境 B：CLAUDE.md 已存在但缺少 Vibe-SDLC 區塊
偵測方式：grep CLAUDE.md 是否包含 /vibe-sdlc 字串。若不包含：
- 提示：「偵測到 CLAUDE.md 未引用 Vibe-SDLC 流程，是否要 append 相關區塊？(y/N)」
- 使用者同意後，從
templates/CLAUDE.md.template 擷取「## Vibe-SDLC 流程」整段（包含核心原則），以 append 方式寫入既有 CLAUDE.md 末尾
- 不覆蓋既有內容，只附加
情境 C：CLAUDE.md 已存在且已含 Vibe-SDLC 區塊
跳過，不動它。
GitHub Remote 建立流程
前置檢查：先執行 git remote -v，若已有 origin 指向有效遠端（非占位），則直接跳過整段流程。
若本地 git 有 commit 但無 remote，輸出下列選擇面板並等待使用者選擇：
🔗 GitHub Remote 尚未設定
──────────────────────────
選擇建立方式：
A 由 AI 代為建立（執行 gh repo create，需要 gh 已登入）
B 我要自己手動建立
C 先跳過，稍後再設定
請選擇（A/B/C）：
選項 A — AI 代為建立：
- 先檢查 gh 是否可用：
gh auth status 若失敗，提示使用者先執行 gh auth login，然後改選 B 或 C- 若 gh 未安裝，直接改選 B
- 互動確認四個資訊：
- Repo 名稱（預設為
basename $(pwd)，可覆寫）
- Owner：帳號 or organization（預設為
gh api user --jq .login 取得的當前使用者，可覆寫）
- 可見性：
private / public / internal（預設 private）
- 是否立即推送 main 與 dev/main-agent（預設 y）
- 顯示即將執行的指令並請使用者最終確認，例如：
即將執行：
gh repo create <owner>/<name> --private --source=. --remote=origin --push
git push -u origin dev/main-agent
執行？(y/N)：
- 使用者答 y 後執行；答 N 則改走選項 B（輸出手動指令）
- 執行失敗（名稱衝突、權限不足等）時停下報告錯誤，並提供修正建議（改名稱 / 換 owner / 檢查 gh 權限）
選項 B — 使用者手動建立：
輸出完整指令清單供使用者複製：
請依序執行以下指令（可依需求調整參數）：
# 1. 建立 GitHub repo（擇一）
# 方式 A：使用 gh CLI
gh repo create <name> --private --source=. --remote=origin --push
# 方式 B：在 GitHub 網頁建立空 repo 後手動加 remote
git remote add origin git@github.com:<owner>/<name>.git
git branch -M main
git push -u origin main
# 2. 將常駐分支推上遠端
git push -u origin dev/main-agent
設定完成後告訴我一聲，我會繼續後續流程。
輸出後暫停流程等待使用者回報，不進入後續 PRD 撰寫。
選項 C — 先跳過：
記錄「稍後再設定 remote」，繼續後續流程（進入 PRD 撰寫）。提醒使用者：「Phase 2 建立 Issues 時必須要有 remote，請在那之前完成 remote 設定。」
行為指引
初始化完成後（或偵測到非空專案時），依下列流程協助使用者：
- 先檢查
/docs 目錄是否存在，以及已有哪些規格文件
- 若
/docs/00-Docs_Index.md 不存在：建議先建立文件入口，作為後續文件的導航索引
- 若規格文件尚未建立：詢問開發者想從哪份文件開始，協助撰寫
- 若規格文件已存在：詢問開發者是要修改規格還是進行交叉比對審查
- 修改既有規格文件時，必須同步更新該文件的版本號、最後更新日期與版本修訂說明表格（詳見「版本修訂記錄格式規範」）
- 執行審查時，逐一讀取所有規格文件，系統性比對後產出報告
- 檢查規格文件間的交互參考是否完整：
- Docs Index 是否已登錄所有已建立的文件
- PRD 各功能需求是否標注對應的 UI/UX 設計章節參考（如有 UI/UX 設計文件）
- SRD 與 SDD 是否職責分離（SRD 僅含需求，SDD 含設計）
- SDD 的架構設計是否與 API Spec 的端點定義一致
- UI/UX 設計文件是否反向參考 PRD、SRD、API Spec
- UI/UX 設計文件是否遵循
references/UI_UX_Writing_Guidelines.md 的 9 條準則（逐條列出符合/違反，違反項必須寫入審查報告）：
/docs/ui/*.html wireframe 是否包含 <meta name="fidelity"> 與 <meta name="spec-ref"> 標籤- UI/UX 規格書與 HTML wireframe 是否保持一致（Design Tokens、欄位、狀態描述無衝突）
- 若為遊戲類專案，提醒開發者是否需要建立 GDD（
01-4-GDD.md）
- 審查完成且無遺漏後，提示開發者可進入 Phase 2（
/vibe-sdlc-issues）
