1. 三大配置体系全景拆解

1.1 为什么 Claude Code 需要“三层记忆”

装好 Claude Code、跑通第一次对话之后，大多数人会进入同一个迷茫期：这工具能写代码、能执行命令、能改文件，但它总记不住事。上午刚定好的代码风格，下午就按默认习惯写了；不同项目之间切换，上一项目的约束全带过来了；想让它在特定目录里放开手脚，却发现权限拦得死死的。

这些问题的根源，都在于配置体系没搭对。Claude Code 本质上不是一个单文件命令行工具，而是一套以“会话 + 工具调用”为核心的 Agent 运行时。它真正区别于普通 Chat 客户端的地方，是它具备执行命令、修改文件、调用外部服务的能力，因此它的配置必然围绕“行为边界”和“记忆上下文”两条主线展开，对应到三个核心体系：

• settings.json：运行行为的开关面板。管模型参数、权限控制、环境变量、MCP 服务注册。
• CLAUDE.md：长期记忆的项目手册。告诉 Claude“你在这个项目里应该怎么做事”。
• memory：跨会话的自主记忆。保存用户偏好、历史关键信息和可以复用的结论。

我习惯用一个入职场景来类比：settings.json 是公司的 IT 策略，规定你能访问哪些系统、外设能不能插、哪些网站能上；CLAUDE.md 是岗位手册，写清楚业务流程、代码规范、项目架构；memory 则是你随手贴的便利贴，记录这两天正在处理什么、上次沟通到哪一步。三者缺一不可，但职责完全不同，如果互相越界，配置体系就会变成一团乱麻。

1.2 加载顺序与作用边界

三大配置体系之间不存在“谁替代谁”的关系，关键是理解它们的加载优先级和覆盖规则。

settings.json 的加载遵循“从全局到项目”的覆盖逻辑。系统维护一份用户级配置，默认在~/.claude/settings.json，它定义了你在所有项目中的通用行为。如果某个项目根目录下也有.claude/settings.json，该文件的配置项会覆盖用户级配置中的同名项。企业或团队还可以通过托管策略文件（通常放在项目.claude/settings.local.json）进一步覆盖。这意味着权限控制永远是“就近生效”——项目级配置拥有最终解释权。

CLAUDE.md 的加载则是“从粗到细”的层级拼接。Claude Code 会按以下顺序读取内容，并将它们全部注入上下文：企业级 CLAUDE.md > 用户级 CLAUDE.md > 项目根目录 CLAUDE.md > 当前工作目录及上层目录的 CLAUDE.md。每一级的内容不是替换关系，而是叠加关系。子目录下的 CLAUDE.md 补充当前模块的专属说明，比如“本目录是数据迁移脚本，禁止直接操作生产库”。

memory 的机制与前两者都不同。它不是一次性注入的静态文件，而是按需检索的动态存储——Claude 在需要时读取记忆库，把与当前任务相关的条目加入上下文。因此记忆库的写入是持续的，读取是选择性的，这也是它跟 CLAUDE.md 最本质的区别：CLAUDE.md 整篇全量加载，memory 是按需抽取。

理解这三者的边界有多重要？我见过最典型的配置混乱现场：有人在 CLAUDE.md 里写了半屏的环境变量说明，结果每次对话都白白消耗大量上下文窗口；有人在 settings.json 里把文件读写权限全部放开，导致 Claude 在重构时误改了一堆不该动的配置文件。配置体系不是越多越好，而是“各归其位、各司其职”。

2. settings.json：给 Agent 立规矩的总开关

2.1 核心字段逐一拆解

settings.json 和大多数开发工具的配置文件一样，使用 JSON 格式，支持注释写法（JSONC）。我对它的定义是：所有不需要 Claude“思考”而应该直接“执行”的规则，都放进这里。

先看最常用的字段。

模型与 API 配置。model字段指定默认模型，比如model: "claude-sonnet-4-5"；env字段用于注入环境变量，尤其适合配置 API Key 或第三方模型的接入地址。很多人在env里配置 ANTHROPIC_BASE_URL 指向代理或网关，这比在 shell profile 里写全局变量干净得多，因为它只对 Claude Code 生效，不污染系统环境。

