Claude Code 系列文 (5/5)：實戰 — 3 天完成 Taiwan Invoice 系統

前提：讀過第 1-4 篇，理解整個工作流 目標：看一個真實的「一人公司 3 天完成功能」案例 收穫：知道如何套用到你的項目

---

案例背景

公司：一人 SaaS 公司（會計軟件） 需求：完整的台灣統一發票系統 期限：3 天內完成 MVP 資源：1 個人 + Claude Code 目標：一次到位，最少改動

---

🗓️ Day 1：規劃 + 準備（6 小時）

上午（3 小時）：理清需求

# Taiwan Invoice System - Requirement Doc

## 為什麼要做
目前手工開發票，容易出錯，無法追蹤

## 用戶故事
"As a freelancer with 50+ monthly invoices,
 I want to generate invoices in Taiwan GUN format,
 so I can legally submit to tax authority"

## MVP Scope（3 天內）
✅ 建立發票 (可編輯草稿)
✅ 查看發票列表
✅ 匯出 PDF (GUN 格式)
✅ 基本驗證 (金額、格式)

⏳ Phase 2 (1 個月後)
- 批量操作
- 進階篩選
- 政府系統整合

花時間：30 分鐘（邊想邊寫）

中午（3 小時）：建立項目規則 + 設計

建立 CLAUDE.md：

# Taiwan Invoice System

## Tech Stack
- Frontend: React 18 + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL
- Styling: Tailwind CSS

## Code Standards
- TypeScript strict mode
- Test coverage > 80%
- JSDoc for public API
- Prettier + ESLint

## Business Rules (Critical!)

### Invoice Format (GUN)
必須符合台灣政府格式：
- 發票號碼：8 位數 (格式：AAA12345)
- 序列必須連續
- 日期：民國年 (e.g., 112/03/25)
- 必填欄位：公司統編、客戶統編、品項、金額

### Tax Rules
- 標準稅率：5% (大部分)
- 零稅率：0% (出口商品)
- 免稅：0% (政府單位等)
- 進項稅：同月內計算，超過月份無法扣

### Immutability
已提交的發票不可修改，只能作廢重新開

## Architecture Decision
使用 Strategy Pattern 處理不同稅率
→ 易於新增新稅種

## Important
必須通過以下檢查：
- 發票序列連續
- 日期格式正確 (民國年)
- 金額計算正確
- 必填欄位都有

花時間：1 小時

寫設計文檔：

# Feature: Create Invoice

## User Flow
1. 使用者點「新建發票」
2. 看到表單：日期、客戶、品項清單、稅率
3. 填完按「儲存為草稿」
4. 發票編號自動產生 (取自上一張+1)
5. 顯示「草稿已保存」訊息

## Data Structure
```typescript
interface Invoice {
  id: UUID;
  invoiceNumber: string;      // e.g., "AAA00001"
  invoiceDate: Date;          // ROC year format
  companyId: string;          // 公司統編
  companyName: string;
  customerId: string;         // 客戶統編
  customerName: string;
  items: InvoiceItem[];       // 品項清單
  taxRate: 5 | 0;            // 稅率
  subtotal: number;
  taxAmount: number;
  total: number;
  status: "DRAFT" | "SUBMITTED" | "VOIDED";
  createdAt: Date;
  updatedAt: Date;
}

interface InvoiceItem {
  id: UUID;
  name: string;
  quantity: number;
  unitPrice: number;
  amount: number;             // qty * price
}
```

## API
```
POST /api/invoices
{
  invoiceDate: "2024-03-25",
  customerId: "12345678",
  customerName: "ABC Company",
  items: [{name, quantity, unitPrice}, ...],
  taxRate: 5
}
→ 201 Created
{
  id: "uuid",
  invoiceNumber: "AAA00123",
  ...
}

GET /api/invoices/:id
→ 返回完整發票資料

PUT /api/invoices/:id
{...updates}
→ 200 OK (只有 DRAFT 狀態可修改)
```

