1. 三套配置体系到底在解决什么问题很多人第一次接触 Claude Code看到项目根目录下同时存在settings.json、CLAUDE.md还有一套叫 memory 的机制第一反应是懵的这三个东西看起来都在“配置”到底谁管谁改哪个才生效我一开始也踩过这个坑——把权限规则写进 CLAUDE.md结果死活不生效又把项目背景塞进 settings.json发现模型根本读不到。后来把三者的职责边界彻底理清才算是真正用顺了。先把结论摆出来这三套体系分别对应三个不同层面的问题settings.json管的是“工具怎么跑”——权限、环境变量、模型选择、钩子命令这些运行时行为属于机器层面的配置。CLAUDE.md管的是“项目是什么”——技术栈、目录结构、编码规范、常用命令属于项目层面的上下文。memory管的是“我们聊过什么、你记住什么”——跨会话的持久化记忆属于会话层面的状态。打个比方把 Claude Code 想象成一个新入职的工程师。settings.json 是他的工牌权限和办公设备配置决定他能进哪些门、能用哪些工具CLAUDE.md 是项目组发给他的《项目上手手册》告诉他这个代码库长什么样、有哪些约定memory 则是他自己的工作笔记记录上次做到哪、你偏好什么风格、哪些坑已经踩过。这三者不重叠、不替代各管一摊。搞混了就会出现“配置写了不生效”“每次都要重复交代背景”“换个会话它就把之前说好的事忘了”这类问题。下面我按这三条线逐个拆开讲把每个文件放哪、写什么、怎么写、什么时候生效全部说清楚。提示本文基于 Claude Code 的通用配置实践整理不同版本可能在字段命名上有细微差异具体以你本地claude --version对应的文档为准。核心思路是通用的。2. settings.json运行时行为的唯一入口2.1 配置文件的三层优先级settings.json 不是一个文件而是一套有优先级的多层结构。这一点非常关键因为很多人改了项目里的配置却不生效往往是被更高优先级的配置覆盖了。按优先级从高到低排列企业级托管配置由组织统一下发位置通常在系统级目录用户无法覆盖。如果你看到 “your organization has disabled claude subscription access” 这类提示多半就是这一层在起作用。用户级配置位于用户主目录下比如~/.claude/settings.json对你所有项目生效适合放个人偏好。项目级配置位于项目根目录的.claude/settings.json只对当前项目生效适合放团队共享的规则。项目本地配置.claude/settings.local.json同样只对当前项目生效但通常不纳入版本控制适合放你个人的临时覆盖。优先级高的会覆盖优先级低的同名配置项。所以当你发现项目配置没生效第一件事就是检查是不是用户级或企业级把它盖掉了。2.2 核心字段逐个拆解settings.json 里最常用的几类字段我按使用频率排一下权限控制permissions是最常改的部分。它决定 Claude Code 能自动执行哪些操作、哪些需要你确认。典型结构长这样{ permissions: { allow: [ Bash(npm run test:*), Bash(git status), Read(./src/**) ], deny: [ Bash(rm -rf:*), Read(./.env) ] } }allow列表里的操作会被自动放行不用每次点确认deny列表里的操作直接被拒绝。这里有个细节规则是按模式匹配的Bash(npm run test:*)里的:*表示匹配所有以npm run test开头的命令。写得太宽会带来风险写得太窄又天天弹确认需要平衡。环境变量env用来给 Claude Code 运行时注入变量比如指定 API 端点、代理设置、日志级别等。注意这里不要放敏感密钥的明文尤其是项目级配置会进版本库的情况。模型选择model指定默认使用哪个模型。如果你在本地用 LM Studio 跑模型可以通过配置把请求指向本地端点这样就能用本地模型驱动 Claude Code适合对数据出境敏感或者想省成本的场景。钩子hooks是进阶玩法允许你在特定事件前后自动执行命令比如每次工具调用前跑一次格式化、每次会话结束前跑一次测试。钩子写不好容易拖慢整个流程建议先用简单命令验证。2.3 实操从零写一份可用的 settings.json我一般按这个顺序来配。先建目录mkdir -p .claude touch .claude/settings.json然后从最小可用配置开始不要一上来就堆一大堆规则{ permissions: { allow: [ Bash(git status), Bash(git diff:*), Bash(npm run lint), Bash(npm run test:*) ], deny: [ Read(./.env), Read(./secrets/**), Bash(curl:*) ] }, env: { NODE_ENV: development } }写完保存重启会话让它生效。然后故意触发一条 allow 里的命令和一条 deny 里的命令确认行为符合预期。这一步别省我见过太多人配完不验证结果真到用的时候发现规则写错了。注意deny的优先级高于allow。如果同一条命令同时命中两个列表以拒绝为准。所以别指望用 allow 去“解锁”被 deny 的东西。2.4 权限规则的常见坑第一个坑是通配符滥用。有人图省事写Bash(*)等于把所有命令都放行了这跟不设权限没区别。正确做法是按命令前缀精确到子命令级别。第二个坑是路径写法。Read(./src/**)里的./是相对于项目根目录的不是相对于你当前 shell 的工作目录。写绝对路径反而容易在不同机器上失效。第三个坑是本地配置误提交。settings.local.json应该加进.gitignore否则你个人的临时放行规则会被推到团队仓库别人拉下来一脸懵。3. CLAUDE.md让模型秒懂你的项目3.1 它和 README 的本质区别README 是写给人看的CLAUDE.md 是写给模型看的。这个区别决定了写法完全不同。README 可以有大段介绍、徽章、截图CLAUDE.md 要的是高信息密度、无歧义、可执行。模型读 CLAUDE.md 的方式是把它塞进上下文所以每一句话都在消耗 token。写废话等于浪费预算还可能稀释真正重要的信息。我的原则是能一句话说清就不写两句能用列表就不写段落能举例就不抽象描述。3.2 一份高质量 CLAUDE.md 的骨架我常用的结构是这样的你可以直接抄# 项目名称 ## 技术栈 - 语言TypeScript 5.x - 框架Next.js 14App Router - 包管理pnpm - 测试Vitest Playwright ## 目录结构 - src/app路由与页面 - src/components可复用组件 - src/lib工具函数与业务逻辑 - tests测试文件 ## 常用命令 - 安装依赖pnpm install - 开发pnpm dev - 测试pnpm test - 构建pnpm build ## 编码规范 - 组件用函数式不用 class - 状态管理优先用 hooks不引入额外库 - 提交信息遵循 Conventional Commits ## 注意事项 - 不要修改 src/generated 下的文件那是自动生成的 - 环境变量从 .env.local 读取不要硬编码这份骨架覆盖了模型最需要的四类信息技术栈、结构、命令、约束。有了它模型不用每次问你“这个项目用什么框架”“测试怎么跑”直接就能上手。3.3 写 CLAUDE.md 的五个实操心得第一命令要写全。别只写“跑测试”要写清楚是pnpm test还是pnpm test:unit有没有 watch 模式。模型不会猜你写什么它用什么。第二约束要具体。“代码要整洁”这种话等于没说。“不要用 any 类型”“导入顺序按字母排”才是可执行的约束。第三别写会变的东西。版本号、依赖列表这类频繁变动的内容写进去很快就过时反而误导模型。让它自己去读 package.json。第四分层组织。如果项目很大可以在子目录放额外的 CLAUDE.md模型进入那个目录时会读取对应的文件。这样根目录的保持精简细节下沉到子目录。第五定期清理。项目演进后CLAUDE.md 里会有过时信息。我一般每个迭代周期过一遍删掉不再适用的条目。过时的上下文比没有上下文更糟。3.4 一个真实的反面案例我见过有人把整个 API 文档贴进 CLAUDE.md几千行。结果每次会话光加载这个文件就吃掉大量上下文真正干活的空间被挤没了模型还经常被无关信息干扰。正确做法是CLAUDE.md 里只写“API 文档在 docs/api.md需要时去读”把大块内容留在外部文件按需加载。这就是所谓的渐进式披露——先给索引再按需展开。4. memory跨会话的持久化记忆4.1 memory 到底存了什么memory 机制解决的是一个很实际的问题每次开新会话模型都是“失忆”的。你昨天跟它说好的偏好、踩过的坑、项目的特殊约定今天它全忘了。memory 就是把这些跨会话需要保留的信息持久化下来。它通常存三类东西用户偏好你喜欢简洁回答还是详细解释习惯用哪种提交信息格式讨厌哪些写法。项目事实这个项目有哪些非显而易见的约定比如“测试环境数据库是只读的”。历史决策之前为什么选了方案 A 而不是 B避免重复讨论。注意 memory 和 CLAUDE.md 的区别CLAUDE.md 是团队共享的项目上下文memory 更偏向个人或会话层面的积累。CLAUDE.md 是“这个项目是什么”memory 是“我们之间发生过什么”。4.2 memory 的写入与读取时机memory 一般有两种写入方式。一种是模型在对话中主动判断“这条信息值得记住”然后写入另一种是你显式要求它记住某件事。读取则通常发生在会话开始时把相关记忆加载进上下文。这里有个关键点memory 不是越多越好。存太多无关记忆每次会话都要加载既费 token 又容易干扰。我一般只让它记三类反复出现的偏好、容易忘的项目约定、影响决策的历史原因。一次性的信息不记。4.3 管理 memory 的实用技巧定期审查。memory 会累积时间长了会有过时或矛盾的条目。我习惯每隔一段时间让它列出现有记忆手动清理。写具体别写抽象。“用户喜欢好代码”没用“用户要求所有异步函数必须处理错误”才有用。区分临时和永久。有些信息只在当前任务有效不该进长期记忆。比如“这次重构先不动测试”任务结束就该清掉。注意安全边界。memory 里不要存密钥、token、个人隐私信息。这些一旦写入后续会话都可能被带出来。提示如果你在团队环境使用注意 memory 的存储位置和共享范围。个人记忆和团队共享记忆要分清楚别把私人偏好写进团队共享区。5. 三套体系如何协同工作5.1 一次会话的完整加载流程把三者串起来看一次典型会话的加载顺序大致是启动时读取各层 settings.json合并出最终的运行时配置权限、环境变量、模型。加载项目根目录及当前目录链上的 CLAUDE.md构建项目上下文。读取 memory加载相关历史记忆。三者一起塞进上下文模型开始工作。理解这个顺序很重要。比如你发现某个权限没生效就知道要去查 settings 的合并结果发现模型不了解项目就去查 CLAUDE.md 有没有被正确加载。5.2 职责边界速查表需求该改哪个原因放行某条命令免确认settings.json属于运行时权限告诉模型项目用 pnpmCLAUDE.md属于项目上下文记住用户偏好简洁回答memory属于跨会话偏好指定本地模型端点settings.json属于运行时配置说明某目录是自动生成的CLAUDE.md属于项目事实记录上次重构到哪了memory属于会话状态这张表我建议存下来遇到“这个该写哪”的疑问时对照一下基本不会错。5.3 常见误配与纠正误配一把权限规则写进 CLAUDE.md。模型读到“允许执行 npm test”这句话但它不会因此获得权限权限只认 settings.json。纠正权限归 settings。误配二把项目技术栈写进 memory。技术栈是项目事实应该团队共享放 memory 只有你自己能看到换个人就丢了。纠正项目事实归 CLAUDE.md。误配三把个人偏好写进项目 CLAUDE.md。你的个人习惯不该强加给团队。纠正个人偏好归 memory 或用户级 settings。误配四settings.json 里塞大段说明文字。settings 是结构化配置不是文档。纠正说明性内容归 CLAUDE.md。6. 排查与调优实战6.1 配置不生效的排查顺序遇到配置不生效按这个顺序查基本能定位确认文件位置对不对。项目级在.claude/settings.json用户级在主目录别放错。检查优先级。是不是被更高层的配置覆盖了。检查 JSON 语法。少个逗号、多个括号都会导致整个文件被忽略。重启会话。很多配置是启动时加载的改完不重启不生效。看日志。启动时通常有配置加载的日志能看出读了哪些文件。6.2 上下文膨胀的调优用久了会发现会话越来越慢多半是上下文膨胀。三个调优点精简 CLAUDE.md删掉过时和冗余内容大块文档移到外部按需读取。清理 memory删掉一次性信息和过时偏好。拆分项目配置大项目用子目录 CLAUDE.md避免根目录文件过大。6.3 常见问题速查现象可能原因解决权限规则不生效被高层配置覆盖检查优先级模型不懂项目CLAUDE.md 未加载确认文件位置与语法每次都要重复交代memory 未写入显式要求记住会话变慢上下文膨胀精简三套配置本地模型连不上端点配置错误检查 settings 的模型配置团队规则冲突本地配置误提交检查 .gitignore6.4 我踩过的三个坑坑一以为改了 CLAUDE.md 立刻生效。实际上它是在会话启动时加载的改完得重开。我有次改了半天没反应重启后才发现早就生效了。坑二memory 存了敏感信息。早期图方便让它记住了一个测试用的 token后来发现它会时不时带出来。现在我对写入 memory 的内容非常谨慎。坑三权限规则写太宽。一开始为了省事放行了整个Bash(git:*)结果它有次直接执行了git push --force。现在我只放行只读类 git 命令写操作一律手动确认。7. 进阶把三套体系用出组合拳7.1 团队协作下的配置分层团队场景下我的做法是项目级 settings.json 放团队统一的权限基线CLAUDE.md 放项目上下文个人偏好全部下沉到用户级配置和 memory。这样新人拉下代码就能用不用挨个问“你那个配置怎么写的”。具体分工项目级 settings.json只放团队共识的权限规则比如放行 lint 和 test拒绝危险命令。项目级 CLAUDE.md技术栈、结构、命令、规范全员共享。用户级 settings.json个人模型偏好、本地端点。memory个人工作习惯和历史积累。7.2 用钩子打通配置与流程settings.json 的钩子能力可以把三套体系串起来。比如会话结束时自动把本次的关键决策写入 memory或者每次提交前自动跑 CLAUDE.md 里定义的检查命令。这类自动化能省掉大量手动操作但要注意钩子命令本身要足够快否则会拖慢整个流程。7.3 本地模型场景的配置要点如果你用本地模型驱动settings.json 里的模型端点配置是核心。要点是确认端点地址和端口正确确认模型名称匹配确认本地服务已启动。CLAUDE.md 和 memory 的用法不变因为它们只影响上下文不影响请求发往哪里。我在本地模型上实测下来CLAUDE.md 的作用更明显——本地模型对项目上下文的理解能力弱一些一份清晰的 CLAUDE.md 能显著提升它的表现。所以本地场景下值得在 CLAUDE.md 上多花点功夫。7.4 配置的版本管理策略最后说个容易被忽略的点这三套配置里哪些该进版本库哪些不该。该进项目级 settings.json、CLAUDE.md。这是团队共享的。不该进settings.local.json、个人 memory。这些是个人私有的。.gitignore里加上.claude/settings.local.jsonmemory 的存储位置因实现而异如果它在项目目录下也要一并忽略。搞错这个轻则团队仓库里混进个人配置重则敏感信息泄露。配置这东西说到底是为了让工具更贴合你的工作方式。三套体系各司其职理清边界之后剩下的就是按自己的习惯慢慢调。我现在的做法是新项目先写一份精简的 CLAUDE.md权限规则从最小集开始按需加memory 只记真正会复用的东西。这套组合用下来基本不用再为“它怎么又不懂了”这种事分心。