1. 三套配置体系到底在解决什么问题很多人第一次接触 Claude Code看到项目根目录下同时存在settings.json、CLAUDE.md和 memory 这三样东西第一反应是懵的——不都是配置吗为什么搞这么复杂我刚开始用的时候也这么想直到在一个二十多人的协作项目里踩了一圈坑才真正理解这三者各自的分工。打个比方你就明白了。settings.json像是你工位上的电源插座和工具规格它决定了这个环境里允许用什么、不允许用什么CLAUDE.md像是贴在显示器边上的项目说明书告诉每一个新来的同事我们这个项目怎么干活、有哪些约定而 memory 更像是你个人的工作笔记记录的是我上次做到哪了、我习惯怎么处理这类问题。三者层级不同、作用域不同、生命周期也不同混用就会出乱子。我见过最常见的错误就是把本该写进CLAUDE.md的项目规范塞进了settings.json结果团队里每个人的配置一同步就互相覆盖也见过把个人偏好写进CLAUDE.md提交到仓库导致别人拉下来之后行为诡异。这些问题的根源都是没搞清楚三套体系的边界。这篇文章我会从实际使用角度出发把这三套配置体系的定位、写法、优先级、常见坑一次性讲透。不管你是刚装好 Claude Code 的新手还是已经在团队里推了一段时间想优化配置的老手应该都能从里面找到能直接抄的东西。核心关键词我会自然带出来但重点还是落在怎么用对这件事上。2. settings.json环境与权限的硬边界2.1 它到底管什么不管什么settings.json是 Claude Code 的运行时配置文件它管的是环境层面的东西权限、工具开关、模型选择、环境变量、钩子脚本。你可以把它理解成这个工具在你机器上的宪法它规定的是能做什么和不能做什么而不是应该怎么做。它不管的是业务逻辑和项目约定。比如我们项目用 pnpm 不用 npm这种约定写进settings.json是错的应该写进CLAUDE.md。再比如我习惯用中文回复这种个人偏好也不该写在这里应该交给 memory 或者个人级配置。这个边界一旦搞混最直接的后果就是配置同步时冲突不断。我见过一个团队把代码风格规则写进settings.json然后提交到仓库结果每个人本地环境不同一拉代码就报错排查了半天才发现是配置文件打架。2.2 配置文件的层级与优先级Claude Code 的settings.json是分层级的从高到低大致是这么个顺序层级位置作用域是否提交仓库企业级系统级托管目录全机器所有用户由管理员控制用户级用户主目录下的配置目录当前用户所有项目否项目级项目根目录.claude/下当前项目通常提交本地级项目内本地覆盖文件当前项目当前人否加入忽略优先级是就近覆盖本地级 项目级 用户级 企业级。但要注意企业级有些字段是锁定的下层改不动这是为了合规场景下强制统一行为。我个人的习惯是用户级放我自己的通用偏好比如默认模型、常用工具开关项目级放这个项目必须的权限声明本地级放我临时调试用的覆盖。这样团队协作时不会互相干扰我自己又能灵活调整。2.3 权限配置的写法与常见坑权限是settings.json里最核心也最容易写错的部分。基本结构长这样{ permissions: { allow: [ Bash(git status), Bash(git diff:*), Read(./src/**) ], deny: [ Bash(rm -rf:*), Read(./.env) ] } }这里有几个我踩过的坑必须说清楚。第一通配符的粒度。Bash(git diff:*)里的:*表示这个命令后面可以跟任意参数但如果你写成Bash(git:*)那就等于放开了所有 git 子命令包括git push --force这种危险操作。我建议宁可写细一点也不要图省事放开整个命令族。第二deny 的优先级高于 allow。也就是说即使你在 allow 里放开了某个路径只要 deny 里也匹配到了最终结果还是拒绝。这个设计是为了安全兜底但很多人不知道导致我明明 allow 了为什么还是被拦的困惑。第三路径匹配是相对项目根目录的。Read(./src/**)里的./指的是项目根不是当前工作目录。如果你在子目录里执行匹配规则不变这点和 shell 的直觉不太一样。提示改完settings.json之后最好用/permissions之类的命令确认一下实际生效的规则别只看文件内容。我有一次改完忘了重启会话折腾了半小时才发现配置根本没加载。2.4 环境变量与钩子的实用配置除了权限settings.json还能配环境变量和钩子。环境变量这块我一般用来注入一些 API 端点、代理地址注意这里指的是正常的网络请求代理配置不是别的意思、日志级别之类的东西。钩子hooks是很多人忽略但极其好用的功能。比如你可以配一个每次执行 Bash 命令前先跑一遍格式化检查的钩子或者每次会话结束时把日志归档的钩子。写法大致是这样{ hooks: { PreToolUse: [ { matcher: Bash, command: echo 即将执行命令 } ] } }钩子的价值在于把一些重复性的检查自动化。我在一个对安全要求比较高的项目里配了一个钩子专门拦截包含敏感路径的命令效果比单纯靠 deny 规则更灵活因为钩子里可以写更复杂的判断逻辑。3. CLAUDE.md项目约定的活文档3.1 为什么需要它而不是全靠 settingssettings.json解决的是能不能做CLAUDE.md解决的是该怎么做。这两者的区别就像公司允许你报销和公司报销流程是先在系统提交再找主管签字的区别。前者是权限后者是流程。CLAUDE.md本质上是一个 Markdown 文档放在项目根目录Claude Code 在会话开始时会自动读取它把它作为上下文的一部分。这意味着你写进去的内容会直接影响模型的行为——它会按照你写的约定来组织代码、命名变量、选择工具。我见过最有效的用法是把项目里那些新人来了要讲三天的隐性知识写进去。比如构建命令是什么、测试怎么跑、目录结构为什么这么设计、有哪些历史遗留的坑不能碰。这些内容写在文档里给人类看也行但写在CLAUDE.md里能让模型也遵守省去了每次都要重复交代的麻烦。3.2 内容组织的推荐结构CLAUDE.md没有强制的格式要求但根据我的经验按下面这个结构组织效果最好# 项目名称 ## 项目概述 一句话说明这个项目是干什么的。 ## 技术栈 - 语言与版本 - 框架与关键依赖 - 包管理器 ## 常用命令 - 安装依赖xxx - 启动开发xxx - 跑测试xxx - 构建xxx ## 代码约定 - 命名规范 - 目录结构说明 - 提交信息格式 ## 注意事项 - 不要碰的目录 - 已知的坑这个结构的好处是层次清晰模型读起来也容易抓重点。我试过把内容堆成一大段效果明显不如分节好——模型对结构化信息的利用效率更高。3.3 写什么、不写什么这是最容易出问题的地方。我的原则是写约定不写偏好写事实不写猜测写稳定信息不写临时状态。该写的项目特有的构建、测试、部署命令代码风格约定缩进、命名、注释语言目录职责划分已知的坑和绕行方案依赖版本约束的原因不该写的个人的编辑器偏好临时的调试信息会频繁变动的状态和项目无关的通用知识我见过有人把我喜欢用中文注释写进CLAUDE.md提交到仓库结果团队里其他人习惯英文注释一提交就冲突。这种个人偏好应该放 memory 或者用户级配置不该污染项目文档。3.4 多层级 CLAUDE.md 的叠加规则Claude Code 支持多个层级的CLAUDE.md项目根目录一个子目录里可以再放用户主目录下还能放一个全局的。读取时是从全局到具体逐层叠加越具体的优先级越高。这个机制很实用。比如我在用户主目录放一个全局的CLAUDE.md写我通用的工作习惯项目根目录放项目级的写这个项目的约定某个特殊子模块再放一个写这个模块独有的规则。这样既避免了重复又能精确控制。但要注意叠加是合并不是替换。如果全局写了用 2 空格缩进项目级写了用 4 空格缩进最终生效的是 4 空格但全局那条并没有被删除只是在冲突时被覆盖。所以写的时候要避免直接矛盾的规则否则模型可能会困惑。注意子目录的CLAUDE.md只在会话涉及到那个目录时才会被加载不是一开始就全部读进来。这个设计是为了控制上下文长度但意味着你不能指望模型一开始就知道所有子模块的规则。4. memory跨会话的个人记忆层4.1 memory 和另外两者的本质区别memory 是这三套体系里最容易被误解的。很多人以为它是另一个配置文件其实不是。memory 的核心特征是跨会话持久化和个人化。settings.json和CLAUDE.md都是静态配置——你写好了每次会话开始时加载会话结束后不变。而 memory 是动态积累——它会在会话过程中记录信息下次会话时再读回来。这就好比前两者是员工手册memory 是工作日志。这个区别带来的直接影响是memory 里的内容会随着使用不断增长需要定期清理而配置文件相对稳定改一次管很久。我见过有人把 memory 当配置文件用往里塞了一堆固定规则结果越积越多反而拖慢了会话启动。4.2 memory 的存储机制与读取时机memory 通常以文件形式存储在用户目录下的特定位置按项目或按主题分文件。读取时机一般是在会话开始时把相关的 memory 内容注入到上下文里。这里有个关键点memory 不是全量加载的。如果 memory 文件很大系统会根据当前会话的主题做相关性筛选只加载相关的部分。这个机制意味着你写 memory 时要注意主题清晰别把不相关的内容混在一个文件里否则筛选效果会打折扣。我自己的做法是按项目分文件每个文件里再按主题分节。比如一个项目一个 memory 文件里面分架构决策踩过的坑待办事项几节。这样既好维护筛选时也精准。4.3 什么内容适合放进 memory根据我的使用经验下面这几类内容最适合放 memory跨会话的决策记录比如我们决定用 X 方案而不是 Y 方案原因是 Z下次会话时模型能知道这个背景不会重复建议已经被否决的方案。个人工作习惯比如我习惯先写测试再写实现我偏好函数式风格这些是个人偏好不该进项目文档。项目的历史包袱比如这个模块是历史遗留的暂时不要重构这种信息写进CLAUDE.md太重放 memory 刚好。待办和进度比如上次做到第三步下次从第四步继续这是 memory 最典型的用法。不适合放 memory 的固定的项目规范应该进CLAUDE.md权限和环境配置应该进settings.json会频繁变动的临时状态放哪都不合适应该用别的机制4.4 memory 的维护与清理策略memory 最大的问题是会发霉——时间久了里面堆了一堆过时信息反而干扰判断。我一般每个月清理一次把已经完成的待办删掉把过时的决策标注或移除。清理时我会问自己三个问题这条信息现在还准确吗这条信息下次会话还用得上吗这条信息是不是应该升级成CLAUDE.md里的正式约定如果一条信息反复被用到说明它已经稳定了就该从 memory 升级到CLAUDE.md。这个从 memory 到 CLAUDE.md的升级路径是我用下来觉得最顺的工作流。新东西先放 memory 试用着顺手、稳定了再固化到CLAUDE.md里让团队共享。5. 三套体系的协作与优先级实战5.1 一个请求进来配置是怎么生效的理解三套体系怎么协作最好的方式是跟踪一个具体请求的处理流程。假设你在会话里说帮我把 src 目录下的工具函数重构一下背后大致发生这些事首先settings.json决定这次操作允不允许。如果重构涉及写文件而你的权限配置里没放开写权限那这一步就被拦下了后面的都谈不上。其次CLAUDE.md决定按什么规范做。模型会读项目约定知道这个项目的命名风格、目录结构、测试要求然后按这个规范来重构。最后memory 提供历史背景。如果之前会话里讨论过这个工具函数为什么这么写memory 里记着模型就会避开那些已经确认不能动的部分。三者是串联关系任何一环缺失都会导致行为不完整。只有settings.json没CLAUDE.md模型能干活但不符合项目规范只有CLAUDE.md没权限模型知道该怎么做但做不了有前两者没 memory模型每次都要重新了解背景。5.2 冲突时的处理原则三套体系偶尔会冲突比如CLAUDE.md说用 4 空格缩进但 memory 里记着上次讨论决定改用 2 空格。这时候怎么办我的处理原则是权限 项目约定 个人记忆。也就是说settings.json的硬性限制永远优先其次是CLAUDE.md的项目约定最后才是 memory 的个人记忆。因为权限是安全底线项目约定是团队共识个人记忆只是参考。如果发现 memory 和CLAUDE.md长期冲突那说明要么 memory 过时了该清理要么CLAUDE.md该更新了。冲突本身是个信号提示你该整理配置了。5.3 团队协作下的配置分工在团队场景里我推荐这么分工配置谁维护放什么提交仓库settings.json 项目级技术负责人项目必需的权限、钩子是settings.json 用户级每个人自己个人偏好、本地环境否CLAUDE.md 项目级技术负责人项目约定、命令、坑是CLAUDE.md 用户级每个人自己个人通用习惯否memory每个人自己个人记忆、进度否这个分工的核心是团队共享的进仓库个人独有的留本地。这样既保证了团队一致性又不牺牲个人灵活性。我见过反面案例有人把个人 memory 也提交到仓库结果别人拉下来之后模型行为变得很奇怪因为读到了不属于自己的记忆。这种坑一定要避免。6. 常见问题与排查技巧实录6.1 配置不生效的排查顺序配置改了不生效是最常见的问题。我的排查顺序是这样的确认文件位置对不对。项目级配置必须在项目根目录的.claude/下放错地方等于没放。确认优先级。是不是被更高优先级的配置覆盖了用命令查看实际生效的配置。确认加载时机。有些配置需要重启会话才生效改完不重启等于没改。确认语法。JSON 格式错一个逗号就整个文件失效用工具校验一下。确认权限。文件权限不对可能导致读不到尤其是团队共享的配置。这个顺序是从最容易错到最不容易错排的按这个顺序查八成问题在前两步就能定位。6.2 权限被拒的典型场景权限被拒的报错信息有时候很模糊让人摸不着头脑。我整理了几个典型场景现象可能原因解决方向明明 allow 了还是被拒deny 优先级更高检查 deny 规则路径匹配不上相对路径基准不对确认是相对项目根命令族被整体拦通配符粒度太粗细化到子命令企业级锁定上层强制策略联系管理员我印象最深的一次是 allow 里写了Bash(npm test)但实际执行的是Bash(npm run test)两者不匹配所以被拒。这种细节问题只能靠仔细核对命令的实际形式来解决。6.3 memory 膨胀导致的问题memory 用久了会膨胀膨胀到一定程度会拖慢会话启动甚至干扰模型判断。症状包括会话开始变慢、模型经常提到不相关的老信息、回复里混入过时内容。解决办法就是定期清理。我的清理节奏是每周扫一眼每月大清理一次。清理时按是否还准确、是否还用得上、是否该升级三个标准过一遍。这个习惯坚持下来memory 一直保持在健康状态。提示清理 memory 前最好备份一下万一删错了还能找回来。我有一次手快删了一条重要决策记录结果后面几天模型一直重复建议已经被否决的方案折腾了好久才想起来是 memory 被清了。6.4 多项目环境下的配置隔离同时维护多个项目时配置隔离是个大问题。我的做法是用户级配置放通用偏好所有项目共享。项目级配置各自独立互不干扰。memory 按项目分文件避免串味。这样切换项目时通用偏好自动继承项目特有约定各自生效个人记忆不会混淆。我试过不隔离结果 A 项目的约定跑到 B 项目里模型行为完全乱套排查了半天才发现是 memory 没分文件。7. 我个人的配置演进路线回过头看我的配置体系是分三个阶段演进过来的。第一阶段是全塞一起所有东西都往一个文件里写能用但乱。第二阶段是按文件分把权限、约定、记忆分开清晰多了但还不够灵活。第三阶段是按层级分用户级、项目级、本地级各司其职这才真正顺手。如果你现在还在第一阶段我的建议是先做最简单的拆分把权限相关的挪到settings.json把项目约定挪到CLAUDE.md剩下的放 memory。这一步做完体验就会有明显提升。至于更细的层级划分可以等遇到具体问题再逐步优化。配置这东西够用就好过度设计反而增加维护成本。我见过有人把配置搞得极其复杂结果自己都记不住哪条规则在哪每次改都要翻半天这就本末倒置了。最后分享一个小技巧我会在CLAUDE.md里专门留一节叫配置说明简单记一下这个项目的三套配置各自放在哪、大概管什么。这样隔一段时间回来或者新人接手都能快速找到入口。这个习惯帮我省了不少这配置到底在哪的排查时间。