# 📕 AI VIBE Coding Guideline

## 1. 定義與理念
**VIBE = Vision → Interface → Behavior → Evidence**  
AI Agent 必須依據此四階段原則執行開發任務。

### 1.1 階段說明
| 階段 | 定義 | 成果 |
|------|------|------|
| Vision | 理解產品願景與使用者需求 | 任務分解圖與開發路線圖 |
| Interface | 理解系統與介面設計 | API / UI 契約圖與資料流模型 |
| Behavior | 實作對應行為 | 程式碼與行為邏輯 |
| Evidence | 驗證成果 | 測試報告與效能結果 |

---

## 2. AI Agent 開發流程
1. **讀取 GuideLine（本文件）**：確定規範。
2. **載入 PRD**：掌握產品願景與 KPI。  
3. **讀取 SDD**：取得架構、模組定義、API 契約。  
4. **分析 TDD**：對應測試案例，建立驗證點。  
5. **生成代碼**：依據規格實作並自動化測試。  
6. **提交報告**：附測試覆蓋率、效能與風險分析。

---

## 3. 開發準則
1. **規格驅動**：程式碼與文件一一對應，無明確條款不得生成。  
2. **測試先行**：先生成測試案例再撰寫程式。  
3. **可回溯性**：每次變更需附帶來源（PRD 條款、SDD 模組、TDD 案例）。  
4. **安全預設**：無網路傳輸，僅本地資料處理。  
5. **自動驗證**：所有程式碼須通過 TDD 測試才能提交。

---

## 4. 實作規範
| 項目 | 標準 |
|------|------|
| 前端 | React + TypeScript + Tailwind，支援暗色模式 |
| 後端 | FastAPI + Pydantic，嚴格型別與錯誤碼機制 |
| 測試 | pytest + Playwright，自動化覆蓋率 ≥ 80% |
| 文件 | 代碼註解、Rationale、版本註記必填 |

---

## 5. 自動化檢查
- **Lint 檢查**：ESLint + flake8。  
- **型別驗證**：mypy（後端）、tsc（前端）。  
- **安全掃描**：Bandit + npm audit。  
- **文件同步**：若檢測到 API/Schema 變更，自動觸發 SDD 更新 PR。

---

## 6. 驗證與審核
- **測試覆蓋率報告**：自動產出於 `/docs/validation/coverage`。  
- **效能報告**：顯示 100、300、1000 筆事件渲染時間。  
- **品質稽核**：PR 須通過以下檢查：
  - 測試通過率 ≥ 100%。
  - 效能落在 KPI 範圍內。
  - 無安全漏洞或規格違反。

---

## 7. 例外與升級
- 若 AI 發現規格不足，必須先生成 **Spec PR** 更新文件。  
- 每次破壞性修改需升版 `x.y.z`，並附 Migration 指南。  
- 所有生成記錄與報告需自動歸檔於 `/docs/audit`。

---

## 8. 變更追溯與文件變更策略（**強制規範**）
> 目標：強制 AI 在開發或修正時具備完整追溯性；並**優先更新現有文檔**而非新建，以維持單一事實來源（SSOT）。

### 8.1 文件清單與索引（Doc Registry）
- 維護 `/docs/REGISTRY.md`（唯一權威清單），包含：
  - `DocID`（如 `PRD-001`、`SDD-API-002`、`TDD-E2E-003`）
  - `Title`、`Owner`、`Scope`、`LastUpdated`、`Link`
  - `SSOT` 標記（是否為單一事實來源）
- AI 修改或查閱前**必讀 REGISTRY**，以判斷應修改的目標文檔。

### 8.2 新增前必查（Pre-Create Check）
AI 在**新建任何文檔**前，必須完成以下檢查並寫入變更報告：
1. 以關鍵詞（需求/模組/API）在 REGISTRY 搜索，列出**Top 5** 既有候選文檔。  
2. 為每一候選估算**適配度分數**（相符段落比例/關鍵詞重合度/更新日期權重）。  
3. 若存在 **適配度 ≥ 0.6** 的文檔，**禁止新建**，改為**在該文檔中更新**：
   - 追加段落或開新章節；
   - 若為過時內容，進行標註並保留舊版於附錄或變更記錄。  
4. 僅當**所有候選皆 < 0.6** 時方可新建，並**同步更新 REGISTRY**。

### 8.3 版本與變更記錄（Versioning & Changelog）
- 每份文檔必須維護 YAML Frontmatter 或標準區塊：
```
Version: x.y.z
LastUpdated: YYYY-MM-DD
DocID: <唯一 ID>
SSOT: true|false
```
- 在文檔尾端新增 `## Changelog`：
  - `YYYY-MM-DD | Agent | Reason | Related DocID/PR | Impact`  
- **禁止**刪除歷史內容；若需淘汰，改以 `Deprecated` 區塊標註與遷移連結。

### 8.4 變更單（Change Ticket）模板（AI 產生並附於 PR）
- **Title**：`[Doc|Code] Change – <Module/Feature>`
- **Reason**：來源需求（PRD 條款/Issue/Meeting Minutes）
- **Scope**：影響模組與文件 DocID 列表
- **Decision**：更新現有文檔或新建的依據（含適配度證據）
- **Tests**：對應 TDD Case 列表
- **Risk & Rollback**：風險與回退策略

### 8.5 單一事實來源（SSOT）與鏡射
- `PRD.md`、`SDD.md`、`TDD.md`、`AI_GUIDELINE.md` 為 SSOT；
- 任何導讀或摘要文檔標註 `SSOT: false` 並**必須**連回原 SSOT；
- 當 API/Schema 更新時：
  1) 先更新 `SDD`（SSOT）；
  2) 觸發腳本自動更新次要文檔與程式碼註解（鏡射）。

### 8.6 檢核 Gate（CI 強制）
在 CI 中新增 **Doc-Change Gate**：
- 若 PR 變更程式碼但未引用相關 `DocID` → **阻擋合併**；
- 若新建文檔但 `Pre-Create Check` 證據不足 → **阻擋合併**；
- 檢查 `REGISTRY.md` 是否同步更新；
- 檢查 `Changelog` 是否新增；
- 檢查 `Version` 是否依規則遞增（fix: patch、feat: minor、break: major）。

### 8.7 追溯鏈（Traceability Chain）
- **需求 → 設計 → 程式碼 → 測試 → 交付** 全鏈路需以 `DocID` 與 `Commit/PR` 互相鏈結：
  - 需求（PRD 條款編號）
  - 設計（SDD 模組節點）
  - 程式碼（目錄/檔案與函式註解）
  - 測試（TDD Case ID）
  - 交付（產物、效能與覆蓋率報告）

### 8.8 最佳實務
- **改寫優先**：小幅調整以段落更新，避免碎片化文件。  
- **章節化**：若更新內容較大，優先在現有文檔開新章，保留連貫脈絡。  
- **變更影響矩陣**：變更單中列出受影響的模組、API、測試與文件 DocID。  
- **審核清單**：Reviewer 需檢查 `Pre-Create Check`、`SSOT` 鏈接與 `Changelog` 完整性。