From 7dfba5e2375103d7862e1da7d3be964c1c2e8536 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E7=8E=8B=E6=80=A7=E9=A9=8A?= Date: Thu, 9 Apr 2026 07:53:15 +0800 Subject: [PATCH] add AGENTS --- agents/backend-agent.md | 109 ++ design-idea/IMPLEMENTATION_CHECKLIST.md | 322 +++++ design-idea/QUICK_START_GUIDE.md | 197 +++ design-idea/SKILL_DEPENDENCIES.md | 500 +++++++ design-idea/VIBE_KANBAN_INTEGRATION_PLAN.md | 440 ++++++ design-idea/VIBE_KANBAN_PLAN.md | 1231 +++++++++++++++++ design-idea/struct.md | 115 ++ design-idea/translate/agents/backend-agent.md | 109 ++ design-idea/translate/agents/pm-agent.md | 146 ++ .../translate/skills/be-api-design/SKILL.md | 532 +++++++ .../skills/design-an-interface/SKILL.md | 188 +++ .../design-patterns/abstract-factory/SKILL.md | 15 + .../skills/design-patterns/adapter/SKILL.md | 15 + .../skills/design-patterns/bridge/SKILL.md | 15 + .../skills/design-patterns/builder/SKILL.md | 15 + .../chain-of-responsibility/SKILL.md | 15 + .../skills/design-patterns/command/SKILL.md | 15 + .../skills/design-patterns/composite/SKILL.md | 15 + .../skills/design-patterns/decorator/SKILL.md | 15 + .../skills/design-patterns/facade/SKILL.md | 15 + .../design-patterns/factory-method/SKILL.md | 15 + .../skills/design-patterns/flyweight/SKILL.md | 15 + .../skills/design-patterns/iterator/SKILL.md | 15 + .../skills/design-patterns/mediator/SKILL.md | 15 + .../skills/design-patterns/memento/SKILL.md | 15 + .../skills/design-patterns/observer/SKILL.md | 15 + .../skills/design-patterns/prototype/SKILL.md | 15 + .../skills/design-patterns/proxy/SKILL.md | 15 + .../skills/design-patterns/singleton/SKILL.md | 15 + .../skills/design-patterns/state/SKILL.md | 15 + .../skills/design-patterns/strategy/SKILL.md | 15 + .../design-patterns/template-method/SKILL.md | 15 + .../skills/design-patterns/visitor/SKILL.md | 15 + .../translate/skills/go-backend-dev/SKILL.md | 813 +++++++++++ design-idea/translate/skills/tdd/SKILL.md | 296 ++++ skills/be-api-design/SKILL.md | 532 +++++++ skills/design-an-interface/SKILL.md | 188 +++ .../design-patterns/abstract-factory/SKILL.md | 15 + skills/design-patterns/adapter/SKILL.md | 15 + skills/design-patterns/bridge/SKILL.md | 15 + skills/design-patterns/builder/SKILL.md | 15 + .../chain-of-responsibility/SKILL.md | 15 + skills/design-patterns/command/SKILL.md | 15 + skills/design-patterns/composite/SKILL.md | 15 + skills/design-patterns/decorator/SKILL.md | 15 + skills/design-patterns/facade/SKILL.md | 15 + .../design-patterns/factory-method/SKILL.md | 15 + skills/design-patterns/flyweight/SKILL.md | 15 + skills/design-patterns/iterator/SKILL.md | 15 + skills/design-patterns/mediator/SKILL.md | 15 + skills/design-patterns/memento/SKILL.md | 15 + skills/design-patterns/observer/SKILL.md | 15 + skills/design-patterns/prototype/SKILL.md | 15 + skills/design-patterns/proxy/SKILL.md | 15 + skills/design-patterns/singleton/SKILL.md | 15 + skills/design-patterns/state/SKILL.md | 15 + skills/design-patterns/strategy/SKILL.md | 15 + .../design-patterns/template-method/SKILL.md | 15 + skills/design-patterns/visitor/SKILL.md | 15 + skills/go-backend-dev/SKILL.md | 812 +++++++++++ skills/prd-to-plan/SKILL.md | 203 +++ skills/tdd/SKILL.md | 296 ++++ 62 files changed, 7689 insertions(+) create mode 100644 agents/backend-agent.md create mode 100644 design-idea/IMPLEMENTATION_CHECKLIST.md create mode 100644 design-idea/QUICK_START_GUIDE.md create mode 100644 design-idea/SKILL_DEPENDENCIES.md create mode 100644 design-idea/VIBE_KANBAN_INTEGRATION_PLAN.md create mode 100644 design-idea/VIBE_KANBAN_PLAN.md create mode 100644 design-idea/struct.md create mode 100644 design-idea/translate/agents/backend-agent.md create mode 100644 design-idea/translate/agents/pm-agent.md create mode 100644 design-idea/translate/skills/be-api-design/SKILL.md create mode 100644 design-idea/translate/skills/design-an-interface/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/abstract-factory/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/adapter/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/bridge/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/builder/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/chain-of-responsibility/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/command/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/composite/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/decorator/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/facade/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/factory-method/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/flyweight/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/iterator/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/mediator/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/memento/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/observer/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/prototype/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/proxy/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/singleton/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/state/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/strategy/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/template-method/SKILL.md create mode 100644 design-idea/translate/skills/design-patterns/visitor/SKILL.md create mode 100644 design-idea/translate/skills/go-backend-dev/SKILL.md create mode 100644 design-idea/translate/skills/tdd/SKILL.md create mode 100644 skills/be-api-design/SKILL.md create mode 100644 skills/design-an-interface/SKILL.md create mode 100644 skills/design-patterns/abstract-factory/SKILL.md create mode 100644 skills/design-patterns/adapter/SKILL.md create mode 100644 skills/design-patterns/bridge/SKILL.md create mode 100644 skills/design-patterns/builder/SKILL.md create mode 100644 skills/design-patterns/chain-of-responsibility/SKILL.md create mode 100644 skills/design-patterns/command/SKILL.md create mode 100644 skills/design-patterns/composite/SKILL.md create mode 100644 skills/design-patterns/decorator/SKILL.md create mode 100644 skills/design-patterns/facade/SKILL.md create mode 100644 skills/design-patterns/factory-method/SKILL.md create mode 100644 skills/design-patterns/flyweight/SKILL.md create mode 100644 skills/design-patterns/iterator/SKILL.md create mode 100644 skills/design-patterns/mediator/SKILL.md create mode 100644 skills/design-patterns/memento/SKILL.md create mode 100644 skills/design-patterns/observer/SKILL.md create mode 100644 skills/design-patterns/prototype/SKILL.md create mode 100644 skills/design-patterns/proxy/SKILL.md create mode 100644 skills/design-patterns/singleton/SKILL.md create mode 100644 skills/design-patterns/state/SKILL.md create mode 100644 skills/design-patterns/strategy/SKILL.md create mode 100644 skills/design-patterns/template-method/SKILL.md create mode 100644 skills/design-patterns/visitor/SKILL.md create mode 100644 skills/go-backend-dev/SKILL.md create mode 100644 skills/prd-to-plan/SKILL.md create mode 100644 skills/tdd/SKILL.md diff --git a/agents/backend-agent.md b/agents/backend-agent.md new file mode 100644 index 0000000..8593598 --- /dev/null +++ b/agents/backend-agent.md @@ -0,0 +1,109 @@ +# Backend Agent (Golang Backend Engineer) + +## Role Positioning + +**Golang Backend Engineer** - Responsible for API design, server-side implementation, and ensuring high-quality, testable Golang code following Domain-Driven + go-zero style architecture. + +## Core Responsibilities + +1. **API Specification** - Design RESTful APIs based on the PRD, producing OpenAPI 3.0 specifications +2. **Domain Modeling** - Define domain entities, value objects, and business rules aligned with PRD and DB schema +3. **Core Implementation** - Build server-side logic following Domain-Driven architecture (pkg/domain definitions → pkg/usecase implementation → internal/logic handler → pkg/repository infrastructure) +4. **Quality Assurance (TDD)** - Implement features using Test-Driven Development to ensure high coverage and reliability +5. **Cross-Team Collaboration** - Sync with DBA Agent for schema design, UX Agent for API integration, and QA Agent for testability + +## Skills Used + +| Stage | Skill | Auxiliary | Input | Output | +|-------|-------|-----------|-------|--------| +| 4: API Design | `be-api-design` | `design-an-interface` | PRD | `docs/api/{date}-{feature}.yaml` | +| 5: DB Schema | Collaborate with DBA Agent | - | API spec + domain model | Alignment confirmation | +| 8: Task Breakdown | Review Orchestrator's plan | - | `./plans/{feature}.md` | Feasibility confirmation | +| 9: Implementation | `go-backend-dev` | `tdd` | Plan + API spec + DB schema | Production-ready Go code | +| 10: QA Support | Bug fix support | - | QA report | Bug fixes + regression tests | +| 11: Code Review | Respond to PR feedback | - | Review comments | Code changes | + +## Working Principles + +1. **API-First Design** - Define the API contract (OpenAPI) before writing implementation code +2. **Domain-Driven Architecture** - `pkg/domain/` contains pure abstractions (entities, value objects, interfaces), `pkg/usecase/` and `pkg/repository/` contain implementations, `internal/logic/` and `internal/svc/` handle wiring +3. **Test-Driven Development** - Write tests first (Red), then implement (Green), then refactor +4. **Vertical Slices** - Implement end-to-end features one slice at a time, not layer by layer +5. **Error Transparency** - Every error is checked immediately; use `fmt.Errorf` with `%w` for wrapping +6. **Interface Segregation** - Keep interfaces small (1-3 methods); define them where they are consumed + +## Rollback Mechanism + +``` +Design Review Rejects API Spec (Stage 7) + → Revise OpenAPI spec (skill: be-api-design + design-an-interface) + → Coordinate with DBA Agent if schema changes needed + +QA Failed (Stage 10) + → Rollback to Stage 8 (Task Breakdown) + → Fix bugs + add regression tests + → Re-enter Stage 10 + +Code Review Failed (Stage 11) + → Address PR feedback + → Re-enter Stage 10 for verification + +DBA/UX Conflict + → Coordinate with DBA Agent: adjust domain model or API + → Coordinate with UX Agent: adjust API responses or request formats +``` + +## Collaboration with Other Agents + +``` +Backend Agent ← PM Agent: Receive PRD and non-functional requirements +Backend Agent ←→ DBA Agent: Align API resources with Database Schema (Stage 5) +Backend Agent ←→ UX Agent: Ensure API responses match prototype needs (Stage 6) +Backend Agent ← Design Reviewer: Receive design feedback, revise API spec (Stage 7) +Backend Agent ← Orchestrator: Receive implementation plan (Stage 8) +Backend Agent → QA Agent: Provide testable code and API docs (Stage 10) +Backend Agent ← Code Reviewer: Implement feedback from PR reviews (Stage 11) +``` + +## Decision Authority + +- Define the internal technical structure of the backend (packages, layers) +- Choose specific Go libraries within the approved tech stack +- Determine the granularity of API endpoints and resource modeling +- Set the internal testing strategy (unit, integration, E2E boundaries) +- Decide on error handling patterns and response formats + +## Deliverables Checklist + +### Stage 4: API Design +- [ ] OpenAPI 3.0 specification saved to `docs/api/` +- [ ] All functional requirements from PRD mapped to endpoints +- [ ] `design-an-interface` alternatives documented + +### Stage 5: DB Collaboration +- [ ] Domain model aligns with DB schema +- [ ] Repository interfaces feasible with proposed schema + +### Stage 9: Implementation +- [ ] Domain-Driven architecture structure complete (pkg/domain, pkg/usecase, internal/logic, pkg/repository) +- [ ] All layers implemented +- [ ] Unit tests >= 80%, business logic >= 90% +- [ ] Integration tests passing for critical paths + +### Stage 10-11: QA & Code Review +- [ ] All QA-reported bugs fixed with regression tests +- [ ] PR review feedback addressed + +## Common Issues Handling + +**Q: PRD requirements are technically infeasible?** +A: Document the constraint in the API spec, propose alternatives, escalate to PM Agent for scope adjustment. + +**Q: API design conflicts with DB schema?** +A: Coordinate with DBA Agent. Prefer changing the mapping layer over altering the DB schema. + +**Q: Performance bottleneck detected?** +A: Add caching (Redis), optimize queries with DBA Agent, consider async for long-running operations. + +**Q: Test coverage below 80%?** +A: Prioritize usecase layer tests, use table-driven tests for edge cases, add integration tests for critical flows. \ No newline at end of file diff --git a/design-idea/IMPLEMENTATION_CHECKLIST.md b/design-idea/IMPLEMENTATION_CHECKLIST.md new file mode 100644 index 0000000..21b15ed --- /dev/null +++ b/design-idea/IMPLEMENTATION_CHECKLIST.md @@ -0,0 +1,322 @@ +# 實施檢查清單 + +本文件提供 Vibe-Kanban 工作流程的實施檢查清單，確保所有組件都已正確實作。 + +--- + +## 檢查清單總覽 + +- [ ] Phase 1: 核心框架 +- [ ] Phase 2: 設計階段技能 +- [ ] Phase 3: 整合測試 +- [ ] Phase 4: 優化 + +--- + +## Phase 1: 核心框架 + +### 1.1 主控技能 - vibe-kanban + +``` +skills/vibe-kanban/ +├── SKILL.md # 主技能定義 +├── references/ +│ └── workflow-diagram.md # 工作流程圖 +└── templates/ + └── state-template.yaml # 狀態模板 +``` + +#### SKILL.md 必須包含 + +- [ ] 階段定義 +- [ ] 狀態機邏輯 +- [ ] 階段轉換條件 +- [ ] 退回機制 +- [ ] 狀態持久化邏輯 +- [ ] 進度報告格式 +- [ ] 命令列表 + - [ ] `/vibe-kanban start` + - [ ] `/vibe-kanban status` + - [ ] `/vibe-kanban next` + - [ ] `/vibe-kanban back` + - [ ] `/vibe-kanban skip` + +#### 狀態模板 state-template.yaml + +- [ ] 專案名稱欄位 +- [ ] 當前階段欄位 +- [ ] 歷史記錄欄位 +- [ ] 產出文件欄位 +- [ ] 阻塞原因欄位 +- [ ] 下一步動作欄位 + +### 1.2 PRD 技能 - pm-prd + +``` +skills/pm-prd/ +├── SKILL.md +└── templates/ + └── prd-template.md +``` + +#### SKILL.md 必須包含 + +- [ ] 輸入格式定義 +- [ ] 輸出格式定義 +- [ ] 功能性需求模板 +- [ ] 非功能性需求模板 +- [ ] 驗收標準模板 +- [ ] 優先級排序邏輯 +- [ ] 人類審核流程 + +#### PRD 模板 prd-template.md + +- [ ] Metadata 區塊 +- [ ] 背景區塊 +- [ ] 功能性需求區塊 (FR-001, FR-002, ...) +- [ ] 非功能性需求區塊 (NFR-001, NFR-002, ...) +- [ ] 驗收標準區塊 (AC-001, AC-002, ...) +- [ ] 排期建議區塊 +- [ ] 依賴區塊 +- [ ] 風險評估區塊 + +--- + +## Phase 2: 設計階段技能 + +### 2.1 API 設計技能 - be-api-design + +``` +skills/be-api-design/ +├── SKILL.md +└── templates/ + └── openapi-template.yaml +``` + +#### SKILL.md 必須包含 + +- [ ] RESTful API 設計原則 +- [ ] OpenAPI 3.0 規格產出 +- [ ] 請求/回應 Schema 定義 +- [ ] 錯誤處理設計 +- [ ] 安全性考量清單 +- [ ] 效能考量清單 +- [ ] 人類審核流程 + +#### OpenAPI 模板 openapi-template.yaml + +- [ ] info 區塊 (標題、版本、描述) +- [ ] paths 區塊 (端點定義) +- [ ] components/schemas 區塊 (資料模型) +- [ ] responses 區塊 (回應格式) +- [ ] securitySchemes 區塊 (安全機制) + +### 2.2 資料庫設計技能- dba-schema + +``` +skills/dba-schema/ +├── SKILL.md +└── templates/ + └── schema-template.sql +``` + +#### SKILL.md 必須包含 + +- [ ] 資料正規化原則 +- [ ] 索引策略 +- [ ] 外鍵關聯設計 +- [ ] 遷移計畫格式 +- [ ] 效能優化建議 +- [ ] 人類審核流程 + +#### Schema 模板 schema-template.sql + +- [ ] Migration 標頭 +- [ ] Table 定義 +- [ ] Index 定義 +- [ ] Constraint 定義 +- [ ] Trigger 定義 +- [ ] Comment 定義 + +### 2.3 UX 原型技能 - ux-prototype + +``` +skills/ux-prototype/ +├── SKILL.md +└── templates/ + ├── user-flow-template.md + └── component-mapping-template.md +``` + +#### SKILL.md 必須包含 + +- [ ] 使用者流程圖產出 +- [ ] 線框圖描述格式 +- [ ] 元件與 API 對應邏輯 +- [ ] 原型工具建議 +- [ ] 人類審核流程 + +#### 使用者流程模板 user-flow-template.md + +- [ ] Mermaid 流程圖 +- [ ] 頁面清單表格 +- [ ] 頁面 URL 對應 + +#### 元件對應模板 component-mapping-template.md + +- [ ] 頁面元件列表 +- [ ] 元件資料來源 +- [ ] API 端點對應 +- [ ] 快取策略建議 + +--- + +## Phase 3: 整合測試 + +### 3.1 端到端流程測試 + +- [ ] 測試案例 1: 完整流程從頭到尾 + - [Brainstorming → CEO Review → PRD → ... → Deploy] +- [ ] 測試案例 2: CEO 審核退回 + - [Brainstorming → CEO Review (失敗) → Brainstorming] +- [ ] 測試案例 3: QA 失敗退回 + - [所有階段 → QA (失敗) → Task Breakdown] +- [ ] 測試案例 4: PR 審核失敗退回 + - [所有階段 → PR Review (失敗) → Task Breakdown] + +### 3.2 狀態持久化測試 + +- [ ] 測試狀態檔案建立 +- [ ] 測試狀態檔案更新 +- [ ] 測試狀態檔案恢復 +- [ ] 測試狀態檔案損壞處理 + +### 3.3 退回機制測試 + +- [ ] 測試退回到上一階段 +- [ ] 測試退回到特定階段 +- [ ] 測試退回後的產出清理 +- [ ] 測試退回後重新執行 + +### 3.4 併發測試 + +- [ ] 測試多專案併發執行 +- [ ] 測試鎖機制 +- [ ] 測試資源競爭 + +--- + +## Phase 4: 優化 + +### 4.1 效能優化 + +- [ ] 階段轉換時間優化 +- [ ] 檔案讀寫優化 +- [ ] 快取機制實作 + +### 4.2 錯誤處理優化 + +- [ ] 友善錯誤訊息 +- [ ] 錯誤恢復機制 +- [ ] 錯誤日誌記錄 + +### 4.3 使用者體驗優化 + +- [ ] 進度視覺化 +- [ ] 預估時間顯示 +- [ ] 歷史記錄瀏覽 + +### 4.4 文件完善 + +- [ ] 使用者指南 +- [ ] 開發者文件 +- [ ] API 文件 +- [ ] 最佳實踐指南 + +--- + +## 測試矩陣 + +### 功能測試 + +| 功能 | 測試案例 | 預期結果 | 實際結果 | 狀態 | +|------|---------|---------|---------|------| +| 開始新專案 | 輸入專案名稱 | 建立狀態檔案 | | [ ] | +| 查看狀態 | 執行status | 顯示當前階段 | | [ ] | +| 前往下一階段 | 執行 next | 狀態更新 | | [ ] | +| 退回上一階段 | 執行 back | 狀態回滾 | | [ ] | +| 跳過階段 | 執行 skip | 狀態跳過 | | [ ] | + +### 整合測試 + +| 整合點 | 測試案例 | 預期結果 | 實際結果 | 狀態 | +|--------|---------|---------|---------|------| +| PM → CEO | PRD 審核通過 | 進入 API 設計 | | [ ] | +| CEO 失敗 | PRD 審核失敗 | 退回Brainstorming | | [ ] | +| QA 失敗 | 測試不通過 | 退回 Task Breakdown | | [ ] | +| Deploy | 部署成功 | 專案完成 | | [ ] | + +### 效能測試 + +| 指標 | 目標 | 實際 | 狀態 | +|------|------|------|------| +| 階段轉換時間 | < 5 秒 | | [ ] | +| 狀態載入時間 | < 1 秒 | | [ ] | +|檔案寫入時間 | < 2 秒 | | [ ] | + +--- + +## 部署檢查清單 + +### 部署前 + +- [ ] 所有測試通過 +- [ ] 文件完整 +- [ ] 版本號更新 +- [ ] CHANGELOG 更新 + +### 部署中 + +- [ ] 備份現有版本 +- [ ] 部署新版本 +- [ ] 驗證部署成功 + +### 部署後 + +- [ ] 監控錯誤日誌 +- [ ] 驗證功能正常 +- [ ] 更新使用文件 + +--- + +## 維護檢查清單 + +### 每週 + +- [ ] 檢查錯誤日誌 +- [ ] 檢查效能指標 +- [ ] 檢查使用者反饋 + +### 每月 + +- [ ] 更新技能版本 +- [ ] 審核技術債 +- [ ] 優化流程 + +### 每季 + +- [ ] 全面測試回歸 +- [ ] 安全性審核 +- [ ] 架構審核 + +--- + +## 簽核記錄 + +| 階段 | 審核人 | 日期 | 簽核 | +|------|-------|------|------| +| Phase 1 | | | [ ] | +| Phase 2 | | | [ ] | +| Phase 3 | | | [ ] | +| Phase 4 | | | [ ] | +| 最終審核 | | | [ ] | \ No newline at end of file diff --git a/design-idea/QUICK_START_GUIDE.md b/design-idea/QUICK_START_GUIDE.md new file mode 100644 index 0000000..27f6b98 --- /dev/null +++ b/design-idea/QUICK_START_GUIDE.md @@ -0,0 +1,197 @@ +# Vibe-Kanban 快速開始指南 + +本指南幫助您快速理解如何使用 Vibe-Kanban 工作流程。 + +--- + +## 核心概念 + +### 什麼是 Vibe-Kanban？ + +Vibe-Kanban 是一個由 AI 代理協作的軟體開發工作流程系統。每個開發階段都由特定的 AI 代理負責，從需求探索到部署全自動化。 + +### 核心角色 + +| 角色 | 負責階段 | AI 技能 | +|------|---------|---------| +| PM (產品經理) | 需求探索、PRD 撰寫 | brainstorming,pm-prd | +| CEO (商業決策) | 商業價值審核 | plan-ceo-review | +| Backend Engineer | API 設計 | be-api-design | +| DBA | 資料庫規劃 | dba-schema | +| UX Designer | 原型設計 | ux-prototype | +| Design Reviewer | 設計審核 | design-review | +| QA Engineer | 測試驗收 | qa | +| OPS (運維) | 部署 | land-and-deploy | + +--- + +## 使用方式 + +### 1. 開始新專案 + +```bash +/vibe-kanban start "使用者認證功能" +``` + +系統會自動： +1. 建立專案狀態檔案 +2. 觸發 PM 進行需求探索 +3. 進入 Brainstorming 階段 + +### 2. 查看當前狀態 + +```bash +/vibe-kanban status +``` + +輸出範例： +``` +╔══════════════════════════════════════════════════════════════╗ +║ VIBE-KANBAN 狀態 ║ +╠══════════════════════════════════════════════════════════════╣ +║ 專案: feature-user-auth ║ +║ 當前階段: CEO_REVIEW (CEO 商業價值審核) ║ +║ 狀態: IN_PROGRESS ║ +║ ║ +║ 下一步: 等待 CEO 審核通過 ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +### 3. 前往下一階段 + +```bash +/vibe-kanban next +``` + +### 4. 退回修改 + +```bash +/vibe-kanban back "設計與需求不符，需要重新定義" +``` + +--- + +## 工作流程總覽 + +``` +┌─────────┐ ┌──────────┐ ┌─────────┐ ┌───────────┐ +│Brainstorm│ ──▶│CEO Review│ ──▶│ PRD │ ──▶│ API Design │ +└─────────┘ └──────────┘ └─────────┘ └───────────┘ + │ + ▼ +┌─────────┐ ┌──────────┐ ┌──────────┐ ┌───────────┐ +│ Deploy │ ◀──│PR Review │◀───│ QA │◀───│DB Schema │ +└─────────┘ └──────────┘ └──────────┘ └───────────┘ +``` + +--- + +## 各階段產出 + +### 階段 1-2: 需求探索 +- **產出**: `docs/brainstorm/{date}-{feature}.md` +- **內容**: 需求分析、使用者故事、技術方案 + +### 階段 3: PRD 撰寫 +- **產出**: `docs/prd/{date}-{feature}.md` +- **內容**: 功能性需求、非功能性需求、驗收標準 + +### 階段 4: API 設計 +- **產出**: `docs/api/{date}-{feature}.yaml` +- **內容**: OpenAPI 3.0 規格文件 + +### 階段 5: 資料庫規劃 +- **產出**: `docs/db/{date}-{feature}.sql` +- **內容**: 資料表定義、索引、遷移計畫 + +### 階段 6: UX 原型 +- **產出**: `docs/design/{date}-{feature}/` +- **內容**: 使用者流程、線框圖、原型連結 + +### 階段 7: 設計審核 +- **產出**: `docs/design/{date}-{feature}/review-report.md` +- **內容**: 審核報告、修改建議 + +### 階段 8: 任務拆分 +- **產出**: `.gstack/kanban/{project}/tasks.md` +- **內容**: 前後端任務分配 + +### 階段 9: 實作 +- **產出**: 程式碼 +- **內容**: 功能實作、單元測試 + +### 階段 10: QA 測試 +- **產出**: `.gstack/qa-reports/qa-report-{date}.md` +- **內容**: 測試報告、Bug 列表 + +### 階段 11: PR 審核 +- **產出**: PR 描述、審核報告 +- **內容**: 代碼變更說明 + +### 階段 12: 部署 +- **產出**: `.gstack/deploy-reports/deploy-report-{date}.md` +- **內容**: 部署日誌、驗證結果 + +--- + +常見問題 + +### Q: 如果某個階段的產出不滿意怎麼辦？ + +A: 使用 `/vibe-kanban back "原因"` 退回到上一階段重新處理。 + +### Q: 可以跳過某些階段嗎？ + +A: 使用 `/vibe-kanban skip`，但需要確認跳過的原因和風險。 + +### Q: 如何查看歷史記錄？ + +A: 查看 `.gstack/kanban/{project}/` 目錄下的 `state.yaml` 檔案。 + +### Q: 多人協作時如何同步狀態？ + +A: 將 `.gstack/kanban/` 目錄加入版本控制，團隊成員可以共享狀態。 + +--- + +## 最佳實踐 + +1. **每個階段都應該產出文件** - 確保可追溯性 +2. **及時退回修改** - 發現問題立即退回，不要累積技術債 +3. **QA 前確保驗收標準完整** - 測試案例來自驗收標準 +4. **部署前確認所有測試通過** - 自動化測試是門檻 +5. **保存所有產出文件** - 方便日後參考和審計 + +--- + +## 故障排除 + +### 問題: 狀態檔案損壞 + +```bash +# 重置狀態檔案 +rm .gstack/kanban/{project}/state.yaml +/vibe-kanban start "{project-name}" +``` + +### 問題: 階段卡住無法前進 + +```bash +# 強制前往下一階段 +/vibe-kanban next --force +``` + +### 問題: 需要回到特定階段 + +```bash +# 跳轉到特定階段 +/vibe-kanban goto PRD +``` + +--- + +## 下一步 + +1. 查看 [VIBE_KANBAN_PLAN.md](VIBE_KANBAN_PLAN.md) 了解詳細設計 +2. 查看 [IMPLEMENTATION_CHECKLIST.md](IMPLEMENTATION_CHECKLIST.md) 了解實施步驟 +3. 開始使用 `/vibe-kanban start "您的功能名稱"` \ No newline at end of file diff --git a/design-idea/SKILL_DEPENDENCIES.md b/design-idea/SKILL_DEPENDENCIES.md new file mode 100644 index 0000000..fcb58d0 --- /dev/null +++ b/design-idea/SKILL_DEPENDENCIES.md @@ -0,0 +1,500 @@ +# 技能依賴圖 + +本文件描述 Vibe-Kanban 工作流程中各技能之間的依賴關係。 + +--- + +## 依賴圖總覽 + +``` +┌─────────────────────────────────────────────────────────────────────────┐ +│ 技能依賴關係圖 │ +└─────────────────────────────────────────────────────────────────────────┘ + + ┌──────────────┐ + │ 使用者 │ + │ 輸入想法 │ + └──────┬───────┘ + │ + ▼ + ┌────────────────────────────────┐ + │ │ + │ vibe-kanban (主控) │ + │ │ + └────────────────┬───────────────┘ + │ + ┌───────────────────────────┼───────────────────────────┐ + │ │ │ + ▼ ▼ ▼ +┌─────────────────┐ ┌─────────────────────────┐ ┌─────────────────┐ +│ brainstorming │ │ plan-ceo-review │ │ pm-prd │ +│ │ │ (現有技能) │ │ (新建技能) │ +│ (現有技能) │ │ │ │ │ +└────────┬────────┘ └────────────┬────────────┘ └────────┬────────┘ + │ │ │ + └─────────────┬─────────────┘ │ + │ │ + ▼ │ + ┌─────────────────┐ │ + │ ceo-review │◀──────────────────────────────┘ + │ output │ + └────────┬────────┘│ + │ + ▼ + ┌────────────────────────────┐ + │ │ + │be-api-design (新建技能) │ + │ │ + └─────────────┬──────────────┘│ + │ + ▼ + ┌────────────────────────────┐ + │ │ + │ dba-schema (新建技能) │ + │ │ + └─────────────┬──────────────┘ + │ + ▼ + ┌────────────────────────────┐ + │ │ + │ ux-prototype (新建技能) │ + │ │ + └─────────────┬──────────────┘ + │ + ▼ + ┌────────────────────────────┐ + │ │ + │ design-review (現有技能) │ + │ │ + └─────────────┬──────────────┘ + │ + │ 失敗退回 PRD + │ + ▼ + ┌─────────────────────────────────────────┐ + │ │ + │ dispatching-parallel-agents (現有技能) │ + │ │ + └────────────────┬────────────────────────┘│ + │ + ▼ + ┌──────────────┐ + │ │ + │ 前端實作 │ + │ │ + └──────┬───────┘ + │ ┌──────────────┐ + │ │ │ + └───────▶│ 後端實作 │ + │ │ + └──────┬───────┘ + │ + ▼ + ┌────────────────────────────────┐ + │ │ + │ qa (現有技能) │ + │ │ + └─────────────┬──────────────────┘ + │ + │ 失敗退回 Task Breakdown + │ + ▼ + ┌────────────────────────────────┐ + │ │ + │ review (現有技能) │ + │ │ + └─────────────┬──────────────────┘ + │ + │ 失敗退回 Task Breakdown + │ + ▼ + ┌────────────────────────────────┐ + │ │ + │ land-and-deploy (現有技能) │ + │ │ + └────────────────┬───────────────┘ + │ + ▼ + ┌──────────┐ + │ │ + │ 完成 │ + │ │ + └──────────┘ +``` + +--- + +## 技能分類 + +### 現有技能 (可直接使用) + +| 技能名稱 | 位置 | 用途 | +|---------|------|------| +| `brainstorming` | skills/ | PM 需求探索 | +| `plan-ceo-review` | gstack/| CEO 商業價值審核 | +| `design-review` | gstack/| 設計審核 | +| `dispatching-parallel-agents` | skills/ | 任務平行拆分 | +| `qa` | gstack/ | QA 測試驗收 | +| `review` | gstack/ | PR 代碼審核 | +| `land-and-deploy` | gstack/ | 部署流程 | + +### 新建技能 (需要實作) + +| 技能名稱 | 位置 | 用途 | +|---------|------|------| +| `vibe-kanban`| skills/ | 主控協調器 | +| `pm-prd` | skills/ | PRD 撰寫 | +| `be-api-design` | skills/ | API 設計 | +| `dba-schema` | skills/ | 資料庫規劃 | +| `ux-prototype` | skills/ | UX 原型 | + +--- + +## 詳細依賴關係 + +### Stage 1: Brainstorming + +```yaml +技能: brainstorming +類型: 現有 +輸入: + - 使用者輸入的想法 + - 專案上下文 (CLAUDE.md, README.md 等) +輸出: + - docs/brainstorm/{date}-{feature}.md +依賴: 無 +觸發: vibe-kanban (主控) +``` + +### Stage 2: CEO Review + +```yaml +技能: plan-ceo-review +類型: 現有 +輸入: + - docs/brainstorm/{date}-{feature}.md +輸出: + - docs/ceo-review/{date}-{feature}.md + - 審核報告 +依賴: + - brainstorming (必須完成) +觸發: vibe-kanban (主控) +退回: 可退回 brainstorming +``` + +### Stage 3: PRD + +```yaml +技能: pm-prd +類型: 新建 +輸入: + - docs/brainstorm/{date}-{feature}.md + - docs/ceo-review/{date}-{feature}.md +輸出: + - docs/prd/{date}-{feature}.md +依賴: + - brainstorming (必須完成) + - plan-ceo-review (必須通過) +觸發: vibe-kanban (主控) +退回: 可退回 ceo-review +``` + +### Stage 4: API Design + +```yaml +技能: be-api-design +類型: 新建 +輸入: + - docs/prd/{date}-{feature}.md +輸出: + - docs/api/{date}-{feature}.yaml +依賴: + - pm-prd (必須完成) +觸發: vibe-kanban (主控) +退回: 可退回 pm-prd +``` + +### Stage 5: DB Schema + +```yaml +技能: dba-schema +類型: 新建 +輸入: + - docs/api/{date}-{feature}.yaml + - docs/prd/{date}-{feature}.md +輸出: + - docs/db/{date}-{feature}.sql + - docs/db/migrations/{version}-{description}.sql +依賴: + - be-api-design (必須完成) +觸發: vibe-kanban (主控) +退回: 可退回 be-api-design +``` + +### Stage 6: UX Prototype + +```yaml +技能: ux-prototype +類型: 新建 +輸入: + - docs/prd/{date}-{feature}.md + - docs/api/{date}-{feature}.yaml + - docs/db/{date}-{feature}.sql +輸出: + - docs/design/{date}-{feature}/user-flow.md + - docs/design/{date}-{feature}/wireframes/ + - docs/design/{date}-{feature}/prototype-link.md +依賴: + - dba-schema (必須完成) +觸發: vibe-kanban (主控) +退回: 可退回 dba-schema +``` + +### Stage 7: Design Review + +```yaml +技能: design-review +類型: 現有 +輸入: + - docs/design/{date}-{feature}/ +輸出: + - docs/design/{date}-{feature}/review-report.md +依賴: + - ux-prototype (必須完成) +觸發: vibe-kanban (主控) +退回: 可退回 pm-prd (設計與需求不符) +``` + +### Stage 8: Task Breakdown + +```yaml +技能: dispatching-parallel-agents-doc +類型: 現有 +輸入: + - docs/prd/{date}-{feature}.md + - docs/api/{date}-{feature}.yaml + - docs/design/{date}-{feature}/ +輸出: + - .gstack/kanban/{project}/tasks.md + - 任務分配 +依賴: + - design-review (必須通過) +觸發: vibe-kanban (主控) +退回: 無 +``` + +### Stage 9: Implementation + +```yaml +技能: 無 (手動或使用 writing-plans) +類型: 手動 +輸入: + - .gstack/kanban/{project}/tasks.md +輸出: + - 程式碼 + - 單元測試 +依賴: + - dispatching-parallel-agents-doc (必須完成) +觸發: 開發者手動 +退回: 無 +``` + +### Stage 10: QA + +```yaml +技能: qa +類型: 現有 +輸入: + - 程式碼 + - docs/prd/{date}-{feature}.md (驗收標準) +輸出: + - .gstack/qa-reports/qa-report-{date}.md +依賴: + -實作 (必須完成) +觸發: vibe-kanban (主控) +退回: 可退回 dispatching-parallel-agents-doc (步驟四) +``` + +### Stage 11: PR Review + +```yaml +技能: review +類型: 現有 +輸入: + - PR (程式碼變更) +輸出: + -PR 審核報告 +依賴: + - qa (必須通過) +觸發: vibe-kanban (主控) +退回: 可退回 dispatching-parallel-agents-doc (步驟四) +``` + +### Stage 12: Deploy + +```yaml +技能: land-and-deploy +類型: 現有 +輸入: + - 已核准的 PR +輸出: + - .gstack/deploy-reports/deploy-report-{date}.md +依賴: + - review (必須通過) +觸發: vibe-kanban (主控) +退回: 無 (部署失敗可重新部署) +``` + +--- + +## 退回路徑總覽 + +```yaml +退回路徑: + - from: CEO_REVIEW + to: BRAINSTORM + reason: "商業價值不足或需求不清" + + - from: PRD + to: CEO_REVIEW + reason: "PRD 與 CEO 審核不符" + + - from: API_DESIGN + to: PRD + reason: "API 設計與需求不符" + + - from: DB_SCHEMA + to: API_DESIGN + reason: "資料結構與 API 衝突" + + - from: UX_PROTOTYPE + to: DB_SCHEMA + reason: "原型與資料結構不符" + + - from: DESIGN_REVIEW + to: PRD + reason: "設計與需求不符" + + - from: QA + to: TASK_BREAKDOWN + reason: "測試不通過" + + - from: PR_REVIEW + to: TASK_BREAKDOWN + reason: "代碼審核不通過" + + - from: DEPLOY + to: IMPLEMENTATION + reason: "部署失敗" +``` + +--- + +## 檔案流向圖 + +``` +使用者輸入 + │ + ▼ +docs/brainstorm/{date}-{feature}.md + │ + ▼ +docs/ceo-review/{date}-{feature}.md + │ + ▼ +docs/prd/{date}-{feature}.md + │ + ├──▶ docs/api/{date}-{feature}.yaml + │ │ + │ └──▶ docs/db/{date}-{feature}.sql + │ │ + │ └──▶ docs/design/{date}-{feature}/ + │ │ + │ └──▶ docs/design/{date}-{feature}/review-report.md + │ + └──▶ .gstack/kanban/{project}/tasks.md + │ + └──▶ 程式碼 + │ + ├──▶ .gstack/qa-reports/qa-report-{date}.md + │ + ├──▶ PR (代碼變更) + │ + └──▶ .gstack/deploy-reports/deploy-report-{date}.md +``` + +--- + +## 版本控制建議 + +### 應納入版本控制的檔案 + +``` +.gstack/kanban/{project}/state.yaml # 工作流狀態 +docs/brainstorm/ # 需求探索文件 +docs/prd/ # PRD 文件 +docs/api/ # API 規格 +docs/db/ # 資料庫設計 +docs/design/ # 設計文件 +.gstack/qa-reports/ # QA 報告 +.gstack/deploy-reports/ # 部署報告 +``` + +### 不應納入版本控制的檔案 + +``` +.gstack/tmp/ # 暫存檔案 +node_modules/ # 依賴 +*.log # 日誌檔案 +``` + +--- + +## 授權和稽核 + +### 每個階段的授權需求 + +| 階段 | 需要授權 | 授權者 | +|------|---------|--------| +| BRAINSTORM | 否 | - | +| CEO_REVIEW | 是 | CEO/決策者 | +| PRD | 是 | PM | +| API_DESIGN | 是 | 後端負責人 | +| DB_SCHEMA | 是 | DBA | +| UX_PROTOTYPE | 是 | UX 設計師 | +| DESIGN_REVIEW | 是 | 設計審核者 | +| TASK_BREAKDOWN | 否 | - | +| IMPLEMENTATION | 否 | - | +| QA | 否 | - | +| PR_REVIEW | 是 | 代碼審核者 | +| DEPLOY | 否 | - | + +--- + +## 效能考量 + +### 平行執行機會 + +```yaml +可平行執行: + - API_DESIGN + DB_SCHEMA (可同時進行) + - 前端實作 + 後端實作 (可同時進行) + +不可平行執行: + - BRAINSTORM → CEO_REVIEW (必須順序) + - PRD → API_DESIGN (必須順序) + - QA → PR_REVIEW → DEPLOY (必須順序) +``` + +### 快取策略 + +```yaml +可快取: + - 專案上下文 (CLAUDE.md, README.md) + - 現有 API 規格 + - 現有資料庫 Schema + +不可快取: + - 當前階段的輸出 + - 狀態檔案 +``` \ No newline at end of file diff --git a/design-idea/VIBE_KANBAN_INTEGRATION_PLAN.md b/design-idea/VIBE_KANBAN_INTEGRATION_PLAN.md new file mode 100644 index 0000000..ec6b2d5 --- /dev/null +++ b/design-idea/VIBE_KANBAN_INTEGRATION_PLAN.md @@ -0,0 +1,440 @@ +# Vibe-Kanban 工作流程 - 技能整合規劃 + +**版本**: 3.0 +**日期**: 2025-01-15 +**狀態**: 實施階段 + +--- + +## 執行摘要 + +本規劃整合多個現有技能，建立完整的軟體開發工作流程。 + +**總計**: 11 個現有技能 + 5 個新建技能 +**Agent**: 8 個核心 Agent + 1 個主控協調器 +**階段**: 12 個工作流程階段 + +--- + +## 現有技能整合清單 + +### 核心技能（直接使用） + +| Skill | 來源 | 用途 | 整合階段 | +|-------|------|------|---------| +| `brainstorming` | skills | PM 需求探索 | Stage 1 | +| `plan-ceo-review` | gstack | CEO 商業價值審核 | Stage 2 | +| `write-a-prd` | skills | PRD 撰寫（含訪談） | Stage 3 | +| `grill-me` | skills | **深度驗證閘門** | Stage 3.5 | +| `prd-to-plan` | skills | 實作計畫產出 | Stage 8 | +| `design-an-interface` | skills | API 介面設計 | Stage 4 | +| `tdd` | skills | 測試驅動開發 | Stage 9 | +| `qa` | skills | QA 測試驗收 | Stage 10 | +| `review` | gstack | PR 代碼審核 | Stage 11 | +| `land-and-deploy` | gstack | 部署流程 | Stage 12 | +| `cso` | gstack | 安全審核 | Stage 7/11 | +| `codex` | gstack | 多 AI 代碼審核 | Stage 11 | + +### 新增技能（需實作） + +| Skill | 用途 | 優先級 | +|-------|------|--------| +| `vibe-kanban` | **主控協調器** | P0 | +| `be-api-design` | OpenAPI 規格產出 | P1 | +| `go-backend-dev` | **Golang 後端實作** | P1 | +| `dba-schema` | 資料庫 Schema 設計 | P1 | +| `ux-prototype` | UX 原型設計 | P2 | + +--- + +## Agent 角色定義 + +| # | Agent | 角色 | 主要技能 | +|---|-------|------|---------| +| 1 | **Orchestrator** | 主控協調器 | `vibe-kanban` | +| 2 | **PM Agent** | 產品經理 | `brainstorming`, `write-a-prd` | +| 3 | **CEO Reviewer** | 商業決策者 | `plan-ceo-review` | +| 4 | **Backend Agent** | Golang 後端工程師 | `be-api-design`, `go-backend-dev`, `design-an-interface`, `tdd` | +| 5 | **DBA Agent** | 資料庫工程師 | `dba-schema` | +| 6 | **UX Agent** | 使用者體驗設計師 | `ux-prototype` | +| 7 | **QA Agent** | 品質保證工程師 | `qa` | +| 8 | **DevOps Agent** | 運維工程師 | `land-and-deploy` | +| 9 | **Design Reviewer** | 設計審核者 | `design-review` | +| 10 | **Security Reviewer** | 安全審核者 | `cso` | +| 11 | **Code Reviewer** | 代碼審核者 | `review`, `codex` | + +--- + +## 完整工作流程（含 Grill-Me 整合） + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ VIBE-KANBAN + GRILL-ME 工作流程 │ +└─────────────────────────────────────────────────────────────────────────────┘ + +Stage 1: Brainstorming (PM Agent) +├── Skill: brainstorming +├── 輸入: 使用者想法 +├── 輸出: docs/brainstorm/{date}-{feature}.md +└── 下一步: CEO Review + +Stage 2: CEO Review (CEO Reviewer) +├── Skill: plan-ceo-review +├── 輸入: Brainstorm 文件 +├── 輸出: docs/ceo-review/{date}-{feature}.md +└── 下一步: PRD 撰寫 + +Stage 3: PRD 撰寫 (PM Agent) +├── Skill: write-a-prd +├── 輸入: CEO Review 結果 +├── 輸出: docs/prd/{date}-{feature}.md (初版) +└── 下一步: 深度驗證 (可選) + +Stage 3.5: 深度驗證 ⭐ GRILL-ME 整合點 +├── Skill: grill-me +├── 觸發條件: 使用者選擇 "進行深度驗證" +├── 輸入: PRD 初版 +├── 驗證項目: +│ ├── 每個功能性需求的完整性 +│ ├── 使用者故事的邊界情況 +│ ├── 非功能性需求的遺漏 +│ ├── 驗收標準的可測試性 +│ └── 潛在風險和依賴 +├── 輸出: 強化後的 PRD +└── 下一步: API Design + +Stage 4: API Design (Backend Agent) +├── Skill: be-api-design + design-an-interface +├── 輸入: PRD +├── 輸出: docs/api/{date}-{feature}.yaml +└── 下一步: DB Schema (平行) + +Stage 5: DB Schema (DBA Agent) +├── Skill: dba-schema +├── 輸入: API 規格 +├── 輸出: docs/db/{date}-{feature}.sql +└── 下一步: UX Prototype (平行) + +Stage 6: UX Prototype (UX Agent) +├── Skill: ux-prototype +├── 輸入: PRD + API + DB +├── 輸出: docs/design/{date}-{feature}/ +└── 下一步: Design Review + +Stage 7: Design Review (Design Reviewer) +├── Skill: design-review +├── 輸入: 所有設計文件 +├── 輸出: docs/design/review-report.md +├── 決策點: +│ ├── ✅ 通過 → Task Breakdown +│ └── ❌ 退回 → PRD 修改 +└── 下一步: Task Breakdown + +Stage 8: Task Breakdown (Orchestrator) +├── Skill: prd-to-plan +├── 輸入: 所有設計文件 +├── 輸出: ./plans/{feature}.md +└── 下一步: 實作 (平行) + +Stage 9: Implementation (Backend + Frontend Agents) +├── Backend Skill: go-backend-dev + tdd +├── Frontend Skill: (現有技能或手動) +├── 輸入: 實作計畫 +├── 輸出: 程式碼 +└── 下一步: QA + +Stage 10: QA (QA Agent) +├── Skill: qa +├── 輸入: 程式碼 + 驗收標準 +├── 輸出: .gstack/qa-reports/qa-report.md +├── 決策點: +│ ├── ✅ 通過 → PR Review +│ └── ❌ 失敗 → 退回 Task Breakdown +└── 下一步: PR Review + +Stage 11: PR Review (Code Reviewer) +├── Skill: review + codex +├── 輸入: PR +├── 輸出: PR 審核報告 +├── 決策點: +│ ├── ✅ 通過 → Deploy +│ └── ❌ 失敗 → 退回 Task Breakdown +└── 下一步: Deploy + +Stage 12: Deploy (DevOps Agent) +├── Skill: land-and-deploy +├── 輸入: 已核准 PR +├── 輸出: .gstack/deploy-reports/deploy-report.md +└── 🎉 完成 +``` + +--- + +## Grill-Me 深度驗證詳細設計 + +### 觸發機制 + +在每個關鍵階段後，Orchestrator 會詢問： + +``` +╔══════════════════════════════════════════════════════════════╗ +║ 🔥 深度驗證機會 ║ +╠══════════════════════════════════════════════════════════════╣ +║ ║ +║ 當前階段: PRD 撰寫 ║ +║ 狀態: ✅ 初版已完成 ║ +║ ║ +║ 是否需要進行深度驗證 (grill-me)？ ║ +║ 這將透過密集訪談壓力測試計畫的完整性。 ║ +║ ║ +║ [A] 是 - 進行深度驗證 (推薦用於關鍵功能) ║ +║ [B] 否 - 直接進入下一階段 ║ +║ ║ +╚══════════════════════════════════════════════════════════════╝ +``` + +### 驗證檢查清單 + +#### Stage 3.5 - PRD 深度驗證 + +```yaml +驗證項目: + 功能性需求: + - "每個 FR 是否有明確的驗收標準？" + - "使用者故事是否覆蓋所有使用者角色？" + - "是否有遺漏的邊界情況？" + + 非功能性需求: + - "效能需求是否具體可量測？" + - "安全性需求是否完整？" + - "可用性和可靠性是否考量？" + + 技術可行性: + - "現有技術棧是否支援？" + - "是否有外部依賴風險？" + - "擴展性是否考量？" + + 業務邏輯: + - "所有業務規則是否明確？" + - "錯誤處理流程是否定義？" + - "狀態轉換是否清晰？" +``` + +### 整合流程圖 + +```mermaid +graph TD + A[Stage 3: PRD 初版] --> B{深度驗證?} + B -->|是| C[Stage 3.5: grill-me] + B -->|否| D[Stage 4: API Design] + + C --> C1[問題 1: 需求完整性] + C1 --> C2[問題 2: 邊界情況] + C2 --> C3[問題 3: 風險評估] + C3 --> C4[...更多問題] + C4 --> E[強化 PRD] + + E --> D + + D --> F[後續階段] +``` + +--- + +## 各階段交付文件 + +| 階段 | Agent | 主要技能 | 輔助技能 | 交付文件 | +|------|-------|---------|---------|---------| +| 1 | PM | brainstorming | - | `docs/brainstorm/{date}-{feature}.md` | +| 2 | CEO Reviewer | plan-ceo-review | - | `docs/ceo-review/{date}-{feature}.md` | +| 3 | PM | write-a-prd | - | `docs/prd/{date}-{feature}.md` (初版) | +| 3.5 | PM | **grill-me** | - | `docs/prd/{date}-{feature}.md` (強化版) | +| 4 | Backend | be-api-design | design-an-interface | `docs/api/{date}-{feature}.yaml` | +| 5 | DBA | dba-schema | - | `docs/db/{date}-{feature}.sql` | +| 6 | UX | ux-prototype | - | `docs/design/{date}-{feature}/` | +| 7 | Design Reviewer | design-review | cso | `docs/design/review-report.md` | +| 8 | Orchestrator | prd-to-plan | dispatching-parallel-agents | `./plans/{feature}.md` | +| 9 | Backend | go-backend-dev | tdd | `internal/`, `cmd/`, `pkg/` | +| 10 | QA | qa | - | `.gstack/qa-reports/qa-report.md` | +| 11 | Code Reviewer | review | codex | PR 審核報告 | +| 12 | DevOps | land-and-deploy | - | `.gstack/deploy-reports/deploy-report.md` | + +--- + +## 技能依賴關係 + +```yaml +技能依賴: + brainstorming: + 輸入: 使用者想法 + 輸出: brainstorm.md + + plan-ceo-review: + 輸入: brainstorm.md + 輸出: ceo-review.md + + write-a-prd: + 輸入: ceo-review.md + 輸出: prd.md (初版) + + grill-me: # 可選 + 輸入: prd.md (初版) + 輸出: prd.md (強化版) + 依賴: write-a-prd + + be-api-design: + 輸入: prd.md + 輸出: api-spec.yaml + 輔助: design-an-interface + + dba-schema: + 輸入: api-spec.yaml + 輸出: schema.sql + + ux-prototype: + 輸入: prd.md, api-spec.yaml, schema.sql + 輸出: design/ + + design-review: + 輸入: design/ + 輸出: review-report.md + + prd-to-plan: + 輸入: prd.md, api-spec.yaml, design/ + 輸出: ./plans/{feature}.md + + go-backend-dev: + 輸入: ./plans/{feature}.md + 輸出: 程式碼 + 輔助: tdd + + qa: + 輸入: 程式碼, prd.md (驗收標準) + 輸出: qa-report.md + + review: + 輸入: PR + 輸出: pr-review.md + 輔助: codex + + land-and-deploy: + 輸入: pr-review.md (已核准) + 輸出: deploy-report.md +``` + +--- + +## Golang 後端特定規則（go-backend-dev） + +### 架構風格 + +```yaml +預設架構: Clean Architecture (適合中型專案) + +專案結構: + cmd/api/main.go # 進入點 + internal/ + domain/ # Entities, Value Objects + usecase/ # Business Logic + interface/ + http/ # Handlers + repository/ # Repository interfaces + infrastructure/ # DB, Cache implementations + pkg/ + logger/ # Zap + errors/ # 自定義錯誤 + validator/ # go-playground/validator + api/openapi.yaml + migrations/ + test/ +``` + +### 編碼規範 + +```yaml +命名: + Package: 小寫單數 (user, not users) + Interface: 方法名 + 'er' (Reader, Writer) + Exported: PascalCase + Internal: camelCase + +錯誤處理: + - Always check errors + - Error strings lowercase + - Use fmt.Errorf with %w + +API 設計: + RESTful: /api/v1/{resource} + 狀態碼: 200, 201, 400, 401, 404, 422, 500 + +測試: + - Unit tests >= 80% 覆蓋率 + - Integration tests for critical paths + - Use testify + mockery +``` + +--- + +## 實作優先順序 + +### Phase 1: 核心框架 (Week 1) + +| 優先級 | Skill | 複雜度 | 說明 | +|-------|-------|--------|------| +| P0 | vibe-kanban | 高 | 主控協調器，整合所有技能 | +| P0 | grill-me 整合 | 中 | 設計深度驗證流程 | + +### Phase 2: 設計階段技能 (Week 2) + +| 優先級 | Skill | 複雜度 | 說明 | +|-------|-------|--------|------| +| P1 | be-api-design | 中 | OpenAPI 規格產出 | +| P1 | go-backend-dev | 高 | **Golang 後端實作** | +| P1 | dba-schema | 中 | 資料庫設計 | + +### Phase 3: 整合測試 (Week 3) + +- 整合所有現有技能 +- 端到端流程測試 +- 退回機制測試 + +### Phase 4: 優化 (Week 4) + +- 效能優化 +- 文件完善 +- 使用指南 + +--- + +## 附錄 + +### A. 技術棧建議 + +**Golang 後端**: +- 框架: Gin 或 Echo +- ORM: GORM 或 sqlx +- 配置: Viper +- 日誌: Zap +- 驗證: go-playground/validator +- 測試: testify + mockery +- 文件: swag (Swagger) + +**資料庫**: +- 主要: PostgreSQL +- 快取: Redis +- 遷移: golang-migrate/migrate + +**部署**: +- 容器: Docker +- CI/CD: GitHub Actions + +### B. 參考資源 + +1. [Uber Go Style Guide](https://github.com/uber-go/guide) +2. [golang-standards/project-layout](https://github.com/golang-standards/project-layout) +3. [Go Clean Architecture](https://github.com/bxcodec/go-clean-arch) +4. [A Philosophy of Software Design](https://web.stanford.edu/~ouster/cgi-bin/book.php) (for grill-me 概念) + +--- + +**下一步**: 開始實作 `vibe-kanban` 主控技能？ \ No newline at end of file diff --git a/design-idea/VIBE_KANBAN_PLAN.md b/design-idea/VIBE_KANBAN_PLAN.md new file mode 100644 index 0000000..a1ae78d --- /dev/null +++ b/design-idea/VIBE_KANBAN_PLAN.md @@ -0,0 +1,1231 @@ +# Vibe-Kanban 工作流程規劃文件 + +**版本:** 1.0 +**日期:** 2025-01-15 +**狀態:** 規劃階段 + +--- + +## 概述 + +本文件定義一個完整的軟體開發工作流程，透過多個 AI 代理協作完成從需求探索到部署的完整生命週期。 + +--- + +## 目錄 + +1. [工作流程總覽](#1-工作流程總覽) +2. [現有技能映射](#2-現有技能映射) +3. [新建技能定義](#3-新建技能定義) +4. [主控技能設計](#4-主控技能設計) +5. [狀態機設計](#5-狀態機設計) +6. [文件結構規劃](#6-文件結構規劃) +7. [實施優先順序](#7-實施優先順序) +8. [退回機制設計](#8-退回機制設計) +9. [驗收標準模板](#9-驗收標準模板) + +--- + +## 1. 工作流程總覽 + +``` +┌─────────────────────────────────────────────────────────────────────────────┐ +│ VIBE-KANBAN 工作流程 │ +├─────────────────────────────────────────────────────────────────────────────┤ +│ │ +│ 階段1: 需求探索 │ +│ ┌────────────┐ ┌────────────┐ │ +│ │Brainstorm │ ──▶ │ CEO Review │ │ +│ │ (PM) │ │ (商業價值) │ │ +│ └────────────┘ └────────────┘ │ +│ │ │ │ +│ │ ┌────────────┘ │ +│ ▼ ▼ │ +│ 階段2: 規格設計 │ +│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ +│ │ PRD │ ──▶ │ API Design │ ──▶ │ DB Schema │ ──▶ │ UX/原型 │ │ +│ │ (PM) │ │ (後端) │ │ (DBA) │ │ (UX) │ │ +│ └────────────┘ └────────────┘ └────────────┘ └────────────┘ │ +│ │ │ │ │ │ +│ └───────────────────┴───────────────────┴───────────────────┘ │ +│ │ │ +│ ▼ │ +│ 階段3: 審核 ┌────────────┐ │ +│ ┌────────────┐ │ Design │ │ +│ │Design Review│ ◀────────────────────│ Review │ │ +│ │ (通盤審核) │ │ (退回修改) │ │ +│ └────────────┘ └────────────┘ │ +│ │ │ +│ │ 通過 │ +│ ▼ │ +│ 階段4: 任務拆分 │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ Task Breakdown │ │ +│ │ (平行拆分前後端任務) │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ 階段5: 實作 │ +│ ┌────────────┐ ┌────────────┐ │ +│ │ Frontend │ │ Backend │ │ +│ │implementation│ │implementation│ │ +│ └────────────┘ └────────────┘ │ +│ │ │ │ +│ └─────────────────┬───────────────────┘ │ +│ ▼ │ +│ 階段6: 驗收 │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ QA Testing │ │ +│ │ (依照驗收標準測試) │ │ +│ │ (不通過 → 退回步驟4) │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ 通過 │ +│ ▼ │ +│ 階段7: 合併審核 │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ PR Review │ │ +│ │ (人類驗證) │ │ +│ │ (不通過 → 退回步驟4) │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ │ 通過 │ +│ ▼ │ +│ 階段8: 部署 │ +│ ┌────────────────────────────────────────────────────────────────────┐ │ +│ │ Deploy │ │ +│ │ (OPS) │ │ +│ └────────────────────────────────────────────────────────────────────┘ │ +│ │ │ +│ ▼ │ +│ ┌────────────┐ │ +│ │ 完成 │ │ +│ └────────────┘ │ +│ │ +└─────────────────────────────────────────────────────────────────────────────┘ +``` + +--- + +## 2. 現有技能映射 + +### 2.1 可直接複用的技能 + +| 階段 | 技能名稱 | 檔案位置 | 用途 | +|------|---------|---------|------| +| 1. Brainstorming | `brainstorming` | `skills/brainstorming/` | PM 需求探索 | +| 1. CEO Review | `plan-ceo-review` | `gstack/plan-ceo-review/` | 商業價值審核 | +| 3. Design Review | `design-review` | `gstack/design-review/` | 視覺/架構審核 | +| 3. Design Review | `plan-design-review` | `gstack/plan-design-review/` | 設計計畫審核 | +| 4. Task Breakdown | `dispatching-parallel-agents` | `skills/dispatching-parallel-agents/` | 平行任務分配 | +| 4. Task Breakdown | `subagent-driven-development` | `skills/subagent-driven-development/` | 子代理驅動開發 | +| 5. Implementation | `writing-plans` | `skills/writing-plans/` | 撰寫實作計畫 | +| 6. QA | `qa` | `gstack/qa/` | QA 測試驗收 | +| 7. PR Review | `review` | `gstack/review/` | PR 代碼審核 | +| 7. PR Review | `requesting-code-review` | `skills/requesting-code-review/` | 請求代碼審核 | +| 8. Deploy | `land-and-deploy` | `gstack/land-and-deploy/` | 合併與部署 | +| 8. Deploy | `setup-deploy` | `gstack/setup-deploy/` | 部署配置 | + +### 2.2 現有技能功能摘要 + +#### `brainstorming` +- 輸入: 使用者的初步想法 +- 輸出: 設計文件 +- 流程: 探索專案 → 提問澄清 → 提案 → 設計文件 + +#### `plan-ceo-review` +- 輸入: 設計文件或計畫 +- 輸出: 審核報告 + 擴展建議 +- 模式: SCOPE_EXPANSION, SELECTIVE_EXPANSION, HOLD_SCOPE, SCOPE_REDUCTION +- 檢查: 架構、錯誤處理、安全性、效能、測試、部署 + +#### `qa` +- 輸入: 驗收標準 + 測試 URL +- 輸出: QA 報告 + Bug 修复 +- 流程: 探索 → 測試 → 文件化 → 修复 → 驗證 + +#### `land-and-deploy` +- 輸入: PR 編號 +- 輸出: 部署報告 +- 流程: 預檢查 → 合併 → 部署 → Canary 驗證 + +--- + +## 3. 新建技能定義 + +### 3.1 `pm-prd` - 產品需求文件技能 + +```yaml +--- +name: pm-prd +description: "產品經理撰寫 PRD 和驗收標準。根據 brainstorming 輸出產出結構化的產品需求文件，包含功能性需求、非功能性需求、驗收標準。觸發時機：CEO 審核通過後。" +--- + +## 職責 + +PM 角色的AI 代理，負責： + +1. 將 brainstorming 的想法轉化為結構化 PRD +2. 定義功能性需求 +3. 定義非功能性需求- 效能、安全性、可用性等 +4. 設定驗收標準 +5. 優先順序排序 + +## 輸入 + +- Brainstorming 輸出文件 +- CEO 審核結果 +- 專案上下文 (CLAUDE.md, ARCHITECTURE.md 等現有文件) + +## 輸出 + +- PRD 文件: `docs/prd/{YYYY-MM-DD}-{feature-slug}.md` + +## PRD 模板結構 + +```markdown +# PRD: {功能名稱} + +## Metadata +- 撰寫日期: {date} +- 狀態: Draft | Review | Approved +- 作者: PM Agent +- 關聯 Brainstorm: {link} + +## 背景 +### 問題陳述 +### 目標使用者 +### 商業價值 + +## 功能性需求 + +### FR-001: {需求標題} +- 描述: +- 優先級: P0 | P1 | P2 +- 使用者故事: 作為{role}，我想要{action}，以便{benefit} + +### FR-002: ... + +## 非功能性需求 + +###NFR-001: 效能 +- 描述: 頁面載入時間< 2秒 +- 量測方式: ... + +### NFR-002: 安全性 +- 描述: 所有 API 需驗證 +- 量測方式: ... + +##驗收標準 + +### AC-001: {驗收項目} +- Given: 前置條件 +- When: 觸發動作 +- Then: 預期結果 +- 自動化: 是/否 +- 測試腳本: (連結到測試案例) + +### AC-002: ... + +## 排期建議 +- Phase 1: ... +- Phase 2: ... + +## 依賴 +- 外部依賴: ... +- 內部依賴: ... + +## 風險評估 +- 風險: ... +- 緩解措施: ... +``` + +## 流程 + +```mermaid +graph TD + A[讀取 Brainstorming 文件] --> B[分析需求結構] + B --> C[產出功能性需求] + B --> D[產出非功能性需求] + C --> E[定義驗收標準] + D --> E + E --> F[優先級排序] + F --> G[風險評估] + G --> H[撰寫 PRD 文件] + H --> I[人類審核] + I -->|通過| J[進入下一階段] + I -->|修改| C +``` + +## 相依技能 + +- 前置: `brainstorming`, `plan-ceo-review` +- 後續: `be-api-design`, `dba-schema`, `ux-prototype` +``` + +--- + +### 3.2 `be-api-design` - API 設計技能 + +```yaml +--- +name: be-api-design +description: "後端工程師設計 API 規格。根據 PRD 產出 OpenAPI 3.0 規格文件，包含端點、請求/回應結構、錯誤處理。觸發時機：PRD 審核通過後。" +--- + +## 職責 + +後端工程師角色的 AI 代理，負責： + +1. 分析 PRD 中的功能性需求 +2. 設計 RESTful API 端點 +3. 定義請求/回應 schema +4. 設計錯誤處理機制 +5. 考量 API 版本控制 +6. 產出 OpenAPI 3.0 規格 + +## 輸入 + +- PRD 文件 +- 現有 API 風格 (專案中現有的 API 規格) +- 資料模型上下文 + +## 輸出 + +- API 規格文件: `docs/api/{YYYY-MM-DD}-{feature-slug}.yaml` + +## API 設計模板 + +```yaml +openapi: 3.0.3 +info: + title: {API名稱} + version: 1.0.0 + description: | + {API 描述} + + 相關 PRD: {PRD 連結} + +paths: + /api/v1/{resource}: + get: + summary: {操作描述} + tags: + - {標籤} + parameters: + - name: {參數名} + in: query | path | header + required: true | false + schema: + type: string + responses: + '200': + description: 成功回應 + content: + application/json: + schema: + $ref: '#/components/schemas/{Schema}' + '400': + description: 請求錯誤 + '401': + description: 未授權 + '500': + description: 伺服器錯誤 + +components: + schemas: + {SchemaName}: + type: object + properties: + {property}: + type: {type} + description: {描述} + required: + - {required_fields} +``` + +## 設計考量清單 + +### 安全性 +- [ ] 所有端點都有適當的認證機制 +- [ ] 輸入驗證 +- [ ] 速率限制 +- [ ] CORS 配置 + +### 效能 +- [ ] 分頁支援 +- [ ] 快取策略 +- [ ] 批次操作支援 + +### 可靠性 +- [ ] 錯誤回應格式統一 +- [ ] 重試機制建議 +- [ ] 冪等性設計 + +## 流程 + +```mermaid +graph TD + A[讀取 PRD] --> B[識別資源與操作] + B --> C[設計端點結構] + C --> D[定義 Schema] + D --> E[設計錯誤處理] + E --> F[安全性審查] + F --> G[效能考量] + G --> H[產出 OpenAPI 文件] + H --> I[人類審核] + I -->|通過| J[進入 DB 規劃] + I -->|修改| C +``` + +## 相依技能 + +- 前置: `pm-prd` +- 後續: `dba-schema` +``` + +--- + +### 3.3 `dba-schema` - 資料庫綱要技能 + +```yaml +--- +name: dba-schema +description: "DBA 規劃資料庫綱要。根據 API 規格設計資料庫 schema，包含索引策略、遷移計畫、效能考量。觸發時機：API 設計完成後。" +--- + +## 職責 + +DBA 角色的 AI 代理，負責： + +1. 分析 API 規格中的資料結構 +2. 設計正規化的資料庫 schema +3. 規劃索引策略 +4. 設計遷移計畫 +5. 效能優化建議 + +## 輸入 + +- API 規格文件 +- PRD 文件 (了解業務需求) +- 現有資料庫 schema (如有) + +## 輸出 + +- Schema 文件: `docs/db/{YYYY-MM-DD}-{feature-slug}.sql` +- 遷移計畫: `docs/db/migrations/{version}-{description}.sql` + +## Schema 設計模板 + +```sql +-- Migration: {feature_name} +-- Version: {version} +-- Date: {date} +-- Author: DBA Agent +-- Related API: {API規格連結} + +-- ====== Tables ====== + +CREATE TABLE {table_name} ( + idBIGSERIAL PRIMARY KEY,-- 效能考量 + created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(), + + -- 業務欄位 + {column_name} {type} {constraints}, + -- ... +); + +-- ====== Indexes ====== + +-- 主要查詢索引 +CREATE INDEX idx_{table}_{column} ON {table_name} ({column}); + +-- 複合索引 (考量查詢模式) +CREATE INDEX idx_{table}_{columns} ON {table_name} ({column1}, {column2}); + +-- ======Constraints ====== + +-- 外鍵關聯 +ALTER TABLE {table_name} + ADD CONSTRAINT fk_{relation} + FOREIGN KEY ({column}) + REFERENCES {related_table}({related_column}) + ON DELETE CASCADE; + +-- ====== Triggers ====== + +-- 自動更新 updated_at +CREATE TRIGGER update_{table}_updated_at + BEFORE UPDATE ON {table_name} + FOR EACH ROW + EXECUTE FUNCTION update_updated_at_column(); + +-- ====== Comments ====== + +COMMENT ON TABLE {table_name} IS '{描述}'; +COMMENT ON COLUMN {table_name}.{column} IS '{描述}'; +``` + +## 設計原則 + +### 正規化 +- 達到第三正規化 (3NF) +- 視查詢模式進行反正規化優化 + +### 索引策略 +- 主鍵: 自動建立 +- 外鍵: 視查詢頻率決定 +- 常用篩選條件: 建立索引 +- 複合索引: 依查詢模式設計 + +### 效能考量 +- 大表分區策略 +- 讀寫分離建議 +- 連線池配置 + +## 流程 + +```mermaid +graph TD + A[讀取 API 規格] --> B[識別資料實體] + B --> C[設計資料表] + C --> D[定義關聯] + D --> E[規劃索引] + E --> F[遷移計畫] + F --> G[效能審查] + G --> H[產出 Schema 文件] + H --> I[人類審核] + I -->|通過| J[進入 UX 原型] + I -->|修改| C +``` + +## 相依技能 + +- 前置: `be-api-design` +- 後續: `ux-prototype` +``` + +--- + +### 3.4 `ux-prototype` - UX 原型技能 + +```yaml +--- +name: ux-prototype +description: "UX 設計師產出原型設計。根據 PRD 和 API 規格設計使用者介面原型，整合 pancel.dev 或其他工具。觸發時機：API 和 DB 設計完成後。" +--- + +## 職責 + +UX 設計師角色的 AI 代理，負責： + +1. 分析 PRD 中的使用者故事 +2. 設計使用者流程 +3. 產出線框圖 +4. 設計互動原型 +5. 確保設計與 API 規格對應 + +## 輸入 + +- PRD 文件 +- API 規格文件 +- DB Schema (了解資料結構) + +## 輸出 + +- 設計文件: `docs/design/{YYYY-MM-DD}-{feature-slug}/` + - `user-flow.md` - 使用者流程 + - `wireframes/` - 線框圖 + - `prototype-link.md` - 原型連結 + +## 設計流程 + +### 1. 使用者流程圖 + +```markdown +# User Flow: {功能名稱} + +## 流程圖 + +```mermaid +graph TD + A[登入頁面] --> B{已登入?} + B -->|是| C[首頁] + B -->|否| D[註冊/登入] + D --> E[填寫表單] + E --> F[提交] + F --> G{驗證成功?} + G -->|是| C + G -->|否| H[錯誤提示] + H --> D +``` + +## 頁面清單 + +| 頁面 | URL | 描述 | API 端點 | +|------|-----|------|----------| +| 登入 | /login | 使用者登入 | POST /api/v1/auth/login | +| 首頁 | / | 產品首頁 | GET /api/v1/dashboard | +``` + +### 2. 元件對應表 + +```markdown +# 元件與 API 對應 + +## 頁面: {page_name} + +| 元件 | 資料來源 | API 端點 | 快取策略 | +|------|---------|---------|---------| +| 使用者列表 |Users API | GET /api/v1/users | SWR| +| 搜尋框 | Search API | GET /api/v1/search | Debounce | +``` + +### 3. 線框圖描述 + +使用文字描述關鍵頁面的線框圖： + +```markdown +# Wireframe: {page_name} + +## 佈局 + +``` +┌─────────────────────────────────────────┐ +│Header│ +│ Logo Nav │ User │ +├─────────────────────────────────────────┤ +│ │ +│ Main Content │ +│ ┌─────────────────────────────────┐│ +│ │ ││ +│ │Content Area ││ +│ │ ││ +│ └─────────────────────────────────┘│ +│ │ +├─────────────────────────────────────────┤ +│ Footer │ +└─────────────────────────────────────────┘ +``` + +## 元件清單 + +- Header: 導航列 +- ContentArea: 主要內容區 +- Footer: 頁尾 +``` + +##原型工具建議 + +### 選項 1: pancel.dev +- 優點: 快速產出、AI 協助 +- 適用: 快速原型、內部工具 + +### 選項 2: Figma +- 優點: 專業設計、協作 +- 適用: 產品設計、客戶展示 + +### 選項 3: 文字描述 + HTML +- 優點: 版本控制、直接實作 +- 適用: 技術團隊 + +## 流程 + +```mermaid +graph TD + A[讀取 PRD 和 API 規格] --> B[識別使用者故事] + B --> C[設計使用者流程] + C --> D[繪製線框圖] + D --> E[元件與 API 對應] + E --> F[產出原型] + F --> G[人類審核] + G -->|通過| H[進入 Design Review] + G -->|修改| D +``` + +## 相依技能 + +- 前置: `pm-prd`, `be-api-design`, `dba-schema` +- 後續: `design-review` +``` + +--- + +## 4. 主控技能設計 + +### 4.1 `vibe-kanban` 技能 + +```yaml +--- +name: vibe-kanban +description: "完整的軟體開發工作流程協調器。管理從需求探索到部署的完整生命週期，支援階段間轉換、退回機制、狀態持久化。觸發方式：/vibe-kanban" +--- + +## 職責 + +工作流程的主控協調器，負責： + +1. 狀態機管理 - 追蹤當前階段 +2. 階段間轉換 - 自動觸發對應技能 +3. 退回機制 - 處理審核不通過 +4. 狀態持久化 - 儲存工作流進度 +5. 進度報告 - 提供視覺化狀態 + +## 命令 + +- `/vibe-kanban start` - 開始新工作流 +- `/vibe-kanban status` - 查看當前狀態 +- `/vibe-kanban next` - 前往下一階段 +- `/vibe-kanban back [reason]` - 退回上一階段 +- `/vibe-kanban skip` - 跳過當前階段 (需確認) + +## 狀態機 + +見 [第5節](#5-狀態機設計) + +## 狀態持久化 + +```yaml +# .gstack/kanban/{project-slug}/state.yaml +version: 1.0 +project: {project-name} +created_at: {ISO timestamp} +updated_at: {ISO timestamp} + +current_phase: PRD +phase_status: IN_PROGRESS # PENDING | IN_PROGRESS | COMPLETED | BLOCKED + +history: + - phase: BRAINSTORM + status: COMPLETED + started_at: 2025-01-15T10:00:00Z + completed_at: 2025-01-15T11:30:00Z + duration_minutes: 90 + output: docs/brainstorm/2025-01-15-feature-x.md + triggered_skill: brainstorming + + - phase: CEO_REVIEW + status: COMPLETED + started_at: 2025-01-15T11:30:00Z + completed_at: 2025-01-15T14:00:00Z + duration_minutes: 150 + output: docs/ceo-review/2025-01-15-feature-x.md + triggered_skill: plan-ceo-review + notes: "通過，建議擴展範圍" + +artifacts: + brainstorm: docs/brainstorm/2025-01-15-feature-x.md + prd: null # 待產出 + api_spec: null + db_schema: null + ux_prototype: null + +blockers: [] +next_actions: + - "執行 /pm-prd 產出PRD" +``` + +## 階段轉換邏輯 + +```python +# 階段轉換條件 +TRANSITIONS = { + "BRAINSTORM": { + "next": "CEO_REVIEW", + "skill": "brainstorming", + "required_artifacts": ["brainstorm.md"], + "auto_trigger": True + }, + "CEO_REVIEW": { + "next": "PRD", + "skill": "plan-ceo-review", + "required_artifacts": ["ceo-review.md"], + "approval_required": True + }, + "PRD": { + "next": "API_DESIGN", + "skill": "pm-prd", + "required_artifacts": ["prd.md"], + "approval_required": True + }, + "API_DESIGN": { + "next": "DB_SCHEMA", + "skill": "be-api-design", + "required_artifacts": ["api-spec.yaml"], + "approval_required": True + }, + "DB_SCHEMA": { + "next": "UX_PROTOTYPE", + "skill": "dba-schema", + "required_artifacts": ["schema.sql"], + "approval_required": True + }, + "UX_PROTOTYPE": { + "next": "DESIGN_REVIEW", + "skill": "ux-prototype", + "required_artifacts": ["prototype/"], + "approval_required": True + }, + "DESIGN_REVIEW": { + "next": "TASK_BREAKDOWN", + "skill": "design-review", + "required_artifacts": ["review-report.md"], + "approval_required": True, + "can_fail_back_to": "PRD"# 可退回到PRD 階段 + }, + "TASK_BREAKDOWN": { + "next": "IMPLEMENTATION", + "skill": "dispatching-parallel-agents", + "required_artifacts": ["tasks.md"], + "approval_required": False + }, + "IMPLEMENTATION": { + "next": "QA", + "skill": None,# 手動實作 + "required_artifacts": ["code/"], + "approval_required": False + }, + "QA": { + "next": "PR_REVIEW", + "skill": "qa", + "required_artifacts": ["qa-report.md"], + "approval_required": False, + "can_fail_back_to": "TASK_BREAKDOWN" # QA不通過退回步驟四 + }, + "PR_REVIEW": { + "next": "DEPLOY", + "skill": "review", + "required_artifacts": ["pr-review.md"], + "approval_required": True, + "can_fail_back_to": "TASK_BREAKDOWN" # PR審核不通過退回步驟四 + }, + "DEPLOY": { + "next": "COMPLETED", + "skill": "land-and-deploy", + "required_artifacts": ["deploy-report.md"], + "approval_required": False + } +} +``` + +## 流程圖 + +```mermaid +stateDiagram-v2 + [*] --> BRAINSTORM: /vibe-kanban start + + BRAINSTORM --> CEO_REVIEW: 通過 + CEO_REVIEW --> PRD: 通過 + CEO_REVIEW --> BRAINSTORM: 退回修改 + + PRD --> API_DESIGN: 通過 + PRD --> CEO_REVIEW: major changes + + API_DESIGN --> DB_SCHEMA: 通過 + API_DESIGN --> PRD: 需求不符 + + DB_SCHEMA --> UX_PROTOTYPE: 通過 + DB_SCHEMA --> API_DESIGN: schema衝突 + + UX_PROTOTYPE --> DESIGN_REVIEW: 完成 + UX_PROTOTYPE --> DB_SCHEMA: 資料結構不符 + + DESIGN_REVIEW --> TASK_BREAKDOWN: 通過 + DESIGN_REVIEW --> PRD: 設計不符需求 + + TASK_BREAKDOWN --> IMPLEMENTATION: 任務拆分完成 + + IMPLEMENTATION --> QA: 實作完成 + QA --> TASK_BREAKDOWN: 測試不通過 + QA --> PR_REVIEW: 測試通過 + + PR_REVIEW --> DEPLOY: 審核通過 + PR_REVIEW --> TASK_BREAKDOWN: 審核不通過 + + DEPLOY --> COMPLETED: 部署成功 + DEPLOY --> IMPLEMENTATION: 部署失敗 + + COMPLETED --> [*] +``` + +## 進度報告 + +執行 `/vibe-kanban status` 時顯示： + +``` +╔══════════════════════════════════════════════════════════════╗ +║ VIBE-KANBAN 狀態 ║ +╠══════════════════════════════════════════════════════════════╣ +║專案: feature-user-auth ║ +║ 當前階段: PRD (撰寫產品需求文件) ║ +║ 狀態: IN_PROGRESS ║ +║ ║ +║已完成階段: ║ +║ ✅ BRAINSTORM (90 分鐘) ║ +║ ✅ CEO_REVIEW (150 分鐘) ║ +║ ║ +║ 待完成階段: ║ +║ ⏳ PRD ← 你在這裡 ║ +║ ⬜ API_DESIGN ║ +║ ⬜ DB_SCHEMA ║ +║ ⬜ UX_PROTOTYPE ║ +║ ⬜ DESIGN_REVIEW ║ +║ ⬜ TASK_BREAKDOWN ║ +║ ⬜ IMPLEMENTATION ║ +║ ⬜ QA ║ +║ ⬜ PR_REVIEW ║ +║ ⬜ DEPLOY ║ +║ ║ +║產出文件: ║ +║ docs/brainstorm/2025-01-15-feature-x.md✅ ║ +║ docs/ceo-review/2025-01-15-feature-x.md ║ +║ docs/prd/ (待產出) ║ +║ ║ +║ 下一步: 執行 /pm-prd 產出PRD ║ +╚══════════════════════════════════════════════════════════════╝ +``` +``` + +--- + +## 5. 狀態機設計 + +### 5.1 階段定義 + +| 階段 | 名稱 | 觸發技能 | 輸入 | 輸出 | 失敗退回 | +|------|------|---------|------|------|---------| +| 1 | BRAINSTORM | brainstorming | 使用者想法 | brainstorm.md | - | +| 2 | CEO_REVIEW | plan-ceo-review | brainstorm.md | review-report.md |階段1 | +| 3 | PRD | pm-prd | review-report.md | prd.md | 階段2 | +| 4 | API_DESIGN | be-api-design | prd.md | api-spec.yaml | 階段3 | +| 5 | DB_SCHEMA | dba-schema | api-spec.yaml | schema.sql | 階段4 | +| 6 | UX_PROTOTYPE | ux-prototype | prd.md + api-spec.yaml + schema.sql | prototype/ | 階段5 | +| 7 | DESIGN_REVIEW | design-review | prototype/ | review-report.md | 階段3 | +| 8 | TASK_BREAKDOWN | dispatching-parallel-agents | tasks.md | task-assignments | 階段7 | +| 9 | IMPLEMENTATION | 手動 | task-assignments | code/ | 階段8 | +| 10 | QA | qa | code/ + acceptance-criteria | qa-report.md | 階段8 (步驟四) | +| 11 | PR_REVIEW | review | code/ | pr-review.md | 階段8 (步驟四) | +| 12 | DEPLOY | land-and-deploy | pr-approved | deploy-report.md | 階段9 | + +### 5.2 退回邏輯 + +```python +#退回規則 +ROLLBACK_RULES = { + "QA_FAILED": { + "from_phase": "QA", + "to_phase": "TASK_BREAKDOWN", + "reason": "測試不通過，需要重新實作" + }, + "PR_REVIEW_FAILED": { + "from_phase": "PR_REVIEW", + "to_phase": "TASK_BREAKDOWN", + "reason": "代碼審核不通過，需要修改" + }, + "DESIGN_REVIEW_FAILED": { + "from_phase": "DESIGN_REVIEW", + "to_phase": "PRD", + "reason": "設計審核不通過，需求需要調整" + }, + "DEPLOY_FAILED": { + "from_phase": "DEPLOY", + "to_phase": "IMPLEMENTATION", + "reason": "部署失敗，需要修復" + } +} +``` + +--- + +## 6. 文件結構規劃 + +``` +.gstack/ +└── kanban/ + └── {project-slug}/ + ├── state.yaml# 工作流狀態 + ├── history/ + │ ├── brainstorm-{date}.md│ ├── ceo-review-{date}.md + │ ├── prd-{date}.md + │ └── ... + └── artifacts/ + ├── prd/ + ├── api/ + ├── db/ + └── design/ + +docs/ +├── brainstorm/ +│ └── {date}-{feature}.md +├── prd/ +│ └── {date}-{feature}.md +├── api/ +│ └── {date}-{feature}.yaml +├── db/ +│ ├── {date}-{feature}.sql│ └── migrations/ +│ └── {version}-{description}.sql +├── design/ +│ └── {date}-{feature}/ +│ ├── user-flow.md +│ ├── wireframes/ +│ └── prototype-link.md +├── qa/ +│ └── qa-report-{date}.md +└── deploy/ + └── deploy-report-{date}.md + +skills/ +├── vibe-kanban/ +│ ├── SKILL.md +│ ├── references/ +│ │ └── workflow-diagram.md +│ └── templates/ +│ └── state-template.yaml +├── pm-prd/ +│ ├── SKILL.md +│ └── templates/ +│ └── prd-template.md +├── be-api-design/ +│ ├── SKILL.md +│ └── templates/ +│ └── openapi-template.yaml +├── dba-schema/ +│ ├── SKILL.md +│ └── templates/ +│ └── schema-template.sql +└── ux-prototype/ + ├── SKILL.md + └── templates/ + ├── user-flow-template.md + └── component-mapping-template.md +``` + +--- + +## 7. 實施優先順序 + +### Phase 1: 核心框架 (Week 1) + +1. **vibe-kanban 主控技能** - 最高優先級 + - 狀態機核心邏輯 + - 狀態持久化 + - 階段轉換 + +2. **pm-prd 技能** - 高優先級 + - PRD 模板 + - 驗收標準定義 + +### Phase 2: 設計階段 (Week 2) + +3. **be-api-design 技能** - 中優先級 + - API 規格產出 + - OpenAPI 模板 + +4. **dba-schema 技能** - 中優先級 + - Schema 設計 + - 遷移計畫 + +5. **ux-prototype 技能** - 中優先級 + - 使用者流程 + - 元件對應 + +### Phase 3: 整合測試 (Week 3) + +6. **整合測試** + - 完整流程演練 + - 邊界條件測試 + - 退回機制測試 + +### Phase 4: 優化 (Week 4) + +7. **性能優化** + - 並行執行優化 + - 快取策略 + +8. **文件完善** + - 使用指南 + - 最佳實踐 + +--- + +## 8. 退回機制設計 + +### 8.1 退回觸發條件 + +```yaml +# 退回觸發條件定義 +ROLLBACK_TRIGGERS: + QA: + conditions: + - 測試覆蓋率< 80% + -關鍵功能測試失敗 + - 效能未達標 + target_phase: TASK_BREAKDOWN + message: "QA 測試未通過，需要返回任務拆分階段重新實作" + + PR_REVIEW: + conditions: + - 代碼審核拒絕 + - 安全漏洞發現 + - 架構問題 + target_phase: TASK_BREAKDOWN + message: "PR 審核未通過，需要返回任務拆分階段修改" + + DESIGN_REVIEW: + conditions: + - 設計與需求不符 + - UX 問題嚴重 + - 技術不可行 + target_phase: PRD + message: "設計審核未通過，需要返回 PRD 階段重新定義需求" +``` + +### 8.2 退回後處理 + +```yaml +# 退回後的處理流程 +ROLLBACK_PROCESS: + steps: + - name: "記錄退回原因"action: "write_to_history" + data: + phase: "{from_phase}" + reason: "{reason}" + timestamp: "{ISO timestamp}" + + - name: "通知相關代理" + action: "notify_agents" + agents: + - "PM (if phase <= PRD)" + - "Backend (if phase > PRD)" + - "UX (if phase >= UX_PROTOTYPE)" + + - name: "清理階段產出" + action: "archive_artifacts" + target: "{current_phase}" + + - name: "恢復到目標階段" + action: "restore_state" + target_phase: "{target_phase}" + + - name: "重新開始" + action: "trigger_skill" + skill: "{target_skill}" +``` + +--- + +## 9. 驗收標準模板 + +### 9.1 通用驗收標準 + +```markdown +#驗收標準模板 + +## AC-001: {驗收項目名稱} + +### Given (前置條件) +- 條件 1 +- 條件 2 + +### When (觸發動作) +- 動作描述 + +### Then (預期結果) +- 結果 1 +- 結果 2 + +### 測試資訊 +- **優先級**: P0 | P1 | P2 +- **類型**: 功能性 | 非功能性 +- **自動化**: 是 | 否 +- **測試腳本**: `tests/{test-file}` + +--- + +## 驗收標準範例 + +### AC-001: 使用者登入功能 + +#### Given +- 使用者已註冊帳號 +- 登入頁面已載入 + +#### When +- 使用者輸入正確的 email 和密碼 +- 使用者點擊「登入」按鈕 + +#### Then +- 系統驗證帳號密碼 +- 使用者被導向首頁 +- Session 被建立 + +#### 測試資訊 +- **優先級**: P0 +- **類型**: 功能性 +- **自動化**: 是 +- **測試腳本**: `tests/auth/login.test.ts` +``` + +### 9.2 非功能性驗收標準 + +```markdown +# 非功能性驗收標準 + +##NFR-001: 效能 + +### 頁面載入時間 +-首頁載入 < 2 秒 (P95) +- API 回應 < 500ms (P95) + +### 測試方法 +- 使用 Lighthouse 測量 +- 使用 k6 進行負載測試 + +--- + +##NFR-002: 安全性 + +### 認證與授權 +- 所有 API 端點需驗證 +- 實作 RBAC (Role-Based Access Control) + +### 測試方法 +- OWASP ZAP 掃描 +- 滲透測試 + +--- + +##NFR-003: 可用性 + +### 正常運行時間 +- 99.9% SLA +- 計畫性維護除外 + +### 測試方法 +- 監控系統日誌 +- Uptime 監控 +``` + +--- + +## 附錄 + +### A. 相關文件連結 + +- Brainstorming 技能: `/skills/brainstorming/SKILL.md` +- CEO Review 技能: `/gstack/plan-ceo-review/SKILL.md` +- QA 技能: `/gstack/qa/SKILL.md` +- Land and Deploy 技能: `/gstack/land-and-deploy/SKILL.md` + +### B. 參考資料 + +- OpenAPI 規格: https://spec.openapis.org/oas/v3.1.0 +- Gherkin 語法: https://cucumber.io/docs/gherkin/ +- 12-Factor App: https://12factor.net/ + +### C. 版本歷史 + +| 版本 | 日期 | 變更 | +|------|------|------| +| 1.0 | 2025-01-15 | 初版規劃文件 | \ No newline at end of file diff --git a/design-idea/struct.md b/design-idea/struct.md new file mode 100644 index 0000000..0bf30c4 --- /dev/null +++ b/design-idea/struct.md @@ -0,0 +1,115 @@ +. +├── build +│   └── Dockerfile +├── docker-compose.yml +├── etc +│   └── member.example.yaml +├── generate +│   └── protobuf +│   └── member.proto +├── go.mod +├── internal +│   ├── config +│   │   └── config.go +│   ├── logic +│   │   └── account +│   │   ├── bind_account_logic.go +│   │   ├── bind_user_info_logic.go +│   │   ├── bind_verify_email_logic.go +│   │   ├── bind_verify_phone_logic.go +│   │   ├── check_refresh_code_logic.go +│   │   ├── create_user_account_logic.go +│   │   ├── generate_refresh_code_logic.go +│   │   ├── get_u_i_d_by_account_logic.go +│   │   ├── get_user_account_info_logic.go +│   │   ├── get_user_info_logic.go +│   │   ├── line_code_to_access_token_logic.go +│   │   ├── line_get_profile_by_access_token_logic.go +│   │   ├── list_member_logic.go +│   │   ├── update_status_logic.go +│   │   ├── update_user_info_logic.go +│   │   ├── update_user_token_logic.go +│   │   ├── verify_google_auth_result_logic.go +│   │   ├── verify_platform_auth_result_logic.go +│   │   └── verify_refresh_code_logic.go +│   ├── server +│   │   └── account +│   │   └── account_server.go +│   └── svc +│   └── service_context.go +├── Makefile +├── member.go +├── pkg +│   ├── domain +│   │   ├── config +│   │   │   └── config.go +│   │   ├── const.go +│   │   ├── entity +│   │   │   ├── account_uid_table.go +│   │   │   ├── account.go +│   │   │   ├── auto_id.go +│   │   │   └── user.go +│   │   ├── errors.go +│   │   ├── member +│   │   │   ├── account_type_test.go +│   │   │   ├── account_type.go +│   │   │   ├── alert_type_test.go +│   │   │   ├── alert_type.go +│   │   │   ├── generate_code_type_test.go +│   │   │   ├── generate_code_type.go +│   │   │   ├── platform_test.go +│   │   │   ├── platform.go +│   │   │   ├── status_test.go +│   │   │   └── status.go +│   │   ├── redis.go +│   │   ├── repository +│   │   │   ├── account_uid.go +│   │   │   ├── account.go +│   │   │   ├── auto_id.go +│   │   │   ├── user.go +│   │   │   └── verify_code.go +│   │   └── usecase +│   │   ├── account.go +│   │   ├── common.go +│   │   ├── generate_uid.go +│   │   └── verify.go +│   ├── mock +│   │   ├── repository +│   │   │   ├── account_uid.go +│   │   │   ├── account.go +│   │   │   ├── auto_id.go +│   │   │   ├── user.go +│   │   │   └── verify_code.go +│   │   └── usecase +│   │   └── generate_uid.go +│   ├── repository +│   │   ├── account_test.go +│   │   ├── account_uid_test.go +│   │   ├── account_uid.go +│   │   ├── account.go +│   │   ├── auto_id_test.go +│   │   ├── auto_id.go +│   │   ├── error.go +│   │   ├── start_mongo_container_test.go +│   │   ├── user_test.go +│   │   ├── user.go +│   │   ├── verify_code_test.go +│   │   └── verify_code.go +│   └── usecase +│   ├── account.go +│   ├── binding_test.go +│   ├── binding.go +│   ├── generate_test.go +│   ├── generate_verify_code_utils_test.go +│   ├── generate_verify_code_utils.go +│   ├── generate.go +│   ├── member_test.go +│   ├── member.go +│   ├── password_utils_test.go +│   ├── password_utils.go +│   ├── verify_google_test.go +│   ├── verify_google.go +│   ├── verify_line.go +│   ├── verify_test.go +│   └── verify.go +└── readme.md \ No newline at end of file diff --git a/design-idea/translate/agents/backend-agent.md b/design-idea/translate/agents/backend-agent.md new file mode 100644 index 0000000..a0d0d1f --- /dev/null +++ b/design-idea/translate/agents/backend-agent.md @@ -0,0 +1,109 @@ +# Backend Agent (Golang 後端工程師) + +## 角色定位 + +**Golang 後端工程師** — 負責 API 設計、伺服器端實作，確保高品質、可測試的 Golang 程式碼，遵循 Domain-Driven + go-zero 風格架構。 + +## 核心職責 + +1. **API 規格** — 根據 PRD 設計 RESTful API，產出 OpenAPI 3.0 規格 +2. **領域建模** — 定義領域實體、值物件和業務規則，與 PRD 和 DB Schema 對齊 +3. **核心實作** — 遵循 Domain-Driven 架構建構伺服器端邏輯（pkg/domain 定義 → pkg/usecase 實作 → internal/logic handler → pkg/repository 基礎設施） +4. **品質確保 (TDD)** — 使用測試驅動開發實作功能，確保高覆蓋率和可靠性 +5. **跨團隊協作** — 與 DBA Agent 同步 Schema 設計、UX Agent 進行 API 整合、QA Agent 確認可測試性 + +## 使用技能 + +| 階段 | 技能 | 輔助 | 輸入 | 輸出 | +|-------|-------|-----------|-------|--------| +| 4: API 設計 | `be-api-design` | `design-an-interface` | PRD | `docs/api/{date}-{feature}.yaml` | +| 5: DB Schema | 與 DBA Agent 協作 | - | API 規格 + 領域模型 | 對齊確認 | +| 8: 任務分解 | 檢視 Orchestrator 計畫 | - | `./plans/{feature}.md` | 可行性確認 | +| 9: 實作 | `go-backend-dev` | `tdd` | 計畫 + API 規格 + DB Schema | 生產級 Go 程式碼 | +| 10: QA 支援 | Bug 修復支援 | - | QA 回報 | Bug 修復 + 回歸測試 | +| 11: Code Review | 回應 PR 回饋 | - | 審查意見 | 程式碼變更 | + +## 工作原則 + +1. **API-First 設計** — 先定義 API 合約（OpenAPI）再寫實作程式碼 +2. **Domain-Driven 架構** — `pkg/domain/` 包含純抽象（實體、值物件、介面），`pkg/usecase/` 和 `pkg/repository/` 包含實作，`internal/logic/` 和 `internal/svc/` 處理組裝 +3. **測試驅動開發** — 先寫測試（Red），再實作（Green），然後重構 +4. **垂直切片** — 一次實作一個端到端切片，不要逐層實作 +5. **錯誤透明** — 立即檢查每個錯誤；使用 `fmt.Errorf` 搭配 `%w` 包裝 +6. **介面隔離** — 保持介面小型（1-3 個方法）；在消費處定義介面 + +## 回滾機制 + +``` +設計審查駁回 API 規格 (Stage 7) + → 修改 OpenAPI 規格（技能：be-api-design + design-an-interface） + → 如需變更 Schema，與 DBA Agent 協調 + +QA 失敗 (Stage 10) + → 回滾到 Stage 8（任務分解） + → 修復 Bug + 新增回歸測試 + → 重新進入 Stage 10 + +Code Review 失敗 (Stage 11) + → 處理 PR 回饋 + → 重新進入 Stage 10 驗證 + +DBA/UX 衝突 + → 與 DBA Agent 協調：調整領域模型或 API + → 與 UX Agent 協調：調整 API 回應或請求格式 +``` + +## 與其他 Agent 協作 + +``` +Backend Agent ← PM Agent：接收 PRD 和非功能性需求 +Backend Agent ←→ DBA Agent：對齊 API 資源與資料庫 Schema（Stage 5） +Backend Agent ←→ UX Agent：確保 API 回應符合原型需求（Stage 6） +Backend Agent ← 設計審查者：接收設計回饋，修改 API 規格（Stage 7） +Backend Agent ← Orchestrator：接收實作計畫（Stage 8） +Backend Agent → QA Agent：提供可測試程式碼和 API 文件（Stage 10） +Backend Agent ← Code Reviewer：實作 PR 審查的回饋（Stage 11） +``` + +## 決策權限 + +- 定義後端內部技術結構（套件、層級） +- 在批准的技術堆疊中選擇特定 Go 函式庫 +- 決定 API 端點粒度和資源建模 +- 設定內部測試策略（單元、整合、E2E 邊界） +- 決定錯誤處理模式和回應格式 + +## 交付物檢查清單 + +### Stage 4: API 設計 +- [ ] OpenAPI 3.0 規格儲存至 `docs/api/` +- [ ] PRD 所有功能需求映射至端點 +- [ ] `design-an-interface` 替代方案已記錄 + +### Stage 5: DB 協作 +- [ ] 領域模型與 DB Schema 對齊 +- [ ] Repository 介面在 proposed schema 下可行 + +### Stage 9: 實作 +- [ ] Domain-Driven 架構結構完整（pkg/domain, pkg/usecase, internal/logic, pkg/repository） +- [ ] 所有層級已實作 +- [ ] 單元測試 >= 80%，業務邏輯 >= 90% +- [ ] 關鍵路徑整合測試通過 + +### Stage 10-11: QA 與 Code Review +- [ ] 所有 QA 回報的 Bug 已修復並有回歸測試 +- [ ] PR 審查回饋已處理 + +## 常見問題處理 + +**Q: PRD 需求技術上不可行？** +A: 在 API 規格中記錄限制，提出替代方案，上報 PM Agent 調整範圍。 + +**Q: API 設計與 DB Schema 衝突？** +A: 與 DBA Agent 協調。優先改變映射層而非修改 DB Schema。 + +**Q: 發現效能瓶頸？** +A: 加入快取（Redis），與 DBA Agent 優化查詢，考慮對長時操作使用非同步。 + +**Q: 測試覆蓋率低於 80%？** +A: 優先測試 usecase 層，使用表格驅動測試處理邊緣案例，為關鍵流程加入整合測試。 \ No newline at end of file diff --git a/design-idea/translate/agents/pm-agent.md b/design-idea/translate/agents/pm-agent.md new file mode 100644 index 0000000..37b7d7e --- /dev/null +++ b/design-idea/translate/agents/pm-agent.md @@ -0,0 +1,146 @@ +# PM Agent (Product Manager) + +## 角色定位 + +**產品經理** — 負責需求探索、PRD 撰寫和產品規劃。 + +## 核心職責 + +1. **需求探索** — 透過訪談了解使用者需求 +2. **PRD 撰寫** — 產出結構化的產品需求文件（包含功能與非功能性需求） +3. **使用者故事** — 定義清晰的使用者故事 +4. **驗收標準** — 設定可測試的驗收標準 +5. **優先排序** — 對功能和需求進行優先排序 + +## 使用技能 + +### Stage 1: 腦力激盪 +- **技能**: `brainstorming` +- **輸入**: 使用者最初的的想法 +- **輸出**: `docs/brainstorm/{date}-{feature}-design.md` +- **內容**: + - 問題陳述 + - 目標使用者 + - 功能列表 + - 技術建議 + +### Stage 3: PRD 撰寫 +- **技能**: `write-a-prd` +- **輸入**: CEO 審查結果 +- **輸出**: `docs/prd/{date}-{feature}.md` +- **內容**: + - 問題陳述 + - 解決方案 + - 使用者故事（詳細列表） + - 實作決策 + - 測試決策 + - 非功能性需求（效能、安全等） + - 範圍外 + +### Stage 3.5: 深度驗證 (Grill-Me) +- **技能**: `grill-me` +- **觸發時機**: PRD 初稿完成後主動啟用以確保無遺漏 +- **輸入**: PRD 初稿 +- **驗證項目**: + - 每個功能需求的完整性 + - 使用者故事的邊緣案例 + - 非功能性需求的遺漏（重要） + - 驗收標準的可測試性 +- **輸出**: 增強後的 PRD + +## PRD 模板結構 + +```markdown +# PRD: {feature_name} + +## Metadata +- Date: {date} +- Status: Draft | Review | Approved +- Author: PM Agent + +## Problem Statement +{problem_description} + +## Solution +{solution} + +## User Stories +1. As a {role}, I want {feature}, so that {benefit} +2. ... + +## Implementation Decisions +- {technical_decisions} +- {architecture_decisions} + +## Testing Decisions +- {testing_strategy} +- {priority_test_items} + +## Non-Functional Requirements +### NFR-001: Performance +- Description: (e.g., Response time < 200ms, Supports 100 concurrency) +- Measurement: +### NFR-002: Reliability/Security +- Description: +- Measurement: + +## Out of Scope +- {omitted_features} + +## Functional Requirements +### FR-001: {requirement_title} +- Description: +- Priority: P0 | P1 | P2 +- User Stories: + +## Acceptance Criteria +### AC-001: {acceptance_item} +- Given: +- When: +- Then: +- Automated: Yes/No +``` + +## 工作原則 + +1. **以使用者為中心** — 所有需求從使用者視角出發 +2. **清晰且具體** — 避免模糊描述，致力於可執行性 +3. **完整覆蓋** — 考慮正常流程、例外情況和非功能性限制 +4. **可測試性** — 每個需求都應有清晰的驗收標準 +5. **迭代精煉** — 定稿前必須透過 `grill-me` 進行深度驗證 + +## 與其他 Agent 協作 + +``` +PM Agent ←→ CEO 審查者：接收審查回饋，調整範圍 +PM Agent → Backend Agent：提供 PRD 進行 API 設計 +PM Agent → UX Agent：提供需求進行原型設計 +PM Agent → QA Agent：提供驗收標準進行測試 +``` + +## 決策權限 + +- 定義產品功能和範圍 +- 設定需求優先順序 +- 決定驗收標準 +- 建議技術解決方案（非最終決定） + +## 交付物檢查清單 + +- [ ] 腦力激盪文件已完成於 `docs/brainstorm/` +- [ ] PRD 文件已完成於 `docs/prd/` +- [ ] 使用者故事清晰且完整 +- [ ] 驗收標準可測試 +- [ ] 非功能性需求（NFR）明確定義且可衡量 +- [ ] Grill-me 深度驗證已完成 + +## 常見問題處理 + +**Q: 使用者需求不清楚？** +A: 使用腦力激盪技能進行多輪訪談，直到需求清楚。 + +**Q: 技術可行性存疑？** +A: 在實作決策中標記風險，與 Backend Agent 討論。 + +**Q: 範圍太大？** +A: 與 CEO 審查者協助拆分為多個階段，定義 MVP。 \ No newline at end of file diff --git a/design-idea/translate/skills/be-api-design/SKILL.md b/design-idea/translate/skills/be-api-design/SKILL.md new file mode 100644 index 0000000..eca89b4 --- /dev/null +++ b/design-idea/translate/skills/be-api-design/SKILL.md @@ -0,0 +1,532 @@ +--- +name: be-api-design +description: "Backend Agent 使用此技能設計 API 規格。根據 PRD 產出 OpenAPI 3.0 規格，包含端點、請求/回應結構、錯誤處理。觸發時機：PRD 通過後（Stage 4）。" +--- + +# /be-api-design — API 設計 + +Backend Agent 使用此技能設計 API 規格。 + +## 職責 + +1. 分析 PRD 中的功能性需求 +2. 使用 `design-an-interface` 探索多種 API 設計方案 +3. 設計 RESTful API 端點 +4. 定義請求/回應 schema +5. 設計錯誤處理機制 +6. 產出 OpenAPI 3.0 規格 + +## 輸入 + +- PRD 文件 (`docs/prd/{date}-{feature}.md`) +- 現有 API 風格 (專案中現有的 API 規格) +- 資料模型上下文 + +## 輸出 + +- API 規格文件: `docs/api/{date}-{feature}.yaml` (OpenAPI 3.0) + +## 流程 + +``` +讀取 PRD + ↓ +識別資源與操作 + ↓ +呼叫 design-an-interface 探索 2-3 種設計方案 + ↓ +選定最佳方案 + ↓ +定義 OpenAPI Schema + ↓ +設計錯誤處理 + ↓ +安全性審查 + ↓ +產出 OpenAPI 文件 +``` + +### 步驟說明 + +**1. 讀取 PRD** + +從 PRD 中提取所有功能性需求，識別： +- 資源（名詞）：使用者、訂單、商品等 +- 操作（動詞）：建立、讀取、更新、刪除等 +- 關係：資源之間的關聯（一對多、多對多） +- 非功能性需求：分頁、速率限制、認證等 + +**2. 識別資源與操作** + +將功能性需求映射為 RESTful 資源： +- 每個名詞 → 潛在資源 +- 每個動詞 → HTTP method +- 每個關係 → 巢狀資源或獨立端點 + +**3. 呼叫 design-an-interface** + +使用 `design-an-interface` 技能，產生 2-3 種截然不同的 API 設計方案： +- 方案 A：最小化方法數（每個資源 1-3 個端點） +- 方案 B：最大化彈性（支援多種使用情境） +- 方案 C：最佳化最常見的操作 + +比較各方案的優劣，選定最佳設計。 + +**4. 定義 OpenAPI Schema** + +使用下方模板產出完整的 OpenAPI 3.0 規格。 + +**5. 安全性審查** + +確認所有端點都有適當的認證機制和權限控制。 + +**6. 產出文件** + +儲存至 `docs/api/{date}-{feature}.yaml`。 + +## 設計原則 + +### RESTful 設計 + +```yaml +資源導向: + - URL 代表資源，而非動作 + - HTTP 方法代表動作 + +範例: + GET /api/v1/users # 列出使用者 + GET /api/v1/users/{id} # 取得特定使用者 + POST /api/v1/users # 建立使用者 + PUT /api/v1/users/{id} # 完整更新 + PATCH /api/v1/users/{id} # 部分更新 + DELETE /api/v1/users/{id} # 刪除使用者 + +巢狀資源: + GET /api/v1/users/{id}/orders # 取得使用者的訂單 + POST /api/v1/users/{id}/orders # 為使用者建立訂單 +``` + +### HTTP 狀態碼 + +```yaml +成功: + 200: OK # GET, PUT, PATCH, DELETE 成功 + 201: Created # POST 成功建立資源 + 204: No Content # DELETE 成功，無回應內容 + +客戶端錯誤: + 400: Bad Request # 請求格式錯誤 + 401: Unauthorized # 未認證 + 403: Forbidden # 無權限 + 404: Not Found # 資源不存在 + 409: Conflict # 資源衝突 (如重複) + 422: Unprocessable Entity # 驗證錯誤 + 429: Too Many Requests # 速率限制 + +伺服器錯誤: + 500: Internal Server Error # 伺服器內部錯誤 + 502: Bad Gateway # 上游服務錯誤 + 503: Service Unavailable # 服務暫時不可用 +``` + +### 回應格式 + +```yaml +成功回應: + type: object + properties: + data: + type: object + meta: + type: object + properties: + page: + type: integer + limit: + type: integer + total: + type: integer + total_pages: + type: integer + +錯誤回應: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + details: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string +``` + +## OpenAPI 3.0 模板 + +```yaml +openapi: 3.0.3 +info: + title: {API 名稱} + version: 1.0.0 + description: | + {描述} + + Related PRD: {PRD 連結} + +servers: + - url: https://api.example.com/v1 + description: Production + - url: https://staging-api.example.com/v1 + description: Staging + +paths: + /users: + get: + summary: 列出使用者 + tags: + - Users + parameters: + - name: page + in: query + schema: + type: integer + default: 1 + - name: limit + in: query + schema: + type: integer + default: 20 + maximum: 100 + - name: search + in: query + schema: + type: string + responses: + '200': + description: 成功 + content: + application/json: + schema: + $ref: '#/components/schemas/UserListResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '500': + $ref: '#/components/responses/InternalError' + + post: + summary: 建立使用者 + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserRequest' + responses: + '201': + description: 建立成功 + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/ValidationError' + + /users/{id}: + parameters: + - name: id + in: path + required: true + schema: + type: string + + get: + summary: 取得使用者 + tags: + - Users + responses: + '200': + description: 成功 + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '404': + $ref: '#/components/responses/NotFound' + + put: + summary: 完整更新使用者 + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserRequest' + responses: + '200': + description: 更新成功 + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/ValidationError' + + patch: + summary: 部分更新使用者 + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PatchUserRequest' + responses: + '200': + description: 更新成功 + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '404': + $ref: '#/components/responses/NotFound' + + delete: + summary: 刪除使用者 + tags: + - Users + responses: + '204': + description: 刪除成功 + '404': + $ref: '#/components/responses/NotFound' + +components: + schemas: + User: + type: object + properties: + id: + type: string + example: "usr_123456" + email: + type: string + format: email + example: "user@example.com" + name: + type: string + example: "John Doe" + status: + type: string + enum: [active, inactive, suspended] + example: "active" + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + required: + - id + - email + - name + - status + - created_at + - updated_at + + CreateUserRequest: + type: object + properties: + email: + type: string + format: email + password: + type: string + minLength: 8 + name: + type: string + minLength: 1 + maxLength: 100 + required: + - email + - password + - name + + UpdateUserRequest: + type: object + properties: + email: + type: string + format: email + name: + type: string + minLength: 1 + maxLength: 100 + status: + type: string + enum: [active, inactive] + + PatchUserRequest: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + status: + type: string + enum: [active, inactive] + + UserResponse: + type: object + properties: + data: + $ref: '#/components/schemas/User' + + UserListResponse: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/User' + meta: + type: object + properties: + page: + type: integer + limit: + type: integer + total: + type: integer + total_pages: + type: integer + + Error: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + details: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + + responses: + BadRequest: + description: 請求格式錯誤 + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + Unauthorized: + description: 未認證 + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + NotFound: + description: 資源不存在 + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + ValidationError: + description: 驗證錯誤 + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + InternalError: + description: 伺服器內部錯誤 + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + +security: + - bearerAuth: [] +``` + +## 設計檢查清單 + +### 安全性 +- [ ] 所有端點都有適當的認證機制 +- [ ] 輸入驗證完整 +- [ ] 速率限制設計 +- [ ] CORS 配置 + +### 效能 +- [ ] 分頁支援 +- [ ] 快取策略 +- [ ] 批次操作支援 + +### 可靠性 +- [ ] 錯誤回應格式統一 +- [ ] 重試機制建議 +- [ ] 冪等性設計 + +### 一致性 +- [ ] 命名規範一致 (資源用名詞複數) +- [ ] 回應格式一致 (data/meta/error 結構) +- [ ] 篩選/排序/分頁參數一致 + +## 相依技能 + +- **前置**: `write-a-prd` (PRD 通過後) +- **輔助**: `design-an-interface` (探索多種設計方案) +- **後續**: `dba-schema` (DB Schema 設計) +- **退回**: 可退回 `write-a-prd` 修改需求 + +## 退回機制 + +``` +Design Review 退回 API 設計 + ↓ +修改 OpenAPI 規格 + ↓ +重新提交 (或重新呼叫 design-an-interface) + +DBA Agent 發現 Schema 衝突 + ↓ +協商調整 domain model 或 API 回應格式 + ↓ +更新 OpenAPI 規格 +``` diff --git a/design-idea/translate/skills/design-an-interface/SKILL.md b/design-idea/translate/skills/design-an-interface/SKILL.md new file mode 100644 index 0000000..1f3891d --- /dev/null +++ b/design-idea/translate/skills/design-an-interface/SKILL.md @@ -0,0 +1,188 @@ +--- +name: design-an-interface +description: "Backend Agent 使用此技能探索多種 API 介面設計方案。根據「Design It Twice」原則，產生多種截然不同的設計，比較後選擇最佳方案。觸發時機：API 設計階段（Stage 4），由 be-api-design 技能呼叫。" +--- + +# /design-an-interface — 介面設計探索 + +Backend Agent 使用此技能探索 API 介面設計方案。 + +基於 "A Philosophy of Software Design" 的 "Design It Twice" 原則：第一個想法通常不是最好的。產生多種截然不同的設計，然後比較選擇。 + +## 職責 + +1. 針對模組需求，產生 2-3 種截然不同的介面設計方案 +2. 每種方案使用不同的設計約束 +3. 比較方案的優劣 +4. 協助選擇或合成最佳方案 + +## 輸入 + +- 模組描述（來自 PRD 的功能性需求） +- 使用者故事和操作場景 + +## 輸出 + +- 多種介面設計方案（含介面簽名、使用範例、優劣分析） +- 方案比較和建議 + +## 流程 + +``` +收集需求 + ↓ +產生 2-3 種設計方案（平行子代理） + ↓ +呈現各方案 + ↓ +比較方案（介面簡潔性、通用性、實作效率、深度） + ↓ +合成最佳方案或選擇最適方案 +``` + +### 步驟說明 + +**1. 收集需求** + +在設計之前，先了解： +- [ ] 這個模組解決什麼問題？ +- [ ] 誰是呼叫者？（其他模組、外部使用者、測試） +- [ ] 關鍵操作有哪些？ +- [ ] 有什麼限制？（效能、相容性、現有模式） +- [ ] 什麼應該隱藏在內部？什麼應該暴露在外？ + +提問：「這個模組需要做什麼？誰會使用它？」 + +**2. 產生設計方案（平行子代理）** + +同時產生 3+ 種截然不同的方案。每個方案必須遵循不同的約束： + +``` +方案 A：最小化方法數 — 目標 1-3 個方法 +方案 B：最大化彈性 — 支援多種使用情境 +方案 C：最佳化最常見操作 +方案 D（可選）：參考特定範式或框架的設計 +``` + +每個方案需包含： +1. 介面簽名（types / methods） +2. 使用範例（呼叫者如何使用） +3. 這個設計隱藏了什麼複雜度 +4. 這個方案的取捨 + +**3. 呈現方案** + +逐一展示每個方案，包含： +- 介面簽名：types, methods, params +- 使用範例：呼叫者如何實際使用 +- 隱藏的複雜度：小介面隱藏大量實作（好）vs 大介面薄實作（差） + +讓使用者充分吸收每個方案後再進行比較。 + +**4. 比較方案** + +依以下維度比較： + +- **介面簡潔性**：方法少、參數簡單 → 更容易學習和正確使用 +- **通用性 vs 專用性**：彈性 vs 專注，取捨在哪 +- **實作效率**：介面形狀是否允許高效內部實作？ +- **深度**：小介面隱藏大量複雜度（深模組，好）vs 大介面薄實作（淺模組，差） +- **正確使用的容易度 vs 誤用的容易度** + +用文字討論取捨，不要只用表格。強調方案分歧最大的地方。 + +**5. 合成最佳方案** + +最佳設計往往結合多個方案的洞見。詢問： +- 「哪個方案最適合你的主要使用情境？」 +- 「其他方案有沒有值得納入的元素？」 + +## 評估標準 + +來自 "A Philosophy of Software Design"： + +**介面簡潔性**：方法少、參數簡單 = 更容易學習和正確使用。 + +**通用性**：能否處理未來的使用情境而不需要修改。但要避免過度通用。 + +**實作效率**：介面形狀是否允許高效實作？還是迫使內部實作變得彆扭？ + +**深度**：小介面隱藏大量複雜度 = 深模組（好）。大介面薄實作 = 淺模組（避免）。 + +``` +深模組（好）: +┌─────────────────────┐ +│ Small Interface │ ← 方法少，參數簡單 +├─────────────────────┤ +│ │ +│ │ +│ Deep Implementation│ ← 複雜邏輯隱藏在內部 +│ │ +│ │ +└─────────────────────┘ + +淺模組（避免）: +┌─────────────────────────────────┐ +│ Large Interface │ ← 方法多，參數複雜 +├─────────────────────────────────┤ +│ Thin Implementation │ ← 只是穿隧 +└─────────────────────────────────┘ +``` + +## 反模式 + +- 不要讓子代理產生相似的設計 — 強制截然不同 +- 不要跳過比較 — 價值在於對比 +- 不要在此階段實作 — 這純粹是介面設計 +- 不要基於實作工作量評價方案 — 只看介面品質 + +## Golang 介面設計範例 + +```go +// 方案 A: 最小化方法數 +type UserRepository interface { + GetByID(ctx context.Context, id string) (*domain.User, error) + Save(ctx context.Context, user *domain.User) error +} +// 優點：簡潔，容易實作 mock +// 缺點：Save 同時處理 Create 和 Update，取決於是否已存在 + +// 方案 B: 分離讀寫 +type UserReader interface { + GetByID(ctx context.Context, id string) (*domain.User, error) + List(ctx context.Context, page, limit int) ([]*domain.User, error) +} + +type UserWriter interface { + Create(ctx context.Context, user *domain.User) error + Update(ctx context.Context, user *domain.User) error + Delete(ctx context.Context, id string) error +} +// 優點：CQRS 友好，職責分離 +// 缺點：方法數較多，但每個方法語意更清楚 + +// 方案 C: 最佳化常見操作 +type UserService interface { + Register(ctx context.Context, email, password, name string) (*domain.User, error) + Authenticate(ctx context.Context, email, password string) (*domain.User, error) + GetProfile(ctx context.Context, id string) (*domain.User, error) +} +// 優點：直接對應業務操作，使用最直覺 +// 缺點：每個新操作都要加方法，彈性較低 +``` + +## 與 be-api-design 的整合 + +此技能由 `be-api-design` 在步驟 3 自動呼叫。API 設計流程： + +``` +be-api-design 步驟 1: 讀取 PRD +be-api-design 步驟 2: 識別資源與操作 +→ design-an-interface: 探索 2-3 種 API 設計方案 +be-api-design 步驟 4: 選定方案，定義 OpenAPI 規格 +``` + +## 相依技能 + +- **前置**: `write-a-prd` (PRD 完成) +- **後續**: `be-api-design` (API 規格定義) diff --git a/design-idea/translate/skills/design-patterns/abstract-factory/SKILL.md b/design-idea/translate/skills/design-patterns/abstract-factory/SKILL.md new file mode 100644 index 0000000..ab21436 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/abstract-factory/SKILL.md @@ -0,0 +1,15 @@ +# 抽象工厂模式 + +## 描述 +提供一个创建相关或依赖对象的接口，而无需指定它们具体的类。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[抽象工厂模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/abstract-factory) diff --git a/design-idea/translate/skills/design-patterns/adapter/SKILL.md b/design-idea/translate/skills/design-patterns/adapter/SKILL.md new file mode 100644 index 0000000..4e1891e --- /dev/null +++ b/design-idea/translate/skills/design-patterns/adapter/SKILL.md @@ -0,0 +1,15 @@ +# 适配器模式 + +## 描述 +在两个不兼容的接口之间起到桥梁作用。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[适配器模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/adapter) diff --git a/design-idea/translate/skills/design-patterns/bridge/SKILL.md b/design-idea/translate/skills/design-patterns/bridge/SKILL.md new file mode 100644 index 0000000..4e4330d --- /dev/null +++ b/design-idea/translate/skills/design-patterns/bridge/SKILL.md @@ -0,0 +1,15 @@ +# 桥接模式 + +## 描述 +将抽象部分与实现部分分离，使它们可以独立变化。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[桥接模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/bridge) diff --git a/design-idea/translate/skills/design-patterns/builder/SKILL.md b/design-idea/translate/skills/design-patterns/builder/SKILL.md new file mode 100644 index 0000000..f56b8e6 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/builder/SKILL.md @@ -0,0 +1,15 @@ +# 生成器模式 + +## 描述 +将复杂对象的构建与其表示分离，使得同样的构建过程可以创建不同的表示。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[生成器模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/builder) diff --git a/design-idea/translate/skills/design-patterns/chain-of-responsibility/SKILL.md b/design-idea/translate/skills/design-patterns/chain-of-responsibility/SKILL.md new file mode 100644 index 0000000..be246dd --- /dev/null +++ b/design-idea/translate/skills/design-patterns/chain-of-responsibility/SKILL.md @@ -0,0 +1,15 @@ +# 责任链模式 + +## 描述 +使多个对象可以处理同一个请求。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[责任链模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/chain-of-responsibility) diff --git a/design-idea/translate/skills/design-patterns/command/SKILL.md b/design-idea/translate/skills/design-patterns/command/SKILL.md new file mode 100644 index 0000000..6f5db5f --- /dev/null +++ b/design-idea/translate/skills/design-patterns/command/SKILL.md @@ -0,0 +1,15 @@ +# 命令模式 + +## 描述 +将一个请求封装为一个对象，从而可以用不同的请求对客户进行参数化。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[命令模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/command) diff --git a/design-idea/translate/skills/design-patterns/composite/SKILL.md b/design-idea/translate/skills/design-patterns/composite/SKILL.md new file mode 100644 index 0000000..e104a7c --- /dev/null +++ b/design-idea/translate/skills/design-patterns/composite/SKILL.md @@ -0,0 +1,15 @@ +# 组合模式 + +## 描述 +将对象组合成树形结构以表示"部分-整体"层次结构。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[组合模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/composite) diff --git a/design-idea/translate/skills/design-patterns/decorator/SKILL.md b/design-idea/translate/skills/design-patterns/decorator/SKILL.md new file mode 100644 index 0000000..81edc13 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/decorator/SKILL.md @@ -0,0 +1,15 @@ +# 装饰模式 + +## 描述 +动态地给一个对象添加一些额外的职责。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[装饰模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/decorator) diff --git a/design-idea/translate/skills/design-patterns/facade/SKILL.md b/design-idea/translate/skills/design-patterns/facade/SKILL.md new file mode 100644 index 0000000..a33f7da --- /dev/null +++ b/design-idea/translate/skills/design-patterns/facade/SKILL.md @@ -0,0 +1,15 @@ +# 外观模式 + +## 描述 +提供一个统一的界面，以隐藏复杂子系统的实现细节。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[外观模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/facade) diff --git a/design-idea/translate/skills/design-patterns/factory-method/SKILL.md b/design-idea/translate/skills/design-patterns/factory-method/SKILL.md new file mode 100644 index 0000000..5063a38 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/factory-method/SKILL.md @@ -0,0 +1,15 @@ +# 工厂方法模式 + +## 描述 +定义一个创建对象的接口，但让子类决定实例化哪个类。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[工厂方法模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/factory-method) diff --git a/design-idea/translate/skills/design-patterns/flyweight/SKILL.md b/design-idea/translate/skills/design-patterns/flyweight/SKILL.md new file mode 100644 index 0000000..9924d91 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/flyweight/SKILL.md @@ -0,0 +1,15 @@ +# 享元模式 + +## 描述 +通过共享公共部分来支持大量细粒度对象的高效创建和使用。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[享元模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/flyweight) diff --git a/design-idea/translate/skills/design-patterns/iterator/SKILL.md b/design-idea/translate/skills/design-patterns/iterator/SKILL.md new file mode 100644 index 0000000..1673d77 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/iterator/SKILL.md @@ -0,0 +1,15 @@ +# 迭代器模式 + +## 描述 +提供一种方法顺序访问一个聚合对象中的元素，而无需公开其内部表示。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[迭代器模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/iterator) diff --git a/design-idea/translate/skills/design-patterns/mediator/SKILL.md b/design-idea/translate/skills/design-patterns/mediator/SKILL.md new file mode 100644 index 0000000..18b336c --- /dev/null +++ b/design-idea/translate/skills/design-patterns/mediator/SKILL.md @@ -0,0 +1,15 @@ +# 中介者模式 + +## 描述 +用一个中介对象来封装一系列类的交互。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[中介者模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/mediator) diff --git a/design-idea/translate/skills/design-patterns/memento/SKILL.md b/design-idea/translate/skills/design-patterns/memento/SKILL.md new file mode 100644 index 0000000..b58b1a0 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/memento/SKILL.md @@ -0,0 +1,15 @@ +# 备忘录模式 + +## 描述 +在不破坏封装性的前提下，捕获一个对象的内部状态，以便该对象可以在以后恢复到原先状态。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[备忘录模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/memento) diff --git a/design-idea/translate/skills/design-patterns/observer/SKILL.md b/design-idea/translate/skills/design-patterns/observer/SKILL.md new file mode 100644 index 0000000..963fd02 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/observer/SKILL.md @@ -0,0 +1,15 @@ +# 观察者模式 + +## 描述 +定义一种一对多的依赖关系，当一个对象的状态发生改变时，所有依赖于它的对象都得到通知并自动更新。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[观察者模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/observer) diff --git a/design-idea/translate/skills/design-patterns/prototype/SKILL.md b/design-idea/translate/skills/design-patterns/prototype/SKILL.md new file mode 100644 index 0000000..fe4f223 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/prototype/SKILL.md @@ -0,0 +1,15 @@ +# 原型模式 + +## 描述 +使用一个原型实例来创建其他实例。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[原型模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/prototype) diff --git a/design-idea/translate/skills/design-patterns/proxy/SKILL.md b/design-idea/translate/skills/design-patterns/proxy/SKILL.md new file mode 100644 index 0000000..93ca580 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/proxy/SKILL.md @@ -0,0 +1,15 @@ +# 代理模式 + +## 描述 +为其他对象提供一个代理以控制对这个对象的访问。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[代理模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/proxy) diff --git a/design-idea/translate/skills/design-patterns/singleton/SKILL.md b/design-idea/translate/skills/design-patterns/singleton/SKILL.md new file mode 100644 index 0000000..7140590 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/singleton/SKILL.md @@ -0,0 +1,15 @@ +# 单例模式 + +## 描述 +确保一个类只有一个实例，并提供一个全局访问点。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[单例模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/singleton) diff --git a/design-idea/translate/skills/design-patterns/state/SKILL.md b/design-idea/translate/skills/design-patterns/state/SKILL.md new file mode 100644 index 0000000..2348ef0 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/state/SKILL.md @@ -0,0 +1,15 @@ +# 状态模式 + +## 描述 +允许一个对象在内部状态改变时改变它的行为。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[状态模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/state) diff --git a/design-idea/translate/skills/design-patterns/strategy/SKILL.md b/design-idea/translate/skills/design-patterns/strategy/SKILL.md new file mode 100644 index 0000000..edde371 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/strategy/SKILL.md @@ -0,0 +1,15 @@ +# 策略模式 + +## 描述 +定义一系列算法，把它们一个个封装起来，并且使它们可以相互替换。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[策略模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/strategy) diff --git a/design-idea/translate/skills/design-patterns/template-method/SKILL.md b/design-idea/translate/skills/design-patterns/template-method/SKILL.md new file mode 100644 index 0000000..4e55ec3 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/template-method/SKILL.md @@ -0,0 +1,15 @@ +# 模板方法模式 + +## 描述 +定义一个操作的骨架，而将一些步骤延迟到子类中。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[模板方法模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/template-method) diff --git a/design-idea/translate/skills/design-patterns/visitor/SKILL.md b/design-idea/translate/skills/design-patterns/visitor/SKILL.md new file mode 100644 index 0000000..ce68fa3 --- /dev/null +++ b/design-idea/translate/skills/design-patterns/visitor/SKILL.md @@ -0,0 +1,15 @@ +# 访问者模式 + +## 描述 +在不改变元素类的前提下，定义作用于这些元素的新操作。 + +## 使用场景 +当你需要解决代码中关于该模式所描述的设计问题时，请加载此技能。 + +## 指导原则 +1. 分析当前代码结构是否符合该模式的意图。 +2. 遵循该模式的典型结构进行重构或实现。 +3. 确保模式的引入降低了耦合度或提高了灵活性。 + +## 详细参考 +更多详细信息、图解及代码示例请参考：[访问者模式 - RefactoringGuru](https://refactoringguru.cn/design-patterns/visitor) diff --git a/design-idea/translate/skills/go-backend-dev/SKILL.md b/design-idea/translate/skills/go-backend-dev/SKILL.md new file mode 100644 index 0000000..b104009 --- /dev/null +++ b/design-idea/translate/skills/go-backend-dev/SKILL.md @@ -0,0 +1,813 @@ +--- +name: go-backend-dev +description: "Backend Agent 使用此技能實作 Golang 後端。根據實作計畫和 API 規格，使用 Domain-Driven + go-zero 風格架構和 TDD 流程產出 production-ready 程式碼。觸發時機：Task Breakdown 完成後（Stage 9）。" +--- + +# /go-backend-dev — Golang 後端實作 + +Backend Agent 使用此技能實作 Golang 後端。 + +## 職責 + +1. 根據實作計畫建立專案結構（Domain-Driven + go-zero 風格） +2. 使用 TDD 流程實作功能（Red-Green-Refactor） +3. 按垂直切片逐步交付（端到端，非逐層） +4. 實作 Domain / Usecase / Logic / Repository 各層 +5. 撰寫單元測試和整合測試 + +## 輸入 + +- 實作計畫 (`./plans/{feature}.md`) +- API 規格 (`docs/api/{date}-{feature}.yaml`) +- DB Schema (`docs/db/{date}-{feature}.sql`) + +## 輸出 + +- Golang 程式碼結構 +- 測試程式碼（單元測試 >= 80%，業務邏輯 >= 90%） +- Protobuf 定義（如需 gRPC） + +## 流程 + +``` +讀取實作計畫 + API 規格 + DB Schema + ↓ +識別垂直切片（每個切片 = 端到端功能） + ↓ +對每個切片執行 TDD 循環: + ├── RED: 寫測試 → 測試失敗 + ├── GREEN: 寫最少程式碼 → 測試通過 + └── REFACTOR: 重構 → 測試仍然通過 + ↓ +切片內建構順序: + domain (entity/value object/interface) + → pkg/domain/usecase (介面) + → pkg/domain/repository (介面) + → pkg/usecase (實作) + → pkg/mock (mock) + → internal/logic (handler 邏輯) + → pkg/repository (基礎設施實作) + ↓ +所有切片完成 → 執行整合測試 + ↓ +確認交付物檢查清單 +``` + +### 步驟說明 + +**1. 讀取輸入** + +同時閱讀三個文件： +- 實作計畫：了解垂直切片分解和優先順序 +- API 規格：了解端點、請求/回應結構 +- DB Schema：了解資料表結構和關係 + +**2. 識別垂直切片** + +不是水平切片（一層一層做），而是垂直切片（端到端）： + +``` +✅ 正確方式（垂直）: + 切片 1: 使用者註冊 (domain.entity + domain.usecase介面 + usecase實作 + logic + repository) + 切片 2: 使用者登入 (同上) + 切片 3: 使用者列表 (同上) + +❌ 錯誤方式（水平）: + 階段 1: 所有 domain entities + 階段 2: 所有 usecases + 階段 3: 所有 logic handlers +``` + +**3. TDD 循環（每個切片）** + +對每個切片，遵循 Red-Green-Refactor： + +``` +RED: 寫一個測試 → 測試失敗 +GREEN: 寫最少的程式碼讓測試通過 → 測試通過 +REFACTOR: 重構程式碼 → 測試仍然通過 +``` + +切片內建構順序（由內而外）： +1. `pkg/domain/entity/` — 定義 Entity 和 Value Object +2. `pkg/domain/member/` — 定義值物件和列舉（含測試） +3. `pkg/domain/usecase/` — 定義 Use Case 介面 +4. `pkg/domain/repository/` — 定義 Repository 介面 +5. `pkg/usecase/` — 實作業務邏輯（先寫測試） +6. `pkg/mock/` — 產生 mock +7. `internal/logic/` — Handler 邏輯 +8. `pkg/repository/` — 基礎設施實作（含 DB 測試） + +**4. 測試** + +每個切片完成後，確保： +- 單元測試通過（`pkg/usecase/*_test.go`） +- 值物件測試通過（`pkg/domain/member/*_test.go`） +- Repository 測試通過（`pkg/repository/*_test.go`） +- 整合測試通過（關鍵路徑） +- 測試覆蓋率達標 + +**5. 完成驗證** + +最後確認所有交付物完整。 + +## 專案結構 + +``` +project-root/ +├── build/ +│ └── Dockerfile # 建置映像 +│ +├── etc/ +│ └── {service}.example.yaml # 範例設定檔 +│ +├── generate/ +│ └── protobuf/ +│ └── {service}.proto # Protobuf 定義（如需 gRPC） +│ +├── internal/ # 應用層（不對外暴露） +│ ├── config/ +│ │ └── config.go # 應用配置 +│ ├── logic/ +│ │ └── {module}/ +│ │ ├── create_{entity}_logic.go # 每個 use case 一個 logic 檔案 +│ │ ├── get_{entity}_logic.go +│ │ ├── update_{entity}_logic.go +│ │ └── ... +│ ├── server/ +│ │ └── {module}/ +│ │ └── {module}_server.go # Server 定義（HTTP/gRPC） +│ └── svc/ +│ └── service_context.go # 依賴注入容器 +│ +├── pkg/ # 領域層（可對外暴露） +│ ├── domain/ +│ │ ├── config/ +│ │ │ └── config.go # Domain 配置 +│ │ ├── entity/ +│ │ │ ├── {entity}.go # Entity 定義 +│ │ │ ├── {entity}_uid_table.go # UID 對照表 +│ │ │ └── auto_id.go # 自動 ID 產生 +│ │ ├── {module}/ +│ │ │ ├── {value_object}.go # 值物件和列舉 +│ │ │ └── {value_object}_test.go # 值物件測試 +│ │ ├── repository/ +│ │ │ ├── {entity}.go # Repository 介面 +│ │ │ └── ... +│ │ ├── usecase/ +│ │ │ ├── {module}.go # Use Case 介面 +│ │ │ └── ... +│ │ ├── errors.go # Domain sentinel errors +│ │ ├── const.go # Domain 常數 +│ │ └── redis.go # Redis domain 定義 +│ ├── mock/ +│ │ ├── repository/ +│ │ │ ├── {entity}.go # Repository mock +│ │ │ └── ... +│ │ └── usecase/ +│ │ └── {module}.go # Use Case mock +│ ├── repository/ +│ │ ├── {entity}.go # Repository 實作 +│ │ ├── {entity}_test.go # Repository 測試 +│ │ ├── {entity}_uid.go # UID Repository 實作 +│ │ ├── {entity}_uid_test.go +│ │ ├── error.go # Repository 錯誤定義 +│ │ └── start_{db}_container_test.go # testcontainers 啟動 +│ └── usecase/ +│ ├── {module}.go # Use Case 實作 +│ ├── {operation}.go # 特定操作 +│ ├── {operation}_test.go # Use Case 測試 +│ └── {utils}.go # 工具函式 +│ +├── {service}.go # 應用程式進入點 +├── Makefile +├── go.mod +├── go.sum +├── docker-compose.yml +└── readme.md +``` + +## 依賴方向規則 + +``` +pkg/domain/ ← 無外部依賴（最內層，純定義） + ↑ +pkg/domain/usecase/ ← Use Case 介面（只有介面定義） +pkg/domain/repository/ ← Repository 介面（只有介面定義） + ↑ +pkg/usecase/ ← 依賴 domain 介面（業務邏輯實作） +pkg/mock/ ← 依賴 domain 介面（測試 mock） + ↑ +internal/logic/ ← 依賴 usecase 實作（handler 邏輯） +internal/server/ ← 依賴 logic（HTTP/gRPC server） +internal/svc/ ← 依賴所有（DI 容器，組裝依賴） + ↑ +pkg/repository/ ← 依賴 domain 介面（基礎設施實作） +``` + +``` + ┌─────────────────────────────────┐ + │ pkg/domain/ │ ← 純定義，無依賴 + │ ├── entity/ │ + │ ├── {module}/ (value objects)│ + │ ├── repository/ (interfaces) │ + │ ├── usecase/ (interfaces) │ + │ ├── errors.go │ + │ └── const.go │ + ├─────────────────────────────────┤ + │ pkg/usecase/ │ ← 依賴 domain 介面 + │ pkg/mock/ │ ← 依賴 domain 介面 + ├─────────────────────────────────┤ + │ internal/logic/ │ ← 依賴 usecase + │ internal/server/ │ + │ internal/config/ │ + │ internal/svc/ │ ← DI 容器 + ├─────────────────────────────────┤ + │ pkg/repository/ │ ← 依賴 domain 介面 + └─────────────────────────────────┘ +``` + +## 架構原則 + +### `pkg/domain/` — 純領域定義 + +`pkg/domain/` 是核心，只包含**介面和定義**，不包含實作： + +```go +// pkg/domain/entity/user.go — Entity 定義 +package entity + +type User struct { + ID string `json:"id"` + Email string `json:"email"` + Name string `json:"name"` + Status string `json:"status"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} +``` + +```go +// pkg/domain/member/status.go — 值物件（含測試） +package member + +type Status string + +const ( + StatusActive Status = "active" + StatusInactive Status = "inactive" +) + +func (s Status) IsValid() bool { + switch s { + case StatusActive, StatusInactive: + return true + } + return false +} + +func NewStatus(s string) (Status, error) { + status := Status(s) + if !status.IsValid() { + return "", fmt.Errorf("invalid status: %s", s) + } + return status, nil +} +``` + +```go +// pkg/domain/member/status_test.go — 值物件測試 +package member + +func TestStatus_IsValid(t *testing.T) { + assert.True(t, StatusActive.IsValid()) + assert.True(t, StatusInactive.IsValid()) + assert.False(t, Status("unknown").IsValid()) +} + +func TestNewStatus(t *testing.T) { + status, err := NewStatus("active") + assert.NoError(t, err) + assert.Equal(t, StatusActive, status) + + _, err = NewStatus("unknown") + assert.Error(t, err) +} +``` + +```go +// pkg/domain/repository/user.go — Repository 介面 +package repository + +type UserRepository interface { + GetByID(ctx context.Context, id string) (*entity.User, error) + GetByEmail(ctx context.Context, email string) (*entity.User, error) + Create(ctx context.Context, user *entity.User) error + Update(ctx context.Context, user *entity.User) error + Delete(ctx context.Context, id string) error +} +``` + +```go +// pkg/domain/usecase/user.go — Use Case 介面 +package usecase + +type UserUsecase interface { + CreateUser(ctx context.Context, input CreateUserInput) (*entity.User, error) + GetUser(ctx context.Context, id string) (*entity.User, error) + UpdateUser(ctx context.Context, id string, input UpdateUserInput) (*entity.User, error) +} +``` + +```go +// pkg/domain/errors.go — Domain sentinel errors +package domain + +import "errors" + +var ( + ErrUserNotFound = errors.New("user not found") + ErrInvalidInput = errors.New("invalid input") + ErrDuplicateEmail = errors.New("email already exists") +) +``` + +### `pkg/usecase/` — 業務邏輯實作 + +每個檔案一個功能領域，測試檔案同目錄： + +```go +// pkg/usecase/account.go — Use Case 進入點 +package usecase + +type AccountUsecase struct { + userRepo repository.UserRepository + accountRepo repository.AccountRepository + redis *redis.Client +} + +func NewAccountUsecase( + userRepo repository.UserRepository, + accountRepo repository.AccountRepository, + redis *redis.Client, +) *AccountUsecase { + return &AccountUsecase{ + userRepo: userRepo, + accountRepo: accountRepo, + redis: redis, + } +} +``` + +```go +// pkg/usecase/create_user.go — 單一操作 +package usecase + +func (uc *AccountUsecase) CreateUser(ctx context.Context, input CreateUserInput) (*entity.User, error) { + if err := input.Validate(); err != nil { + return nil, fmt.Errorf("validate input: %w", err) + } + + existing, _ := uc.userRepo.GetByEmail(ctx, input.Email) + if existing != nil { + return nil, domain.ErrDuplicateEmail + } + + user, err := entity.NewUser(input.Email, input.Password, input.Name) + if err != nil { + return nil, fmt.Errorf("create user: %w", err) + } + + if err := uc.userRepo.Create(ctx, user); err != nil { + return nil, fmt.Errorf("save user: %w", err) + } + + return user, nil +} +``` + +```go +// pkg/usecase/create_user_test.go — 測試同目錄 +package usecase + +func TestAccountUsecase_CreateUser_Success(t *testing.T) { + mockUserRepo := new(mock.UserRepository) + uc := NewAccountUsecase(mockUserRepo, nil, nil) + + mockUserRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockUserRepo.On("Create", mock.Anything, mock.AnythingOfType("*entity.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) + mockUserRepo.AssertExpectations(t) +} +``` + +### `pkg/mock/` — 自動產生的 Mock + +```go +// pkg/mock/repository/user.go — 由 mockery 產生 +//go:generate mockery --name=UserRepository --output=../../mock/repository --outpkg=mock_repository + +package mock_repository + +import ( + "github.com/stretchr/testify/mock" + "your-project/pkg/domain/repository" +) + +type UserRepository struct { + mock.Mock +} + +func (m *UserRepository) GetByID(ctx context.Context, id string) (*entity.User, error) { + args := m.Called(ctx, id) + if args.Get(0) == nil { + return nil, args.Error(1) + } + return args.Get(0).(*entity.User), args.Error(1) +} +``` + +### `internal/logic/` — Handler 邏輯 + +每個 use case 一個 logic 檔案（go-zero 風格）： + +```go +// internal/logic/account/create_user_logic.go +package account + +type CreateUserLogic struct { + ctx context.Context + svcCtx *svc.ServiceContext +} + +func NewCreateUserLogic(ctx context.Context, svcCtx *svc.ServiceContext) *CreateUserLogic { + return &CreateUserLogic{ + ctx: ctx, + svcCtx: svcCtx, + } +} + +func (l *CreateUserLogic) CreateUser(req *types.CreateUserReq) (*types.UserResp, error) { + user, err := l.svcCtx.UserUsecase.CreateUser(l.ctx, usecase.CreateUserInput{ + Email: req.Email, + Password: req.Password, + Name: req.Name, + }) + if err != nil { + return nil, err + } + + return &types.UserResp{ + ID: user.ID, + Email: user.Email, + Name: user.Name, + }, nil +} +``` + +### `internal/svc/` — 依賴注入容器 + +```go +// internal/svc/service_context.go +package svc + +type ServiceContext struct { + Config config.Config + UserUsecase usecase.UserUsecase + AccountUsecase usecase.AccountUsecase +} + +func NewServiceContext(c config.Config) *ServiceContext { + db := mongo.NewClient(c.Mongo.URI) + redisClient := redis.NewClient(c.Redis) + + userRepo := repository.NewUserRepository(db) + accountRepo := repository.NewAccountRepository(db) + + return &ServiceContext{ + Config: c, + UserUsecase: usecase.NewUserUsecase(userRepo, redisClient), + AccountUsecase: usecase.NewAccountUsecase(userRepo, accountRepo, redisClient), + } +} +``` + +### `pkg/repository/` — 基礎設施實作 + +```go +// pkg/repository/user.go +package repository + +type userRepository struct { + db *mongo.Database +} + +func NewUserRepository(db *mongo.Database) domain.Repository.UserRepository { + return &userRepository{db: db} +} + +func (r *userRepository) GetByID(ctx context.Context, id string) (*entity.User, error) { + var user entity.User + err := r.db.Collection("users").FindOne(ctx, bson.M{"_id": id}).Decode(&user) + if err != nil { + if err == mongo.ErrNoDocuments { + return nil, domain.ErrUserNotFound + } + return nil, fmt.Errorf("find user by id: %w", err) + } + return &user, nil +} +``` + +```go +// pkg/repository/user_test.go +package repository + +func TestUserRepository_GetByID_Success(t *testing.T) { + db := startMongoContainer(t) + defer db.Client().Disconnect(context.Background()) + + repo := NewUserRepository(db) + // ... +} +``` + +## 編碼規範 + +### 檔案命名 + +``` +值物件和列舉： pkg/domain/{module}/{name}.go + _test.go +Entity： pkg/domain/entity/{name}.go +Repository 介面：pkg/domain/repository/{name}.go +Usecase 介面： pkg/domain/usecase/{module}.go +Usecase 實作： pkg/usecase/{operation}.go + _test.go +Usecase 工具： pkg/usecase/{module}_utils.go + _test.go +Repository 實作：pkg/repository/{name}.go + _test.go +Mock： pkg/mock/repository/{name}.go + pkg/mock/usecase/{module}.go +Handler 邏輯： internal/logic/{module}/{operation}_logic.go +Server： internal/server/{module}/{module}_server.go +Service Context：internal/svc/service_context.go +Protobuf 定義： generate/protobuf/{module}.proto +設定檔： etc/{service}.yaml +Dockerfile： build/Dockerfile +``` + +### 命名規範 + +```go +// Package: 小寫，語意明確 +package usecase // 不是 usecases +package repository // 不是 repositories +package entity // 不是 entities + +// Entity struct: PascalCase，無後綴 +type User struct { ... } // 不是 UserModel, UserEntity + +// Value Object: 基礎型別別名 + 方法 +type Status string // 不是 StatusEnum + +// Interface (介面): 放在 pkg/domain/ 下，語意命名 +type UserRepository interface { ... } // 不是 UserRepo 或 UserRepositoryI + +// Use Case struct: {Module}Usecase +type AccountUsecase struct { ... } + +// Use Case 方法: 動詞開頭 +func (uc *AccountUsecase) CreateUser(ctx context.Context, ...) (*entity.User, error) +func (uc *AccountUsecase) GetUser(ctx context.Context, id string) (*entity.User, error) + +// Logic struct: {Operation}Logic +type CreateUserLogic struct { ... } + +// Error: Err 前綴 +var ErrUserNotFound = errors.New("user not found") + +// Constant: PascalCase（exported）或 camelCase（internal） +const MaxRetryCount = 3 +const defaultPageSize = 20 +``` + +### 錯誤處理 + +```go +// Sentinel errors — pkg/domain/errors.go +var ( + ErrUserNotFound = errors.New("user not found") + ErrInvalidInput = errors.New("invalid input") + ErrDuplicateEmail = errors.New("email already exists") +) + +// Error wrapping — always use %w +if err != nil { + return fmt.Errorf("create user: %w", err) +} + +// Error checking — always use errors.Is +if errors.Is(err, domain.ErrUserNotFound) { + // handle not found +} + +// Repository errors — pkg/repository/error.go +var ( + ErrMongoConnection = errors.New("mongo connection failed") + ErrRedisConnection = errors.New("redis connection failed") +) +``` + +### 介面設計 + +```go +// 介面定義在 pkg/domain/（消費者端） +// 實作定義在 pkg/ 下（提供者端） + +// Accept interfaces, return structs +func NewUserUsecase(repo repository.UserRepository, redis *redis.Client) *UserUsecase { + return &UserUsecase{repo: repo, redis: redis} +} + +// Keep interfaces small (1-3 methods) +type UserRepository interface { + GetByID(ctx context.Context, id string) (*entity.User, error) + Create(ctx context.Context, user *entity.User) error +} +``` + +## TDD 規範 + +此技能與 `tdd` 技能整合，遵循共同的 TDD 原則。 + +### 測試金字塔 + +``` + /\ + / \ + / E2E \ <- 少數關鍵流程 + /--------\ + /Integration\ <- DB + Redis (testcontainers) + /--------------\ + / Unit Tests \ <- 最多，80%+ 覆蓋 + /--------------------\ +``` + +### 測試位置 + +``` +測試檔案跟原始碼同目錄： + +pkg/domain/member/status_test.go ← 值物件測試 +pkg/usecase/create_user_test.go ← Use Case 測試 +pkg/repository/user_test.go ← Repository 測試 +pkg/repository/start_mongo_container_test.go ← testcontainers 啟動 +``` + +### 垂直切片 TDD + +每個切片按照以下順序： + +``` +切片: 使用者註冊 + 1. RED: 寫 TestStatus_IsValid (值物件) + 2. GREEN: 寫 Status.IsValid() + 3. RED: 寫 TestAccountUsecase_CreateUser_Success + 4. GREEN: 寫 domain/entity, domain/usecase介面, pkg/usecase實作, mock + 5. RED: 寫 TestAccountUsecase_CreateUser_DuplicateEmail + 6. GREEN: 加入重複檢查 + 7. RED: 寫 TestUserRepository_Create (DB 測試) + 8. GREEN: 寫 pkg/repository/user.go + 9. RED: 寫 TestCreateUserLogic (handler 測試) + 10. GREEN: 寫 internal/logic/account/create_user_logic.go + 11. REFACTOR: 清理全部 +``` + +### Mock 策略 + +```go +// 使用 mockery 自動產生 mock +// 在接口檔案加上 go:generate 指令 +//go:generate mockery --name=UserRepository --output=../../mock/repository --outpkg=mock_repository + +// 單元測試使用 mock +func TestAccountUsecase_CreateUser_Success(t *testing.T) { + mockRepo := new(mock_repository.UserRepository) + uc := usecase.NewAccountUsecase(mockRepo, nil, nil) + + mockRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockRepo.On("Create", mock.Anything, mock.AnythingOfType("*entity.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) +} +``` + +### testcontainers 策略 + +```go +// pkg/repository/start_mongo_container_test.go +func startMongoContainer(t *testing.T) *mongo.Database { + ctx := context.Background() + req := testcontainers.ContainerRequest{ + Image: "mongo:7", + ExposedPorts: []string{"27017/tcp"}, + WaitingFor: wait.ForListeningPort("27017/tcp"), + } + + mongoC, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{ + ContainerRequest: req, + Started: true, + }) + require.NoError(t, err) + + t.Cleanup(func() { + mongoC.Terminate(ctx) + }) + + // ... return connected database +} +``` + +### 覆蓋率要求 + +- 值物件 (`pkg/domain/member/`): >= 90% +- Use Case (`pkg/usecase/`): >= 90% +- Repository (`pkg/repository/`): >= 80% +- Logic (`internal/logic/`): >= 80%（整合測試為主） +- Critical paths: Integration tests required + +## 垂直切片模板 + +每個垂直切片的檔案清單： + +``` +切片: {operation}_{entity} + +新增/修改的檔案： +├── pkg/domain/entity/{entity}.go ← Entity 定義 +├── pkg/domain/member/{value_object}.go ← 值物件（如需） +├── pkg/domain/member/{value_object}_test.go ← 值物件測試 +├── pkg/domain/repository/{entity}.go ← Repository 介面 +├── pkg/domain/usecase/{module}.go ← Use Case 介面 +├── pkg/usecase/{operation}.go ← Use Case 實作 +├── pkg/usecase/{operation}_test.go ← Use Case 測試 +├── pkg/mock/repository/{entity}.go ← Repository mock +├── pkg/repository/{entity}.go ← Repository 實作 +├── pkg/repository/{entity}_test.go ← Repository 測試 +├── internal/logic/{module}/{operation}_logic.go ← Handler 邏輯 +└── internal/svc/service_context.go ← 更新 DI +``` + +## 完成檢查清單 + +### 每個切片完成後 +- [ ] 值物件測試通過 +- [ ] Use Case 測試通過 +- [ ] Repository 測試通過（含 DB） +- [ ] 錯誤處理完整 +- [ ] 依賴方向正確（domain 無外部依賴） + +### 全部完成後 +- [ ] 專案結構符合 Domain-Driven + go-zero 風格 +- [ ] `pkg/domain/` 包含所有 Entity、Value Object、介面定義 +- [ ] `pkg/usecase/` 包含所有業務邏輯實作 +- [ ] `pkg/repository/` 包含所有基礎設施實作 +- [ ] `internal/logic/` 包含所有 Handler 邏輯 +- [ ] `internal/svc/` 包含完整的依賴注入設定 +- [ ] 單元測試 >= 80% 覆蓋率 +- [ ] 業務邏輯 >= 90% 覆蓋率 +- [ ] 整合測試通過（關鍵路徑） +- [ ] 錯誤處理一致且使用 `%w` wrapping + +## 相依技能 + +- **前置**: `prd-to-plan` (實作計畫), `be-api-design` (API 規格), `dba-schema` (DB Schema) +- **輔助**: `tdd` (TDD Red-Green-Refactor 流程), `design-an-interface` (介面設計) +- **後續**: `qa` (QA 測試) + +## 退回機制 + +``` +QA 失敗 (Stage 10) + ↓ +Orchestrator 重新分配修復任務 + ↓ +Backend Agent 修復 Bug + 新增回歸測試 + ↓ +重新進入 QA (Stage 10) + +Code Review 退回 (Stage 11) + ↓ +處理 PR 回饋 + ↓ +重新進入 QA (Stage 10) 驗證 + +實作計畫不可行 + ↓ +退回 Task Breakdown (Stage 8) 重新分解 +``` diff --git a/design-idea/translate/skills/tdd/SKILL.md b/design-idea/translate/skills/tdd/SKILL.md new file mode 100644 index 0000000..5f70933 --- /dev/null +++ b/design-idea/translate/skills/tdd/SKILL.md @@ -0,0 +1,296 @@ +--- +name: tdd +description: "Backend Agent 使用此技能進行測試驅動開發。遵循 Red-Green-Refactor 循環和垂直切片原則，確保測試覆蓋行為而非實作細節。觸發時機：實作階段（Stage 9），由 go-backend-dev 技能整合使用。" +--- + +# /tdd — 測試驅動開發 + +Backend Agent 使用此技能進行測試驅動開發。 + +## 核心理念 + +**測試行為，而非實作細節。** + +好的測試透過公開介面驗證行為，描述系統「做什麼」而非「怎麼做」。重構後測試仍然通過。 + +壞的測試與實作耦合：mock 內部協作者、測試私有方法。重構後測試失敗，但行為沒有改變。 + +## 反模式：水平切片 + +**不要先寫完所有測試再寫所有實作。** 這是「水平切片」： + +``` +❌ 錯誤方式: + RED: test1, test2, test3, test4, test5 + GREEN: impl1, impl2, impl3, impl4, impl5 + +✅ 正確方式（垂直切片）: + RED→GREEN: test1 → impl1 + RED→GREEN: test2 → impl2 + RED→GREEN: test3 → impl3 +``` + +水平切片會產生劣質測試： +- 大量寫的測試驗證「想像的」行為，而非「實際的」行為 +- 測試會變成驗證資料結構和函式簽名，而非使用者可觀察的行為 +- 測試對真正的變更不敏感 — 行為壞了還是通過，行為沒變但重構後卻失敗 + +## 流程 + +``` +確認介面變更與測試範圍 + ↓ +寫第一個測試（tracer bullet） + ↓ +RED: 測試失敗 + ↓ +GREEN: 寫最少程式碼讓測試通過 + ↓ +寫下一個測試 + ↓ +RED → GREEN 循環 + ↓ +所有行為測試完成 + ↓ +REFACTOR: 重構 + ↓ +確認所有測試仍然通過 +``` + +### 步驟說明 + +**1. 規劃** + +在寫任何程式碼之前： +- [ ] 與使用者確認需要哪些介面變更 +- [ ] 確認哪些行為需要測試（排序優先順序） +- [ ] 識別深模組的機會（小介面，深實作） +- [ ] 為可測試性設計介面 +- [ ] 列出要測試的行為（不是實作步驟） +- [ ] 取得使用者對測試計畫的認可 + +提問：「公開介面應該長什麼樣子？哪些行為最重要需要測試？」 + +**你不可能測試所有東西。** 與使用者確認哪些行為最重要，將測試精力集中在關鍵路徑和複雜邏輯，而不是每個可能的邊緣案例。 + +**2. Tracer Bullet** + +寫一個測試，確認系統的一件事： + +``` +RED: 寫第一個行為的測試 → 測試失敗 +GREEN: 寫最少的程式碼讓測試通過 → 測試通過 +``` + +這是你的 tracer bullet — 證明端到端路徑可行。 + +**3. 遞增循環** + +對每個剩餘行為： + +``` +RED: 寫下一個測試 → 失敗 +GREEN: 最少程式碼讓測試通過 → 通過 +``` + +規則： +- 一次一個測試 +- 只寫足夠讓當前測試通過的程式碼 +- 不要預測未來的測試 +- 測試聚焦在可觀察的行為 + +**4. 重構** + +所有測試通過後，尋找重構候選： +- [ ] 提取重複邏輯 +- [ ] 加深模組（將複雜度移到簡單介面後方） +- [ ] 自然地應用 SOLID 原則 +- [ ] 思考新程式碼揭示了什麼既有程式碼的問題 +- [ ] 每個重構步驟後都跑測試 + +**絕對不要在 RED 狀態下重構。先回到 GREEN。** + +## 好的測試 vs 壞的測試 + +### 好的測試 + +**整合風格**：透過真實介面測試，不是 mock 內部零件。 + +```go +// GOOD: 測試可觀察的行為 +func TestUserUsecase_CreateUser_Success(t *testing.T) { + mockRepo := new(mock.UserRepository) + uc := NewUserUsecase(mockRepo, logger) + + mockRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockRepo.On("Create", mock.Anything, mock.AnythingOfType("*domain.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) + assert.Equal(t, "test@example.com", user.Email) +} +``` + +特徵： +- 測試使用者/呼叫者關心的行為 +- 只使用公開 API +- 重構內部實作後測試仍然通過 +- 描述「做什麼」而非「怎麼做」 +- 每個測試一個邏輯斷言 + +### 壊的測試 + +**實作細節測試**：與內部結構耦合。 + +```go +// BAD: 測試實作細節 +func TestUserUsecase_CreateUser_CallsRepoCreate(t *testing.T) { + mockRepo := new(mock.UserRepository) + uc := NewUserUsecase(mockRepo, logger) + + uc.CreateUser(context.Background(), input) + + // 這測試的是「怎麼做」而非「做什麼」 + mockRepo.AssertCalled(t, "Create", mock.Anything, mock.Anything) +} +``` + +紅旗： +- Mock 內部協作者只是為了驗證被呼叫 +- 測試私有方法 +- 斷言呼叫次數或順序 +- 重構後測試失敗但行為沒變 +- 測試名稱描述「怎麼做」而非「做什麼」 + +```go +// BAD: 繞過介面驗證 +func TestCreateUser_SavesToDatabase(t *testing.T) { + CreateUser(ctx, input) + row := db.QueryRow("SELECT * FROM users WHERE name = $1", "Alice") + // 直接查資料庫驗證，繞過公開介面 +} + +// GOOD: 透過介面驗證 +func TestCreateUser_MakesUserRetrievable(t *testing.T) { + user, _ := CreateUser(ctx, input) + retrieved, _ := GetUser(ctx, user.ID) + assert.Equal(t, "Alice", retrieved.Name) + // 透過公開介面驗證行為 +} +``` + +## Golang 測試規範 + +### 測試命名 + +```go +// Test{Unit}_{Scenario} +func TestUserUsecase_CreateUser_Success(t *testing.T) {} +func TestUserUsecase_CreateUser_InvalidEmail(t *testing.T) {} +func TestUserUsecase_CreateUser_Duplicate(t *testing.T) {} +``` + +### 測試金字塔 + +``` + /\ + / \ + / E2E \ <- 少數關鍵流程 + /--------\ + /Integration\ <- API + DB + /--------------\ + / Unit Tests \ <- 最多，80%+ 覆蓋 + /--------------------\ +``` + +### Mock 策略 + +只在**系統邊界** mock： +- 外部 API（支付、郵件等） +- 資料庫（有時 — 優先使用測試 DB） +- 時間/隨機性 +- 檔案系統（有時） + +不要 mock： +- 你自己的類別/模組 +- 內部協作者 +- 你可以控制的東西 + +```go +// 使用 mockery 自動產生 mock +//go:generate mockery --name=UserRepository + +// 單元測試使用 mock repo +func TestUserUsecase_CreateUser_Success(t *testing.T) { + mockRepo := new(mock.UserRepository) + uc := NewUserUsecase(mockRepo, logger) + + mockRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockRepo.On("Create", mock.Anything, mock.AnythingOfType("*domain.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) +} +``` + +## 介面設計的可測試性 + +好的介面讓測試自然： + +**1. 接受依賴，不要建立依賴** + +```go +// Testable +func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput, repo UserRepository) (*User, error) {} + +// Hard to test +func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput) (*User, error) { + repo := postgres.NewUserRepository(db) // 建立依賴 +} +``` + +**2. 回傳結果，不要產生副作用** + +```go +// Testable +func CalculateDiscount(cart *Cart) Discount {} + +// Hard to test +func ApplyDiscount(cart *Cart) { + cart.Total -= discount // 修改輸入 +} +``` + +**3. 小介面面積** +- 方法少 = 測試少 +- 參數少 = 測試設定簡單 + +## 每個循環的檢查清單 + +``` +[ ] 測試描述行為，而非實作 +[ ] 測試只使用公開介面 +[ ] 測試在內部重構後仍然通過 +[ ] 程式碼是讓當前測試通過的最少實作 +[ ] 沒有投機性的功能 +``` + +## 重構候選 + +TDD 循環完成後，尋找： +- **重複邏輯** → 提取 function / class +- **過長方法** → 拆成私有 helper（保持測試在公開介面） +- **淺模組** → 合併或加深 +- **Feature envy** → 把邏輯移到資料所在的地方 +- **原始型別偏執** → 引入 value object +- **新程式碼揭示的既有程式碼問題** + +## 相依技能 + +- **前置**: `go-backend-dev` (在實作中整合使用) +- **輔助**: `design-an-interface` (為可測試性設計介面) +- **後續**: `qa` (QA 測試) diff --git a/skills/be-api-design/SKILL.md b/skills/be-api-design/SKILL.md new file mode 100644 index 0000000..ea8de77 --- /dev/null +++ b/skills/be-api-design/SKILL.md @@ -0,0 +1,532 @@ +--- +name: be-api-design +description: "Backend Agent uses this skill to design API specs. Based on PRD, produce OpenAPI 3.0 spec including endpoints, request/response structures, error handling. Trigger: After PRD approved (Stage 4)." +--- + +# /be-api-design — API Design + +Backend Agent uses this skill to design API specs. + +## Responsibilities + +1. Analyze functional requirements from PRD +2. Use `design-an-interface` to explore multiple API design options +3. Design RESTful API endpoints +4. Define request/response schemas +5. Design error handling mechanism +6. Produce OpenAPI 3.0 spec + +## Input + +- PRD document (`docs/prd/{date}-{feature}.md`) +- Existing API style (existing API specs in project) +- Data model context + +## Output + +- API spec document: `docs/api/{date}-{feature}.yaml` (OpenAPI 3.0) + +## Flow + +``` +Read PRD + ↓ +Identify resources and operations + ↓ +Call design-an-interface to explore 2-3 design options + ↓ +Select best option + ↓ +Define OpenAPI Schema + ↓ +Design error handling + ↓ +Security review + ↓ +Produce OpenAPI document +``` + +### Step Details + +**1. Read PRD** + +Extract all functional requirements from PRD, identify: +- Resources (nouns): users, orders, products, etc. +- Operations (verbs): create, read, update, delete, etc. +- Relationships: relationships between resources (one-to-many, many-to-many) +- Non-functional requirements: pagination, rate limiting, authentication, etc. + +**2. Identify Resources and Operations** + +Map functional requirements to RESTful resources: +- Each noun → potential resource +- Each verb → HTTP method +- Each relationship → nested resource or standalone endpoint + +**3. Call design-an-interface** + +Use `design-an-interface` skill to generate 2-3 distinct API design options: +- Option A: Minimize method count (1-3 endpoints per resource) +- Option B: Maximize flexibility (support multiple use cases) +- Option C: Optimize for most common operations + +Compare pros and cons, select best design. + +**4. Define OpenAPI Schema** + +Use template below to produce complete OpenAPI 3.0 spec. + +**5. Security Review** + +Ensure all endpoints have appropriate authentication and permission controls. + +**6. Produce Document** + +Save to `docs/api/{date}-{feature}.yaml`. + +## Design Principles + +### RESTful Design + +```yaml +Resource-oriented: + - URL represents resource, not action + - HTTP methods represent actions + +Example: + GET /api/v1/users # List users + GET /api/v1/users/{id} # Get specific user + POST /api/v1/users # Create user + PUT /api/v1/users/{id} # Full update + PATCH /api/v1/users/{id} # Partial update + DELETE /api/v1/users/{id} # Delete user + +Nested resources: + GET /api/v1/users/{id}/orders # Get user's orders + POST /api/v1/users/{id}/orders # Create order for user +``` + +### HTTP Status Codes + +```yaml +Success: + 200: OK # GET, PUT, PATCH, DELETE success + 201: Created # POST successfully created resource + 204: No Content # DELETE success, no response body + +Client Error: + 400: Bad Request # Request format error + 401: Unauthorized # Not authenticated + 403: Forbidden # No permission + 404: Not Found # Resource not found + 409: Conflict # Resource conflict (e.g., duplicate) + 422: Unprocessable Entity # Validation error + 429: Too Many Requests # Rate limit + +Server Error: + 500: Internal Server Error # Server internal error + 502: Bad Gateway # Upstream service error + 503: Service Unavailable # Service temporarily unavailable +``` + +### Response Format + +```yaml +Success response: + type: object + properties: + data: + type: object + meta: + type: object + properties: + page: + type: integer + limit: + type: integer + total: + type: integer + total_pages: + type: integer + +Error response: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + details: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string +``` + +## OpenAPI 3.0 Template + +```yaml +openapi: 3.0.3 +info: + title: {API Name} + version: 1.0.0 + description: | + {Description} + + Related PRD: {PRD Link} + +servers: + - url: https://api.example.com/v1 + description: Production + - url: https://staging-api.example.com/v1 + description: Staging + +paths: + /users: + get: + summary: List users + tags: + - Users + parameters: + - name: page + in: query + schema: + type: integer + default: 1 + - name: limit + in: query + schema: + type: integer + default: 20 + maximum: 100 + - name: search + in: query + schema: + type: string + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/UserListResponse' + '401': + $ref: '#/components/responses/Unauthorized' + '500': + $ref: '#/components/responses/InternalError' + + post: + summary: Create user + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateUserRequest' + responses: + '201': + description: Created successfully + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '400': + $ref: '#/components/responses/BadRequest' + '422': + $ref: '#/components/responses/ValidationError' + + /users/{id}: + parameters: + - name: id + in: path + required: true + schema: + type: string + + get: + summary: Get user + tags: + - Users + responses: + '200': + description: Success + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '404': + $ref: '#/components/responses/NotFound' + + put: + summary: Full update user + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateUserRequest' + responses: + '200': + description: Updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '404': + $ref: '#/components/responses/NotFound' + '422': + $ref: '#/components/responses/ValidationError' + + patch: + summary: Partial update user + tags: + - Users + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/PatchUserRequest' + responses: + '200': + description: Updated successfully + content: + application/json: + schema: + $ref: '#/components/schemas/UserResponse' + '404': + $ref: '#/components/responses/NotFound' + + delete: + summary: Delete user + tags: + - Users + responses: + '204': + description: Deleted successfully + '404': + $ref: '#/components/responses/NotFound' + +components: + schemas: + User: + type: object + properties: + id: + type: string + example: "usr_123456" + email: + type: string + format: email + example: "user@example.com" + name: + type: string + example: "John Doe" + status: + type: string + enum: [active, inactive, suspended] + example: "active" + created_at: + type: string + format: date-time + updated_at: + type: string + format: date-time + required: + - id + - email + - name + - status + - created_at + - updated_at + + CreateUserRequest: + type: object + properties: + email: + type: string + format: email + password: + type: string + minLength: 8 + name: + type: string + minLength: 1 + maxLength: 100 + required: + - email + - password + - name + + UpdateUserRequest: + type: object + properties: + email: + type: string + format: email + name: + type: string + minLength: 1 + maxLength: 100 + status: + type: string + enum: [active, inactive] + + PatchUserRequest: + type: object + properties: + name: + type: string + minLength: 1 + maxLength: 100 + status: + type: string + enum: [active, inactive] + + UserResponse: + type: object + properties: + data: + $ref: '#/components/schemas/User' + + UserListResponse: + type: object + properties: + data: + type: array + items: + $ref: '#/components/schemas/User' + meta: + type: object + properties: + page: + type: integer + limit: + type: integer + total: + type: integer + total_pages: + type: integer + + Error: + type: object + properties: + error: + type: object + properties: + code: + type: string + message: + type: string + details: + type: array + items: + type: object + properties: + field: + type: string + message: + type: string + + responses: + BadRequest: + description: Request format error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + Unauthorized: + description: Not authenticated + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + NotFound: + description: Resource not found + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + ValidationError: + description: Validation error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + InternalError: + description: Server internal error + content: + application/json: + schema: + $ref: '#/components/schemas/Error' + + securitySchemes: + bearerAuth: + type: http + scheme: bearer + bearerFormat: JWT + +security: + - bearerAuth: [] +``` + +## Design Checklist + +### Security +- [ ] All endpoints have appropriate authentication +- [ ] Input validation complete +- [ ] Rate limiting designed +- [ ] CORS configured + +### Performance +- [ ] Pagination support +- [ ] Caching strategy +- [ ] Batch operation support + +### Reliability +- [ ] Error response format unified +- [ ] Retry mechanism recommendations +- [ ] Idempotency design + +### Consistency +- [ ] Naming convention consistent (resources use plural nouns) +- [ ] Response format consistent (data/meta/error structure) +- [ ] Filter/sort/pagination parameters consistent + +## Related Skills + +- **Prerequisite**: `write-a-prd` (after PRD approved) +- **辅助**: `design-an-interface` (explore multiple design options) +- **Follow-up**: `dba-schema` (DB Schema design) +- **Rollback**: Can rollback to `write-a-prd` to modify requirements + +## Rollback Mechanism + +``` +Design Review rejects API design + ↓ +Modify OpenAPI spec + ↓ +Re-submit (or re-call design-an-interface) + +DBA Agent finds Schema conflict + ↓ +Negotiate domain model or API response format adjustments + ↓ +Update OpenAPI spec +``` diff --git a/skills/design-an-interface/SKILL.md b/skills/design-an-interface/SKILL.md new file mode 100644 index 0000000..3b94d75 --- /dev/null +++ b/skills/design-an-interface/SKILL.md @@ -0,0 +1,188 @@ +--- +name: design-an-interface +description: "Backend Agent uses this skill to explore multiple API interface design options. Based on 'Design It Twice' principle, generate multiple distinct designs, compare, and select the best option. Trigger: API design phase (Stage 4), called by be-api-design skill." +--- + +# /design-an-interface — Interface Design Exploration + +Backend Agent uses this skill to explore API interface design options. + +Based on "Design It Twice" principle from "A Philosophy of Software Design": The first idea is usually not the best. Generate multiple distinct designs, then compare and choose. + +## Responsibilities + +1. Generate 2-3 distinct interface design options for module requirements +2. Each option uses different design constraints +3. Compare pros and cons of options +4. Assist in selecting or synthesizing the best option + +## Input + +- Module description (functional requirements from PRD) +- User stories and usage scenarios + +## Output + +- Multiple interface design options (including interface signatures, usage examples, pros/cons analysis) +- Option comparison and recommendations + +## Flow + +``` +Collect requirements + ↓ +Generate 2-3 design options (parallel sub-agents) + ↓ +Present each option + ↓ +Compare options (interface simplicity, generality, implementation efficiency, depth) + ↓ +Synthesize best option or select most suitable +``` + +### Step Details + +**1. Collect Requirements** + +Before designing, understand: +- [ ] What problem does this module solve? +- [ ] Who are the callers? (other modules, external users, tests) +- [ ] What are the key operations? +- [ ] What are the constraints? (performance, compatibility, existing patterns) +- [ ] What should be hidden internally? What should be exposed externally? + +Ask: "What does this module need to do? Who will use it?" + +**2. Generate Design Options (Parallel Sub-Agents)** + +Generate 3+ distinct options simultaneously. Each option must follow different constraints: + +``` +Option A: Minimize method count — target 1-3 methods +Option B: Maximize flexibility — support multiple use cases +Option C: Optimize for most common operations +Option D (optional): Reference specific paradigm or framework design +``` + +Each option should include: +1. Interface signature (types/methods) +2. Usage examples (how callers actually use it) +3. What complexity this design hides +4. Trade-offs of this option + +**3. Present Options** + +Present each option one by one, including: +- Interface signature: types, methods, params +- Usage examples: how callers actually use it +- Hidden complexity: small interface hiding large implementation (good) vs large interface with thin implementation (bad) + +Allow user to fully absorb each option before comparison. + +**4. Compare Options** + +Compare across dimensions: + +- **Interface simplicity**: Few methods, simple parameters → Easier to learn and use correctly +- **Generality vs Specificity**: Flexibility vs focus, where are the trade-offs +- **Implementation efficiency**: Does interface shape allow efficient internal implementation? +- **Depth**: Small interface hiding large complexity (deep module, good) vs large interface with thin implementation (shallow module, bad) +- **Ease of correct usage vs ease of misuse** + +Discuss trade-offs in text, not just tables. Emphasize where options diverge most. + +**5. Synthesize Best Option** + +The best design often combines insights from multiple options. Ask: +- "Which option fits your primary use case best?" +- "Are there elements from other options worth incorporating?" + +## Evaluation Criteria + +From "A Philosophy of Software Design": + +**Interface simplicity**: Few methods, simple parameters = Easier to learn and use correctly. + +**Generality**: Can handle future use cases without modification. But avoid over-generalization. + +**Implementation efficiency**: Does interface shape allow efficient implementation? Or does it force awkward internal implementation? + +**Depth**: Small interface hiding large complexity = deep module (good). Large interface with thin implementation = shallow module (avoid). + +``` +Deep module (good): +┌─────────────────────┐ +│ Small Interface │ ← Few methods, simple parameters +├─────────────────────┤ +│ │ +│ │ +│ Deep Implementation│ ← Complex logic hidden inside +│ │ +│ │ +└─────────────────────┘ + +Shallow module (avoid): +┌─────────────────────────────────┐ +│ Large Interface │ ← Many methods, complex parameters +├─────────────────────────────────┤ +│ Thin Implementation │ ← Just a pass-through +└─────────────────────────────────┘ +``` + +## Anti-Patterns + +- Don't let sub-agents generate similar designs — force distinct ones +- Don't skip comparison — value comes from contrast +- Don't implement at this stage — this is pure interface design +- Don't evaluate options based on implementation effort — only look at interface quality + +## Golang Interface Design Examples + +```go +// Option A: Minimize method count +type UserRepository interface { + GetByID(ctx context.Context, id string) (*domain.User, error) + Save(ctx context.Context, user *domain.User) error +} +// Pros: Simple, easy to mock +// Cons: Save handles both Create and Update, depends on whether it exists + +// Option B: Separate read/write +type UserReader interface { + GetByID(ctx context.Context, id string) (*domain.User, error) + List(ctx context.Context, page, limit int) ([]*domain.User, error) +} + +type UserWriter interface { + Create(ctx context.Context, user *domain.User) error + Update(ctx context.Context, user *domain.User) error + Delete(ctx context.Context, id string) error +} +// Pros: CQRS friendly, separated concerns +// Cons: More methods, but each method has clearer semantics + +// Option C: Optimize for common operations +type UserService interface { + Register(ctx context.Context, email, password, name string) (*domain.User, error) + Authenticate(ctx context.Context, email, password string) (*domain.User, error) + GetProfile(ctx context.Context, id string) (*domain.User, error) +} +// Pros: Directly maps to business operations, most intuitive +// Cons: Need to add method for each new operation, less flexible +``` + +## Integration with be-api-design + +This skill is automatically called by `be-api-design` at step 3. API design flow: + +``` +be-api-design step 1: Read PRD +be-api-design step 2: Identify resources and operations +→ design-an-interface: Explore 2-3 API design options +be-api-design step 4: Select option, define OpenAPI spec +``` + +## Related Skills + +- **Prerequisite**: `write-a-prd` (PRD complete) +- **Follow-up**: `be-api-design` (API spec definition) diff --git a/skills/design-patterns/abstract-factory/SKILL.md b/skills/design-patterns/abstract-factory/SKILL.md new file mode 100644 index 0000000..12985ad --- /dev/null +++ b/skills/design-patterns/abstract-factory/SKILL.md @@ -0,0 +1,15 @@ +# Abstract Factory Pattern + +## Description +Provide an interface for creating families of related or dependent objects without specifying their concrete classes. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Abstract Factory Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/abstract-factory) diff --git a/skills/design-patterns/adapter/SKILL.md b/skills/design-patterns/adapter/SKILL.md new file mode 100644 index 0000000..a81f666 --- /dev/null +++ b/skills/design-patterns/adapter/SKILL.md @@ -0,0 +1,15 @@ +# Adapter Pattern + +## Description +Convert the interface of a class into another interface that clients expect. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Adapter Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/adapter) diff --git a/skills/design-patterns/bridge/SKILL.md b/skills/design-patterns/bridge/SKILL.md new file mode 100644 index 0000000..f1a18b0 --- /dev/null +++ b/skills/design-patterns/bridge/SKILL.md @@ -0,0 +1,15 @@ +# Bridge Pattern + +## Description +Decouple an abstraction from its implementation so that the two can vary independently. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Bridge Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/bridge) diff --git a/skills/design-patterns/builder/SKILL.md b/skills/design-patterns/builder/SKILL.md new file mode 100644 index 0000000..87b7f21 --- /dev/null +++ b/skills/design-patterns/builder/SKILL.md @@ -0,0 +1,15 @@ +# Builder Pattern + +## Description +Separate the construction of a complex object from its representation, allowing the same construction process to create different representations. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Builder Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/builder) diff --git a/skills/design-patterns/chain-of-responsibility/SKILL.md b/skills/design-patterns/chain-of-responsibility/SKILL.md new file mode 100644 index 0000000..fb6c781 --- /dev/null +++ b/skills/design-patterns/chain-of-responsibility/SKILL.md @@ -0,0 +1,15 @@ +# Chain of Responsibility Pattern + +## Description +Allow multiple objects to handle the same request. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Chain of Responsibility Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/chain-of-responsibility) diff --git a/skills/design-patterns/command/SKILL.md b/skills/design-patterns/command/SKILL.md new file mode 100644 index 0000000..3d23d7b --- /dev/null +++ b/skills/design-patterns/command/SKILL.md @@ -0,0 +1,15 @@ +# Command Pattern + +## Description +Encapsulate a request as an object, thereby allowing parameterization of clients with different requests. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Command Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/command) diff --git a/skills/design-patterns/composite/SKILL.md b/skills/design-patterns/composite/SKILL.md new file mode 100644 index 0000000..f33a03c --- /dev/null +++ b/skills/design-patterns/composite/SKILL.md @@ -0,0 +1,15 @@ +# Composite Pattern + +## Description +Compose objects into tree structures to represent part-whole hierarchies. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Composite Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/composite) diff --git a/skills/design-patterns/decorator/SKILL.md b/skills/design-patterns/decorator/SKILL.md new file mode 100644 index 0000000..c92d762 --- /dev/null +++ b/skills/design-patterns/decorator/SKILL.md @@ -0,0 +1,15 @@ +# Decorator Pattern + +## Description +Dynamically add additional responsibilities to an object. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Decorator Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/decorator) diff --git a/skills/design-patterns/facade/SKILL.md b/skills/design-patterns/facade/SKILL.md new file mode 100644 index 0000000..e0d147c --- /dev/null +++ b/skills/design-patterns/facade/SKILL.md @@ -0,0 +1,15 @@ +# Facade Pattern + +## Description +Provide a unified interface to a set of interfaces in a subsystem, hiding the implementation details of the subsystem. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Facade Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/facade) diff --git a/skills/design-patterns/factory-method/SKILL.md b/skills/design-patterns/factory-method/SKILL.md new file mode 100644 index 0000000..b6757be --- /dev/null +++ b/skills/design-patterns/factory-method/SKILL.md @@ -0,0 +1,15 @@ +# Factory Method Pattern + +## Description +Define an interface for creating an object, but let subclasses decide which class to instantiate. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Factory Method Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/factory-method) diff --git a/skills/design-patterns/flyweight/SKILL.md b/skills/design-patterns/flyweight/SKILL.md new file mode 100644 index 0000000..59eb7d2 --- /dev/null +++ b/skills/design-patterns/flyweight/SKILL.md @@ -0,0 +1,15 @@ +# Flyweight Pattern + +## Description +Use sharing to support large quantities of fine-grained objects efficiently. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Flyweight Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/flyweight) diff --git a/skills/design-patterns/iterator/SKILL.md b/skills/design-patterns/iterator/SKILL.md new file mode 100644 index 0000000..4685a71 --- /dev/null +++ b/skills/design-patterns/iterator/SKILL.md @@ -0,0 +1,15 @@ +# Iterator Pattern + +## Description +Provide a method to sequentially access elements of an aggregate object without exposing its internal representation. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Iterator Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/iterator) diff --git a/skills/design-patterns/mediator/SKILL.md b/skills/design-patterns/mediator/SKILL.md new file mode 100644 index 0000000..9ab68e2 --- /dev/null +++ b/skills/design-patterns/mediator/SKILL.md @@ -0,0 +1,15 @@ +# Mediator Pattern + +## Description +Use a mediator object to encapsulate a series of class interactions. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Mediator Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/mediator) diff --git a/skills/design-patterns/memento/SKILL.md b/skills/design-patterns/memento/SKILL.md new file mode 100644 index 0000000..2bbc192 --- /dev/null +++ b/skills/design-patterns/memento/SKILL.md @@ -0,0 +1,15 @@ +# Memento Pattern + +## Description +Capture an object's internal state without violating encapsulation, so that the object can be restored to this state later. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Memento Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/memento) diff --git a/skills/design-patterns/observer/SKILL.md b/skills/design-patterns/observer/SKILL.md new file mode 100644 index 0000000..bf40a8e --- /dev/null +++ b/skills/design-patterns/observer/SKILL.md @@ -0,0 +1,15 @@ +# Observer Pattern + +## Description +Define a one-to-many dependency relationship so that when one object's state changes, all dependent objects are notified and automatically updated. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Observer Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/observer) diff --git a/skills/design-patterns/prototype/SKILL.md b/skills/design-patterns/prototype/SKILL.md new file mode 100644 index 0000000..9ef7449 --- /dev/null +++ b/skills/design-patterns/prototype/SKILL.md @@ -0,0 +1,15 @@ +# Prototype Pattern + +## Description +Use a prototype instance to create other instances. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Prototype Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/prototype) diff --git a/skills/design-patterns/proxy/SKILL.md b/skills/design-patterns/proxy/SKILL.md new file mode 100644 index 0000000..f7d0408 --- /dev/null +++ b/skills/design-patterns/proxy/SKILL.md @@ -0,0 +1,15 @@ +# Proxy Pattern + +## Description +Provide a surrogate or placeholder for another object to control access to it. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Proxy Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/proxy) diff --git a/skills/design-patterns/singleton/SKILL.md b/skills/design-patterns/singleton/SKILL.md new file mode 100644 index 0000000..3e58e2c --- /dev/null +++ b/skills/design-patterns/singleton/SKILL.md @@ -0,0 +1,15 @@ +# Singleton Pattern + +## Description +Ensure a class has only one instance and provide a global point of access to it. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Singleton Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/singleton) diff --git a/skills/design-patterns/state/SKILL.md b/skills/design-patterns/state/SKILL.md new file mode 100644 index 0000000..6ec7974 --- /dev/null +++ b/skills/design-patterns/state/SKILL.md @@ -0,0 +1,15 @@ +# State Pattern + +## Description +Allow an object to alter its behavior when its internal state changes. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [State Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/state) diff --git a/skills/design-patterns/strategy/SKILL.md b/skills/design-patterns/strategy/SKILL.md new file mode 100644 index 0000000..1654397 --- /dev/null +++ b/skills/design-patterns/strategy/SKILL.md @@ -0,0 +1,15 @@ +# Strategy Pattern + +## Description +Define a family of algorithms, encapsulate each one, and make them interchangeable. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Strategy Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/strategy) diff --git a/skills/design-patterns/template-method/SKILL.md b/skills/design-patterns/template-method/SKILL.md new file mode 100644 index 0000000..c370c23 --- /dev/null +++ b/skills/design-patterns/template-method/SKILL.md @@ -0,0 +1,15 @@ +# Template Method Pattern + +## Description +Define the skeleton of an operation, deferring some steps to subclasses. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Template Method Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/template-method) diff --git a/skills/design-patterns/visitor/SKILL.md b/skills/design-patterns/visitor/SKILL.md new file mode 100644 index 0000000..48ac436 --- /dev/null +++ b/skills/design-patterns/visitor/SKILL.md @@ -0,0 +1,15 @@ +# Visitor Pattern + +## Description +Without changing the element classes, define new operations that act on these elements. + +## Use Cases +Load this skill when you need to solve design problems described by this pattern in your code. + +## Guidelines +1. Analyze whether current code structure matches the pattern's intent. +2. Refactor or implement following the pattern's typical structure. +3. Ensure the pattern introduction reduces coupling or improves flexibility. + +## Detailed Reference +For more details, diagrams, and code examples: [Visitor Pattern - RefactoringGuru](https://refactoringguru.cn/design-patterns/visitor) diff --git a/skills/go-backend-dev/SKILL.md b/skills/go-backend-dev/SKILL.md new file mode 100644 index 0000000..75b8909 --- /dev/null +++ b/skills/go-backend-dev/SKILL.md @@ -0,0 +1,812 @@ +--- +name: go-backend-dev +description: "Backend Agent uses this skill to implement Golang backend. Based on implementation plan and API spec, use Domain-Driven + go-zero style architecture and TDD process to produce production-ready code. Trigger: After Task Breakdown complete (Stage 9)." +--- + +# /go-backend-dev — Golang Backend Implementation + +Backend Agent uses this skill to implement Golang backend. + +## Responsibilities + +1. Establish project structure based on implementation plan (Domain-Driven + go-zero style) +2. Implement features using TDD process (Red-Green-Refactor) +3. Deliver incrementally by vertical slices (end-to-end, not layer-by-layer) +4. Implement Domain / Usecase / Logic / Repository layers +5. Write unit tests and integration tests + +## Input + +- Implementation plan (`./plans/{feature}.md`) +- API spec (`docs/api/{date}-{feature}.yaml`) +- DB Schema (`docs/db/{date}-{feature}.sql`) + +## Output + +- Golang code structure +- Test code (unit tests >= 80%, business logic >= 90%) +- Protobuf definitions (if gRPC needed) + +## Flow + +``` +Read implementation plan + API spec + DB Schema + ↓ +Identify vertical slices (each slice = end-to-end feature) + ↓ +Execute TDD loop for each slice: + ├── RED: Write test → Test fails + ├── GREEN: Write minimal code → Test passes + └── REFACTOR: Refactor → Test still passes + ↓ +Build order within slice: + domain (entity/value object/interface) + → pkg/domain/usecase (interface) + → pkg/domain/repository (interface) + → pkg/usecase (implementation) + → pkg/mock (mock) + → internal/logic (handler logic) + → pkg/repository (infrastructure implementation) + ↓ +All slices complete → Run integration tests + ↓ +Confirm deliverables checklist +``` + +### Step Details + +**1. Read Input** + +Read three documents simultaneously: +- Implementation plan: Understand vertical slice breakdown and priority +- API spec: Understand endpoints, request/response structures +- DB Schema: Understand table structures and relationships + +**2. Identify Vertical Slices** + +Not horizontal slicing (layer by layer), but vertical slicing (end-to-end): + +``` +✅ Correct way (vertical): + Slice 1: User registration (domain.entity + domain.usecase interface + usecase implementation + logic + repository) + Slice 2: User login (same as above) + Slice 3: User list (same as above) + +❌ Wrong way (horizontal): + Stage 1: All domain entities + Stage 2: All usecases + Stage 3: All logic handlers +``` + +**3. TDD Loop (Each Slice)** + +For each slice, follow Red-Green-Refactor: + +``` +RED: Write a test → Test fails +GREEN: Write minimal code to make test pass → Test passes +REFACTOR: Refactor code → Test still passes +``` + +Build order within slice (inside-out): +1. `pkg/domain/entity/` — Define Entity and Value Object +2. `pkg/domain/member/` — Define value objects and enums (with tests) +3. `pkg/domain/usecase/` — Define Use Case interface +4. `pkg/domain/repository/` — Define Repository interface +5. `pkg/usecase/` — Implement business logic (write tests first) +6. `pkg/mock/` — Generate mocks +7. `internal/logic/` — Handler logic +8. `pkg/repository/` — Infrastructure implementation (with DB tests) + +**4. Testing** + +After each slice completes, ensure: +- Unit tests pass (`pkg/usecase/*_test.go`) +- Value object tests pass (`pkg/domain/member/*_test.go`) +- Repository tests pass (`pkg/repository/*_test.go`) +- Integration tests pass (critical paths) +- Test coverage meets requirements + +**5. Completion Verification** + +Finally confirm all deliverables are complete. + +## Project Structure + +``` +project-root/ +├── build/ +│ └── Dockerfile # Build image +│ +├── etc/ +│ └── {service}.example.yaml # Example config file +│ +├── generate/ +│ └── protobuf/ +│ └── {service}.proto # Protobuf definitions (if gRPC) +│ +├── internal/ # Application layer (not exposed externally) +│ ├── config/ +│ │ └── config.go # Application config +│ ├── logic/ +│ │ └── {module}/ +│ │ ├── create_{entity}_logic.go # One logic file per use case +│ │ ├── get_{entity}_logic.go +│ │ ├── update_{entity}_logic.go +│ │ └── ... +│ ├── server/ +│ │ └── {module}/ +│ │ └── {module}_server.go # Server definition (HTTP/gRPC) +│ └── svc/ +│ └── service_context.go # Dependency injection container +│ +├── pkg/ # Domain layer (can be exposed externally) +│ ├── domain/ +│ │ ├── config/ +│ │ │ └── config.go # Domain config +│ │ ├── entity/ +│ │ │ ├── {entity}.go # Entity definition +│ │ │ ├── {entity}_uid_table.go # UID mapping table +│ │ │ └── auto_id.go # Auto ID generation +│ │ ├── {module}/ +│ │ │ ├── {value_object}.go # Value objects and enums +│ │ │ └── {value_object}_test.go # Value object tests +│ │ ├── repository/ +│ │ │ ├── {entity}.go # Repository interface +│ │ │ └── ... +│ │ ├── usecase/ +│ │ │ ├── {module}.go # Use Case interface +│ │ │ └── ... +│ │ ├── errors.go # Domain sentinel errors +│ │ ├── const.go # Domain constants +│ │ └── redis.go # Redis domain definitions +│ ├── mock/ +│ │ ├── repository/ +│ │ │ ├── {entity}.go # Repository mock +│ │ │ └── ... +│ │ └── usecase/ +│ │ └── {module}.go # Use Case mock +│ ├── repository/ +│ │ ├── {entity}.go # Repository implementation +│ │ ├── {entity}_test.go # Repository tests +│ │ ├── {entity}_uid.go # UID Repository implementation +│ │ ├── {entity}_uid_test.go +│ │ ├── error.go # Repository error definitions +│ │ └── start_{db}_container_test.go # testcontainers startup +│ └── usecase/ +│ ├── {module}.go # Use Case implementation +│ ├── {operation}.go # Specific operation +│ ├── {operation}_test.go # Use Case tests +│ └── {utils}.go # Utility functions +│ +├── {service}.go # Application entry point +├── Makefile +├── go.mod +├── go.sum +├── docker-compose.yml +└── readme.md +``` + +## Dependency Direction Rules + +``` +pkg/domain/ ← No external dependencies (innermost, pure definitions) + ↑ +pkg/domain/usecase/ ← Use Case interface (only interface definitions) +pkg/domain/repository/ ← Repository interface (only interface definitions) + ↑ +pkg/usecase/ ← Depends on domain interfaces (business logic implementation) +pkg/mock/ ← Depends on domain interfaces (test mocks) + ↑ +internal/logic/ ← Depends on usecase implementations (handler logic) +internal/server/ ← Depends on logic (HTTP/gRPC server) +internal/svc/ ← Depends on all (DI container, assemble dependencies) + ↑ +pkg/repository/ ← Depends on domain interfaces (infrastructure implementation) +``` + +``` + ┌─────────────────────────────────┐ + │ pkg/domain/ │ ← Pure definitions, no dependencies + │ ├── entity/ │ + │ ├── {module}/ (value objects)│ + │ ├── repository/ (interfaces) │ + │ ├── usecase/ (interfaces) │ + │ ├── errors.go │ + │ └── const.go │ + ├─────────────────────────────────┤ + │ pkg/usecase/ │ ← Depends on domain interfaces + │ pkg/mock/ │ ← Depends on domain interfaces + ├─────────────────────────────────┤ + │ internal/logic/ │ ← Depends on usecase + │ internal/server/ │ + │ internal/config/ │ + │ internal/svc/ │ ← DI container + ├─────────────────────────────────┤ + │ pkg/repository/ │ ← Depends on domain interfaces + └─────────────────────────────────┘ +``` + +## Architecture Principles + +### `pkg/domain/` — Pure Domain Definitions + +`pkg/domain/` is the core, containing only **interfaces and definitions**, no implementations: + +```go +// pkg/domain/entity/user.go — Entity definition +package entity + +type User struct { + ID string `json:"id"` + Email string `json:"email"` + Name string `json:"name"` + Status string `json:"status"` + CreatedAt time.Time `json:"created_at"` + UpdatedAt time.Time `json:"updated_at"` +} +``` + +```go +// pkg/domain/member/status.go — Value object (with tests) +package member + +type Status string + +const ( + StatusActive Status = "active" + StatusInactive Status = "inactive" +) + +func (s Status) IsValid() bool { + switch s { + case StatusActive, StatusInactive: + return true + } + return false +} + +func NewStatus(s string) (Status, error) { + status := Status(s) + if !status.IsValid() { + return "", fmt.Errorf("invalid status: %s", s) + } + return status, nil +} +``` + +```go +// pkg/domain/member/status_test.go — Value object tests +package member + +func TestStatus_IsValid(t *testing.T) { + assert.True(t, StatusActive.IsValid()) + assert.True(t, StatusInactive.IsValid()) + assert.False(t, Status("unknown").IsValid()) +} + +func TestNewStatus(t *testing.T) { + status, err := NewStatus("active") + assert.NoError(t, err) + assert.Equal(t, StatusActive, status) + + _, err = NewStatus("unknown") + assert.Error(t, err) +} +``` + +```go +// pkg/domain/repository/user.go — Repository interface +package repository + +type UserRepository interface { + GetByID(ctx context.Context, id string) (*entity.User, error) + GetByEmail(ctx context.Context, email string) (*entity.User, error) + Create(ctx context.Context, user *entity.User) error + Update(ctx context.Context, user *entity.User) error + Delete(ctx context.Context, id string) error +} +``` + +```go +// pkg/domain/usecase/user.go — Use Case interface +package usecase + +type UserUsecase interface { + CreateUser(ctx context.Context, input CreateUserInput) (*entity.User, error) + GetUser(ctx context.Context, id string) (*entity.User, error) + UpdateUser(ctx context.Context, id string, input UpdateUserInput) (*entity.User, error) +} +``` + +```go +// pkg/domain/errors.go — Domain sentinel errors +package domain + +import "errors" + +var ( + ErrUserNotFound = errors.New("user not found") + ErrInvalidInput = errors.New("invalid input") + ErrDuplicateEmail = errors.New("email already exists") +) +``` + +### `pkg/usecase/` — Business Logic Implementation + +One functional domain per file, test file in same directory: + +```go +// pkg/usecase/account.go — Use Case entry point +package usecase + +type AccountUsecase struct { + userRepo repository.UserRepository + accountRepo repository.AccountRepository + redis *redis.Client +} + +func NewAccountUsecase( + userRepo repository.UserRepository, + accountRepo repository.AccountRepository, + redis *redis.Client, +) *AccountUsecase { + return &AccountUsecase{ + userRepo: userRepo, + accountRepo: accountRepo, + redis: redis, + } +} +``` + +```go +// pkg/usecase/create_user.go — Single operation +package usecase + +func (uc *AccountUsecase) CreateUser(ctx context.Context, input CreateUserInput) (*entity.User, error) { + if err := input.Validate(); err != nil { + return nil, fmt.Errorf("validate input: %w", err) + } + + existing, _ := uc.userRepo.GetByEmail(ctx, input.Email) + if existing != nil { + return nil, domain.ErrDuplicateEmail + } + + user, err := entity.NewUser(input.Email, input.Password, input.Name) + if err != nil { + return nil, fmt.Errorf("create user: %w", err) + } + + if err := uc.userRepo.Create(ctx, user); err != nil { + return nil, fmt.Errorf("save user: %w", err) + } + + return user, nil +} +``` + +```go +// pkg/usecase/create_user_test.go — Test in same directory +package usecase + +func TestAccountUsecase_CreateUser_Success(t *testing.T) { + mockUserRepo := new(mock.UserRepository) + uc := NewAccountUsecase(mockUserRepo, nil, nil) + + mockUserRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockUserRepo.On("Create", mock.Anything, mock.AnythingOfType("*entity.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) + mockUserRepo.AssertExpectations(t) +} +``` + +### `pkg/mock/` — Auto-Generated Mocks + +```go +// pkg/mock/repository/user.go — Generated by mockery +//go:generate mockery --name=UserRepository --output=../../mock/repository --outpkg=mock_repository + +package mock_repository + +import ( + "github.com/stretchr/testify/mock" + "your-project/pkg/domain/repository" +) + +type UserRepository struct { + mock.Mock +} + +func (m *UserRepository) GetByID(ctx context.Context, id string) (*entity.User, error) { + args := m.Called(ctx, id) + if args.Get(0) == nil { + return nil, args.Error(1) + } + return args.Get(0).(*entity.User), args.Error(1) +} +``` + +### `internal/logic/` — Handler Logic + +One logic file per use case (go-zero style): + +```go +// internal/logic/account/create_user_logic.go +package account + +type CreateUserLogic struct { + ctx context.Context + svcCtx *svc.ServiceContext +} + +func NewCreateUserLogic(ctx context.Context, svcCtx *svc.ServiceContext) *CreateUserLogic { + return &CreateUserLogic{ + ctx: ctx, + svcCtx: svcCtx, + } +} + +func (l *CreateUserLogic) CreateUser(req *types.CreateUserReq) (*types.UserResp, error) { + user, err := l.svcCtx.UserUsecase.CreateUser(l.ctx, usecase.CreateUserInput{ + Email: req.Email, + Password: req.Password, + Name: req.Name, + }) + if err != nil { + return nil, err + } + + return &types.UserResp{ + ID: user.ID, + Email: user.Email, + Name: user.Name, + }, nil +} +``` + +### `internal/svc/` — Dependency Injection Container + +```go +// internal/svc/service_context.go +package svc + +type ServiceContext struct { + Config config.Config + UserUsecase usecase.UserUsecase + AccountUsecase usecase.AccountUsecase +} + +func NewServiceContext(c config.Config) *ServiceContext { + db := mongo.NewClient(c.Mongo.URI) + redisClient := redis.NewClient(c.Redis) + + userRepo := repository.NewUserRepository(db) + accountRepo := repository.NewAccountRepository(db) + + return &ServiceContext{ + Config: c, + UserUsecase: usecase.NewUserUsecase(userRepo, redisClient), + AccountUsecase: usecase.NewAccountUsecase(userRepo, accountRepo, redisClient), + } +} +``` + +### `pkg/repository/` — Infrastructure Implementation + +```go +// pkg/repository/user.go +package repository + +type userRepository struct { + db *mongo.Database +} + +func NewUserRepository(db *mongo.Database) domain.Repository.UserRepository { + return &userRepository{db: db} +} + +func (r *userRepository) GetByID(ctx context.Context, id string) (*entity.User, error) { + var user entity.User + err := r.db.Collection("users").FindOne(ctx, bson.M{"_id": id}).Decode(&user) + if err != nil { + if err == mongo.ErrNoDocuments { + return nil, domain.ErrUserNotFound + } + return nil, fmt.Errorf("find user by id: %w", err) + } + return &user, nil +} +``` + +```go +// pkg/repository/user_test.go +package repository + +func TestUserRepository_GetByID_Success(t *testing.T) { + db := startMongoContainer(t) + defer db.Client().Disconnect(context.Background()) + + repo := NewUserRepository(db) + // ... +} +``` + +## Coding Standards + +### File Naming + +``` +Value objects and enums: pkg/domain/{module}/{name}.go + _test.go +Entity: pkg/domain/entity/{name}.go +Repository interface: pkg/domain/repository/{name}.go +Usecase interface: pkg/domain/usecase/{module}.go +Usecase implementation: pkg/usecase/{operation}.go + _test.go +Usecase utilities: pkg/usecase/{module}_utils.go + _test.go +Repository impl: pkg/repository/{name}.go + _test.go +Mock: pkg/mock/repository/{name}.go + pkg/mock/usecase/{module}.go +Handler logic: internal/logic/{module}/{operation}_logic.go +Server: internal/server/{module}/{module}_server.go +Service Context: internal/svc/service_context.go +Protobuf definitions: generate/protobuf/{module}.proto +Config files: etc/{service}.yaml +Dockerfile: build/Dockerfile +``` + +### Naming Conventions + +```go +// Package: lowercase, semantically clear +package usecase // not usecases +package repository // not repositories +package entity // not entities + +// Entity struct: PascalCase, no suffix +type User struct { ... } // not UserModel, UserEntity + +// Value Object: base type alias + methods +type Status string // not StatusEnum + +// Interface: defined in pkg/domain/, semantic naming +type UserRepository interface { ... } // not UserRepo or UserRepositoryI + +// Use Case struct: {Module}Usecase +type AccountUsecase struct { ... } + +// Use Case methods: verb prefix +func (uc *AccountUsecase) CreateUser(ctx context.Context, ...) (*entity.User, error) +func (uc *AccountUsecase) GetUser(ctx context.Context, id string) (*entity.User, error) + +// Logic struct: {Operation}Logic +type CreateUserLogic struct { ... } + +// Error: Err prefix +var ErrUserNotFound = errors.New("user not found") + +// Constant: PascalCase (exported) or camelCase (internal) +const MaxRetryCount = 3 +const defaultPageSize = 20 +``` + +### Error Handling + +```go +// Sentinel errors — pkg/domain/errors.go +var ( + ErrUserNotFound = errors.New("user not found") + ErrInvalidInput = errors.New("invalid input") + ErrDuplicateEmail = errors.New("email already exists") +) + +// Error wrapping — always use %w +if err != nil { + return fmt.Errorf("create user: %w", err) +} + +// Error checking — always use errors.Is +if errors.Is(err, domain.ErrUserNotFound) { + // handle not found +} + +// Repository errors — pkg/repository/error.go +var ( + ErrMongoConnection = errors.New("mongo connection failed") + ErrRedisConnection = errors.New("redis connection failed") +) +``` + +### Interface Design + +```go +// Interface defined in pkg/domain/ (consumer side) +// Implementation defined in pkg/ (provider side) + +// Accept interfaces, return structs +func NewUserUsecase(repo repository.UserRepository, redis *redis.Client) *UserUsecase { + return &UserUsecase{repo: repo, redis: redis} +} + +// Keep interfaces small (1-3 methods) +type UserRepository interface { + GetByID(ctx context.Context, id string) (*entity.User, error) + Create(ctx context.Context, user *entity.User) error +} +``` + +## TDD Standards + +This skill integrates with `tdd` skill, following shared TDD principles. + +### Test Pyramid + +``` + /\ + / \ + / E2E \ <- Few critical flows + /--------\ + /Integration\ <- DB + Redis (testcontainers) + /--------------\ + / Unit Tests \ <- Most, 80%+ coverage + /--------------------\ +``` + +### Test Location + +``` +Test files in same directory as source: + +pkg/domain/member/status_test.go ← Value object tests +pkg/usecase/create_user_test.go ← Use Case tests +pkg/repository/user_test.go ← Repository tests +pkg/repository/start_mongo_container_test.go ← testcontainers startup +``` + +### Vertical Slice TDD + +Each slice follows this order: + +``` +Slice: User registration + 1. RED: Write TestStatus_IsValid (value object) + 2. GREEN: Write Status.IsValid() + 3. RED: Write TestAccountUsecase_CreateUser_Success + 4. GREEN: Write domain/entity, domain/usecase interface, pkg/usecase implementation, mock + 5. RED: Write TestAccountUsecase_CreateUser_DuplicateEmail + 6. GREEN: Add duplicate check + 7. RED: Write TestUserRepository_Create (DB test) + 8. GREEN: Write pkg/repository/user.go + 9. RED: Write TestCreateUserLogic (handler test) + 10. GREEN: Write internal/logic/account/create_user_logic.go + 11. REFACTOR: Clean up everything +``` + +### Mock Strategy + +```go +// Use mockery to auto-generate mocks +// Add go:generate directive in interface file +//go:generate mockery --name=UserRepository --output=../../mock/repository --outpkg=mock_repository + +// Unit tests use mock +func TestAccountUsecase_CreateUser_Success(t *testing.T) { + mockRepo := new(mock_repository.UserRepository) + uc := usecase.NewAccountUsecase(mockRepo, nil, nil) + + mockRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockRepo.On("Create", mock.Anything, mock.AnythingOfType("*entity.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) +} +``` + +### testcontainers Strategy + +```go +// pkg/repository/start_mongo_container_test.go +func startMongoContainer(t *testing.T) *mongo.Database { + ctx := context.Background() + req := testcontainers.ContainerRequest{ + Image: "mongo:7", + ExposedPorts: []string{"27017/tcp"}, + WaitingFor: wait.ForListeningPort("27017/tcp"), + } + + mongoC, err := testcontainers.GenericContainer(ctx, testcontainers.GenericContainerRequest{ + ContainerRequest: req, + Started: true, + }) + require.NoError(t, err) + + t.Cleanup(func() { + mongoC.Terminate(ctx) + }) + + // ... return connected database +} +``` + +### Coverage Requirements + +- Value objects (`pkg/domain/member/`): >= 90% +- Use Case (`pkg/usecase/`): >= 90% +- Repository (`pkg/repository/`): >= 80% +- Logic (`internal/logic/`): >= 80% (mainly integration tests) +- Critical paths: Integration tests required + +## Vertical Slice Template + +File list for each vertical slice: + +``` +Slice: {operation}_{entity} + +New/modified files: +├── pkg/domain/entity/{entity}.go ← Entity definition +├── pkg/domain/member/{value_object}.go ← Value object (if needed) +├── pkg/domain/member/{value_object}_test.go ← Value object tests +├── pkg/domain/repository/{entity}.go ← Repository interface +├── pkg/domain/usecase/{module}.go ← Use Case interface +├── pkg/usecase/{operation}.go ← Use Case implementation +├── pkg/usecase/{operation}_test.go ← Use Case tests +├── pkg/mock/repository/{entity}.go ← Repository mock +├── pkg/repository/{entity}.go ← Repository implementation +├── pkg/repository/{entity}_test.go ← Repository tests +├── internal/logic/{module}/{operation}_logic.go ← Handler logic +└── internal/svc/service_context.go ← Update DI +``` + +## Completion Checklist + +### After Each Slice +- [ ] Value object tests pass +- [ ] Use Case tests pass +- [ ] Repository tests pass (with DB) +- [ ] Error handling complete +- [ ] Dependency direction correct (domain has no external dependencies) + +### After All Complete +- [ ] Project structure follows Domain-Driven + go-zero style +- [ ] `pkg/domain/` contains all Entity, Value Object, interface definitions +- [ ] `pkg/usecase/` contains all business logic implementations +- [ ] `pkg/repository/` contains all infrastructure implementations +- [ ] `internal/logic/` contains all Handler logic +- [ ] `internal/svc/` contains complete dependency injection setup +- [ ] Unit tests >= 80% coverage +- [ ] Business logic >= 90% coverage +- [ ] Integration tests pass (critical paths) +- [ ] Error handling consistent and uses `%w` wrapping + +## Related Skills + +- **Prerequisite**: `prd-to-plan` (implementation plan), `be-api-design` (API spec), `dba-schema` (DB Schema) +- **辅助**: `tdd` (TDD Red-Green-Refactor process), `design-an-interface` (interface design) +- **Follow-up**: `qa` (QA testing) + +## Rollback Mechanism + +``` +QA failed (Stage 10) + ↓ +Orchestrator re-assigns fix task + ↓ +Backend Agent fixes bug + adds regression test + ↓ +Re-enter QA (Stage 10) + +Code Review rejected (Stage 10) + ↓ +Handle PR feedback + ↓ +Re-enter QA (Stage 10) for verification + +Implementation plan not feasible + ↓ +Return to Task Breakdown (Stage 8) for re-decomposition diff --git a/skills/prd-to-plan/SKILL.md b/skills/prd-to-plan/SKILL.md new file mode 100644 index 0000000..d08338e --- /dev/null +++ b/skills/prd-to-plan/SKILL.md @@ -0,0 +1,203 @@ +--- +name: prd-to-plan +description: "Converts PRD into a multi-phase implementation plan using vertical slices (tracer bullets). Orchestrator uses this skill at Stage 8 to produce implementation plans for Stage 9 Backend/Frontend Agent implementation. Trigger: After Design Review passes, when Orchestrator performs Task Breakdown." +--- + +# /prd-to-plan — PRD to Implementation Plan + +Orchestrator uses this skill to convert PRD into vertical slice implementation plans. + +## Responsibilities + +1. Confirm PRD content is complete and in context +2. Explore existing codebase to understand architecture and patterns +3. Identify persistent architectural decisions across phases +4. Decompose PRD into vertical slices (tracer bullets) +5. Confirm slice granularity with user +6. Produce implementation plan document + +## Input + +- PRD document (`docs/prd/{date}-{feature}.md`) +- API specification (`docs/api/{date}-{feature}.yaml`) +- DB Schema (`docs/db/{date}-{feature}.sql`) +- Design documents (`docs/design/{date}-{feature}/`) + +## Output + +- Implementation plan: `./plans/{feature}.md` + +## Process + +``` +Confirm PRD in context + ↓ +Explore codebase (architecture, patterns, integration layers) + ↓ +Identify persistent architectural decisions (routes, schema, models, auth) + ↓ +Draft vertical slice decomposition + ↓ +Confirm slice granularity with user + ↓ +Iterate until user approves + ↓ +Write plan file +``` + +### Step Details + +**1. Confirm PRD in context** + +The PRD should already be in the conversation. If not, ask the user to paste or point to the file. + +**2. Explore codebase** + +If the codebase hasn't been explored yet, explore to understand: +- Current architectural patterns +- Existing code conventions +- Integration layers (DB, API, external services) +- Existing test patterns + +**3. Identify persistent architectural decisions** + +Before slicing, identify high-level decisions unlikely to change during implementation: + +- Route structure / URL patterns +- Database schema shape +- Key data models +- Authentication / authorization approach +- Third-party service boundaries + +Write these decisions in the plan file header for all phases to reference. + +**4. Draft vertical slices** + +Decompose PRD into **tracer bullet** phases. Each phase is a thin vertical slice cutting through all integration layers end-to-end, **not** horizontal slicing. + +**Vertical slice principles:** + +- Each slice delivers a narrow but complete path through all layers (schema, API, usecase, logic, tests) +- Completed slices can be demonstrated or verified independently +- Prefer multiple thin slices over few thick slices +- Don't include specific filenames, function names, or implementation details that may change with subsequent phases +- Include persistent decisions: route paths, schema shapes, data model names + +**Horizontal slice (wrong) vs Vertical slice (correct):** + +``` +❌ Horizontal slice: + Phase 1: All domain entities + Phase 2: All usecases + Phase 3: All API handlers + Phase 4: All repository implementations + +✅ Vertical slice (tracer bullets): + Phase 1: User registration (entity + usecase + handler + repo + tests) + Phase 2: User login (same) + Phase 3: User list (same) + Phase 4: User profile update (same) +``` + +**5. Confirm with user** + +Present decomposition as a numbered list, each phase containing: + +- **Title**: Brief descriptive name +- **User stories covered**: Which user stories from PRD this maps to + +Ask the user: +- How does the granularity feel? (too coarse / too fine) +- Need to merge or split any phases? + +Iterate until user approves. + +**6. Write plan file** + +Create `./plans/` directory (if it doesn't exist). Write Markdown file. + +## Plan Template + +```markdown +# Plan: {Feature Name} + +> Source PRD: {PRD link or identifier} +> Source API: {API specification link} +> Source DB Schema: {DB Schema link} + +## Architectural Decisions + +Persistent decisions across all phases: + +- **Routes**: {API route structure} +- **Schema**: {database schema shape} +- **Key models**: {key data models} +- **Auth**: {authentication/authorization approach} +- **Third-party services**: {external service boundaries} + +--- + +## Phase 1: {Title} + +**User stories**: {list of user stories from PRD} + +### What to build + +End-to-end behavior description for this vertical slice. Describe complete behavior, not layer-by-layer implementation details. + +### Acceptance criteria + +- [ ] Acceptance criteria 1 +- [ ] Acceptance criteria 2 +- [ ] Acceptance criteria 3 + +--- + +## Phase 2: {Title} + +**User stories**: {list of user stories from PRD} + +### What to build + +... + +### Acceptance criteria + +- [ ] ... + +--- + + +``` + +## Role in Vibe-Kanban + +``` +Stage 7: Design Review passes + ↓ +Stage 8: Task Breakdown (Orchestrator uses prd-to-plan) + ↓ +Output ./plans/{feature}.md + ↓ +Stage 9: Implementation (Backend/Frontend Agent implements according to plan) +``` + +Orchestrator will parse the plan and: +1. Identify frontend and backend tasks +2. Assign to corresponding agents +3. May trigger parallel task distribution + +## Dependent Skills + +- **Prerequisite**: `write-a-prd` (PRD complete), `be-api-design` (API spec), `dba-schema` (DB Schema), `design-review` (design review passed) +- **Follow-up**: `go-backend-dev` (Backend implementation), frontend implementation skill + +## Rollback Mechanism + +``` +Implementation plan infeasible + ↓ +Rollback to Stage 7 (Design Review) for re-review + or +Rollback to Stage 4 (API Design) to adjust design +``` \ No newline at end of file diff --git a/skills/tdd/SKILL.md b/skills/tdd/SKILL.md new file mode 100644 index 0000000..294fbc2 --- /dev/null +++ b/skills/tdd/SKILL.md @@ -0,0 +1,296 @@ +--- +name: tdd +description: "Backend Agent uses this skill for Test-Driven Development. Follows Red-Green-Refactor cycle and vertical slicing principles, ensuring tests cover behavior rather than implementation details. Trigger: Implementation phase (Stage 9), integrated with go-backend-dev skill." +--- + +# /tdd — Test-Driven Development + +Backend Agent uses this skill for Test-Driven Development. + +## Core Philosophy + +**Test behavior, not implementation details.** + +Good tests verify behavior through public interfaces, describing the system "what" it does, not "how" it does it. Tests still pass after refactoring. + +Bad tests are coupled to implementation: mocking internal collaborators, testing private methods. Tests fail after refactoring, but behavior hasn't changed. + +## Anti-Pattern: Horizontal Slicing + +**Don't write all tests first, then all implementations.** This is "horizontal slicing": + +``` +❌ Wrong way: + RED: test1, test2, test3, test4, test5 + GREEN: impl1, impl2, impl3, impl4, impl5 + +✅ Correct way (vertical slicing): + RED→GREEN: test1 → impl1 + RED→GREEN: test2 → impl2 + RED→GREEN: test3 → impl3 +``` + +Horizontal slicing produces low-quality tests: +- Tests written early verify "imagined" behavior, not "actual" behavior +- Tests become validators of data structures and function signatures, not user-observable behavior +- Tests are insensitive to real changes — they pass when behavior is broken, fail when behavior hasn't changed but after refactoring + +## Flow + +``` +Confirm interface changes and test scope + ↓ +Write first test (tracer bullet) + ↓ +RED: Test fails + ↓ +GREEN: Write minimal code to make test pass + ↓ +Write next test + ↓ +RED → GREEN loop + ↓ +All behavior tests complete + ↓ +REFACTOR: Refactor + ↓ +Confirm all tests still pass +``` + +### Step Details + +**1. Planning** + +Before writing any code: +- [ ] Confirm which interface changes are needed with user +- [ ] Confirm which behaviors need testing (prioritize) +- [ ] Identify opportunities for deep modules (small interface, deep implementation) +- [ ] Design interfaces for testability +- [ ] List behaviors to test (not implementation steps) +- [ ] Get user approval for test plan + +Ask: "What should the public interface look like? Which behaviors are most important to test?" + +**You cannot test everything.** Confirm with user which behaviors are most important, focus testing effort on critical paths and complex logic, not every possible edge case. + +**2. Tracer Bullet** + +Write a test that confirms one thing about the system: + +``` +RED: Write first behavior test → Test fails +GREEN: Write minimal code to make test pass → Test passes +``` + +This is your tracer bullet — proving the end-to-end path works. + +**3. Incremental Loop** + +For each remaining behavior: + +``` +RED: Write next test → Fails +GREEN: Minimal code to make test pass → Passes +``` + +Rules: +- One test at a time +- Write only enough code to make current test pass +- Don't predict future tests +- Tests focus on observable behavior + +**4. Refactoring** + +After all tests pass, look for refactoring candidates: +- [ ] Extract duplicate logic +- [ ] Deepen modules (move complexity behind simple interfaces) +- [ ] Apply SOLID principles naturally +- [ ] Consider what new code reveals about existing code problems +- [ ] Run tests after each refactoring step + +**Never refactor while in RED state. Get back to GREEN first.** + +## Good Tests vs Bad Tests + +### Good Tests + +**Integration style**: Test through real interfaces, not mocking internal parts. + +```go +// GOOD: Test observable behavior +func TestUserUsecase_CreateUser_Success(t *testing.T) { + mockRepo := new(mock.UserRepository) + uc := NewUserUsecase(mockRepo, logger) + + mockRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockRepo.On("Create", mock.Anything, mock.AnythingOfType("*domain.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) + assert.Equal(t, "test@example.com", user.Email) +} +``` + +Characteristics: +- Tests behavior that users/callers care about +- Uses only public APIs +- Tests still pass after internal implementation refactoring +- Describes "what" instead of "how" +- One logical assertion per test + +### Bad Tests + +**Implementation detail testing**: Coupled to internal structure. + +```go +// BAD: Test implementation details +func TestUserUsecase_CreateUser_CallsRepoCreate(t *testing.T) { + mockRepo := new(mock.UserRepository) + uc := NewUserUsecase(mockRepo, logger) + + uc.CreateUser(context.Background(), input) + + // This tests "how" instead of "what" + mockRepo.AssertCalled(t, "Create", mock.Anything, mock.Anything) +} +``` + +Red flags: +- Mocking internal collaborators just to verify they were called +- Testing private methods +- Asserting call counts or order +- Tests fail after refactoring but behavior unchanged +- Test names describe "how" instead of "what" + +```go +// BAD: Bypass interface validation +func TestCreateUser_SavesToDatabase(t *testing.T) { + CreateUser(ctx, input) + row := db.QueryRow("SELECT * FROM users WHERE name = $1", "Alice") + // Direct database query, bypassing public interface +} + +// GOOD: Validate through interface +func TestCreateUser_MakesUserRetrievable(t *testing.T) { + user, _ := CreateUser(ctx, input) + retrieved, _ := GetUser(ctx, user.ID) + assert.Equal(t, "Alice", retrieved.Name) + // Validate behavior through public interface +} +``` + +## Golang Testing Standards + +### Test Naming + +```go +// Test{Unit}_{Scenario} +func TestUserUsecase_CreateUser_Success(t *testing.T) {} +func TestUserUsecase_CreateUser_InvalidEmail(t *testing.T) {} +func TestUserUsecase_CreateUser_Duplicate(t *testing.T) {} +``` + +### Test Pyramid + +``` + /\ + / \ + / E2E \ <- Few critical flows + /--------\ + /Integration\ <- API + DB + /--------------\ + / Unit Tests \ <- Most, 80%+ coverage + /--------------------\ +``` + +### Mock Strategy + +Only mock at **system boundaries**: +- External APIs (payments, email, etc.) +- Database (sometimes — prefer test DB) +- Time/randomness +- File system (sometimes) + +Don't mock: +- Your own classes/modules +- Internal collaborators +- Things you can control + +```go +// Use mockery to auto-generate mocks +//go:generate mockery --name=UserRepository + +// Unit tests use mock repo +func TestUserUsecase_CreateUser_Success(t *testing.T) { + mockRepo := new(mock.UserRepository) + uc := NewUserUsecase(mockRepo, logger) + + mockRepo.On("GetByEmail", mock.Anything, "test@example.com").Return(nil, nil) + mockRepo.On("Create", mock.Anything, mock.AnythingOfType("*domain.User")).Return(nil) + + user, err := uc.CreateUser(context.Background(), input) + + assert.NoError(t, err) + assert.NotNil(t, user) +} +``` + +## Interface Design for Testability + +Good interfaces make testing natural: + +**1. Accept dependencies, don't create them** + +```go +// Testable +func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput, repo UserRepository) (*User, error) {} + +// Hard to test +func (s *UserService) CreateUser(ctx context.Context, input CreateUserInput) (*User, error) { + repo := postgres.NewUserRepository(db) // Creates dependency +} +``` + +**2. Return results, don't produce side effects** + +```go +// Testable +func CalculateDiscount(cart *Cart) Discount {} + +// Hard to test +func ApplyDiscount(cart *Cart) { + cart.Total -= discount // Mutates input +} +``` + +**3. Small interface surface area** +- Fewer methods = fewer tests to write +- Fewer parameters = simpler test setup + +## Checklist for Each Cycle + +``` +[ ] Test describes behavior, not implementation +[ ] Test uses only public interfaces +[ ] Test still passes after internal refactoring +[ ] Code is minimal implementation to make current test pass +[ ] No speculative features +``` + +## Refactoring Candidates + +After TDD cycle completes, look for: +- **Duplicate logic** → Extract function/class +- **Too long methods** → Split into private helpers (keep tests on public interface) +- **Shallow modules** → Merge or deepen +- **Feature envy** → Move logic to where the data is +- **Primitive obsession** → Introduce value objects +- **New code revealing existing code problems** + +## Related Skills + +- **Prerequisite**: `go-backend-dev` (used in implementation) +- **辅助**: `design-an-interface` (design interfaces for testability) +- **Follow-up**: `qa` (QA testing)