Claude Code 三套配置体系详解：settings.json、CLAUDE.md 与 memory 的分工与实战

1. 三套配置体系到底在解决什么问题很多人第一次接触 Claude Code装完之后发现能跑但用着用着就开始别扭每次都要重复交代项目背景换个目录就忘了之前定的规矩团队里几个人用同一套代码库却各跑各的风格。这些问题的根源基本都落在三个地方——settings.json、CLAUDE.md和memory。我先把这三者的定位用一句话说清楚后面再逐个拆settings.json管的是工具本身怎么运行比如权限、环境变量、模型选择、钩子命令。它是给 Claude Code 这个程序读的配置。CLAUDE.md管的是这个项目是什么、该怎么改是写给模型看的项目说明书跟着代码库走可以提交到版本控制。memory管的是跨会话记住的东西是模型在跟你长期协作过程中沉淀下来的偏好和事实存在本地不跟着项目走。打个比方settings.json像是你给一台机器设的操作面板CLAUDE.md像是贴在项目文件夹里的施工规范memory像是你脑子里对这个合作者的长期印象。三者层级不同、生命周期不同、作用范围也不同混着用就会乱。这篇文章适合三类人看刚装完 Claude Code 还没搞明白配置放哪的新手已经能用但觉得每次都要重复交代背景、效率上不去的中级用户以及需要把 Claude Code 推广到团队、要统一规范的负责人。我会把每个配置文件的字段、优先级、实操写法、踩坑点都讲透尽量做到你照着抄就能用。需要提前说明的是Claude Code 迭代很快具体字段名和默认值可能随版本变化。我下面写的是基于常见实践和当前主流版本的整理你在实际使用时最好用claude config相关命令或官方文档再核对一遍。但配置体系的设计逻辑是相对稳定的理解了逻辑字段变了也能自己推。2. settings.json工具运行层面的总控台2.1 它到底管哪些事settings.json是 Claude Code 的运行时配置决定这个工具在你机器上以什么姿态工作。它管的东西大致分几类第一类是权限控制。哪些命令允许直接执行、哪些需要每次确认、哪些直接拒绝都在这里定。这是安全底线尤其是让模型能跑 shell 命令的时候不设权限等于把终端交出去。第二类是环境变量。比如 API 相关的地址、代理配置、超时时间还有一些功能开关。第三类是模型与行为参数。用哪个模型、温度多少、最大输出长度、是否开启某些实验特性。第四类是钩子hooks。在特定事件前后自动执行命令比如每次提交前跑一遍格式化或者会话开始时加载某些上下文。第五类是界面与交互偏好。主题、是否显示 token 用量、自动更新策略等。2.2 配置文件放在哪优先级怎么算这是新手最容易懵的地方。Claude Code 的配置有多个层级从全局到项目到本地优先级从低到高大致是层级位置作用范围是否提交版本控制全局用户配置用户主目录下的配置目录当前用户所有项目否项目共享配置项目根目录的.claude/settings.json该项目所有协作者是项目本地配置项目根目录的.claude/settings.local.json仅当前用户当前项目否应加入 gitignore企业级策略系统级策略目录整台机器所有用户由管理员维护优先级的原则是越具体越优先。项目本地覆盖项目共享项目共享覆盖全局。这个设计很合理全局放你的个人习惯项目共享放团队约定项目本地放你在这个项目里的临时调整。注意settings.local.json一定要写进.gitignore。我见过有人把带个人 API 配置的本地文件提交上去虽然多数情况不致命但把个人偏好强加给团队、甚至泄露一些本地路径信息都是不必要的麻烦。2.3 一份可直接抄的配置模板下面这份是我自己在用的一个基础模板字段做了精简你可以按需增删。注意 JSON 不支持注释我在这里用文字说明实际文件里不要写注释。{ permissions: { allow: [ Bash(git status), Bash(git diff:*), Bash(npm run lint), Bash(npm run test:*), Read(*) ], deny: [ Bash(rm -rf:*), Bash(curl:*), Bash(git push:*), Read(./.env), Read(./secrets/**) ] }, env: { NODE_ENV: development, CLAUDE_CODE_MAX_OUTPUT_TOKENS: 8192 }, model: claude-sonnet-4-5, hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write $CLAUDE_FILE_PATHS } ] } ] } }逐块解释一下为什么这么写。permissions.allow里放的是高频且低风险的操作。git status、git diff、跑 lint 和测试这些几乎每次会话都要用如果每次都弹确认体验会碎成渣。把它们放行等于给模型开了绿灯让它能自主收集信息。permissions.deny里放的是高风险或高破坏性的操作。rm -rf不用解释curl放行意味着模型可以往任意地址发请求数据外泄风险陡增git push放行意味着它可能把你的分支推上去这些都应该拦。.env和secrets目录直接禁止读取防止密钥被读进上下文。env里设CLAUDE_CODE_MAX_OUTPUT_TOKENS是个实用技巧。默认输出长度有时不够用写长文件会被截断调大一点能减少写到一半停了的情况。但也不要无脑拉满输出越长越慢越贵8192 到 16384 之间是个比较舒服的区间。hooks里的PostToolUse是重点。它的意思是每当模型用 Edit 或 Write 工具改了文件就自动跑一次 prettier 格式化。这样模型写出来的代码风格永远和项目一致你不需要在 prompt 里反复强调记得格式化。$CLAUDE_FILE_PATHS是 Claude Code 注入的环境变量指向本次被修改的文件路径。2.4 权限规则的写法与匹配逻辑权限规则不是随便写的字符串它有固定的语法。基本格式是工具名(参数模式)。Bash(git status)精确匹配这条命令。Bash(git diff:*)里的:*是通配表示git diff后面可以跟任意参数。Read(*)表示允许读任意文件。Read(./src/**)表示只允许读 src 目录下的内容。匹配是从左到右、从具体到宽泛的。如果一条命令同时命中 allow 和 denydeny 优先。这个设计是对的安全规则永远应该压过便利规则。实操心得不要一上来就把 allow 写得很宽。我的做法是先跑一段时间看模型实际请求了哪些命令把反复出现的、确认安全的再加进 allow。这样权限列表是长出来的而不是拍脑袋猜出来的既安全又贴合真实工作流。2.5 环境变量与模型选择env块里能设的东西不少但常用的就几个。除了上面说的输出长度还有超时时间、是否开启遥测、日志级别等。模型选择单独用model字段不放在 env 里。模型选择这块有个常见误区很多人以为越强的模型越好全程用最贵的。实际上日常的改 bug、写测试、重构小函数用中等模型完全够只有在做架构设计、复杂推理时才需要上最强模型。你可以通过项目级配置给不同项目设不同默认模型比如核心业务库用强模型工具脚本库用中等模型成本能省不少。2.6 钩子把重复劳动自动化钩子是settings.json里最有价值但也最容易被忽略的部分。它的核心价值是把你希望模型每次都做但模型不一定记得做的事变成系统强制执行的流程。常见的钩子场景PostToolUse匹配 Edit/Write自动跑格式化、lint 修复。PreToolUse匹配 Bash在危险命令执行前做二次校验。SessionStart在会话开始时自动加载某些文件到上下文。Stop在模型结束响应时触发通知或日志。钩子的执行是同步的命令跑完才继续。所以钩子命令要快别在里面跑全量测试否则每次改文件都卡半天。格式化、单文件 lint 这种毫秒级操作才适合放钩子。3. CLAUDE.md写给模型看的项目说明书3.1 为什么需要它和 settings.json 有什么本质区别settings.json是给程序读的CLAUDE.md是给模型读的。这个区别决定了它们的一切差异。程序读的配置要求精确、结构化、字段固定模型读的文档要求自然、清晰、信息密度高。所以CLAUDE.md就是一份 Markdown 文档你用大白话写模型能理解。它的核心作用是消除重复交代。没有它的时候你每次开新会话都要说这个项目用 pnpm 不用 npm测试跑 vitest 不是 jest组件都放 src/components 下。有了它这些信息在会话开始就自动进入上下文模型一上来就知道规矩。3.2 放在哪怎么分层CLAUDE.md支持多个位置从全局到项目用户主目录下的CLAUDE.md你的个人通用偏好所有项目生效。项目根目录的CLAUDE.md项目级规范提交到版本控制团队共享。子目录里的CLAUDE.md该子目录的局部规范模型进入这个目录时才加载。这个分层很实用。比如 monorepo 里根目录写整体架构和通用命令每个 package 子目录写自己的特殊约定。模型在处理某个 package 时会同时看到根的和子目录的规范。3.3 一份高质量 CLAUDE.md 的结构我见过很多人的CLAUDE.md写得像 README堆了一堆项目介绍但对模型真正有用的信息很少。模型不需要知道项目多牛它需要知道怎么在这个项目里干活。我推荐的结构是这样的# 项目概述 一句话说清这个项目是什么、技术栈是什么。 # 常用命令 - 安装依赖pnpm install - 开发pnpm dev - 测试pnpm test - 单测某个文件pnpm test path - 类型检查pnpm typecheck - 格式化pnpm format # 代码规范 - 用 TypeScript strict 模式 - 组件用函数式不用 class - 状态管理用 zustand不用 redux - 样式用 tailwind不写独立 css 文件 # 目录结构 - src/components通用组件 - src/features按功能划分的业务模块 - src/lib工具函数 - src/api接口封装 # 注意事项 - 不要改 package.json 里的依赖版本需要新增依赖先问我 - 所有对外接口必须有 zod 校验 - 提交前必须跑 pnpm typecheck 和 pnpm test这份结构的关键在于可执行。每一条都是模型能直接照做的指令而不是模糊的描述。用 zustand 不用 redux比使用现代状态管理方案有用一百倍。3.4 写 CLAUDE.md 的几个原则原则一写怎么做不写是什么。项目背景一两句带过就行重点放在操作指令上。模型不需要读你的产品愿景它需要知道改代码的规矩。原则二命令要具体到能复制粘贴。别写运行测试写pnpm test。别写格式化代码写pnpm format。模型会直接执行这些命令模糊描述会让它猜猜就可能猜错。原则三把不要做什么写清楚。模型默认倾向于帮忙你不明确禁止它可能就自作主张改了不该改的东西。明确列出禁区比如不要动 migrations 目录不要升级依赖。原则四保持精简。CLAUDE.md会占用上下文窗口写太长会挤占真正的工作空间。我建议控制在几百行以内只放高频、关键的信息。低频的细节可以放到单独文档里在CLAUDE.md里用链接引用。踩过的坑我曾经把整个 API 文档贴进CLAUDE.md结果上下文被占了一大半模型处理实际代码时反而变笨了。后来改成只写接口定义在 docs/api.md需要时再读效果好很多。上下文是稀缺资源要省着用。3.5 用 引用文件避免重复CLAUDE.md支持用path/to/file的语法引用其他文件。被引用的文件内容会在需要时加载进上下文。这个机制能让你把长文档拆出去保持主文件精简。比如# 数据库规范 详见 docs/database-conventions.md # API 设计规范 详见 docs/api-guidelines.md这样主文件清爽细节按需加载。但要注意别滥用引用太多文件等于没拆上下文照样爆。4. memory跨会话的长期记忆4.1 memory 和 CLAUDE.md 的区别这是最容易被混淆的一对。简单说CLAUDE.md是项目属性跟着代码库走团队共享memory是个人属性跟着你的机器走只对你自己生效。举个例子。CLAUDE.md里写这个项目用 pnpm因为这是项目的事实谁来了都得遵守。memory里记我偏好简洁的回答不要长篇解释因为这是你的个人偏好跟项目无关。memory的另一个特点是动态积累。CLAUDE.md是你手写的memory可以在协作过程中由模型主动记录也可以由你手动添加。它更像一个不断生长的笔记本。4.2 memory 存在哪怎么管理memory通常存在用户主目录下的配置目录里以文件形式保存。你可以通过 Claude Code 提供的命令查看、添加、删除记忆条目。常见的管理操作包括查看当前所有记忆用对应的 memory 列表命令。添加一条记忆用 memory 添加命令或者直接在对话里说记住这个。删除过时记忆用 memory 删除命令。具体命令名随版本变化你在终端里敲claude --help或进交互模式后敲/help能看到当前版本支持的命令。4.3 什么该记什么不该记memory用得好是神器用不好是负担。判断标准很简单这条信息是否跨项目、跨会话都成立且模型不知道会犯错。适合记进 memory 的你的技术偏好比如回答用中文代码注释用英文不要用 var。你的工作习惯比如改代码前先解释思路不要一次性改太多文件。你的环境事实比如我的 shell 是 zshNode 版本是 20。反复纠正过模型的事如果同一个错误你纠正了三次就该记下来。不适合记进 memory 的项目特定的信息这些应该放CLAUDE.md。一次性的任务细节记了也是噪音。敏感信息密钥、密码、个人身份信息绝对不要记。模型本来就知道的常识记了浪费空间。实操心得我给自己定了个规矩只有当某件事我重复交代超过两次才考虑记进 memory。这样能避免 memory 膨胀成一堆没用的碎片。定期回顾 memory 列表删掉过时的保持它精简有效。4.4 memory 的加载机制与上下文成本memory里的内容会在会话开始时加载进上下文。这意味着它和CLAUDE.md一样占用宝贵的上下文窗口。记忆越多留给实际工作的空间越少。所以 memory 的管理核心是克制。不要什么都往里塞只放真正高频、真正影响协作质量的信息。我见过有人记了几百条 memory结果模型每次会话开头就被淹没反而表现下降。一个健康的 memory 列表我建议控制在几十条以内每条一两句话。超过这个量就该考虑是不是该把某些内容整理进CLAUDE.md或者干脆删掉。5. 三套体系的协作与优先级实战5.1 一次会话里信息是怎么叠加的当你启动一次 Claude Code 会话上下文是这样拼起来的系统提示词内置你改不了。全局CLAUDE.md你的个人通用规范。项目CLAUDE.md项目规范。子目录CLAUDE.md如果当前工作目录在子目录里。memory内容你的长期记忆。当前对话。settings.json不直接进上下文它影响的是工具行为比如哪些命令能跑、跑之前要不要确认。理解这个叠加顺序很重要。当信息冲突时越靠后的越具体通常越优先。比如全局CLAUDE.md说用 npm项目CLAUDE.md说用 pnpm模型会倾向于听项目的因为项目规范更具体。5.2 一个真实项目的配置分工假设你在做一个 Next.js 项目团队五个人。配置可以这样分全局CLAUDE.md你的个人偏好# 个人偏好 - 回答用中文代码注释用英文 - 改代码前先说明思路等我确认 - 不要一次性修改超过 3 个文件项目CLAUDE.md团队共享提交到 git# 项目概述 Next.js 15 TypeScript Tailwind 的电商前台。 # 常用命令 - 开发pnpm dev - 测试pnpm test - 类型检查pnpm typecheck # 规范 - 组件用 Server Component 优先 - 数据获取用 server actions不用 useEffect - 样式只用 tailwind不写 css module # 禁区 - 不要改 next.config.js - 不要升级 next 版本项目settings.local.json你的本地调整{ permissions: { allow: [Bash(pnpm test:*), Bash(pnpm typecheck)] } }memory你的长期记忆我习惯用 pnpm 不用 npm我偏好简洁回答不要客套话这样分工团队共享的是项目事实个人保留的是个人习惯互不干扰。5.3 冲突排查当模型不听话时模型没按你预期行事排查顺序应该是先看CLAUDE.md里有没有明确写这条规矩。没写模型不知道正常。再看规矩是不是写得太模糊。模糊的规矩模型会自由发挥。再看是不是被更高优先级的配置覆盖了。最后看是不是 memory 里有冲突的旧记忆。我遇到最多的情况是规矩写得太模糊。比如写代码要整洁模型理解不了什么叫整洁。改成函数不超过 50 行嵌套不超过 3 层模型立刻就能执行。写配置的本质是把你的隐性知识显性化这需要你自己先想清楚。6. 常见问题与排查速查6.1 配置不生效怎么办现象可能原因排查方法改了 settings.json 没反应改错了层级被上层覆盖检查项目本地、项目共享、全局三层CLAUDE.md 内容没进上下文文件位置不对或文件名拼错确认在项目根目录文件名全大写权限规则不生效语法写错或 deny 覆盖了 allow用精确命令测试检查通配符memory 记了但模型不遵守记忆太多被淹没或表述模糊精简 memory把关键项写具体钩子不执行matcher 写错或命令路径不对先用绝对路径测试钩子命令6.2 权限相关的典型坑坑一allow 写太宽。比如Bash(git:*)放行了所有 git 命令包括git push --force。应该精确到子命令。坑二忘了 deny 优先。有人以为 allow 里写了就一定能跑结果 deny 里有匹配规则还是被拦。这是设计如此安全优先。坑三路径通配符用错。Read(./src/*)只匹配 src 下一层Read(./src/**)才匹配所有层级。差一个星号行为完全不同。6.3 CLAUDE.md 写作的常见误区误区一写成 README。大段项目介绍、背景故事对模型干活没帮助。删掉只留操作指令。误区二命令不具体。运行测试不如pnpm test格式化不如pnpm format。模型会照抄你写的命令写模糊了它就猜。误区三太长。超过几百行就该拆。把低频内容移到单独文档用引用。误区四只写要做什么不写不要做什么。模型默认爱帮忙不设禁区它可能改你不希望改的东西。6.4 memory 管理的经验我自己的做法是每月清一次 memory。标准是过去一个月里这条记忆有没有真正影响过协作没有就删。这样能保持 memory 精简每条都是真正有用的。另外memory 里的表述要可执行。我喜欢干净的代码是废话函数不超过 50 行才是有效记忆。写 memory 和写CLAUDE.md一样具体、可执行是关键。最后分享一个我踩过的坑我曾经把项目的数据库连接串记进了 memory想着方便。后来意识到这是严重的安全隐患赶紧删了。memory 是本地文件但一旦被读进上下文就可能出现在日志、对话记录里。任何敏感信息都不要进 memory这条底线要守住。配置体系这东西说到底是为了让模型更懂你、更懂你的项目。settings.json定规矩CLAUDE.md讲背景memory记偏好三者各司其职。刚开始可能觉得麻烦但配好之后你会发现每次会话的效率提升是实打实的。我现在的习惯是每开一个新项目先花二十分钟把这三样配齐后面省下的重复沟通时间远超这个投入。