Claude Code 設定沒生效怎麼查：先分清楚它是沒收到，還是收到了不照做

寫於 2026 年 8 月 25 日，9 月才上線（部落格的發佈額度在 8 月中用完了，稿子積壓了三週）。文中的版本號與「目前」都指 8 月 25 日的狀態，Claude Code 更新很快，你讀到時可能已經又改過了。

CLAUDE.md 的第一行寫得很清楚：所有回覆用繁體中文。

它回你英文。

你把那行改成粗體，重送一次。還是英文。你在句尾補上「這是硬性規定，不可違反」，它跟你道歉，道歉完下一段繼續用英文。

到這裡通常會做兩件事。第一件是把規則寫得更兇：加驚嘆號、改成全大寫的 MUST、把同一句話在檔案裡重複三次。第二件是關掉整個 session 重開，想說它可能是累了。

兩件都沒用。沒用的原因是同一個：你在調整一份可能從來沒被讀到的檔案。

家裡的燈不亮，你換了三顆燈泡。第四顆換上去之前，先確認一件事會比較快：電到底有沒有到那個燈座。燈泡是好是壞，是電到了之後才需要問的問題。順序反了，你可以換一整晚。

第一個指令永遠是 /context

Claude Code 有個指令專門回答「電有沒有到」：/context。

照官方文件的說法，它會列出目前這個 session 的 context window 裡裝了什麼，按類別拆開：system prompt、內建工具、MCP 工具、自訂 subagent（連同各自從哪裡載入的）、記憶檔案、skills，還有對話本身。

用途只有一個，但這個用途決定後面所有動作：確認你那份 CLAUDE.md、那條規則、那個 skill 的描述，到底在不在裡面。

在，跟不在，是兩條完全不同的路。

大部分人卡住是因為跳過這一步直接開始猜。猜的成本很高，因為兩條路的修法沒有任何交集，你在其中一條路上做的每件事，對另一條路的問題都是零效果。

岔路一：它根本沒收到

/context 裡找不到你的檔案，問題在位置或格式，不在內容。這時候把規則寫得再用力都不會有變化。

子目錄的 CLAUDE.md 不是開場就載入的。 它按需載入：當 Claude 用 Read 工具讀了那個目錄底下的檔案，那份 CLAUDE.md 才會進來。不是啟動時載，也不是它在那個目錄裡寫檔案的時候載。所以你在 backend/CLAUDE.md 寫的規範，在對話剛開始時它是真的看不到。

Skill 放成單一檔案不會被認。 要是資料夾，裡面放 SKILL.md，也就是 .claude/skills/name/SKILL.md。寫成 .claude/skills/name.md 就不會出現在 /skills 清單裡。

hooks 沒有獨立檔案這種東西。 專案跟使用者層級的 hook 一律寫在 settings.json 的 "hooks" 鍵底下。只有 plugin 才會去讀自己那份 hooks/hooks.json。

~/.claude.json 跟 ~/.claude/settings.json 是兩個不同的檔案。 前者放 app 狀態跟 UI 開關。你把 permissions、hooks、env 寫進去，它們不會生效，也不會報錯。

對應的檢查指令跟 /context 是同一套邏輯，只是看得更細：/memory 看記憶檔案的位置、/skills 看有哪些 skill 被認出來、/hooks 看目前註冊了哪些 hook、/mcp 看 server 的連線狀態、/permissions 看實際生效的允許與拒絕規則。

有一類特別安靜的失敗值得單獨拿出來講：hook 的 matcher 寫錯。

matcher 是單一字串，要比對多個工具名得用 | 串起來，像 "Edit|Write"。文件寫得很細：v2.1.191 之後逗號也等價，但在那之前，逗號會掉進 regex 判斷，"Edit,Write" 什麼都比不到。工具名還分大小寫，寫成 "bash" 比不到 Bash。這三種寫法的共同點是不會噴錯，hook 就是安靜地不觸發。

