2d37d23bcf
- 新增 _calculate_lane_conflicts_v2() 分開返回標籤重疊和線穿框分數 - 修改泳道選擇算法，優先選擇無標籤重疊的泳道 - 兩階段搜尋：優先側別無可用泳道則嘗試另一側 - 增強日誌輸出，顯示標籤範圍和詳細衝突分數 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
139 lines
5.9 KiB
Markdown
139 lines
5.9 KiB
Markdown
# 📕 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` 完整性。
|
||
|