實戰背景

quick-flow 是 Superpowers 內建的四個 workflow 之一，專門處理「小任務」。它把四個 skills 按順序串起來：

brainstorming → writing-plans → test-driven-development → verification-before-completion

這個範例會用 quick-flow 走完一圈，目標是一個具體的小功能：為一個 TypeScript 計算機 module 加上「百分比」函式。

假設 module 已有 add(a, b) 與 multiply(a, b) 兩個純函式。現在要加一個 percent(total, percentValue)，例如 percent(200, 10) 要回傳 20。

第 1 步：brainstorming 探索做法

觸發：

使用 brainstorming skill，為計算機加 percent 函式，回傳 total 的 percentValue 百分比

AI 回應摘要：

## 三個方向

### A：percent(total, percentValue) → number
- 簡單、與既有 add / multiply 同形式

### B：回傳 { value, formula }
- 多回公式字串方便顯示，但跟既有 API 風格不一致

### C：鏈式 API calc(200).percent(10)
- 物件導向，但改動範圍大，超出小任務

### 建議：A，最小改動，與既有 API 一致。

決定走 A，進入下一步。

第 2 步：writing-plans 拆成階段

觸發：

使用 writing-plans skill，把 percent 函式實作拆成階段

AI 回應摘要：

## 實作計畫

### 階段 1：核心邏輯
- 實作 percent(total, percentValue)
- 驗收：percent(200, 10) === 20

### 階段 2：零邊界
- 處理 total 或 percentValue 為 0
- 驗收：percent(0, 10) === 0、percent(200, 0) === 0

### 階段 3：負數處理
- 決定負數 percentValue 的行為
- 驗收：percent(200, -10) 應丟錯（討論後決定）

第 3 步：TDD 紅 → 綠 → 重構

test-driven-development skill 走的是三階段循環：紅、綠、重構。

紅：先寫會失敗的測試

// tests/calc.test.ts
import { describe, it, expect } from 'vitest';
import { percent } from '../src/calc';

describe('percent', () => {
  it('回傳 total 的 percentValue 百分比', () => {
    expect(percent(200, 10)).toBe(20);
  });
});

跑 vitest → 失敗，因為 percent 還沒實作。這是預期的紅燈。

綠：寫最小通過的實作

// src/calc.ts（新增）
export function percent(total: number, percentValue: number): number {
  return (total * percentValue) / 100;
}

跑 vitest → 通過。綠燈。注意這個實作故意不處理負數，因為紅綠階段只求「最小通過」。

重構：改善程式碼而不改行為

目前核心邏輯夠簡潔，但計畫階段 3 要求處理負數。討論後決定丟錯，於是加上守護並補測試：

// src/calc.ts（更新）
export function percent(total: number, percentValue: number): number {
  if (percentValue < 0) {
    throw new Error('percentValue 不可為負數');
  }
  return (total * percentValue) / 100;
}

// tests/calc.test.ts（補測試）
it('負數 percentValue 應丟錯', () => {
  expect(() => percent(200, -10)).toThrow();
});

it('零邊界', () => {
  expect(percent(0, 10)).toBe(0);
  expect(percent(200, 0)).toBe(0);
});

跑 vitest → 三條測試全綠。

第 4 步：verification-before-completion 收尾

最後一個 skill 強制「證明完成」，不是「宣稱完成」。

觸發：

使用 verification-before-completion skill，驗證 percent 函式完成

AI 回應摘要：

## 驗收清單

### 測試
- 3 條測試全綠（核心、零邊界、負數）✓
- vitest run，exit code 0 ✓

### 建置
- pnpm run build 通過 ✓
- 無 TypeScript 錯誤 ✓

### 實際操作
- 手動呼叫 percent(200, 10) → 20 ✓
- 手動呼叫 percent(0, 10) → 0 ✓
- 手動呼叫 percent(200, -10) → 丟錯 ✓

三個面向都過，這個小功能才算交付。

串起來看：四個 skills 各做了什麼

四個 skills 串起來，等於一個有紀律的小功能交付，沒有跳過任何一步。

關鍵學習點

• quick-flow 不是新東西，是把四個常用 skills 按順序串起來。順序記住：先想、再規劃、TDD 實作、最後驗收。
• TDD 的紅燈不是失敗，是設計。先寫測試才知道「做完」長什麼樣子，綠燈階段只求最小通過。
• 重構不是「找事做」。本例重構階段把錯誤處理加上去，是因為計畫階段 3 有明確要求，不是順手改。
• verification 的三個面向（測試、建置、實際操作）缺一不可，只跑測試不能算完成。