Claude Code配置体系全解：settings.json、CLAUDE.md与memory协作实践

最近在几个技术社群里看到讨论 Claude Code 配置的人越来越多。有的是嫌每次执行命令都要反复确认动不动弹出权限请求有的是换了项目以后Claude 还带着上一套项目的习惯来干活还有的是明明已经把规则写进了配置文件但它就是不按说的来。这些问题的根源其实都指向同一个地方——大家把 Claude Code 的配置体系想得太简单了以为改一个文件就能解决所有问题。实际上要让 Claude Code 真正成为“顺手”的编程伙伴至少需要理解并操作三套配置settings.json、CLAUDE.md和memory。这三者分别管着不同层面的记忆和规则settings.json管工具行为边界CLAUDE.md管项目级上下文注入memory管跨会话的长期经验沉淀。这篇文章我会从日常使用的角度把这三套体系的定位、写法、坑和协作关系完整拆开来讲适合刚接触 Claude Code 的新手也适合已经用了一段时间但总感觉哪里不对劲的人。1. 三大配置体系各自管什么从“频繁确认权限”和“每次重新交代背景”说起1.1 你重复遇到的那些问题正好对应三套配置我见过大量 Cloude Code 的使用困扰整理一下百分之八十可以归到三类工具行为不可控每次跑命令、读文件、改文件都要确认权限规则不明确模型切来切去没个章法。上下文持续丢失新开一个会话Claude 完全不知道项目是干嘛的、有哪些命令、代码结构是什么你不得不重新讲一遍背景。同样的错误反复犯上次刚纠正过它“不要用 A 方案要用 B 方案”换了个会话它又按 A 方案来。这三个问题正好对应到三套配置。settings.json解决第一类它定义的是工具自身如何运行包括默认模型、权限许可、环境变量、钩子脚本。CLAUDE.md解决第二类它是以 Markdown 文件形式存在的项目级上下文Claude 启动时会自动读取让每个新会话都能快速“了解”项目。memory解决第三类它把长期形成的偏好、决策、教训沉淀下来让 Claude 在后续协作中越来越懂你的习惯。1.2 一个通俗的类比环境变量、员工手册、老员工经验我用一个生活化的方式来理解这三者的分工。settings.json就像操作系统的环境变量。它决定了程序能不能跑、能跑多快、权限边界在哪里。你不需要每次运行都重新设置它是一种稳定的、偏底层的控制层。CLAUDE.md就像新人入职时拿到的那本《员工手册》。里面有项目背景、常用命令、代码风格约定、发布流程。新人只要认真读过一遍就能按规矩干活。Claude Code 的每个新会话本质上就是一个“新员工”所以它需要一本手册。memory像老员工脑中的长期经验。这些经验不在手册里而是通过一次次合作积累下来的比如“用户习惯用 pnpm 而不是 npm”“这个项目上次已经决定不用 TypeScript 的 namespace”“遇到这类报错直接看 service.log”。这些写不进正式文档但是有了记忆之后Claude 就会像老员工一样“省心”。1.3 常见认知误区三条错误但普遍的想法第一认为只需要改settings.json就够了。很多人改完权限和模型之后发现 Claude 还是不听话原因就是缺了上下文记忆和长期记忆。第二认为CLAUDE.md只有一个且只能放在项目根目录。其实它可以放在用户目录、项目根目录、子目录也可以多份叠加不同层级作用于不同范围。第三认为 memory 不需要管让它自己积累就好。记忆这种东西有脏数据和没有数据一样麻烦。你以为它能帮助 Claude结果它把过时的、错误的信息当成真理反而拖后腿。2. settings.json把工具行为锁在边界内2.1 全局配置与项目配置的合并逻辑settings.json的存放位置有两个一个是用户级全局配置~/.claude/settings.json一个是项目级配置.claude/settings.json。这个设计很像 Git 的~/.gitconfig和.git/config的关系——全局配置是所有项目共享的基础设施项目级配置则只对当前项目生效。两者的合并逻辑是项目级配置会覆盖全局配置里同名的字段未提及的字段沿用全局。所以一个比较稳妥的做法是在全局配置里放通用的、大多数项目都用得上的规则比如默认模型、禁止危险命令、统一的环境变量变量名在项目级配置里放跟当前项目强相关的规则比如只允许操作 src 目录、只运行某些固定脚本。这里有个很容易犯的错很多人图省事把所有项目相关的规则都写进全局配置导致换一个项目时上一套项目的上下文被带了进来。我的建议是全局配置尽量保持轻量、通用、少改动项目相关的权限和设置一律放进项目目录下的.claude/settings.json并且提交到 Git这样可以跟着项目走。2.2 值得优先配置的核心字段settings.json里的字段不多但每个都有用。以下是我实际使用中觉得优先级最高的几个字段作用配置建议model设置默认使用的模型固定到团队统一使用的模型避免各人设置不一致permissions配置工具权限allow/deny越具体越好尽量不用宽泛通配符hooks在工具执行前后触发外部脚本适合做代码格式化、日志记录、安全检查env注入环境变量适合配置本地服务地址、专用配置路径apiKeyHelper自定义获取 API 密钥的脚本适合团队有内部密钥管理系统的场景includeCoAuthoredBy是否在提交信息中加入共同作者视团队规范而定model这个字段值得多说一句。Claude Code 官方支持通过配置切换模型团队内如果统一模型可以避免不同人用不同模型导致的行为差异。如果你是在折腾本地模型常常需要在env里配置指向本地服务的环境变量比如设置自定义的 API 地址和 key这些也属于settings.json的管理范围。注意不同版本对字段名可能有差异以官方文档为准。2.3 从“每次询问”到“静默执行”permissions 配置实例权限配置是settings.json里最影响日常体验的部分。默认情况下Claude Code 对一些操作会弹确认框比如执行 Bash 命令、写入文件、删除文件。确认框本质上是一道安全防线但如果每次都点合作流畅度会大打折扣。我们可以通过permissions字段先把信任的操作“放行”。比如下面这个配置{ permissions: { allow: [ Bash(npm run test), Bash(npm run build), Read(webpack.config.js), Edit(src/**) ], deny: [ Bash(rm -rf *), Bash(git push --force) ] } }这里的关键是精确。Bash(npm run test)只允许执行这个具体命令而不是允许所有 Bash 操作Edit(src/**)允许改src目录下的文件但没有放开整个项目。通配符要克制越宽泛的 allow 规则意味着越高的误操作风险。我踩过的坑是早期为了省事直接在allow里写了Bash结果 Claude 在做一个重构任务时自己跑了一条我没有预期到的系统命令。虽然没造成事故但那种“失控感”很强。后来我把规则缩到指定命令和指定目录体验反而更好——因为它会停下来问我而不是擅自行动。2.4 为什么不要把项目规范写进 settings.json这是一个很常见的误区。有人会在settings.json里写“本项目使用 pnpm”“代码风格按照 ESLint 配置”“这个项目禁止使用 any”之类的说明希望 Claude 能遵守。但settings.json本质是工具行为配置不是上下文说明。它确实也能影响 Claude 的一部分行为但如果把项目规范塞进去会出现两个问题一是全局配置会被污染。你在项目 A 写的规范可能通过全局配置影响项目 B。二是 Claude 对settings.json的语义理解是“工具怎么执行”而不是“项目是什么样”所以它的行为遵循度远不如在CLAUDE.md里明确描述。项目规范的正确去处是下面要讲的CLAUDE.md。3. CLAUDE.md项目记忆的信息架构3.1 它到底如何被加载位置与继承关系CLAUDE.md是 Claude Code 中最接近“项目记忆”的文件。它会在会话启动时被自动读取并注入到对话上下文中让 Claude 一开始就知道自己在哪个项目里、这个项目怎么运转。存放位置很关键。可以放在这几个地方~/.claude/CLAUDE.md用户全局记忆适用于所有项目的通用规则。比如“写代码前先检查测试”“提交信息要遵循 Conventional Commits”。项目根目录下的./CLAUDE.md整个项目共享的上下文。子目录里的./subdir/CLAUDE.md只对当前目录及其子目录生效。当你在子目录运行 Claude Code 时会同时加载这个子目录的CLAUDE.md和它父级目录的文档。我在实际项目中会把全局CLAUDE.md写成“通用的工作偏好”项目根目录的CLAUDE.md写成“这个项目的全貌”子目录的CLAUDE.md则专门写某块业务的独特约束。这样做的好处是不同范围的记忆各司其职不至于所有内容都堆在一个文件里。需要注意的是官方文档对这些文件加载顺序的描述比较清晰当前工作目录向上找到的CLAUDE.md会被加载如果有多个层级它们会叠加。如果你在子目录里写了一条和项目根目录冲突的规则不一定是谁覆盖谁而是都可能出现在上下文里。所以命名和表述要清晰避免同一件事在多个文件里说法不一样。3.2 一个好用的 CLAUDE.md 应该写什么很多人第一次写CLAUDE.md时要么写三行“这是某某项目”就结束要么写几千字的详细文档把 Claude 的上下文窗口塞得满满的。这两种都不可取。我现在的模板一般包含六个部分项目一句话简介让 Claude 在 3 秒内明白这个项目的定位。常用命令这是最重要的部分。比如pnpm dev、pnpm test、pnpm build。Claude 只有知道这些命令才能真正派上用场。代码结构说明主要目录的作用新模块应该放在哪里。架构与设计约定比如是否使用依赖注入、状态管理方案是什么、路由怎么组织。工作流与发布流程分支命名、测试要求、打包部署步骤。避坑清单记录这个项目里最容易踩的坑。比如“不要直接改数据库表结构必须走 migration”。给出一个简短的示例# 项目名content-platform ## 简介 内容发布平台后端负责文章管理、审核流、CDN刷新。 ## 常用命令 - pnpm dev 启动本地开发服务 - pnpm test 跑单元测试 - pnpm lint 检查代码风格 - pnpm storybook 启动组件预览 ## 代码结构 - src/modules/ 按业务域划分模块 - src/shared/ 公共 UI 组件与工具函数 - src/db/migrations/ 数据库迁移脚本 - docs/adr/ 架构决策记录 ## 设计约定 - 所有接口返回统一格式 { code, data, message } - 新业务必须走 Feature Flag不能直接全量上线 - 禁止使用 var统一 ESM 模块规范 ## 避坑清单 - 不要直接改数据库表结构必须使用 migration 文件 - pnpm test 需要先启动 mock server见 scripts/mock-server.ts注意不要把那些经常变动的工具版本、临时任务、敏感账号密码写进CLAUDE.md。它会成为上下文的一部分一旦过时反而会误导 Claude。3.3 让 CLAUDE.md 变成“活的记忆”而不是一份死文档CLAUDE.md的另一个重要用法是记录项目中的决策过程和阶段性经验。这些内容通常不会出现在接口文档或 README 里但对 AI 协作非常关键。比如你们的项目曾经在“用 Redux Toolkit 还是 zustand”之间做过取舍最终选了 zustand并且在文档里说明了原因。把这个决策写进CLAUDE.md后Claude 在后续实现状态管理时就会主动采用 zustand而不是每次都重新纠结甚至试图自己引入另一套方案。我还会在CLAUDE.md里用“为什么”句式来写规则。比如“为什么要求所有外部 API 请求必须走http.ts封装”因为历史上有过接口地址散落各处、后来改 base URL 改到崩溃的教训。当 Claude 理解了这背后的原因它就更容易在遇到新情况时做出符合意图的决策而不只是机械照搬规则。另外CLAUDE.md也可以引用其他文档。使用文件名的方式把更详细的文档链接进去这样既能保持主文档精简又能让 Claude 需要细节时去翻对应文件。4. memory跨会话经验的沉淀与治理4.1 在这个配置体系里memory 到底是什么比起settings.json和CLAUDE.mdmemory 是更动态、更贴近“长期记忆”的一层。它记录的不是某个项目的固定信息而是在你和 Claude 的多次协作中逐渐形成的偏好、决策和教训。在我的理解里memory 本质上是一组越用越“懂你”的持久化经验。它通常以文本或目录形式存储在用户目录下通过命令或日常交互来维护。举个例子你告诉过 Claude “提交信息格式用 conventional commits”这个偏好如果只存在于某一次对话那下一次会话它就忘了。但如果沉淀到 memory 里后续所有会话都会遵守。memory 和CLAUDE.md的最大区别在于CLAUDE.md是有意识地写出来的上下文内容更像“项目档案”而 memory 更像“个人习惯与经验档案”。项目可以换但你的偏好、你的工作习惯、你常用的技术栈是跨项目通用的。所以 memory 通常放在用户级目录而不是项目目录。4.2 如何让 memory 真正生效抓准写入时机memory 不会自己长出来它需要主动维护。很多人以为用得久了它自然就丰富了但现实是如果你不让 Claude 记住关键决策它只会记住一些零散的、无关紧要的对话。我的经验是抓准几个写入时机第一当你纠正 Claude 的时候。它说错了你给了正确方向这就是最重要的记忆候选。比如“这个项目不要用any要定义具体类型”“接口请求必须走request.ts封装”。这些纠正如果不沉淀等于没说。第二当你们做了一个重要技术决策的时候。比如“模块间依赖方向只能从 domain 层指向 infrastructure 层”“前端路由改用文件式路由”。这类决策值得固化。第三当你的需求表达发生了变化的时候。比如“你现在做的这个功能优先保证性能而不是代码可读性”。这不是长期偏好但在一段时间内非常重要也值得在记忆里标记清晰。在操作层面我会把它们整理成条目化的短句避免模糊表述。比如“用户偏好 pnpm 作为包管理器”“遇到ERR_OSSL_EVP_UNSUPPORTED时检查 Node 版本是否匹配”。这种条目对 Claude 来说最容易理解和遵守。4.3 坏记忆比没有记忆更可怕清理与治理记忆最大的风险不是没有而是脏。如果一条早已过时的决策被当成真理Claude 会在新项目里做出让你匪夷所思的操作。我见过一个人因为 memory 里残留着“使用 npm 而不是 yarn”的旧偏好结果在新团队强制使用 pnpm 的项目里Claude 一直试图用 npm 安装依赖反复报错浪费了不少时间。所以 memory 需要定期审查和清理。我的习惯是每隔一段时间打开 memory 存储文件逐条问自己三个问题这条现在还成立吗如果团队已经切换了工具链或者项目已经重构就该删掉或更新。这条是事实还是临时结论临时结论不应留在长期记忆里。这条会不会造成误解如果表述过于泛化比如“用户喜欢简洁代码”这可能让 Claude 在很多场景做出错误判断不如改成“用户不喜欢过度抽象优先 readable 实现”。如果你是团队使用更建议把重要的 memory 条目纳入版本管理或者用类似 review 的方式多人确认。否则每个人的记忆只会加速“私有化”导致不同成员跑出来的 Claude 行为差异巨大。5. 三者如何协作落地读取顺序、覆盖规则和团队基建5.1 作用力方向与优先级前面分别讲了三个体系的具体配置。但实际使用中它们是协作运行的而不是孤立地各管一摊。从作用力来看我的排序是settings.json决定“能不能做”CLAUDE.md决定“现在应该做什么”memory 决定“长期倾向于怎么做”。举个例子你希望 Claude 在项目里使用pnpm installmemory 里有“用户偏好 pnpm”这个偏好CLAUDE.md里写了常用命令是pnpm installsettings.json里配置了允许Bash(pnpm install)。三者都对齐时Claude 的行为就是稳定且符合预期的。只要其中一层出现冲突比如 memory 里还残留着“用户偏好 npm”就可能导致它临时改变行为。所以在配置的时候我强烈建议你先梳理这三层各自有什么再检查它们之间有没有冲突。特别是当你新加入一个团队项目时最稳妥的操作是先看项目里的.claude/settings.json和CLAUDE.md再把自己的全局CLAUDE.md和 memory 里的偏好调成一致最后确认权限规则不会阻止必要的操作。5.2 一套可执行的初始化工作流基于上面的逻辑我总结了一个很简单的初始化流程适合接手任何项目把项目根目录.claude/settings.json创建或拉取下来先确认权限和模型。创建或补全项目根目录的CLAUDE.md把命令、结构、约定写进去。检查全局的~/.claude/CLAUDE.md和 memory 里有没有跟这个项目冲突的历史偏好。跑一条简单的只读命令例如让 Claude 读一下package.json并总结项目启动方式验证它是否读到了正确的上下文。进入真实任务观察它有没有触发不合理的权限请求或不符合项目约定的行为有则立即修正并沉淀到 memory。这套流程不会超过半小时但能避免后面很多“短期失忆”问题。5.3 高频翻车现场与处理建议结合我自己的经历和群里反馈最常见的翻车有三个第一个是权限规则过宽。settings.json里允许了所有 Bash 操作结果 Claude 在处理一个简单格式化任务时自作主张跑了一个重建索引的脚本。权限是安全底线我不建议为了“顺滑”而放弃约束。规则写得越具体它越能帮你挡住意外操作。第二个是CLAUDE.md里给了已经失效的命令。很多人复制粘贴命令时不检查比如项目早就从npm run dev改成了pnpm dev文档没更新。Claude 按照旧命令执行后自然会失败。要养成更新文档的习惯否则它会在错误的路线上反复横跳。第三个是 memory 冲突。这是最隐蔽的。你新项目要求用 pnpm但 memory 里存的是 npm 偏好。我的建议是长期使用的偏好不要写得太绝对只记录“用户在当前项目中倾向于 x”而不是“用户一直使用 x”。这样在多项目切换时能减少冲突。5.4 团队落地时的配置管理建议如果你是在团队里推广 Claude Code这套配置绝不能停留在个人层面。我记得有过一次很惨的教训团队五个人各自配置了不同的settings.json同一个指令跑出来的结果完全不一样最后只能靠人肉对齐。后来我们做了三件事.claude/settings.json和项目根目录的CLAUDE.md提交到 Git 仓库由核心维护者统一维护。全局CLAUDE.md只保留通用规则每个人可以有自己的补充文件但最少化。memory 不直接共享但团队会把关键的决策写进项目的CLAUDE.md确保核心经验不依赖个人 memory。这样做以后即使每个成员的 memory 不同项目行为也能保持在一个可控范围。Claude Code 的配置本质上是在给 AI 立规矩而规矩最好是显式、集中、可审查的。6. 最后一点使用体会我自己折腾这套配置体系花了大半个下午但后面节省的时间远超预期。最初我把所有规则都塞进settings.json后来一点点把项目信息挪到CLAUDE.md再把习惯和偏好沉淀到 memoryClaude 的行为才真正稳定下来。如果你现在还在被权限弹窗和上下文丢失折磨我建议你别急着加功能先花点时间把这三层配置理顺。配置这个东西前期花一分钟想清楚后期能少生十分钟的气。