权限控制。这是 settings.json 里权重最高的部分，也是我建议每个用户第一时间配置的内容。核心机制是permissions对象，里面通过allow和deny规则控制工具调用。可配置的规则非常细：允许/拒绝读取某类路径、允许/拒绝执行某类命令、允许/拒绝读写某个目录。例如：

{ "permissions": { "allow": [ "Read(project_root)", "Edit(project_root/src/**)", "Bash(git:*)", "Bash(npm:*)" ], "deny": [ "Read(project_root/.env)", "Edit(project_root/dist/**)", "Bash(rm:*)", "Bash(curl:*)" ] } }

这套规则的优先级是 deny 大于 allow，也就是“一票否决”。即便某个命令在白名单里，只要它同时命中 deny 规则，仍然会被拦截。我用这个特性来兜底安全底线：不管对话里怎么被诱导，rm、curl、sudo永远被拒绝。

输出与交互行为。maxTokens控制单轮生成的最大 token 数，默认值通常够用，但如果你处理超长代码文件，建议调高，否则输出会被截断。includeCoAuthoredBy决定是否在 Git 提交信息里增加“Co-Authored-By: Claude”署名，如果你参与开源项目、需要保留 AI 协作痕迹，把它设为 true；如果你给客户交付代码、不想留下工具痕迹，保持 false。forceLogin控制 OAuth 登录模式，在受限网络环境下可能需要关注。

工具与服务注册。mcpServers字段集中登记 MCP 服务——可以把 MCP 理解成给 Claude Code 外接的“技能包”。数据库、浏览器、文件系统、告警平台都可以通过 MCP 接入。这个字段极其实用，也让 settings.json 的定位从“参数表”升级为“能力中心”。

2.2 一份可直接上手的配置示例

下面这份配置是我在多个 Python 项目中实测过的基线版本，思路是“默认拒绝、按需放开、关键路径留痕”：

