每個開發者都經歷過這種時刻：

腦海中：「我要做一個超酷的功能！」
↓
打開 IDE：「呃...從哪裡開始？」
↓
2 小時後：「我剛剛想做什麼來著？」

想法很豐滿，執行很骨感。

這中間的鴻溝，就是缺少了一個關鍵環節：任務規劃。

Task 文件：想法的具象化

Task 文件不只是一個待辦事項。

它是執行藍圖，提供詳細的實作指引。它定義驗收標準，說明什麼叫「完成」。它記錄思考過程，解釋為什麼這樣做。它也是知識地圖，未來可以回顧的經驗。

任務的兩種類型：FR vs BUG

功能需求（FR - Functional Requirement）

當你要創造新東西時：

0001_fr_user_authentication.md    # 新增使用者認證
0003_fr_add_project.md            # 新增專案管理功能
0006_fr_database_migration_system.md  # 建立資料庫遷移系統

錯誤修復（BUG - Bug Fix）

當你要修復問題時：

0002_bug_memory_leak_fix.md       # 修復記憶體洩漏
0004_bug_special_char_crash.md    # 修復特殊字元導致崩潰

一個優秀的 Task 文件

讓我用實際案例 0006_fr_database_migration_system.md 來展示什麼是好的 Task 文件：

1. 標題與狀態：一目了然

# 功能需求：資料庫 Migration 系統

## 狀態
開發中

## 更新歷程
- 2025-01-11：建立需求文件
- 2025-01-12：開始實作
- 2025-01-13：完成初版，測試中

設計要點：

• 清楚的標題說明要做什麼
• 視覺化的狀態標記
• 時間軸記錄進展

2. 需求概述：Why 比 What 重要

## 需求概述

### 背景
專案需要支援資料庫架構的演進，包括：
- 新增表格和欄位
- 修改現有結構
- 資料轉換和遷移

### 問題陳述
目前沒有 migration 機制，每次架構變更都需要：
1. 手動刪除資料庫
2. 重新建立
3. 資料會遺失

### 解決方案
實作 SQLDelight 2.0+ 的 migration 系統，支援：
- 版本化的 schema 管理
- 自動 migration 執行
- 向後相容性保證

設計要點：

• 說明背景和動機
• 明確指出問題
• 提出解決方案

3. 使用案例：具體場景

## 使用案例

### UC1: 首次啟動
```mermaid
sequenceDiagram
    participant App
    participant MigrationHelper
    participant SQLDelight
    
    App->>MigrationHelper: initDatabase()
    MigrationHelper->>SQLDelight: Schema.create()
    SQLDelight-->>MigrationHelper: Database v1 created
    MigrationHelper-->>App: Database ready

UC2: 版本升級

當用戶從 v1 升級到 v2：

1. 偵測當前版本（v1）
2. 找到需要的 migration（1.sqm）
3. 執行 migration
4. 更新版本號到 v2

**設計要點**：
- 用流程圖視覺化
- 列出關鍵場景
- Step by step 說明

### 4. 技術設計：How 的細節

```markdown
## 技術設計

### 架構決策
- 使用 SQLDelight 2.0+ 內建 migration 功能
- 採用 `deriveSchemaFromMigrations = true`
- Migration 檔案放在 `migrations/` 目錄

### 實作細節

#### MigrationHelper.kt
```kotlin
class MigrationHelper {
    suspend fun migrate(driver: SqlDriver) {
        val currentVersion = getCurrentVersion(driver)
        val targetVersion = Schema.version
        
        if (currentVersion == 0L) {
            Schema.create(driver).await()
        } else if (currentVersion < targetVersion) {
            Schema.migrate(driver, currentVersion, targetVersion).await()
        }
    }
}

目錄結構

shared/src/commonMain/sqldelight/
├── migrations/
│   ├── 1.sqm    # v0 → v1
│   ├── 2.sqm    # v1 → v2
│   └── 3.sqm    # v2 → v3
└── dev/grimo/
    └── Project.sq

**設計要點**：
- 關鍵技術決策
- 程式碼範例
- 檔案結構說明

### 5. 驗收標準：Definition of Done

```markdown
## 驗收標準

### 功能性需求
- [ ] 新安裝能自動建立資料庫
- [ ] 舊版本能自動升級
- [ ] Migration 失敗能 rollback
- [ ] 支援跳版本升級（v1→v3）

### 非功能性需求
- [ ] Migration 執行時間 < 5 秒
- [ ] 錯誤訊息清楚明確
- [ ] 有完整的單元測試
- [ ] 文件更新完成

### 測試案例
1. **Test_FirstInstall**: 全新安裝建立 v3 資料庫
2. **Test_UpgradeV1toV3**: 從 v1 升級到 v3
3. **Test_MigrationFailure**: Migration 失敗的處理
4. **Test_DataIntegrity**: 升級後資料完整性

