有人说 Claude Code 的配置很迷改了半天 settings.json下一句话还是听不懂项目背景。我一开始也是这个感觉直到把三个配置体系分开看之后整个思路就通了settings.json 管的是“状态”CLAUDE.md 管的是“知识”memory 管的是“记忆”。三者的职责完全不同但很多人把项目背景、模型参数、权限规则、临时提醒全部堆到 settings.json 里结果配置文件成了一个大杂烩改了不生效、生效了不对路、对了又不知道当初为什么这么写。这篇文章我想把这套体系完整拆开。说白了我的目标就一个让读完的人能对照自己的项目把配置放到正确的位置并且知道改完之后怎么验证到底生效没有。适合刚接触 Claude Code 的新手也适合已经在用但被配置搞烦的老手。1. 三种配置管三件不同的事别再把所有内容都塞进 settings.json先说结论Claude Code 的配置按“管什么”分成三大类分清楚了再动手比记住任何字段都重要。1.1 用开厨房来理解这三个配置各自的角色我把这三套配置比作一家餐厅的后厨settings.json 是灶台上的旋钮和仪表盘。火力大小、哪个灶能用、哪个报警要关、要不要自动关火都是这里控制。它管的是“工具本身的状态”。CLAUDE.md 是贴在墙上的操作卡和菜单说明。今天做的是川菜还是粤菜、哪种食材不能提前切、上菜顺序是什么写在这里。它管的是“Claude 需要知道的规则和背景”。memory 是老师傅脑子里的长期记忆。老客人的忌口、上次哪道菜盐放多了、供应商的电话这些不会写进菜单但每次开工都要用。它管的是“跨会话保留下来的信息”。这个类比不是随便打的。我在实际项目里见过太多配置问题本质都是三件事混在一起有人在 settings.json 里写项目技术栈有人把权限校验规则写进 CLAUDE.md还有人希望 Claude 记住的临时需求既没写进文件也没写进记忆就只能靠每次对话重新教一遍。1.2 一张表理清“遇到什么需求该动哪个文件”先把这个矩阵放在前面后面每个章节再展开讲具体配置。需求场景应该动的配置位置为什么换模型、改 API 接入、控制最大 tokensettings.json或环境变量这些是运行参数不属于上下文内容允许或禁止某个工具、命令、文件路径settings.json 的 permissions 字段权限属于安全边界必须在运行时校验告诉 Claude 项目结构、常用命令、编码规范项目根目录的 CLAUDE.md启动时自动注入上下文让 Claude 记住你的个人偏好、全局习惯~/.claude/CLAUDE.md每个会话都会加载相当于全局记忆记住某个任务的关键决策和当前状态memory写入 CLAUDE.md 或单独记忆文件跨会话保留而不是靠聊天记录临时性的“这次任务注意……”直接在对话里说临时约束写完就丢别污染长期配置1.3 常见的三个配置反面教材说点我实际踩过的问题。第一所有规则都往 settings.json 堆。settings.json 是 JSON 结构天生不适合写长文本更不适合写“项目模块划分”这种描述性内容。强行塞进去的结果就是改一个逗号导致整个配置失效而且 Claude 根本不会主动读取 JSON 里的说明性字段。第二CLAUDE.md 写成流水账。有人把整个项目的 README 复制进去几千行文字全部注入上下。每次对话前几十秒都耗在读文档上token 烧得飞快关键信息反而被淹没。CLAUDE.md 要的是“给 Claude 的驾驶提示”不是“项目存档”。第三memory 只用来存不清理。记忆文件越攒越多最后里面全是一年前的项目状态新会话里 Claude 拿着过期信息瞎猜。记忆和现实世界的归档一样不维护就变成污染源。2. settings.json权限、模型与钩子的总控逻辑settings.json 是三个配置体系里最“硬”的一个它直接决定 Claude Code 怎么启动、能干什么、不能干什么。这部分我从层级结构、常用字段和实际案例三个角度讲透。2.1 金字塔形的三层配置优先级settings.json 不是只有一个文件。官方实际支持三层用户级~/.claude/settings.json对这台机器上的所有项目生效。项目共享级项目目录下.claude/settings.json提交到 Git 里整个团队共享。项目本地级项目目录下.claude/settings.local.json不提交到 Git只影响当前机器。优先级从低到高是用户级 → 项目共享级 → 项目本地级。也就是说后面的会覆盖前面的同名配置。为什么要设计三层我理解是这么个逻辑用户级放“我这个人的偏好”比如我习惯用哪个模型、我不想让 Claude 访问哪个目录项目共享级放“这个项目统一的规定”比如只允许操作src目录、所有提交必须过测试项目本地级放“我这台机器独有的东西”比如本地调试用的 API 地址、我自己加的额外权限。这个分层最大的好处是换了电脑用户级配置自动跟着走换了项目项目级配置自动生效想临时调一下改本地级不动共享配置。我自己的习惯是凡是可能影响别人的条款都放共享级凡是涉及本地路径和个人调试的都放本地级。2.2 高频字段与它们各自的作用我列几个日常用得最多的字段每个都说明白为什么要这么配。{ model: claude-sonnet-4-5, permissions: { allow: [ Git, Bash(npm run lint), Read(src/**) ], deny: [ Bash(rm -rf *) ], ask: [ Write(.env) ] }, disableTools: [ WebSearch ], hooks: { PostToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \工具执行完成: $CLAUDE_TOOL_NAME\ } ] } ] }, env: { MY_CUSTOM_ENV: some-value } }model指定默认模型。这个字段决定了不传其他参数时走哪个模型。注意模型切换不一定非要在配置文件里写死命令行参数可以覆盖它这就是我前面说的“命令行 本地 项目 用户”。permissions这个最重要也最容易配错。它分allow、deny、ask三类。allow是直接放行deny是直接拒绝ask是每次弹确认。顺序上拒绝优先于允许也就是说同一个操作既在 allow 又在 deny最终是拒绝。这条我建议所有人都记住别到时候以为自己放行了结果被 deny 拦住了。disableTools彻底关闭某个工具相当于把灶台上的某个旋钮卸掉。比如你不想让 Claude 用浏览器搜索就把WebSearch关掉。这比用权限 deny 更彻底因为工具直接从候选列表消失。hooks在工具调用前后触发自定义命令。这个功能很强但也最容易失控。我在项目里主要用它做两件事一个是在跑测试完后自动把结果归档另一个是在文件修改后自动通知构建系统。写 hooks 时一定要把 shell 命令的转义和错误处理写好否则 hook 崩了Claude Code 自己也跟着崩。env给子进程注入环境变量。这里有个细节很多自动化脚本拿不到 shell 里的变量就是因为 Claude Code 启动的子进程并没有继承完整的 shell 环境通过env字段显式声明是最稳的做法。2.3 实际案例让 Claude Code 走自定义 API 端点很多人喜欢折腾模型接入想用兼容接口或本地模型服务。同时 Claude Code 官方支持通过环境变量指定 API 地址和令牌这是通用的标准做法。我看到很多人卡在这里大部分是因为不知道这些配置本质上就是两个环境变量和一条 URL 的事。典型配置方式是这样的先设置环境变量指向目标服务端点和令牌然后启动 Claude Code。示例Linux / macOS 下export ANTHROPIC_BASE_URLhttp://localhost:1234 export ANTHROPIC_AUTH_TOKEN你的令牌 claude如果你用的模型服务商有专门接入文档以文档为准但原理基本就是这个链路Claude Code 启动时会读ANTHROPIC_BASE_URL来决定请求发到哪读ANTHROPIC_AUTH_TOKEN来鉴权。Windows 用户用setx设置永久变量或者直接在终端里set临时变量同一个道理。我自己更倾向于在.claude/settings.local.json里配env字段而不是直接 export 到 shell。原因是项目本地级配置能跟着项目走换台电脑重新 clone 仓库后只要补一个本地文件就能恢复同样环境比每次手敲 export 靠谱。2.4 改了 settings.json 不生效多半是这三个原因第一文件和目录名写错。用户级要放在.claude目录下项目级也是.claude目录下不是.vscode不是config。我就犯过失落感极强的错误在项目根目录建了个settings.json改了半天Claude Code 根本看都不看。第二JSON 语法错误。settings.json 是严格的 JSON最后一项后面不能有逗号注释也会导致解析失败。很多编辑器你看着是彩色的实际上配置根本没加载。改完之后先用jq . settings.json验一下语法养成这个习惯能省很多时间。第三缓存和会话状态。Claude Code 启动时读配置你改完一个正在运行的会话它不会自动热更新。别浪费时间重试直接退出当前会话再开一个或者用/config之类的管理命令重新加载。3. CLAUDE.md启动即注入的项目说明书怎么写得有营养这一层和 settings.json 完全不同。settings.json 是给程序读的CLAUDE.md 是给 Claude 读的。它会在会话启动时自动注入上下文相当于 Claude 开工前先看的“驾舱检查单”。3.1 CLAUDE.md 从哪里加载加载多少Claude Code 会自动发现多级 CLAUDE.md用户级~/.claude/CLAUDE.md每次对话都会加载适合放你的通用工作习惯比如“写代码前先列计划”“不要编造命令参数”。项目级项目根目录的CLAUDE.md在这个目录启动会话时自动加载适合放项目背景、技术栈、目录结构、常用命令。子目录级项目子目录下的.claude/CLAUDE.md或CLAUDE.md当 Claude 的当前工作目录进入某个子目录时会按需加载适合放这个模块的专属规范。这里有一个特别容易忽略的点自动加载不等于一次全加载。用户级和项目级是常驻的子目录级则是在工作目录变化时才会被引入。所以不要把全局性的规范写到子目录文件里否则 Claude 在根目录干活时根本看不到。3.2 高价值 CLAUDE.md 的内容构成我写过很多版本的 CLAUDE.md踩过不少坑之后总结出五个必要区块顺序很重要项目一句话定位让 Claude 快速知道在做什么、面向谁。核心命令速查安装、测试、构建、lint、部署全部用代码块给出实际命令。目录结构与职责这个项目哪些目录是业务代码、哪些是生成文件、哪些不能动。编码规范与红线命名方式、错误处理习惯、禁止提交哪些文件。常见陷阱这个项目特有的坑比如“测试环境依赖本地 mock跑 CI 前必须启动 mock 服务”。我举个实际的例子一个 Node.js 后端项目的 CLAUDE.md 核心部分大概长这样# 项目订单服务 ## 项目定位 接收下单请求做库存校验然后发出订单事件。不处理支付。 ## 常用命令 - 安装依赖npm ci - 本地启动npm run dev - 跑测试npm test - 跑 lintnpm run lint ## 目录结构 - src/modules业务模块按订单域拆分 - src/shared公共工具改动需要评审 - scripts一次性脚本不进生产代码 ## 规范 - 新增接口必须写 JSDoc - 错误处理统一走 AppError不要直接 throw 裸字符串 - 不要修改 src/shared 下的文件除非获得明确授权 ## 陷阱 - 本地连的是 mock 数据库启动前先执行 npm run mock - 不要直接运行 scripts/migrate.js它只用于 CI 环境这个文件我不会写得超过 80 行。信息密度要足够高让 Claude 一眼扫完就能干活又不至于把上下文占满。3.3 注意上下文开销CLAUDE.md 不是越详细越好这是我最想强调的一点。CLAUDE.md 里的每个字都会占用模型上下文窗口。一次会话上下文窗口有限你塞进去 3000 行文档真正留给代码分析和输出的空间就少了。所以写 CLAUDE.md 的原则是“只保留稳定且必要的信息”。判断标准就一条这句话如果不告诉 Claude它会不会做出和项目事实不符的事会就写不会就不要写。比如“这个项目是对外销售产品的 B 端后台”这种细枝末节写了也行但价值不高而“所有数据库迁移命令必须在维护窗口执行”这种不写就可能出事。另外CLAUDE.md 里的示例代码尽量精简重点标出命令本身不要贴一长串输出日志。Claude 要的是命令和预期结果的关系不是日志收藏夹。3.4 和 settings.json 的联动关系CLAUDE.md 与 settings.json 不是互斥的是配合的。我的经验是这么分工CLAUDE.md 明确“应该怎么做”settings.json 明确“允不允许做”。举个例子CLAUDE.md 写了“测试命令用 npm test”settings.json 里就要给 Bash 工具放行npm test这个模式。不然 Claude 读完说明文档想帮忙跑测试直接被权限拦下来体验极度割裂。反过来也一样你在 settings.json 里 deny 了某个操作CLAUDE.md 就不要引导 Claude 去执行被禁止的操作否则每次都会被弹权限确认效率极低。我建议配置顺序是先写 CLAUDE.md 内容再照着内容去 settings.json 开放必要的权限。这样两个文件永远对齐。4. memory跨会话记忆的正确打开方式memory 是三个体系里最抽象的也是提升效率最明显的。没有记忆的时候每次新会话 Claude 都是“失忆状态”你好不容易教它的项目背景、决策逻辑、避免踩的坑全部归零。有了记忆它才能真的像团队老成员。4.1 memory 在 Claude Code 里的载体是什么很多人以为 memory 是一个独立数据库实际上在 Claude Code 里记忆的载体仍然是 CLAUDE.md 文件只是位置和内容类型不同。全局记忆~/.claude/CLAUDE.md保存你的跨项目偏好比如“我习惯代码缩进用两个空格”“请始终在改动前给出 diff 摘要”。项目记忆项目根目录的CLAUDE.md或子目录的.claude/CLAUDE.md保存这个项目的长期事实和决策记录。动态记忆对话过程中产生的临时信息通过工具调用写入对应文件变成跨会话可读取的静态内容。Claude Code 本身也提供了记忆管理的入口常见的是/memory相关命令或者直接对话里提出“把刚才这个约定记下来”。核心机制是一回事把动态对话中产生的知识点固化成静态文件内容。4.2 主动写 memory 的正确姿势很多人的问题是对话里谈了一大堆关掉会话全忘了从来没有想过让 Claude 自己把关键信息写下来。我的做法是在对话里明确下达记忆指令比如把这个约定记到项目记忆里前端组件库统一用项目内的 UI 组件不允许直接引用第三方组件库。然后 Claude 会调用文件写入工具更新 CLAUDE.md。下次新会话启动这条规则已经在上下文里了你不用再重复一遍。更完整的姿势是让 Claude 整理一段结构化的记忆内容而不是零散地堆句子。我给过一个指令模板把刚才讨论的结论整理成三到五条要点追加到项目根目录的 CLAUDE.md包含背景、规则、例外情况。这个模板的效果好是因为它同时要求了信息结构化和位置明确。Claude 不会把一大段谈话流水账写进文件而是提炼成有价值的条目。4.3 什么时候用全局记忆什么时候用项目记忆这是记忆体系里最容易搞混的。判断标准就一条这条信息是不是只在这个项目里成立只在这个项目成立 → 项目记忆。比如“订单模块的库存校验走 Redis 缓存”这就是项目专属的。在所有项目都成立 → 全局记忆。比如“回复时不要编造不存在的命令”“改动共享代码前先说明影响范围”。临时性、一次性 → 不写记忆。比如“这次任务先把支付模块的日志看完”这种放对话里就好写进记忆反而是污染。还有一个细节全局记忆不要太长。因为~/.claude/CLAUDE.md每个项目都会加载你写太多等于每个项目都背上沉重的上下文包袱。我自己的全局文件长期控制在 30 行以内只保留最高频、最通用的偏好。4.4 记忆的维护与清理定期删除过期信息记忆系统用久了就会遇到一种尴尬早期写的规则已经过时但 Claude 依然拿着它当圣旨。这个问题规避不了只能靠维护。我给自己定了一个简单的维护节奏每次完成一个重要迭代后检查项目记忆把已经落地的临时规定删除把仍然生效的决策保留。遇到 Claude 按旧规则做事而明显不对时第一个反应是去查记忆文件而不是骂它。全局记忆每两三个月清理一次原则是“如果这条规则这周没帮到我就删掉”。再补充一个小技巧记忆里的条目可以加一个“最近更新时间”前缀比如[2025-01] 生产环境禁止直接改数据库。这样 Claude 面对两条冲突规则时可以根据时间判断哪条更新你也能快速发现过期内容。5. “改了没生效”排查链路文件层级、生效顺序与验证手段这一节是我自己经历最多的一类问题。配置写完结果 Claude 跟没看到一样这时候千万不要反复乱改按一条固定的排查链路走几分钟就能定位。5.1 完整生效链路配置是从哪一步开始进场的先梳理一下一个典型会话的配置加载顺序这对排查很有帮助用户级 settings.json 加载设定基础运行参数。项目级 settings.local.json 和 settings.json 按优先级覆盖用户级配置。用户级~/.claude/CLAUDE.md注入上下文。项目根目录 CLAUDE.md 注入上下文。当前工作目录对应的子目录 CLAUDE.md 按需加载。对话开始后Claude 按 permissions 规则检查每一个工具调用。所以如果某个配置没生效先判断它属于哪个环节。权限问题大概率在第 1、2、6 步之间内容问题Claude 不知道某条规范大概率在第 3、4、5 步出问题。5.2 我的五分钟排查顺序我把排查顺序固定成了一套动作你可以直接抄第一步确认文件位置正确。用户级必须在~/.claude/settings.json项目级必须在.claude/settings.json或.claude/settings.local.jsonCLAUDE.md 必须在项目根目录或对应子目录的.claude/CLAUDE.md。目录名错一个.就不认。第二步确认语法正确。settings.json 用jq . settings.json验证CLAUDE.md 用 Markdown 预览看一下标题层级是不是乱了。JSON 解析失败时Claude Code 可能直接采用默认配置你改什么都没用。第三步确认优先级没有覆盖。比如你项目级 settings.json 里明确 allow 了某个命令但用户级 settings.json 里 deny 了它最终结果是 deny。排查时打开两个文件对照一遍别只看其中一个。第四步查看运行时的实际配置。Claude Code 提供了一些斜杠命令来查看当前状态。最常见的做法是启动会话后用/config查看当前配置或使用/status检查当前环境。如果命令显示的值和你改的值不一致说明某个上层配置把你覆盖了。第五步重启会话验证。配置是在启动时读取的改完不重启等于没改。这个动作看似简单但绝大多数“改了没生效”都是败在这一步。5.3 一个真实案例权限和记忆打架我曾经在一个项目里遇到这样的问题CLAUDE.md 里写了“可以用脚本生成迁移文件”settings.json 里也 allow 了对应的Bash(npm run generate:migration)。但 Claude 每次执行这个命令都被弹窗拦下来而且过一段时间又被 deny 了。排查后发现问题出在记忆上。项目记忆文件里有一条很早就留下的规则数据库迁移必须人工执行不允许自动跑迁移命令。这条规则来自项目早期一个很谨慎的阶段后来整个流程改了CLAUDE.md 也更新了但那条旧记忆一直躺在文件底部。Claude 按上下文聚合规则时把旧记忆当成更权威的信息所以权限上虽然 allow行为上却被记忆里的旧指令挡住了。这件事给我的教训就是settings.json 和 CLAUDE.md 只决定“能不能”记忆却可以扭曲“该不该”。记忆比配置更难排查因为它不会报错只会让 Claude 的行为悄悄偏离预期。所以当你觉得配置明明没问题但行为不对时一定要去翻记忆文件。5.4 我推荐的初始模板和成长路径最后分享一套我现在固定用的初始配置组合适合大多数从零开始的项目第一层用户级配置只做两件事设置默认模型写一份 20 行以内的全局 CLAUDE.md内容限定在通用编码偏好和沟通习惯。第二层项目根目录放一个 CLAUDE.md包含 3.2 节里说的五个区块但每个区块先写最少的内容后面用的时候再补。第三层.claude/settings.json只放三条权限规则放行项目核心命令拒绝危险命令对敏感文件读写弹确认。其他一律不配等实际需要再加。这个模板的精髓是“最小可用”。配置不是越多越好而是每一条都能说出它存在的理由。随着项目推进你会慢慢往里加 hooks、加 env、加细化权限但每次加之前都问自己一句这条配置如果不加会发生什么如果答案是“不会怎样”就不加。Claude Code 配置体系的精髓也就一句话settings.json 负责边界CLAUDE.md 负责背景memory 负责延续。边界守住安全背景提升理解延续减少重复三件事各司其职才能真正跑得又稳又省心。这也是我在多个项目里反复调整后觉得最值得分享的一套思路。