Claude Code 系列文 (2/5)：CLAUDE.md — 你的編碼憲法

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

下一篇見！👋