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

為什麼需要「配置」AI 工具

大多數人用 AI 工具的方式是「裝好就用」—— 打開 ChatGPT 貼個問題、在 VS Code 裝個 Copilot 就開始寫 code。這沒問題，但你會逐漸碰到瓶頸：

• AI 不了解你的專案架構，每次都要重新解釋
• 重複的 prompt 沒辦法重用，每次都在重新打字
• 跨工具（Notion、Gmail、Discord）的操作需要手動搬運
• 多人協作時，AI 的行為規範無法統一

「裝好就用」                    「系統性配置」
每次重新解釋背景 ────→ CLAUDE.md 記住專案規範
同樣的 prompt 重打 ────→ Skills 封裝可重用技能
手動搬資料 ──────────→ MCP 連接外部工具
經驗丟失 ──────────→ Memory 累積跨對話記憶

本文不是入門教學。如果你需要了解 AI 工具的基礎概念，請先閱讀 AI 全景與核心概念。如果你需要了解工作流自動化的工具選型，請參考 AI 工作流自動化。

本文聚焦在：你已經在用了，如何讓它更強。

全景架構

flowchart TD
    subgraph "開發者環境"
        CC["Claude Code\n(IDE 整合)"]
        CM["CLAUDE.md\n專案規範"]
        SK["Skills\n可重用技能"]
        MEM["Memory\n持久記憶"]
    end

    subgraph "連接層"
        GW["Gateway\nAPI 路由 & 成本控制"]
        MCP["MCP Servers\n外部工具整合"]
    end

    subgraph "外部服務"
        NT["Notion"]
        GM["Gmail"]
        DC["Discord Bot"]
        LLM["LLM Provider\n(OpenAI / Anthropic)"]
    end

    CC --> CM
    CC --> SK
    CC --> MEM
    CC --> GW
    CC --> MCP
    GW --> LLM
    MCP --> NT
    MCP --> GM
    DC --> GW

    style CC fill:#4CAF50,color:#fff
    style GW fill:#FF9800,color:#fff
    style MCP fill:#2196F3,color:#fff

---

Claude Code 配置深入

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"
  }
}

權限設計原則：

策略	說明	適用場景
最小權限	只允許 read-only 和測試指令	生產環境相關專案
開發友善	允許 git、test、build	日常開發
完全信任	dangerouslyDisableSandbox	本地實驗、自動化 pipeline

建議：從最小權限開始，遇到頻繁需要確認的指令再逐步加入 allow 清單。

CLAUDE.md：專案級行為規範

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
- Testing: Vitest + Supertest
 