設計要點：

• 可檢查的清單
• 功能與非功能分離
• 具體的測試案例

6. 實作解決方案：事後記錄

## 實作解決方案

### 實際實作
最終採用 SQLDelight 2.0.2 的新 API：

1. **Schema 自動衍生**
   - 設定 `deriveSchemaFromMigrations = true`
   - Schema 從 .sqm 檔案自動產生

2. **非同步執行**
   - 使用 `generateAsync = true`
   - Migration 用 coroutines 執行

3. **版本管理**
   - 使用 PRAGMA user_version
   - 不需要額外的版本表

### 遇到的挑戰
1. **問題**：文件過時，很多範例還是舊版 API
   **解決**：查看 GitHub issues 和原始碼

2. **問題**：Migration 檔案格式不明確
   **解決**：參考官方測試案例

### 學到的經驗
- SQLDelight 2.0+ 的 migration 比想像中簡單
- 官方文件有時落後於實作
- GitHub issues 是很好的學習資源

設計要點：

• 記錄實際做法
• 分享踩坑經驗
• 總結學習心得

Task 撰寫的黃金法則

1. SMART 原則

• Specific（具體）：明確說明要做什麼
• Measurable（可衡量）：有清楚的驗收標準
• Achievable（可達成）：在能力範圍內
• Relevant（相關）：符合專案目標
• Time-bound（有時限）：預估完成時間

2. 5W1H 框架

• What：要做什麼功能？
• Why：為什麼要做？
• Who：誰負責？誰受益？
• When：什麼時候開始和完成？
• Where：在哪個模組實作？
• How：如何實作？

3. 三段式結構

## 前段：定義問題
- 背景說明
- 問題陳述
- 影響範圍

## 中段：設計方案
- 技術選型
- 架構設計
- 實作步驟

## 後段：驗證完成
- 驗收標準
- 測試計畫
- 文件更新

實戰技巧：Task 文件的進化

V1：簡單記錄

# TODO: 加個資料庫 migration

V2：基本結構

# 資料庫 Migration

## 需求
需要支援資料庫升級

## 方案
用 SQLDelight migration

V3：完整規劃

# 功能需求：資料庫 Migration 系統

## 需求概述
[背景、問題、方案]

## 使用案例
[具體場景、流程圖]

## 技術設計
[架構、程式碼、細節]

## 驗收標準
[功能、非功能、測試]

V4：知識沉澱

[V3 的內容]

## 實作解決方案
[實際做法、挑戰、經驗]

Task 與 AI 協作

我：請實作 0006_fr_database_migration_system
AI：我看到任務文件，了解需要：
    1. 使用 SQLDelight 2.0+ migration
    2. 支援自動升級
    3. 實作 MigrationHelper
    現在開始實作...

AI 寫 Task：結構化思考

我：幫我規劃一個新功能的 Task
AI：我會按照 FR 模板創建：
    - 需求分析
    - 使用案例
    - 技術設計
    - 驗收標準

雙向優化的結果很明顯。人類提供業務邏輯和需求，AI 補充技術細節和範例，最後得到更完整的 Task 文件。

常見錯誤

太模糊的描述：「做一個好用的功能」，這種需求沒人知道怎麼做。

太技術的說明：「實作 AbstractSingletonProxyFactoryBean」，完全不知道為什麼要做這個。

沒有驗收標準：「做完就好」，什麼叫做完？

缺少背景說明：「加個按鈕」，為什麼要加？解決什麼問題？

Task 管理的最佳實踐

1. 及時更新狀態

# 每天檢查
grep "## 狀態" docs/tasks/*.md | grep "🟡"

2. 定期回顧

每週五花 30 分鐘：

• 檢查進行中的任務
• 更新完成的任務
• 規劃下週任務

3. 知識萃取

完成任務後：

1. 更新「實作解決方案」
2. 提取可重用的模式
3. 更新相關文件

4. 版本控制

# Task 也要進版控
git add docs/tasks/0007_fr_new_feature.md
git commit -m "task: 新增用戶管理功能任務"

Task 是思考的結晶

一個好的 Task 文件就像是合約，明確定義要交付什麼。就像地圖，指引如何到達目的地。就像教科書，記錄知識和經驗。就像橋樑，連接想法和實作。

對一人公司來說，Task 文件特別重要。

你需要在不同任務間切換。你需要記住為什麼要做某件事。你需要累積可重用的經驗。你還要讓 AI 助手理解需求。

花在規劃上的時間，會在執行時加倍返還。

今日金句

「模糊的任務產生模糊的結果，清晰的規劃帶來精準的執行。」

關於作者：Sam，一人公司創辦人。正在打造 Grimo，一個智能任務管理和分配平台。

專案連結：GitHub - grimostudio