Claude Code/五層架構

多數人把 CLAUDE.md 當成「我這次 session 想叫 Claude 注意的事」。錯了——它是 agent 的 constitution，是永遠載入、永遠 active 的最底層 context。

正確內容：架構決策、命名慣例、測試期待、repo 結構地圖、避雷清單。寫一次，之後每次 session 自動套用——不再有「我又得提醒它」的循環。

兩個 scope 配合使用：~/.claude/CLAUDE.md 是個人或公司全域守則（語氣、語言、安全紅線），.claude/CLAUDE.md 是 repo 內專案守則（架構、慣例、術語）。專案那層放進 git，整隊共享同一份憲法。

Skills 是「按需載入的領域知識包」。每份 SKILL.md 開頭有一行 description，描述「這份 skill 解決什麼問題、什麼情境該觸發」。

Runtime 時 Claude 會比對當前任務 vs. 所有 skill 的 description，匹配上才會 fork 一個隔離的 subagent 載入該 skill，不匹配的根本不進主 context。

結果：主 context 永遠瘦，但你可以擁有上百個高度專精的 skill 待命——做圖時用 frontend-design skill、寫文檔時用 doc-coauthoring skill、debug 時用 systematic-debugging skill。模組化由設計決定，不靠人記得。

Hooks 是最被低估的一層。它不是 AI——是 deterministic 的 event-driven shell command。每次特定事件發生（PreToolUse、PostToolUse、SessionStart、Stop、SubagentStop），harness 會跑一次比對，符合 matcher 的 hook 就執行。

典型用途：每次 Write 自動 lint、硬擋 rm -rf、Stop 後丟一條 Slack 通知。這些品質約束跟 LLM 說了沒用——它記得就會做、不記得就不做。Hooks 把它下沉到基礎建設：不靠模型自律，靠 harness 強制。

跳過這層的代價：production 出意外的時候，你會發現「明明 prompt 裡寫了不要 X」根本擋不住——因為 prompt 是 soft constraint，hook 才是 hard。

Subagents 解決的是「大任務拆小、平行跑、別污染主 context」。每次 spawn 一個 subagent，它得到自己的 context window、自己的 model（可以選不同等級）、自己的 tool set、自己的權限白名單。

架構規則只有兩條：主 agent 委派下去、subagent 回報上來。subagent 不能再 spawn subagent——硬擋無限遞迴，避免 fork bomb 式失控。

實務上這讓你能做：探索性 search 開一個、跑測試開一個、寫 PR description 開一個，三個平行跑，結果在主 agent 收斂。主 context 不會被中間搜尋雜訊塞滿，token 預算守得住。

前四層解決的是「個別工程師的 agent 變強」，Plugins 解決的是「整個團隊的 agent 同步變強」。

把你寫好的一組 skills + 自定 subagents + 一批 hooks + slash commands 捆成一個 plugin，再透過 marketplace 或私有 registry 散布。隊員 install 一次，所有規則、Skill、護欄、命令全部自動就位。

類比：npm package 散布函式，plugin 散布行為。新人進團隊不用再口傳 30 條規矩——`/install our-team-plugin` 一行，他的 agent 立刻變得跟資深成員一樣有紀律。