## 架構概述
- `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 流程）
- 不要在 service 層直接 import route
- 不要用 any type
 
## 測試要求
- 新增功能必須附帶測試
- 用 `pnpm test` 執行測試

常見錯誤：

問題	為什麼有害	解法
CLAUDE.md 超過 1000 行	AI 會忽略後面的內容	保持在 500 行以內，細節用連結指向其他文件
太抽象：「寫好的 code」	AI 不知道你定義的「好」是什麼	給具體規則和正反例
沒有範例	AI 猜不到你要的格式	每個規則附一個好的例子
放敏感資訊	CLAUDE.md 可能被 commit	API key 放環境變數，不放 CLAUDE.md

Skills 系統：可重用的技能包

Skills 是 Claude Code 的「可重用 prompt 模組」。當你發現自己在不同對話中重複打同樣的指令，就該把它變成 Skill。

SKILL.md 的結構（Progressive Disclosure）：

---
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 報告，格式：
 
## Review 報告格式
| 檔案 | 嚴重性 | 問題 | 建議 |
|------|--------|------|------|

實用 Skills 範例：

Skill	觸發方式	用途
code-review	/code-review	自動 review staged changes
commit	/commit	分析 diff 並生成 commit message
blog-writing	/blog-writing	按照固定格式撰寫 blog 文章
test-gen	/test-gen	為指定函式生成測試

Memory 系統：跨對話的持久記憶

Memory 讓 AI 在不同對話之間累積經驗。它不是聊天記錄，而是提煉過的教訓和知識。

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

MEMORY.md 最佳寫法：

# 專案 Memory
 
## 關鍵架構
- Gateway port: 18789
- 主要 model: openai-codex/gpt-5.2-codex
- MCP: Notion (22 tools), Gmail (21 tools)
 
## 踩坑紀錄
- Notion API 回傳過於冗長 → 只提取 title+id，立即寫入檔案
- Gateway 429 errors → 是 Google model fallback 造成，統一用同一個 model
- Windows Git Bash 會 mangle `/FI` flag → 改用 PowerShell
 
## 不該記的
- 特定對話的臨時結果
- 完整的程式碼片段（放在檔案裡，memory 只記檔案位置）
- 過期的資訊

Memory vs CLAUDE.md 的分工：CLAUDE.md 是靜態規範（「應該怎麼做」），Memory 是動態經驗（「我學到了什麼」）。CLAUDE.md 適合 commit 進 repo，Memory 是個人化的。

Agent Teams：多 Agent 協作

Agent Teams 讓你同時啟動多個 Claude Code 實例，各自負責不同的子任務：

sequenceDiagram
    participant Lead as Team Lead
    participant R as Researcher
    participant C as Coder
    participant T as Tester

    Lead->>R: 調查現有 API 結構
    Lead->>C: 實作新的 endpoint
    R-->>Lead: API 結構報告
    Lead->>C: 附上 API 結構，繼續實作
    C-->>Lead: 實作完成
    Lead->>T: 跑測試
    T-->>Lead: 測試通過

適用場景：

場景	為什麼需要多 Agent
大型重構	一個 agent 分析、一個 agent 修改、一個 agent 測試
Blog 內容規劃	一個 agent 審計、一個 agent 寫文章、一個 agent 修 backlink
跨模組功能	前端 agent + 後端 agent + 測試 agent 並行

限制與注意事項：

• 每個 agent 的 context 是獨立的，不共享對話歷史
• 通訊靠 SendMessage 工具，有延遲
• 在 Windows 上，agent 的檔案編輯需要權限確認（bottleneck）
• 建議 team 規模控制在 3-5 個 agent，太多會增加協調成本

---

MCP 整合配置

MCP（Model Context Protocol）是 AI 的標準化工具介面，讓 Claude Code 能直接操作外部服務。概念詳見 AI 工作流自動化。

mcporter 實戰配置

mcporter 是管理 MCP server 連接的 CLI 工具：

# 安裝
npm i -g mcporter
 
# 列出已配置的 MCP server
mcporter list
 
# 呼叫 Notion API
mcporter call notion notion_search '{"query": "blog"}'
 
# 呼叫 Gmail API
mcporter call gmail gmail_search_messages '{"query": "from:github.com"}'

Notion MCP 常用操作：

操作	工具名稱	用途
搜尋	notion_search	全域搜尋 page/database
讀取	notion_get_page	取得特定 page 內容
查詢	notion_query_database	查詢 database 記錄
建立	notion_create_page	新建 page
更新	notion_update_page	更新 page 屬性

MCP 效能優化

Notion API 回傳的 JSON 非常冗長。8 次 mcporter 呼叫就能填滿 2.4MB 的 session context，導致 context_length_exceeded 錯誤。

解法：

❌ 錯誤做法：直接把 API response 放在 context 裡
   mcporter call notion notion_search '{"query": "blog"}'
   → 回傳 500KB JSON → context 爆炸

✅ 正確做法：只提取需要的欄位，立即寫入檔案
   1. 呼叫 API
   2. 只取 title + id
   3. 寫入 ~/tmp/notion-results.json
   4. Context 裡只留「已寫入檔案，共 24 筆」

策略	說明
只取需要的欄位	不要把整個 response 留在 context
立即寫入檔案	API response → 檔案，context 只留摘要
分批呼叫	一次查 10 筆，不要一次查 100 筆
Rate limit 處理	遇到 429 就等待重試，不要狂送

---

Gateway 設定

為什麼需要 Gateway

當你有多個 AI 工具（Claude Code、Discord Bot、自動化腳本）都需要呼叫 LLM 時，讓它們各自管理自己的 API key 會很混亂。Gateway 提供統一的 API endpoint：

flowchart LR
    CC["Claude Code"] --> GW["Gateway\n:18789"]
    Bot["Discord Bot"] --> GW
    Script["自動化腳本"] --> GW
    GW --> Provider["LLM Provider"]

    style GW fill:#FF9800,color:#fff

Gateway 的好處：

• API key 集中管理：只在 Gateway 設定一次
• 模型路由：不同 client 可以用不同 model
• 成本監控：所有呼叫都經過同一個點
• Rate limit 統一處理：避免各 client 互搶配額

Gateway 配置要點

// openclaw.json（關鍵設定項）
{
  "gateway": {
    "port": 18789,
    "model": "openai-codex/gpt-5.2-codex"
  },
  "agents": {
    "defaults": {
      "heartbeat": {
        "interval": "30m",
        "activeHours": "08:00-23:00",
        "timezone": "Asia/Taipei"
      }
    }
  }
}

踩坑紀錄：

問題	原因	解法
大量 429 errors	設了 Google model fallback，兩個 provider 互搶	統一用同一個 model，不設 fallback
Gateway 無法啟動	Service mode 有 bug	用 pnpm openclaw gateway（direct mode）代替
Session 越來越慢	sessions.json 累積太多舊資料	定期寫入 {} 清空，強制新 session

---

多 Agent 工作流配置

單 Agent vs 多 Agent

考量	單 Agent	多 Agent
任務複雜度	單一面向的任務	多面向、可並行的任務
Context 需求	一個 context 就夠	各子任務需要獨立 context
通訊成本	無	有（SendMessage 延遲）
協調複雜度	低	中~高
適用場景	bug fix、single file edit	重構、大型 feature、文件審計

經驗法則：如果任務能拆成 3 個以上獨立的子任務，而且每個子任務需要閱讀不同的檔案，就值得用多 Agent。

ClawdBot（Discord Bot）配置要點

如果你有用 Discord Bot 作為 AI 介面，system prompt 的設計至關重要：

必須包含的資訊：
✅ 執行環境（Windows 11, NOT Docker）
✅ 所有相關檔案的完整路徑
✅ Shell 規則（不要用 bash heredoc、不要寫 wrapper script）
✅ Context 管理規則（定期摘要、清理舊 session）
✅ 任務完成協議（完成後怎麼回報）

常見問題：
❌ Agent 在 Windows 上用 bash syntax（heredoc、管道）
❌ Agent 用 `message send` 發訊息（Bot 會忽略自己的訊息）
❌ Session 膨脹導致 context overflow

---

跨工具協作配置

工具間的資料流

Claude Code ──→ Git Repo ──→ CI/CD ──→ 部署
     │              │
     ├── CLAUDE.md  ├── ClawdBot 讀取 repo 狀態
     ├── Skills     │
     └── Memory     └── MCP ──→ Notion（文件同步）
                              ──→ Gmail（通知）

配置同步策略

配置類型	同步方式	說明
CLAUDE.md	Git	跟著 repo 走，團隊共享
Skills	Git 或本地目錄	通用 skills 放 repo，個人 skills 放 ~/.claude/
Memory	本地	個人化，不適合共享
settings.json	本地	機器特定的全域設定

Windows 環境的特殊處理

在 Windows 上使用 AI 工具時，有幾個陷阱值得注意：

問題	說明	解法
Git Bash flag mangling	/FI 被轉成 C:/Program Files/...	改用 powershell -Command "..."
路徑分隔符	\ vs /	在 CLAUDE.md 裡明確指定路徑格式
Shell 語法衝突	Bash heredoc 在 PowerShell 不可用	禁止使用 bash syntax，統一用 PowerShell
taskkill 語法	Git Bash 會 mangle /PID	用 powershell -Command "Stop-Process -Id PID -Force"

---

配置最佳實踐清單

Do’s

1. CLAUDE.md 保持在 500 行以內，用具體規則搭配範例
2. Memory 按主題分檔，主檔控制在 200 行
3. Skills 遵循 Progressive Disclosure，metadata 精簡
4. MCP 呼叫後立即提取關鍵資訊寫入檔案
5. Gateway 設定 rate limit，統一 model 不做 fallback
6. Session 定期清理，避免 context 膨脹
7. 配置檔案 納入版本控制（除了 Memory 和 API key）

Don’ts

1. 不要在 CLAUDE.md 放敏感資訊（API key、密碼）
2. 不要讓 Memory 變成流水帳
3. 不要一次載入所有 MCP server（按需啟用）
4. 不要跳過 Agent 輸出的驗證 — AI 會 hallucinate 檔案存在、路徑正確
5. 不要在多處重複定義相同的規則（DRY 原則）
6. 不要讓 Agent Teams 超過 5 個 agent（協調成本超過收益）

---

延伸閱讀

• AI 全景與核心概念 — AI 基礎概念和模型選型
• RAG 架構實務 — 需要 AI 做知識庫搜尋時的架構
• AI 工作流自動化 — n8n/LangChain/Agent 的工具選型
• AI 工具生態系 — Skills、MCP、Bot 架構的完整介紹