標籤: AI 輔助開發

前提：讀過第 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 小時！

前提：已有 CLAUDE.md + 設計文檔 時間投入：15 分鐘設置 + 自動化 省時：每週 5-10 小時（再也不用手動 lint/test）

---

核心觀點

傳統流程：
1. 你寫代碼
2. 你手動 npm run lint
3. 你修復 lint 錯誤
4. 你手動 npm test
5. 你看測試結果... 有 bug
6. 你修復 bug
7. 你再手動 lint 一遍
8. 最後才提交

時間：45 分鐘 / 功能

===

Hook 自動化：
1. 你寫代碼
2. 保存檔案 → Hook 自動 lint + fix ✅
3. 提交 git → Hook 自動測試 ✅
4. 測試通過 → 允許提交 ✅

時間：10 分鐘 / 功能

節省時間：35 分鐘 × 10 功能 / 月 = 6 小時 / 月！

---

一人公司最需要的 3 個 Hook

Hook 1: after-edit（保存檔案時自動格式化）

作用：自動執行 prettier + eslint –fix

好處：

• 不用手動 npm run lint
• 代碼永遠符合格式
• Code review 不再被卡在「縮排問題」

設置（5 分鐘）：

# 編輯 ~/.claude/settings.json
cat >> ~/.claude/settings.json << 'EOF'
{
  "hooks": {
    "after-edit": {
      "enabled": true,
      "commands": [
        {
          "patterns": ["**/*.ts", "**/*.tsx", "**/*.js"],
          "run": "prettier --write {file_path} && eslint --fix {file_path}",
          "on_failure": "warn",
          "timeout": 5000
        }
      ]
    }
  }
}
EOF

驗證（1 分鐘）：

# 寫一個格式很爛的檔案
echo "const  x   =   1" > src/test.ts

# 通過 Claude 編輯它（或手動編輯）
# 檢查：是否自動格式化為 "const x = 1;"
cat src/test.ts

Hook 2: before-commit（提交前自動測試）

作用：提交前必須通過所有測試

好處：

• 永遠不會提交有 bug 的代碼
• 主分支永遠綠色（測試都通過）
• 不用事後才發現 bug

設置（5 分鐘）：

cat >> ~/.claude/settings.json << 'EOF'
{
  "hooks": {
    "before-commit": {
      "enabled": true,
      "commands": [
        {
          "name": "test",
          "run": "npm test -- --onlyChanged --passWithNoTests",
          "on_failure": "block",
          "timeout": 60000,
          "message": "Tests failed. Fix before committing."
        },
        {
          "name": "lint",
          "run": "npm run lint -- {staged_files}",
          "on_failure": "warn"
        }
      ]
    }
  }
}
EOF

驗證（1 分鐘）：

# 破壞一個測試
echo "test('fail', () => expect(1).toBe(2));" > src/__tests__/test.ts

# 嘗試提交
git add .
git commit -m "test: add failing test"

# 結果：被 Hook 擋住 ✅
# 訊息：Tests failed. Fix before committing.

Hook 3: scheduled（每週自動檢查依賴）

作用：每週一自動檢查 npm 依賴更新 + 安全漏洞

好處：

• 不用手動 npm audit
• 自動 npm audit fix（修復已知漏洞）
• 依賴永遠最新，安全性更好

設置（5 分鐘）：

cat >> ~/.claude/settings.json << 'EOF'
{
  "hooks": {
    "scheduled": {
      "enabled": true,
      "jobs": [
        {
          "name": "weekly_dependency_audit",
          "cron": "0 10 * * MON",
          "run": "npm audit fix --audit-level=moderate",
          "description": "Check and fix dependencies every Monday 10 AM"
        }
      ]
    }
  }
}
EOF

---

Hook 完整配置（給一人公司）

把這個存到 ~/.claude/settings.json：

