[ai/08] AI 工具最佳配置：從 Claude Code 到多 Agent 工作流

cover

先講結論

配置 AI 工具不是什麼高深的技術活，但它是「用得順」和「每次都想摔鍵盤」之間的分水嶺。我自己花了大概兩個月，才從「裝好就用」進化到「系統性配置」，這中間踩的坑比我寫的 bug 還多。

核心就三件事：

CLAUDE.md — 讓 AI 記住你的專案規範，別再每次對話都從「我的專案用 TypeScript…」開始
Skills — 把重複的 prompt 封裝成可重用模組，~~因為人生苦短，不該花在重複貼 prompt 上~~
Memory — 跨對話累積經驗，讓 AI 不再像金魚一樣七秒忘記一切

如果你還在「裝好就用」的階段，這篇幫你省下那兩個月。如果你已經會配了但想做多 Agent 和 MCP 整合，請直接看下篇。

settings.json：你的第一道防線

settings.json 控制 Claude Code 的全域行為。我的建議是：從最小權限開始，被煩到受不了再逐步開放。

// ~/.claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(npm test:*)",
      "Bash(pnpm build:*)"
    ]
  },
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

為什麼不直接全部打開？因為你遲早會遇到 AI 自作主張跑 rm -rf 的那天。~~問我怎麼知道的？別問。~~

權限三種策略：

最小權限：只允許 read-only 和測試 → 碰生產環境用這個
開發友善：允許 git、test、build → 日常開發夠用
完全信任：dangerouslyDisableSandbox → 本地實驗才開，名字都寫 dangerously 了你還要我說什麼？

CLAUDE.md：讓 AI 了解你的專案

這是整個配置裡 CP 值最高的一件事。沒有 CLAUDE.md 的 AI 就像新來的同事第一天上班——什麼都要問、什麼都搞不清楚。

載入順序是這樣的：

~/.claude/CLAUDE.md          ← 全域（你的個人習慣）
  └── project/CLAUDE.md      ← 專案根目錄（團隊規範）
        └── src/CLAUDE.md    ← 子目錄（模組特定）

一個實用的 CLAUDE.md 長這樣：

# 專案名稱
 
## 技術棧
- Runtime: Node.js 20 + TypeScript 5.x
- Framework: Express.js
- Database: PostgreSQL + Prisma ORM
 
## 架構概述
- `src/routes/` — API endpoints
- `src/services/` — Business logic
- `src/models/` — Prisma schema & types
 
## Coding Standards
- 使用 functional programming style，避免 class
- 所有 async 函式必須有 error handling
- API response 統一用 `{ data, error, meta }` 格式
 
## 禁止事項
- 不要修改 prisma/schema.prisma（需要 migration 流程）
- 不要用 any type

重點來了，以下是我踩過的坑：

問題	為什麼有害	怎麼修
超過 1000 行	AI 會忽略後半段，跟人一樣	控制在 500 行內，細節另外開文件
太抽象：「寫好的 code」	AI 不知道你定義的「好」是什麼	給具體規則 + 正反例
沒有範例	AI 只好自由發揮	每個規則至少附一個例子
放了 API key	CLAUDE.md 會被 commit	敏感資訊永遠放環境變數

你有沒有想過，為什麼每次 AI 的輸出風格都不一致？九成是因為你的 CLAUDE.md 寫得太模糊。

Skills：別再重複貼 prompt 了

如果你在不同對話中重複打同樣的指令超過三次，就該把它變成 Skill。就這麼簡單的判斷標準。

---
name: code-review
description: 對目前的 git diff 做安全性與品質的 code review
---
 
# Code Review Skill
 
## 步驟
1. 用 `git diff --staged` 取得待 commit 的變更
2. 針對每個變更檔案檢查：
   - 安全漏洞（SQL injection、XSS、敏感資訊外洩）
   - 效能問題（N+1 query、不必要的 re-render）
   - 程式碼品質（命名、重複邏輯、錯誤處理）
3. 產出 review 報告

我自己常用的 Skills：

Skill	觸發方式	幹嘛用的
`code-review`	`/code-review`	自動 review staged changes
`commit`	`/commit`	分析 diff 產生 commit message
`blog-writing`	`/blog-writing`	按固定格式寫 blog
`test-gen`	`/test-gen`	為指定函式生成測試

Skill 的精髓是 Progressive Disclosure——metadata 精簡、步驟明確、格式有範例。寫太長的 Skill 跟寫太長的 CLAUDE.md 一樣，AI 會選擇性失明。

Memory：讓 AI 累積經驗

Memory 不是聊天記錄的備份，是提煉過的「教訓和知識」。你每次踩的坑、發現的 workaround，都應該變成 Memory。

~/.claude/projects/{project-hash}/memory/
├── MEMORY.md              ← 主檔（自動載入，限 200 行）
├── debugging.md           ← 除錯經驗
├── patterns.md            ← 程式碼模式
└── architecture.md        ← 架構決策記錄

MEMORY.md 寫法示範：

## 踩坑紀錄
- Notion API 回傳超冗長 → 只提取 title+id，立即寫入檔案
- Gateway 429 errors → Google model fallback 造成，統一用同一個 model
- Windows Git Bash 會 mangle `/FI` flag → 改用 PowerShell
 
## 不該記的
- 特定對話的臨時結果
- 完整的程式碼片段（放在檔案裡，memory 只記位置）
- 過期的資訊

CLAUDE.md 和 Memory 的分工？簡單說：CLAUDE.md 是「應該怎麼做」（靜態規範），Memory 是「我學到了什麼」（動態經驗）。前者適合 commit 進 repo 跟團隊共享，後者是你個人的。

配置清單（速查用）

Do：

CLAUDE.md 保持 500 行以內，具體規則配範例
Memory 按主題分檔，主檔控制 200 行
Skills 遵循 Progressive Disclosure
配置檔案納入版本控制（除了 Memory 和 API key）

Don’t：

不要在 CLAUDE.md 放敏感資訊
不要讓 Memory 變流水帳
不要跳過 AI 輸出的驗證——它會 hallucinate 檔案存在
不要在多處重複定義同樣的規則

下篇 MCP 整合與多 Agent 工作流會講 Gateway、MCP 效能優化、多 Agent 協作，以及 Windows 上的各種地雷。

配置 AI 工具就像整理房間——你永遠覺得「之後再弄就好」，直到某天在垃圾堆裡找不到自己的 API key。

Terry Yao's Blog

分類

目錄