聊到 Claude Code 的配置大部分人第一反应就是往项目根目录丢一个 CLAUDE.md等到 settings.json 不生效、memory 跟预期不一致的时候才开始头疼。我最早也这么干结果用着用着发现改了配置仿佛没改Claude 昨天确认过的事今天又忘干净权限弹窗多到想把终端砸了。后来花了一整周把 settings.json、CLAUDE.md、memory 这三套配置体系彻底捋了一遍才意识到它们根本不是同一个文件的三种写法而是三条完全不同的链路各管一摊、各有各的加载时机和优先级。Claude Code 是 Anthropic 出品的终端 AI 编程代理能读项目、改文件、跑命令本质上相当于把一个会写代码的实习生装进了命令行。它最容易被低估的其实是配置能力settings.json 管的是允许做什么、用什么模型、跑命令时守什么规矩CLAUDE.md 管的是这个项目长什么样、该按什么规矩干活memory 管的是上次聊完的结论下次还记不记得。这三样配合好了同一个仓库同一套配置不同人用起来的体验会差一个量级。这篇的定位是实操向适合两类人一类是刚装好 Claude Code、被各种配置选项搞晕的新手另一类是用了一段时间、隐约觉得配置越来越乱的老手。我会把每个文件的存放位置、加载顺序、关键字段、优先级和常见坑都过一遍最后给一个可以直接抄的完整配置模板。1. 配置体系全景三个文件到底各管什么1.1 一表看懂三者分工我先给一张总表后面所有细节都围着这张表展开。这也是我在实际工作中给团队讲配置时最爱用的开场。配置体系典型文件管什么生活类比settings.json~/.claude/settings.json、.claude/settings.json、.claude/settings.local.json权限规则、默认模型、环境变量、钩子、状态栏公司章程CLAUDE.md.claude/CLAUDE.md、CLAUDE.md、CLAUDE.local.md、~/.claude/CLAUDE.md项目上下文、编码规范、常用命令、工程约束员工手册memory.claude/memory/目录、/memory命令跨会话记住偏好、决策、教训工作笔记本这里有个很关键的区别很多人没想明白settings.json 是机器在执行前要检查的硬规则它决定 Claude 能不能跑npm install、要不要先问你CLAUDE.md 是每次开新会话都塞进上下文里的说明书它决定 Claude 知不知道这个项目的构建命令和代码风格memory 则是会话过程中动态沉淀下来的短时笔记它跟着对话实时增删改Claude 自己就能写。我见过有人在 settings.json 里写编码规范然后困惑为什么 Claude 不遵守。它当然不遵守——编码规范就该进 CLAUDE.mdsettings.json 只认权限、模型、钩子这类结构化规则。文件放错了位置效果等于零甚至会在你不知情的时候以另一种方式生效造成更难排查的隐患。1.2 三类配置的加载时机完全不同settings.json 在会话启动时一次性读取并合并所以改完必须重启会话或新开一个才会生效。这一点很多人踩坑改完权限立刻在当前会话里试发现没用以为配置写错了其实只是没重启。CLAUDE.md 是每次会话启动时直接作为上下文注入的同时会在/compact之后重新读取。compact 相当于把历史对话压缩了但说明书会重新完整加载这就是它和普通对话记忆的本质区别——可以压缩但不会丢。memory 则不走启动加载这条路它是通过工具调用按需读取和写入的。Claude 在对话中觉得这个信息值得记或者需要查一下上次记了什么的时候才会去读写 memory 文件。所以 memory 不是越大越好也不是每句话都会被记住它是一套有取舍的动态机制。1.3 为什么拆成三套而不是一个大配置文件我刚开始也吐槽过一个工具搞三套配置不是自找麻烦吗实际用下来这个拆分其实很合理。归属不同。settings.json 涉及权限和密钥需要严谨管理改错了有安全风险CLAUDE.md 是项目知识的延伸应该跟着仓库走大家共享memory 是个人化、易变的甚至允许 Claude 自动写入不需要走严格的 review 流程。变更频率也不同settings.json 低频改动、改了要谨慎CLAUDE.md 在项目结构变化时更新memory 几乎每次会话都在变。风险等级更不一样settings.json 配错权限可能让危险命令被静默执行CLAUDE.md 写错顶多让代码风格跑偏memory 记错影响的只是短期判断依据。想清楚这层逻辑之后你就不需要纠结某个规则到底该放哪了。放错位置的配置比不配置更坑。2. settings.json把允许做什么和怎么做钉死2.1 三个层级的位置与优先级settings.json 不是一个孤零零的文件而是按层级合并的一整套文件企业级托管配置由组织管理员下发个人改不了适合公司统一管控的场景。用户级~/.claude/settings.json对你机器上的所有项目生效。项目级项目根目录下的.claude/settings.json随仓库提交团队共享。本地级.claude/settings.local.json默认被 git 忽略放个人差异化配置。合并规则是从企业级到本地级逐层叠加后面的同名键覆盖前面的。所以本地级能覆盖项目级的 model 设置项目级能覆盖用户级的默认值。这个覆盖关系在团队协作里特别有用团队在项目级统一锁死权限和模型个人想用别的模型就在 local 文件里覆盖互不干扰也不会污染仓库。注意.claude/settings.local.json不会被 git 跟踪但前提是你的.gitignore里没把它漏掉。我见过团队把整个.claude/目录加入 git结果个人的 API key 直接进了仓库这是很危险的事。2.2 核心字段实操解析permissions是最重要的字段直接决定 Claude 的动作边界。它支持三种规则allow直接放行、deny直接拒绝、ask每次询问。规则写法是工具名(参数)加上 glob 匹配。我自己常用的权限配置长这样{ permissions: { allow: [ Bash(npm run build), Bash(npm test), Bash(git status), Read(~/secrets/*), Edit(**), WebFetch(https://example.com) ], deny: [ Bash(rm -rf *), Bash(git push --force) ], ask: true, defaultMode: acceptEdits } }这里有个容易犯的错误Bash(**)这种写法等于给 Claude 无限执行权它可能在你没看明白的时候就跑了rm -rf node_modules或者git reset --hard。我的建议是宁可多列几条具体命令也别图省事写通配。另外defaultMode里的acceptEdits表示自动接受文件编辑但工具执行和命令运行仍然要走权限判断。如果你刚上手不要轻易开bypassPermissions之类的免确认模式那相当于给实习生发了张无限额度的信用卡。model字段可以指定默认模型比如claude-sonnet-4-5或你通过第三方 API 映射的模型名。env字段用来注入环境变量第三方 API 场景几乎必用。hooks是挂载钩子的地方支持PreToolUse工具执行前、PostToolUse执行后、UserPromptSubmit用户提交输入、SessionStart会话开始、Stop(停止)、PreCompact压缩前等事件。钩子命令里可以用CLAUDE_TOOL_NAME、CLAUDE_TOOL_INPUT、CLAUDE_PROJECT_DIR这类变量拿到上下文。includeCoAuthoredBy设为 true 时Claude 生成的提交会在 git 信息里带上 Co-Authored-By 标记团队做 AI 辅助开发统计时很有用。statusLine可以自定义终端状态栏我一般放一个当前模型名和剩余上下文量的显示脚本方便在长会话里判断什么时候该 compact。2.3 一个可以直接抄的完整示例{ model: claude-sonnet-4-5, includeCoAuthoredBy: true, env: { MY_PROJECT_ENV: development }, permissions: { allow: [ Bash(npm run *), Bash(git *), Read(**), Edit(**) ], deny: [ Bash(rm -rf *), Bash(git push --force *) ], ask: true, defaultMode: acceptEdits }, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo 准备执行命令: $CLAUDE_TOOL_INPUT } ] } ] } }逐段说model锁定默认模型includeCoAuthoredBy给提交加署名env注入项目环境变量permissions用npm run *和git *覆盖日常高频命令Read和Edit放开文件读写但配合ask: true保底deny把两个高危命令堵死。hooks里在每次执行 Bash 前打印一下命令内容相当于给 AI 加了一道说给我听再动手的仪式实测能减少很多误操作。2.4 常见误区与我的建议有几个坑我反复遇到列出来给你们避雷误区一权限规则写得太宽。Bash(**)会让 Claude 在长会话里悄悄执行各种命令事后看日志才冷汗直冒。权限规则宁可多列不要通配。误区二在 settings.json 里写自然语言规则。比如请使用 4 空格缩进JSON 里能写但 Claude 不会把它当权限规则处理该进 CLAUDE.md 的东西不要硬塞进来。误区三改完不重启会话。settings.json 只在会话启动时读取改完需要重启或新开会话。误区四把 API key 直接写进 env 然后提交 git。密钥要么走环境变量文件要么放进 local 配置绝对不要进仓库。我的经验是settings.json 每两周 review 一次用git diff看配置变更删掉那些已经用不上的 allow 规则。配置和代码一样是会腐化的。3. CLAUDE.md给项目写操作手册3.1 文件位置与优先级CLAUDE.md 可以放在多个位置处理优先级从低到高是用户级~/.claude/CLAUDE.md对所有项目生效→ 项目级.claude/CLAUDE.md→ 项目根目录的CLAUDE.md兼容旧版布局→CLAUDE.local.md本地个人向导不进 git→ 子目录下的CLAUDE.md只在该目录下生效。优先级高的文件会覆盖优先级低的同名指令。也就是说如果用户级文件里写了测试命令是 npm test项目级文件里写了测试命令是 pnpm test那实际生效的是项目级的。子目录文件适合放某个模块特有的规则比如处理src/api下的代码时额外加载 API 设计约定。这个优先级设计很好用我把自己对代码风格的整体偏好放在用户级把每个仓库的具体命令和结构写在项目级两不冲突。但也要注意用户级文件写得太重会让所有项目的 Claude 都带上你的个人偏好换台机器或换个人协作时容易产生奇怪的行为差异。3.2 一份能落地的 CLAUDE.md 结构模板我自己写 CLAUDE.md 会严格按下面的结构来每一行都确保有信息量# 项目说明 一句话说清楚项目是干嘛的、技术栈是什么。 ## 常用命令 - 构建: npm run build - 测试: npm test - 代码检查: npm run lint ## 架构约定 - /src 下按模块划分禁止跨模块直接引用内部实现 - 不要修改生成的 dist 目录 - 新增 API 必须走 /src/api 下的统一封装 ## 编码规范 - TypeScript4 空格缩进 - 组件用函数式写法禁止 class 组件 - 所有错误信息统一走 errorHandler不要直接 console.error ## 注意事项 - 数据库迁移脚本不能自动执行需要人工 review - 某些测试依赖本地 DockerCI 里要跳过关键在于CLAUDE.md 不是写给人类读的文档是写给 Claude 读的约束和提示。每条规则都应该能被验证和执行比如使用 4 空格缩进是能检查的注意代码质量这种话写了等于没写。我见过有人把 README 直接改成 CLAUDE.md里面全是本项目致力于打造最优质的体验这种废话结果 Claude 该知道的构建命令一条都不知道干活全靠猜。3.3 import、path、# 命令与 $ 变量CLAUDE.md 支持几个很实用的扩展语法。import ./docs/commands.md可以把另一个文件的完整内容导入进来适合把大文档拆成小模块按需加载。./docs/architecture.md可以直接引用项目里的某个文件Claude 会读取该文件内容作为上下文效果等同于把这份文档塞进这次会话。自定义斜杠命令也值得用在 CLAUDE.md 里写# test: run the full test suite之后在会话里输入/test就会触发这条指令Claude 会自动执行对应的测试命令。这相当于把高频操作固化成了快捷指令。$ENV_VAR可以在 CLAUDE.md 里引用环境变量比如构建产物输出到 $BUILD_DIR在多环境部署时很实用。需要注意的是import是文件加载而不是文件链接。被导入的内容会成为上下文的一部分占 token 空间。引用大文件前先想想这个信息是这次会话必需的吗不是的话就别加载。3.4 别把 CLAUDE.md 写成裹脚布CLAUDE.md 的每一行都会进入每次会话的上下文越长越占 token。更麻烦的是Claude 对超长说明书的注意力会明显下降——就像你给新同事塞一本 300 页的员工手册他照样会漏掉关键条款甚至只记住开头和结尾的内容。我的经验是项目级 CLAUDE.md 控制在 50 到 100 行最重要的约束放最前面。细节部分用import拆到docs/子目录真正需要的时候才加载。文件里可以留一个最近更新小节标注哪些规则是这周加的、为什么加这样 Claude 在判断规则冲突时有更多依据。实测下来精简的 CLAUDE.md 对行为稳定性的提升远大于事无巨细的说明。4. memory让跨会话记忆真正落地4.1 memory 到底是什么memory 是 Claude Code 最近的版本里逐步完善的跨会话记忆机制。简单说Claude 会在会话过程中把值得记住的信息写入 memory 文件下次会话通过工具读取从而形成跨会话的记忆。你可以用/memory命令查看当前记忆列表也可以用write-memory、forget-memory、view-memory、ls-memories这些工具主动管理。在文件层面memory 以 markdown 文本的形式存放项目相关的记忆一般在.claude/memory/目录下用户级偏好则在~/.claude/memory/下。每个记忆文件可以带标题、正文和更新时间目录结构可以按主题分类比如decisions/、preferences/、lessons/。这里要澄清一点memory 不是聊天记录的自动备份而是经过提炼的结论性信息。Claude 不会把你和它的每句对话都记下来它只记录自己判断为值得长期复用的内容——比如你纠正过它的某个偏好、某个被反复确认的架构决策、某次踩坑后的教训。这也是为什么手动用write-memory写清楚比放任自动记录更可靠。4.2 自动记忆与手动干预Claude 的自动记忆触发条件我观察下来大致有这几类用户明确纠正了它的行为某个模式在对话里反复出现用户强调了某个重要决策或约束。触发时它会写一条记忆并可能在后续对话里参考。但自动的不一定准。有次 Claude 把我的一个临时决定记成了永久偏好之后每次写代码都按那个方向走我花了好久才反应过来是 memory 在捣鬼。所以我的建议是当 Claude 写了一条不符合事实的记忆直接用forget-memory删掉别留到以后。重要的结论在对话里明说请记住……Claude 会更认真地处理比暗示有效得多。定期用/memory查看记忆列表像我这种重度用户基本每周清理一次。4.3 记忆的污染与清理memory 最常见的坑是串台多个项目共用同一份用户级 memoryA 项目的结论在 B 项目的会话里冒出来。比如你在 A 项目里确定了数据库用 MySQL结果 B 项目也用 PostgreSQLClaude 却因为读了用户级记忆而默认推荐 MySQL 方案排查起来非常费劲。解决思路是分好目录项目级结论尽量让 Claude 写进.claude/memory/跟仓库走用户级 memory 只放真正与项目无关的个人偏好比如代码注释用中文提交信息用 conventional commits。跨项目串台还有一个变种是记忆过期项目重构后旧的架构记忆反而会成为误导。所以项目迭代周期里建议每次大重构后主动清一遍记忆删掉那些已经失效的结论别让它继续影响新代码。4.4 memory 和 CLAUDE.md 的分工边界我把这条规则写在团队文档里稳定的、应该长期生效的进 CLAUDE.md易变的、来自会话经验的进 memory。当同一条记忆反复出现三次以上说明它已经固化了应该把它从 memory 升级进 CLAUDE.md然后删除对应的 memory 条目。反过来也有情况CLAUDE.md 里的某条规则在实际使用中经常被推翻说明它不适合这个项目。这种规则应该降级回 memory甚至直接删掉而不是死守着一句写在纸面上但没人遵守的规范。memory 和 CLAUDE.md 不是替代关系是一个内容从临时经验沉淀到稳定约束的管道。5. 实操串联三件套怎么协同工作5.1 从零配置一个项目的七步流程我每次接新项目都会走一遍这个流程大约 20 分钟配置完基本就不用再操心了安装并确认 Claude Code 能正常启动进入任意目录测试一下基本会话。在项目根目录创建.claude/settings.json先把deny规则写死再列高频命令的allow别一上来就放通配。创建.claude/CLAUDE.md按前面说的结构填项目说明、常用命令、架构约定和注意事项。开第一个会话让它跑一遍build和test观察权限规则是否覆盖到了所有高频命令缺什么补什么。在对话中让 Claude 把这次踩坑的结论写进.claude/memory/比如构建前需要先执行 codegen这种仓库文档里没写但实际必要的信息。用 hooks 加一道保险PreToolUse里对Bash(rm -rf *)之类的高危操作做拦截提示。确认.gitignore覆盖了settings.local.json和CLAUDE.local.md然后提交配置到仓库。第 4 步是最关键的。你不实际跑一遍根本不知道这个项目的命令里有多少细枝末节比如测试前要起 mock 服务前端构建依赖特定 node 版本。这些信息写在 CLAUDE.md 里Claude 以后每次干活都会带着省下来的时间远大于配置成本。5.2 换用第三方模型时的配置位置很多人用 cc switch 这类工具接入 DeepSeek、Qwen、GLM 等模型。原理上这类工具改的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个环境变量让 Claude Code 把请求发到第三方兼容接口去。这个改法本身没问题但配置位置选不对会出乱子。我的建议是这些值放进用户级 settings.json 的env字段或者单独的本地配置文件里让它们只影响你自己的机器。千万不要写进项目级 settings.json 并提交到仓库否则整个团队的 Claude Code 都会被带偏到第三方服务上去。另外不同模型对 tool calling 的支持程度和上下文窗口差别很大model字段要填成第三方服务对应的模型名并在 CLAUDE.md 里注明当前按 XX 模型调优避免 Claude 按另一个模型的习惯来做假设。5.3 团队协作什么进 git什么不进文件是否进 git理由.claude/settings.json是权限规则与工具链统一团队共用.claude/settings.local.json否个人差异含私有配置.claude/CLAUDE.md是项目知识资产应随仓库分发CLAUDE.md根目录视情况兼容旧布局新项目直接忽略CLAUDE.local.md否个人笔记.claude/memory/通常否易变且个人化进 git 会造成大量噪音~/.claude/目录否用户级配置属于个人环境团队协作时最忌讳的是每个人都交出自己的本地配置那会导致同一套代码在不同人手里行为不一致。正确的姿势是项目级配置由团队维护review 后合并个人偏好全部留在 local 和用户级文件里。这样新人 clone 仓库后开箱即用老手的个性化设置也不受影响。6. 常见坑与排查技巧实录6.1 问题速查表症状可能原因处理方式settings.json 改了不生效当前会话没重启重启会话或新开会话CLAUDE.md 没加载文件位置或文件名不对检查.claude/CLAUDE.md注意大小写权限弹窗刷屏allow 规则太少在会话里允许后把对应规则固化进 settings.jsonmemory 串台项目记忆写进了用户级目录清理后指定写入项目级 memory组织提示 subscription access 被禁用账号鉴权方式受限换用 API key 鉴权或联系管理员检查权限Windows 安装报与 64 位版本不兼容安装包架构或网络问题改用 npm 全局安装安装时InternetOpenUrl()报错网络连通性问题检查网络连接、更换 npm 镜像源后重试6.2 排查套路遇到配置问题我会按下面的顺序排查效率比瞎试高很多第一步开 verbose 日志。用claude --verbose启动或者在会话里用/status查看当前生效的配置。第二步检查配置文件读取路径。用claude的日志输出确认它实际读了哪几个文件、合并结果是什么很多不生效其实是路径不对。第三步核对权限规则匹配。把规则逐条照抄到会话里触发一次看是没匹配上还是匹配了但被 deny。第四步查 memory。用/memory列出当前记忆看看是不是有旧记忆在干扰判断。日志是排查的照妖镜。有个案例我印象很深一个同事的 Claude Code 总是不按 CLAUDE.md 里的命令做事查了半天发现他在~/.claude/CLAUDE.md里写了另一套命令用户级的优先级高于项目级把他的项目级配置覆盖了。不看路径的话这种问题能猜三天。6.3 我的几条独家经验最后分享几个不写进官方文档的小技巧。第一settings.json 是 JSON 格式不能写注释但你可以配套维护一个docs/claude-settings.md把每条配置的意图、修改时间、修改原因都记下来。时间久了你会感谢这个习惯。第二CLAUDE.md 的头几行非常关键。Claude 在处理长上下文时对文件开头的内容权重更高所以把最重要的约束放在最前面别用客套话开头这个项目是一个...这种废话直接删掉。第三memory 别只依赖自动记录。每次完成一个重要任务顺手说一句请记住这次的关键决策让 Claude 主动整理比事后翻日志强得多。第四Windows 用户如果安装时报架构不兼容优先改用 npm 安装npm install -g anthropic-ai/claude-code再补一个有效的终端环境。不要盯着安装包反复试浪费时间。7. 结尾配置是性价比最高的投资最后说点个人体会。把三套配置体系理顺之后我最明显的感觉是Claude Code 的好用程度一半取决于模型一半取决于配置。settings.json 决定它敢不敢干活CLAUDE.md 决定它会不会干活memory 决定它下次还记不记得怎么干活。这三者不是一份文档能替代的各有各的职责缺一个都会让你在日常使用中感受到某种别扭。我现在每接到一个新项目先花 20 分钟把 settings.json 和 CLAUDE.md 配好跑通之后让 Claude 自己把踩坑记录写进 memory迭代两三天后把反复出现的记忆固化回 CLAUDE.md。这套流程走下来项目维护的时间越长协作越顺畅后期基本不太需要重复交代同一件事。如果你现在还在只丢一个 CLAUDE.md 就开干的状态建议试试这套完整打法差距很快就会体现出来。