{
  "hooks": {
    "after-edit": {
      "enabled": true,
      "description": "Auto-format and lint after editing files",
      "commands": [
        {
          "patterns": ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
          "run": "prettier --write {file_path} && eslint --fix {file_path}",
          "on_failure": "warn",
          "timeout": 5000
        },
        {
          "patterns": ["**/*.json"],
          "run": "prettier --write {file_path}",
          "on_failure": "warn",
          "timeout": 3000
        }
      ]
    },

    "before-commit": {
      "enabled": true,
      "description": "Run tests and lint before committing",
      "commands": [
        {
          "name": "test",
          "run": "npm test -- --onlyChanged --passWithNoTests",
          "on_failure": "block",
          "timeout": 60000,
          "message": "Tests failed. Fix before committing."
        },
        {
          "name": "lint",
          "run": "npm run lint",
          "on_failure": "warn",
          "timeout": 30000
        }
      ]
    },

    "scheduled": {
      "enabled": true,
      "description": "Automated background tasks",
      "jobs": [
        {
          "name": "weekly_dependency_audit",
          "cron": "0 10 * * MON",
          "description": "Check and fix dependencies every Monday 10 AM",
          "run": "npm audit fix --audit-level=moderate || true"
        },
        {
          "name": "daily_test_report",
          "cron": "0 9 * * *",
          "description": "Run full test suite daily at 9 AM",
          "run": "npm test"
        }
      ]
    }
  }
}

---

一週省下的時間

假設你一週寫 5 個功能

任務	次數	時間 / 次	舊方式	Hook 方式	省下
手動 lint	5	2 min	10 min	0 min	10 min
手動測試	5	5 min	25 min	0 min	25 min
修復 lint bug	5	3 min	15 min	0 min	15 min
手動 npm audit	1	10 min	10 min	0 min	10 min
總計			60 min	0 min	60 min

一週省 1 小時，一年省 52 小時！

---

一人公司老闆應該知道的 Hook 細節

細節 1: on_failure 的三種選擇

"on_failure": "block"   ← Hook 失敗就停止
            (測試失敗時用)

"on_failure": "warn"    ← Hook 失敗但繼續
            (建議性檢查，不強制)

"on_failure": "ignore"  ← Hook 失敗完全忽視
            (做了無關的操作時)

建議：

• 測試失敗 → block（必須通過）
• 格式化失敗 → warn（不影響功能）
• npm audit → warn（有漏洞但不阻止提交）

細節 2: timeout 設定

"timeout": 5000   ← 5 秒超時（快速操作）
"timeout": 30000  ← 30 秒超時（複雜操作）
"timeout": 60000  ← 60 秒超時（完整測試）

建議：

• prettier/eslint：5 秒
• 單個檔案 lint：10 秒
• 單個 component 測試：30 秒
• 全部測試：60 秒

細節 3: patterns（針對特定檔案類型）

"patterns": ["**/*.ts", "**/*.tsx"]
            ↓ 只對 TypeScript 檔案執行

"patterns": ["**/*.js"]
            ↓ 只對 JavaScript 檔案執行

"patterns": ["src/**"]  (可選)
            ↓ 只對 src/ 資料夾執行

---

常見問題

Q: Hook 會拖慢我的開發速度嗎？

A: 不會，反而加快。

Hook 執行時間：< 5 秒
傳統修復時間：15-30 分鐘

所以快 180-360 倍。

Q: 如果我想跳過 Hook（緊急情況）？

A: 可以，但不推薦。

# 跳過 before-commit hook
git commit -m "message" --no-verify

# 但這很危險！只在真正緊急時用

一人公司建議：不要跳過。多花 1 分鐘讓 Hook 通過，比之後修 bug 便宜。

Q: 我已經有自己的 lint 設定，怎樣整合？

A: Hook 尊重你的 .eslintrc 和 .prettierrc

# 如果你已經有這些檔案，Hook 會自動用它
ls -la .eslintrc .prettierrc

