Claude Code 系列文 (3/5)：設計文檔 — 讓 Claude 一次做對

前提：已寫好 CLAUDE.md（第 2 篇） 時間投入：20-30 分鐘設計 + 2 小時實施（vs 8 小時傳統方式） 成果：90%+ 一次正確，最多微調 1-2 處

---

核心觀點

CLAUDE.md：永遠的規則（不變）
   ↓
設計文檔：這次功能的具體需求（會變）
   ↓
實施：Claude 讀完兩者，一次到位

實際效果：

傳統：
user: "加個 PDF 匯出功能"
claude: 實施... 但漏了 QR code、沒考慮大文件、錯誤處理不完善
result: 改 3 次，花 8 小時

===

設計優先：
user: 先寫「PDF 匯出設計文檔」
   ├─ 輸出什麼欄位
   ├─ 格式細節
   ├─ 大文件怎麼處理
   └─ 邊界情況怎麼做

claude: 讀完設計，實施功能
result: 一次到位，花 2 小時

---

為什麼設計文檔這麼關鍵

原因 1：Claude 不是心靈讀者

你想要：
"PDF 應該很專業，像官方發票"

Claude 理解的：
"Generate a PDF" (可能就是基礎格式)

===

如果你寫：
"PDF 格式：
 - 頁眉：公司 logo + 發票編號
 - 內容：3 欄表格 (品項|數量|金額)
 - 頁尾：二維碼 + 簽章區域
 - 字體：14pt 標題，11pt 內容"

Claude 理解的：
正確無誤 ✅

原因 2：邊界情況很容易漏

你沒說的情況：
- 如果發票超過 1 頁怎麼辦？
- 品項名稱很長怎麼折行？
- 金額超過 99,999,999 怎麼顯示？

Claude 的猜測：
- 默認假設只有 1 頁
- 品項名稱截斷
- 金額省略號或出錯

===

設計文檔說清楚：
- 多頁：自動翻頁，每頁重複頁眉
- 長品項：自動折行到 2-3 行，調整行高
- 大金額：科學計數法或分行顯示

Claude：
做對 ✅

原因 3：審核快得多

沒有設計文檔：
你看代碼 → "嗯... 這個邏輯有點問題？"
            → 要改 → 再看一遍 → 還要改
時間：1-2 小時審核

===

有設計文檔：
設計文檔清楚 → Claude 一次到位
審核只需檢查「有沒有按設計文檔做」
時間：15 分鐘審核

---

一人公司的設計文檔長什麼樣

最小版本（20 分鐘寫完）

假設你要加「發票篩選功能」：

# Invoice Filter Feature

## What
用戶可以按日期、狀態、金額篩選發票列表

## How
### Page Flow
1. 使用者進入「發票清單」頁面
2. 頁面上方顯示篩選器：
   - Date range picker (from - to)
   - Status dropdown (全部 / 草稿 / 已提交 / 已申報)
   - Amount range slider (0 - 999,999)
3. 用戶選擇條件 → 自動篩選列表（無需按搜尋按鈕）
4. 篩選結果顯示在表格

### Data Model
```sql
-- 輸入參數
filter: {
  dateFrom: Date,
  dateTo: Date,
  status: enum ['DRAFT', 'SUBMITTED', 'FILED'],
  amountMin: number,
  amountMax: number
}
```

### Edge Cases
- 沒有搜尋結果 → 顯示「沒有符合條件的發票」
- 篩選中 → 顯示 loading spinner
- API 錯誤 → 顯示「載入失敗，請重試」

## Why
- 用戶有 100+ 發票，手動找很慢
- 會計需要按日期整理報表
- 管理者需要看特定金額範圍的交易

花時間：20 分鐘 代碼行數：20-30 行（因為清晰，不用試錯）

完整版本（30 分鐘寫完）

如果功能更複雜，加這些：

# Invoice PDF Export Feature

## 業務背景
台灣政府要求發票有統一格式（GUN 標準）
用戶要匯出發票給客戶或存檔

## 用戶故事
"作為發票系統使用者，我想點擊『匯出 PDF』按鈕，
  得到一份官方格式的 PDF，這樣我可以寄給客戶或稅務局"

## 功能範圍
### 必須有
- [ ] PDF 包含所有發票欄位（發票號碼、日期、品項、金額等）
- [ ] GUN 格式（台灣政府標準）
- [ ] 二維碼（可掃描驗證）
- [ ] 頁眉和頁尾
- [ ] 多頁自動分頁

### 可以有（下個版本）
- [ ] 批量匯出（多張發票 1 個 PDF）
- [ ] 自訂 logo
- [ ] 簽章區域

### 不包含
- [ ] 自訂格式（template 系統太複雜）
- [ ] 列印功能（瀏覽器列印已足）

