你是否有過這樣的經驗：跟 Claude Code 說了一大段需求，它做出來的結果差了一點點，於是你開始修正、補充說明、再確認，來回四五輪才終於完成？

這篇文章整理的，就是如何系統性地消滅這些來回。不靠運氣，靠結構。

1. CLAUDE.md：把規則寫進專案，不用每次重說

CLAUDE.md 是 Claude Code 自動載入的專案規則檔，放在 ~/your-project/CLAUDE.md。它是永久生效的，只要存在，每次對話都會自動套用。

效果：寫一次，永久有效，減少 50–70% 重複提示。

CLAUDE.md 應該寫什麼

分四層，由外到內：

層次	內容	範例
基本資訊	Tech stack、架構決策	Next.js 14 App Router + PostgreSQL
代碼標準	命名規則、檔案結構	TypeScript strict mode，禁止 any
業務邏輯	領域規則、合規要求	台灣統一編號驗證邏輯
技術決策	測試策略、代碼審查規則	每個函數必須有對應單元測試

可直接複製的最小版 CLAUDE.md

# 專案規則

## Tech Stack
- Runtime: Node.js 20, TypeScript strict
- Frontend: Next.js 14 App Router
- Database: PostgreSQL + Prisma ORM
- Testing: Vitest + Testing Library

## 代碼標準
- 禁止使用 `any` 類型
- 所有 API 回應都必須有錯誤處理
- 命名：camelCase 變數/函數，PascalCase 元件
- 每個新函數必須有對應測試

## 禁止事項
- 不要在 .env 以外的地方寫入 secrets
- 不要 commit node_modules
- 不要繞過 TypeScript 類型檢查

## 測試策略
- 單元測試：純函數、工具類
- 整合測試：API routes、資料庫操作
- E2E：核心用戶流程

常見錯誤：規則太模糊（「要寫好的代碼」）。寫 CLAUDE.md 要具體到可驗證，例如「API 回應必須包含 { success, data, error } 結構」。

2. 設計文件：讓 Claude 第一次就做對

沒有設計文件，Claude 會根據最可能的假設去實作。你的需求愈複雜，這些假設偏離你想法的機率就愈高。

設計文件 ≠ CLAUDE.md：CLAUDE.md 是永久規則，設計文件是「這個功能」的一次性說明。

最小版設計文件（20 分鐘內完成）

# 功能：[名稱]

## 要做什麼
[一段話描述，包含用戶場景]

## 輸入 / 輸出格式
輸入：{ invoiceNumber: string, amount: number }
輸出：{ success: boolean, invoiceId: string }

## 邊界條件
- 金額為 0 時：回傳錯誤，不建立發票
- 統編格式錯誤時：拋出 ValidationError
- 重複發票號碼：回傳已存在的 invoiceId

## 完成定義（Done When）
- [ ] 所有邊界條件有對應測試
- [ ] API 回應符合 CLAUDE.md 定義的格式
- [ ] TypeScript 0 errors

這 20 分鐘可以省下 4–6 小時的修改。數學很簡單。

複雜場景：從用戶故事快速產出設計文件

當你腦中只有模糊需求，可以用這個提示讓 Claude 幫你產出設計文件初稿：

我需要實作：[用戶故事]

請幫我寫一份設計文件，包含：
1. 功能描述（一段話）
2. 輸入/輸出格式（JSON 範例）
3. 邊界條件清單
4. 完成定義

不要實作，只寫文件。

確認文件正確後，再說「依照這份設計文件實作」。這是「計劃→確認→執行」的標準流程，比直接說需求減少至少 2 輪來回。

3. Plan Mode：大型任務的正確啟動方式

Plan Mode 是 Claude Code 的三段式決策機制：探索 → 規劃 → 用戶確認。只有用戶批准後才開始執行，避免走錯方向浪費的大量時間。

何時使用 Plan Mode

場景	使用 Plan Mode？	原因
修一個 bug	不需要	範圍小，直接做
新增一個 API endpoint	不需要	單一改動
重構模組（跨 5+ 個文件）	需要	需要確認拆分策略
架構遷移（框架升級）	需要	不可逆，要先對齊
全新功能模組（3 天以上工作量）	需要	複雜度高，先確認再做

Plan Mode 的正確提示格式

啟動 Plan Mode 後，給 Claude 的提示要包含三個部分：

【背景】
這個專案是 [系統描述]，目前 [現況]。

【目標】
我需要 [具體目標]，完成後要能 [驗收標準]。

【約束條件】
- 不能破壞現有的 [X] 功能
- 必須相容 [Y] 版本
- 不要修改 [Z] 目錄的任何檔案

請先制定實作計劃，列出方案選項和取捨，等我確認後再開始執行。

「等我確認後再開始執行」這句話非常關鍵。沒有這句話，Claude 可能在呈現計劃的同時就開始執行了。

4. Agent Teams：平行作業的正確姿勢

Agent Teams 讓多個 Claude 實例同時處理獨立任務。正確使用可以把 3 天的工作壓縮到 1 天，錯誤使用會讓機器記憶體爆掉。

模型選擇速查

模型	記憶體	適合任務	口訣
Opus	~1GB/agent	架構決策、複雜業務邏輯、Code Review	需要「想」
Sonnet	~600MB/agent	CRUD 實作、API 對接、表單頁面	需要「做」
Haiku	~400MB/agent	檔案掃描、配置對比、簡單查詢	需要「找」

建立 Agent Team 前必做的三件事