# 如果沒有，建議建立預設的
touch .eslintrc.json .prettierrc.json

---

設置 Hook 的完整步驟

Step 1: 確認已安裝工具（2 分鐘）

npm --version          # Node.js
npm list prettier      # Prettier 已裝
npm list eslint        # ESLint 已裝

# 如果沒裝，安裝它們
npm install --save-dev prettier eslint

Step 2: 複製配置（3 分鐘）

# 如果你沒有 settings.json
touch ~/.claude/settings.json

# 貼上上面「完整配置」的內容
# 或用模板
cp ~/claude-code-guide/templates/settings.json.template \
   ~/.claude/settings.json

Step 3: 驗證設置（5 分鐘）

按照上面「驗證」部分，測試 3 個 Hook 是否工作。

Step 4: 提交到 Git（1 分鐘）

# 可選：把配置存在 repo 裡（方便分享給團隊）
cp ~/.claude/settings.json .claude/settings.json
git add .claude/settings.json
git commit -m "chore: add hooks configuration"

---

進階：自訂你的 Hook

假設你想在每次提交前自動檢查台灣稅務規則：

{
  "before-commit": {
    "commands": [
      {
        "name": "tax_rule_check",
        "run": "grep -r 'TODO.*tax' src/ && echo 'WARNING: Tax rules need attention' || true",
        "on_failure": "warn"
      }
    ]
  }
}

---

一人公司的 Hook 最佳實踐

✅ DO

1. 保持 Hook 快（< 10 秒）
2. 從必須有的開始（測試、格式化）
3. 定期檢查 Hook 日誌

“bash tail -50 ~/.claude/logs/hooks.log “

1. 團隊共享 Hook 配置

“bash git commit .claude/settings.json “

❌ DON’T

1. 不要太多 Hook（> 5 個會累）
2. 不要 Hook 做複雜邏輯（只做檢查和格式化）
3. 不要在 Hook 裡執行部署（太危險）

---

下一步

現在就做

1. 複製完整配置到 ~/.claude/settings.json
2. 測試 3 個 Hook（1-2 分鐘）
3. 編輯一個檔案，檢查是否自動格式化
4. 提交代碼，檢查是否自動測試
5. 享受節省下來的時間！

---

重點回顧

CLAUDE.md：規則（永遠不變）
設計文檔：需求（每功能一份）
Hook：自動化（一次設置，永遠運行）

一人公司工作流：
規劃 → 寫代碼（自動格式化）
   → 提交（自動測試）
   → 完成

時間：30% 規劃 + 70% 實施（不是傳統的 20% 規劃 + 80% 改動）

---

下一篇預告

第 5 篇：實戰案例 – Taiwan Invoice 3 天完成

前四篇教了理論和細節。

最後一篇會示範完整的一人公司工作流：

1. Day 1：規劃 + 寫 CLAUDE.md + 設計文檔
2. Day 2：Claude 實施 + 自動化驗證
3. Day 3：部署 + 監控

看完了，你就可以套用到自己的項目。

---

現在就設置 Hook，開始自動化！ 👋

還有一篇，堅持到最後！💪

前提：讀過第 1 篇，理解「規劃優先」的理念 時間投入：30 分鐘讀 + 30 分鐘寫你自己的 CLAUDE.md 收益：從此每次 prompt 少打 50% 重複內容

---

這一篇的核心觀點

傳統用法：
prompt #1: "用 TypeScript 寫"
prompt #2: "按照我們的命名規則..."
prompt #3: "記得加 unit tests"
prompt #4: "遵守這些安全規則..."

=== vs ===

CLAUDE.md 方法：
寫一次（CLAUDE.md 裡記錄所有規則）
之後：Claude 自動遵守，不用每次都提醒

實際節省：每個 prompt 減少 50-70% 的文字。

---

CLAUDE.md 是什麼

