Claude Code 用起来上手很快但真正想让它高效干活关键往往不是把提示词写得多漂亮而是搞懂它的三套配置体系settings.json、CLAUDE.md 和 memory。我最早用的时候只在对话里反复强调要求结果换一个目录、换一台机器Claude 的行为全还原教训很深。这篇笔记我把三块分别管什么、怎么配、优先级怎么算、踩过的坑有哪些一次说清。无论你是刚接触 CLI还是已经在 VS Code 里集成使用这套配置思路都直接可复用。内容以我常用的 Claude Code 版本为例字段名可能随版本有小变化但机制基本一致。1. 三大配置体系到底是干什么的1.1 先分清楚哪份配置在管什么很多新手最容易犯的错是把所有东西都往一个文件里塞。实际上 Claude Code 的配置天然分了三层职责完全不同。settings.json 管的是运行环境选哪个模型、输出 token 上限、允许执行哪些命令、注入什么环境变量、在工具调用前后执行哪些钩子。你可以把它理解成应用的权限开关和运行参数。CLAUDE.md 管的是项目知识用自然语言写清楚这个项目是什么、技术栈有哪些、启动命令怎么敲、代码风格怎么统一、哪些目录不能动。它相当于入职第一天发给新人的《项目手册》Claude 会在会话开始时自动读取。memory 管的是长期记忆对话过程中发现你偏好某个测试框架、不喜欢某种注释风格、某个目录有特殊约定这些信息会被沉淀下来下次不用重新教。它不是手动编辑的静态手册而是动态积累的经验库。配置维度典型位置更新方式作用范围settings.json~/.claude 或项目 .claude 目录手动编辑 JSON模型、权限、环境变量、钩子CLAUDE.md用户目录、项目根目录或子目录手动维护 Markdown项目背景、命令、规范、约束memory用户级记忆文件或项目记忆对话中自动/显式写入用户偏好、项目事实、决策记录三者各管一摊但又互相配合。settings.json 决定能不能做CLAUDE.md 决定应该怎么做memory 决定你这个人平时喜欢怎么做。缺一个Claude Code 都只是个一次性聊天工具。1.2 为什么是三层而不是一个配置文件把三层合并成一个文件表面上省事实际会带来一堆问题。首先是变更频率不同settings.json 里的权限和模型相对固定CLAUDE.md 跟着项目走、每次任务可能要微调memory 则几乎每天都在变。混在一起改一个字段就可能误伤另一个模块。其次是作用域不同一台机器上你会跑多个项目每个项目的技术栈和命令都不一样CLAUDE.md 必须跟着项目走而你对回答风格、默认语言、常用工具的偏好希望全局生效。作用域不同却放在同一份文件里没法拆分。第三是维护成本。如果所有规则都在一个巨型文件里Claude 的上下文会被无关内容稀释模型很容易忽略关键指令。三层分离之后记忆负责高频、轻量的偏好CLAUDE.md 负责稳定的项目知识settings.json 负责强硬的执行边界各查各的。优先级上的一个基本原则是越靠近当前工作目录、越是当前会话里明确提出的要求优先级越高。全局记忆和用户级 CLAUDE.md 是兜底项目级 CLAUDE.md 会覆盖它们当前对话里你直接说的指令又比项目级说明更优先。记住这条后面遇到冲突时基本都能判断该听谁的。2. settings.json 实操权限、模型与运行参数2.1 配置文件的层级与合并规则settings.json 常见有两层用户级和项目级。用户级文件在 Linux 和 macOS 下是~/.claude/settings.jsonWindows 下是%USERPROFILE%\.claude\settings.json。项目级文件放在当前项目根目录的.claude/settings.json里随仓库一起提交方便团队统一权限。两层的合并规则很简单同名配置项项目级覆盖用户级用户级里没写的项目级补充。比如说用户级设置了model为claude-opus-4某个项目需要在资源有限的环境里用更轻量的模型就可以在项目级 settings.json 里写一个不同的model覆盖掉全局配置。需要提醒的是环境变量的优先级通常比 settings.json 里写的值更高。如果你在 shell 里已经导出了ANTHROPIC_API_KEY或ANTHROPIC_BASE_URL即使 settings.json 的env字段配了别的值也可能不生效。这个坑我后面在常见问题里细讲。修改配置之后在会话里输入/status可以查看当前实际生效的模型、目录、权限等信息这是验证配置有没有生效最直接的办法比猜方便多了。2.2 关键字段解析与我的推荐配置用我实际用的配置来拆解每个字段都有明确目的。下面这份是一个比较通用的模板{ model: claude-sonnet-4, maxTokens: 4096, permissions: { allow: [ Read(./src/**), Edit(./src/**), Bash(npm run dev), Bash(npm test), Bash(git status), Bash(git diff) ], deny: [ Bash(rm -rf *), Bash(shutdown*) ], ask: [ Bash(git push), Bash(npm install) ] }, env: { YOUR_APP_ENV: development }, hooks: { PreToolUse: [ { matcher: Bash, command: echo \工具调用前触发\ } ] }, includeCoAuth: true }model决定当前会话用哪个模型不同版本支持的模型 ID 有差异建议以官方文档为准。maxTokens限制单次输出的最大长度。别把它设得太小否则代码生成和长文本分析会被截断太大又会拖慢响应速度4096 是我个人折中后的数值。permissions是这块配置的核心。allow列表里放你希望 Claude 直接执行的命令deny列表是绝对禁止的命令ask列表表示每次执行前都要跟你确认。这里要注意匹配规则Bash(npm test)只匹配完全等于这条命令的调用如果你允许Bash(npm test*)就能匹配前缀。原则是能写精确就写精确少用通配符兜底不然权限形同虚设。hooks用来在工具调用前后挂自动化逻辑比如审计日志、检查危险命令、拦截文件写入。includeCoAuth打开后Claude 提交代码时会自动加上 Co-Authored-By 署名方便追溯。2.3 权限配置的核心心法先 deny 再 allow权限配置最容易踩的坑是一上来就大量 allow把Bash(*)全放行。这样确实省了确认的麻烦但风险非常大。万一 Claude 理解偏了执行了危险命令后悔都来不及。我的习惯是先想清楚绝对不能让它干什么把deny填满再把日常开发一定会用到、不会出风险的命令放进allow剩下拿不准的放ask让它问一句。比如测试命令、启动开发服务器、查看 git 状态这些高频且相对安全可以直接 allow。推送代码、安装依赖、删除文件这些有副作用的操作让它先问一次。这个配置的过程很像给实习生开服务器权限你不需要给 root只给能完成工作所需的最小权限。这样 Claude 不会被确认弹窗烦到没法干活你也不会因为权限太宽而提心吊胆。2.4 把 settings.json 与第三方模型对接实战很多人想用 Claude Code 的自带交互能力但后端接其他模型比如 DeepSeek 的 Anthropic 兼容接口。这个场景可以通过 settings.json 的env字段解决不用改任何代码。以 DeepSeek 为例它提供了 Anthropic 兼容的 API 端点。配置可以这样写{ env: { ANTHROPIC_BASE_URL: https://api.deepseek.com/anthropic, ANTHROPIC_AUTH_TOKEN: 你的API Key } }注意不同服务要求的字段名不太一样。有的用ANTHROPIC_API_KEY有的用ANTHROPIC_AUTH_TOKEN以目标服务的接入文档为准。配置完成后重启会话输入/status检查模型信息是否变成了目标服务。这里有两个忠告第一不要把带 Key 的 settings.json 提交到仓库Key 应该用环境变量在外部注入或者用settings.local.json这类本地文件忽略掉第二第三方模型虽然可以接入 Claude Code但它对 Claude Code 内置的提示词工程和工具调用模式不一定完全兼容实际效果会有折扣遇到行为异常先别怀疑配置可能是模型本身的差异。3. CLAUDE.md 编写让 Claude 真正懂你的项目3.1 CLAUDE.md 的读取位置与覆盖规则CLAUDE.md 是 Claude Code 里最像文档的配置但它不是给人看的是给 Claude 自动读的。会话启动时Claude 会按层级加载多份 CLAUDE.md把它们的内容当作项目背景和行事准则。用户级文件在~/.claude/CLAUDE.md存的是你跨项目的通用偏好比如回答用中文代码缩进用两个空格不要使用全局变量。项目级文件在项目根目录的CLAUDE.md存的是这个项目专属的信息。如果你在某个子目录里还放了一份CLAUDE.md那 Claude 在进入该目录工作时会优先读取它子目录相对于项目根目录更精确所以优先级更高。覆盖规则延续前面的原则越精确越优先。用户级 CLAUDE.md 是兜底项目级覆盖用户级子目录覆盖项目根目录。这个机制非常适合大仓库根目录放整体架构和构建命令在api/、frontend/等子目录分别放自己的技术栈和约束Claude 切到哪就看到哪上下文不会被无关信息占满。3.2 一份实用的 CLAUDE.md 内容框架很多人的 CLAUDE.md 只有一句话你是我的项目助手请帮助我开发。 这种文件写了等于没写。我的做法是把它当成新员工入职培训大纲来写覆盖七个模块项目一句话简介让 Claude 知道自己在做什么。技术栈与目录结构用树形结构或简短列表标注关键目录用途。常用命令启动、测试、构建、迁移、代码检查每条命令单独一行。代码规范命名风格、缩进、引号、是否强制类型标注。明确禁止的事比如不要改 lock 文件、不要动某个生成目录。典型工作流程改一个接口通常要经过哪些步骤。关键背景数据库连接方式、环境变量说明、特殊业务规则。举个例子一个小型 Python 项目可以这么写# 订单服务项目说明 这是内部订单管理服务使用 Python 3.11 FastAPI后端连接 PostgreSQL。 ## 常用命令 - 启动服务python -m uvicorn app.main:app --reload - 单元测试pytest tests/ -x - 代码检查ruff check . ## 代码风格 - 必须使用 Black 格式化行宽 120 - import 顺序按 isort 规则 - 日志一律用 structlog不要用 print ## 禁止事项 - 禁止修改 poetry.lock除非升级依赖 - 禁止在未检查 migration 的情况下直接改表结构 ## 工作流程 - 新增接口先写 schema再写 service最后补测试 - 提交前必须跑一遍 pytest这份文件不需要很长几百字就够。太长反而会让 Claude 抓不住重点我见过有人写了几千字的 CLAUDE.md结果模型在该按规范写代码时规范被淹没在一堆背景描述里。3.3 提高指令遵循度的写法细节CLAUDE.md 的生效效果取决于你怎么写。同样一条规则不要用 print 调试和日志一律用 structlog调试优先使用 logger.info后者明显更容易被执行。原因是模型理解命令式的实际行动比理解否定描述更容易。使用祈使句尽量以动词开头比如必须运行 XXX提交前执行 XXX禁止修改 XXX。应该可能最好这类模糊词要少用Claude Code 的模型在没有强约束时会选择自己觉得合理的路径模糊表述等于没写。规则之间不要互相打架。比如 CLAUDE.md 里写了测试命令用 pytest tests/ -x后来又在某个位置说测试用 make test模型就可能困惑。一份文件里只保留一套标准旧规则要及时更新。另外CLAUDE.md 里不要放机密信息。如果文件会跟着仓库提交那所有读得到仓库的人都能看到这些内容。数据库口令、API Key 这类东西应该放在环境变量或本地配置里让 CLAUDE.md 用变量名引用而不是写真实值。3.4 CLAUDE.md 与 settings.json 的配合方式两者不是二选一而是要配合。CLAUDE.md 描述的是做什么、怎么做settings.json 决定的是让不让做。最理想的配合是CLAUDE.md 里规定的每个高频操作在 settings.json 的 allow 列表里都有对应权限。比如 CLAUDE.md 写了测试命令是 pytest tests/ -xsettings.json 里就应该允许Bash(pytest tests/ -x)。如果漏了这一条Claude 虽然知道该跑什么命令但会被权限拦下来反复询问你。反过来如果 settings.json 允许了某个命令但 CLAUDE.md 根本没提什么时候该用那 Claude 可能根本不会主动用它。所以我的项目模板是CLAUDE.md 管意图和规范settings.json 管边界和放行memory 管个人偏好。三者对齐之后Claude Code 才像是你团队里的一个正经工程师而不是每次都要手把手教一遍的实习生。4. memory 记忆体系长期记忆的写入、查看与清理4.1 memory 到底存在哪里memory 是三个体系里最容易被误解的。很多人以为 Claude Code 有某种神奇的云端记忆换台机器还能想起来。实际上它的记忆分两种载体一类是用户级和项目级的 CLAUDE.md 文件Claude 在对话中如果发现你的偏好可能会把新约定写进这些文件另一类是独立维护的记忆条目通常存在用户数据目录下新版本里可以用/memory命令统一查看和管理。记忆内容通常是短句比如用户偏好使用 double quotes 而不是 single quotes这个项目的构建命令是 pnpm build用户不喜欢在 commit message 里使用 emoji。这些信息有的是你主动告诉它的有的是 Claude 从你们过往对话中自动概括出来的。自动积累是 memory 最大的价值也是最大的风险。模型判断你看起来喜欢 A未必等于你真的喜欢 A。比如偶尔一次用了单引号它可能会记成偏好单引号之后每次生成代码都给你改成单引号你得反复纠正。所以 memory 绝不是记下就不管定期检查和清理是必要的。4.2 如何主动写入和纠正记忆想让记忆更可靠最好用主动写入替代被动积累。在对话里直接说请记住XXX是一个有效办法。更规范的方式是用/memory命令比如/memory 记住本项目测试命令是 pnpm test这条指令会明确写入记忆之后新会话里 Claude 会直接阅读并在相关场景下调用。查看当前记忆也很简单输入/memory会列出已有条目。删除不想要的内容用/memory delete选对应条目或者直接打开记忆文件手工编辑。纠正记忆最快的方式是在当前会话里明确说取消之前的记忆改成 XXX。因为会话中的显式指令优先级最高它会在本次运行里立即覆盖旧记忆。如果旧记忆已经被写进用户级或项目级文件建议直接去文件里把对应段落改掉避免下次会话又被读到。清理记忆要有节奏。我习惯每周五抽五分钟翻一遍记忆列表把过时、错误、不再适用的条目删掉。这部分工作从表面看不是功能开发但它直接影响 AI 助手的输出质量长期坚持能省下大把对话纠偏的时间。4.3 memory 与 CLAUDE.md 的优先级和冲突处理记忆和 CLAUDE.md 出现冲突时判断标准仍然是谁更具体、谁更靠近当前上下文。通常项目级 CLAUDE.md 会覆盖用户级记忆。比如全局记忆里写着代码用双引号但项目 CLAUDE.md 明确写了本仓库统一单引号那 Claude 在项目里应该按单引号来毕竟仓库规范优先于个人习惯。不过实际运行中模型并不会像代码执行一样严格按优先级跳转它可能会把两条信息同时带上造成行为摇摆。最好的办法不是靠优先级硬压而是让冲突不出现。检查到记忆里有矛盾的内容直接删除旧条目保持记忆干净。还有一个需要注意的层次权限和记忆冲突时权限永远赢。即使记忆里写了用户允许直接执行 git push只要 settings.json 把这条命令放在 ask 或 deny 里Claude 也不能绕过。这是安全底线不要试图用记忆突破权限因为记忆文件可能被模型误写而权限是更可靠的控制点。4.4 避免记忆污染的实用技巧记忆污染最常见的表现形式是Claude 变得固执老按旧习惯办事。比如你上周还在用 A 框架这周项目换成了 B 框架Claude 却因为旧记忆里到处是 A 框架的约定生成代码时反复用 A 的方式。这不是模型笨是记忆文件里残留了大量过期上下文。避免污染我有三个习惯第一重要项目用项目级记忆或项目根目录的 CLAUDE.md 管理不要依赖全局记忆因为它们会跨项目串味第二项目切换技术栈后第一时间去清理相关记忆条目不要等出错再处理第三在 memory 里写入否定性偏好时要写清楚不要做什么而不是只写做什么比如不要使用 lodash优先用原生方法这样 Claude 在相关场景下能直接避开。把 memory 看成一块白板而不是永久硬盘。你愿意每次写什么、保留什么、擦掉什么决定了这个 AI 助手是不是真的越用越顺手。5. 常见问题与排查实录5.1 settings.json 改了却不生效这个是我被问得最多的。改了 settings.json 但行为没变化先按这个顺序排查。第一步看文件位置。用户级文件必须在~/.claude/目录下Windows 用户注意是在%USERPROFILE%\.claude\下这个目录通常隐藏在用户文件夹里。项目级文件必须在当前项目的.claude/目录下不是放在项目根目录就完事没有.claude文件夹的话需要自己创建。第二步看 JSON 格式。JSON 对逗号、引号要求严格多一个逗号就可能整份配置失效。用命令检查最稳妥python -m json.tool settings.json能正常输出格式化后的内容说明语法没问题报错会明确指出哪一行有问题。第三步用/status看当前实际生效的模型和权限。如果显示的还是旧模型说明配置没被加载。这时候检查是不是 shell 环境变量覆盖了设置项。比如你之前导出了ANTHROPIC_MODEL之类的变量设置里的 model 就会被顶掉。取消环境变量后重开终端一般就正常了。5.2 CLAUDE.md 指令被忽略或部分生效CLAUDE.md 被忽略大概率不是 Claude 不听话而是它根本没读到或没读全。先确认文件名是不是真的叫CLAUDE.md大小写不能错扩展名必须是.md。放在项目根目录还是.claude/目录取决于你的版本最稳妥的做法是项目根目录放一份.claude/目录再放一份内容精简的核心版本。如果你发现指令在对话里执行得很好过一阵子又不管用了常见原因是会话上下文太长Claude 把 CLAUDE.md 的内容挤出注意力窗口。这时候要精简文件把最重要的规则放在文件开头长尾背景放后面。还要检查是不是你的指令和当前用户要求冲突。用户说帮我把日志改成 printCLAUDE.md 说禁止 print模型通常会优先满足用户当前请求因为对话中的最新指令更有优先级。这不是配置错误而是交互逻辑。想让规范更硬可以在回应里加一句按项目规范我应该用 logging你确定要 print 吗把它升级成确认问题。5.3 memory 记错信息导致行为异常如果你发现 Claude 反复做出违背当前需求的行为很可能是记忆里有过期条目在干扰。比如它一直用旧的构建命令、旧的代码风格而你早就改革了。这时候别先骂模型打开/memory检查一遍看看有没有明显过期或错误的条目。项目级记忆也要检查对应的 CLAUDE.md看 Claude 是否在某个时刻把一段自动总结写进了文件。找到问题后用/memory delete删除或直接编辑记忆文件手动更正。更正完还有一个容易被忽视的步骤重启会话。记忆和文件都是在会话启动时加载的不重启当前会话里可能还保留着旧记忆的上下文影响。新开一个会话测试基本就能确认是否修好。5.4 与 VS Code、Windows/macOS 相关的配置坑在 VS Code 里使用 Claude Code配置逻辑和命令行一样但有几个环境差异要注意。VS Code 默认终端可能不加载 shell 的环境变量导致你明明在系统里配置了 API KeyClaude Code 却提示没有权限。解决办法是在扩展设置或 VS Code 环境里显式配置或者在启动脚本里导出变量。Windows 下的路径特别容易错。用户级配置不是简单的~/.claude完整路径是C:\Users\你的用户名\.claude\settings.json。有些教程会写%USERPROFILE%\.claude\settings.json在系统终端里这个写法能展开但在某些工具里可能不会。改了配置后VS Code 集成不生效先重新加载窗口再新开一个终端。扩展通常在新终端会话里重新读取配置老终端可能一直用旧状态。第三方模型接入不生效也一样别急着怀疑扩展输入/status看请求的 base URL 是否变成你要的服务没有变化就去检查环境变量名有没有写错。最后强烈建议不要在共享仓库里提交带真实 Key 的 settings.json。可以提交一个settings.example.json作为团队模板具体密钥放进.gitignore或本地环境变量。这些细节看似麻烦但能避免你某天不小心把密钥冲到远程仓库然后欲哭无泪。最后说一个我自己的习惯每周五花五分钟过一遍 memory 和项目根目录的 CLAUDE.md把过时条目删掉把本周踩坑的经验补进去。配置体系这件事本质上是在给未来的自己省时间。今天花半小时把三层配置理顺之后每次打开 Claude Code它都会以更接近你期望的方式工作。希望这份笔记能帮你少走点弯路。