用 Claude Code 有一段时间了最深的体会是这工具的上限一半由模型决定另一半由配置决定。很多人装上就开干默认配置用了两周抱怨“它怎么老问我要权限”“上下文老是乱”“改文件总不按我的来”——其实这些问题一大半都能在settings.json、CLAUDE.md和memory这三个配置层面解决。这篇就围绕 Claude Code 三大配置体系把我实际用下来的理解、踩过的坑、以及一套可以直接抄的配置思路完整写出来。无论你刚安装完 Claude Code还是已经在 VSCode 里用了一阵子这篇都值得存下来对照着调。1. 先搞清楚三层配置到底各管什么1.1 三个配置文件的分工与心智模型Claude Code 这个工具本质上是一个跑在终端里的 AI 编码代理它要干活就得知道三件事能做什么动作、按什么规矩干活、记不记得上次干到哪了。这三件事恰好对应三大配置体系。settings.json管的是“手脚”。模型调用、权限模式、钩子脚本、环境变量都归它管。你可以把它理解成给 Claude 定的一套操作规则哪些命令可以直接跑、哪些要问一声、哪些碰都不许碰。相当于给一个能力很强但不太懂人情世故的实习生立规矩。CLAUDE.md管的是“脑子里的岗位说明书”。它告诉 Claude 这个项目是干什么的、代码结构长什么样、测试命令是什么、代码风格有什么约定。没有这个东西Claude 每次开新会话都像第一天上班的应届生什么都要现猜。memory管的是“记性”。它决定 Claude 能不能跨会话记住你的偏好、项目当前状态、已经放弃过的方案。如果CLAUDE.md是入职手册那 memory 就是工作笔记记录的是“今天我们决定用 pnpm 而不是 npm”这种动态信息。三者的关系可以用一句话概括settings.json决定 Claude 能做什么CLAUDE.md决定它该怎么做memory决定它还记得什么。这三层配合好Claude Code 用起来才叫“顺手”配合不好就会陷入反复授权、反复解释、反复踩同一个坑的恶性循环。1.2 文件都在哪、加载顺序是什么样的先记住一个重要原则Claude Code 的配置是分级叠加的不是单一文件。我整理了一个对应关系表配置项用户级路径项目级路径说明设置~/.claude/settings.json.claude/settings.json用户级全局生效项目级只对当前项目生效本地设置无.claude/settings.local.json不入 git通常放个人偏好项目说明书~/.claude/CLAUDE.md项目根目录CLAUDE.md、子目录CLAUDE.md会自动加载进上下文记忆~/.claude/下的记忆文件.claude/下的记忆文件通过#引用或/memory管理加载顺序上settings.json遵循“项目本地 项目级 用户级”的覆盖关系也就是说.claude/settings.local.json里的配置优先级最高适合放只有你自己需要的实验性配置。而CLAUDE.md不存在覆盖关系它是叠加关系用户级、项目根、当前目录的CLAUDE.md会一起被读进上下文共同约束模型行为。这一点很多人搞混以为子目录写一个就能覆盖根目录实际上是“都生效”所以内容安排要注意别互相矛盾。1.3 配置改完什么时候生效这是另一个高频问题。settings.json改完之后当前会话不会立刻生效你必须重开会话或者用/config之类的命令重新加载配置。CLAUDE.md相对智能一些文件有变化时 Claude Code 会检测到并在后续对话中重新读取但为了稳妥我建议改完大版本内容后直接重开会话避免上下文里还残留旧版本的内容。memory的生效则取决于你怎么用。如果只是通过对话临时提到的内容下个会话大概率就丢了如果写进了记忆文件那要等文件被引用或重新扫描后才会发挥作用。记住一句话配置没有“保存就立刻全局生效”这种好事所有改动都建议在新会话里验证。2. settings.json把默认行为调成你的习惯2.1 配置文件位置与命名规则先看用户级配置。在终端里执行# 创建用户级配置目录 mkdir -p ~/.claude # 编辑用户级配置文件 code ~/.claude/settings.json项目级配置则是放在项目根目录下的.claude目录里。一个常见的大坑是有的人把.claude目录写成了.claude-code或者干脆在项目根目录放了个settings.json这都不对。Claude Code 认的是.claude/settings.json这个固定路径。项目级设置还有个特殊文件叫.claude/settings.local.json这个文件应该加进.gitignore里面放你自己的私有配置比如个人偏好的模型、个人 API key 相关的环境变量。我见过有人把settings.local.json提交进仓库结果团队里别人的本地配置被覆盖排查了半天才发现是这个问题。2.2 核心配置项逐个说清楚一个典型的用户级settings.json长这样{ model: claude-sonnet-4-5, includeCoAuthoredBy: true, permissions: { allow: [ Bash(git status), Bash(git diff), Bash(git log:*), Bash(npm run lint), Bash(npm test) ], ask: [ Bash(npm install *), Bash(rm -rf *) ], deny: [ Bash(git push --force) ] }, hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: node scripts/check-format.js } ] } ] }, env: { MY_APP_ENV: development } }每个字段的用途我分开讲。model字段指定默认模型。不同账号能用的模型不一样以你实际账号为准不确定就用/model在对话里切换看看。这个字段适合团队统一指定型号避免有人手动切错。includeCoAuthoredBy控制提交信息里是否带上“Co-Authored-By: Claude”这属于团队规范问题建议团队开会统一决定不要每个人各自设。开了之后所有通过 Claude Code 生成的 commit 都会带上署名审计和协作时很有用。permissions是大多数人最关心的部分。它支持三种规则allow白名单直接放行ask弹窗询问deny直接拒绝。匹配格式是工具(参数模式)其中Bash对应终端命令、Edit对应文件编辑、Write对应新建文件、Read对应读取文件。Bash(git log:*)表示允许所有以git log开头的命令*是通配符。这个语法非常实用建议熟练掌握。hooks是高级玩法。它允许你在某些事件发生时执行本地脚本比如文件编辑前后触发格式化、会话结束时清理临时文件。matcher指定事件匹配范围hooks数组里是实际要执行的命令。这相当于给 Claude Code 加了个“条件反射”很多团队用它在 CI 前自动跑检查。env字段用于给 Claude Code 的运行环境注入环境变量。注意它注入的是 Claude Code 这个进程本身的环境变量不是项目里应用运行时的环境变量。我之前搞混过一次想在env里给 Node.js 应用塞数据库连接串结果发现根本没传进应用进程里这个字段冲泡用错了地方。2.3 权限控制实操从碰壁到顺手权限配置是最容易走极端的部分。我见过两种典型用户一种是把所有命令都设成allow结果 Claude 有一次在错误目录下执行了清理命令把临时文件删了另一种是全部保持默认的ask结果每跑一步都要按一下回车最后烦到弃用。正确做法是“白名单兜底 敏感操作询问 危险操作拒绝”。先观察一段时间把高频、安全、可重复的命令放进allow比如git status、git diff、npm run lint这类只读或低风险命令。把安装依赖、删除文件这类命令设为ask保留一个确认环节。把git push --force、rm -rf这类高风险命令直接deny不给任何机会。这里有个细节容易被忽略ask规则如果你在工作流里每次都输入y确认等于形同虚设还可能因为肌肉记忆把危险操作也顺手确认了。所以高风险命令直接deny才是真的安全。权限的目的是让你在不打断节奏的前提下挡住真正的危险不是每步都拦。2.4 状态栏与 hooks 的实际玩法statusLine字段可以自定义终端里 Claude Code 的状态栏信息比如显示 git 分支、当前时间、待办数量。官方默认其实已经够用但如果团队有特殊需求比如想在状态栏显示当前环境是 dev 还是 prod可以写一个小脚本输出内容配置格式类似{ statusLine: { type: command, command: node scripts/status-line.js } }hooks 我觉得最值得抄的一个用法是“编辑后自动格式化”。很多项目代码风格不统一Claude 改完的代码经常出现缩进混乱、分号缺失。可以写一个PostToolUse钩子匹配Edit|Write触发时执行项目的格式化命令比如npx prettier --write。这样 Claude 每次改完文件代码风格都被自动拉回正轨省掉大量人工 review 时的格式琐事。2.5 环境变量与密钥管理环境变量这块必须提醒一句千万别把真实密钥写进settings.json尤其是会提交进仓库的settings.json。正确姿势是写在settings.local.json里并且确保文件已被.gitignore忽略。Claude Code 读取env字段注入环境变量如果你的脚本需要读取密钥优先让脚本从系统环境变量里读而不是从 Claude Code 的配置里拿。密钥这东西一旦进了上下文就等于进了日志很难彻底清理。3. CLAUDE.md给 Claude 打印一份岗位说明书3.1 CLAUDE.md 是什么、为什么重要CLAUDE.md是 Claude Code 里的项目说明文件用 Markdown 写的。它在每次会话开始时自动加载进上下文相当于一见面就先让 Claude 读一遍这份文档。它解决的核心痛点是Claude Code 每次开新会话都不带记忆它不知道你的项目用什么包管理器、测试框架是什么、目录结构长什么样。每次都得现问或者干脆瞎猜然后在一个错误假设上继续写代码。有了CLAUDE.md这些信息就会变成每次对话的默认背景知识。它不光省时间更重要的是减少“猜错上下文”带来的连锁错误。想象一下给一个实习生一份详细的入职须知和什么都不给直接让他上手写业务代码产出质量完全两个级别。3.2 放在哪里、能放几份CLAUDE.md有几个层级~/.claude/CLAUDE.md用户级所有项目都会加载项目根目录CLAUDE.md当前项目加载任意子目录CLAUDE.md当 Claude 操作到该目录及其子目录范围时加载子目录的CLAUDE.md适合放局部模块的专属约定比如src/legacy/CLAUDE.md可以写“这块代码千万别重构改了会炸”。不过要注意叠加生效的问题我前面提过子目录的内容不会覆盖根目录是叠加进来。所以不要在两个层级的文档里写互相矛盾的规则比如根目录说“用 pnpm”子目录说“用 npm”Claude 会无所适从。3.3 一份可以直接抄的 CLAUDE.md 模板我建议一份好的CLAUDE.md控制在 50 到 80 行以内太长了会占用正常的对话上下文窗口。下面是一个通用模板# 项目名用户中心服务 ## 项目一句话简介 后端 API 服务提供用户注册、登录、资料管理能力Node.js 18 TypeScript。 ## 常用命令 - 安装依赖pnpm install - 本地开发pnpm dev默认端口 3000 - 构建pnpm build - 测试pnpm test单测 集成测试 - Lintpnpm lint ## 目录结构 - src/controllersHTTP 层只做参数解析与响应 - src/services业务逻辑层核心业务都在这里 - src/repositories数据访问层只负责 SQL 和表操作 - tests测试文件按模块分目录 ## 代码规范 - 使用 pnpm禁止新增 npm install 或 yarn - 所有接口返回格式统一为 { code, data, message } - 时间字段一律使用 ISO 8601 字符串禁止使用本地时间 - 新功能必须补测试覆盖率不强制但核心路径必须有 - 日志用项目封装的 logger禁止直接 console.log ## 不要做 - 不要修改 src/legacy 目录下的逻辑只允许 bug 修复 - 不要给数据库表新增索引迁移脚本需要走 DBA 评审 - 不要删除任何带有 deprecated 标记的接口先询问 ## 开发约定 - 当前主分支是 main功能分支名格式 feature/xxx - 提交信息建议用 conventional commits 格式 - 本地已验证过的命令可以放心执行git push 前确认一次这份模板的要点是信息密度高、全是事实性描述、几乎没有废话。Claude 是语言模型你写“项目很复杂”这种模糊表述它没法转化成具体行为但“禁止使用本地时间”这种指令就能直接落到代码里。3.4 写作技巧与踩坑经验写CLAUDE.md最大的坑是“贪多求全”。我早期写过一份 200 多行的说明包含大量“如果……那么……”的条件分支、历史背景、未来规划。结果 Claude 为了“严格遵守规范”回复里频繁复述文档内容有效工作上下文被压缩得很厉害产出质量反而下降。精简之后模型的行为指令更清晰废话也少了。第二个坑是把CLAUDE.md当垃圾箱什么旧信息都往里塞。文档里如果残留着已经废弃的命令、旧的目录结构Claude 会优先信任书面信息而不是代码本身导致它在错误的方向上努力。所以CLAUDE.md必须随项目演进持续维护改目录、换包管理器、调整结构这些事情要同步更新文档。第三个技巧CLAUDE.md里可以用文件名引用其他文档比如把一份超长的 API 规范放在docs/api.md然后在CLAUDE.md里写“API 详细规范见 docs/api.md”。这样正文保持精简需要时 Claude 会自己展开引用文件。第四个技巧不要在CLAUDE.md里放密钥、token、数据库连接串。它会被加载进上下文活跃会话越多泄露风险越大。任何带密钥的内容都应该走环境变量或密钥管理系统。4. memory让 Claude 跨会话长记性4.1 memory 在 Claude Code 里到底是什么先说清楚一个让很多人困惑的点Claude Code 里的 memory 并不是一个单一的“记忆库文件”它是一整套让信息跨会话保留的机制集合。我结合自己的使用经验把它分成四类第一类是会话恢复。Claude Code 支持用claude --resume或claude --continue恢复之前的会话这样上次聊到一半的上下文还能继续。适合长时间任务中断后回来接着干但它的本质是临时记忆会话多了照样会遗忘。第二类是记忆文件。在~/.claude/或项目.claude/目录下放几个 Markdown 文件比如memory.md、todo.md、decisions.md然后在对话中通过#文件名的方式引用比如“参考一下 #memory.md 里我们上周的决定”。这是跨会话记忆最务实的方案。第三类是CLAUDE.md本身。它其实承担了很大一部分长期记忆的功能项目规范、代码约定写进去每次会话自动加载等价于“永久记忆”。区别在于它偏静态偏“规则”不记录动态状态。第四类是版本差异带来的内置命令。不同版本的 Claude Code 对 memory 的实现有差异有些版本提供/memory命令来管理记忆内容。如果你当前版本有这个命令直接在对话里输入/memory就能看到帮助信息。我的建议是以你当前版本的官方帮助为准永远不要把某个自媒体说的特定命令当成所有版本通用。4.2 建立一套自己的记忆体系我的方案分三层。第一层项目根CLAUDE.md放静态规则第二层.claude/state.md放动态状态比如“当前在改登录模块cors 配置已调整待完成联调”第三层.claude/decisions.md放关键决策及原因比如“2025-03-10迁移到 pnpm因为 npm workspace 依赖提升问题太多”。平时对话时如果 Claude 问起某个决策我直接让它读#decisions.md。实际操作中我发现让 Claude 自己把结论写进记忆文件比手动维护靠谱得多。比如在对话结束时说一句“把这次查明的端口冲突原因和解决办法追加到 #state.md 里”它会准确整理并追加。这比自己复制粘贴省事也更不容易遗漏细节。4.3 记忆维护与清理记忆最大的风险是“过时信息比没有信息更糟”。如果state.md里写着“当前分支是 feature/login”但实际已经合并到 main 了Claude 可能基于错误前提做出一堆无用功。所以我给自己定了个规矩每完成一个小阶段就清理一次动态记忆把已完成的待办划掉把已过期的事实删除。还要特别提醒不要什么都往记忆里丢。一些临时性的、只跟某次会话相关的信息写进 memory 只会造成长期噪音。记忆里只保留两类内容一是会影响未来决策的事实二是你不想第二次踩的坑。其他内容聊完就忘。4.4 记忆的安全风险与投毒防护这一条值得单独讲。最近有安全研究比如 agentpoison 这类针对 LLM agent 的攻击研究指出LLM agent 的记忆和知识库可能成为投毒攻击的目标。简单说如果你让 Claude 读取了不可信的网页、陌生 issue、第三方粘贴内容并且这些内容被写进了记忆文件恶意指令可能会在后续会话中悄悄影响 Claude 的行为。防御措施不复杂第一只让可信来源的内容进入长期记忆比如你自己组织的笔记、经过 review 的文档第二定期人工审阅记忆文件发现异常内容立刻删除第三不要让 Claude 无脑地把网络搜索结果直接写入memory.md先经过你的确认。这个习惯在团队协作场景尤其重要因为多人的内容都汇入同一份记忆时一条恶意插入就可能造成连锁影响。5. 组合使用三层配置怎么配合才顺手5.1 从零开始搭一套配置的四步走如果你现在用的还是纯默认配置我建议按下面的顺序搭一套自己的体系第一步先建用户级~/.claude/settings.json把权限里的高频安全命令放进allow把危险命令放进deny。这一步决定日常使用的顺畅度先解决“老被问”的问题。第二步为每一个正式项目写根目录CLAUDE.md内容按前面模板精简到 50 行左右。如果你维护多个项目这一份文档就是每个项目的“打开方式”。第三步在项目.claude/目录下创建state.md和decisions.md两个记忆文件并在对话中习惯性引用。这一步解决“跨会话遗忘”的问题。第四步把.claude/settings.local.json和记忆文件里的敏感内容加入.gitignore团队协作时明确哪些入库哪些不入库。5.2 团队协作哪些配置该入库我建议的入库策略是.claude/settings.json入库因为权限白名单、hooks 这类东西团队统一更安全根目录CLAUDE.md入库它本质是项目文档的一部分decisions.md入库它是团队决策记录state.md可以入库也可以不入取决于里面有没有敏感信息如果有个人相关的密钥、本地路径就别入settings.local.json永远不入库。还有一点容易被忽略hooks 里执行的命令脚本是很有价值的供应链攻击面。如果团队仓库里有人提交了一个恶意脚本并且 hooks 指向它那么每个成员在 Claude Code 触发 hook 时都会执行这段代码。所以团队里要约定hooks 命令必须指向仓库内有代码评审记录的脚本禁止指向外部 URL 下载的内容。5.3 配置前后效果对比我自己的一个项目在配置前每次让 Claude 改个接口它都要问一遍“测试怎么跑”“依赖用什么装”十分钟的活有一半时间在回答基础问题。配置完CLAUDE.md之后这些问题彻底消失它能直接按规范写代码、跑测试、提交整个链路顺了很多。权限配置的效果同样直观。配置前删除一个文件弹一次确认改一个文件弹一次配置后只读命令和低风险命令直接放行只有安装依赖、删除文件才询问节奏感完全不同。说实话settings.json里allow规则多写几行比换一个更强的模型带来的体验提升还明显。6. 常见问题与排查技巧实录6.1 配置文件没生效怎么办先检查路径。项目级配置一定是.claude/settings.json不是.vscode不是项目根目录下的settings.json更不是claude.json。再检查 JSON 格式多一个逗号或者漏个引号都可能导致整个文件静默失效。然后重开一个会话验证因为配置改动不总是热加载。最后用/status或者查看官方诊断信息确认当前会话加载的是哪个层级的配置。如果项目级配置和用户级配置有冲突记住项目级覆盖用户级settings.local.json优先级最高。还有个隐蔽问题如果你同时在 VSCode 扩展和终端里跑 Claude Code两边可能读取了不同的配置文件。VSCode 扩展有时会使用扩展自带的配置路径和终端的~/.claude不完全一致。遇到“终端里配置生效、VSCode 里不生效”的情况优先查扩展的配置入口。6.2 权限相关的高频问题“Claude 想跑的命令被 deny 了怎么办”在settings.json的allow里加对应规则。特别注意通配符写法Bash(npm run lint)只匹配这一条命令Bash(npm run *)才匹配所有 npm run 子命令。“弹窗太频繁了怎么办”往allow里加规则把高频安全命令白名单化。但别为了省事全 allow至少保留deny黑名单兜底。“命令被误拒绝但又不该问”检查是否有一条过宽的deny规则把正常命令也挡住了。6.3 安装与运行问题速查表我把日常社区里高频的安装运行问题整理成一个速查表问题原因与处理Windows 下提示npm 不是内部或外部命令未安装 Node.js 或未加入 PATH装 Node.js LTS 版并重启终端macOS 全局安装权限不足使用 nvm 管理 node或用npm config set prefix指定用户级目录Ubuntu 下claude: command not foundnpm 全局 bin 目录没加进 PATH检查npm prefix -g对应目录VSCode 里没有 Claude Code 面板需要先安装 Claude Code for VS Code 扩展再在终端执行claude完成认证claude update升级失败检查网络、npm 源也可以重新执行全局安装命令覆盖安装登录后仍提示功能受限部分能力和账号权限、订阅类型有关以官方支持范围为准不确定环境是否正常运行claude doctor如果你的版本支持可以输出一段环境诊断信息6.4 上下文与记忆相关的问题“Claude 把我的上下文搞乱了”直接/clear开新会话不必硬撑着对话。“Claude 忘了上次说的约定”先检查CLAUDE.md有没有更新再检查记忆文件里有没有记如果都没有就在当下明确说一遍并让它写进记忆文件。“模型表现突然变笨”可能就是CLAUDE.md太长把有效上下文窗口挤掉了。检查一下文档是否超过一百行试试精简后再观察。“memory 文件里有过时的内容误导了 Claude”把过时内容删掉而不是推翻重来。我习惯在记忆文件顶部加一行“最后更新时间”提醒大家包括 Claude注意时效性。我个人在实际操作中还有两个小习惯一是每份CLAUDE.md至少保证前 20 行内写出“项目是干什么的 三条最高优先级禁令”这能最大程度避免 Claude 跑偏二是每次改动配置文件之后主动跑一个低风险任务验证而不是以“看起来没问题”为标准。配置体系这东西没有一次配完永不改的项目在变、工具在变配置也得跟着养。希望这篇能帮你把 Claude Code 从“一个能跑的终端工具”调教成“一个懂你项目、懂你习惯的结对搭子”。