給技術人員的架構導覽

最後更新：2026-03-10 適用對象：接手維護或參與協作的工程師 前提假設：你懂軟體工程，但不一定用過 Claude Code CLI

一句話：這是什麼技術棧？

Claude Code CLI + 自定義 agent/skill/hook/memory 層，建構在 ~/.claude/ 目錄下的一套「AI 驅動的策略分析工作站」。

白話說：這不是一個 web app，而是一台裝滿分析工具的工作台。Claude Code 是作業系統，agent 是員工，skill 是 SOP，hook 是品管流程，memory 是公司制度。整套系統透過終端機（CLI）操作，用 slash command（如 /brand-research、/marketing）觸發完整的多階段分析流程。

核心概念快速理解

Agent -- 想像成有專長的員工

系統裡有 39 位 agent，每位有明確的職責、觸發詞、和思考力度設定（effort）。

比喻：這是一間有 39 人的顧問公司。但你不會每次開會都叫齊 39 人 -- 那不現實，也浪費時間。所以 agent 分成三層操作表面：

Agent 又依職能分成 5 個層級：

決策層 (6)   -- Jobs/Gates/Musk/Popovich/Hassabis/Creative Council
               以真實思維模型命名，各代表不同決策視角
協調層 (1)   -- Orchestrator，雙軌調度（單任務 vs 多視角協作）
產品層 (2)   -- Designer + PM
執行層 (24)  -- 研究院(4) / 策略組(4) / 數據組(3) / 開發組(3) / 品質組(3) / 資安組(3) / 其他(4)
驗證層 (5)   -- Consumer/CFO/Lawyer/Marketer/Skeptic
+ Joker (1)  -- 不屬於任何層級，動態介入打破共識陷阱

為什麼這樣設計？ 想像你做一份品牌調研報告。如果只有一個 AI 去寫，它會自洽但可能有盲點。把不同「專家」拆開，讓 Strategist 做定位、Deep Researcher 做資料蒐集、Skeptic 做挑戰，最後再碰撞 -- 報告的品質和可信度會好很多。這就像 code review：你不會自己 review 自己的 PR。