## Validation
- [ ] 發票號碼格式：AAA + 5 位數
- [ ] 客戶統編：8 位數
- [ ] 日期：不能是未來日期
- [ ] 品項至少 1 個
- [ ] 金額都是正數
- [ ] 稅率只能是 5 或 0

## Edge Cases
- 新使用者，沒有上一張發票？→ 自動從 AAA00001 開始
- 修改數量後，金額要自動計算 ✅
- 刪除品項要更新小計 ✅
- 同一天多張發票？→ 號碼自動遞增 ✅

## Acceptance Criteria
- [ ] 表單能填入資料
- [ ] 發票自動編號
- [ ] 計算正確
- [ ] 驗證有效
- [ ] 錯誤訊息清晰（中文）
- [ ] 所有測試通過

花時間：1.5 小時

設置 Hook（複製 settings.json）：

花時間：30 分鐘

下午成果

Day 1 完成：
✅ 需求清晰（RFC 格式）
✅ CLAUDE.md 完成（規則明確）
✅ 設計文檔完成（API + UI + 驗證規則）
✅ Hook 已設置（自動格式化和測試）
✅ Git 提交

Code ready for Claude!

---

🗓️ Day 2：實施 + 驗證（8 小時）

早上（4 小時）：Claude 實施後端 + API

Prompt 給 Claude：

這是我們的 Taiwan Invoice 系統。

CLAUDE.md（規則）：[貼上 CLAUDE.md]

設計文檔（需求）：[貼上設計文檔]

請按照設計實施：
1. 建立 Invoice 數據模型
2. 建立 API endpoints (POST /invoices, GET /invoices/:id, PUT)
3. 實施驗證邏輯
4. 寫單元測試（coverage > 80%）

注意：台灣稅法很嚴格，邊界情況要測試完整。

Claude 做的事：

• 自動讀 CLAUDE.md（知道 TypeScript strict，要測試）
• 自動讀設計文檔（知道確切的 API 格式和驗證規則）
• 一次性實施，不猜測
• 自動加測試（因為 CLAUDE.md 要求）
• 自動格式化和 lint（Hook 搞定）

結果（2 小時）：

✅ models/Invoice.ts (50 行)
✅ services/InvoiceService.ts (200 行)
✅ routes/invoices.ts (80 行)
✅ __tests__/invoiceService.test.ts (150 行，30 個測試)

所有測試通過 ✅
代碼 lint 通過 ✅
覆蓋率 > 85% ✅

中午（2 小時）：Claude 實施前端 + 表單

Prompt：

前端現在需要：
1. 發票新建表單（日期、客戶、品項清單）
2. 發票列表頁面
3. 發票詳情頁面

用設計文檔中的 API，請實施 React 組件。

要點：
- 表單驗證（錯誤訊息用中文）
- 品項動態新增/刪除
- 自動計算小計和稅額
- 載入中和錯誤狀態要顯示

結果（2 小時）：

✅ components/InvoiceForm.tsx (300 行)
✅ pages/InvoiceList.tsx (150 行)
✅ pages/InvoiceDetail.tsx (200 行)
✅ hooks/useInvoice.ts (100 行，API 調用)
✅ __tests__/InvoiceForm.test.tsx (200 行)

測試通過 ✅
外觀符合預期 ✅

下午（2 小時）：整合測試 + Bug 修復

做法：

1. 連接前後端
2. 手動測試端到端流程
3. 發現 2 個小 bug（日期格式，驗證訊息）
4. Claude 修復
5. 再測一遍，沒問題

結果：

✅ 前後端連接
✅ 表單能提交
✅ 發票能保存到 DB
✅ 列表能顯示
✅ 所有驗證工作
✅ 錯誤訊息清晰

Day 2 成果

✅ 後端 API 完成
✅ 前端 UI 完成
✅ 單元測試通過（200+ 測試）
✅ 整合測試通過
✅ 0 console.log，0 TODO
✅ 準備上線

---

🗓️ Day 3：優化 + 部署（4 小時）

早上（1 小時）：性能 + 安全檢查

