1. 先搞清楚一个前提这三套配置到底各管什么事很多人刚开始用 Claude Code第一反应都是“这不就是个终端里的 AI 助手吗”装上以后直接在对话里甩需求让它改代码、跑命令、读日志用两天就发现一个问题同一个项目别人用起来像带了个十年的老司机自己用起来像带了个刚毕业的实习生。差别不在模型多聪明而在人家把配置体系给玩明白了。Claude Code 的配置体系可以拆成三层对应三个完全不同的“负责人”名字分别叫 settings.json、CLAUDE.md 和 memory。这三个词在官方文档里散落各处但很少有人把它们放在一起讲透更少有人能说清楚三者之间的边界。这篇文章的目标很简单把这个三角形拆开揉碎每一层管什么、怎么配、怎么排错一次讲明白。1.1 三套配置的分工一句话就能说明白先给一个总览后面每一层都会有详细拆解配置体系管的是“什么”一个合适的类比settings.json工具怎么跑权限、环境变量、钩子脚本、输出风格汽车的行车电脑决定油门响应、刹车介入CLAUDE.md模型知道什么项目命令、架构、规范、禁忌副驾驶位上的详细路线图memory跨会话记得什么技术决策、踩坑经验、个人偏好老司机的驾驶直觉越开越准这三层不是替代关系而是互补关系。settings.json 决定“允许做什么”CLAUDE.md 决定“应该怎么做”memory 决定“我记得以前是怎么做的”。把这三层分清楚后面所有配置都顺了。1.2 什么情况下这套配置会真正改变你的体验我见过太多人只把注意力放在“怎么提问”上完全忽略配置结果就是每次新开会话都要把项目背景重新交代一遍权限系统默认值不够精准导致 AI 动不动被拒绝或者乱执行项目规范形同虚设。你问它“这个项目的测试怎么跑”它给你编一个不存在的命令你让它改数据库连接配置它顺手把生产环境的读取权限也给摸了。如果你也遇到过上面任意一条说明配置体系该补课了。这篇文章适合三类人刚装好 Claude Code 想认真用起来的新手被权限问题和“模型失忆”折磨了一段时间的老用户以及想在团队里推广 Claude Code、需要把配置规范化的人。读完你至少能获得三样东西一份可以直接抄的 settings.json 模板一套 CLAUDE.md 的写法套路以及让跨会话记忆不再“一觉清零”的具体方法。1.3 动手之前先把命令行环境准备好在往下读之前先确认你手里有 Claude Code 的 CLI 环境。最快的方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完在项目目录里执行claude就能进入交互界面。如果你是 VSCode 用户也可以装对应的插件在编辑器侧边栏直接唤出会话窗口。后面要讲到的所有路径和文件全部基于这个基础环境配置逻辑在命令行和 VSCode 里完全一致。2. settings.json把权限、环境、钩子一次配齐2.1 三个配置文件的位置以及它们的优先级settings.json 不是只有一个文件按作用域从大到小一共有三个主要层级文件位置作用域典型用途~/.claude/settings.json用户级对所有项目生效全局默认权限、通用环境变量、个人钩子.claude/settings.json项目级只对当前项目生效项目专用权限、项目环境变量、团队约定.claude/settings.local.json项目级但应该被 git 忽略本地个人偏好不提交到版本库优先级规则并不复杂越是“靠近当前项目”的配置越能覆盖更大的范围。也就是说.claude/settings.local.json最高然后是.claude/settings.json最后才是~/.claude/settings.json。这个设计跟很多工具的 config 体系一脉相承目的是让团队共享的默认配置放在项目级个人习惯放在 local全局兜底放在用户级。我自己的习惯是这样分配的用户级只放两样东西——默认的权限策略和几个通用的环境变量项目级放团队约定比如只允许运行哪些脚本、禁止写哪些目录local 放我个人的 statusLine 配置和调试用的临时变量。这样既不会把自己埋在全局配置里也不会把私人设置提交到仓库污染队友。2.2 高频配置项permissions 与 defaultModepermissions 是 settings.json 里最重要的字段没有之一。它控制 Claude Code 在什么情况下可以直接执行工具、什么情况下需要向你确认、什么情况下直接拒绝。{ permissions: { allow: [ Bash(npm run *), Read(~/projects/**), Write(.claude/**) ], deny: [ Bash(sudo *), Write(prod-config/**), Edit(secrets.**) ], defaultMode: acceptEdits } }这里有几个细节值得展开。allow 和 deny 都支持带括号的规则匹配Bash(npm run *)代表“允许执行以 npm run 开头的命令”Write(prod-config/**)代表“禁止写入 prod-config 目录下的任何文件”。通配符语法跟 glob 一致*匹配当前层级**匹配任意层级这套规则能覆盖绝大多数诉求。defaultMode 我强烈建议你理解清楚。它控制默认的交互模式default表示每个需要权限的动作都会弹确认acceptEdits表示文件编辑类操作直接放行只有危险操作才询问bypassPermissions表示全部放行一般只建议在自动化和 CI 场景使用。我实测下来日常开发用acceptEdits最舒服——AI 改代码不用每次都打断你但执行系统级命令时仍然会征询同意安全感和效率兼顾。还有一个很容易被忽略的点permissions 里的路径规则是大小写敏感的而且建议统一用正斜杠相对路径。遇到过好几次“明明加了 deny 结果文件还是被改了”的诡异情况最后查出来都是路径写法没对上。如果你在 Windows 上开发或者目录命名有大小写混用这条尤其容易踩。2.3 env、hooks 和其他实用字段env 字段可以给每个会话注入环境变量等价于在 shell 里 export但更规范、更可共享。比如团队项目要求统一使用某个 API endpoint 或 feature flag写在项目级 settings.json 里谁打开都是同一套环境比各自在 .bashrc 里折腾可靠得多。{ env: { NODE_ENV: development, API_BASE_URL: https://api.example.local, LOG_LEVEL: debug } }hooks 是这三大体系里可玩性最高、但大家用得最少的部分。它允许你在 Claude Code 生命周期的关键节点挂脚本常见的有PreToolUse某个工具被调用前触发适合做安全检查或格式校验。PostToolUse工具执行后触发适合自动跑 lint 或收集结果。UserPromptSubmit用户输入提交前触发适合做敏感信息过滤。Notification异步进程完成时触发可以做桌面通知。举个例子我想在每次编辑文件之前跑一遍 prettier 校验就在项目 settings.json 里写{ hooks: { PreToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --check {file_path} || exit 98 } ] } ] } }注意退出码不是 0 时Claude Code 会判定钩子失败并阻止后续操作这个机制非常适合做“硬性门禁”。{file_path}这类占位符会在注入时替换成实际路径具体可用变量以官方文档为准但核心模型就是“在动作发生前后给你一个插一脚的机会”。另外几个实用字段也顺带说一句model可以锁定每次会话使用的模型比如团队统一用model: opusincludeCoAuthoredBy控制是否在提交信息里加入作者声明statusLine可以定制底部状态栏显示的内容outputStyle可以设置输出是纯文本还是带 rich 格式。如果不想手工维护多个 CLAUDE Code 环境的切换也可以借助 cc-switch 这类配置管理工具在不同模型端点之间快速切换本质还是读写配置文件理解清楚这里面的字段后你会用得更有底气。这些字段不一定每个人都需要但知道存在以后遇到场景能少查半天文档。3. CLAUDE.md写给模型看的项目说明书3.1 文件放哪、什么时候加载加载顺序是什么CLAUDE.md 是另一个体系它不控制工具行为而是控制模型对项目的理解。Claude Code 在启动会话时会把相应作用域下的 CLAUDE.md 注入到上下文里作为对话的背景知识。加载顺序同样分层级~/.claude/CLAUDE.md用户级全局记忆适合放通用的个人偏好和工作习惯比如“所有 commit message 用 conventional commits 规范”。项目根目录CLAUDE.md项目级记忆适合放构建命令、目录结构、技术栈约束。.claude/CLAUDE.md另一个项目级位置如果和根目录的 CLAUDE.md 同时存在两个都会读取内容合并进上下文。会话启动时模型看到这些内容就像是新入职员工第一天拿到了一本团队手册。你写得越清楚它后续的每个动作就越贴合项目实际反过来如果手册是空的它就只能靠代码内容反推规范猜错的概率相当高。有个细节值得注意CLAUDE.md 不是越大越好。它会被完整放进上下文占的是宝贵的 context window。整成一本两万字的百科全书模型反而会“看不清重点”。我的经验是把主体内容控制在 200 到 400 行而且最重要的约束放在开头因为模型对前面的内容关注度天然更高。3.2 项目说明书的核心内容与写法一份合格的 CLAUDE.md 至少要覆盖四个板块命令、架构、规范、禁忌。下面这份是我很常用的一版模板# MyProject 开发手册 ## 常用命令 - pnpm dev 启动本地开发环境端口 3000 - pnpm build 构建生产包 - pnpm test 运行单元测试改动核心模块后必须执行 ## 架构概览 - 前端代码在 web/后端代码在 server/ - 数据库访问统一走 server/repo/禁止在业务层直接写 SQL - 状态管理使用 zustand不要引入 redux ## 代码规范 - TypeScript 开启 strict 模式 - 组件命名统一 PascalCase - 错误信息输出到日志不直接 console.log ## 禁止事项 - 不要修改 dist/ 下的生成文件 - 不要在 commit 里包含 .env - 不要删除 scripts/ 下的发布脚本除非需求明确要求很多人觉得这写得有点像 README没错本质上就是在 README 基础上再加一层“给 AI 的操作约束”。区别在于README 面向人类读者而 CLAUDE.md 面向模型行为所以尽量用祈使句写“不要做什么”比写“项目是什么”更重要。我推荐的写法有一个优先级排序命令 规范 架构 业务背景。命令和规范直接决定模型会不会干蠢事架构决定它改代码时找不找得到对的位置业务背景属于锦上添花只在空间允许时再放。别把 CLAUDE.md 写成一篇优美的项目介绍散文——模型不需要文学熏陶它需要的是可执行的指令。3.3 进阶玩法imports、多文件拆分与自动化维护CLAUDE.md 支持path导入语法让你可以把内容拆到多个文件再统一引进来。这样做最大的好处是可维护性架构说明单独放docs/architecture.md命令规范放docs/commands.mdCLAUDE.md 里只留导航和核心禁忌。docs/architecture.md docs/commands.md不过这里我要提醒一个坑导入的文件同样会占上下文空间而且模型是“平铺”地读不会因为你用了目录结构就自动建立层次感。所以导入的文件也应该精简每份控制在几十行。如果发现上下文被大量无用背景填满模型的表现会肉眼可见地下降——它的注意力是有限的背景信息越多关键指令越容易被稀释。还有一个很实用的小技巧可以在 CLAUDE.md 里写“当用户问你 X 时你应该先执行 Y”这等于给模型预埋了行为触发器。比如我在项目手册里写“当用户提出要新增接口时先找出 server/repo 下对应的仓储文件并列出改动方案”实测下来非常稳定省去了每次手动引导的麻烦。另外记得让 CLAUDE.md 保持与项目同步。项目重构、命令变更之后花两分钟顺手改一下手册远比每次开会话都靠人工解释要划算。你甚至可以主动让 Claude 帮你“根据最近的代码变更更新 CLAUDE.md”它会按当前上下文起草一份 diff你再确认合并维护成本几乎可以忽略。4. memory让跨会话记忆真正可用4.1 memory 的机制和定位如果说 CLAUDE.md 是“文件化的静态记忆”那 memory 就是“运行时的动态记忆”。它的目标是解决一个特别现实的问题你今天花了三个小时让 Claude 摸清了项目套路明天新开一个会话它又回到了“你是谁、这项目是什么、上次结论是什么”的失忆状态。Claude Code 的 memory 机制会把值得跨会话保留的事实记录下来。官方的交互入口是/memory命令使用它可以查看当前保存的记忆列表也能对记忆进行管理。模型在对话中如果识别到值得长期保留的信息也会主动写入同时你可以明确告诉它“记住这一点”让某些关键决策沉淀下来。从文件系统的视角看这些记忆通常落在~/.claude/projects/项目标识/下的会话或记忆目录里以结构化的形式存储。你用/memory看到的内容本质上是这些持久化记录的可视化结果。实际存储格式和字段会随版本迭代调整不需要去手工改用命令管理就够了。我个人的理解是这样settings.json 是“这辆车出厂时的标定”CLAUDE.md 是“这次出车的路线图”而 memory 是“司机积累的路况经验”。经验会随着每一次驾驶更新但路线图不会因为一次绕路就全盘重画。所以三者的职责边界非常清晰静态、高频、需要团队共享的放 CLAUDE.md动态、个人化、会话之间累积的放 memory涉及工具权限和运行环境的永远放 settings.json。4.2 怎么主动管理和维护记忆主动维护 memory 很重要因为它是一个会“骗人”的系统——你默认它记得它应该记得的东西但你不查看就不知道哪些被丢了、哪些被记歪了。我建议在每个比较重要的项目里每周至少执行一次/memory查看当前状态。实际操作中我发现几个特别值得主动让 Claude 记住的内容技术决策及其原因比如“为什么选 PostgreSQL 而不是 MySQL”这类决策背景几乎肯定会在未来被反复问起。用户偏好比如“该用户偏好函数式写法、不喜欢 class 组件”这类偏好写进全局 CLAUDE.md 也行但如果是项目特有的放 memory 更灵活。踩过的坑和解决方案比如“升级依赖后 nginx 配置必须同步修改否则会出现 502”。想让模型记住就直接对会话说“请记住这条XXX”它一般会调用对应的持久化机制写入记忆。反过来的操作也一样重要过时了、矛盾了、不再适用的记忆主动让它删除或更新不要让老经验持续污染新决策。这里顺便提一个关于“记忆污染”的安全意识。现在模型上下文里可以被注进来的信息来源越来越多包括 CLAUDE.md、导入文档、网页内容、工具输出等等。如果有人能控制其中某一份资料理论上就可以在模型不知情的情况下塞入恶意指令诱导它后续做出错误甚至危险的行为。这个风险在业界已经有针对 AI Agent 记忆投毒的研究被公开讨论过。所以我的建议是CLAUDE.md 和 import 的文档必须来自可信来源不要让来路不明的文本混进长期记忆涉及敏感操作时宁可多一次确认也不要让模型凭“记得”就去执行。4.3 memory 与 CLAUDE.md 的边界和常见误区最容易犯的错就是把 memory 当 CLAUDE.md 用。有人让模型把所有项目规范都“记住”结果发现会话一多、记忆一杂模型反而开始自作主张地执行过时规则。原因很简单memory 是动态的、按相关度检索的它不是一份被完整、稳定注入的说明书。CLAUDE.md 每次启动都会稳定加载适合放必须 100% 生效的规则memory 适合放“最好知道但不至于致命”的背景信息。第二个误区是重内容不重更新。记忆的价值在于时效性一条过时的决策记录远比没有记录更危险因为它让模型“错得很自信”。建议每隔一段时间清理打开/memory把已经翻篇的内容清掉把模糊的表述改精确。第三个误区是不给记忆分级。所有记忆都塞在一起系统没法区分“项目必须遵守的硬规范”和“顺便了解的技术背景”。正确的做法是硬规范进 CLAUDE.md环境与权限进 settings.json软知识和经验进 memory。这个分级不是强迫症而是让每个配置系统干自己最擅长的事。5. 三套配置联动一个真实项目的完整配置实战5.1 从零配置一个项目的实操流程假设你刚接手一个全栈项目前端 React 后端 Node用 pnpm 管理依赖。你希望 Claude Code 第一天就能像老成员一样干活。按照下面的顺序操作基本不踩坑。第一步初始化目录结构。在项目根目录创建.claude/文件夹把settings.json和settings.local.json都建好后者加入.gitignore。第二步写用户级兜底配置。在~/.claude/settings.json里放通用权限和默认模式比如允许Bash(pnpm run *)、Bash(git *)defaultMode 设为acceptEdits。这些规则对绝大多数项目都能复用。第三步写项目级 settings.json。项目特有的权限在这里补充比如 denyWrite(Http/Migrations/**)、allowRead(server/**)env 里设置NODE_ENVdevelopment。第四步写 CLAUDE.md。先列命令再列架构然后列规范和禁忌控制在 150 行以内命令部分用实际参数不要写抽象描述。第五步开一个会话把近期项目的关键决策和历史坑位告诉它让它写入 memory。之后在开发过程中遇到值得沉淀的信息直接说“记住这一点”持续累积。第六步验证。新开会话问模型“这个项目的启动命令是什么”“改数据库连接配置的时候要注意什么”看它答得对不对。不对就回去调整 CLAUDE.md 或 memory直到它稳定回答正确为止。这套流程我跑过很多次第一次配置大约 20 分钟之后每次新项目可以控制在 10 分钟以内。真正值钱的不是那几次配置而是后续会话不再重复交底效率提升是实打实的。5.2 常见问题排查速查表现象可能原因排查与解决模型频繁弹权限确认、操作被拒permissions 的 allow 规则没覆盖常用命令检查 allow 规则里的命令模式和路径通配符放宽到实际需要的范围明明配了 deny文件还是被改了路径写法不匹配实际路径用相对项目根的正斜杠路径确认大小写必要时直接写绝对路径CLAUDE.md 写了但模型好像没看到文件位置不正确或会话启动时没有加载确认是项目根目录的 CLAUDE.md 或.claude/CLAUDE.md然后重启会话上下文被占满模型回答变笨CLAUDE.md 太长或 import 了太多大文件精简 CLAUDE.md把长文档拆到按需查阅的 import只保留核心规则新会话完全不记得上次的结论memory 里没有该类记录在会话里明确说“记住这一点”之后用/memory验证是否写入模型执行了过时的规则memory 和 CLAUDE.md 里的内容冲突清理 memory 中的过时记录以 CLAUDE.md 为准统一规范钩子没生效matcher 写错或钩子命令退出码不符合预期确认 matcher 匹配的工具名钩子命令失败时检查退出码和执行环境这张表里的问题我基本都现场遇到过其中“路径不匹配”和“CLAUDE.md 太长”是出现频率最高的两类。排查思路都可以先抓住“信息是否真的进入了模型上下文”这一点再谈效果避免空转。5.3 我的实操习惯和一些避坑心得最后说几个我自己的习惯纯个人经验供参考。第一配置变更必须重启会话验证。settings.json 和 CLAUDE.md 的很多改动是在会话启动时快照的运行中的会话不一定实时生效。改完配置后最稳的验证方式是退出当前会话重新执行claude进入再针对性提问。别嫌麻烦这一步能省掉大量“我明明配了为什么不生效”的疑惑。第二CLAUDE.md 里加“版本号”。在文件开头放一行“本文档最后更新于 2025-xx-xx当前版本 v1.2”模型读到后能感知信息时效性你在审计上下文时也能快速发现哪个文件该更新了。第三memory 的清理频率要高。我自己的节奏是小项目一两周查一次大项目每次大需求迭代后都查。你可以把“检查/memory并清理过时记录”作为一条固定指令放进 CLAUDE.md每次开会话时模型会先做一趟记忆体检省心很多。第四不要把所有希望寄托在“让 AI 自己记得”。凡是关系到正确性、安全性、合规性的硬规则永远同时写进 CLAUDE.md而不是只靠 memory。memory 再好也只是经验经验可以启发但不能当法律。实际上用顺之后你会发现Claude Code 真正的分水岭不在模型本身而在配置。把 settings.json、CLAUDE.md、memory 这套组合拳练好同一个模型、同一个项目体验完全可以是两个量级的。上面这些都是我这段时间实际踩出来的经验项目不同、环境不同配置不能照抄但只要掌握每一层管什么、怎么写、怎么排错你就能快速搭出适合自己项目的那套体系。