## API/Data
### Input
```typescript
POST /api/invoices/{id}/export-pdf

// Response
{
  pdf_url: "https://..../invoice_2024_001.pdf",
  generated_at: "2024-03-25T10:30:00Z"
}
```

## UI/UX
### 按鈕位置
- 在「發票詳情」頁面右上角
- 按鈕文字：「匯出 PDF」
- 點擊後：shows loading 3 秒，下載 PDF

### 錯誤情況
- 網路錯誤 → 「無法生成 PDF，請重試」
- 發票不完整 → 「發票資料不完整，無法匯出」
- 檔案太大（> 10MB） → 「檔案過大，請聯絡管理員」

## 技術決策
### Why jsPDF instead of server-side?
- jsPDF：快速、實時、不佔服務器資源 ✅
- Server-side：需要 Node.js 套件、佔内存

### Why QR code?
- Taiwan GUN requirement
- Users can verify authenticity by scanning

## 測試 Checklist
- [ ] PDF 內容完整（所有欄位都在）
- [ ] 格式符合 GUN 標準（對齐、字體大小）
- [ ] 二維碼可掃描
- [ ] 多頁發票能正確分頁
- [ ] 邊界情況：長品項名稱、大金額
- [ ] 錯誤訊息清晰

## 完成條件（Acceptance Criteria）
- [ ] 用戶點擊按鈕能下載 PDF
- [ ] PDF 格式符合 GUN 標準
- [ ] 二維碼正確生成
- [ ] 網路慢時顯示 loading
- [ ] 有錯誤時顯示清晰的訊息
- [ ] 所有測試通過（coverage > 85%）

花時間：30 分鐘 代碼行數：50-80 行（因為設計完整，邊界情況少）

---

如何快速寫設計文檔（給一人公司老闆）

方法 1：從 User Story 開始（最快）

## 功能
允許用戶標記發票為「已審核」

## 用戶故事
"As a manager, I want to mark invoices as reviewed,
 so I can track which invoices have been checked"

## 怎麼做
1. 發票表格增加「審核」按鈕
2. 點擊後標記為「已審核」，按鈕變灰
3. 可以「取消審核」改回去

## Edge Cases
- 多人同時審核同一張發票？ → 最後一次改動獲勝
- 已提交的發票能審核嗎？ → 能，審核和提交獨立

## Done When
- [ ] 按鈕會出現
- [ ] 狀態能改變
- [ ] 數據持久化
- [ ] 網路慢時有 loading

花時間：10-15 分鐘

方法 2：從技術問題開始（有爭議時）

## 問題
稅務計算邏輯現在在 service/taxCalculator.ts，
很難測試，也難新增新稅種

## 提議
用 Strategy Pattern 重構

## 對比
### 現狀（有問題）
```typescript
if (type === 'standard') {
  tax = amount * 0.05;
} else if (type === 'zero') {
  tax = 0;
}
// 很多 if，難擴展
```

### 改進後
```typescript
const strategy = TaxStrategyFactory.get(type);
tax = strategy.calculate(amount);
// 新稅種只需新建 class，無需改舊代碼
```

## 工作
1. 建立 TaxStrategy interface
2. 建立 StandardTaxStrategy, ZeroTaxStrategy, ExemptTaxStrategy
3. 建立 TaxStrategyFactory
4. 遷移現有邏輯
5. 寫測試

## 完成條件
- [ ] 所有現有測試通過
- [ ] 無新 bug
- [ ] 代碼行數 < 現狀（因為減少 if）
- [ ] 新稅種能在 30 分鐘內加入

花時間：15-20 分鐘

---

設計文檔和 CLAUDE.md 的區別

項目	CLAUDE.md	設計文檔
頻率	一年改幾次	每個功能寫一份
內容	規則、標準	這次功能的細節
例子	「所有 component 用 PascalCase」	「篩選器有 date picker 和 status dropdown」
變化	不變	常變
時效	永遠有用	功能完成後就 archive

---

常見問題

Q: 設計文檔很麻煩嗎？

A: 不麻煩。其實省時間。

對比：

• ❌ 不寫設計文檔：2 小時設計（腦子裡）+ 8 小時實施 + 5 小時改 = 15 小時
• ✅ 寫設計文檔：30 分鐘寫 + 2 小時實施 + 0.5 小時改 = 2.5 小時

省時 6 倍。

Q: 如果需求改了怎麼辦？

A: 更新設計文檔，再讓 Claude 改。

原設計：篩選器是下拉選單
新需求：改成複選框（可選多個狀態）

做法：
1. 更新設計文檔的 UI/UX 部分
2. Prompt: "按照新設計文檔改篩選器"
3. Claude 改
4. 完成

