Timeline_Generator/GUIDLINE.md

📕 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 完整性。