1. 評估記憶體：執行 free -h，可用記憶體必須大於預計用量的 1.5 倍（安全邊界）
2. 拆分獨立任務：每個 agent 的任務不能有隱性依賴，確認前後順序再分配
3. 準備共用 CLAUDE.md：所有 agent 共享同一套規則，避免各自用不同標準

任務拆分原則

適合平行的任務：API endpoint A、API endpoint B、前端表單 C（互不依賴）

不適合平行的任務：「建資料庫 schema」→「實作 API」→「寫測試」（有嚴格先後順序）

# 建立 Agent Team 的標準提示
我需要建立一個 Agent Team 完成以下任務：

【總目標】[一句話]

【任務清單】（已確認互相獨立）
1. [任務 A] → 負責人：Sonnet agent
2. [任務 B] → 負責人：Sonnet agent
3. [任務 C]（需要架構決策）→ 負責人：Opus agent

【共用規則】
- 所有代碼遵守 CLAUDE.md
- 任務完成後回報：完成的文件列表 + 測試通過狀態

【資源限制】
可用記憶體：[X]GB，請確認 agent 數量不超過安全上限。

5. Hooks：讓機器自動做重複的事

Hooks 是在特定事件（編輯後、提交前、排程）自動執行的腳本。設定一次，永久省力。

三個最值得設定的 Hook

Hook 1：編輯後自動格式化（after-edit）

{
  "hooks": {
    "after-edit": {
      "command": "prettier --write $FILE && eslint --fix $FILE",
      "on_failure": "warn",
      "timeout": 30000
    }
  }
}

Hook 2：提交前強制測試通過（before-commit）

{
  "hooks": {
    "before-commit": {
      "command": "npm run test -- --passWithNoTests && npm run lint",
      "on_failure": "block",
      "timeout": 120000
    }
  }
}

"on_failure": "block" 代表測試未通過時 commit 會被阻止，不是只警告。

Hook 3：每週安全掃描（scheduled）

{
  "hooks": {
    "scheduled": {
      "cron": "0 10 * * 6",
      "command": "npm audit fix && npm outdated",
      "on_failure": "warn"
    }
  }
}

這三個 Hook 每週省下約 60 分鐘，一年就是 52 小時。

6. 降低來回、提高準確的通用技巧

多文件上下文提示法

要讓 Claude 了解跨文件的關係，不要一次只給一個文件，要同時提供：

請先閱讀這三個文件後再開始：
- src/types/invoice.ts（資料模型）
- src/api/invoices.ts（現有 API）
- docs/designs/invoice-search.md（本次設計文件）

閱讀完成後告訴我你的理解，再開始實作。

「閱讀完成後告訴我你的理解」這個確認步驟，能在執行前抓到 Claude 對現有代碼的誤解。

邊界條件先行法

把邊界條件和錯誤情況列在需求的最前面，而不是最後面。Claude 讀到越早的內容，優先度越高：

# 不好的順序
實作用戶登入功能，支援 email/password，記得處理密碼錯誤的情況

# 好的順序
實作用戶登入功能

【錯誤情況（必須處理）】
- 帳號不存在 → 401，訊息「帳號或密碼錯誤」（不透露哪個錯）
- 密碼錯誤 → 401，同上訊息
- 連續失敗 5 次 → 鎖定帳號 15 分鐘

【正常流程】
支援 email/password，成功回傳 JWT token

分段確認法（適合複雜場景）

不要一次把整個複雜需求丟給 Claude，分段完成並確認：

1. 「先實作資料模型，不要碰 API 層，完成後給我看」
2. （確認模型正確）「現在依照這個模型實作 API」
3. （確認 API 正確）「現在寫整合測試」

每一段都比整體更容易驗證，錯誤也更容易在早期被發現。

明確說「不要做什麼」

Claude 很善意，會主動補充它認為合理的東西。如果不想要這些補充：

# 加上明確的範圍限制
只修改 src/utils/tax.ts 這個文件，不要動 tests/ 目錄，
不要重構現有函數，只新增 calculateVAT() 函數。

整合使用：複雜功能的標準流程

把上面所有技巧整合成一套可重複使用的流程：

1. 確認 CLAUDE.md 存在且最新（一次性，專案生命週期）
2. 寫設計文件（每個新功能，20–30 分鐘）
3. 用「計劃→確認→執行」啟動任務（複雜任務用 Plan Mode）
4. 分段驗證（模型 → API → 測試，每段確認一次）
5. Hooks 自動把關（格式、測試、安全）

這套流程把原本 10–15 輪的來回壓縮到 2–3 輪。

常見問題

Q：CLAUDE.md 要多詳細才夠？

夠到「可以驗證」就夠了。「代碼要好維護」是沒用的規則，「函數超過 50 行必須拆分」是有用的規則。從最重要的 5 條開始，持續更新。

Q：設計文件需求中途改了怎麼辦？

先更新設計文件，再告訴 Claude「設計文件已更新，請依最新版本繼續，以下是改變的部分：[…]」。不要只口頭說需求變了，有文件才有依據。

Q：Agent Teams 記憶體爆掉怎麼辦？

立即執行 free -h 確認狀況，用 ps aux --sort=-%mem | head -20 找出佔用最多的 agent，優先結束 Opus 實例。恢復後先用 git status 確認哪些工作已完成，從斷點繼續而不是重頭來過。

Q：Claude 輸出的代碼跟我的風格差很多？

這幾乎都是 CLAUDE.md 不夠具體的問題。找一個你認為寫得好的現有文件，告訴 Claude「比照這個文件的風格」，然後把那個風格總結後加進 CLAUDE.md。