Q: 小功能也要寫設計文檔嗎？

A: 看複雜度

• 簡單（邏輯 < 5 行）：無需文檔，直接 prompt
• 中等（邏輯 20-50 行）：寫簡單版設計文檔（10 分鐘）
• 複雜（邏輯 > 50 行，多頁面）：寫完整版設計文檔（30 分鐘）

一般來說：中等及以上都要寫。

---

實戰範例：Taiwan Invoice 設計文檔

這是真實的設計文檔，你可以直接改成自己的：

# Taiwan Invoice System - Design Doc

## 概述
系統需要符合台灣官方發票格式 (GUN)
用戶可以生成、儲存、匯出發票

## 模組 1: Invoice Data Model

### 資料結構
```sql
CREATE TABLE c_invoice (
  id UUID PRIMARY KEY,
  invoice_number VARCHAR(10),  -- e.g., "001", "002"
  invoice_date DATE,
  company_name VARCHAR(255),
  company_tax_id VARCHAR(8),
  customer_name VARCHAR(255),
  customer_tax_id VARCHAR(8),
  items JSONB,  -- [{name, qty, price, amount}, ...]
  subtotal DECIMAL(12,2),
  tax_amount DECIMAL(12,2),
  total DECIMAL(12,2),
  status ENUM('DRAFT', 'SUBMITTED', 'FILED'),
  created_at TIMESTAMP,
  updated_at TIMESTAMP
);
```

## 模組 2: Tax Calculation

### 規則
- 標準稅率：5%（大部分商品）
- 零稅率：0%（出口商品）
- 免稅：0%（非營利組織）
- 進項稅扣除：同月內才能計算

### 計算邏輯
```
total_tax = sum(item.tax for item in items)
where tax = item.amount * tax_rate

if invoice.status == 'SUBMITTED':
  deductible_tax = tax (可抵扣)
else:
  deductible_tax = 0 (草稿狀態不計)
```

## 模組 3: PDF Export

### 輸出格式
頁面：A4 (210mm x 297mm)
邊距：10mm

頁眉：
- 左：公司 logo (40x40mm)
- 中：「統一發票」(20pt bold)
- 右：發票號碼 (16pt)

內容：
- 發票日期
- 買賣雙方資訊
- 3 欄表格：品項、數量、金額
- 合計 / 稅額 / 總金額

頁尾：
- QR code (25x25mm)
- 簽章區域

## 完成條件
- [ ] 資料模型完整
- [ ] 稅務計算正確
- [ ] PDF 格式符合 GUN 標準
- [ ] 所有 edge cases 測試通過

---

一人公司老闆的建議

做法 1：檔案形式

寫在 docs/designs/ 資料夾：

docs/designs/
├── invoice-filter.md
├── invoice-pdf-export.md
└── tax-calculation.md

提交到 git，成為代碼庫的一部分。

做法 2：更新設計文檔的時機

• 需求改變時
• 發現 bug 時
• 新的 edge case 出現時

加一句：

## 更新日誌
- 2024-03-25：初版
- 2024-03-26：加入多頁分頁需求
- 2024-03-27：修正邊界情況 (長品項名稱)

---

下一步

現在就做

選一個你想要的功能（不用很大），寫設計文檔：

1. 打開編輯器

“bash touch docs/designs/[feature-name].md “

1. 按照上面的「最小版本」模板寫

• What (是什麼)
• How (怎麼做)
• Edge cases (邊界情況)
• Done when (完成條件)

1. 花時間：15-20 分鐘

1. 給 Claude

“`bash claude user: “這是 [功能名稱] 的設計文檔 [貼上設計文檔]

請按照這個設計實施” “`

1. 對比傳統方式

• 時間縮短 60-70%
• 修改次數 ÷ 3
• Bug 數量 ÷ 2

---

重點回顧

CLAUDE.md：「怎樣寫好代碼」(寫一次，永遠用)
   ↓
設計文檔：「這次要寫什麼」(每功能一份)
   ↓
Claude：一次實施正確 ✅

投資回報：

• 每份設計文檔花 30 分鐘
• 省 6 小時實施時間
• 一年 (~50 功能) 省 300 小時 = 6 周工作量！

---

下一篇預告

第 4 篇：Hook 自動化

有了 CLAUDE.md 和設計文檔，代碼質量大幅提升。

但還有很多重複的手動工作：

• 每次編輯後手動 lint
• 每次 commit 前手動執行測試
• 每週手動檢查依賴更新

用 Hooks 自動化這些！

下一篇會告訴你：

• 怎樣 5 分鐘設置 3 個最重要的 Hook
• 節省每週 5-10 小時手動工作
• 實例：after-edit (auto-format) + before-commit (auto-test)

---

現在就開始寫第一個設計文檔！ 👋