Skip to content

README.zh-TW.md

Latest commit

 

History

History
318 lines (238 loc) · 7.78 KB

README.zh-TW.md

File metadata and controls

318 lines (238 loc) · 7.78 KB

Kiro TDD Workflow

🎯 基於測試驅動開發 (TDD) 的完整工作流程工具，支援多種現代前端框架。

特色功能

  • 📝 四階段 TDD 流程 - 設計 → 測試 → 實作 → 驗證
  • 🎨 完整設計模板 - 標準化的功能設計文件
  • 🧪 測試驅動開發 - 確保程式碼品質和功能正確性
  • ⚙️ 開發準則整合 - DRY、KISS 原則，TypeScript 嚴格模式
  • 🌍 國際化支援 - 完整的 i18n 規劃和實作
  • 🎭 主題系統 - CSS 變數系統，支援 dark/light 主題
  • 📱 響應式設計 - 移動端優先的設計原則

快速開始

安裝使用

# 在專案中初始化 TDD 工作流程
npx kiro-tdd-workflow init

# 設定框架類型和開發準則
npx kiro-tdd-workflow setup

# 或使用互動式安裝
npx kiro-tdd-workflow

AI 助手整合

初始化完成後，使用 .kiro/dev/ai-initialization-guide.md 與你的 AI 助手確認設定：

  1. 複製 ai-initialization-guide.md 的內容
  2. 貼給你的 AI 助手（如 Claude、ChatGPT、Kiro 等）
  3. AI 會幫你檢查缺少的文件和配置
  4. 根據建議完成剩餘設定
  5. 開始使用 TDD 工作流程

基本使用

# 1. 初始化工作流程
npx kiro-tdd-workflow init

# 2. 設定框架類型（可選）
npx kiro-tdd-workflow setup
# 可以選擇預設模板或跳過建立空白文件

# 3. 與 AI 確認設定
# 將 .kiro/dev/ai-initialization-guide.md 內容複製給 AI 助手

# 4. 開始開發新功能
# 在你的 AI 助手中使用：
「設計 useNotification composable」

# 5. 按照四階段流程開發
「撰寫測試」    # 階段 1
「實作功能」    # 階段 2  
「執行測試」    # 階段 3

TDD 四階段流程

階段 0: 設計規劃 📝

  • 需求分析與方案討論
  • 產生完整的功能設計文件
  • 遵循所有開發準則和最佳實踐

階段 1: 撰寫測試 🧪

  • 根據設計文件撰寫 unit test
  • 測試應該失敗（Red）
  • 使用 Vitest 測試框架

階段 2: 實作功能 ⚙️

  • 根據設計文件實作功能
  • 讓測試通過（Green）
  • 遵循 DRY、KISS 原則

階段 3: 執行測試與重構 ✅

  • 執行測試確認通過
  • 重構優化程式碼（Refactor）
  • 功能開發完成

目錄結構

初始化後會在專案中建立以下結構：

.kiro/
├── dev/
│   ├── README.md                    # 工作流程說明
│   ├── tdd-workflow.md              # 完整流程文件
│   ├── design-template.md           # 設計文件模板
│   ├── ai-initialization-guide.md   # AI 初始化指南
│   └── designs/                     # 功能設計文件目錄
│       └── README.md
└── steering/
    └── development.md               # 開發準則與最佳實踐

核心原則

