Claude Code 三套配置体系：settings.json、CLAUDE.md 与 memory 分层详解

1. 三套配置体系到底在管什么

很多人第一次接触 Claude Code，装完之后发现能跑起来就以为万事大吉了，结果用着用着就发现不对劲：每次对话都要重新交代项目背景，团队里每个人的行为风格不一样，换个项目又得从头调教。这些问题的根源，其实都指向同一件事——你还没搞清楚 Claude Code 的配置体系是怎么分层的。

Claude Code 的配置体系可以拆成三个独立但互相配合的层面：settings.json管的是工具层的行为参数，CLAUDE.md管的是项目层的上下文约定，memory管的是跨会话的持久化记忆。这三者不是替代关系，而是各管一摊、层层叠加的关系。你可以把它们想象成一家公司的管理制度：settings.json 是员工手册里的硬性规定（比如几点打卡、报销额度上限），CLAUDE.md 是部门内部的工作规范（比如代码提交格式、review 流程），memory 则是你个人的工作笔记（比如上次那个客户偏好什么沟通方式）。

我见过太多人把这三个东西混在一起用，把所有配置都往 CLAUDE.md 里塞，结果文件膨胀到几百行，每次对话都要消耗大量 token 去读取，既浪费成本又拖慢响应速度。还有人完全不用 memory，每次开新会话都像失忆一样重新解释一遍需求。这些坑我在实际项目里都踩过，所以这篇文章我会把三套体系的边界、写法、优先级和实战技巧全部拆开讲清楚。

这篇文章适合已经装好 Claude Code、能跑通基本对话、但还没建立起系统化配置思路的开发者。如果你还在纠结安装问题，那可以先跳过这篇，等环境跑通了再回来看。下面我会从设计思路开始，逐层拆解每一套配置的核心机制和实操方法。

2. 三套配置体系的设计逻辑与分层思路

2.1 为什么要分三层而不是一个大配置文件

这个问题的答案藏在 Claude Code 的运行机制里。每次你发起一次对话，Claude Code 会把当前生效的配置内容拼接到系统提示词里，然后一起发给模型。这意味着配置文件的体积直接影响到每次请求的 token 消耗。如果你把所有东西都写在一个文件里，那不管当前任务是否需要这些信息，它们都会被加载进去。

分层设计的核心目的就是按需加载、按场景生效。settings.json 里的配置是结构化的键值对，体积小、解析快，适合放那些不需要每次变动的硬性参数。CLAUDE.md 是自然语言描述的项目约定，它只在特定项目目录下才会被读取，换个目录就不生效了。memory 则是跨项目的持久化存储，它记录的是你个人的偏好和历史决策，不管你切换到哪个项目都能调用。

另一个关键考量是协作场景。settings.json 和 CLAUDE.md 通常是跟着项目仓库走的，团队里每个人拉下代码后都能获得一致的配置。而 memory 是跟人走的，每个人可以根据自己的习惯积累不同的记忆内容。这种分离让团队协作和个人定制互不干扰。

2.2 三者的加载优先级与覆盖关系

实际运行中，这三套配置的加载顺序和优先级是这样的：

当三者出现冲突时，settings.json 里的硬性参数会覆盖其他层的设置。比如你在 settings.json 里指定了模型版本，那 CLAUDE.md 里就算写了"请用另一个模型"也不会生效。CLAUDE.md 的约定会覆盖 memory 里的通用偏好，因为项目级的规则比个人习惯更具体。

理解这个优先级很重要，它决定了你遇到配置不生效的问题时该往哪个方向排查。我后面会专门讲排查方法，这里你先记住一个原则：越具体的配置优先级越高，越靠近当前任务的配置越优先。

2.3 不同规模项目的配置策略

不是所有项目都需要三套配置全上。根据项目规模和团队情况，我建议这样分配精力：

• 个人小项目：只需要一个精简的 CLAUDE.md，写清楚项目结构和技术栈就行。settings.json 用默认值，memory 靠日常积累自然生长。
• 团队中型项目：CLAUDE.md 要写详细，包括代码规范、目录约定、常用命令。settings.json 需要统一团队的工具行为，比如格式化规则、权限设置。
• 大型多模块项目：三套都要认真配置。settings.json 管全局工具行为，每个子模块可以有独立的 CLAUDE.md，memory 用来记录跨模块的架构决策和历史遗留问题的处理方式。

这个策略的核心逻辑是：配置的复杂度应该和项目的复杂度匹配。过度配置和配置不足都会带来问题，前者浪费维护精力，后者导致行为不一致。

3. settings.json 核心配置项与实操要点

