Skip to main content
這個單元解決什麼問題在學任何一家工具的設定細節之前，先建立一個通用座標系。掌握「作用範圍」與「設定種類」這兩個軸，之後看到任何工具的設定檔，你都能立刻判斷它屬於哪一格、會不會被別的設定覆寫、該不該提交到版控。

​
學習目標

  • 能用「作用範圍」軸（受管理 → 使用者 → 專案 → 本地）描述任一設定的生效範圍。
  • 能用「設定種類」軸（個人化 / 記憶 / 規則 / 隱私 / 權限 / 自動化）分類任一設定項。
  • 能說明覆寫優先序，並分辨「覆寫」「串接」「合併」三種不同的層級語意。
  • 能正確區分「該提交到版控（團隊共享）」與「該 gitignore（個人）」的設定檔。

​
1. 第一軸：作用範圍（scope）

同一個設定可以出現在不同範圍，誰生效取決於優先序。以 Claude Code 為主範本，由高到低五層（截至 2026-05 官方文件 [1]）：
通用心法「越靠近當前任務的設定，優先序越高」。受管理政策是唯一從上而下、不可違逆的例外，那是給 IT 管控用的。其餘四層都遵守「近者為大」。

​
三種層級語意：覆寫 vs 串接 vs 合併

這是多數人對「層級」最大的誤解：不是所有設定都用「高層覆寫低層」。Claude Code 裡至少有三種不同的合併行為，混用這兩種心智模型會讓你在 debug 時耗費大量時間（[1][2]）： 換句話說：你的 ~/.claude/CLAUDE.md 與專案 ./CLAUDE.md 不會互相覆寫，兩份都會被讀進去（使用者層在前、專案層在後）。但 ~/.claude/settings.json 與 .claude/settings.json 裡同一個鍵，高層的會贏。把這兩件事當成同一回事，是「我明明在使用者層設了，怎麼專案裡行為不一樣」這類困惑的根源。

​
2. 第二軸：設定種類

範圍決定「在哪生效」，種類決定「管什麼」。六類：
  • 個人化：角色、語言、語氣、輸出格式。
  • 記憶：跨 session 持久化的事實與偏好（01-4 談過短期 vs 長期）。
  • 規則 / 指令：專案慣例、約束（CLAUDE.md、AGENTS.md、.claude/rules/）。
  • 隱私：訓練退出、保留期限、暫時對話。
  • 權限：工具可否執行、可讀寫哪些路徑（allow / ask / deny）。
  • 自動化：Skill、Hook、工作流。
兩軸一交叉，任何一個設定項都能被你定位到「哪一格」：一條規則是「規則種類 × 某個範圍」，一個權限是「權限種類 × 某個範圍」。

​
3. 兩軸交叉：決策工具

把「種類 × 範圍」當成一張矩陣，每次要放一個設定，先選這兩個軸，答案就決定了它該進哪個檔、要不要提交版控。
三個設定，三個位置
  1. 團隊共用的程式碼風格規約：規則種類 × 專案範圍 → 寫進 ./CLAUDE.md，提交版控，全隊共享。
  2. 你個人的測試沙箱 URL 與偏好測試資料：個人化 / 規則種類 × 本地範圍 → 寫進 ./CLAUDE.local.md，加進 .gitignore，只有你看得到、不污染團隊。
  3. 你跨所有專案的語言偏好（一律用台灣繁中回覆）：個人化種類 × 使用者範圍 → 寫進 ~/.claude/CLAUDE.md，套用到你機器上每個專案。
三個都是「規則 / 個人化」種類，差別只在範圍，而範圍直接決定了「提交還是 gitignore、誰看得到」。這就是兩軸座標系的用法：先定種類，再定範圍，檔案位置與版控策略就自動掉出來了。
同一個鍵設在多層時，先想清楚是覆寫還是串接若你在 ~/.claude/settings.json 設了 model，又在 .claude/settings.json 設了不同的 model，專案層贏（覆寫，近者為大）。但若你在 ~/.claude/CLAUDE.md 與 ./CLAUDE.md 各寫了風格規則，兩份都生效（串接），衝突時 Claude 可能任選一條，所以別讓兩層的規則互相矛盾。

​
4. 提交 vs gitignore（關鍵實務）