DRY 原則 (Don't Repeat Yourself)

  • 抽取共用邏輯到 composables
  • 建立可重用的 UI 組件
  • 統一的 API 呼叫方式
  • 避免重複的樣式定義

KISS 原則 (Keep It Simple, Stupid)

  • 優先選擇簡單直接的解決方案
  • 避免過度抽象和複雜設計
  • 組件職責單一，易於理解
  • 函數長度 < 50 行，巢狀 < 3 層

TypeScript 嚴格模式

  • 避免使用 any 類型
  • 完整的 Props 和 API 介面定義
  • 明確的函數返回類型
  • 適當的類型組織策略

支援的技術棧

前端框架

  • ✅ React + Next.js - App Router，Shadcn/ui 組件
  • ✅ Vue 3 + Nuxt 3 - 組合式 API，SSR 支援
  • ✅ Vue 3 + Vite - 輕量化開發環境
  • ✅ TypeScript - 嚴格類型檢查，通用專案支援

UI 組件庫

  • ✅ Shadcn/ui - React 生態系統
  • ✅ Shadcn Vue - Vue 生態系統
  • ✅ CSS 變數系統 - 主題化設計
  • ✅ 響應式設計 - 移動端優先

測試框架

  • ✅ Vitest - Vue 專案快速測試
  • ✅ Jest + Testing Library - React 專案測試
  • ✅ @vue/test-utils - Vue 組件測試
  • ✅ 測試驅動開發 - 完整 TDD 流程

狀態管理

  • ✅ Pinia - Vue 3 官方狀態管理
  • ✅ Zustand/Redux - React 狀態管理
  • ✅ 組合式 API - 現代化狀態管理

國際化

  • ✅ Vue i18n - Vue 多語言支援
  • ✅ Next.js i18n - React 國際化
  • ✅ 完整翻譯規劃 - 英文/中文支援

使用範例

Vue 專案 - 開發 Composable

# 階段 0: 設計
「設計一個 useNotification composable」
# → 建立 .kiro/dev/designs/use-notification-composable.md

# 階段 1: 測試
「撰寫測試」
# → 建立 composables/__tests__/useNotification.test.ts

# 階段 2: 實作
「實作功能」
# → 建立 composables/useNotification.ts

# 階段 3: 驗證
「執行測試」
# → 執行測試並確認通過

React 專案 - 開發 Custom Hook

# 階段 0: 設計
「設計一個 useNotification hook」
# → 建立 .kiro/dev/designs/use-notification-hook.md

# 階段 1: 測試
「撰寫測試」
# → 建立 hooks/__tests__/useNotification.test.ts

# 階段 2: 實作
「實作功能」
# → 建立 hooks/useNotification.ts

# 階段 3: 驗證
「執行測試」
# → 執行測試並確認通過

開發 UI 組件

# 階段 0: 設計
「設計一個 StatusBadge 組件」
# → 建立 .kiro/dev/designs/status-badge-component.md

# 階段 1: 測試
「撰寫測試」
# → React: components/__tests__/StatusBadge.test.tsx
# → Vue: components/UI/__tests__/StatusBadge.test.ts

# 階段 2: 實作
「實作功能」
# → React: npx shadcn-ui@latest add badge
# → Vue: npx shadcn-vue@latest add badge
# → 建立對應的組件檔案

# 階段 3: 驗證
「執行測試」
# → 執行測試並確認通過

指令參考

CLI 指令

# 初始化專案
npx kiro-tdd-workflow init

# 互動式設定
npx kiro-tdd-workflow setup

# 顯示使用指南
npx kiro-tdd-workflow help-guide

# 互動式選單
npx kiro-tdd-workflow

AI 助手指令

# 完整 TDD 流程
「設計 [功能名稱]」        # 階段 0: 設計規劃
「撰寫測試」              # 階段 1: 撰寫測試
「實作功能」              # 階段 2: 實作功能
「執行測試」              # 階段 3: 執行測試

# 簡化流程（適用於簡單修復）
「修復 Bug：[問題描述]」
「調整 UI：[調整內容]」
「加入功能：[簡短描述]」

# 其他指令
「調整設計」
「重構程式碼」
「查看設計文件」

開發檢查清單

新功能開發

  • 遵循 DRY 原則（避免重複程式碼）
  • 遵循 KISS 原則（保持簡單直觀）
  • 使用 CSS 變數（禁止硬編碼顏色）
  • 所有文字使用 i18n（t() 函數）
  • TypeScript 類型定義完整
  • 組件使用組合式 API
  • 響應式設計（Media Queries）
  • 函數職責單一，長度 < 50 行
  • 避免過深巢狀（< 3 層）

UI 組件開發

  • 優先檢查 Shadcn Vue 組件
  • 檢查專案現有組件
  • 使用 CSS 變數確保主題一致性
  • 支援 dark/light 主題切換
  • 組件 props < 10 個
  • 可訪問性（a11y）考量

貢獻指南

歡迎提交 Issue 和 Pull Request！

本地開發

# 安裝依賴
npm install

# 開發模式
npm run dev

# 建置
npm run build

# 測試
npm test

授權

MIT License - 詳見 LICENSE 文件。

相關連結

支援

如有問題或建議：

  1. 查看 .kiro/dev/tdd-workflow.md 完整流程說明
  2. 參考 .kiro/dev/design-template.md 設計模板
  3. 閱讀 .kiro/steering/development.md 開發準則
  4. 提交 GitHub Issue

讓 TDD 成為你的開發習慣，提升程式碼品質和開發效率！ 🚀