CLAUDE.md 是一份你放在項目根目錄的文檔。

Claude Code 啟動時會自動讀取它，並把規則記住。

# 檔案位置
~/your-project/CLAUDE.md

# Claude 行為
claude
 ├─ 讀取 CLAUDE.md
 ├─ 記住所有規則
 ├─ 每次你輸入 prompt 時遵守
 └─ 不再需要你重複告訴它

類比：

• 傳統方式 = 每次進公司都告訴員工「要穿正式服裝」
• CLAUDE.md 方式 = 第一天讀 dress code，以後自動遵守

---

一人公司應該在 CLAUDE.md 裡寫什麼

第一層：基本信息（不改的東西）

# Project: Taiwan Invoice System

**Stack**: React 18 + Node.js 18 + PostgreSQL
**Language**: TypeScript (strict mode)
**Main concern**: Taiwan tax law compliance

---

## Architecture Decision Log

### Decision 1: Use Strategy Pattern for tax calculation
**Why**: Taiwan tax law changes frequently (new government = new rates)
**Impact**: New tax type can be added in 30 min, not 8 hours
**Done**: ✅

### Decision 2: Keep invoice data immutable once submitted
**Why**: Taiwan tax audit requires unmodifiable records
**Impact**: No delete/edit after submit, only void new ones
**Done**: ✅

好處：

• 6 個月後你自己看，能快速想起設計邏輯
• 新人（或外包）接手，有據可查
• Claude 理解你的業務優先級

第二層：代碼標準（重複最多的東西）

## Code Standards

### File Structure
```
src/
├── components/       # React components
├── pages/           # Page-level components
├── services/        # API calls & business logic
├── utils/           # Helpers
├── hooks/           # Custom React hooks
├── styles/          # CSS modules
└── __tests__/       # Test files (mirror structure)
```

### Naming Conventions
- Components: PascalCase (e.g., InvoiceForm.tsx)
- Utilities: camelCase (e.g., calculateTax.ts)
- Constants: UPPER_SNAKE_CASE (e.g., MAX_INVOICE_AMOUNT)
- Database tables: snake_case (e.g., c_invoice)

### Code Quality Rules

**MUST HAVE**:
- [ ] TypeScript (no `any` type)
- [ ] Unit tests for all logic (TDD)
- [ ] JSDoc for public functions
- [ ] Error handling (no silent failures)

**NEVER**:
- ❌ Hardcode config values (use .env)
- ❌ Leave console.log() in production code
- ❌ Commit commented-out code
- ❌ Use var (only let/const)

為什麼重要：

• Claude 有了標準，自動遵守
• 省去每個 prompt 都要說「按 TypeScript best practices」
• 代碼風格一致，review 更快

第三層：業務邏輯（最容易被遺忘的）

## Taiwan-Specific Rules

### Tax Calculation
- Standard VAT: 5% (applies to most goods)
- Zero-rated: 0% (exports, specific items)
- Tax-exempt: 0% (non-profit, some services)
- Input tax can be deducted if invoice dated in same month

### Invoice Rules
- Invoice number format: GUN (Government Uniform Number)
- Sequence must be continuous
- Cannot be modified after submission
- Must include buyer's company ID + name
- QR code is mandatory for official submission

### Compliance
- Must report to MOPS (Ministry system) by 15th of next month
- Annual audit by tax bureau
- Keep records for 10 years

為什麼重要：

• Claude 有了背景，不會犯「常見的 bug」
• 減少審查時需要找的問題
• 新人學習曲線 ÷ 2

第四層：技術決策（省掉最多討論時間）

## When You Ask Claude to Build Something

### Before Implementation (Planning Phase)
1. Claude enters Plan Mode automatically
2. Claude reads this CLAUDE.md + design docs
3. Claude proposes approach
4. **YOU APPROVE** (or suggest changes)
5. Claude implements