範圍軸最直接的版控後果，就是這條二分：
  • 提交（版控、團隊共享）：團隊應一致遵守的規則與設定。./CLAUDE.md、.claude/settings.json、.claude/rules/、AGENTS.md。
  • gitignore（個人、不分享）：個人覆寫、密鑰、本地路徑。./CLAUDE.local.md、.claude/settings.local.json、任何含 token 的檔。
這跟 .env / .env.example 是同一套思維：可分享的模板進版控，含密鑰的實體留本地。判準很簡單：這個設定換一個隊友套用，是幫到他還是洩漏你？ 幫到他就提交，洩漏你就 gitignore。
密鑰永遠不進會被提交的檔最常見也最貴的錯誤：把 API key、token 寫進 .claude/settings.json（會提交）而非 settings.local.json（gitignore）。一旦推上遠端，等於公開。密鑰、本地絕對路徑、個人沙箱位址，一律走 local 層。

​
5. 把任何新工具對位到此模型

這個座標系的價值，在於它跨工具通用。拿到一個陌生工具，依序問五個問題，你就摸清了它的設定面，不用讀完整份文件：
1

使用者級設定在哪？

套用所有專案的個人偏好放哪個檔或目錄？
2

專案級規則檔是哪個？

哪個檔案進版控、對全隊生效？
3

有沒有本地覆寫層？

有沒有已 gitignore 的個人設定入口？
4

隱私 / 訓練退出開關在哪？

如何退出資料訓練或設定資料保留期？
5

權限怎麼控制？

能不能限制它讀寫、執行的範圍？deny / ask / allow 在哪設？
五題答得出來，你就能安全地開始用它，而不是踩到「設了沒用」或「不小心提交了密鑰」才回頭補課。

​
工具對照

各家的設定層級對應（截至 2026-05，精確檔名與機制以官方文件為準，逐項細節見 02-2 與 02-6）：
對照表給座標，不給細則這張表讓你知道「同一層在你的工具叫什麼」。各 cell 的精確語意（誰覆寫誰、哪些進版控）屬快變動事實，統一在 02-2（Claude）與 02-6（其餘）查證並標日期。值得記住的是：幾乎每家都有「使用者 / 專案 / 本地」這條範圍軸，差別只在檔名與本地層完整度。

​
常見誤區

反模式清單
  • 以為所有層都是「高層覆寫低層」：settings.json 是覆寫，但 CLAUDE.md 是串接、permissions 是合併。用錯心智模型會有 debug 成本（第 1 節）。
  • 把個人偏好寫進團隊共享的專案規則檔：你的語言偏好、沙箱 URL 進了 ./CLAUDE.md，全隊都被你的偏好污染。那是 CLAUDE.local.md 或使用者層的事。
  • 把密鑰寫進會被提交的設定檔：settings.json 會進版控，密鑰要走 settings.local.json（第 4 節）。
  • 不知道某設定被更高優先序的層覆寫：「我明明設了怎麼沒用」十之八九是被近一層的設定蓋掉，或被受管理政策鎖死。先確認生效的是哪一層。

​
自我檢核

通過本單元的標準
  1. 你能說出你主力工具的「使用者級」與「專案級」設定各放哪、哪些已進版控嗎？
  2. 給你一個 API key、一條團隊風格規則、一個個人語言偏好，你能各自說出「放哪一格、提交還是 gitignore」嗎？
  3. 你能解釋為什麼 ~/.claude/CLAUDE.md 與 ./CLAUDE.md 不會互相覆寫，但兩份 settings.json 的同一個鍵會嗎？

​
來源與延伸閱讀

事實主張依官方文件，快變動項標註截至 2026-05。
  • [1] Anthropic, “Claude Code settings”（設定優先序：managed → CLI → local → project → user；檔案位置；permissions 為跨層合併），Claude Code Docs. https://code.claude.com/docs/en/settings （截至 2026-05）
  • [2] Anthropic, “How Claude remembers your project”（CLAUDE.md 階層與串接載入、CLAUDE.local.md、@path 匯入語法、.claude/rules/、Claude Code 讀 CLAUDE.md 而非 AGENTS.md），Claude Code Docs. https://code.claude.com/docs/en/memory （截至 2026-05）
  • 銜接：02-2 Claude 設定逐項、02-6 其他工具設定對照、04-1 CLAUDE.md 與記憶檔、04-2 rules 規則檔。