1. 三套配置体系到底在管什么很多人第一次接触 Claude Code看到项目根目录下同时存在settings.json、CLAUDE.md还有一套叫 memory 的机制第一反应是懵的——这三个东西看起来都在“配置”到底谁管谁我刚开始用的时候也踩过这个坑把一堆本该写进CLAUDE.md的项目约定塞进了settings.json结果要么不生效要么每次启动都报解析错误。后来把三者的职责边界彻底理清整个工作流才顺起来。先把结论摆出来方便你建立整体认知settings.json管的是“工具怎么跑”——权限、环境变量、模型选择、钩子hooks、MCP 服务器注册这类运行时行为。它是给 Claude Code 这个程序本身读的配置。CLAUDE.md管的是“项目是什么”——代码规范、目录结构说明、构建命令、团队约定、注意事项。它是给模型读的“项目说明书”每次会话都会作为上下文注入。memory管的是“跨会话记住什么”——你在对话中让 Claude 记住的偏好、决策、临时结论它会持久化下来下次接着用。打个比方settings.json像是你给新员工配的工牌权限和办公设备门禁能进哪些房间、电脑装了什么软件CLAUDE.md是贴在工位上的项目手册这个项目怎么跑、代码风格是什么memory 则是这个员工的随身笔记本记着“上次老板说这个模块先别动”。三者层级不同、加载时机不同、作用对象也不同。下面逐个拆开讲把每一层的配置项、写法、生效逻辑和踩坑点都过一遍。1.1 为什么需要三套而不是一套这个问题我被问过很多次。核心原因在于作用域和生命周期不一样。settings.json的配置是机器级或项目级的一旦设定就稳定生效不随对话内容变化。比如你规定Bash命令只能执行白名单里的命令这是安全边界不能因为某次对话说“这次允许”就放开。CLAUDE.md是项目级的跟着代码仓库走会提交到 Git团队成员共享。它描述的是这个项目的客观事实不因个人偏好改变。memory 是用户级 会话级的跟着你个人走跨项目、跨会话。你告诉 Claude“我习惯用 pnpm 不用 npm”这是你的个人偏好不该写进团队共享的CLAUDE.md。如果硬要用一套配置搞定你会遇到两个死结一是团队共享的配置里混进了个人偏好别人拉下来一堆不适用二是安全边界和个人习惯混在一起想临时放宽权限时容易误伤安全设置。分开之后各管各的改哪层心里有数。1.2 三者的加载顺序与优先级理解加载顺序对排查“为什么我的配置没生效”至关重要。根据我实测和官方文档的说明大致的加载链路是这样的启动时先读全局用户配置通常在用户主目录下的.claude目录里这是你个人的默认设置。然后读项目级配置项目根目录的.claude/settings.json项目级会覆盖全局级的同名项。接着读本地私有配置一般是.claude/settings.local.json不提交 Git用于覆盖前两者中你不想共享的部分。CLAUDE.md在会话初始化时被读取并注入上下文项目根目录的优先子目录的按需加载。memory 在会话过程中动态读写优先级最高因为它代表你“刚刚说的话”。注意项目级配置覆盖全局配置是“合并覆盖”而非“整体替换”。也就是说你只写了permissions字段其他字段仍然沿用全局的值。这一点很多人误解以为写了项目配置全局就全废了。我踩过的一个典型坑在项目settings.json里只写了model字段结果发现全局配的 hooks 还在生效一度以为是缓存问题。后来才明白是合并逻辑。所以改配置时要清楚自己是在“增量修改”还是“想完全接管”。2. settings.json 深度拆解settings.json是三者里最“硬核”的一个因为它直接控制程序行为。写错了轻则不生效重则命令被拦截、会话起不来。我把常用字段和实际写法整理如下。2.1 核心字段与权限模型权限系统是settings.json里最值得花时间研究的部分。Claude Code 默认对敏感操作执行 shell 命令、写文件、访问网络会请求确认你可以通过配置把某些操作设为“总是允许”或“总是拒绝”。一个典型的权限配置长这样{ permissions: { allow: [ Bash(git status), Bash(git diff:*), Read(./src/**), Edit(./src/**) ], deny: [ Bash(rm -rf:*), Read(./.env), Read(./secrets/**) ] } }这里的语法规则需要重点说明因为写错了不会报错只会静默不匹配Bash(git status)表示精确匹配这条命令。Bash(git diff:*)里的:*是通配符表示git diff后面可以跟任意参数。Read(./src/**)里的**匹配任意层级路径。deny的优先级高于allow两者冲突时以deny为准。我个人的经验是deny列表一定要把敏感文件写死尤其是.env、密钥目录、生产配置。因为模型有时候会“好心”去读这些文件来理解项目一旦读进上下文就可能出现在日志或输出里。把Read(./.env)放进deny等于上了一道保险。提示权限匹配是大小写敏感的路径写法要和你实际调用时一致。Windows 下路径分隔符用正斜杠/更稳妥反斜杠容易出问题。2.2 环境变量与模型配置除了权限settings.json还负责注入环境变量和指定模型。环境变量这块很实用比如你想让项目里的脚本默认走某个 API 端点或者设置NODE_ENV都可以在这里配{ env: { NODE_ENV: development, PROJECT_ROOT: /Users/me/workspace/myapp }, model: claude-sonnet-4-5 }模型字段决定了默认用哪个模型。如果你同时用多个模型比如复杂任务用强模型、简单任务用快模型可以在这里设默认值然后在会话里临时切换。这里有个细节值得说env里配的变量会注入到 Claude Code 执行的子进程环境中但不会自动写进你的 shell 配置文件。也就是说它只影响 Claude Code 发起的命令不影响你手动在终端敲的命令。这个隔离设计是合理的避免污染你的全局环境。2.3 hooks 与 MCP 服务器注册hooks 是settings.json里进阶但极其好用的功能。它允许你在特定事件发生时自动执行命令比如“每次 Claude 写完文件后自动跑一次格式化”。{ hooks: { PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: npx prettier --write $CLAUDE_FILE_PATH } ] } ] } }这段配置的意思是当 Claude 使用Edit工具修改文件后自动对该文件跑一次 Prettier。$CLAUDE_FILE_PATH是内置变量指向被修改的文件路径。MCPModel Context Protocol服务器的注册也在这里。MCP 让 Claude Code 能连接外部工具和数据源比如数据库、内部 API。注册写法通常是{ mcpServers: { my-database: { command: npx, args: [-y, myorg/mcp-db-server], env: { DB_URL: postgres://localhost:5432/mydb } } } }注意MCP 服务器启动失败时Claude Code 通常不会阻塞主流程但对应工具会不可用。排查时先手动在终端跑一遍command加args确认能起来再看配置。我实测下来hooks 最容易出问题的地方是命令超时和路径含空格。格式化大文件时如果超过默认超时hook 会被中断但不报明显错误。路径含空格时记得加引号否则命令会被拆断。3. CLAUDE.md 的写法与实战技巧如果说settings.json是给程序看的那CLAUDE.md就是给模型看的。它的质量直接决定了 Claude 对你项目的理解程度进而影响它给出的建议和代码是否“对味”。3.1 该写什么、不该写什么很多人把CLAUDE.md写成 README 的复制粘贴这是浪费。README 是给人看的CLAUDE.md是给模型看的两者关注点不同。该写进CLAUDE.md的内容项目一句话定位让模型快速建立上下文比如“这是一个基于 FastAPI 的订单服务依赖 PostgreSQL 和 Redis”。构建与测试命令模型需要知道怎么验证自己的改动比如pnpm test、make build。代码规范命名约定、目录组织原则、禁止使用的库。架构关键决策为什么用某个方案避免模型提出已经被否决的建议。常见陷阱比如“不要直接改generated/目录那是自动生成的”。不该写的内容大段的业务背景介绍模型不需要知道公司历史。敏感的凭据、内部地址。频繁变动的信息这类放 memory 更合适。我见过一个反例有人在CLAUDE.md里贴了整整 800 行的 API 文档结果每次会话上下文被占掉一大块模型反而抓不住重点。CLAUDE.md讲究精炼且高信号一般控制在 100 到 300 行比较合适。3.2 分层组织与子目录覆盖CLAUDE.md支持分层。项目根目录放一份总纲子目录可以放各自的CLAUDE.md模型在处理该目录下的文件时会加载对应的说明。这个机制在大型 monorepo 里特别有用。比如/CLAUDE.md # 全局约定 /packages/api/CLAUDE.md # API 包特有约定 /packages/web/CLAUDE.md # 前端包特有约定根目录的写通用规范提交信息格式、代码风格子目录的写各自的技术栈细节API 包用 pytest前端包用 vitest。这样模型在改前端代码时不会被后端测试命令干扰。提示子目录的CLAUDE.md是“叠加”而非“替换”根目录的。所以根目录里已经写过的通用规则子目录不用重复。3.3 让模型真正“读懂”的写作技巧写CLAUDE.md有几个实操技巧是我反复试验后总结的用命令式而非描述式。与其写“本项目使用 ESLint 进行代码检查”不如写“提交前必须运行pnpm lint并修复所有报错”。前者是陈述后者是可执行指令模型对后者的遵循度明显更高。给出正反例。对于容易出错的规范直接给例子。比如命名规范 - 正确getUserById - 错误get_user_by_id、GetUserById标注优先级。当规则之间有冲突可能时明确说哪个优先。比如“性能优先于可读性”或“安全优先于便利性”。定期清理。项目演进后CLAUDE.md里过时的内容会误导模型。我一般每个迭代周期 review 一次删掉不再适用的条目。4. memory 机制与跨会话记忆memory 是三者里最“隐形”的因为它不像前两者那样有明确的文件让你编辑而是在对话中动态形成。但它的影响很大用好了能省大量重复沟通。4.1 memory 的存储位置与结构memory 本质上是一组持久化的笔记文件通常存放在用户主目录下的.claude相关目录里按项目或主题组织。每条记忆包含内容、创建时间、来源会话等元信息。它的读写逻辑是这样的会话开始时相关的 memory 被加载进上下文会话过程中当你明确说“记住这个”或模型判断某条信息值得留存时会写入 memory下次会话如果涉及相关主题这些记忆会被召回。这里有个关键点memory 不是全量加载的。它按相关性召回所以不会像CLAUDE.md那样每次都占满上下文。这也是它适合存“零散偏好”的原因。4.2 什么该让 Claude 记住不是所有东西都值得存进 memory。存太多会导致召回噪音反而干扰判断。我的经验是以下几类值得存个人工具偏好比如“我用 pnpm 不用 npm”“我的编辑器是 Neovim”。项目决策结论比如“这个模块的缓存方案最终选了 Redis不用 Memcached”。反复出现的纠正如果你已经三次纠正模型同一个错误就该让它记住。临时但跨会话的上下文比如“这周在重构认证模块相关改动先别提交”。不值得存的一次性的调试信息。能从代码或CLAUDE.md推导出来的事实。敏感信息memory 也是持久化的别存密钥。4.3 手动管理 memory 的实用方法虽然 memory 可以自动形成但手动管理更可控。我常用的几个操作显式要求记住。直接说“记住这个项目所有日期都用 UTC 存储”比让模型自己判断更可靠。定期查看和清理。可以要求模型列出当前相关的 memory检查有没有过时或错误的条目然后让它删除。按项目隔离。确保 memory 的归属正确避免把 A 项目的偏好带到 B 项目。如果发现串了手动清理。注意memory 的召回依赖相关性匹配如果某条记忆一直没被用到可能是它的描述不够具体。把“用 pnpm”改成“本机 Node 项目统一用 pnpm 作为包管理器”召回率会更高。我踩过的一个坑早期我让模型记住了一堆临时决策结果几个月后这些决策早就变了但 memory 还在导致模型给出过时建议。后来养成习惯每个项目阶段结束时清理一次 memory把已完成的临时上下文删掉。5. 三套配置的协同与冲突排查单独搞懂三者不难难的是它们协同工作时出的问题。这一节专门讲冲突场景和排查方法。5.1 典型冲突场景与解决场景一权限被settings.json拦截但CLAUDE.md里说可以执行。这是最常见的冲突。CLAUDE.md是给模型的建议settings.json是硬性边界。模型可能“想”执行某命令但被权限系统拦下。解决办法是把该命令加进allow列表而不是改CLAUDE.md。场景二memory 里的偏好和CLAUDE.md的规范打架。比如CLAUDE.md规定用 2 空格缩进但你之前让 memory 记住了“我喜欢 4 空格”。这时 memory 优先级更高模型会按 4 空格来。解决办法是清理冲突的 memory团队规范应该以CLAUDE.md为准。场景三项目级settings.json覆盖了全局的 hooks。如果你在项目配置里重写了hooks字段全局的 hooks 可能就不生效了。要确认是合并还是替换必要时在项目配置里把全局 hooks 也带上。下面这张表可以帮你快速定位问题现象可能原因排查方向命令被拒绝执行权限 deny 或未在 allow检查 settings.json 的 permissions模型不懂项目规范CLAUDE.md 缺失或太笼统补充具体、命令式的规范偏好没被记住memory 未形成或描述模糊显式要求记住写具体配置改了不生效层级覆盖或缓存确认加载顺序重启会话hooks 不触发matcher 不匹配或超时检查 matcher 字符串和命令耗时5.2 排查配置问题的通用流程遇到配置相关问题时我一般按这个顺序排查确认改的是哪一层。是全局、项目级还是本地私有改错层是最常见的原因。检查 JSON 语法。settings.json语法错误会导致整个文件被忽略而且不一定有明显报错。用编辑器的 JSON 校验功能过一遍。确认加载顺序。项目级是否覆盖了你的全局设置用/config之类的命令查看当前生效的配置。重启会话。很多配置在会话启动时读取改完要新开会话才生效。看日志。Claude Code 通常有调试日志能看到配置加载和权限判定的过程。提示改settings.json前先备份尤其是权限相关的配置。一个写错的 deny 规则可能让你连正常命令都跑不了恢复起来麻烦。5.3 团队协作下的配置管理建议团队一起用 Claude Code 时配置管理要有约定settings.json的项目级部分提交 Git但把个人偏好放settings.local.json并加进.gitignore。CLAUDE.md必须提交它是团队共享的项目知识。memory 不共享它是个人资产不要试图同步。定期 reviewCLAUDE.md把它当成代码一样维护过时内容及时清理。我所在的团队有个习惯每次架构调整后指定一个人更新CLAUDE.md并在 PR 里一起 review。这样保证模型拿到的项目信息始终是最新的避免它基于过时认知给出建议。6. 实操心得与常见问题速查最后这部分是我在实际使用中积累的一些零散但有用的经验以及高频问题的快速答案。6.1 我踩过的那些坑坑一把密钥写进settings.json的 env。settings.json如果提交了 Git密钥就泄露了。正确做法是用环境变量引用或者放settings.local.json。我现在所有涉及凭据的配置一律走本地私有文件。坑二CLAUDE.md写太长导致模型“失忆”。上下文是有限资源CLAUDE.md占太多留给实际代码的空间就少。控制在 300 行以内把细节放到子目录的CLAUDE.md里按需加载。坑三memory 和CLAUDE.md内容重复。重复不仅浪费还容易冲突。原则是团队共享的进CLAUDE.md个人偏好进 memory两者不重叠。坑四hooks 命令没考虑失败情况。格式化命令如果失败可能阻塞后续流程。建议在 hook 命令里加容错比如|| true或者用脚本包装处理错误。坑五权限配置过于宽松。为了省事把Bash(*)全放开等于放弃了安全边界。我现在的做法是默认拒绝按需逐条添加虽然麻烦但安全。6.2 高频问题速查表问题快速答案配置改了不生效怎么办确认层级、检查 JSON 语法、重启会话怎么让模型记住我的偏好显式说“记住xxx”描述要具体权限怎么配最安全默认拒绝白名单逐条加敏感文件进 denyCLAUDE.md 写多长合适100 到 300 行精炼高信号memory 怎么清理要求模型列出相关记忆逐条确认删除团队怎么共享配置settings.json 项目级提交个人偏好走 localhooks 不触发怎么查检查 matcher 字符串、命令路径、超时设置多个项目配置会串吗memory 可能串settings 和 CLAUDE.md 按项目隔离6.3 给新手的上手顺序建议如果你刚接触这三套配置别一上来就全配。我的建议顺序是先写CLAUDE.md。这是投入产出比最高的写好项目说明模型立刻就能给出更贴合的建议。再配settings.json的权限。把敏感文件保护起来把常用命令加白名单安全边界先立住。最后用 memory。等前两者稳定了再用 memory 处理个人偏好和临时上下文。这个顺序的逻辑是先让模型“懂项目”再让工具“守规矩”最后让协作“更顺滑”。反过来先折腾 memory容易在项目理解还没到位时存一堆没用的偏好反而添乱。我在多个项目上按这个顺序走下来基本一两天就能把配置调顺之后就是偶尔微调。真正花时间的不是写配置本身而是想清楚哪些信息该放哪一层——这个判断力比记住字段名重要得多。