3.1 settings.json 的文件位置与生效范围

settings.json 有两个可能的位置，生效范围不同。全局配置放在用户主目录下的.claude文件夹里，对所有项目生效。项目级配置放在项目根目录的.claude文件夹里，只对当前项目生效。如果两个位置都有文件，项目级的会覆盖全局的同名配置项。

我通常的做法是：全局配置放那些所有项目都通用的设置，比如默认模型、主题、快捷键；项目级配置放这个项目特有的东西，比如特定的权限规则、环境变量。这样切换项目时不会互相干扰。

创建项目级配置的步骤很简单：

# 在项目根目录下创建配置文件夹 mkdir -p .claude # 创建配置文件 touch .claude/settings.json

然后往里面写 JSON 内容就行。注意这个文件必须是合法的 JSON 格式，多一个逗号都会导致解析失败，Claude Code 会直接忽略整个文件。我踩过这个坑，当时排查了半天才发现是末尾多了个逗号。

3.2 常用配置项逐条拆解

settings.json 支持的配置项不少，但日常高频使用的就那么几个。我挑最实用的几个展开讲：

模型选择：通过model字段指定默认使用的模型。这个配置决定了每次对话请求发往哪个模型，直接影响响应质量和速度。如果你有多个模型可选，可以根据任务类型切换。

权限控制：permissions字段用来控制 Claude Code 能执行哪些操作。比如你可以限制它只能读取文件不能写入，或者只允许在特定目录下操作。这个在团队协作里特别重要，防止误操作影响到不该动的文件。

环境变量：env字段可以注入环境变量，这些变量在 Claude Code 执行命令时生效。比如你可以在这里设置 API 的基础地址、超时时间等。

工具开关：tools字段控制哪些内置工具可用。如果你不希望 Claude Code 执行某些类型的操作，可以在这里禁用对应的工具。

主题与界面：theme等字段控制终端界面的显示效果。这个纯属个人偏好，不影响功能。

下面是一个我常用的项目级配置示例：

{ "model": "claude-sonnet-4-20250514", "permissions": { "allow": [ "Read", "Glob", "Grep" ], "deny": [ "Bash(rm -rf *)", "Write(/etc/*)" ] }, "env": { "NODE_ENV": "development", "LOG_LEVEL": "debug" } }

这个配置的意思是：默认用 sonnet 模型，允许读取和搜索文件，禁止执行危险的删除命令和写入系统目录，同时注入两个环境变量。

3.3 配置项的常见错误与避坑指南

在实际使用中，settings.json 最容易出问题的地方有三个：

JSON 格式错误。这是最高频的问题，表现是配置完全不生效，但也不报错。排查方法是把文件内容复制到任意 JSON 校验工具里检查一遍。我建议写完配置后养成习惯，用python -m json.tool .claude/settings.json验证一下格式。