### Testing Strategy
- Unit tests: Must cover edge cases
- Integration tests: For API + database interaction
- Manual testing: Only for UI/UX
- Coverage target: > 85%

### Code Review Checklist
- [ ] Logic is correct (test passes)
- [ ] Taiwan business rules followed
- [ ] No security holes
- [ ] Performance acceptable
- [ ] Error messages are clear (in Chinese)
- [ ] Documentation updated

為什麼重要：

• Claude 知道你的評審標準
• 自動寫出符合預期的代碼
• 不用反覆改

---

一人公司版本的 CLAUDE.md 精簡版

如果你覺得上面太複雜，這是最小版本（30 分鐘可寫完）：

# Taiwan Invoice System

## Stack & Language
- TypeScript + React 18 + Node.js
- Database: PostgreSQL

## Code Rules
- File structure: components/ pages/ services/ __tests__/
- Names: Components = PascalCase, functions = camelCase, constants = UPPER_CASE
- MUST: TypeScript strict, unit tests, JSDoc, error handling
- NEVER: console.log, hardcoded config, var, no tests

## Business Rules
- Tax rates: 5% standard, 0% zero-rated, 0% exempt
- Invoice format: GUN, continuous sequence, immutable after submit
- Compliance: Report to MOPS by 15th, keep records 10 years

## When You Ask Me to Build
1. I'll enter Plan Mode
2. Read design doc + this file
3. Propose approach (you approve)
4. Implement with tests
5. You review

## Important Decisions
1. Tax calculation uses Strategy Pattern (easy to add new rates)
2. Invoices immutable after submit (Taiwan law requirement)

---

Done! Keep this updated as rules change.

寫這個花了多少時間？ 30-45 分鐘。

省了多少時間？ 每週 3-5 小時（因為不用重複解釋）。

---

真實案例：有沒有 CLAUDE.md 的差別

沒有 CLAUDE.md 的一人公司

Day 1, Prompt:
"Build invoice form with validation.
Use React, TypeScript, follow best practices."

Claude builds... but:
- Uses var instead of const ❌
- Only 60% test coverage ❌
- API call has no error handling ❌
- Component name is lowercase ❌

You: "Oh no, 改了改了改了"
時間消耗：8 小時 (1 小時寫 + 7 小時改)

有 CLAUDE.md 的一人公司

Day 1, CLAUDE.md 寫好，然後 Prompt:
"Build invoice form with validation"

Claude builds:
- Automatically uses let/const ✅
- Automatically writes unit tests ✅
- Automatically adds error handling ✅
- Automatically uses PascalCase ✅

You: "一次到位！"
時間消耗：2.5 小時 (30 分鐘規劃 + 2 小時實施)

節省時間：5.5 小時 per feature。 一個月（~4 features）= 22 小時 = 3 整天！

---

怎樣寫一個好的 CLAUDE.md

❌ 常見錯誤

# Project Rules

要遵守我們的架構。要寫好代碼。不要有 bug。

Done!

問題：太模糊，Claude 無法遵守。

✅ 正確方式

# Project Rules

## Code Quality
- MUST: TypeScript strict mode, no `any` type
- MUST: Unit tests for all functions (Jest)
- MUST: Error handling (try-catch or error state)
- NEVER: console.log in production code
- NEVER: var keyword (use let/const)

## File Naming
- Components: PascalCase (InvoiceForm.tsx)
- Utilities: camelCase (calculateTax.ts)
- Tests mirror source: src/foo.ts → src/__tests__/foo.test.ts

好處：具體、可驗證、Claude 能遵守。

規則

1. 具體 > 模糊

• ❌ 「寫好代碼」
• ✅ 「TypeScript strict mode, coverage > 85%, no console.log」

1. 實例 > 敘述

• ❌ 「按照公司命名慣例」
• ✅ 「組件 = PascalCase (InvoiceForm.tsx), 函數 = camelCase (calculateTax.ts)」

1. MUST/NEVER > 建議