最狠的是把 matcher 寫成陣列。那是 schema 錯誤，整份 settings 檔會被拒收，那個檔案裡的所有 hook 一起消失。claude doctor 會報出這個驗證失敗，但你得先想到去跑它。

MCP 那邊也有幾個同款的安靜失敗。專案層的 server 定義在 repo 根目錄的 .mcp.json，不是放在 .claude/ 裡面，而且 server 要掛在 mcpServers 這個鍵底下，寫成 VS Code 那種 servers 不會被讀到。settings.json 則是根本不吃 mcpServers 這個鍵。另外專案層的 server 需要一次性核准，核准提示被你順手關掉的話，它會一直停在停用狀態，得從 /mcp 裡面補核准。至於 command 或 args 用相對路徑的，路徑是相對於你啟動 Claude Code 的目錄去解，不是相對於 .mcp.json 的位置，換個目錄啟動就掛掉。

還有一個很多人踩到但很少人聯想到設定的：內建的 Explore 跟 Plan agent 會跳過 CLAUDE.md。你派工給它們，專案規範不會自動跟過去，得在派工的 prompt 裡自己重講一次。自訂的 subagent 倒是跟主對話一樣會載入。

岔路二：收到了，但被另一份設定蓋掉

/context 裡看得到，行為還是不對，那就換個方向查：是不是有另一層設定把你的值蓋掉了。

設定分四層：managed、user、project、local。有 managed 的時候它最先套用。剩下三層的規則是近的蓋遠的，順序是 local 蓋 project、project 蓋 user。除此之外，命令列參數跟環境變數是另一層覆蓋。

實務上最常見的一種長這樣：你改了 settings.json，但同一個鍵在 settings.local.json 裡也有一份。local 那份贏。你可以在 settings.json 裡改一整天。

要看目前有哪些設定來源生效，用 /status，它也會告訴你 managed settings 是不是在作用中。要找語法壞掉的設定檔，用 /doctor。想在不開 session 的情況下看安裝與設定的診斷，終端機直接下 claude doctor，它是唯讀的。

順帶一提，改完 settings.json 不用重開。文件說會經過一小段檔案穩定性的延遲之後就套用到當前 session（延遲多久，文件沒寫具體秒數）。要是 /hooks 過幾秒還顯示舊的定義，再跑一次 /hooks 刷新畫面就好。

當你連自己的設定都不信任了

上面兩條路都查不出來，還有一招是把變因全部拿掉。

claude --safe-mode 會開一個關掉所有自訂內容的 session：CLAUDE.md、skills、plugins、hooks、MCP servers、自訂指令與 agent 全部不載入。登入、模型選擇、內建工具跟權限照常運作。問題在 safe mode 消失，代表兇手就在那幾個被關掉的東西裡，回頭用前面那些指令一個一個找。

safe mode 不是完全乾淨這點要先知道：組織部署的 managed hooks 跟 settings policy 還是會套用。

如果連 safe mode 都還在壞，或者你懷疑的正是設定檔本身，那就再退一步，開一個什麼都不讀的環境：

1	cd /tmp && CLAUDE_CONFIG_DIR=/tmp/claude-clean claude

CLAUDE_CONFIG_DIR 指到一個空目錄，~/.claude 底下的東西整包被繞過；從 /tmp 啟動則是為了避開專案層的 .claude、.mcp.json 跟 CLAUDE.md。第一次跑會看到初次設定的畫面，從選主題開始。看到那些畫面反而是好消息，代表乾淨設定目錄真的生效了。

這裡有個平台差異：macOS 的憑證存在 Keychain，會沿用過去；Linux 跟 Windows 的憑證存在設定目錄底下，所以要重新登入一次。

問題在這個乾淨 session 裡消失，就把你的檔案一份一份搬回去，找出是哪一份。要是連這樣都還在壞，兇手在你的使用者與專案設定之外，接下來該查的是 managed settings 跟環境變數。