路径写法不一致。权限规则里的路径支持通配符，但写法有讲究。/etc/*和etc/*含义不同，前者是绝对路径，后者是相对路径。如果你不确定当前工作目录是什么，建议统一用绝对路径，避免歧义。

配置项名称拼写错误。Claude Code 对未知的配置项不会报错，而是静默忽略。这意味着你拼错一个字段名，可能完全察觉不到。我的经验是每次添加新配置后，用/config命令查看当前生效的配置，确认新项已经加载。

注意：修改 settings.json 后需要重启 Claude Code 会话才能生效，热重载不支持。这一点和 CLAUDE.md 不同，后者是每次对话时动态读取的。

4. CLAUDE.md 的写法与项目上下文管理

4.1 CLAUDE.md 应该写什么、不该写什么

CLAUDE.md 的本质是一份给 AI 看的项目说明书。它的作用是让 Claude Code 在进入你的项目时，快速理解这个项目的结构、技术栈、约定和注意事项。写得好，AI 就像团队里待了半年的老员工；写不好，它就是个每天新入职的实习生。

该写的内容包括：项目的一句话定位、技术栈和版本、目录结构说明、代码风格约定、常用命令、已知的坑和特殊处理。不该写的内容包括：具体的业务逻辑细节（这些应该看代码）、临时的调试信息、和项目无关的个人偏好。

我见过有人把 CLAUDE.md 写成了一本开发手册，洋洋洒洒上千行。结果每次对话都要加载这么多内容，token 消耗巨大，而且真正关键的信息反而被淹没了。我的建议是控制在 100 行以内，只写那些"如果不知道就会做错"的信息。

4.2 一份高效 CLAUDE.md 的结构模板

经过多个项目的迭代，我总结出一个比较通用的结构：

# 项目名称 一句话说明这个项目是做什么的。 ## 技术栈 - 语言：TypeScript 5.x - 框架：Next.js 14 - 数据库：PostgreSQL 16 - 包管理：pnpm ## 目录结构 - src/app：页面路由 - src/components：通用组件 - src/lib：工具函数 - src/server：服务端逻辑 ## 代码约定 - 组件文件用 PascalCase 命名 - 工具函数用 camelCase 命名 - 所有导出必须有类型标注 - 提交信息遵循 Conventional Commits ## 常用命令 - pnpm dev：启动开发服务器 - pnpm test：运行测试 - pnpm lint：代码检查 ## 注意事项 - 不要直接修改 generated 目录下的文件 - 数据库迁移必须通过 migration 脚本 - 环境变量在 .env.local 中配置

这个模板的好处是结构清晰，AI 能快速定位到需要的信息。每个部分都只写关键内容，不展开细节。

4.3 多层级 CLAUDE.md 的组织方式

大型项目里，单个 CLAUDE.md 往往不够用。Claude Code 支持在子目录里放置额外的 CLAUDE.md，进入对应目录时会自动加载。这个机制让你可以按模块拆分上下文。

比如一个 monorepo 项目可以这样组织：

• 根目录的 CLAUDE.md：写全局的技术栈、包管理方式、提交规范
• packages/web/CLAUDE.md：写前端特有的约定，比如组件规范、状态管理方式
• packages/api/CLAUDE.md：写后端特有的约定，比如接口设计规范、数据库访问方式
• packages/shared/CLAUDE.md：写共享库的使用说明

这样当你在 web 目录下工作时，加载的是根目录加 web 目录的配置，不会把 api 的约定也带进来。这种按需加载的机制能有效控制上下文体积。

提示：子目录的 CLAUDE.md 会追加到根目录的内容后面，而不是替换。所以根目录写通用规则，子目录写特有规则，不要重复。

5. memory 机制的原理与持久化记忆管理

5.1 memory 和 CLAUDE.md 的本质区别

很多人搞不清楚 memory 和 CLAUDE.md 的区别，觉得都是存文本的地方。它们的核心差异在于生命周期和作用范围。

CLAUDE.md 是项目绑定的，跟着仓库走，团队共享，内容相对静态。memory 是用户绑定的，跟着人走，个人独享，内容动态增长。CLAUDE.md 是你主动写的，memory 是 Claude Code 在对话过程中自动记录和更新的。

举个例子：你在 CLAUDE.md 里写"这个项目用 pnpm 而不是 npm"，这是项目约定。你在 memory 里记录"我偏好简洁的代码风格，不喜欢过多的注释"，这是个人偏好。前者换个人来看这个项目也需要遵守，后者只影响你自己的使用体验。

memory 的另一个特点是跨会话持久化。你这次会话里告诉 Claude Code 的信息，下次开新会话它还记得。这个机制让长期使用变得越来越顺手，不用每次都重复交代背景。

5.2 memory 的自动记录与手动管理

Claude Code 会在对话过程中自动识别值得记住的信息并写入 memory。比如你纠正了它的一个错误做法，它会把这条纠正记录下来，下次不再犯。你告诉它你的偏好，它也会记住。

但自动记录不是万能的，有时候它记的东西不准确，或者记了你不想让它记的内容。这时候就需要手动管理。你可以通过命令查看当前 memory 里存了什么，也可以手动添加、修改或删除条目。

我的习惯是每隔一段时间 review 一次 memory 内容，把过时的、不准确的清理掉。memory 不是越多越好，冗余的信息会干扰 AI 的判断。就像你的笔记软件，如果不定期整理，最后会变成一堆找不到东西的垃圾堆。

5.3 memory 内容的组织与检索优化

memory 的检索是基于语义相似度的。当你发起一个请求时，Claude Code 会根据请求内容去 memory 里找相关的条目。这意味着 memory 条目的写法直接影响检索效果。

好的 memory 条目应该是具体、独立、可操作的。比如"用户偏好用 async/await 而不是 Promise 链式调用"就比"用户喜欢现代 JavaScript"要好，因为前者更具体，更容易在相关场景下被检索到。

另外，memory 条目之间不要有矛盾。如果你先记录了"用户喜欢详细注释"，后来又记录了"用户偏好简洁代码"，AI 就不知道该听哪个。遇到这种情况，应该删除旧条目，只保留最新的偏好。

我通常会把 memory 分成几类来管理：编码风格偏好、工具使用习惯、常见错误的纠正、项目无关的通用知识。这样在 review 的时候更容易发现冗余和矛盾。

6. 三套配置协同工作的实战场景

6.1 新项目初始化时的配置流程

接手一个新项目时，我通常会按这个顺序建立配置体系：

第一步，先花十分钟浏览项目结构，搞清楚技术栈和目录组织。然后写一份精简的 CLAUDE.md，只写最关键的约定。这时候不要追求完整，先让 AI 能基本理解项目就行。

第二步，根据项目需要调整 settings.json。比如项目有特殊的格式化要求，或者需要限制某些操作权限，在这里配置。如果全局配置已经够用，这一步可以跳过。

第三步，在后续的对话中逐步积累 memory。遇到 AI 做错的地方及时纠正，它会自动记录。遇到自己反复交代的偏好，也可以手动写入 memory。

这个流程的核心思路是渐进式配置，不要一开始就追求完美，而是在使用中不断调整。

6.2 团队协作中的配置同步策略

团队使用 Claude Code 时，最大的挑战是保持配置一致。我的建议是：

settings.json 和 CLAUDE.md 必须提交到仓库。这两个文件是项目的一部分，应该像代码一样被版本管理。新成员拉下代码后就自动获得一致的配置。

memory 不提交，各自管理。每个人的 memory 是个人的使用习惯积累，不需要也不应该同步。但团队可以约定一些通用的偏好，写进 CLAUDE.md 里，这样对所有人都生效。

定期 review 配置。项目在演进，配置也要跟着更新。我建议每个 sprint 结束时花几分钟看看 CLAUDE.md 有没有过时的内容，settings.json 有没有需要调整的地方。

6.3 配置冲突的排查与解决思路

当你发现配置不生效时，按这个顺序排查：

先确认 settings.json 的 JSON 格式是否正确。用校验工具跑一遍，排除格式问题。

再确认配置文件的加载顺序。项目级配置是否覆盖了全局配置？子目录的 CLAUDE.md 是否和根目录的冲突？

然后检查 memory 里是否有矛盾的条目。有时候 AI 不按预期行事，是因为 memory 里有旧的、错误的记录在干扰。

最后用/config命令查看当前实际生效的配置，和你的预期对比，找出差异。

这个排查流程我用了很多次，基本上能覆盖 90% 以上的配置问题。剩下的 10% 通常是版本兼容性问题，需要查看官方文档确认当前版本支持哪些配置项。

7. 常见问题与排查技巧实录

7.1 配置不生效的典型原因速查表

7.2 我踩过的五个真实坑

第一个坑：settings.json 末尾多了逗号。这个前面提过，排查了半小时才发现。现在养成了写完就校验的习惯。

第二个坑：CLAUDE.md 写太长导致响应变慢。有个项目我写了 300 多行，每次对话明显感觉慢。后来精简到 80 行，速度恢复正常。教训是 CLAUDE.md 要克制，只写必要的。

第三个坑：memory 里存了过时的技术栈信息。项目从 Vue 2 迁移到 Vue 3 后，memory 里还记着"用 Options API"，导致 AI 一直按旧写法生成代码。后来手动清理了才正常。

第四个坑：团队成员的 settings.json 不一致。有人用了全局配置覆盖了项目配置，导致行为不统一。后来我们在 CLAUDE.md 里明确写了"不要用全局配置覆盖项目配置"，问题才解决。

第五个坑：子目录 CLAUDE.md 和根目录内容重复。我在两个文件里都写了代码规范，结果 AI 收到两份重复信息，反而产生了混淆。后来把通用规范只放在根目录，子目录只写特有内容。

7.3 配置优化的实用技巧

技巧一：用注释说明配置意图。settings.json 不支持注释，但 CLAUDE.md 可以。我会在 CLAUDE.md 里解释为什么某个配置是这样设置的，方便后来者理解。

技巧二：定期清理 memory。我每个月会花十分钟 review 一次 memory，删掉过时的条目。保持 memory 精简能提升检索准确率。

技巧三：用 CLAUDE.md 记录配置变更历史。每次调整配置时，在 CLAUDE.md 末尾加一行说明改了什么、为什么改。这样出问题时能快速回溯。

技巧四：新项目从模板开始。我维护了一份 CLAUDE.md 模板，新项目直接复制过来改改就能用，省去了从零写的时间。

技巧五：配置改动后立即验证。改完配置后马上发一个测试请求，确认行为符合预期。不要等到正式使用时才发现问题。

这套配置体系我用了大半年，最大的体会是：配置不是一次性的工作，而是持续迭代的过程。刚开始不用追求完美，先用起来，遇到问题再调整。随着使用时间增长，你的配置会越来越贴合自己的习惯，Claude Code 也会越来越懂你。