# 代碼審查
npm run lint           # 0 錯誤 ✅
npm test              # 200+ 測試通過 ✅
npm run type-check    # TypeScript: 0 錯誤 ✅

# 安全檢查
npm audit             # 0 高風險漏洞 ✅
grep -r "console.log" src/   # 0 結果 ✅
grep -r "TODO" src/          # 0 結果 ✅

中午（1 小時）：文檔 + README

# Taiwan Invoice System

## Features
- ✅ Create/Edit/View invoices in GUN format
- ✅ Automatic invoice numbering
- ✅ Tax calculation (5% / 0% / exempt)
- ✅ Form validation (Taiwan rules)
- ✅ PDF export (coming v1.1)

## API
[自動生成 API 文檔]

## Setup
```bash
npm install
npm run dev
```

## Testing
```bash
npm test
npm run test:coverage
```

## Deployment
[部署指令]

下午（2 小時）：部署 + 監控

# 部署
npm run build         # 0 警告
deployment-script    # 部署到 staging

# 煙霧測試
curl http://staging/api/invoices
# 確保 API 正常

# 監控設置
[設定錯誤告警]
[設定性能監控]

Day 3 成果

✅ 代碼審查通過
✅ 安全檢查通過
✅ 文檔完整
✅ 部署到 Staging
✅ 煙霧測試通過
✅ 準備上線

---

📊 3 天總結

時間分配

Day 1 規劃：6 小時
  ├─ 需求文檔：30 min
  ├─ CLAUDE.md：1 hour
  ├─ 設計文檔：1.5 hours
  ├─ Hook 設置：30 min
  └─ Git 提交：30 min

Day 2 實施：8 小時
  ├─ 後端實施 + 測試：4 hours
  ├─ 前端實施 + 測試：2 hours
  ├─ 整合 + Bug 修復：2 hours
  └─ 無重複改動 ✅

Day 3 優化：4 小時
  ├─ 性能 + 安全：1 hour
  ├─ 文檔：1 hour
  ├─ 部署 + 測試：2 hours
  └─ 準備上線

總計：18 小時 = 2.25 天工作量

成果

代碼行數：~1500 行（含測試）
測試數：200+ 個
測試覆蓋率：85%+
Bug 數：0 個（在 staging）
改動次數：0 次（一次到位）

典型方式的對比：
傳統（沒規劃）：40-50 小時，改 5-6 次
規劃優先（本案例）：18 小時，0 次改動

關鍵成功因素

因素	為什麼重要	這次是否做到
CLAUDE.md	Claude 知道規則，不猜測	✅
設計文檔	Claude 知道確切需求，一次對	✅
Hook	自動化質量檢查，省手動操作	✅
TypeScript	類型安全，邊界情況早發現	✅
完整測試	回歸測試保證不破壞舊功能	✅
Git 提交	每個功能清楚的 commit	✅

---

🎯 如何套用到你的項目

Step 1：這週做

• ☐ 為你的項目寫 CLAUDE.md（1 小時）
• ☐ 選一個新功能，寫設計文檔（30 分鐘）
• ☐ 給 Claude，看效果

Step 2：下週做

• ☐ 設置 Hook（15 分鐘）
• ☐ 再試 2 個功能用設計文檔
• ☐ 感受時間節省

Step 3：成習慣

• ☐ 所有新功能都先寫設計文檔
• ☐ Hook 自動化所有品質檢查
• ☐ CLAUDE.md 定期更新

---

💡 一人公司老闆應該學到的

1. 規劃比實施更值得

傳統思維：「趕快寫代碼！」
結果：寫很多，改很多，還是有 bug

正確思維：「花 2 小時規劃，用 8 小時實施」
結果：代碼一次對，沒有重複

一人公司必須這樣思考，因為時間最貴。

2. 文檔不是累贅，是投資

成本：30-60 分鐘寫設計文檔
收益：省 6-8 小時改動

ROI = 600-800%

最好的投資。

3. 自動化不是選項，是必須