• ❌ 「考慮使用 const」
• ✅ 「MUST use const (never var)」

1. 定期更新 > 一次寫完就忘

• 每月審視 1 次
• 如果發現 Claude 經常犯某個錯誤，加入 CLAUDE.md

---

一人公司老闆的 CLAUDE.md 檢查清單

寫完了嗎？檢查一下：

• ☐ 基本信息
• ☐ 項目名稱
• ☐ 技術棧
• ☐ 主要業務邏輯

• ☐ 代碼標準
• ☐ 文件結構
• ☐ 命名約定
• ☐ TypeScript/語言設置
• ☐ 測試要求

• ☐ 業務規則
• ☐ 稅務/財務規則（如有）
• ☐ 數據有效性
• ☐ 合規要求

• ☐ 決策日誌
• ☐ 架構決策 + 理由
• ☐ 為什麼選這個技術

• ☐ 評審標準
• ☐ 什麼樣的代碼才算「完成」
• ☐ 什麼是「不接受」

---

如何開始

Step 1：複製模板（1 分鐘）

cp ~/claude-code-guide/templates/CLAUDE.md.template \
   ~/your-project/CLAUDE.md

Step 2：填入你的內容（30 分鐘）

打開編輯器，按照上面的框架填入：

1. 你的技術棧
2. 你的命名約定
3. 你的業務規則
4. 你的決策理由

Step 3：提交到 Git（2 分鐘）

git add CLAUDE.md
git commit -m "chore: add project rules"
git push

Step 4：開始用（即時）

claude

user: "Add a new invoice field called customer_contact_number"
# 不用再說「用 TypeScript」、「加測試」、「命名要駝峰」
# Claude 自動知道

---

一個月後會發生什麼

Week 1

• CLAUDE.md 寫好
• 第一個功能用新規則
• “哦，還是得改一些東西…”
• 把發現的規則加入 CLAUDE.md

Week 2-3

• Claude 開始學到你的風格
• 改動變少了
• “不錯，大部分對了”

Week 4

• 新功能一次到位 90%+ 正確
• 只需要微調
• 驚嘆「怎麼忽然快這麼多」

Month 2+

• CLAUDE.md 成為寶貴資產
• 新人/外包根據 CLAUDE.md 快速上手
• 你的編碼風格一致，代碼可維護性 ↑

---

一個常見問題：CLAUDE.md 應該多詳細

答案：「足夠清楚讓 Claude 不猜測」

測試方法：

1. 寫 CLAUDE.md
2. 給 Claude 一個簡單的 prompt
3. 看結果
   - 如果 Claude 做對了 90%+ → 夠詳細
   - 如果還要改 → 加更多細節

一人公司的理想狀態：

• 一份 1000-2000 字的 CLAUDE.md
• 涵蓋 70% 的日常情況
• 20% 用 design docs（下一篇講）
• 10% 需要臨時 prompt

---

重點回顧

CLAUDE.md 是「一次性投資」：

30 分鐘寫 CLAUDE.md
  ↓
之後每周省 3-5 小時
  ↓
一年省 150+ 小時
  ↓
相當於半個全職開發者的成本！

你如果是一人公司老闆，這是值得的投資。

---

下一篇預告

第 3 篇：設計文檔模板

CLAUDE.md 處理「永遠不變的規則」

那「會變的東西」（業務邏輯、UI 流程）怎麼辦？

用設計文檔。

下一篇我會告訴你：

• 怎樣寫一份 2 小時內完成的設計文檔
• 讓 Claude 看懂你的想法，一次實施正確
• 實例：Invoice 功能設計文檔

---

現在就做這一件事

1. 打開編輯器
2. 複製上面的「精簡版 CLAUDE.md」
3. 填入你的技術棧和規則
4. 保存為 ~/your-project/CLAUDE.md
5. git add + commit

花時間：30 分鐘 收益：未來每週省 3-5 小時

