Claude Code 三套配置详解：settings.json、CLAUDE.md 与 memory 实战

在接了两个多月的 Claude Code 项目之后我最大的感受是这工具上限很高但下限也低得吓人。很多人装完就开干结果要么被权限弹窗烦死要么发现 Claude 根本不认识你项目的结构每天靠嘴硬“重新自我介绍”过日子。想要把它真正调教成趁手工具绕不开三套配置体系settings.json、CLAUDE.md和 memory。这三者听起来都是“配置”实际分工完全不同——一个管行为一个管背景一个管记忆。这篇我就把每个文件怎么用、写什么、藏在哪、踩过哪些坑一次说清楚。1. 三种配置各管一段先搞懂它们的分工很多人第一次接触 Claude Code都知道要改配置但不知道改哪个。我见过有人把所有乱七八糟的东西全堆进settings.json也有人把整个项目的架构说明塞进CLAUDE.md搞到最后文件比项目代码还长。其实这三个体系的职责边界非常清晰settings.json管的是“运行时行为”。它控制 Claude 能调用哪些工具、需要哪些权限、走哪个模型、环境变量怎么注入、钩子脚本怎么挂。你可以把它理解成操作系统的“安全策略环境配置”它决定的是 Claude Code 这个进程怎么跑、能跑多野。CLAUDE.md管的是“项目上下文”。它给 Claude 一份静态的、项目专属的说明书代码架构、构建命令、常用规范、关键注意事项。这个文件不需要天天改但每一次对话里 Claude 都会读到它。memory 管的是“跨会话的事实积累”。它记录的是“你这个开发者偏好什么风格”“这个项目之前踩过什么坑”这类动态信息。和CLAUDE.md最大的区别是memory 由 Claude 自己在使用过程中写入和更新不需要你手动维护一篇“产品文档”。用一句话总结settings.json决定 Claude 能不能做CLAUDE.md决定 Claude 知不知道该怎么做memory 决定 Claude 记不记得上次怎么做。这里有个常见的误解我得先拆掉很多人把CLAUDE.md当 memory 用在每个会话开头手动往里面添加一大段“项目历史”。这个思路又累又容易过时因为CLAUDE.md是一次性注入的静态文本你每改一次它都会直接改变之后所有会话的行为基线。它的定位应该是“常量”而 memory 才是“变量”。搞清楚这一层后面的配置逻辑就顺了。2. settings.json全局行为的“控制面板”2.1 它到底在哪以及优先级怎么排我一开始接触时最懵的就是settings.json到底有哪几个答案是它有三层而且越靠下优先级越高。层级路径适用场景用户级~/.claude/settings.json全局偏好比如默认模型、通用权限项目级.claude/settings.json当前仓库专属行为通常提交到 Git本地级.claude/settings.local.json个人本机配置不提交 Git比如个人 API 端点实际工作时三个文件会做深度合并本地级的值会覆盖项目级项目级会覆盖用户级。所以正确的做法是把通用的、稳定的配置放用户级把团队共享的配置放项目级把个人路径、密钥、测试性配置放本地级。我习惯在新建项目时执行一条命令把骨架拉出来claude setup它会自动生成.claude/settings.json和.claude/CLAUDE.md的最小模板省得手写踩格式坑。如果你用的是 VSCode 插件也可以在命令面板里跑“Claude Code: Open Settings”直接打开对应文件。2.2 最值得先改的几个配置键这块儿很多人按文档抄但不知道每个键背后解决的问题。我说几个最有代表性的permissions这是最核心的一个对象。它控制工具调用的默认策略支持allow、deny、ask三种规则。我在真实项目中是这么配的{ permissions: { allow: [ Read, Glob, Grep, LS, Write, Edit, NotebookEdit, WebFetch, Bash ], deny: [ Bash(npm publish:*), Bash(rm -rf *) ], ask: [ Bash(git push:*), Bash(git reset:*) ] } }这里要说一下思路开发类工具我直接放开因为天天弹确认框真的很打断心流。但危险命令必须拦——rm -rf *这种我直接 denygit push和git reset我保留 ask毕竟推送和回滚是有副作用的操作让 Claude 先问一句我能多一次检查机会。hooks这个是我认为最被低估的配置。它允许你在特定时机执行外部脚本。下面这个例子是对每个会话做 preToolUse 检查拦截包含“测试”字样的危险命令{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: if echo \$TOOL_INPUT\ | grep -q \rm -rf\ ; then echo \BLOCK: 危险删除命令\; exit 2; fi } ] } ], Stop: [ { hooks: [ { type: command, command: echo \Claude Code 会话结束\ /tmp/cc_audit.log } ] } ] } }你看到的exit 2就是钩子返回“阻止执行”的标准方式命令本身不会跑。这个机制很适合做审计日志、安全拦截、甚至自动跑测试。有一条踩坑经验钩子脚本路径如果是相对路径Claude Code 是相对于当前工作目录解析的所以最好用绝对路径或者在脚本里先cd到固定目录。model这个键是很多人忽略的“法宝”。你要接本地模型或者第三方兼容 API就在这个层面覆盖而不是去改系统环境变量。{ model: claude-sonnet-4-1, modelMaxThinkingTokens: 8000 }如果你走的是 Anthropic 兼容接口比如接 LM Studio 起的本地服务官方文档里有标准做法通过ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN指向本地端点。有些人会用社区工具如cc-switch来切换不同第三方 API 提供方比如 DeepSeek、Qwen、GLM 这些兼容接口原理就是动态改这两个环境变量或者等价于配置里的数据源。做之前务必确认对方真的是 Anthropic API 格式兼容否则claude起来一串报错排查老半天才明白是协议不匹配。2.3 权限配置的坑和思路配置权限时最容易犯的错就是图省事直接allow一切。我第一周也是这么干的后果就是有一次 Claude 不知道从哪里学来的灵感自动git commit了一个还没 review 的大文件改动差点推到远端。权限这东西真不能全开“负责的懒”才是正确的姿势——把高频、无副作用、可自愈的操作放开把有副作用、不可逆的操作设为 ask把极端危险的命令直接 deny。另外一个很多帖子没提过的点permissions规则是支持通配的而且从上往下按顺序匹配。你把Bash(git push:*)放前面、Bash(*)放后面和反过来写效果完全不同。我习惯把精确规则放前、宽泛规则放后避免宽泛规则提前拦截精确规则。3. CLAUDE.md项目记忆的“活档案”3.1 文件位置与作用范围比你想的更灵活很多人以为 CLAUDE.md 只能放项目根目录其实它有“层级继承”逻辑。Claude Code 会在启动时按从当前位置到仓库根目录的顺序逐级向上找所有 CLAUDE.md并逐级合并。也就是说你既可以在仓库根目录放一份全项目说明书也可以在某个子模块目录里放一份局部说明。举我手头一个 monorepo 的例子根目录的CLAUDE.md描述了整个仓库的框架、构建链和部署流程packages/frontend/CLAUDE.md则专门写前端模块的组件规范和样式约定packages/shared/CLAUDE.md写公共包导出的注意事项。子目录的说明只在涉及那个目录的任务中被合并输入这比“一份文件管所有”更清爽也能有效减少 token 浪费。在用户级目录~/.claude/CLAUDE.md里我还会放一份“个人偏好说明书”告诉 Claude 我喜欢什么样的代码风格变量命名倾向短语义、注释中文还是英文、提交信息什么格式。这样不管进哪个项目Claude 都带着同一套“行为底色”效果拔群。3.2 内容怎么组织Claude 才真正“看得进”CLAUDE.md 不是给人写的 README它是要被另一个模型在心智里实时读取的所以结构和用词直接决定理解质量。我踩过很多次坑总结出的一个可靠模板是这样的# 项目概述 一句话说清楚这个项目做什么。 # 技术栈 - 框架Next.js 14 / TypeScript / Tailwind - 状态管理Zustand - 测试Vitest Testing Library # 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev - 运行测试pnpm test - 构建产物pnpm build # 目录结构说明 src/components —— 通用组件 src/features —— 业务模块按功能聚合 src/lib —— 工具函数与第三方封装 # 编码规范 1. 组件使用函数式写法hook 命名以 use 开头 2. API 请求统一走 lib/api.ts 中的 request 方法禁止在各处直接 fetch 3. 涉及时间格式化一律使用 dayjs 封装的方法 # 注意事项 - 修改 db 相关代码后必须执行 pnpm db:generate - 环境变量新增时必须同步更新 .env.example - 禁止在 reducer 内部调用任何带副作用的函数这里有个关键点不要写大段大段的叙述性文字而是尽量用短句和列表把命令和规则拆出来。模型读这类“规范式”文本比读“散文式”文本准确率高得多。我在早期版本里写了两大段“项目背景与发展历程”后来发现 Claude 抓重点的能力明显下降——因为它把注意力分散到背景故事上了真正要用的构建命令反而没记住。还有个小技巧在 CLAUDE.md 中写“禁止”事项比写“应该”事项更有效。比如“禁止在 reducer 内部调用任何带副作用的函数”这种规则比“请保持 reducer 纯净”模糊表达触发正确行为的概率高很多。模型对否定式指令的记忆更深刻尤其当它与“安全问题”绑定的时候效果更好。4. memory会话记忆的“长效储蓄”4.1 memory 到底是以什么机制在工作memory 在 Claude Code 里不是像数据库那样的一张大表它更像是一个“文件中存储的知识库”。/memory指令可以让你保存跨会话的信息这些内容会被写入~/.claude/projects/项目标识/memory/目录下一个条目对应一个文件。Claude 在处理查询时会先通过检索机制提取相关的记忆条目作为上下文注入。还有一种是自动记忆机制开启--memory标志后Claude 会在合适的时机自己把用户偏好、项目约定、决策过程等写入记忆文件不需要你手动干预。手动 vs 自动的区别一个是你的笔记一个是代理的“备忘录”。我平时使用/memory的方式更朴素一些——它确实很方便适合把那种“改过一次后来忘了”的信息固化下来。比如某个第三方 API 的鉴权方式、某个命令必须在特定目录下跑、或者某次排查后确定的一个规律直接/memory存进去下次再聊到相关内容Claude 能直接翻出来用不用你重新花嘴皮子解释。4.2 和 CLAUDE.md 的区别别再用错了很多人分不清 memory 和 CLAUDE.md觉得都是给 Claude 提供信息写哪儿都一样。这里差别很大维度CLAUDE.mdmemory写入方式手动维护手动/memory或自动记录作用范围项目级或用户级项目级甚至页面级更新频率低稳定不变高动态变化内容类型架构、命令、规范偏好、决策、事实、踩坑记录注入方式每次会话全量注入按需检索注入相关知识条目打个比方CLAUDE.md 像公司的规章制度手册员工入职人手一份内容相对固定memory 像老员工脑中的工作经验平时不特意文档化但遇到问题时“我记得以前这么干过”马上就能浮现。我之前有个项目数据库字段是created_at但 ORM 映射的代码里写的是createdAt映射层做了转换。这个“转换规则”我一开始写在 CLAUDE.md 里后来发现 Claude 一旦生成跨层代码总会在边界处犯错。后来我干脆用/memory把这个转换规则作为一条事实存起来效果立竿见影——因为它在触达数据库相关任务时会主动被提取比塞在大文档里的命中率更高。4.3 如何高效管理记忆条目memory 文件多了以后也会脏一个坑是Claude 会把一些过时的决策留在记忆里导致新会话里出现“信息打架”。我的做法是每隔一段时间看一眼记忆目录手动清理明显过期的条目ls ~/.claude/projects/项目标识/memory/文件命名通常是“话题关键词-时间戳”之类的形式能看出大概内容。对于拿不准的直接打开看正文。如果某条记忆已经和当前代码状态冲突果断删掉不要让旧的错误“幽灵”继续干扰新会话。另外提醒一个坑不要在所有项目里共用一份全局 memory否则项目 A 的决策会污染项目 B 的上下文。我在早期就这么干过结果 Claude 在写 Python 项目时坚持要用 Node 风格的命名查了半天才发现是另一个项目的记忆被注入进来了。5. 实操从零配好一套顺手的环境5.1 最小步骤还原我的配置过程我不会从零装着墨假设你已经装好了 Claude Code 本体。我的配置流程是三步走第一步建立用户级基础配置。编辑~/.claude/settings.json把通用权限和模型先设好。我喜欢在一开始就把permissions.allow加上Read、Write、Edit、Bash这些高频操作把deny里放上最危险的东西然后写一个最小CLAUDE.md到~/.claude/目录描述个人风格偏好。第二步进入具体项目目录执行claude setup生成项目骨架。然后打开.claude/settings.json和CLAUDE.md把项目特有的命令、结构、规范写进去。注意如果团队协作这份项目级配置是应该提交到 Git 的每个人拉下来都能用。第三步开启 memory 能力。我启动时常用claude --memory或者直接在里面用/memory手动存档关键信息。也可以设置一个别名让常见启动方式自动带上这个参数alias ccclaude --memory如果是在 VSCode 里用插件去扩展设置里找到 Claude Code 相关的启动参数同样可以填入--memory。这个参数加上之后Claude 的“跨会话”能力立刻不一样。如果你要接第三方兼容 API比如本地模型或 DeepSeek/Qwen/GLM 这类一套典型的配置是在用户级 settings.json 里覆盖env字段注意不要写在项目级里避免把个人接点信息提交到仓库{ env: { ANTHROPIC_BASE_URL: http://127.0.0.1:1234, ANTHROPIC_AUTH_TOKEN: local-test-token } }这里要特别说明这只是通用配置方法前提是目标服务真的实现了 Anthropic 兼容协议。很多第三方中转或本地推理工具确实提供这类兼容端点但你用的 DeepSeek、Qwen、GLM 这些模型本身能不能达到 Claude Code 的全部功能预期是不好打包票的。工具调用、权限控制、函数返回格式如果兼容得不彻底跑着跑着就会有一些莫名其妙的报错。所以这个配置只建议在试验/旁路场景下使用主力还是老老实实官方模型。5.2 碰到报错别慌先对照这几条配置过程中最经典的报错和解决思路可以按下面的清单逐个排查现象可能原因处理方式启动后提示不支持地区网络/账号/地区检查不通过确认账号是否在官方支持范围不支持就别硬试权限弹窗不断刷屏permissions.ask规则过多把高频无副作用操作挪到allow危险操作保留askCLAUDE.md 改了但没生效可能没有识别到文件确认文件在正确的层级目录检查文件名大小写明明加了 memory 但新会话想起来检索阈值问题或记忆文件损坏手动打开 memory 目录直接查看文件内容VSCode 插件连不上 Code插件与 CLI 版本不匹配升级插件或直接在终端里运行 claude 测试连通性接第三方 API 后工具调用乱兼容层的函数调用格式不对切回官方模型逐一对比锁定哪个环节逸出第三条我特别强调一下CLAUDE.md文件名是固定的大小写不能错我见过有人写成claude.md或Claude.md结果这个文件被当普通文本忽略Claude 一直没加载自定义规范。5.3 我对这套组合拳的最终配置样板下面这份是我现在个人常用的一套“最小实用配置”可以直接抄去改。用户级~/.claude/settings.json{ permissions: { allow: [ Read, Write, Edit, Glob, Grep, LS, Bash(npm run:*), Bash(pnpm run:*), Bash(git status:*), Bash(git diff:*), Bash(git log:*) ], ask: [ Bash(git add:*), Bash(git commit:*), Bash(git push:*), Bash(rm:*), WebFetch ], deny: [ Bash(rm -rf /*) ] }, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo \[PreToolUse] $TOOL_INPUT\ /tmp/claude_tool_audit.log } ] } ] } }项目级.claude/CLAUDE.md我写得更精简只留下“机器必须知道”的信息。写太多反而稀释注意力。真正的项目细节靠 memory 和对话推进去发现并记录。6. 常见问题与排查技巧实录6.1 我踩过最深的三个坑先说第一个权限配置“一刀切”全放行。这个坑我前面提过但真的值得再讲一次。有一回 Claude 自动执行了一个rm -rf node_modules然后立刻重新pnpm install它本意是帮我搞一个干净依赖环境但我一个旧依赖是本地 tar 包删了就再也找不回来整个环境废掉半天。从那以后凡是rm -rf开头我全部放 deny非要清理就手动执行。第二个坑CLAUDE.md 塞了太多内容。早期我把几百行的架构设计文档整个搬进去结果 Claude 回答前先处理两万字上下文反应慢了不少而且经常抓不住操作重心。后来我砍到只剩最关键的命令、目录、规范、注意事项整体准确率反而提升很大。要知道模型读再多的信息能稳定“用出来”的就那几条核心提炼永远是第一优先级的。第三个坑memory 存了不设过期时间的信息。它在我们组里是当作“中长期事实”来用的但软件项目迭代快“当前”状态三个月就过期了。以前我有一条记忆是“数据库迁移用 drizzle-kit push”后来团队切到了 Prisma旧记忆里残留的内容还会时不时被 Claude 翻出来干扰。现在我对记忆的原则是能查代码库直接推断的不优先存 memory必须存的尽量写成“最新事实”而不是“曾经如此”。6.2 一条独家的排查顺序我每次都用它收场如果 Claude Code 行为异常我从不乱翻文档先按下面这个顺序来第一看是不是 memory 在捣乱。我优先检查~/.claude/projects/项目名/memory/目录找找有没有和当前行为矛盾的内容。如果有先删掉再重启会话多半问题解决。第二看 CLAUDE.md 有没有过期指令。比如构建命令从 pnpm 改成了 npm但 CLAUDE.md 里还写着 pnpmClaude 当然每步都在按错误方式跑。第三看 settings.json 有没有规则冲突。比如你在ask里放了Bash(*)又在allow里放了Bash(npm run:*)顺序不对前者会把后面全部吃掉。第四最后才是检查环境变量和模型接入点。因为模型或者 API 端点的变化往往是“全局性故障”症状会很明显不需要细查就能发现。这套排查流程帮我省了至少两天时间建议直接抄走。7. 配置之外的三个习惯比配置本身更重要写到这光看文件本身可能还差一点。我的经验是配置体系能给你的上限很高的“底子”但真正拉开差距的是使用习惯。下面这三条是我后来慢慢总结的第一每周花十分钟整理 memory 目录。看到已经失效的条目标记就删掉非常值。很多用 Claude Code 越用越顺手的人背后都是有一个干净的记忆库在支撑。第二CLAUDE.md 每两周回头审视一次。项目演进快命令经常变不更新配置文件等于让 Claude 带着一本旧地图找新路。第三权限配置跟着项目风险走不要一套配置跑所有项目。写个人玩具项目可以宽松碰生产环境就严格尤其涉及部署、运维、支付相关的命令多问几次不丢人。我现在的生产项目里凡是带有--prod标记的命令一律用 ask让 Claude 先复述一遍后果。最后再分享一个我最近踩的新坑很多人喜欢把个人偏好写进项目级 CLAUDE.md结果团队协作时别人拉代码也带着你个人的命名风格偏好非常别扭。正确做法是个人风格放~/.claude/CLAUDE.md项目规范才放.claude/CLAUDE.md。这个边界守住了团队协作里的奇怪意见冲突能少掉一大半。