每週 5 小時手動 lint/test
一年 260 小時
相當於 1.5 個全職開發者成本

用 15 分鐘設置 Hook，省這麼多

不設置 Hook 的一人公司，在浪費金錢。

4. 一個人不代表不能有系統

一人公司有一個優勢：決策快

用 CLAUDE.md + 設計文檔 + Hook
建立「個人系統」：
- 代碼風格一致
- 質量有保證
- 規律可預測
- 未來能擴招

這是一個小公司變成可擴展企業的基礎。

---

📈 一人公司的進化路徑

Month 1：學習 (讀這 5 篇文章，試一個功能)
Month 2：習慣 (所有新功能都用規劃優先)
Month 3：系統 (CLAUDE.md + Hook 成為日常)
Month 4-6：收穫 (月開發速度 ×3, bug ÷2)
Month 6+：擴招 (有文檔，新人能快速上手)

最後變成一個「可擴展的一人公司」
而不是「永遠只能一人」的公司

---

核心觀點回顧

┌─────────────────────────────────────┐
│ 一人公司的黃金工作流                │
├─────────────────────────────────────┤
│ 規劃（30%）                         │
│  ├─ CLAUDE.md：寫一次，永遠用      │
│  └─ 設計文檔：每功能寫一份          │
│     ↓                                │
│ 實施（50%）                         │
│  ├─ Claude 一次對                  │
│  └─ Hook 自動檢查                  │
│     ↓                                │
│ 驗收（20%）                         │
│  ├─ 測試自動通過                   │
│  └─ 文檔已完整                     │
│     ↓                                │
│ 上線                               │
│                                    │
│ 結果：                              │
│ - 時間 -70%                        │
│ - Bug -80%                         │
│ - 心理壓力 -90%                    │
└─────────────────────────────────────┘

---

最後的話

這個系列文教你的不是「怎麼用 Claude Code」

而是「怎麼用 Claude Code 作為一人公司老闆活得更輕鬆」

你的時間 ≠ 開發者的時間
你的時間 = 企業的命脈

所以：
不要做「重複的手動工作」
不要「改」代碼（要「規劃」代碼）
不要「猜測」用戶需求（要「寫下來」）

文檔優先，自動化第二，代碼最後。

這是一人公司的生存法則。

---

行動清單（現在就做）

Week 1

• ☐ 讀完這 5 篇文章（2 小時）
• ☐ 為你的項目寫 CLAUDE.md（1 小時）
• ☐ 設置 Hook（15 分鐘）

Week 2

• ☐ 選一個新功能，寫設計文檔
• ☐ 用新工作流實施，看效果
• ☐ 記錄時間（和傳統方式比較）

Week 3-4

• ☐ 再用 2-3 個功能測試
• ☐ 調整 CLAUDE.md（發現遺漏的規則）
• ☐ 分享給朋友（看看他們的反應）

---

資源總結

你現在有：

📚 5 篇教學文
📋 3 個可直接用的模板
✅ 4 個檢查清單
🔧 1 個實戰案例 (Taiwan Invoice)
📖 完整的 Claude Code 指南庫 (~/claude-code-guide/)

一切你需要的都在了。

---

致謝

感謝你讀完這個系列。

如果有問題、改進建議或你的實踐心得，歡迎分享。

下一步：不是讀更多，是實踐。

選一個功能，按照 Day 1-3 的流程試試看。

你會驚嘆「怎麼忽然快這麼多」。

---

THE END – 系列完！ 🎉

---

系列文快速導航

#	標題	你學到	時間
1	為什麼規劃優先	理解痛點	15 min
2	CLAUDE.md – 編碼憲法	寫規則文檔	30 min
3	設計文檔 – 讓 Claude 一次對	寫需求文檔	30 min
4	Hook 自動化 – 省手動工作	設置自動化	15 min
5	實戰 – 3 天完成系統	看完整案例	20 min

總時間：1.5 小時讀 + 2 小時實踐 = 3.5 小時 收益：未來每週省 5-10 小時，一年省 260-520 小時！