解剖 .claude 資料夾：它的作用以及讓人困惑的原因

如果你搜尋過「.claude 資料夾的結構」，大概率是想搞清楚這個資料夾到底在做什麼、為什麼讓人困惑、哪些部分值得關注。這幾個問題問得很有道理。這個資料夾看起來很簡單，直到你意識到它不僅僅是存放設定檔。

2026年3月的一則 Reddit 貼文把這件事講得很清楚。一位開發者因為放置位置不明確吃過虧，於是整理了一份速查表，涵蓋了 .claude/ 目錄結構、鉤子事件、settings.json、MCP 設定、技能結構和上下文管理閾值。貼文引起共鳴，是因為這個資料夾不只是儲存設定——它在你執行命令、呼叫技能、管理代理時，主動影響發生的事情。

核心困惑：全域 vs 專案層級

最大的困惑來源是全域目錄 ~/.claude 和專案層級目錄 .claude/ 之間的區別。

全域目錄在你的主資料夾裡，定義了所有專案共享的行為。包括個人設定、全域 MCP 伺服器設定，以及你希望隨處可用的技能。把它理解為你的個人預設值。

專案層級 .claude/ 目錄在具體儲存庫內部。它覆蓋或擴展該特定專案的全域設定。專案專屬的技能、代理定義、鉤子和 MCP 設定放在這裡。

當你混淆這兩個層級——把專案特定的行為放在全域目錄裡，或者期望全域設定在專案覆蓋它們時仍然生效——資料夾就變得神秘了。它並不神秘。它只是有作用域，而作用域決定了優先順序。

一個實用規則：如果一個行為應該在所有地方生效，放在 ~/.claude。如果它屬於某個專案，放在專案的 .claude/ 裡。不確定的時候，先放在專案層級，確認在多個程式碼庫中都能運作後再提升到全域。

放置慣例：東西到底該放哪裡

資料夾結構不是隨意的。特定類型的內容屬於特定位置，搞錯這個是最常見的錯誤之一。

技能放在 .claude/skills/ 下。每個技能有自己的目錄，包含 SKILL.md 檔案。SKILL.md 是進入點——定義技能做什麼、如何呼叫、需要什麼。

代理放在 .claude/agents/，而不是散落在頂層資料夾的鬆散檔案。代理用特定的設定檔定義，系統需要一致地找到它們。

設定在專案層級的 .claude/settings.json 或全域的 ~/.claude/settings.json。

鉤子是操作性的，不是被動的

很多開發者把鉤子當作可選裝飾。它們不是。鉤子是在工具生命週期的特定時刻執行的操作元件。

最常見的錯誤是匹配範圍過窄。如果你設定的 PostToolUse 鉤子只匹配「Write」，你會錯過透過「Edit」或「MultiEdit」操作進行的修改。更寬泛的匹配模式「Edit|MultiEdit|Write」能捕捉更多情況。

真正需要關注的四件事

1. 作用域。 全域 vs 專案層級是第一個決定。搞錯了這個，其他一切都不會按預期運作。

2. 放置慣例。 技能需要自己的目錄和 SKILL.md。代理放在 agents/。設定有定義好的結構。

3. 內容 vs 編排。 技能、代理、設定、鉤子和 MCP 設定不是等價的概念。不要混淆。

4. 漂移的跡象。 文件變化很快，如果設定突然不工作了，檢查底層約定是不是變了。

如何看待這個資料夾

.claude 資料夾將作用域、結構和行為組合在一棵目錄樹中。從作用域開始，然後學習放置約定，最後理解行為。一旦你內化了這個三層模型，資料夾就不再是隱藏的雜物堆，而是一張操作地圖。