同)
1. 三套配置體系到底在管什么很多人第一次接觸 Claude Code看到項(xiàng)目根目錄下同時(shí)存在settings.json、CLAUDE.md和 memory 相關(guān)文件第一反應(yīng)是懵的——這三個(gè)東西看起來(lái)都在“配置”到底誰(shuí)管誰(shuí)我剛開(kāi)始用的時(shí)候也踩過(guò)這個(gè)坑把一堆本該寫(xiě)在settings.json里的東西塞進(jìn)了CLAUDE.md結(jié)果權(quán)限規(guī)則死活不生效排查了半天才發(fā)現(xiàn)是放錯(cuò)了地方。先把結(jié)論擺在前面這三套體系分別對(duì)應(yīng)三個(gè)完全不同的層面。settings.json管的是“工具怎么跑”——權(quán)限、環(huán)境變量、模型選擇、鉤子hooks、MCP 服務(wù)器注冊(cè)。它是機(jī)器讀的格式嚴(yán)格寫(xiě)錯(cuò)一個(gè)逗號(hào)整個(gè)文件就廢了。CLAUDE.md管的是“項(xiàng)目是什么”——技術(shù)棧、目錄結(jié)構(gòu)、構(gòu)建命令、代碼規(guī)范、協(xié)作約定。它是給模型讀的自然語(yǔ)言上下文每次會(huì)話啟動(dòng)時(shí)會(huì)被加載進(jìn)上下文窗口。memory管的是“跨會(huì)話記住什么”——你在對(duì)話中讓 Claude 記住的偏好、決策、臨時(shí)約定它會(huì)持久化到本地文件下次開(kāi)新會(huì)話還能用。打個(gè)比方settings.json像是你給新員工配的工牌和門(mén)禁權(quán)限CLAUDE.md是放在工位上的項(xiàng)目手冊(cè)memory 則是這個(gè)員工自己的筆記本記著“老板喜歡用 pnpm 不用 npm”這類口頭約定。理解了這個(gè)分層后面所有的配置問(wèn)題基本都能對(duì)號(hào)入座。我見(jiàn)過(guò)太多人把權(quán)限規(guī)則寫(xiě)進(jìn)CLAUDE.md然后抱怨“為什么 Claude 還是每次都問(wèn)我”根源就是沒(méi)搞清楚這三者的邊界。1.1 為什么要有三套而不是一套這個(gè)問(wèn)題我被問(wèn)過(guò)不止一次。直覺(jué)上把所有配置塞進(jìn)一個(gè)文件不是更簡(jiǎn)單嗎實(shí)際上不行原因有三個(gè)。第一是加載時(shí)機(jī)不同。settings.json在進(jìn)程啟動(dòng)時(shí)就要解析決定了這次會(huì)話能用哪些工具、走哪個(gè)模型。CLAUDE.md是在會(huì)話初始化階段作為上下文注入的它影響的是模型的“認(rèn)知”而不是“能力”。memory 則是在會(huì)話過(guò)程中動(dòng)態(tài)讀寫(xiě)的隨時(shí)可能變化。三者生命周期完全不一樣硬合并會(huì)導(dǎo)致要么啟動(dòng)變慢要么上下文浪費(fèi)。第二是格式約束不同。settings.json必須是合法 JSON機(jī)器要嚴(yán)格解析CLAUDE.md是 Markdown本質(zhì)是給模型看的自然語(yǔ)言格式寬松得多memory 通常是結(jié)構(gòu)化的鍵值對(duì)或者追加式日志。把自然語(yǔ)言和嚴(yán)格 JSON 混在一個(gè)文件里解析器會(huì)瘋掉。第三是共享范圍不同。settings.json里有一部分是項(xiàng)目級(jí)提交到倉(cāng)庫(kù)團(tuán)隊(duì)共享有一部分是用戶級(jí)放在家目錄只對(duì)自己生效。CLAUDE.md通常是項(xiàng)目級(jí)共享的。memory 則基本是個(gè)人本地的。混在一起就沒(méi)法做這種粒度控制。提示如果你在團(tuán)隊(duì)里推廣 Claude Code建議把settings.json的項(xiàng)目級(jí)部分和CLAUDE.md一起提交到倉(cāng)庫(kù)用戶級(jí)配置和 memory 加進(jìn).gitignore。這樣新人 clone 下來(lái)就能直接用又不會(huì)把自己的個(gè)人偏好污染給全組。1.2 三者的優(yōu)先級(jí)與覆蓋關(guān)系實(shí)際使用中經(jīng)常出現(xiàn)“同一個(gè)設(shè)置在兩處都寫(xiě)了”的情況這時(shí)候誰(shuí)生效根據(jù)我的實(shí)測(cè)優(yōu)先級(jí)從高到低大致是命令行參數(shù)臨時(shí)覆蓋最高優(yōu)先級(jí)項(xiàng)目級(jí)settings.json.claude/settings.json用戶級(jí)settings.json~/.claude/settings.jsonCLAUDE.md中的約定僅作為上下文提示不強(qiáng)制memory 中的記錄最弱模型可能忽略這里有個(gè)關(guān)鍵點(diǎn)容易被誤解CLAUDE.md和 memory 里的內(nèi)容不是強(qiáng)制規(guī)則它們只是上下文。模型“傾向于”遵守但在復(fù)雜任務(wù)中可能被忽略。而settings.json里的權(quán)限規(guī)則是硬約束工具層面直接攔截。所以如果你有“絕對(duì)不能讓 Claude 執(zhí)行某類命令”的需求必須寫(xiě)在settings.json的權(quán)限配置里寫(xiě)進(jìn)CLAUDE.md是靠不住的。我踩過(guò)一次坑在CLAUDE.md里寫(xiě)了“不要執(zhí)行 rm -rf”結(jié)果某次重構(gòu)時(shí) Claude 還是建議了一條刪除命令。后來(lái)老老實(shí)實(shí)在settings.json里加了 deny 規(guī)則才徹底堵住。2. settings.json 深度拆解與實(shí)操配置settings.json是整個(gè)配置體系里最“硬”的部分也是最容易出錯(cuò)的。它的位置有兩個(gè)項(xiàng)目級(jí)的在項(xiàng)目根/.claude/settings.json用戶級(jí)的在~/.claude/settings.json。項(xiàng)目級(jí)會(huì)覆蓋用戶級(jí)的同名配置。2.1 文件結(jié)構(gòu)與核心字段一個(gè)完整的settings.json大致長(zhǎng)這樣{ permissions: { allow: [ Bash(npm run test:*), Bash(git status), Read(//src/**) ], deny: [ Bash(rm -rf:*), Bash(curl:*), Read(./.env) ], ask: [ Bash(git push:*), Write(//src/**) ] }, env: { NODE_ENV: development, PROJECT_ROOT: /Users/me/projects/demo }, model: claude-sonnet-4-5, hooks: { PostToolUse: [ { matcher: Write, hooks: [ { type: command, command: npx prettier --write $CLAUDE_FILE_PATH } ] } ] } }逐個(gè)字段說(shuō)。permissions是最核心的部分分allow、deny、ask三個(gè)數(shù)組。allow里的規(guī)則直接放行不詢問(wèn)deny里的直接拒絕ask里的每次都要用戶確認(rèn)。規(guī)則格式是工具名(參數(shù)模式)比如Bash(npm run test:*)表示允許所有以npm run test開(kāi)頭的命令。這里有個(gè)細(xì)節(jié)Bash規(guī)則的匹配是基于命令前綴的Bash(git status)只匹配完全等于git status的命令而B(niǎo)ash(git status:*)匹配git status后面跟任何參數(shù)。冒號(hào)加星號(hào)是通配符語(yǔ)法別漏了。env是注入到工具執(zhí)行環(huán)境里的變量。注意它不會(huì)自動(dòng)注入到 Claude 的上下文里只是影響 Bash 等工具執(zhí)行時(shí)的環(huán)境。如果你想讓 Claude 知道某個(gè)變量得寫(xiě)在CLAUDE.md里。model指定默認(rèn)模型。這個(gè)字段在不同版本里名字可能有變化有的版本用model有的用defaultModel。建議配置前先跑一次claude config list看看當(dāng)前支持的字段名。hooks是鉤子系統(tǒng)允許在工具調(diào)用前后執(zhí)行自定義命令。上面例子里的PostToolUse表示在 Write 工具執(zhí)行后跑 prettier 格式化。這個(gè)功能非常強(qiáng)大后面單獨(dú)講。2.2 權(quán)限規(guī)則的寫(xiě)法與常見(jiàn)陷阱權(quán)限規(guī)則寫(xiě)錯(cuò)是新手最高頻的問(wèn)題。我整理了幾種典型場(chǎng)景的正確寫(xiě)法。需求錯(cuò)誤寫(xiě)法正確寫(xiě)法允許所有 git 命令Bash(git)Bash(git:*)允許讀取 src 下所有文件Read(src/*)Read(//src/**)拒絕讀取 .envRead(.env)Read(./.env)允許 npm 腳本Bash(npm run:*)Bash(npm run:*)但注意空格允許特定目錄寫(xiě)入Write(src)Write(//src/**)幾個(gè)關(guān)鍵點(diǎn)路徑規(guī)則里//開(kāi)頭表示相對(duì)于項(xiàng)目根目錄./表示相對(duì)于當(dāng)前工作目錄~/表示家目錄。**匹配任意層級(jí)*只匹配單層。這個(gè)和 gitignore 的語(yǔ)法類似但不完全一樣別想當(dāng)然。Bash規(guī)則的匹配是前綴匹配不是正則。Bash(npm run test:*)會(huì)匹配npm run test、npm run test:unit、npm run test -- --watch但不會(huì)匹配npm run testx。冒號(hào)后面的*是必須的不寫(xiě)的話只匹配完全相等的命令。注意deny規(guī)則的優(yōu)先級(jí)高于allow。如果一條命令同時(shí)匹配 allow 和 deny會(huì)被拒絕。這個(gè)設(shè)計(jì)是為了安全但也意味著你寫(xiě) allow 的時(shí)候要小心別和已有的 deny 沖突。2.3 hooks 鉤子系統(tǒng)的實(shí)戰(zhàn)用法hooks 是我認(rèn)為settings.json里最被低估的功能。它讓你能在 Claude 執(zhí)行工具的前后插入自己的邏輯實(shí)現(xiàn)自動(dòng)化。支持的鉤子事件主要有PreToolUse工具執(zhí)行前觸發(fā)可以用來(lái)做校驗(yàn)、攔截PostToolUse工具執(zhí)行后觸發(fā)適合做格式化、lint、通知UserPromptSubmit用戶提交 prompt 時(shí)觸發(fā)Stop會(huì)話結(jié)束時(shí)觸發(fā)一個(gè)實(shí)用的例子每次 Claude 寫(xiě)完文件自動(dòng)跑 eslint 修復(fù)。{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx eslint --fix $CLAUDE_FILE_PATH 2/dev/null || true } ] } ] } }matcher支持正則Write|Edit表示匹配這兩個(gè)工具。$CLAUDE_FILE_PATH是環(huán)境變量指向被操作的文件路徑。末尾的|| true是為了防止 eslint 報(bào)錯(cuò)導(dǎo)致鉤子失敗阻塞流程。另一個(gè)場(chǎng)景在PreToolUse里攔截危險(xiǎn)命令。{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \$CLAUDE_TOOL_INPUT\ | grep -qE rm -rf / exit 1 || exit 0 } ] } ] } }這個(gè)鉤子檢查即將執(zhí)行的 Bash 命令里有沒(méi)有rm -rf /有就返回非零退出碼阻止執(zhí)行。雖然permissions.deny也能做類似的事但 hooks 能做更復(fù)雜的邏輯判斷。2.4 用戶級(jí)與項(xiàng)目級(jí)的分工策略我的建議是把配置分成兩類用戶級(jí)~/.claude/settings.json放個(gè)人偏好默認(rèn)模型、個(gè)人常用的 allow 規(guī)則比如允許所有g(shù)it只讀命令、個(gè)人 hooks比如通知腳本。項(xiàng)目級(jí).claude/settings.json放團(tuán)隊(duì)約定項(xiàng)目特定的構(gòu)建命令權(quán)限、項(xiàng)目 hooks格式化、lint、項(xiàng)目環(huán)境變量。這樣新人入職時(shí)clone 項(xiàng)目就自動(dòng)獲得團(tuán)隊(duì)約定同時(shí)保留自己的個(gè)人偏好。沖突時(shí)項(xiàng)目級(jí)覆蓋用戶級(jí)符合直覺(jué)。有個(gè)坑要注意項(xiàng)目級(jí)settings.json如果提交到倉(cāng)庫(kù)里面不要放任何敏感信息API key、內(nèi)部路徑。環(huán)境變量里的密鑰應(yīng)該通過(guò)系統(tǒng)環(huán)境變量注入而不是寫(xiě)死在配置文件里。3. CLAUDE.md 的寫(xiě)法與上下文管理如果說(shuō)settings.json是給機(jī)器看的CLAUDE.md就是給模型看的。它的質(zhì)量直接決定了 Claude 對(duì)你項(xiàng)目的理解程度進(jìn)而影響輸出質(zhì)量。我見(jiàn)過(guò)太多人把CLAUDE.md寫(xiě)成一句話“這是一個(gè) React 項(xiàng)目”然后抱怨 Claude 生成的代碼不符合規(guī)范。3.1 一份合格 CLAUDE.md 的必備要素根據(jù)我多個(gè)項(xiàng)目的實(shí)踐一份好用的CLAUDE.md應(yīng)該包含以下內(nèi)容項(xiàng)目概述一兩句話說(shuō)明項(xiàng)目是干什么的目標(biāo)用戶是誰(shuí)。這幫助模型建立整體認(rèn)知。技術(shù)棧語(yǔ)言、框架、主要依賴的版本。特別注意標(biāo)注版本因?yàn)椴煌姹镜?API 差異很大。目錄結(jié)構(gòu)關(guān)鍵目錄的用途說(shuō)明。不需要列出所有文件但要讓模型知道“組件放哪、工具函數(shù)放哪、測(cè)試放哪”。常用命令構(gòu)建、測(cè)試、lint、啟動(dòng)開(kāi)發(fā)服務(wù)器的命令。這是最高頻被用到的部分。代碼規(guī)范命名約定、文件組織約定、導(dǎo)入順序、注釋風(fēng)格。越具體越好。協(xié)作約定提交信息格式、分支命名、PR 流程。如果團(tuán)隊(duì)有約定的話。已知限制項(xiàng)目里有哪些坑、哪些地方不要?jiǎng)?、哪些依賴不能升?jí)。一個(gè)真實(shí)的例子# 項(xiàng)目概述 這是一個(gè)面向中小企業(yè)的庫(kù)存管理系統(tǒng)前端使用 React TypeScript。 # 技術(shù)棧 - React 18.2注意不用 19因?yàn)橐蕾嚨?UI 庫(kù)還沒(méi)適配 - TypeScript 5.3 - Vite 5.0 構(gòu)建 - Zustand 狀態(tài)管理不用 Redux - TanStack Query 數(shù)據(jù)請(qǐng)求 # 目錄結(jié)構(gòu) - src/components/ 通用組件每個(gè)組件一個(gè)目錄 - src/features/ 按業(yè)務(wù)模塊組織的功能代碼 - src/lib/ 工具函數(shù)和第三方封裝 - src/types/ 全局類型定義 # 常用命令 - pnpm dev 啟動(dòng)開(kāi)發(fā)服務(wù)器 - pnpm test 跑單元測(cè)試 - pnpm lint 代碼檢查 - pnpm build 生產(chǎn)構(gòu)建 # 代碼規(guī)范 - 組件用函數(shù)式 hooks不用 class - 文件名用 kebab-case組件名用 PascalCase - 導(dǎo)入順序react → 第三方 → 內(nèi)部絕對(duì)路徑 → 相對(duì)路徑 - 禁止使用 any用 unknown 加類型守衛(wèi) # 已知限制 - 不要升級(jí) react 到 19 - src/lib/legacy/ 下的代碼是歷史遺留不要重構(gòu) - 測(cè)試覆蓋率要求 80%新代碼必須帶測(cè)試這份CLAUDE.md大概 300 字但信息密度很高。Claude 讀完就知道該用什么、不該用什么、命令怎么跑。3.2 上下文窗口的取舍藝術(shù)CLAUDE.md不是越長(zhǎng)越好。它每次會(huì)話都會(huì)被加載進(jìn)上下文窗口占用 token。如果你的CLAUDE.md寫(xiě)了 5000 字那每次對(duì)話都先消耗掉一大塊上下文留給實(shí)際任務(wù)的空間就少了。我的經(jīng)驗(yàn)是控制在 500-1500 字之間。超過(guò)這個(gè)范圍就要考慮拆分把詳細(xì)的規(guī)范文檔放在單獨(dú)的文件里在CLAUDE.md里用引用指向它需要時(shí)再讓 Claude 去讀。比如# 代碼規(guī)范 詳細(xì)的代碼規(guī)范見(jiàn) docs/coding-standards.md。 核心約定函數(shù)式組件、kebab-case 文件名、禁止 any。這樣CLAUDE.md保持精簡(jiǎn)詳細(xì)內(nèi)容按需加載。另一個(gè)技巧是分層組織。把最重要的信息放在最前面因?yàn)槟Ｐ蛯?duì)開(kāi)頭的注意力更集中。項(xiàng)目概述、技術(shù)棧、常用命令放前面已知限制放后面。提示如果你的項(xiàng)目有多個(gè)子包monorepo可以在每個(gè)子包目錄下放一個(gè)CLAUDE.mdClaude 會(huì)根據(jù)當(dāng)前工作目錄自動(dòng)加載對(duì)應(yīng)的文件。這樣每個(gè)子包的上下文都是獨(dú)立的不會(huì)互相干擾。3.3 動(dòng)態(tài)更新與版本管理CLAUDE.md應(yīng)該跟著項(xiàng)目一起演進(jìn)。我的做法是把它納入 code review 流程每次有重大的技術(shù)決策變更換框架、改目錄結(jié)構(gòu)、加新約定都要同步更新CLAUDE.md。有個(gè)實(shí)用的技巧在CLAUDE.md里加一個(gè)“最近變更”小節(jié)記錄最近幾次重要的約定調(diào)整。這樣模型能感知到項(xiàng)目在演進(jìn)而不是把它當(dāng)成靜態(tài)文檔。# 最近變更 - 2024-11從 Redux 遷移到 Zustand舊代碼逐步替換 - 2024-10引入 TanStack Query新數(shù)據(jù)請(qǐng)求都用它 - 2024-09測(cè)試框架從 Jest 換成 Vitest這個(gè)習(xí)慣幫我避免了好幾次“Claude 用舊方案寫(xiě)代碼”的問(wèn)題。4. memory 機(jī)制的原理與使用技巧memory 是三套體系里最“隱形”的很多人用了很久都沒(méi)意識(shí)到它的存在。它的作用是讓 Claude 跨會(huì)話記住一些信息不用每次重復(fù)交代。4.1 memory 的存儲(chǔ)位置與格式memory 通常存儲(chǔ)在~/.claude/memory/目錄下具體路徑可能因版本而異每個(gè)項(xiàng)目一個(gè)文件文件名基于項(xiàng)目路徑的哈希。格式一般是 Markdown 或 JSON記錄的是鍵值對(duì)形式的條目。你可以通過(guò)對(duì)話讓 Claude 記住東西比如“記住這個(gè)項(xiàng)目用 pnpm 不用 npm”它會(huì)自動(dòng)寫(xiě)入 memory。也可以手動(dòng)編輯 memory 文件但要注意格式。memory 的條目通常包含內(nèi)容、創(chuàng)建時(shí)間、來(lái)源哪次對(duì)話、置信度。有些版本還支持過(guò)期時(shí)間到點(diǎn)自動(dòng)清理。4.2 什么該記、什么不該記memory 用得好是神器用不好是負(fù)擔(dān)。我的原則是該記的個(gè)人偏好“我喜歡簡(jiǎn)潔的回復(fù)不要長(zhǎng)篇解釋”跨會(huì)話的決策“這個(gè)項(xiàng)目決定用 Zustand 不用 Redux”臨時(shí)約定“這周在重構(gòu) auth 模塊相關(guān)代碼先別動(dòng)”不該記的項(xiàng)目結(jié)構(gòu)、技術(shù)棧這些應(yīng)該寫(xiě)在CLAUDE.md里團(tuán)隊(duì)共享一次性的任務(wù)細(xì)節(jié)記了也沒(méi)用任務(wù)完成就過(guò)時(shí)了敏感信息memory 是本地文件但也不建議存密鑰我見(jiàn)過(guò)有人把整個(gè)項(xiàng)目的架構(gòu)說(shuō)明都塞進(jìn) memory結(jié)果每次會(huì)話都加載一大堆過(guò)時(shí)信息反而干擾了判斷。memory 應(yīng)該保持精簡(jiǎn)只記那些“跨會(huì)話仍然有效”的東西。4.3 memory 與 CLAUDE.md 的邊界這兩者最容易混淆。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單團(tuán)隊(duì)共享的寫(xiě)CLAUDE.md個(gè)人專屬的寫(xiě) memory。比如“這個(gè)項(xiàng)目用 pnpm”是團(tuán)隊(duì)約定寫(xiě)CLAUDE.md?！拔伊?xí)慣看簡(jiǎn)潔的 diff不要貼大段代碼”是個(gè)人偏好寫(xiě) memory。如果一條信息既想團(tuán)隊(duì)共享又想個(gè)人保留那它大概率應(yīng)該寫(xiě)CLAUDE.md因?yàn)閭€(gè)人偏好可以通過(guò)用戶級(jí)settings.json或 memory 單獨(dú)處理。有個(gè)常見(jiàn)的誤區(qū)是把 memory 當(dāng)成“臨時(shí)便簽”記一堆“今天要改 XX 文件”之類的。這些信息下次會(huì)話就過(guò)時(shí)了留在 memory 里只會(huì)造成干擾。臨時(shí)任務(wù)應(yīng)該用 TODO 工具或者直接寫(xiě)在對(duì)話里不要污染 memory。4.4 清理與維護(hù) memorymemory 會(huì)隨著使用不斷累積定期清理很有必要。我的做法是每個(gè)月過(guò)一遍 memory 文件刪掉過(guò)時(shí)的條目。清理時(shí)問(wèn)自己三個(gè)問(wèn)題這條信息現(xiàn)在還準(zhǔn)確嗎這條信息下次會(huì)話還用得上嗎這條信息是不是應(yīng)該挪到CLAUDE.md里三個(gè)問(wèn)題有一個(gè)答“否”就考慮刪除或遷移。有些版本支持claude memory list和claude memory clear命令可以直接在命令行管理。如果你的版本不支持就手動(dòng)編輯文件。注意清理 memory 前建議先備份。雖然 memory 丟了不影響項(xiàng)目運(yùn)行但一些積累的偏好設(shè)置重新建立起來(lái)挺麻煩的。5. 三套體系的協(xié)同與常見(jiàn)問(wèn)題排查單獨(dú)理解三套體系不難難的是它們協(xié)同工作時(shí)出的問(wèn)題。這一節(jié)整理我遇到過(guò)的典型故障和排查思路。5.1 配置不生效的排查順序當(dāng)你發(fā)現(xiàn)某個(gè)配置沒(méi)生效時(shí)按這個(gè)順序排查確認(rèn)文件位置項(xiàng)目級(jí)還是用戶級(jí)路徑對(duì)不對(duì).claude/settings.json不是claude/settings.json少個(gè)點(diǎn)就找不到。確認(rèn) JSON 合法性用jq . settings.json驗(yàn)證有語(yǔ)法錯(cuò)誤會(huì)直接報(bào)出來(lái)。確認(rèn)優(yōu)先級(jí)是不是被更高優(yōu)先級(jí)的配置覆蓋了項(xiàng)目級(jí)覆蓋用戶級(jí)命令行覆蓋兩者。確認(rèn)加載時(shí)機(jī)settings.json改動(dòng)需要重啟會(huì)話才生效CLAUDE.md改動(dòng)下次會(huì)話生效memory 改動(dòng)立即生效。查看日志claude --debug啟動(dòng)可以看到配置加載的詳細(xì)日志哪條規(guī)則被應(yīng)用了一目了然。我遇到最多的問(wèn)題是 JSON 語(yǔ)法錯(cuò)誤。一個(gè)多余的逗號(hào)、一個(gè)中文引號(hào)都會(huì)導(dǎo)致整個(gè)文件被忽略。建議用編輯器自帶的 JSON 校驗(yàn)或者寫(xiě)完跑一次jq。5.2 權(quán)限規(guī)則沖突的典型案例案例一allow 里寫(xiě)了Bash(git:*)但git push還是每次詢問(wèn)。原因git push可能被ask里的規(guī)則匹配了或者用戶級(jí)配置里有更嚴(yán)格的規(guī)則。檢查所有層級(jí)的配置確認(rèn)沒(méi)有沖突。案例二deny 里寫(xiě)了Read(./.env)但 Claude 還是讀到了 .env 的內(nèi)容。原因路徑規(guī)則寫(xiě)錯(cuò)了。./.env是相對(duì)于當(dāng)前工作目錄如果 Claude 的工作目錄不是項(xiàng)目根就匹配不上。應(yīng)該用Read(//.env)或者絕對(duì)路徑。案例三hooks 里的命令不執(zhí)行。原因hooks 命令的執(zhí)行環(huán)境可能和你的 shell 不一樣PATH 可能不完整。建議用絕對(duì)路徑調(diào)用命令或者在命令前加source ~/.bashrc。5.3 上下文超限的應(yīng)對(duì)策略當(dāng)CLAUDE.md太長(zhǎng)、memory 條目太多時(shí)會(huì)出現(xiàn)上下文超限表現(xiàn)為 Claude 開(kāi)始“忘記”前面的內(nèi)容或者響應(yīng)變慢。應(yīng)對(duì)方法精簡(jiǎn)CLAUDE.md把詳細(xì)內(nèi)容外鏈到單獨(dú)文檔清理 memory刪除過(guò)時(shí)條目用/compact命令壓縮當(dāng)前會(huì)話的上下文把大任務(wù)拆成多個(gè)小會(huì)話每個(gè)會(huì)話專注一個(gè)子任務(wù)我處理大型重構(gòu)時(shí)的做法是先開(kāi)一個(gè)會(huì)話專門(mén)做規(guī)劃把規(guī)劃結(jié)果寫(xiě)進(jìn)CLAUDE.md或 memory然后開(kāi)新會(huì)話執(zhí)行具體任務(wù)。這樣每個(gè)會(huì)話的上下文都很干凈。5.4 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因排查方法配置完全不生效文件路徑錯(cuò)誤或 JSON 語(yǔ)法錯(cuò)誤jq . settings.json驗(yàn)證權(quán)限規(guī)則不生效優(yōu)先級(jí)沖突或規(guī)則語(yǔ)法錯(cuò)誤claude --debug看加載日志Claude 不遵守 CLAUDE.md內(nèi)容太長(zhǎng)被截?cái)嗷虮硎瞿：?jiǎn)內(nèi)容用明確的祈使句memory 不生效條目過(guò)期或格式錯(cuò)誤檢查 memory 文件格式hooks 不執(zhí)行命令路徑問(wèn)題或權(quán)限不足手動(dòng)跑一遍 hook 命令會(huì)話變慢上下文超限/compact或開(kāi)新會(huì)話模型選錯(cuò)model 字段名不對(duì)claude config list確認(rèn)字段名5.5 我的配置管理實(shí)踐最后分享一套我用了半年的配置管理流程供參考。版本控制項(xiàng)目級(jí).claude/settings.json和CLAUDE.md提交到倉(cāng)庫(kù)。用戶級(jí)配置和 memory 不提交但我會(huì)定期備份到私有倉(cāng)庫(kù)。模板化我維護(hù)了一套配置模板新項(xiàng)目初始化時(shí)直接復(fù)制改改項(xiàng)目名和技術(shù)棧就能用。省去了每次從零寫(xiě)CLAUDE.md的時(shí)間。定期審查每季度過(guò)一遍所有項(xiàng)目的配置清理過(guò)時(shí)規(guī)則更新技術(shù)棧版本。這個(gè)習(xí)慣幫我避免了好幾次“配置和實(shí)際不符”的問(wèn)題。團(tuán)隊(duì)同步團(tuán)隊(duì)里指定一個(gè)人負(fù)責(zé)維護(hù)共享配置其他人有變更需求提 PR。避免多人同時(shí)改導(dǎo)致沖突。這套流程跑下來(lái)配置相關(guān)的故障率明顯下降。配置這東西前期花時(shí)間搭好后期省的時(shí)間是成倍的。關(guān)于 memory 的清理我還有個(gè)習(xí)慣每次項(xiàng)目里程碑結(jié)束時(shí)把 memory 里和這個(gè)階段相關(guān)的條目清掉只保留長(zhǎng)期有效的偏好。這樣 memory 始終保持在幾十條以內(nèi)不會(huì)變成垃圾場(chǎng)。配置體系這東西沒(méi)有標(biāo)準(zhǔn)答案每個(gè)人的工作流不一樣最優(yōu)解也不一樣。但理解清楚settings.json、CLAUDE.md、memory 三者的邊界和協(xié)同方式是搭出適合自己方案的前提。我上面寫(xiě)的都是踩過(guò)坑之后總結(jié)出來(lái)的你可以根據(jù)自己的情況調(diào)整。 Claude Code 配置體系深度解析：settings.json、CLAUDE.md 與 memory 的邊界與協(xié)同
1. 三套配置體系到底在管什么很多人第一次接觸 Claude Code看到項(xiàng)目根目錄下同時(shí)存在settings.json、CLAUDE.md和 memory 相關(guān)文件第一反應(yīng)是懵的——這三個(gè)東西看起來(lái)都在“配置”到底誰(shuí)管誰(shuí)我剛開(kāi)始用的時(shí)候也踩過(guò)這個(gè)坑把一堆本該寫(xiě)在settings.json里的東西塞進(jìn)了CLAUDE.md結(jié)果權(quán)限規(guī)則死活不生效排查了半天才發(fā)現(xiàn)是放錯(cuò)了地方。先把結(jié)論擺在前面這三套體系分別對(duì)應(yīng)三個(gè)完全不同的層面。settings.json管的是“工具怎么跑”——權(quán)限、環(huán)境變量、模型選擇、鉤子hooks、MCP 服務(wù)器注冊(cè)。它是機(jī)器讀的格式嚴(yán)格寫(xiě)錯(cuò)一個(gè)逗號(hào)整個(gè)文件就廢了。CLAUDE.md管的是“項(xiàng)目是什么”——技術(shù)棧、目錄結(jié)構(gòu)、構(gòu)建命令、代碼規(guī)范、協(xié)作約定。它是給模型讀的自然語(yǔ)言上下文每次會(huì)話啟動(dòng)時(shí)會(huì)被加載進(jìn)上下文窗口。memory管的是“跨會(huì)話記住什么”——你在對(duì)話中讓 Claude 記住的偏好、決策、臨時(shí)約定它會(huì)持久化到本地文件下次開(kāi)新會(huì)話還能用。打個(gè)比方settings.json像是你給新員工配的工牌和門(mén)禁權(quán)限CLAUDE.md是放在工位上的項(xiàng)目手冊(cè)memory 則是這個(gè)員工自己的筆記本記著“老板喜歡用 pnpm 不用 npm”這類口頭約定。理解了這個(gè)分層后面所有的配置問(wèn)題基本都能對(duì)號(hào)入座。我見(jiàn)過(guò)太多人把權(quán)限規(guī)則寫(xiě)進(jìn)CLAUDE.md然后抱怨“為什么 Claude 還是每次都問(wèn)我”根源就是沒(méi)搞清楚這三者的邊界。1.1 為什么要有三套而不是一套這個(gè)問(wèn)題我被問(wèn)過(guò)不止一次。直覺(jué)上把所有配置塞進(jìn)一個(gè)文件不是更簡(jiǎn)單嗎實(shí)際上不行原因有三個(gè)。第一是加載時(shí)機(jī)不同。settings.json在進(jìn)程啟動(dòng)時(shí)就要解析決定了這次會(huì)話能用哪些工具、走哪個(gè)模型。CLAUDE.md是在會(huì)話初始化階段作為上下文注入的它影響的是模型的“認(rèn)知”而不是“能力”。memory 則是在會(huì)話過(guò)程中動(dòng)態(tài)讀寫(xiě)的隨時(shí)可能變化。三者生命周期完全不一樣硬合并會(huì)導(dǎo)致要么啟動(dòng)變慢要么上下文浪費(fèi)。第二是格式約束不同。settings.json必須是合法 JSON機(jī)器要嚴(yán)格解析CLAUDE.md是 Markdown本質(zhì)是給模型看的自然語(yǔ)言格式寬松得多memory 通常是結(jié)構(gòu)化的鍵值對(duì)或者追加式日志。把自然語(yǔ)言和嚴(yán)格 JSON 混在一個(gè)文件里解析器會(huì)瘋掉。第三是共享范圍不同。settings.json里有一部分是項(xiàng)目級(jí)提交到倉(cāng)庫(kù)團(tuán)隊(duì)共享有一部分是用戶級(jí)放在家目錄只對(duì)自己生效。CLAUDE.md通常是項(xiàng)目級(jí)共享的。memory 則基本是個(gè)人本地的。混在一起就沒(méi)法做這種粒度控制。提示如果你在團(tuán)隊(duì)里推廣 Claude Code建議把settings.json的項(xiàng)目級(jí)部分和CLAUDE.md一起提交到倉(cāng)庫(kù)用戶級(jí)配置和 memory 加進(jìn).gitignore。這樣新人 clone 下來(lái)就能直接用又不會(huì)把自己的個(gè)人偏好污染給全組。1.2 三者的優(yōu)先級(jí)與覆蓋關(guān)系實(shí)際使用中經(jīng)常出現(xiàn)“同一個(gè)設(shè)置在兩處都寫(xiě)了”的情況這時(shí)候誰(shuí)生效根據(jù)我的實(shí)測(cè)優(yōu)先級(jí)從高到低大致是命令行參數(shù)臨時(shí)覆蓋最高優(yōu)先級(jí)項(xiàng)目級(jí)settings.json.claude/settings.json用戶級(jí)settings.json~/.claude/settings.jsonCLAUDE.md中的約定僅作為上下文提示不強(qiáng)制memory 中的記錄最弱模型可能忽略這里有個(gè)關(guān)鍵點(diǎn)容易被誤解CLAUDE.md和 memory 里的內(nèi)容不是強(qiáng)制規(guī)則它們只是上下文。模型“傾向于”遵守但在復(fù)雜任務(wù)中可能被忽略。而settings.json里的權(quán)限規(guī)則是硬約束工具層面直接攔截。所以如果你有“絕對(duì)不能讓 Claude 執(zhí)行某類命令”的需求必須寫(xiě)在settings.json的權(quán)限配置里寫(xiě)進(jìn)CLAUDE.md是靠不住的。我踩過(guò)一次坑在CLAUDE.md里寫(xiě)了“不要執(zhí)行 rm -rf”結(jié)果某次重構(gòu)時(shí) Claude 還是建議了一條刪除命令。后來(lái)老老實(shí)實(shí)在settings.json里加了 deny 規(guī)則才徹底堵住。2. settings.json 深度拆解與實(shí)操配置settings.json是整個(gè)配置體系里最“硬”的部分也是最容易出錯(cuò)的。它的位置有兩個(gè)項(xiàng)目級(jí)的在項(xiàng)目根/.claude/settings.json用戶級(jí)的在~/.claude/settings.json。項(xiàng)目級(jí)會(huì)覆蓋用戶級(jí)的同名配置。2.1 文件結(jié)構(gòu)與核心字段一個(gè)完整的settings.json大致長(zhǎng)這樣{ permissions: { allow: [ Bash(npm run test:*), Bash(git status), Read(//src/**) ], deny: [ Bash(rm -rf:*), Bash(curl:*), Read(./.env) ], ask: [ Bash(git push:*), Write(//src/**) ] }, env: { NODE_ENV: development, PROJECT_ROOT: /Users/me/projects/demo }, model: claude-sonnet-4-5, hooks: { PostToolUse: [ { matcher: Write, hooks: [ { type: command, command: npx prettier --write $CLAUDE_FILE_PATH } ] } ] } }逐個(gè)字段說(shuō)。permissions是最核心的部分分allow、deny、ask三個(gè)數(shù)組。allow里的規(guī)則直接放行不詢問(wèn)deny里的直接拒絕ask里的每次都要用戶確認(rèn)。規(guī)則格式是工具名(參數(shù)模式)比如Bash(npm run test:*)表示允許所有以npm run test開(kāi)頭的命令。這里有個(gè)細(xì)節(jié)Bash規(guī)則的匹配是基于命令前綴的Bash(git status)只匹配完全等于git status的命令而B(niǎo)ash(git status:*)匹配git status后面跟任何參數(shù)。冒號(hào)加星號(hào)是通配符語(yǔ)法別漏了。env是注入到工具執(zhí)行環(huán)境里的變量。注意它不會(huì)自動(dòng)注入到 Claude 的上下文里只是影響 Bash 等工具執(zhí)行時(shí)的環(huán)境。如果你想讓 Claude 知道某個(gè)變量得寫(xiě)在CLAUDE.md里。model指定默認(rèn)模型。這個(gè)字段在不同版本里名字可能有變化有的版本用model有的用defaultModel。建議配置前先跑一次claude config list看看當(dāng)前支持的字段名。hooks是鉤子系統(tǒng)允許在工具調(diào)用前后執(zhí)行自定義命令。上面例子里的PostToolUse表示在 Write 工具執(zhí)行后跑 prettier 格式化。這個(gè)功能非常強(qiáng)大后面單獨(dú)講。2.2 權(quán)限規(guī)則的寫(xiě)法與常見(jiàn)陷阱權(quán)限規(guī)則寫(xiě)錯(cuò)是新手最高頻的問(wèn)題。我整理了幾種典型場(chǎng)景的正確寫(xiě)法。需求錯(cuò)誤寫(xiě)法正確寫(xiě)法允許所有 git 命令Bash(git)Bash(git:*)允許讀取 src 下所有文件Read(src/*)Read(//src/**)拒絕讀取 .envRead(.env)Read(./.env)允許 npm 腳本Bash(npm run:*)Bash(npm run:*)但注意空格允許特定目錄寫(xiě)入Write(src)Write(//src/**)幾個(gè)關(guān)鍵點(diǎn)路徑規(guī)則里//開(kāi)頭表示相對(duì)于項(xiàng)目根目錄./表示相對(duì)于當(dāng)前工作目錄~/表示家目錄。**匹配任意層級(jí)*只匹配單層。這個(gè)和 gitignore 的語(yǔ)法類似但不完全一樣別想當(dāng)然。Bash規(guī)則的匹配是前綴匹配不是正則。Bash(npm run test:*)會(huì)匹配npm run test、npm run test:unit、npm run test -- --watch但不會(huì)匹配npm run testx。冒號(hào)后面的*是必須的不寫(xiě)的話只匹配完全相等的命令。注意deny規(guī)則的優(yōu)先級(jí)高于allow。如果一條命令同時(shí)匹配 allow 和 deny會(huì)被拒絕。這個(gè)設(shè)計(jì)是為了安全但也意味著你寫(xiě) allow 的時(shí)候要小心別和已有的 deny 沖突。2.3 hooks 鉤子系統(tǒng)的實(shí)戰(zhàn)用法hooks 是我認(rèn)為settings.json里最被低估的功能。它讓你能在 Claude 執(zhí)行工具的前后插入自己的邏輯實(shí)現(xiàn)自動(dòng)化。支持的鉤子事件主要有PreToolUse工具執(zhí)行前觸發(fā)可以用來(lái)做校驗(yàn)、攔截PostToolUse工具執(zhí)行后觸發(fā)適合做格式化、lint、通知UserPromptSubmit用戶提交 prompt 時(shí)觸發(fā)Stop會(huì)話結(jié)束時(shí)觸發(fā)一個(gè)實(shí)用的例子每次 Claude 寫(xiě)完文件自動(dòng)跑 eslint 修復(fù)。{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: npx eslint --fix $CLAUDE_FILE_PATH 2/dev/null || true } ] } ] } }matcher支持正則Write|Edit表示匹配這兩個(gè)工具。$CLAUDE_FILE_PATH是環(huán)境變量指向被操作的文件路徑。末尾的|| true是為了防止 eslint 報(bào)錯(cuò)導(dǎo)致鉤子失敗阻塞流程。另一個(gè)場(chǎng)景在PreToolUse里攔截危險(xiǎn)命令。{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \$CLAUDE_TOOL_INPUT\ | grep -qE rm -rf / exit 1 || exit 0 } ] } ] } }這個(gè)鉤子檢查即將執(zhí)行的 Bash 命令里有沒(méi)有rm -rf /有就返回非零退出碼阻止執(zhí)行。雖然permissions.deny也能做類似的事但 hooks 能做更復(fù)雜的邏輯判斷。2.4 用戶級(jí)與項(xiàng)目級(jí)的分工策略我的建議是把配置分成兩類用戶級(jí)~/.claude/settings.json放個(gè)人偏好默認(rèn)模型、個(gè)人常用的 allow 規(guī)則比如允許所有g(shù)it只讀命令、個(gè)人 hooks比如通知腳本。項(xiàng)目級(jí).claude/settings.json放團(tuán)隊(duì)約定項(xiàng)目特定的構(gòu)建命令權(quán)限、項(xiàng)目 hooks格式化、lint、項(xiàng)目環(huán)境變量。這樣新人入職時(shí)clone 項(xiàng)目就自動(dòng)獲得團(tuán)隊(duì)約定同時(shí)保留自己的個(gè)人偏好。沖突時(shí)項(xiàng)目級(jí)覆蓋用戶級(jí)符合直覺(jué)。有個(gè)坑要注意項(xiàng)目級(jí)settings.json如果提交到倉(cāng)庫(kù)里面不要放任何敏感信息API key、內(nèi)部路徑。環(huán)境變量里的密鑰應(yīng)該通過(guò)系統(tǒng)環(huán)境變量注入而不是寫(xiě)死在配置文件里。3. CLAUDE.md 的寫(xiě)法與上下文管理如果說(shuō)settings.json是給機(jī)器看的CLAUDE.md就是給模型看的。它的質(zhì)量直接決定了 Claude 對(duì)你項(xiàng)目的理解程度進(jìn)而影響輸出質(zhì)量。我見(jiàn)過(guò)太多人把CLAUDE.md寫(xiě)成一句話“這是一個(gè) React 項(xiàng)目”然后抱怨 Claude 生成的代碼不符合規(guī)范。3.1 一份合格 CLAUDE.md 的必備要素根據(jù)我多個(gè)項(xiàng)目的實(shí)踐一份好用的CLAUDE.md應(yīng)該包含以下內(nèi)容項(xiàng)目概述一兩句話說(shuō)明項(xiàng)目是干什么的目標(biāo)用戶是誰(shuí)。這幫助模型建立整體認(rèn)知。技術(shù)棧語(yǔ)言、框架、主要依賴的版本。特別注意標(biāo)注版本因?yàn)椴煌姹镜?API 差異很大。目錄結(jié)構(gòu)關(guān)鍵目錄的用途說(shuō)明。不需要列出所有文件但要讓模型知道“組件放哪、工具函數(shù)放哪、測(cè)試放哪”。常用命令構(gòu)建、測(cè)試、lint、啟動(dòng)開(kāi)發(fā)服務(wù)器的命令。這是最高頻被用到的部分。代碼規(guī)范命名約定、文件組織約定、導(dǎo)入順序、注釋風(fēng)格。越具體越好。協(xié)作約定提交信息格式、分支命名、PR 流程。如果團(tuán)隊(duì)有約定的話。已知限制項(xiàng)目里有哪些坑、哪些地方不要?jiǎng)?、哪些依賴不能升?jí)。一個(gè)真實(shí)的例子# 項(xiàng)目概述 這是一個(gè)面向中小企業(yè)的庫(kù)存管理系統(tǒng)前端使用 React TypeScript。 # 技術(shù)棧 - React 18.2注意不用 19因?yàn)橐蕾嚨?UI 庫(kù)還沒(méi)適配 - TypeScript 5.3 - Vite 5.0 構(gòu)建 - Zustand 狀態(tài)管理不用 Redux - TanStack Query 數(shù)據(jù)請(qǐng)求 # 目錄結(jié)構(gòu) - src/components/ 通用組件每個(gè)組件一個(gè)目錄 - src/features/ 按業(yè)務(wù)模塊組織的功能代碼 - src/lib/ 工具函數(shù)和第三方封裝 - src/types/ 全局類型定義 # 常用命令 - pnpm dev 啟動(dòng)開(kāi)發(fā)服務(wù)器 - pnpm test 跑單元測(cè)試 - pnpm lint 代碼檢查 - pnpm build 生產(chǎn)構(gòu)建 # 代碼規(guī)范 - 組件用函數(shù)式 hooks不用 class - 文件名用 kebab-case組件名用 PascalCase - 導(dǎo)入順序react → 第三方 → 內(nèi)部絕對(duì)路徑 → 相對(duì)路徑 - 禁止使用 any用 unknown 加類型守衛(wèi) # 已知限制 - 不要升級(jí) react 到 19 - src/lib/legacy/ 下的代碼是歷史遺留不要重構(gòu) - 測(cè)試覆蓋率要求 80%新代碼必須帶測(cè)試這份CLAUDE.md大概 300 字但信息密度很高。Claude 讀完就知道該用什么、不該用什么、命令怎么跑。3.2 上下文窗口的取舍藝術(shù)CLAUDE.md不是越長(zhǎng)越好。它每次會(huì)話都會(huì)被加載進(jìn)上下文窗口占用 token。如果你的CLAUDE.md寫(xiě)了 5000 字那每次對(duì)話都先消耗掉一大塊上下文留給實(shí)際任務(wù)的空間就少了。我的經(jīng)驗(yàn)是控制在 500-1500 字之間。超過(guò)這個(gè)范圍就要考慮拆分把詳細(xì)的規(guī)范文檔放在單獨(dú)的文件里在CLAUDE.md里用引用指向它需要時(shí)再讓 Claude 去讀。比如# 代碼規(guī)范 詳細(xì)的代碼規(guī)范見(jiàn) docs/coding-standards.md。 核心約定函數(shù)式組件、kebab-case 文件名、禁止 any。這樣CLAUDE.md保持精簡(jiǎn)詳細(xì)內(nèi)容按需加載。另一個(gè)技巧是分層組織。把最重要的信息放在最前面因?yàn)槟Ｐ蛯?duì)開(kāi)頭的注意力更集中。項(xiàng)目概述、技術(shù)棧、常用命令放前面已知限制放后面。提示如果你的項(xiàng)目有多個(gè)子包monorepo可以在每個(gè)子包目錄下放一個(gè)CLAUDE.mdClaude 會(huì)根據(jù)當(dāng)前工作目錄自動(dòng)加載對(duì)應(yīng)的文件。這樣每個(gè)子包的上下文都是獨(dú)立的不會(huì)互相干擾。3.3 動(dòng)態(tài)更新與版本管理CLAUDE.md應(yīng)該跟著項(xiàng)目一起演進(jìn)。我的做法是把它納入 code review 流程每次有重大的技術(shù)決策變更換框架、改目錄結(jié)構(gòu)、加新約定都要同步更新CLAUDE.md。有個(gè)實(shí)用的技巧在CLAUDE.md里加一個(gè)“最近變更”小節(jié)記錄最近幾次重要的約定調(diào)整。這樣模型能感知到項(xiàng)目在演進(jìn)而不是把它當(dāng)成靜態(tài)文檔。# 最近變更 - 2024-11從 Redux 遷移到 Zustand舊代碼逐步替換 - 2024-10引入 TanStack Query新數(shù)據(jù)請(qǐng)求都用它 - 2024-09測(cè)試框架從 Jest 換成 Vitest這個(gè)習(xí)慣幫我避免了好幾次“Claude 用舊方案寫(xiě)代碼”的問(wèn)題。4. memory 機(jī)制的原理與使用技巧memory 是三套體系里最“隱形”的很多人用了很久都沒(méi)意識(shí)到它的存在。它的作用是讓 Claude 跨會(huì)話記住一些信息不用每次重復(fù)交代。4.1 memory 的存儲(chǔ)位置與格式memory 通常存儲(chǔ)在~/.claude/memory/目錄下具體路徑可能因版本而異每個(gè)項(xiàng)目一個(gè)文件文件名基于項(xiàng)目路徑的哈希。格式一般是 Markdown 或 JSON記錄的是鍵值對(duì)形式的條目。你可以通過(guò)對(duì)話讓 Claude 記住東西比如“記住這個(gè)項(xiàng)目用 pnpm 不用 npm”它會(huì)自動(dòng)寫(xiě)入 memory。也可以手動(dòng)編輯 memory 文件但要注意格式。memory 的條目通常包含內(nèi)容、創(chuàng)建時(shí)間、來(lái)源哪次對(duì)話、置信度。有些版本還支持過(guò)期時(shí)間到點(diǎn)自動(dòng)清理。4.2 什么該記、什么不該記memory 用得好是神器用不好是負(fù)擔(dān)。我的原則是該記的個(gè)人偏好“我喜歡簡(jiǎn)潔的回復(fù)不要長(zhǎng)篇解釋”跨會(huì)話的決策“這個(gè)項(xiàng)目決定用 Zustand 不用 Redux”臨時(shí)約定“這周在重構(gòu) auth 模塊相關(guān)代碼先別動(dòng)”不該記的項(xiàng)目結(jié)構(gòu)、技術(shù)棧這些應(yīng)該寫(xiě)在CLAUDE.md里團(tuán)隊(duì)共享一次性的任務(wù)細(xì)節(jié)記了也沒(méi)用任務(wù)完成就過(guò)時(shí)了敏感信息memory 是本地文件但也不建議存密鑰我見(jiàn)過(guò)有人把整個(gè)項(xiàng)目的架構(gòu)說(shuō)明都塞進(jìn) memory結(jié)果每次會(huì)話都加載一大堆過(guò)時(shí)信息反而干擾了判斷。memory 應(yīng)該保持精簡(jiǎn)只記那些“跨會(huì)話仍然有效”的東西。4.3 memory 與 CLAUDE.md 的邊界這兩者最容易混淆。我的判斷標(biāo)準(zhǔn)很簡(jiǎn)單團(tuán)隊(duì)共享的寫(xiě)CLAUDE.md個(gè)人專屬的寫(xiě) memory。比如“這個(gè)項(xiàng)目用 pnpm”是團(tuán)隊(duì)約定寫(xiě)CLAUDE.md?！拔伊?xí)慣看簡(jiǎn)潔的 diff不要貼大段代碼”是個(gè)人偏好寫(xiě) memory。如果一條信息既想團(tuán)隊(duì)共享又想個(gè)人保留那它大概率應(yīng)該寫(xiě)CLAUDE.md因?yàn)閭€(gè)人偏好可以通過(guò)用戶級(jí)settings.json或 memory 單獨(dú)處理。有個(gè)常見(jiàn)的誤區(qū)是把 memory 當(dāng)成“臨時(shí)便簽”記一堆“今天要改 XX 文件”之類的。這些信息下次會(huì)話就過(guò)時(shí)了留在 memory 里只會(huì)造成干擾。臨時(shí)任務(wù)應(yīng)該用 TODO 工具或者直接寫(xiě)在對(duì)話里不要污染 memory。4.4 清理與維護(hù) memorymemory 會(huì)隨著使用不斷累積定期清理很有必要。我的做法是每個(gè)月過(guò)一遍 memory 文件刪掉過(guò)時(shí)的條目。清理時(shí)問(wèn)自己三個(gè)問(wèn)題這條信息現(xiàn)在還準(zhǔn)確嗎這條信息下次會(huì)話還用得上嗎這條信息是不是應(yīng)該挪到CLAUDE.md里三個(gè)問(wèn)題有一個(gè)答“否”就考慮刪除或遷移。有些版本支持claude memory list和claude memory clear命令可以直接在命令行管理。如果你的版本不支持就手動(dòng)編輯文件。注意清理 memory 前建議先備份。雖然 memory 丟了不影響項(xiàng)目運(yùn)行但一些積累的偏好設(shè)置重新建立起來(lái)挺麻煩的。5. 三套體系的協(xié)同與常見(jiàn)問(wèn)題排查單獨(dú)理解三套體系不難難的是它們協(xié)同工作時(shí)出的問(wèn)題。這一節(jié)整理我遇到過(guò)的典型故障和排查思路。5.1 配置不生效的排查順序當(dāng)你發(fā)現(xiàn)某個(gè)配置沒(méi)生效時(shí)按這個(gè)順序排查確認(rèn)文件位置項(xiàng)目級(jí)還是用戶級(jí)路徑對(duì)不對(duì).claude/settings.json不是claude/settings.json少個(gè)點(diǎn)就找不到。確認(rèn) JSON 合法性用jq . settings.json驗(yàn)證有語(yǔ)法錯(cuò)誤會(huì)直接報(bào)出來(lái)。確認(rèn)優(yōu)先級(jí)是不是被更高優(yōu)先級(jí)的配置覆蓋了項(xiàng)目級(jí)覆蓋用戶級(jí)命令行覆蓋兩者。確認(rèn)加載時(shí)機(jī)settings.json改動(dòng)需要重啟會(huì)話才生效CLAUDE.md改動(dòng)下次會(huì)話生效memory 改動(dòng)立即生效。查看日志claude --debug啟動(dòng)可以看到配置加載的詳細(xì)日志哪條規(guī)則被應(yīng)用了一目了然。我遇到最多的問(wèn)題是 JSON 語(yǔ)法錯(cuò)誤。一個(gè)多余的逗號(hào)、一個(gè)中文引號(hào)都會(huì)導(dǎo)致整個(gè)文件被忽略。建議用編輯器自帶的 JSON 校驗(yàn)或者寫(xiě)完跑一次jq。5.2 權(quán)限規(guī)則沖突的典型案例案例一allow 里寫(xiě)了Bash(git:*)但git push還是每次詢問(wèn)。原因git push可能被ask里的規(guī)則匹配了或者用戶級(jí)配置里有更嚴(yán)格的規(guī)則。檢查所有層級(jí)的配置確認(rèn)沒(méi)有沖突。案例二deny 里寫(xiě)了Read(./.env)但 Claude 還是讀到了 .env 的內(nèi)容。原因路徑規(guī)則寫(xiě)錯(cuò)了。./.env是相對(duì)于當(dāng)前工作目錄如果 Claude 的工作目錄不是項(xiàng)目根就匹配不上。應(yīng)該用Read(//.env)或者絕對(duì)路徑。案例三hooks 里的命令不執(zhí)行。原因hooks 命令的執(zhí)行環(huán)境可能和你的 shell 不一樣PATH 可能不完整。建議用絕對(duì)路徑調(diào)用命令或者在命令前加source ~/.bashrc。5.3 上下文超限的應(yīng)對(duì)策略當(dāng)CLAUDE.md太長(zhǎng)、memory 條目太多時(shí)會(huì)出現(xiàn)上下文超限表現(xiàn)為 Claude 開(kāi)始“忘記”前面的內(nèi)容或者響應(yīng)變慢。應(yīng)對(duì)方法精簡(jiǎn)CLAUDE.md把詳細(xì)內(nèi)容外鏈到單獨(dú)文檔清理 memory刪除過(guò)時(shí)條目用/compact命令壓縮當(dāng)前會(huì)話的上下文把大任務(wù)拆成多個(gè)小會(huì)話每個(gè)會(huì)話專注一個(gè)子任務(wù)我處理大型重構(gòu)時(shí)的做法是先開(kāi)一個(gè)會(huì)話專門(mén)做規(guī)劃把規(guī)劃結(jié)果寫(xiě)進(jìn)CLAUDE.md或 memory然后開(kāi)新會(huì)話執(zhí)行具體任務(wù)。這樣每個(gè)會(huì)話的上下文都很干凈。5.4 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因排查方法配置完全不生效文件路徑錯(cuò)誤或 JSON 語(yǔ)法錯(cuò)誤jq . settings.json驗(yàn)證權(quán)限規(guī)則不生效優(yōu)先級(jí)沖突或規(guī)則語(yǔ)法錯(cuò)誤claude --debug看加載日志Claude 不遵守 CLAUDE.md內(nèi)容太長(zhǎng)被截?cái)嗷虮硎瞿：?jiǎn)內(nèi)容用明確的祈使句memory 不生效條目過(guò)期或格式錯(cuò)誤檢查 memory 文件格式hooks 不執(zhí)行命令路徑問(wèn)題或權(quán)限不足手動(dòng)跑一遍 hook 命令會(huì)話變慢上下文超限/compact或開(kāi)新會(huì)話模型選錯(cuò)model 字段名不對(duì)claude config list確認(rèn)字段名5.5 我的配置管理實(shí)踐最后分享一套我用了半年的配置管理流程供參考。版本控制項(xiàng)目級(jí).claude/settings.json和CLAUDE.md提交到倉(cāng)庫(kù)。用戶級(jí)配置和 memory 不提交但我會(huì)定期備份到私有倉(cāng)庫(kù)。模板化我維護(hù)了一套配置模板新項(xiàng)目初始化時(shí)直接復(fù)制改改項(xiàng)目名和技術(shù)棧就能用。省去了每次從零寫(xiě)CLAUDE.md的時(shí)間。定期審查每季度過(guò)一遍所有項(xiàng)目的配置清理過(guò)時(shí)規(guī)則更新技術(shù)棧版本。這個(gè)習(xí)慣幫我避免了好幾次“配置和實(shí)際不符”的問(wèn)題。團(tuán)隊(duì)同步團(tuán)隊(duì)里指定一個(gè)人負(fù)責(zé)維護(hù)共享配置其他人有變更需求提 PR。避免多人同時(shí)改導(dǎo)致沖突。這套流程跑下來(lái)配置相關(guān)的故障率明顯下降。配置這東西前期花時(shí)間搭好后期省的時(shí)間是成倍的。關(guān)于 memory 的清理我還有個(gè)習(xí)慣每次項(xiàng)目里程碑結(jié)束時(shí)把 memory 里和這個(gè)階段相關(guān)的條目清掉只保留長(zhǎng)期有效的偏好。這樣 memory 始終保持在幾十條以內(nèi)不會(huì)變成垃圾場(chǎng)。配置體系這東西沒(méi)有標(biāo)準(zhǔn)答案每個(gè)人的工作流不一樣最優(yōu)解也不一樣。但理解清楚settings.json、CLAUDE.md、memory 三者的邊界和協(xié)同方式是搭出適合自己方案的前提。我上面寫(xiě)的都是踩過(guò)坑之后總結(jié)出來(lái)的你可以根據(jù)自己的情況調(diào)整。