下一篇見！👋

前提：已寫好 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)

---

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

寫給：一人公司老闆、獨立開發者 痛點：時間少、要求多、不能重複勞動 解決方案：用規劃優先的工作流 + Claude Code

---

你的困境（認真的）

你一個人同時是：

• 💼 產品經理（要什麼功能）
• 🔨 開發者（怎麼建）
• 🧪 QA（有沒有 bug）
• 📚 文檔編寫者（怎麼用）
• 🚀 運維（部署和監控）

時間分配很絕望：

• 實際寫代碼：可能只有 30%
• 重複做同樣的決策：20%
• 找 bug、修 bug：20%
• 手動測試：15%
• 其他雜事：15%

結果：

• 一個月才能交付一個功能
• 沒時間優化
• 沒時間文檔
• 夢裡都在 debug

---

一般人的解決方案（都不對勁）

❌ 方案 1：招一個開發者

• 成本：月薪 $2000-4000
• 你的增加成本：70-80% (管理、協調、溝通)
• 結果：不划算，特別是你的需求變化快

❌ 方案 2：外包給開發公司

• 成本：$1000-3000 per feature
• 問題：
• 他們不懂你的業務邏輯
• 一堆 bug 需要反覆修
• 根本沒人維護
• 改 UI 要等一周

❌ 方案 3：用低代碼/無代碼工具

• 優點：快速上手
• 缺點：
• 超過基本功能就卡住
• 無法擴展
• 數據鎖定在平台
• 月費永不停止

---

✅ 我的方案：Claude Code + 規劃優先

這個方案的核心理念：

少 prompt（提示詞）→ 多文檔（規劃文件）→ 穩定開發

運作邏輯：

傳統 Claude Code 用法：
user: "加個登入功能"
claude: "好，現在實施..."
結果: 80% 對，20% 要改，改 3 次才對 ❌

===

我的方法：
user: 先寫設計文檔
   ├─ 登入流程圖
   ├─ 數據模型
   ├─ API 規格
   ├─ 錯誤情況
   └─ 安全檢查點

claude: 讀完設計文檔
       → 一次到位 ✅
       → 90%+ 對
       → 最多微調 1-2 次

為什麼效果這麼好？

1. 你花 2 小時規劃，省 8 小時改

• Claude 少猜測 80%
• 實施清晰，bug 少

1. 從此不重複決策

• 設計一次，可重用
• 新人接手也看得懂
• 6 個月後改需求，有據可查

1. Claude 更聰明

• 它讀懂需求精細度 ↑ → 代碼品質 ↑
• 不再「我猜你想要」
• 自動找出邊界情況

1. 自動化率提高

• Hooks 自動 lint + format
• 測試自動跑
• 手動操作 ↓ 50%

---

一人公司的黃金公式

CLAUDE.md (5 min 寫)
  ↓
設計文檔 (20-30 min 寫)
  ↓
Claude Code 實施 (1-2 hours)
  ↓
驗收 (15 min)
  ↓
上線 (5 min)
  ↓
自動化監控 (0 min，Hook 搞定)

總時間：2-3 hours per feature ✅

vs

傳統方式：
實施 → 測試 → 修改 1 → 測試 → 修改 2 → ...
總時間：8-16 hours per feature ❌

---

這個系列會教你什麼

📖 第 1 篇 (本篇)：為什麼規劃優先

📖 第 2 篇：建立你的「編碼憲法」

• CLAUDE.md 怎麼寫
• 一次性規則，永遠生效
• 讓 Claude 記住你的風格和要求

例：

你寫一次：「所有 API 返回都要帶 error_code」
之後：Claude 永遠自動加這個，不用提醒

📖 第 3 篇：設計文檔模板

• Invoice 系統設計文檔怎麼寫
• 從業務需求到技術規格
• 讓 Claude 能一次實施正確

📖 第 4 篇：自動化 Hook

