最近把 Claude Code 从“裸奔”状态升级成了一套正经的配置体系前后折腾了两个晚上最大的感受是这工具默认状态能用但你要是不把配置捋明白每次开新会话都要重新跟它解释项目背景、技术栈、代码规范效率低到怀疑人生。后来我把配置拆成三层来看一切就顺了这三层就是标题里说的 settings.json、CLAUDE.md 和 memory。很多刚接触的人会困惑这三个东西到底什么区别优先级谁高谁低改哪个文件干什么事这篇文章就把我实际调试过程中踩过的坑和最终沉淀下来的方案完整记录下来给那些正在用或者准备用 Claude Code 的朋友一个可以直接抄作业的参考。先说结论settings.json 管的是“能不能做”CLAUDE.md 管的是“该怎么做”memory 管的是“记得怎么做”。理解了这个分工你就不会被一堆文档绕晕。1. 先把三个配置文件的关系理清楚1.1 三张配置表解决的是同一个问题的三个侧面拿一个真实团队来类比。settings.json 相当于公司的 IT 管理制度规定谁能访问哪台服务器、哪些操作需要审批、哪些命令被禁止它是运行环境和行为边界的定义。CLAUDE.md 则相当于项目组的操作手册告诉新来的同事这个项目是干什么的、代码放哪、构建命令是什么、有没有什么历史遗留的坑。memory 则像老员工脑子里的经验积累他记得上次那个线上事故是怎么修复的、这个客户偏好什么风格、那个模块为什么当初那么设计。这三者缺一不可。只配 settings.jsonClaude 知道能执行什么命令但不知道你的项目要什么只写 CLAUDE.md它知道项目规则但每次会话都要重新加载只有 memory 而没有前两者记忆没有约束容易跑偏。我见过不少人的配置只有 settings.jsonCLAUDE.md 是空的memory 也没概念结果就是 Claude Code 像一台配置完好的服务器却没有任何业务逻辑在上面跑。1.2 一个会话里三个文件是怎么被读取的我实测下来的加载顺序是这样的启动 Claude Code 时它先读取 settings.json 确定运行环境包括 API 密钥、模型选择、权限规则、钩子脚本然后加载各层级的 CLAUDE.md把这些内容作为会话的系统指令注入Claude 在回答任何问题之前就“知道”了你的项目背景和规则memory 则是在整个对话过程中动态累积的它既包括 JSON 配置文件和 CLAUDE.md 里静态写入的长期记忆也包括会话进行中你明确让它记住的内容。理解这个顺序很重要因为它决定了你的配置策略。你在 settings.json 里修改的环境变量会在 CLAUDE.md 加载之前生效你在 CLAUDE.md 里写的规则会先于你对话中的临时指令被遵守——但如果你在对话里明确说“这次忽略 CLAUDE.md 里的某某规则”它的优先级又会更高。所以不要指望着用一个配置文件解决所有问题三层配置分开管理才是长期可维护的姿势。1.3 推荐的上手顺序如果你现在是一个新项目要从零配置我建议按这个顺序来。第一先把 settings.json 搞定把环境变量、权限、模型选择配置好保证 Claude Code 能在你的终端里稳定跑起来。第二写一份项目级的 CLAUDE.md不用追求大而全先把项目概述、技术栈、常用命令、代码规范写进去这几项就能让 Claude 的回复质量上一个台阶。第三随着使用慢慢沉淀 memory把你在对话中反复强调的偏好、踩过的坑、团队的决策记录进去。不少新手一上来就照着网上的大而全模板写了几百行 CLAUDE.md结果 Claude 反而被各种互相矛盾的规则搞糊涂。我的经验是配置是迭代出来的不是一次写出来的。先跑起来再加规则遇到问题再改规则这才是正路。2. settings.json全局行为的控制中心2.1 配置文件到底放在哪里settings.json 有两层用户级和项目级。用户级的全局配置在~/.claude/settings.json它影响你机器上所有项目里的 Claude Code 会话。项目级的配置在项目根目录下的.claude/settings.json只对当前项目生效。两份文件都存在时项目级配置会覆盖用户级配置里的同名项这一点和 Git 的 local 配置覆盖 global 配置的逻辑是一样的。我推荐的做法是用户级 settings.json 只放跟账号、模型、全局权限相关的内容比如 API Key 的环境变量、默认模型、允许全局执行的命令白名单。项目级 settings.json 则放跟项目相关的权限开关比如这个项目允许 Claude 直接修改哪些目录下的文件、允许执行哪些包管理命令。如果你把项目特定的权限写进用户级配置另一个项目可能也会用到不小心就会造成权限越界。2.2 值得你仔细看的几个配置项{ model: claude-sonnet-4-20250514, env: { ANTHROPIC_API_KEY: sk-xxxx, ANTHROPIC_MODEL: claude-sonnet-4-20250514, ANTHROPIC_BASE_URL: https://api.example.com }, permissions: { allow: [ Bash(npm run test), Read(~/Projects/MyApp/**) ], deny: [ Bash(git push), Edit(.env) ], ask: [ Bash(rm -rf **) ] }, hooks: { PreToolUse: [ { matcher: Edit, command: node .claude/hooks/lint-check.js } ] }, includeCoAuthoredBy: false, cleanupPeriodDays: 30 }上面这个 JSON 是我实际在用的一个精简版本字段名可能会随版本更新变化但核心思路不变。env是最常用的字段用来设置环境变量比如 API Key、模型名、API 网关地址。注意两个坑一个是在 shell 里 export 的环境变量和 settings.json 里的env字段是两套体系当 settings.json 里有值时它会覆盖 shell 里同名的变量另一个是env字段里不要写没有引号的注释JSON 标准不允许注释写错了整个文件都会解析失败。permissions是权限控制的重点。它分成 allow允许、deny禁止、ask询问三类。Claude 执行任何敏感操作之前会先检查这个列表。如果不在任何列表里默认会弹窗问你“是否允许”。如果你觉得每次都被打断就把那些日常必须的命令和文件路径加进 allow如果某些操作绝对不想让 Claude 做就加进 deny。优先级是 deny 最高allow 次之ask 最后。也就是说即使某条规则同时出现在 allow 和 ask 里只要它在 deny 里就一定会被拒绝。有人可能会问为什么不直接把所有命令都加进 allow省得烦这里我要提醒一句Claude Code 的权限设计本质上是安全边界特别是Bash类操作一旦允许了 rm、git push、生产环境部署这类命令它可能在你没来得及反应的时候执行完。我个人的底线是读操作放开写操作按目录控制破坏性命令永远放在 ask 里。2.3 hooks 钩子机制的作用hooks 是 settings.json 里容易被忽视但又特别强大的能力。它的作用是在 Claude 执行 Tool 调用的前后触发你自定义的命令。举个例子我在项目配置里加了一个 hook在 Claude 准备修改代码Edit 操作之前跑一遍 ESLint 规则检查如果代码风格有问题就阻止它的修改。这等于在 Claude 和你的代码库之间加了一道自动化质检。我用的心思是把这次检查的脚本放在项目里的.claude/hooks/目录下让团队所有人都能共用这个质量门槛。另一个实用场景是 PostToolUse。Claude 执行完命令之后把输出结果追加到日志文件方便你事后复盘它做了什么、为什么这样做。调过复杂任务的人应该深有体会对话轮次多了之后你根本记不清它中间执行了什么命令。有了钩子的日志出了问题就能快速定位是哪一步操作导致的。2.4 第三方模型接入配置现在圈子里的玩法早就不仅限于官方模型了。通过设置ANTHROPIC_BASE_URL和ANTHROPIC_MODEL这类环境变量可以把 Claude Code 接到兼容 OpenAI/Anthropic 接口的第三方模型上比如 DeepSeek、Qwen、GLM 等。社区里还有人做了 cc switch 这类便捷工具专门用来快速切换不同的模型供应商。我的建议是不要把模型相关的配置写死在用户级 settings.json 里。因为你会经常切换写死就意味着每次切换都要编辑 JSON非常容易出错。更优雅的方式是在 shell 配置文件里定义几个环境变量别名或者干脆用 cc switch 这样的工具来管理多套供应商配置。如果确实要在 settings.json 里写也尽量写成注释清楚、结构简单的形式并且做好备份。3. CLAUDE.md项目规则的载体3.1 CLAUDE.md 的本质是“给 Claude 的入职手册”settings.json 告诉我怎么跑那么 CLAUDE.md 告诉它“你在这个项目里是什么角色”。每一个 Claude Code 会话启动时它会自动读取项目根目录下的 CLAUDE.md并把它当作最高优先级的上下文进行理解。这相当于每次面试之前先给候选人一份公司手册让他大概了解业务方向和工作规则。CLAUDE.md 在官方设计里有多个层级用户级~/.claude/CLAUDE.md存放个人偏好比如你希望 Claude 用中文回复、注释风格用 JSDoc 等等项目级项目根目录的CLAUDE.md存放项目相关的背景和规则本地私有级CLAUDE.local.md存放只对你自己生效、不想提交进版本库的内容。多层级之间会合并生效项目级覆盖用户级本地私有级再覆盖项目级。用 Git 管理项目时CLAUDE.md 要提交到仓库里这样团队成员都能共享同一套规则CLAUDE.local.md 则加入 .gitignore。3.2 一份可以直接抄下来的模板下面这个模板是我根据自己维护的几个项目总结出来的删减了很多花哨的东西只留核心。你可以拿去直接改# 项目名称XXX 管理平台 ## 项目概述 这是一个面向小微企业的多租户订单管理系统。 前端使用 React TypeScript Vite后端使用 Spring Boot MySQL。 核心业务模块包括订单、库存、对账、权限。 ## 常用命令 - 安装依赖npm install - 启动开发服务npm run dev - 运行测试npm run test -- --watch - 构建生产包npm run build - 数据库迁移npx prisma migrate dev ## 代码风格约定 - 组件文件使用 PascalCase 命名工具函数使用 camelCase。 - 所有接口调用必须经过 src/api/ 下的封装模块禁止在组件里直接 fetch。 - 注释使用中文关键逻辑必须写明为什么这么实现。 - 新加的依赖必须说明用途并同步更新 README。 ## 架构与目录说明 - src/pages/页面级组件 - src/components/可复用组件 - src/store/状态管理 - src/server/后端接口 ## 常见陷阱 - 订单号在创建后不可修改任何涉及订单号的更新操作都要先确认是否有历史关联数据。 - 库存扣减必须在事务内执行同时更新乐观锁版本号防止并发超卖。 - 导出报表的接口耗时较长前端要处理超时重试不要盲目加大 axios timeout。这个模板的核心逻辑是让它知道你项目的背景概述、怎么跑命令、怎么写风格、在哪写架构、别踩什么陷阱。这几项内容能覆盖 Claude 日常协作 80% 以上的需求。3.3 规则书写的两个核心原则第一个原则是“具体到可以被执行”第二个是“给正面例子而不是抽象口号”。“要写出高质量代码”这种话就是典型的抽象口号Claude 无法把“高质量”变成具体的操作写了一句等于没写。但“所有接口调用必须通过 src/api/ 封装禁止在业务代码里直接 fetch”就是一条可执行规则Claude 在写代码时会真的去检查自己有没有违反。我在实际过程中发现规则里配上正面和反面的例子效果最好。比如你可以写“建议使用 async/await 而不是 .then 链式调用反例见本项目 git history 中重构前的提交记录”。Claude 能根据这个例子判断自己的写法是否符合预期。还有一点CLAUDE.md 会随着项目演进而过时。我见过有人写了一年没更新过的 CLAUDE.md里面还写着已经废弃的构建命令结果 Claude 每次跑命令都报错它还一脸茫然地重试。我的习惯是每两周左右翻一次 CLAUDE.md把过时的命令、改动的架构、新踩的坑同步进去。这个动作看起来不起眼却是配置体系长期有效的重要保障。3.4 利用 语法搭建项目知识库CLAUDE.md 还有一个容易被忽略的扩展能力在文件里通过语法引用其他文档。比如在 CLAUDE.md 里写## 接口设计规范 详细接口设计规范见 docs/api-design.md ## 数据库设计 ER 图和字段说明见 docs/database.md这样 Claude 会自动加载docs/目录下的相应文档作为上下文。它的意义在于你不需要把所有内容都塞进一个 CLAUDE.md 文件而是可以像维护技术文档一样把规则、设计文档、说明文档分门别类放在项目里然后在 CLAUDE.md 里建立索引。当 Claude 需要相关上下文时再通过语法按需引入避免了单个文件过于臃肿导致上下文被稀释。实测下来把 CLAUDE.md 保持在 300 行以内剩余细节全部用引用Claude 的理解准确率最高。超过 500 行以后规则之间的优先级和冲突就开始变得频繁Claude 会偶尔遗漏某些条款。4. memory跨会话记忆的正确姿势4.1 记忆到底存在哪很多人一听到 memory第一反应是“是不是有一个数据库或者向量索引”。实际在 Claude Code 的体系里记忆的承载形式主要是文件用户级 CLAUDE.md、项目级 CLAUDE.md、以及你在对话中明确要求记录下来的内容。它更像是一个结构化的“长期记忆仓库”而不是一个自动学习的向量库。如果你需要语义检索级别的记忆能力可以借助 MCP 记忆服务器或者维护独立的 knowledge 目录但那属于扩展玩法入门阶段先把文件层次的记忆用明白就行。我把 memory 拆成三种类型偏好记忆、项目记忆、决策记忆。偏好记忆记录你喜欢什么比如“回复用中文”“函数注释必须写清参数说明”项目记忆记录项目的背景和约定本质上就是项目级 CLAUDE.md决策记忆记录的是“为什么”比如当初为什么要用 A 方案而不是 B 方案它可以帮助 Claude 在未来面临相似选择时做出和你一致的判断。4.2 三层记忆目录搭建方案我给自己设定的三层记忆结构是这样的第一层是用户级~/.claude/CLAUDE.md只放跨项目的通用偏好。比如语言偏好、编码风格偏好、常用工具的配置习惯。因为它是全局的所以内容要克制不能把项目特有的东西放进去。第二层是项目级 CLAUDE.md 加上项目内的docs/claude/目录。项目 CLAUDE.md 放高度浓缩的核心规则和索引docs/claude/目录放完整的架构决策记录、踩坑记录、API 文档、会议总结之类的详细内容。通过语法在 CLAUDE.md 里按需引用。第三层是运行期的隐性记忆。当我在对话里跟 Claude 说“记住这个项目的部署流程是……”它会在当前会话内记忆。为了让这个记忆在下一次会话也有效我养成了一个习惯每次会话结束前把有效的结论追加到项目 CLAUDE.md 或 docs 目录下的对应文档里。这一步很多人会忽略相当于你让 Claude 记住了但没让它形成长期记忆下次还是得重新讲。4.3 知识库文件的维护节奏记忆体系不是一次搭完就完事的。我给自己的维护节奏是日常随手记每周整理一次。日常中遇到 Claude 反复问同样的问题或者我在对话中纠正了它某个错误认知就顺手记到临时文件里。每周抽十分钟把这些零散的记录整理进 docs/claude 和 CLAUDE.md。这样做的好处很明显随着时间推移Claude 对你的项目理解会越来越深新开一个会话也能带着之前的“经验”进入状态而不是每次冷启动。这和你带一个新同事的曲线差不多最开始需要反复交代越到后面越省心。4.4 记忆安全别什么都往里面写记忆体系里最容易忽略的是安全问题。我见过有人把数据库密码、云服务密钥直接写进 CLAUDE.md然后推送到公共仓库这种事故一旦发生就是灾难。凡是密钥、Token、内网地址一律不要出现在记忆文件里建议通过环境变量注入。另外最近圈子里讨论比较多的 AgentPoison 这类研究表明攻击者可以通过向智能体的记忆或知识库中投毒内容诱导它在后续决策中按照攻击者意图行动。也就是说如果你的 CLAUDE.md 或知识库里有一些恶意或误导性内容Claude 有可能把这些内容当作可信规则执行。所以我给自己定了一条规矩所有写进记忆体系的内容必须是自己审核过的可信信息如果是团队协作别人修改 CLAUDE.md 后要先 review 再合入不能任由不明来源的内容混进来。5. 常见问题与排查技巧5.1 配置不生效的排查清单我遇到最多的反馈是“我改了 settings.json但 Claude Code 根本没反应”。这里有一个排查顺序按这个顺序走能解决绝大部分问题。第一确认文件位置对不对。用户级配置必须在~/.claude/目录下项目级配置必须在当前工作目录的.claude/目录下或项目根目录下。注意 Claude Code 启动时的当前目录你以为是项目根目录实际上可能是在子目录里启动的那么它加载的就不是你改的那份配置。第二确认 JSON 格式合法。settings.json 里多加了一个逗号、少了一个引号整个文件都会被忽略而且很多情况下报错信息并不显眼。可以用jq . ~/.claude/settings.json这类命令快速验证格式。第三确认配置项名称是否是当前版本支持的。Claude Code 升级频率很高某些配置字段会改名或者迁移。我在升级后都会跑一个简单测试看看claude --version和官方 changelog如果发现配置项被废弃及时更新。第四确认 CLAUDE.md 是否被正确加载。在会话里直接问 Claude“CLAUDE.md 里写了些什么”它如果答不上来或者答错了说明加载顺序或文件位置有问题。我测试过CLAUDE.md 的位置放错一级加载结果就是完全不同的两份内容。5.2 权限弹窗和多模型切换问题权限弹窗太频繁是很常见的问题。解决办法是把自己日常允许的操作写进 settings.json 的 permissions.allow 列表。比如Bash(npm run dev)、Read(~/MyProject/**)注意权限规则的路径用 glob 通配符的时候要谨慎写宽了就等于放开整个目录的读取权限。多模型切换不生效的问题十有八九是环境变量被某个位置的配置覆盖了。检查顺序是系统环境变量 → shell 配置里的 export → settings.json 的 env 字段 → 命令行传入的参数。优先级从低到高也就是说命令行参数最高。如果 cc switch 这种工具切了没生效大概率是它的配置只改了 shell 环境变量但 settings.json 里还写死了旧值。删掉 settings.json 里对应的 env 项让外部变量透传进来问题就解决了。5.3 安装与 VSCode 集成相关安装本身不复杂通过 npm 全局安装anthropic-ai/claude-code就行前置条件是 Node.js 版本满足要求。macOS 和 Ubuntu 的安装步骤基本一致但要注意 PATH 环境变量是否包含了 npm 全局安装目录。VSCode 集成则在插件市场搜索 Claude Code 插件安装后在 IDE 里打开命令面板就能呼出 Claude Code 面板。VSCode 插件的配置和 CLI 共享同一套配置文件你改 settings.json 和 CLAUDE.md 后重启插件让配置生效即可。如果是在 Ubuntu 这类 Linux 环境下遇到报错我见过的最多的问题是 Node 版本太低。建议先node -v确认版本低了就升级不要直接硬跑。5.4 我的几个避坑心得最后说几个很难从官方文档里直接读到的东西。一个是 CLAUDE.md 里写“中文要求”的细节。如果你想让它用中文回复直接写“请用中文回复”就行但如果你的项目里有大量英文技术术语建议配套写一句“专业术语保留英文原文”否则它可能会把 API、DTO、Repository 全都强行翻译成中文看着非常别扭。另一个是日志目录和输出量的问题。Claude Code 会在运行过程中产生大量的会话日志默认情况下的自动清理周期也许并不适合你。我在~/.claude目录下见过好几个 G 的日志文件如果你机器的磁盘空间紧张记得在 settings.json 里设置cleanupPeriodDays或者定期手动清理。还有一个是 hooks 脚本的运行权限。在 Linux 和 macOS 上hook 指定的脚本如果没有可执行权限Claude Code 会静默失败看起来像是 hook 没配置成功实际上只是缺了一个chmod x。这个坑我踩过排查了很久才发现是权限问题。我自己的体会是配置文件这东西一次性搞大而全反而容易出错。先把 settings.json 和 CLAUDE.md 的最小功能跑通再在日常使用中慢慢补 memory等三轮迭代之后你就能拥有一套完全贴合自己工作流的配置体系。那之后你再去对比刚上手时裸奔的体验会明显感觉 Claude Code 像换了一个人在帮你干活。