1. 配置体系全景：三个文件各管哪一块
接触过 Claude Code 的人十有八九都会经历这样一个阶段：安装跑通之后，立刻开始折腾配置。网上教程零零散散，今天看到有人改 settings.json 解决了权限弹窗，明天看到有人说 CLAUDE.md 能让代理更懂项目，后天又听说 memory 可以实现跨会话记忆。三样东西搅在一起，很容易把配置改成一锅粥。
我自己的经历也差不多。最早我把所有想让它记住的东西全往 CLAUDE.md 里塞，项目迭代几轮之后，这个文件越来越臃肿，每次会话开始都要读一大段背景信息，真正关键的操作指令反而被稀释掉。后来踩了几次坑才慢慢摸清楚：这三个文件解决的是完全不同层面的问题，理解边界之后，配置才谈得上是一个"体系"。
1.1 三者的核心边界：程序配置、项目指令、知识沉淀
先说结论。settings.json 管的是"Claude Code 这个程序怎么运行"，CLAUDE.md 管的是"Claude 进入某个代码库时该懂什么规矩"，memory 管的是"跨会话要记住什么信息"。三者生命周期不同、维护方式不同、生效机制也不同。
我用一张表把这个边界摊开来看：
| 配置文件 | 本质 | 谁来维护 | 更新频率 | 生命周期 |
|---|---|---|---|---|
| settings.json | 客户端配置 | 使用者 | 低频，按需调整 | 全局或单个项目 |
| CLAUDE.md | 项目指令说明 | 人类编写 | 随项目演化定期更新 | 跟随项目长期有效 |
| memory 记忆文件 | 动态知识沉淀 | Claude 与人类共同维护 | 高频，随会话积累 | 跨会话保留，需定期清理 |
打个生活化的比方。settings.json 类似你手机里的"系统设置"，决定的是工具本身的行为习惯；CLAUDE.md 类似新员工入职时拿到的那本《团队手册》，写清楚了这边的代码风格、发布流程、哪些雷区不能踩；memory 则是你工位上的笔记本，今天记一笔"这个服务用 8080 端口"，明天补一句"客户那边要求走内网域名"，随着工作推进不断增删。
搞混三者的典型后果是什么？把动态知识写进 CLAUDE.md，会导致这个文件频繁变动，每次改动都要提交、review，效率极低；把稳定规则写进 memory，会导致规则在各种上下文里时隐时现，今天有效明天可能就丢了；而试图在 settings.json 里写业务约定，那更是找错了地方。
1.2 加载顺序与生效时机：为什么"我明明配了却不生效"
三个文件的加载机制差异很大，这也是很多人困惑的源头。settings.json 在会话启动时读取，修改后通常新的会话才生效；CLAUDE.md 分全局、项目、子目录三层按需加载；memory 则是在会话过程中按相关性动态载入，并且可能在对话中被实时写入。
具体来说，settings.json 有两个层级：全局配置在~/.claude/settings.json，项目配置在项目根目录的.claude/settings.json。同名配置项项目级会覆盖全局级，但覆盖粒度是"按配置项合并"，不是整个文件覆盖。CLAUDE.md 的加载顺序是：全局~/.claude/CLAUDE.md最先载入，随后是项目根目录的CLAUDE.md，当 Claude 实际访问某个子目录时，才加载该目录下的CLAUDE.md。memory 一般存放在~/.claude/memory/和项目目录的.claude/memory/下，启动会话或进入相关任务时，Claude 会根据相关性挑选记忆文件读取。
这里有一条可以解释 80% 配置问题的经验：先判断你改的那个文件，属于哪个加载层级，再判断它是否在该生效的时机被读取。很多人改了项目级 settings.json 却发现所有项目都受影响，是因为全局配置里同样的字段还留着旧值；也有人把 CLAUDE.md 放进子目录，却在项目根目录下对话，自然读不到。
2. settings.json：项目环境的"出厂设置"
2.1 配置位置与覆盖规则
settings.json 是 Claude Code 的客户端配置文件，承担的是类似 IDE 里 Preferences 的角色。最需要注意的就是它的两个存放位置以及它们的关系：
- 全局配置：
~/.claude/settings.json，对当前用户的所有项目生效。 - 项目配置：
.claude/settings.json（项目根目录下），只对当前项目生效。
按配置项合并的意思是：项目配置里写了permissions，全局配置里的permissions不会整个被替换，而是同名子项以项目为准，项目没写的子项仍继承全局。这种做法比"全量覆盖"灵活得多，但副作用就是排查问题时容易看漏。我建议在改动项目级配置之前，先打开全局配置对照一遍，避免出现两边互相打架的情况。
值得一提的还有那些通过命令行工具切换第三方 API 的使用场景。无论是本地模型还是第三方中转服务，本质上都是在修改最终传给客户端的模型标识和环境变量，这些能力最终都会落到 settings.json 的env字段上。理解了这个文件的结构，就能理解为什么那些切换工具能做到"一次切换、全局生效"。
2.2 权限控制：先学会划边界，再谈效率
权限配置是 settings.json 里价值最高、也最需要谨慎的部分。Claude Code 默认会对危险操作弹出确认，这本来是保护机制，但如果每次跑个git status都要确认一次，体验确实很糟。合理的做法不是把权限全放开，而是让安全的操作静默通过，把真正危险的操作挡在门外。
下面是我个人比较推荐的配置结构：
{ "permissions": { "allow": [ "Read", "Edit", "Grep", "Glob", "Bash(bash:git status)", "Bash(bash:git diff)", "Bash(bash:git log)", "WebFetch(domain:docs.anthropic.com)" ], "deny": [ "Write", "Bash(bash:rm -rf /*)", "Bash(bash:git push --force)" ], "ask": [ "Bash(bash:sudo *)", "Bash(bash:curl *)" ] } }这里的逻辑是三层：allow里的工具或命令模式直接放行，deny里的一票否决，ask里的仍然需要人工确认。我特别想强调的是 Bash 的写法——最好精确到命令前缀。你可以允许git status，但不要去允许一个裸的Bash，否则等于把终端完全交给了模型。等你哪天看到它自作主张执行了一条git push --force，再想收紧就晚了。
另一个实用技巧是，会话中可以用/permissions命令查看当前生效的权限配置。排查"某个工具怎么突然不能用"的时候，先看这里，比瞎猜快得多。
2.3 模型选择、环境变量与钩子
settings.json 里除了权限，还有三个高频配置项：模型指定、环境变量注入、生命周期钩子。下面是一份完整的示例：
{ "model": "claude-sonnet-4-20250514", "env": { "ANTHROPIC_MODEL": "claude-sonnet-4-20250514", "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-20250514" }, "hooks": { "PreToolUse": [ { "matcher": "Bash", "command": "echo \"即将执行 Bash 命令\" >> /tmp/claude_hook.log" } ], "PostToolUse": [ { "matcher": "Edit", "command": "echo \"文件已被修改\"" } ] } }先看model字段。它的作用是固定每次会话默认使用哪个模型，避免在长对话中模型意外切换。配合ANTHROPIC_MODEL和ANTHROPIC_SMALL_FAST_MODEL这对环境变量，可以同时控制主模型和轻量模型（用于标题生成、短任务等）的选型。如果你在本地部署了模型服务，或者接了第三方兼容接口，一般也是通过这里的环境变量来路由，原理是一样的。
再看 hooks 钩子。它允许你在 Claude 调用工具的前后插入自定义脚本，常见的用途包括：把每次工具调用写入审计日志、拦截特定命令并追加参数、任务结束时发送桌面通知。我建议第一次使用 hooks 时先打印日志，确认触发时机和参数格式，再逐步加固逻辑。注意：hook 脚本执行失败不应阻断主流程，所以脚本里要做好容错，别因为一个 echo 命令写错路径导致整个会话报错。
2.4 修改配置的生效与调试习惯
settings.json 修改后，一般不需要重启 Claude Code 进程，新的会话就会按新配置执行，但当前正在进行的会话通常会沿用启动时的配置。所以调试配置时，建议开一个新的会话验证。
我踩过最蠢的一个坑是：手一抖把 JSON 里加了注释，然后死活不生效。注意，settings.json 是标准 JSON，不是 JSONC，不支持注释，写//会导致解析失败。另一个高频问题是引号和中英文标点混用，尤其是在中文输入法下编辑文件。建议改完配置后用编辑器自带的 JSON 格式化功能校验一遍，再确认无红错。
如果你需要跨机器同步配置，我建议把项目级的.claude/settings.json纳入 Git 追踪。全局配置则不建议提交到代码仓库，它通常包含本机特有的路径和环境变量，属于个人环境的一部分。
3. CLAUDE.md：写给 Claude 看的项目说明书
3.1 没有 CLAUDE.md 时，Claude 有多"没谱"
很多人第一次用 Claude Code 时，感觉它"能力很强但不太懂这个项目"。这很正常——它做的是通用代码模型，而每个项目都有自己的历史包袱、约定和潜规则。举个例子：在一个 pnpm monorepo 里，如果你不告诉它应该用 pnpm，它可能默认就用 npm 安装依赖，然后跑出各种版本冲突；在一个"发布前必须跑 lint"的项目里，你不告诉它这条规矩，它可能改完代码直接提交，把 CI 弄得一片红。
CLAUDE.md 就是用来补上这些信息差的。它本质上是给 Claude 读的 Markdown 说明书，会在会话启动时自动加载到上下文里，告诉它这个项目是什么、怎么开发、怎么测试、有哪些禁忌。用一份好的 CLAUDE.md，Claude 的行为模式会立刻从"通用编程助手"切换成"熟悉这个仓库的协作者"。
3.2 最值得写进 CLAUDE.md 的四类内容
不是所有内容都值得写。写得太多、太碎，反而会让模型抓不住重点。我归纳下来，四类内容的性价比最高。
第一类是项目概览与架构，两三句话讲清楚这个仓库是做什么的、核心模块在哪、数据流大概长什么样。第二类是常用命令，把启动、测试、构建、代码生成这些命令写全，模型就不需要去猜。第三类是代码风格与约定，比如命名规范、组件组织方式、是否强制使用 TypeScript 严格模式。第四类是已知的坑和禁止事项，这部分的经验价值极高，比如"这个模块不要动，重构计划还没定"。
给你看一个实际项目的 CLAUDE.md 骨架：
# 项目说明 电商后台管理系统，前端 React + TypeScript + Vite，后端 Node.js 服务在 server/ 目录。 ## 常用命令 - 安装依赖：pnpm install - 启动前端：pnpm dev - 运行测试：pnpm test - 构建生产包：pnpm build ## 代码约定 - 组件统一使用函数式组件 + hooks - 新代码必须通过 TypeScript 严格检查 - 状态管理使用 zustand，不要引入新的全局状态库 ## 已知问题 - legacy/ 目录是旧代码，不要迁移，后续会整体移除 - 修改数据库相关代码前，先和 @dba 确认变更脚本关键是要简洁。每个条目都应该是"读了就能照做"的操作级描述，而不是口号式的自我要求。
3.3 全局、项目、子目录：三层文件的加载逻辑
CLAUDE.md 不是只能有一份。它支持全局、项目根目录、子目录三个层级，加载逻辑比较灵活：
~/.claude/CLAUDE.md：全局规则，适合放你的个人通用偏好，比如"所有代码用中文写注释""提交信息必须用英文"。- 项目根目录
CLAUDE.md：项目级规则，上面说的四类内容一般放在这里。 - 子目录
CLAUDE.md：当 Claude 实际操作到某个子目录时，该目录下的 CLAUDE.md 才会被加载。适合放"此目录专属"的约束，比如某个服务子目录有自己的部署流程。
我建议保持全局文件极简，因为全局内容会在每个会话中都占一份上下文。全局写得太多，相当于每个项目都背着一大段无关背景，既浪费上下文窗口，也可能干扰项目特定指令。子目录文件也不要滥用，只有在那个目录确实有独立规则时才值得单独维护一份。
3.4 写了却不生效？多半是这五个原因
用户最常见的反馈是"我写了 CLAUDE.md，但它好像没读"。排查下来，原因基本集中在下面几个：
第一，文件名或路径不对。注意是CLAUDE.md，全部大写，放在项目根目录，不少人建成了claude.md或者放进了docs/目录。第二，内容跑题。CLAUDE.md 是给模型读的，不要在上面写给自己看的 TODO。第三，和会话指令冲突。对话过程中明确下达的指令，优先级高于文件里的静态规则，所以你以为"文件没生效"，其实是会话上下文压过了它。第四，太冗长。几百行的 CLAUDE.md 里有效信息被淹没，模型抓不住重点。第五，你还没有让 Claude 主动读取。新版工具一般启动时按需加载，但个别版本或场景下，可能需要在对话中提示一下。
如果你不确定怎么写，最省事的做法是直接在项目根目录运行初始化命令，让 Claude 自己读一遍代码库，生成一份初始 CLAUDE.md，你再在它基础上增删。比自己从零写快得多，而且它生成的细节往往更贴合实际代码。
4. memory：跨会话记忆的工作机制与维护
4.1 memory 到底在存什么
memory 解决的是 "上次聊过的内容，下次开场就忘" 的问题。它的价值不在于"记住所有对话"，而在于把对话中产生的、对未来有复用价值的知识沉淀下来。
适合放进 memory 的典型内容包括：用户的操作偏好（"发布前必须先跑迁移脚本"）、项目事实（"生产数据库连接串放在 .env.production"）、踩坑结论（"这个 SDK 在 v2 之后弃用了旧的初始化方法"）、以及团队约定（"提交信息必须遵循 conventional commits 规范"）。这些信息的特点是：它们在对话过程中被明确或隐含地表达出来，且在后续任务中可能反复使用。
memory 存放位置和前面的配置类似，也分全局与项目两层：~/.claude/memory/存个人通用记忆，.claude/memory/存项目相关记忆。每个记忆通常是一个独立的 Markdown 文件，文件名就是这个记忆的主题标签。保持"一个文件一个主题"的习惯很重要，后续查找、清理都方便。
4.2 一条记忆从对话到落盘的完整路径
很多人的误区是，对话里说了一句"记住这个"，就觉得万事大吉。实际上，这句话要真正生效，需要经历一次"写入-读取"的闭环。
写入环节是这样的：你在对话中表达某个偏好或事实，Claude 判断它值得跨会话保留，就会把内容整理后写入对应的 memory 文件。比如你说"以后部署都用 npm run deploy，不要用 npm start"，它很可能会新增或更新一个deployment.md的记忆文件。读取环节则发生在新的会话里：启动时或进入相关任务时，Claude 根据当前任务主题，从 memory 目录中挑出相关性高的文件加载到上下文。
你可以用/memory命令查看当前已有的记忆文件，也可以直接用编辑器打开那个 md 文件手动修改。验证记忆是否真的写入的唯一方式，就是去看文件系统里有没有对应的 md 文件，而不是看它在当前对话中是否点头。我在使用早期就吃过亏，以为口头确认过就万事大吉，结果换了个会话，它照旧忘得干干净净。
4.3 memory 与 CLAUDE.md 的边界：什么该搬进记忆库
和 CLAUDE.md 相比，memory 最大的特点是动态。判断一条信息该放哪，我有一条很实用的标准：这条信息的有效期是"项目生命周期"还是"当下这个阶段"？
稳定不变的规则，比如"这个仓库必须用 pnpm""禁止修改 legacy 目录"，放 CLAUDE.md，因为它长期有效、由人维护、随项目代码一起评审。而大概率会变的动态信息，比如"这台测试服务器的部署脚本路径""客户的 UAT 环境账号用 xx 格式"，放 memory，因为它们在运行过程中产生，且更新频繁，不值得每次改 CLAUDE.md 都要走一次提交流程。
如果你发现自己频繁修改 CLAUDE.md 里的某一段，每次都是因为同样的"临时信息"变了，那说明这条信息应该挪到 memory 里去。反过来，如果 memory 里有一条规则长期不变、每次都要用，那也该升级进 CLAUDE.md，减少动态加载的不确定性。
4.4 记忆膨胀：从资产变成负担
memory 的文件多了以后，会带来一个隐蔽的问题。会话启动时，Claude 按相关性挑记忆文件加载，如果 memory 目录里塞满了过时、重复甚至互相矛盾的记录，它可能会读到错误的信息。更麻烦的是，你以为某条旧记忆已经被覆盖了，实际上旧文件还在，新的文件也写着相反的结论，模型两头为难。
我的建议是开启一个固定节奏：每隔一两周打开/memory看一遍，删掉明确过时的文件，合并重复的主题。你甚至可以直接在对话里让 Claude 帮你清理过期记忆，给它一个淘汰标准，比如"所有 2024 年的部署记录都归档掉"。不要担心删错，memory 是动态的，删掉的只要需要随时能重建。真正危险的反而是保留了一堆看似无害、实则过时的知识，它在悄悄影响每一个新的会话。
另外一个我认为很重要的提醒：敏感信息放 memory 要格外慎重。memory 文件会随着会话被反复加载，某种意义上它比普通配置文件的暴露面更大。涉及密钥、生产环境地址这类敏感信息，优先放到 gitignored 的环境变量文件里，而不是写进记忆库。
5. 三套配置组合实战：一套可复制的落地样例
5.1 一个真实项目的完整配置模板
说了这么多，最后给一套可以抄的作业。假设一个 Node.js + React 技术栈的中后台项目，我会这样组织三套配置。
首先是项目级.claude/settings.json：
{ "permissions": { "allow": [ "Read", "Edit", "Grep", "Glob", "Bash(bash:git status)", "Bash(bash:git diff)", "Bash(bash:pnpm run *)" ], "deny": [ "Write", "Bash(bash:git push --force)", "Bash(bash:rm -rf /)" ] }, "model": "claude-sonnet-4-20250514", "hooks": { "PreToolUse": [ { "matcher": "Bash", "command": "echo \"$(date) $CLAUDE_TOOL_INPUT\" >> /tmp/claude_bash.log" } ] } }然后是项目根目录的CLAUDE.md：
# 中后台管理系统 React + TypeScript + Vite 前端，Node.js 服务在 server/ 目录。 ## 常用命令 - 安装依赖：pnpm install - 启动前端：pnpm dev - 启动服务端：pnpm dev:server - 执行测试：pnpm test ## 约定 - 所有新代码必须通过 TypeScript 严格检查 - API 调用统一走 src/api/ 下的封装，禁止直接 fetch - 环境变量文件为 .env.local，不要提交 ## 注意事项 - legacy/ 目录代码不迁移，等待整体替换 - 修改 server/ 下的数据库逻辑前，需要先查看 migrations/ 目录的迁移记录最后是 memory 目录里可能出现的两个记忆文件：
# 部署 - UAT 环境部署：npm run deploy:uat - 生产部署需要先确认 .env.production 中的版本号 - 上次部署踩坑：迁移脚本必须先于构建执行# 用户偏好 - 代码注释使用中文 - 提交信息遵循 conventional commits 格式 - 重构时优先小步提交，不要一次性大改你会发现三套配置各司其职：settings.json 管程序行为，CLAUDE.md 管项目规则，memory 管动态知识。它们组合在一起，才是完整的配置体系。
5.2 配置不生效的排查思路：按顺序走完这三步
最后分享一下配置出问题时的排查顺序。别瞎猜，按这个链路走，绝大多数问题五分钟内能定位。
第一步，确认配置被正确读取。先看会话状态，确认当前加载的是哪个层级的 settings.json，以及 CLAUDE.md 有没有被载入。如果项目配置没生效，优先怀疑放错位置或 JSON 解析失败。
第二步，判断是不是权限先拦了。功能没按预期执行时，不一定是配置错，很可能是权限模块把某个工具调用静默拦截或转成了确认。用/permissions查看当前会话的实际权限，再对照你配置文件里的 allow/deny。
第三步，区分规则类问题和知识类问题。如果规则时灵时不灵，查 CLAUDE.md 是否被子目录文件覆盖、是否被会话指令覆盖；如果是对某个事实的记忆时有时无，直接打开 memory 目录的文件，看它到底在不在、内容是否过时。把问题归类到"程序配置、项目指令、动态知识"这三个桶里，你自然知道该查哪个文件。
5.3 我个人的几条配置心得
用到现在，我对这套配置体系最深的体会是：不要追求完美配置，要追求可维护配置。权限宁可先紧后松，一开始全放开省事，等出了事故再收紧，留下的烂摊子反而更多。CLAUDE.md 不需要一次写完，跟着项目演进，每隔一段时间让它自己读一遍代码库，看看有没有新的约定要补进去。memory 的关键不是"记得越多越好"，而是"可清理"，隔段时间就删一批过时文件。
还有一个容易被忽略的习惯：把项目级配置都纳入版本控制。.claude/settings.json和CLAUDE.md提交到 Git 里，好处是所有人共享一套规则，改了什么一目了然，出问题还能回溯。memory 文件则可以看情况决定是否提交——团队项目建议提交公共约定部分，个人偏好部分留在本地就好。
这套配置体系说复杂也复杂，说简单也简单，归根结底就是一件事：让 Claude 在正确的时机，读到正确的信息。边界划清楚，问题就已经解决了一半。