• 自動格式化、自動測試、自動檢查
• 從此沒有手動 lint 這種事
• 節省每週 5-10 小時

📖 第 5 篇：實戰案例 – Taiwan Invoice System

• 完整的一人公司開發流程
• 從零到部署，3 天內完成
• 如何用 Plan Mode 少 prompt

---

一人公司老闆應該知道的三件事

事實 1：你的時間不是資源，是稀缺商品

你的時間 ≠ 開發者的時間

你 1 小時的時間價值 = 你一個小時的營收機會成本

所以：

• ✅ 花 30 分鐘規劃（你做）
• ❌ 不要花 8 小時反覆改（讓 Claude 做，正確率 90%+）

事實 2：文檔是最好的投資

一個一人公司最怕什麼？

• 不是 bug
• 不是需求改變
• 是「我忘了為什麼這樣設計」

3 個月後：

• ❌ 沒文檔：「為什麼税務計算這樣寫？誰知道… 反正改不了」
• ✅ 有文檔：「哦，這是因為台灣稅法 §96，我記得」

事實 3：規劃優先，自動化第二

很多人想著「如何自動化我的工作」

正確的順序是「如何規劃好我的工作」才能「自動化」

類比：

• 製造業 1.0：手工 → 效率低
• 製造業 2.0：流程化 + 自動化 → 效率高
• 開發 1.0：隨意寫代碼 + 手動測試 → 慢
• 開發 2.0：規劃 + 自動化 → 快

---

你應該期待什麼結果

Week 1（學習）

• 讀完這個系列（2 小時）
• 寫出你的 CLAUDE.md（1 小時）
• 設置 Hook（30 分鐘）
• 第一個功能用新方法（3 小時）

Week 2-4（習慣）

• 每個功能都有設計文檔（快速發現問題）
• 自動化 lint/test（省去手動操作）
• 改需求不再是「全部改」，而是「增量改」

Month 2（收穫）

• 開發速度 ×3
• bug 率 ÷2
• 個人壓力 ÷3
• 有時間優化產品

Month 3+（習慣）

• 文檔成為資產（不是負擔）
• 新功能開發時間可預測（不再「要多久」→「大概 2 天」）
• 可以考慮擴招（有文檔，新人能快速上手）

---

下一篇預告

第 2 篇：CLAUDE.md – 你的編碼憲法

我會教你怎樣用一份文檔，讓 Claude 永遠記住：

• 你的代碼風格
• 你的業務邏輯
• 你的命名約定
• 你的安全要求

寫一次，永遠受用。

---

現在就開始

問自己三個問題：

1. 我上週浪費了多少時間在「改 bug」上？

• < 3 小時：你還不夠痛苦，可以緩一緩
• 3-10 小時：現在該改了
• \> 10 小時：你應該昨天就開始

1. 我有沒有寫過設計文檔？

• 沒有：你損失了 80% 的時間
• 有，但是手寫的：轉換成模板化的吧

1. 我願不願意花 2 小時規劃，換 8 小時省下來？

• 願意：到第 2 篇見！
• 不願意：你可能不是一人公司老闆該有的效率思維

---

系列文快速導航

篇章	標題	重點	你需要做什麼
1️⃣	為什麼規劃優先	理解痛點	讀完，認同理念
2️⃣	CLAUDE.md 編碼憲法	寫一份文檔	複製模板，填入自己的規則
3️⃣	設計文檔模板	學會規劃	為下個功能寫設計文檔
4️⃣	Hook 自動化	節省時間	設置 3-5 個 Hook
5️⃣	實戰：Taiwan Invoice	看完整案例	套用到自己的項目

---

核心觀念一句話

「規劃優先，少 prompt；文檔優先，少反覆。」

多花 30% 規劃時間，省 70% 改動時間。

一人公司的職責太多，不能靠「反覆試錯」活著。

下一篇見！👋