Claude Code 用了一段时间之后我发现一个挺普遍的现象很多人把它装好、跑通一个 hello world 之后就停在那个状态了。问起来就是能用就行但真到项目里一用问题全冒出来了——每次对话都要重新交代项目背景团队里每个人的行为不一致换个目录就忘了之前定好的规矩。这些问题的根子其实都指向同一件事没搞明白 Claude Code 的配置体系到底是怎么分层的。我自己也是踩了一圈坑才理清楚。最开始我以为配置就是改改 settings.json后来发现光有它根本不够再后来往 CLAUDE.md 里塞了一堆东西结果又和 memory 的机制打架。这三套东西——settings.json、CLAUDE.md、memory——各自管什么、优先级怎么排、什么时候该用哪个是真正决定你用得顺不顺的分水岭。这篇就把我理解的这套体系完整拆一遍从每个文件的作用边界到它们之间的协作关系再到实际项目里怎么组合使用尽量讲透。不管你是刚装好 Claude Code 想认真用起来还是已经用了一阵但总觉得哪里别扭应该都能从里面找到对应的答案。1. 三套配置体系到底在解决什么问题在具体讲每个文件之前得先把为什么需要三套这件事说清楚。很多人第一反应是配置嘛一个文件搞定不就行了搞这么多层不是自找麻烦我一开始也这么想直到被现实教育了几次才明白这三套东西解决的是三个完全不同维度的问题硬塞进一个文件反而会乱套。1.1 从每次都要重新交代这个痛点说起最直观的痛点就是重复沟通。你打开 Claude Code想让它帮你改一个项目里的函数结果它不知道这个项目用什么语言、什么框架、代码风格是什么、测试怎么跑。你得先花一段话把这些背景交代清楚它才能开始干活。下一次开新会话同样的背景又得再说一遍。这种重复劳动在单个小脚本里还能忍一旦项目稍微复杂点光是交代背景就消耗掉大量 token 和耐心。这个问题的本质是有些信息是跨会话、跨任务都成立的它不应该属于某一次对话而应该属于这个项目或者我这个使用者。CLAUDE.md 和 memory 就是来解决这个层面的问题的只不过一个偏向项目维度的约定一个偏向个人维度的记忆。1.2 权限、模型、工具开关为什么必须单独放另一类问题跟背景知识完全不是一回事。比如你希望 Claude Code 在执行某些命令前先问你一声或者你公司环境里只能用某个特定的模型端点又或者你想关掉某个你不需要的工具。这些是运行时行为控制它们的特点是跟具体项目内容无关跟对话内容也无关纯粹是这个工具该怎么运行的设定。这类东西如果写进 CLAUDE.md会非常别扭——CLAUDE.md 是给模型读的自然语言上下文而权限开关是给程序读的结构化配置。两者混在一起既不好维护模型也未必能正确理解。所以 settings.json 承担的就是这个角色它是机器读的配置管的是工具本身的行为。1.3 三者的分工边界一张表看清我把这三者的核心区别整理成了一张表先有个整体印象后面再逐个展开维度settings.jsonCLAUDE.mdmemory读取方Claude Code 程序本身模型作为上下文模型作为持久记忆内容形式结构化 JSON自然语言 Markdown自然语言条目作用范围工具运行时行为项目级约定跨项目个人偏好典型内容权限、模型、环境变量、工具开关项目结构、编码规范、常用命令个人习惯、通用偏好、历史结论生效时机启动/运行时会话加载项目时会话加载时注入是否进上下文否是是优先级关系决定工具怎么跑决定模型怎么看项目决定模型怎么看你看懂这张表其实三者的边界就清楚了settings.json 管工具怎么运行CLAUDE.md 管这个项目是什么样memory 管我这个人是什么样。三者各司其职谁也替代不了谁。提示很多人把三者混用的根源是没区分给程序读和给模型读。记住这条线大部分配置该放哪就清楚了。2. settings.json工具运行时行为的控制中枢settings.json 是我建议第一个搞明白的文件因为它直接决定 Claude Code 这个工具本身怎么跑。它不参与对话内容但它的每一个字段都在悄悄影响你的使用体验。2.1 文件位置与层级覆盖逻辑settings.json 不是只有一个它存在多个层级从高到低大致是这样的覆盖关系用户级配置放在用户主目录下的配置目录里对你所有项目生效适合放个人通用偏好。项目级配置放在项目根目录的配置目录里只对这个项目生效适合放项目特定的设定。本地覆盖配置项目里通常会有一个不进版本控制的本地配置文件用来放你个人的、不想提交给团队的覆盖项。覆盖逻辑是就近原则越靠近当前项目的配置优先级越高。也就是说项目级会覆盖用户级本地覆盖又会盖过项目级。这个设计的好处是团队可以约定一套项目级配置提交到仓库而每个人又能用自己的本地配置做个性化调整互不干扰。我踩过的一个坑是早期我把个人偏好全写进了项目级配置结果提交上去之后团队里其他人拉下来全被我的设定影响了。后来才改成——团队共享的放项目级个人的放用户级或本地覆盖。这个习惯养成之后协作就顺畅多了。2.2 权限控制allow / deny / ask 的实际用法权限控制是 settings.json 里最实用的部分。它让你能精细地规定哪些操作可以直接放行哪些必须经过你确认哪些直接禁止。核心是三个列表allow白名单列在这里的操作直接执行不再询问。deny黑名单列在这里的操作直接拒绝连问都不问。ask灰名单列在这里的操作每次都要你确认。举个实际场景。如果你经常让 Claude Code 跑测试命令每次都弹确认会很烦那就可以把测试命令加进 allow。反过来像删除文件、强制推送这类危险操作就应该放进 deny 或者至少 ask给自己留一道保险。{ permissions: { allow: [ Bash(npm run test:*), Bash(git status), Bash(git diff:*) ], ask: [ Bash(git push:*) ], deny: [ Bash(rm -rf:*), Bash(git push --force:*) ] } }这里有个细节值得说通配符的写法很关键。Bash(npm run test:*)里的:*表示匹配这个前缀开头的所有命令。如果你只写Bash(npm run test)那就只能精确匹配这一条稍微带个参数就不生效了。我一开始就是漏了通配符纳闷为什么加了白名单还是每次弹确认查了半天才发现是这个原因。注意deny 的优先级高于 allow。也就是说如果一条命令同时匹配了 allow 和 deny最终会被拒绝。这个设计是刻意的安全优先。2.3 模型与环境变量的配置细节除了权限settings.json 还能配置模型选择和环境变量。模型这块你可以指定默认用哪个模型也可以针对不同场景切换。环境变量则用来给 Claude Code 运行时注入一些必要的值比如某些工具需要的路径或者密钥引用。环境变量这块要特别小心。不要把敏感信息明文写进会提交到仓库的配置文件里。正确做法是引用系统环境变量或者放在不进版本控制的本地配置里。我见过有人把密钥直接写进项目级配置然后提交这属于典型的安全事故。{ env: { PROJECT_ROOT: /path/to/project, NODE_ENV: development } }模型配置方面如果你所在的环境需要通过特定端点访问也是在这里指定。具体字段名以官方文档为准因为这块更新比较频繁我这里只讲思路凡是工具怎么连、连哪里、用什么身份的问题都归 settings.json 管。2.4 一个容易忽略的点配置的生效时机settings.json 的改动很多情况下需要重启会话才能完全生效。我遇到过好几次改完配置发现没反应以为写错了其实是当前会话还在用旧的配置。养成改完配置重开一次的习惯能省掉不少自我怀疑的时间。另外不同层级的配置合并时是按字段深度合并的不是简单替换。也就是说项目级配置里只写了 allow用户级配置里的 deny 依然有效两者会合并。理解这一点能帮你更精确地设计各层配置的分工。3. CLAUDE.md项目级上下文的载体如果说 settings.json 是给工具看的那 CLAUDE.md 就是给模型看的。它是你向模型介绍这个项目是什么、该怎么在这个项目里干活的主要渠道。用得好能极大减少每次对话的重复交代用得不好就是一堆没人看的废话。3.1 CLAUDE.md 应该写什么、不该写什么先说什么该写。CLAUDE.md 的核心价值是提供模型无法从代码里直接推断出来的信息。比如项目的整体架构和模块划分尤其是那些从目录结构看不出来的设计意图。编码规范和风格约定比如命名习惯、注释要求、错误处理方式。常用的开发命令比如怎么跑测试、怎么构建、怎么启动本地环境。一些潜规则比如某个目录是自动生成的不要手动改某个文件有特殊含义。再说说什么不该写。我见过有人把 CLAUDE.md 写成了项目文档的复制粘贴几百行流水账。这有两个问题一是浪费上下文窗口二是重点被淹没模型反而抓不住关键。CLAUDE.md 要的是精炼的、可操作的约定不是完整的项目说明书。还有一个常见误区把本该放 settings.json 的东西写进来。比如执行删除命令前要确认这种写进 CLAUDE.md 模型可能会遵守但它不如 settings.json 的 deny 规则可靠——因为前者靠模型自觉后者是程序强制。能用程序强制的就别靠模型自觉。3.2 怎么写才能让模型真正读懂CLAUDE.md 是自然语言但写法有讲究。我的经验是用短句和列表别写大段散文。模型对结构化的内容理解更准。把最重要的约定放前面。上下文是有注意力衰减的开头的内容权重更高。给具体例子别只给抽象规则。比如与其说遵循项目的命名规范不如直接写组件文件用 PascalCase工具函数用 camelCase。明确边界。哪些目录可以改哪些不能碰写清楚。一个我常用的结构是这样的# 项目约定 ## 技术栈 - 语言TypeScript - 框架React Vite - 测试Vitest ## 常用命令 - 开发npm run dev - 测试npm run test - 构建npm run build ## 编码规范 - 组件用函数式不用 class - 所有导出函数必须有 JSDoc 注释 - 错误处理统一用 Result 类型不抛异常 ## 注意事项 - src/generated/ 目录自动生成不要手动修改 - 提交前必须跑通 npm run test这个结构不复杂但覆盖了模型最需要知道的几件事。实测下来有了它之后新会话里模型基本能直接进入状态不用我再从头交代。3.3 多层级 CLAUDE.md 的叠加规则和 settings.json 类似CLAUDE.md 也支持多层级。通常有用户级的放个人通用约定和项目级的放项目特定约定。加载时两者会叠加项目级的通常优先级更高或者放在更靠后的位置。这个机制的实际意义是你可以把我个人所有项目都遵循的习惯放用户级把这个项目特有的约定放项目级。比如你个人习惯用某种提交信息格式这是跨项目的放用户级而这个项目用的是特定的测试框架放项目级。这样既避免了重复又保证了针对性。我自己的做法是用户级 CLAUDE.md 保持极简只放真正跨项目的个人偏好项目级 CLAUDE.md 才是重点写得详细一些。因为项目级的约定往往更具体、更影响实际产出。3.4 维护 CLAUDE.md 的节奏感CLAUDE.md 不是写完就一劳永逸的。项目在演进约定也会变。我的习惯是每次发现模型在某个点上反复出错就回头看看是不是 CLAUDE.md 里没写清楚或者写的方式有问题。这其实是一个持续调优的过程。另外CLAUDE.md 最好纳入版本控制跟代码一起走。这样团队里每个人的模型行为是一致的新人拉下来也能立刻获得正确的项目上下文。这一点在多人协作里特别重要——没有统一的 CLAUDE.md每个人喂给模型的背景都不一样产出自然参差不齐。4. memory跨会话的个人记忆层memory 是这三套体系里最容易被忽视、但用好了收益很大的一层。它和 CLAUDE.md 的区别在于CLAUDE.md 是项目的记忆memory 是你的记忆。4.1 memory 和 CLAUDE.md 的本质区别很多人分不清这两个我一开始也是。后来想明白了一个判断标准这条信息是跟着项目走的还是跟着我走的跟着项目走的这个项目用什么框架、有什么约定、怎么跑测试——放 CLAUDE.md。跟着我走的我习惯用中文回复、我喜欢简洁的代码风格、我讨厌过度注释——放 memory。举个例子这个项目用 Vitest是项目属性换个人来这个项目也一样放 CLAUDE.md。我偏好用中文交流是个人属性我换到任何项目都成立放 memory。这个区分看似简单但实际用起来能避免大量混乱。4.2 memory 里放什么最划算memory 的价值在于一次记录处处生效。所以最划算的内容是那些你反复要交代的个人偏好。比如语言偏好回复用什么语言代码注释用什么语言。风格偏好喜欢详细解释还是直接给代码喜欢保守改动还是激进重构。工作习惯改代码前是否要先看测试是否要先解释思路再动手。通用结论某些你验证过的、跨项目成立的技术判断。我自己的 memory 里就记了几条比如改代码前先说明改动范围、优先给可运行的完整代码而不是片段。这些记进去之后新会话里模型会自动遵守省了我每次重复。提示memory 不是越多越好。记太多会稀释重点也可能引入过时的偏好。定期清理只留真正高频、真正跨项目的条目。4.3 memory 的更新与清理策略memory 是动态的会随着使用不断积累。如果不主动管理很容易变成一堆互相矛盾或者早已过时的条目。我的做法是定期回顾每隔一段时间翻一遍 memory删掉不再适用的。合并同类项如果发现好几条说的是一回事合并成一条。警惕矛盾如果两条 memory 互相冲突模型会无所适从必须解决。还有一个细节memory 的条目最好写得具体、可执行。写代码要优雅这种就是废话模型没法执行。函数不超过 50 行超过就拆分这种才是有效的。4.4 三者协作时的优先级直觉当 settings.json、CLAUDE.md、memory 三者同时存在时它们其实不冲突因为管的是不同层面。但如果硬要排个谁说了算的直觉顺序大概是settings.json 的硬性规则最高比如 deny 列表里的操作无论 CLAUDE.md 和 memory 怎么说都会被拒绝。CLAUDE.md 的项目约定次之在项目范围内项目约定优先于个人偏好。memory 的个人偏好兜底当项目没有特别约定时用你的个人偏好。这个顺序符合直觉安全规则最硬项目约定其次个人习惯最软。理解这个层次你在设计配置时就知道该把什么放哪一层了。5. 三套体系在真实项目里的组合打法前面把三者拆开讲了这一节讲怎么组合起来用。因为实际项目里你不可能只用其中一个关键是让它们各就各位、互相配合。5.1 新项目初始化时的配置顺序我接手一个新项目时配置的顺序大致是这样的先配 settings.json把权限规则定好尤其是 deny 列表先把危险操作挡住。这一步是打地基。再写 CLAUDE.md把项目结构、技术栈、常用命令、编码规范写清楚。这一步是给模型建立项目认知。最后调 memory检查一下个人偏好是否已经覆盖需要补充的补上。这一步是让模型更贴合你的习惯。这个顺序的逻辑是先保证安全再保证理解最后保证顺手。反过来先调 memory 再配权限容易在还没设防的时候出岔子。5.2 团队协作场景下的配置分工团队场景下配置的分工要更讲究。核心原则是共享的进仓库个人的留本地。settings.json项目级的权限规则、环境变量进仓库个人的覆盖项留本地。CLAUDE.md项目级的约定进仓库这是团队一致性的关键。memory纯个人层不进仓库每个人管好自己的。我见过团队因为 CLAUDE.md 不统一导致产出风格混乱的情况。A 的模型知道项目用某种规范B 的模型不知道两人让模型改同一份代码结果风格打架。统一 CLAUDE.md 之后这个问题基本消失了。5.3 常见配置冲突的排查思路配置多了冲突在所难免。我总结了一个排查思路现象可能原因排查方向权限规则不生效通配符写法错误 / 层级覆盖检查 allow/deny 的匹配模式确认哪层配置生效模型不遵守项目约定CLAUDE.md 没写清 / 被 memory 覆盖检查 CLAUDE.md 表述是否具体看 memory 有无冲突条目个人偏好时灵时不灵memory 条目矛盾 / 项目约定优先清理 memory确认项目 CLAUDE.md 是否覆盖了该偏好改配置没反应未重启会话重开会话再验证这个表是我自己踩坑总结的大部分配置问题都能归到这几类里。遇到问题先对号入座比盲目试错快得多。5.4 一套可以直接抄的配置模板最后给一套我自己在用的模板你可以直接拿去改。settings.json项目级{ permissions: { allow: [ Bash(npm run test:*), Bash(npm run lint:*), Bash(git status), Bash(git diff:*) ], ask: [ Bash(git push:*), Bash(npm install:*) ], deny: [ Bash(rm -rf:*), Bash(git push --force:*), Bash(git reset --hard:*) ] } }CLAUDE.md项目级# 项目约定 ## 技术栈 - TypeScript React Vite - 测试用 Vitest ## 常用命令 - 开发npm run dev - 测试npm run test - 构建npm run build ## 编码规范 - 组件用函数式 - 导出函数必须有 JSDoc - 错误处理用 Result 类型 ## 注意事项 - src/generated/ 不要手动改 - 提交前跑通测试memory个人级示例条目回复用中文代码注释也用中文改代码前先说明改动范围优先给完整可运行的代码而不是片段解释技术问题时先给结论再展开这套模板不复杂但覆盖了大部分日常场景。你可以根据自己的项目特点往里加但记住一个原则每一条配置都要有明确的理由不要为了配置而配置。配置这件事说到底是为了让工具更贴合你的工作方式而不是给自己增加负担。我见过有人把配置搞得极其复杂结果自己都记不住哪条在哪反而成了累赘。真正好用的配置往往是精简的、有层次的、每一层都职责清晰的。settings.json 管运行CLAUDE.md 管项目memory 管个人这三条线理清楚剩下的就是按需填充了。我自己从一团乱麻到理清这套体系花了大概两三个项目的时间希望这篇能帮你把这个过程压缩到一两个下午。