技術實作：每位 agent 就是一個 markdown 檔（~/.claude/agents/*.md），定義了該 agent 的角色、視角、工具權限。Claude Code 的 subagent / Agent Teams 機制會載入對應定義，在獨立 context 中執行任務。

Skill -- 想像成 SOP 手冊

Skill 是結構化的工作流程定義，存在 ~/.claude/skills/<name>/SKILL.md。

目前有 10 個 skill，其中 3 個是核心業務 skill：

為什麼不直接寫在 prompt 裡？ 因為一個完整的品牌調研流程涉及：需求釐清 -> 多 agent 並行研究 -> 來源品質閘門 -> 驗證 -> 洞察整合 -> 交叉辯論 -> 報告產出 -> 自檢。如果每次都手寫 prompt 來指揮這一切，你會瘋掉。Skill 把流程「程序化」了，就像 CI/CD pipeline 把部署程序化一樣。

核心 Skill 的共同機制：

• CRF（Compact Relay Format）：agent 完整分析寫入檔案，只把摘要（<=300 tokens）回傳主 context。省 token、保完整度。
• 來源品質閘門（Source Quality Gate）：每項數據標注來源等級（A-E），超過 50% 為 D/E 就暫停流程。
• 認識論分層（L1-L5）：所有事實必須標注信心度，從 L1（已驗證）到 L5（未知）。不確定就降級，絕不硬寫成確定句。
• Agent Teams 辯論：交叉審視用真實多輪辯論，不是模擬。最多 2 輪（研究顯示同模型辯論超 2 輪準確率不再提升）。

Hook -- 想像成自動化品管關卡

Hook 是在 Claude Code 生命週期事件上掛載的 shell script，自動執行、不需人工觸發。

目前有 3 個自建 hook：

為什麼不直接寫在 skill 裡？ 因為品管應該是 cross-cutting concern，不是每個 skill 各自實作一份。Hook 就像 git hooks 或 middleware -- 你寫一次，所有流程自動套用。

重要細節：quality-gate.sh 目前是 advisory 模式（永遠 exit 0），只提醒不阻擋。要啟用阻擋模式，改 exit code 為 2。這是刻意的設計決策 -- 先觀察誤報率，確認穩定後再考慮強制。

CLAUDE.md 階層 -- 想像成公司規章制度

Claude Code 有一套原生的指令階層機制，基於 CLAUDE.md 檔案的目錄位置：

Layer 1    ~/.claude/CLAUDE.md           -- 總部規章（user-level，永遠載入）
Layer 1.5  ~/CLAUDE.md                   -- 工作區規則（project layer，永遠載入）
Layer 1.8  ~/.claude/projects/CLAUDE.md  -- 部門規章（subtree rules，進入子樹時載入）
Layer 2    REGISTRY.md                   -- 調度手冊（首次調度時載入）
Layer 3    agents/*.md                   -- 個人職責說明書（按需載入）
Layer 4    skills/ + library/            -- 知識庫（JIT 檢索，從不預載）

為什麼分這麼多層？ 兩個字：省 token。如果把 39 個 agent 定義全部預載，大約吃掉 15,000 tokens。但查 REGISTRY.md（約 1,000 tokens）再按需載入 1-5 個 agent（約 1,500 tokens），節省 85-90%。這就像 lazy loading -- 不要一開始就把所有 JS bundle 載完。

關鍵原則：

• 上層規則不能被下層覆蓋（除非明確設計）
• 每層盡可能精簡、單語（繁中或英文，不混寫）
• 只有在需求無法放進既有 canonical doc 時，才新增 path-scoped rules

Memory 分層 -- 想像成公司知識管理

這套系統有 7 層記錄機制，各有明確分工：

Layer 0    git                    -- 合約（檔案變更的唯一事實來源）
Layer 0.5  logs/                  -- 日誌（事件、audit、skill run 記錄）
Layer 0.8  DECISIONS.md           -- 決策紀錄（專案決策、取捨、規則）
Layer 0.9  memory/MEMORY.md       -- 里程碑摘要（高層脈絡，不重抄 diff）
Layer 1    CLAUDE.md hierarchy    -- 制度手冊（Claude Code 原生指令）
Layer 1.5  claude-mem MCP plugin  -- 自動觀察（補充型，非權威來源）
Layer 2    memory/*.md            -- 經驗傳承（長期原則、偏好、反模式）

為什麼不用一個大資料庫？ 因為不同類型的知識有不同的生命週期和信任等級。git diff 是事實，不可能錯；memory 裡的偏好是可能過時的經驗。把它們混在一起，你就分不清哪些是 ground truth，哪些是 heuristic。

已退役層：~/.claude/agent-memory/ 是早期實驗，嘗試讓 agent 跨 session 累積知識。結論是原生能力已足夠，不需要平行系統。目錄保留但不再使用。

架構全景圖

系統架構

 使用者                Claude Code CLI              ~/.claude/
   |                       |                          |
   | /brand-research       |                          |
   |---------------------> |                          |
   |                       |  1. 載入 CLAUDE.md 階層   |
   |                       |------------------------->|  CLAUDE.md (L1)
   |                       |                          |  ~/CLAUDE.md (L1.5)
   |                       |  2. 查 REGISTRY.md        |
   |                       |------------------------->|  agents/REGISTRY.md
   |                       |                          |
   |                       |  3. 載入 SKILL.md         |
   |                       |------------------------->|  skills/brand-research/SKILL.md
   |                       |                          |
   |                       |  4. 按 Skill 調度 Agents  |
   |                       |                          |
   |                       |  +-----------------------+|
   |                       |  | Stage 1: 並行研究     ||
   |                       |  | Deep Researcher       ||  -> stage1/deep-researcher.md
   |                       |  | Strategist            ||  -> stage1/strategist.md
   |                       |  | Context Analyst       ||  -> stage1/context-analyst.md
   |                       |  +-----------------------+|
   |                       |           |               |
   |                       |  5. Source Quality Gate   |
   | <来源品質報表摘要>     | <------------------------|
   | 確認繼續               |                          |
   |---------------------> |                          |
   |                       |  +-----------------------+|
   |                       |  | Stage 2-3: 驗證+洞察  ||  -> stage2/*.md, stage3/*.md
   |                       |  +-----------------------+|
   |                       |           |               |
   |                       |  6. Agent Teams 辯論     |
   |                       |  +-----------------------+|
   |                       |  | Cross-Review          ||  -> cross-review/*.md
   |                       |  | 正方 vs 反方 + Joker  ||
   |                       |  +-----------------------+|
   |                       |           |               |
   |                       |  7. 報告產出 + 自檢       |
   |                       |           |               |
   |                       |  8. Hooks 自動觸發        |
   |                       |     quality-gate.sh ----->|  (認識論/來源檢查)
   |                       |     debate-quality.sh --->|  logs/YYYY-MM.jsonl
   |                       |     runtime-event.sh ---->|  logs/YYYY-MM.jsonl
   |                       |           |               |
   | <最終報告>             | <------------------------|

指令階層與資料流

                    ┌──────────────────────┐
                    │  ~/.claude/CLAUDE.md  │  Layer 1: 永遠載入，最小常駐規則
                    └──────────┬───────────┘
                               |
                    ┌──────────v───────────┐
                    │    ~/CLAUDE.md        │  Layer 1.5: workspace project layer
                    └──────────┬───────────┘
                               |
           ┌───────────────────┼───────────────────┐
           |                   |                   |
  ┌────────v─────────┐ ┌──────v───────┐ ┌────────v─────────┐
  │ agents/           │ │ skills/      │ │ library/          │
  │ REGISTRY.md       │ │ SKILL.md     │ │ reference/        │
  │ 39 agent 定義     │ │ 10 個 skill  │ │ frameworks/       │
  │ 觸發詞 + effort  │ │ 調度流程     │ │ checklists/       │
  └────────┬─────────┘ └──────┬───────┘ │ templates/        │
           |                   |         │ sources/          │
           |                   |         └────────┬─────────┘
           └───────────────────┼───────────────────┘
                               |
                    ┌──────────v───────────┐
                    │  hooks/               │  PostToolUse / Lifecycle
                    │  quality-gate.sh      │  品質閘門
                    │  debate-quality.sh    │  辯論評分
                    │  runtime-event.sh     │  telemetry
                    └──────────┬───────────┘
                               |
                    ┌──────────v───────────┐
                    │  logs/YYYY-MM.jsonl   │  統一事件日誌
                    │  logs/eval-artifacts/ │  eval 產物
                    └──────────────────────┘

你需要知道的維護重點

1. 如何新增/修改 Agent

新增 agent：

1. 在 ~/.claude/agents/ 建立 agent-name.md，定義角色、視角、工具權限
2. 在 ~/.claude/agents/REGISTRY.md 的 Full Agent Table 中新增一行（觸發詞、effort、檔案名）
3. 決定放在哪個操作表面（Core / Conditional / Specialist）
4. 如果涉及 combo triggers，更新 Combo Triggers 表

修改 agent：

• 直接改對應的 agents/*.md 檔案
• 若改了觸發詞或 effort，同步更新 REGISTRY.md
• 若是合併或拆分 agent，記錄在 REGISTRY.md 的 Merge Log

注意：agent merge/deprecate 走數據驅動。不要憑感覺砍能力，先看 telemetry 和使用率（telemetry 在 logs/ 裡，由 runtime-event-log.sh 自動記錄）。

2. 如何建立新 Skill

步驟：

1. 建立 ~/.claude/skills/<skill-name>/SKILL.md
2. 寫 YAML frontmatter（name, description, default_mode, arguments）
3. 定義調度流程（哪些 agent、什麼順序、什麼模式）
4. 定義 routing matrix（哪些步驟用 main thread / subagent / agent teams）
5. 定義 output contract（報告必須包含哪些章節）
6. 定義 completion logging（完成後寫什麼到 logs/）

要點：

• Skill 只是 prompt 模板 + 流程定義，不含可執行程式碼
• 寫檔策略要明確：哪些 agent 有 Write 權限，哪些沒有
• 新 skill 不自動納入 eval framework；只有成為核心長流程 skill 時才考慮

參考：看 skills/brand-research/SKILL.md 和 skills/marketing/SKILL.md 作為範本。它們是系統中最完整的兩個 skill，涵蓋了所有慣例。

3. 如何調整 Hooks

Hook 掛載位置：~/.claude/settings.json（不在版控中） Hook 定義文件：~/.claude/hooks/*.sh Hook 登記簿：~/.claude/hooks/REGISTRY.md

新增 hook：

1. 寫 shell script 放到 ~/.claude/hooks/
2. 在 settings.json 中加入掛載設定（event, path, mode）
3. 更新 hooks/REGISTRY.md

重要設計約束：

• Hook 必須輕量。sync 模式有 10 秒 timeout -- 超時就算失敗
• 所有輸出寫入既有 logs/YYYY-MM.jsonl，不建立平行日誌系統
• Hook 從 stdin 接收 JSON payload，用 jq 解析
• runtime-event-log.sh 使用 cache 機制避免重複解析 transcript

目前 hook 列表：

4. 如何管理 Memory

最重要的原則：不要在 MEMORY.md 重抄 git diff。

反模式警告：

• 不要建立新的 memory / logging / routing 平行系統
• 不要讓 MEMORY.md 變成流水帳
• 不要在多個地方重複記錄同一件事
• claude-mem 注入的子目錄 CLAUDE.md 是 runtime artifact，不是設計的一部分

5. Eval Framework 怎麼用

系統有一套最小 eval 回路，定義在 ~/.claude/library/reference/checklists/skill-eval.md。

何時需要跑 eval：

• Skill prompt 結構重寫
• 大段內容外移到 template/checklist/framework
• Model routing 變更
• Agent dispatch 規則變更
• Output contract 或 source-quality gate 變更

不需要跑的情況：純 typo、路徑修正、標題調整。

Benchmark 題組（3 組必跑）：

評分維度（5 維度 x 0-2 分 = 總分 10）：

1. Structure completeness -- 關鍵章節是否齊全
2. Source discipline -- 來源等級和不確定性標示是否清楚
3. Readability -- 結構清楚、可掃讀
4. Actionability -- 建議可執行、與證據對應
5. Cost sanity -- token 成本合理

硬性失敗條件（出現任一即判定失敗，不看總分）：

• 關鍵數據缺少來源標示
• Output contract 強制段落缺失
• 把假設/未知寫成確定結論
• 為純格式化新增不必要的 subagent

結構級變更：同一 benchmark 至少跑 3 次，避免單次波動誤判。

工具：可搭配 skill-creator@anthropic plugin 執行自動化 eval，但 accept/reject 決策仍依 skill-eval.md 的規則，不直接看 plugin 的 pass_rate。

技術債與已知限制

誠實揭露

已做過但放棄的方向

以下是歷史上嘗試過、最終決定不走的路 -- 了解這些可以避免重蹈覆轍：

接手指南

如果你是新來的工程師，建議的學習路徑：

第一天：理解骨架

1. 讀本文件 -- 你正在做這件事
2. 讀 ~/.claude/CLAUDE.md -- 最小常駐規則，只有 29 行，但定義了整個系統的哲學
3. 讀 ~/CLAUDE.md -- workspace 層規則，了解日常操作慣例
4. 瀏覽 ~/.claude/agents/REGISTRY.md -- 重點看架構圖和 Human Operating Surface

第二天：理解核心流程

5. 讀 ~/.claude/skills/brand-research/SKILL.md -- 最完整的 skill 範本，理解調度流程、CRF、來源閘門、認識論分層
6. 讀 ~/.claude/docs/memory.md -- 理解 7 層記錄分工，知道什麼該寫在哪裡
7. 跑一次 /brand-research <品牌> quick -- 親自體驗最簡流程，看看 agent 怎麼被調度、報告長什麼樣

第三天：理解品管與演進

8. 讀 3 個 hook script -- 都在 ~/.claude/hooks/，理解自動品管機制
9. 讀 ~/.claude/library/reference/checklists/skill-eval.md -- 理解 eval framework
10. 讀 ~/.claude/docs/roadmap.md -- 理解目前的技術債和優先順序

持續參考

黃金規則（背起來）

1. 原生優先 -- 能用 Claude Code 原生能力解決的，不自建平行系統
2. git 是事實來源 -- 不在 memory 重抄 diff
3. 單一主控 -- 一個任務只能有一個 primary executor
4. 減法先於加法 -- 不為了完整感加新 protocol 或治理文字
5. 數據驅動 -- agent 合併/廢棄看 telemetry，不憑感覺

檔案索引

本文件提及的關鍵檔案路徑：

本文件由 Storyteller 撰寫。如有過時之處，以各 canonical doc 為準。