{ "model": "claude-sonnet-4-5", "env": { "ANTHROPIC_API_KEY": "your-key-here", "PYTHONUTF8": "1" }, "permissions": { "defaultMode": "acceptEdits", "allow": [ "Read(project)", "Edit(project/src/**)", "Edit(project/tests/**)", "Bash(python:*)", "Bash(pytest:*)", "Bash(git:*)", "Bash(npm:run:*:*)" ], "deny": [ "Read(project/.env)", "Read(project/secrets/**)", "Bash(rm:*)", "Bash(curl:*)", "Bash(wget:*)" ], "additionalDirectories": [] }, "maxTokens": 32000, "includeCoAuthoredBy": false, "mcpServers": { "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] } } }

几个配置项的解释：

• defaultMode设为acceptEdits表示默认接受文件编辑类操作，但保留对危险命令的拦截，兼顾效率与安全。
• additionalDirectories空数组保持默认，Claude 只能访问当前项目目录，避免它越权读取家目录下其他项目的文件。
• 环境变量里设置PYTHONUTF8是因为 Windows 下 Python 默认编码容易踩 GBK 的坑，Claude Code 执行脚本时因为编码问题报错极常见，这个设置一劳永逸。

2.3 实操中的高频配置技巧

第一，环境变量注入比改全局配置文件更安全。我见过有人在~/.bashrc里直接写 API Key，然后因为 shell 环境冲突排查半天。放进 settings.json 的env字段后，只有 Claude Code 的进程能读取，不会泄漏到其他终端会话。修改后无需重启终端，重新启动 Claude Code 即生效。

第二，权限规则做“场景化集合”。与其写一条条散乱的 allow，不如按用途分组。比如这个项目是前端为主，那就把Bash(npm:*)和Edit(project/src/**)放一起组成“前端任务集”；换 Node 后端项目时，再换成Bash(node:*)。我自己的做法是维护一份settings.global.json放通用规则，每个项目再独立写settings.local.json，既复用又隔离。

第三，不要忽视 JSON 语法错误。settings.json 虽然支持注释，但依然是严格结构化的。少一个逗号、多一个尾逗号，都会导致 Claude Code 启动时直接报错或静默使用默认配置。改完配置后，第一件事是用claude config list查看实际加载结果，而不是直接进对话。这是我踩过好多次坑之后的强迫症：改配置必看加载结果，不看不进对话。

3. CLAUDE.md：真正有效的“项目手册”

3.1 三个层级的职责划分

如果说 settings.json 控制的是“能不能”，CLAUDE.md 控制的就是“怎么做”。它是一份 Markdown 文件，Claude Code 会在每次会话启动时自动读取并注入系统提示词，相当于给模型一份关于当前环境的详细说明书。

CLAUDE.md 的层叠结构是它的灵魂。用户级文件位于~/.claude/CLAUDE.md，适合存放跨越所有项目的个人偏好，比如“编写代码时使用 TypeScript strict 模式”“提交信息必须遵循 Conventional Commits 规范”。项目级文件位于项目根目录，写的是本项目的架构约束、目录说明、测试命令、代码风格。子目录级文件则放在具体模块目录中，只影响该目录下的任务。

我举一个具体的分工例子。用户级 CLAUDE.md 我会写：

## 通用规范 - 在编写单元测试时，优先使用 pytest 而非 unittest - 提交信息格式：type(scope): description，禁止使用 "update" "fix bug" 等模糊描述 - 生成代码时自动补充类型注解，不允许出现裸的 dict 返回

项目级 CLAUDE.md 则完全不同：

# 支付网关项目规范 ## 架构说明 - 本项目采用六边形架构，domain 层禁止依赖 infrastructure 层 - 所有外部服务调用必须经过 adapter 层，禁止在 service 层直接发起 HTTP 请求 ## 常用命令 - 安装依赖：poetry install - 运行测试：poetry run pytest tests/ -m "not integration" - 本地启动： poetry run uvicorn app.main:app --reload ## 不要做什么 - 禁止修改 alembic 版本文件 - 禁止在代码中硬编码商户密钥，统一读取环境变量

这种分层设计的好处是显而易见的：切换项目时，用户级规范依然生效，但项目级规范会随上下文切换而替换；不会出现 A 项目的架构约束被带到 B 项目里的错乱。而且，层级越多，每一层需要写的就越精炼，注入上下文的效率越高。

3.2 写一份合格 CLAUDE.md 的四个铁律

我在自己项目里反复迭代 CLAUDE.md，总结出四条硬规则。

规则一：永远写“要做什么”，不要写“是什么”。Claude 需要的不是百科知识，而是行为指令。与其写“项目使用 FastAPI 开发”，不如写“新增 API 路由时，必须先在 app/routes/ 目录下定义 schema，再在 services/ 中实现业务逻辑，最后通过 router 暴露”。描述越具体，行为越可预测。

规则二：把“不要做什么”单独成节。大模型的默认风格是“尽力完成任务”，如果没有明确的禁令，它倾向于自由发挥。我在 CLAUDE.md 里专门维护一个“不要做什么”的列表，比如“禁止修改数据库迁移文件”“禁止删除 fixtures 目录下的共享数据”。这些禁令能精准拦截很多灾难性操作。

规则三：善用命令而非散文。与其写“如果你要运行测试，请先检查虚拟环境是否激活，然后执行测试命令”，不如直接给一条命令示例：

## 测试 - 运行全部用例：poetry run pytest - 运行单个用例：poetry run pytest tests/test_user_service.py::test_create_user -s

命令越明确，Claude 执行时越少犹豫，也越少尝试“自由发挥”地发明参数。

规则四：让 CLAUDE.md 自己长出来。不要第一次就把 CLAUDE.md 写得尽善尽美，而是通过/init生成骨架后，在实际使用中发现问题就补充一条。我会在日常开发中反复问自己：这句话如果让一个刚接手项目的同事看，他能照做吗？不能，就继续改写。CLAUDE.md 应该是活文档，而不是一次性的毕业设计。

3.3 让 CLAUDE.md 具备“主动性”的进阶用法

CLAUDE.md 不只是被动说明，它还能定义 Claude 在某些场景下的主动行为。比如，在代码审查类项目中，我写入：

## 审查流程 - 当用户发起 review 请求时，先运行 `poetry run ruff check src/` 获取静态检查结果 - 再运行 `poetry run pytest -x` 确认测试状态 - 最后基于差异输出评审意见，按“阻塞问题、建议改进、可忽略”三档分类

Claude 会在你触发 review 时自动执行这个三步流程，而不是空谈代码质量。这个用法本质上是把 CLAUDE.md 从“项目字典”升级成了“行为触发器”。

另一个实用技巧是把决策依据写进去。比如在CLAUDE.md里记录“本项目为什么不用 ORM 而使用原生 SQL”，后续 Claude 在扩展功能时会自动遵循这个决策，避免反复提出已经否决过的方案。这个技巧特别适合长期维护的项目——很多上下文只在最初决策时存在过，如果不落盘到 CLAUDE.md 里，几周后 Claude 就会“失忆”，重新建议你已经否掉的方案。

4. memory：让 Agent 记住长对话之外的东西

4.1 memory 的存储机制与使用场景

memory 是我认为 Claude Code 配置体系里最容易被低估、也最容易被误用的一层。它解决的是“跨会话遗忘”问题：普通聊天工具关闭对话后就断片了，但 Claude Code 的 memory 允许它把一些关键信息保存下来，在未来的对话中重新唤起。

从实际使用感受来说，memory 用于三类信息最合适：

第一，用户偏好。比如“用户倾向于使用 2 空格缩进而不是 4 空格”“用户在生成提交信息时不希望出现 emoji”。这类信息不是某个项目特有的，而是你个人的工作习惯。

第二，跨会话的项目进度。比如“支付模块的重构已完成 70%，剩余工作是 adapter 层单元测试”。下次开启新会话时，Claude 能直接接上进度，而不是像刚入职的实习生一样从头问起。

第三，经验教训。比如“使用 pandas 处理大数据集时，不要用 iterrows，改用向量化操作”。这类结论一旦写入 memory，后续同类任务会自动调用。

从机制上看，memory 与 CLAUDE.md 最大的不同在于写入方式。CLAUDE.md 是你主动编辑的文件，而 memory 是 Claude 根据对话内容自动总结后写入的。这意味着 memory 的质量取决于你怎么“喂”它——你在对话中表达得越明确，Claude 总结得就越准确。

4.2 memory 与 CLAUDE.md 的分工与冲突

这两个体系虽然都是“记忆”，但定位完全不同，如果不加区分，很容易互相污染。

CLAUDE.md 适合放“稳定性知识”：项目架构、团队规范、长期决策。这些东西一旦变化缓慢，写死在文件里更可靠，而且全量注入、不会遗漏。

memory 适合放“动态信息”：当前任务状态、用户临时偏好、最近的排查结果。这类信息时效性强，如果写进 CLAUDE.md 反而会制造噪音。

那两者冲突时怎么办？我遇到的典型场景是：CLAUDE.md 里写了“项目使用 pnpm 作为包管理器”，但 memory 里记录了“用户最近在这个项目里改用 npm”。实际运行时，Claude 会同时读取两者，产生矛盾。我的处理原则是：明确文件优先于隐式记忆。CLAUDE.md 是用户主动维护的显式规范，应该作为基准；memory 是自动积累的隐式记忆，可以通过对话中的明确指令来覆盖。如果想让新习惯长期生效，直接改 CLAUDE.md，而不是指望 memory 自动纠偏——这是两条完全不同的路径。

4.3 跨模型切换时的 memory 留存

很多朋友用第三方工具切换不同模型接入 Claude Code（比如用 CC Switch 这类工具把 DeepSeek、Qwen、GLM 等模型接到 Claude Code 的工作流里），这时最关心的一个问题就是 memory 还能不能保住。根据我的实测，memory 的存储位置在本地，与具体模型无关。只要配置环境没有改变，底层记忆文件一直都在；切换模型后，新的模型也能读取旧的记忆内容。但要注意，第三方的模型能力参差不齐，有的模型对 memory 中自然语言描述的遵循程度远不如 Claude，因此越是切换到第三方模型，越建议把关键规范同步到 CLAUDE.md 里，依靠显式规则而不是隐式记忆来约束行为。

另外，我建议定期清理 memory。自动积累的机制虽然方便，但时间久了会沉淀大量过时信息——去年某次对话中的临时决定，到今年早就不适用了，却被 Claude 当作当前偏好来遵循，反而误导任务。清理方式很直接：直接查看记忆文件，删掉过期条目；也可以直接在对话中告诉 Claude“删除关于 X 的记忆”，它会同步更新记忆库。

5. 常见问题与排查录制

5.1 配置不生效的三大原因

在实际使用中，配置写对了但不生效的情况，九成出在以下三个原因。

原因一：路径错误。Claude Code 读取配置有固定路径，如果你把settings.json放在项目根目录而不是.claude/子目录下，它根本不会加载。CLAUDE.md 同理，必须放在正确层级。我见过最离谱的一次，是同事把配置写进~/.config/claude/目录，折腾了两小时。排查方法非常简单：在项目里运行claude doctor或检查claude config list，它会明确告诉你当前加载的是哪些文件。

原因二：缓存与热加载问题。Claude Code 的大部分配置修改后无需重启即可生效，但 settings.json 中的某些字段（比如 MCP 服务、模型参数）在会话启动时就已经固化，改动后必须重启会话。我自己的经验是：改完配置后，宁可靠谱地重启一次 Claude Code，也不要在长会话里赌它是否热更新。

原因三：权限规则冲突。deny 规则优先于 allow 规则，这是设计如此，但很多人在配置里写了看似放开实则矛盾的白名单，导致操作被静默拦截。比如 allow 里写了Bash(git:*)，但 deny 里写了Bash(git:push)，那么推送操作永远失败。排查时把 permissions 里所有规则逐条过一遍，确认不存在重叠矛盾。

5.2 高频报错与应对方案

把社区里高频出现的几个报错整理成速查表：

注意，遇到网络类报错时，最合理的排查顺序永远是从“本地网络是否正常、系统代理是否生效、订阅状态是否有效”三个维度入手，而不是急于寻找捷径。

5.3 配置健康检查清单

我现在每到一个新项目，做完配置后的第一件事就是跑一遍检查。下面是清理后的检查清单，你可以直接抄走：

• settings.json语法是否合法，是否放在.claude/下？
• 必填环境变量（API Key、Base URL）是否已在env中声明，且未泄漏到全局 shell 配置？
• 权限规则是否遵循“deny 优先”原则？危险命令是否已兜底拦截？
• CLAUDE.md 是否三层齐全（用户级、项目级、需要的子目录级）？
• CLAUDE.md 中是否有“不要做什么”章节？命令是否具体可执行？
• 最近两次跨会话任务，Claude 是否还能记得关键上下文？如果忘了，memory 是否需要补充或修正？
• 是否存在明显过期或冲突的记忆条目？
• 第三方模型切换后，行为是否符合预期？关键规范是否已显式落到 CLAUDE.md？

这份清单能拦住 80% 的配置问题。剩下 20%，大概率是版本更新的变化，记得留意官方更新日志，新版本可能会调整配置字段的加载逻辑。

6. 一整套可以照抄的组合配置方案

前面把三大配置体系拆开讲了，最后把它们串起来，给一个真实项目的完整组合。

假设你在开发一个 FastAPI 电商后端，团队规范是“pytest 测试 + Ruff 检查 + Conventional Commits”。你的目标：让 Claude Code 在这个项目里既能高效干活，又不越界。

settings.json 的关键决策：默认接受文件编辑，只放行测试和静态检查命令，对所有网络请求命令和危险删除命令一律 deny，同时在 env 中注入测试数据库连接串。这样 Claude 可以改代码、跑测试、提 commit，但无法 curl 外网、无法删除文件、无法连接生产库。

CLAUDE.md 的关键决策：项目级文件写清楚“先跑 Ruff 再跑 pytest”、目录职责、禁止修改迁移文件；再配一个子目录级 CLAUDE.md 放在tests/下，限定“只允许新增 API 测试，禁止修改共享 fixtures”。层级划分让约束精确到目录级，比在 settings 里写一堆路径正则要直观得多。

memory 的关键决策：把“用户偏好 2 空格缩进”“上次重构进度”这类动态信息交给 memory 自动积累，每次新会话开启时，Claude 能快速接上上次的上下文。同时定期检查，删除过期的临时决定。

这三层配合起来，实际使用体验是什么样的？我启动一个新会话，打开项目，Claude Code 会自动读取策略与规范，然后我只需要说“继续处理昨天那个支付接口的分页问题”，它就能准确找到相关代码、遵循项目规范、跳过危险操作，并在提交时生成符合格式的 commit message。整个过程，我只需要偶尔审查它生成的代码。

这是我个人在实际项目里打磨出来的组合套路。Claude Code 的配置体系没有什么神秘魔法，本质规律就是：把稳定的约束写成文件，把临时的信息交给记忆，把危险的边界交给权限。你按这个原则去设计自己的配置，无论是做个人项目还是团队协作，都能少踩很多坑。