Claude Code 三層架構：CLAUDE.md / Memory / Skills

我們如何整理 memory、skills 和專案指令，讓 token 消耗減少 35%，新成員加入不需要任何教學。

背景：為什麼需要三層架構

我們建立了一支 12 個 AI agent 並行工作的團隊，兩天完成 5 門 AIA 建築師課程、7 篇文章、284 張投影片。但隨著 agent 數量增加，memory 檔案膨脹到 5,000+ tokens，每次對話有 80% 的 context 根本用不到——我們在為一堆無關資訊付費。

解法是把 context 分成三層：永遠載入的規則、精簡的索引指標、按需載入的完整手冊。以下是具體做法。

大幅降低 Token 使用的方法：三層架構

核心洞見：不是所有 context 都需要隨時載入。把「永遠相關」和「偶爾相關」分開，讓 AI 在需要時才按需載入後者。

第一層：CLAUDE.md（永遠載入）

這是 AI 的「入職指南」。任何人在專案目錄開啟 Claude Code，AI 都會自動讀取這個檔案。它是你的團隊與 AI 之間的約定。

CLAUDE.md 裡放的是最核心的兩件事：

• 意圖偵測表——AI 看到你說什麼話，就知道該用哪個 skill（下面會詳細講）
• 基本規則——語言設定、內容放哪裡、部署流程等，讓 AI 不用每次重新學

其他所有東西（詳細工作流程、參考資料、個人偏好）都不放這裡——放到 Skill 或 Memory 裡，需要時才載入。

不要要求使用者背記 slash command，直接在 CLAUDE.md 裡寫一張「行為對應 skill」的對照表：

## Behavior Rules — Proactive Skill Suggestion

Do NOT wait for slash commands. Detect user intent:
- Clear intent → auto-use the skill
- Ambiguous intent → suggest the skill

| When the user...                    | Auto-suggest or use...  |
|-------------------------------------|------------------------|
| Discusses writing an article        | /publish-article       |
| Mentions deploying or uploading     | /upload                |
| Says "done" or "finished editing"   | /upload                |
| Reviews content for accuracy        | /content-review        |
| Is about to git push                | /security-check        |

AI 讀了這張表，就會主動建議正確的 skill，不需要任何記憶。這個改變消除了大約 90% 的「我不知道有這個功能」的 onboarding 摩擦。

第二層：Memory（精簡索引）

目標：所有 memory 檔案加起來不超過 4,000 tokens。

Memory 只應該包含四種資訊：

1. 行為規則——每條 3-5 行。AI 應該如何配合你工作。
2. Skill 指標——每個一行。「遇到 X 情況，用 /skill-y」。
3. 設計偏好——簡短。UI 風格、程式碼慣例。
4. 專案索引——連結到詳細檔案，不是詳細內容本身。

# Memory Index

## Behavior Rules
- [feedback_workflow.md](feedback_workflow.md) — Plan before coding, never jump straight to implementation
- [feedback_delegate.md](feedback_delegate.md) — Use sub-agents for execution, don't code directly

## Skill Pointers
- Writing articles → /publish-article
- Deploying → /upload
- Security scan → /security-check (mandatory before every push)

## Preferences
- [feedback_ui_style.md](feedback_ui_style.md) — Large fonts (16-20px), spacious layout

## Active Projects
- [projects_active.md](projects_active.md) — Links to 3 currently active projects

第三層：Skills（由 CLAUDE.md 觸發載入）

Skill 裡面放的是完整的工作流程——可以很長、很詳細，因為平常不會被載入。只有當 CLAUDE.md 的意圖偵測判斷「現在需要這個 skill」時，才會讀進來。

.claude/skills/
├── CATALOG.md              ← All skills overview (human + AI readable)
├── publish-article/
│   ├── SKILL.md            ← Trigger conditions + operation manual
│   └── references/         ← Detailed docs, loaded when needed
├── security-check/
│   └── SKILL.md
├── aia-rewrite/
│   ├── SKILL.md
│   └── references/
│       ├── writing-guide.md
│       └── aia-standards.md

每個 SKILL.md 的 frontmatter 告訴 AI 什麼時候要載入它：

---
name: publish-article
description: Generate blog articles for watersonusa.ai. Use when the user
  says "write article", "generate content", "新文章", or discusses
  creating content for the website.
---

延伸閱讀

本文聚焦在三層架構的設定。進階主題請參考：

• 用 OGSM 建立 AI Agent 團隊 — 多 agent 團隊的 Objective-Goal-Strategy-Measure 架構
• 多 AI 協作：Claude + Gemini + Codex — 怎麼把工作分配給不同 AI，省錢又高效

與業界最佳實踐的對照

我們的三層架構與 2025-2026 年最新的 AI agent memory 管理模式高度吻合。以下是我們做的事情對應到研究者和從業者使用的術語：

我們已經在做的

接下來可以加的

常見問題