Claude Code配置调优：settings.json、CLAUDE.md与memory三文件实战指南-北京尧图网络

我大概花了两个周末才把 Claude Code 从一个“看起来很聪明但总不在线”的工具调教成真正能交付代码的队友。关键点不在模型本身而在三份配置文件settings.json、CLAUDE.md、memory。如果你也装了 Claude Code 却觉得表现平平先别急着换模型多半是这三样没理顺。很多人第一次接触 Claude Code第一反应是装好、登录、开始对话。但用两三天就会发现它每一轮操作都来问你要权限写了代码却不遵守你的代码风格上次交代过的背景下次会话又要重新讲一遍。这背后的原因本质上就是三份配置没有各司其职。settings.json 管的是“运行时环境”CLAUDE.md 管的是“项目规矩”memory 管的是“跨会话记忆”。这篇文章我会从用途、原理、写法一路讲到落地排错最后附上我自己的初始配置你可以直接抄。1. 三份配置的职责边界先分清再动手1.1 一个真实对比默认状态与配置好的状态先说个我自己的例子。前阵子给一个 Vue3 Express 的电商后台做重构刚开始用默认状态跑 Claude Code体验可以用“又菜又稳”来形容。它确实不会乱来但每一步都问“可以修改这个文件吗”“可以执行这条命令吗”我在旁边当了两小时点击确认的机器人。更难受的是明明前一个会话刚告诉过它“测试命令是 pnpm test”新开一个会话它又忘了只好重新解释。配置好之后完全变了。我只授权了pnpm和git相关命令文件读写限定在项目目录内把技术栈和命名约定写进 CLAUDE.md再让它记住“尽量用 pnpm、接口前缀统一 /api/v1”。它现在能一口气改完三个文件跑完测试把 git 提交信息都写好了。整个过程不用我点头它自己按规矩来。这就是三份配置协同的效果settings.json 决定它能做什么CLAUDE.md 决定它按什么规矩做memory 决定它还记不记得你的习惯。1.2 settings.json运行时的控制面板settings.json 相当于 Claude Code 的“系统设置”。它控制的是工具权限、模型选择、环境变量、事件钩子这些偏运行时的东西。你希望它自动执行哪条终端命令、不许碰哪个目录、用哪个模型干活都在这里写。它不负责“教”模型你的项目长什么样。模型读不读得懂你的业务是 CLAUDE.md 的事。settings.json 只负责“能不能做”和“怎么做”。1.3 CLAUDE.md项目的操作手册CLAUDE.md 是我的最爱也是大多数人忽略的杀手锏。它本质上是放在项目里的一个 Markdown 文件Claude Code 在每次进入会话时会自动读取。你把它当成“给新员工的第一天入职手册”就对了技术栈、目录结构、常用命令、代码规范、踩坑记录全部写进去。为什么是 Markdown因为模型对 Markdown 结构理解得最好。标题、列表、代码块天然就是信息密度高的结构模型能快速抽取出“这个项目的规矩是什么”。而且它跟着项目走可以直接提交进 Git每个成员都能共享。1.4 memory跨会话的长期记忆memory 和 CLAUDE.md 最大的区别是CLAUDE.md 是显式的、静态的、共享的memory 是隐式的、动态的、私有的。Claude Code 会在你和它对话的过程中自动记录它观察到的偏好和习惯。举个例子你在对话里说“下次改这个模块的时候记得不要动公共函数”这句话如果没有走 CLAUDE.mdClaude Code 会把它作为一条记忆写入本地记忆库。下次你重新打开一个会话它还能记得这个约定。你不用再解释一遍。这就是“跨会话记忆”的意义。1.5 三者协作关系配置管什么存放位置变更频率是否共享settings.json权限、模型、环境、钩子用户目录/项目 .claude 目录低通常个人CLAUDE.md项目背景、规范、命令项目根目录/子目录中随项目变进 Git团队共享memory个人偏好、动态上下文本地用户目录高自动写入私有三者缺一不可。settings.json 不给权限CLAUDE.md 写得再好它也动不了手CLAUDE.md 不写规矩memory 只能靠一次次试错积累memory 不清理时间一长就会污染上下文。下面我逐项拆开讲。2. settings.json 逐字段拆解权限、模型与钩子2.1 配置文件的存放位置与加载优先级settings.json 不止一个。Claude Code 采用分层配置从高到低依次是启动命令参数临时、优先最高项目级配置.claude/settings.json可提交 Git适合团队共享默认权限用户级配置~/.claude/settings.json个人偏好权限更严格更安全项目级和用户级会合并同名配置项以项目级为准。我习惯把通用且安全的权限放用户级把项目专属的放项目级。比如我自己在所有项目里都允许读文件和 glob 搜索但需要写文件、执行命令的权限只在特定项目的.claude/settings.json里显式授权。在 Windows 上用户目录通常是C:\Users\你的用户名\.claude\settings.jsonmacOS 和 Linux 是~/.claude/settings.json。命令行版本和桌面版共用同一套路径这点很方便改一次两边同时生效。2.2 permissions把危险命令关进笼子默认情况下Claude Code 对工具调用的策略是“问询”——每个动作都要你批准。安全是安全但效率极低。我建议提前在permissions.allow里放行你高频使用的操作。规则格式是工具名(参数模式)。常见的工具名有Read、Edit、Glob、Bash。比如{ permissions: { allow: [ Read(**), Glob(**), Bash(git *), Bash(pnpm *), Bash(npm run *) ], deny: [ Bash(rm -rf *), Bash(sudo *), Edit(~/.ssh/**) ] } }说明几点**表示任意路径Bash(git *)表示所有以git开头的 shell 命令。deny永远高于allow。即使你 allow 了Bash(**)只要有个 deny 规则匹配到也不会执行。我不建议写Bash(**)全放行。Claude Code 再聪明也只是一个基于统计模型的工具一旦误判执行了清盘命令哭都来不及。宁可多维护几条白名单也不要一条通配全放行。实际操作中我还会额外 deny 掉Bash(shutdown *)、Bash(poweroff)这种系统级命令以及Bash(wget *)、Bash(curl *)这类网络下载防止它在我不注意时往项目里塞依赖。2.3 model 与 env换模型就在这一步Claude Code 默认使用官方订阅或 API 的模型但它是支持配置环境和模型的。常见的字段{ model: sonnet, env: { ANTHROPIC_MODEL: sonnet } }model字段只在部分版本生效更通用的做法是通过环境变量控制。如果你有第三方模型接入需求后面第 5 节详细讲核心就是两个环境变量ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。BASE_URL指向你的 API 端点AUTH_TOKEN换成对应服务的密钥。这个思路可以通用于 DeepSeek、Qwen、GLM、本地模型等。注意不同提供方的 API 协议细节不同。官方 Anthropic API 有自己的消息格式部分第三方服务提供的是 OpenAI 兼容格式所以直接替换 URL 不一定行通常需要一层协议转换后面我会讲社区常用的cc switch这类工具。2.4 hooks让 Agent 在关键节点自动执行动作hooks 是 settings.json 里被低估的功能。它允许你在 Claude Code 的某个动作发生前后自动执行本地脚本。最常见的场景是每次 Claude Code 改完文件自动帮你跑 lint 或格式化。配置示例{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write {file_path} } ] } ] } }PostToolUse意思是工具执行完之后触发matcher限定哪些工具触发。{file_path}是变量会被替换成实际修改的文件路径。这样 Agent 改完代码格式化跟着就做了不用你手动收尾。还有PreToolUse、UserPromptSubmit等事件可以做更细的控制比如在命令执行前检查是否是安全命令。但刚开始用建议只加一条PostToolUse的格式化钩子够用就好。2.5 一份可直接改用的 settings.json 全量示例{ permissions: { allow: [ Read(**), Glob(**), Grep(**), Bash(git *), Bash(pnpm *), Bash(npm run *) ], deny: [ Bash(rm -rf *), Bash(sudo *), Bash(poweroff), Bash(shutdown *) ] }, model: sonnet, env: { ANTHROPIC_SMALL_FAST_MODEL: haiku }, hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: npx prettier --write {file_path} } ] } ] } }这份配置我用了好一阵子只放行 git 和 pnpm 相关命令写文件后自动格式化其余动作全部走确认。既能保证效率又不会失控。3. CLAUDE.md 的写法把项目规矩刻进 Agent 的“入职手册”3.1 CLAUDE.md 应该写什么六类必填信息写 CLAUDE.md 最容易犯的错是“什么都写”。但我尝试下来信息密度越高的文档Agent 的表现越稳定。我把它压缩成六类项目一句话简介这个项目是干什么的给模型一个全局背景。技术栈清单前端框架、后端框架、数据库、构建工具、包管理器。常用命令启动、测试、构建、Lint、数据库迁移。这是模型执行终端命令时最需要的东西。代码结构和目录约定哪个目录放组件、哪个放页面、哪个放 API 封装。编码规范命名规则、组件写法、状态管理方式、样式方案。踩坑与限制这里写“不要做的事”比如“不要在 utils 里放业务代码”“不要直接改 dist 目录”。一个我实际用过的模板# 电商后台管理系统 ## 项目简介 B2B 电商后台负责商品、订单、用户、优惠券管理。前端 Vue 3 Element Plus后端 Node.js Express数据库 PostgreSQL。 ## 常用命令 - 启动前端开发服务pnpm dev - 启动后端pnpm server - 运行全部测试pnpm test - 构建生产包pnpm build ## 目录结构 - src/views页面级组件 - src/components可复用组件 - src/api接口封装统一按模块拆文件 - src/storePinia 状态管理 ## 编码约定 - 组件文件名使用 PascalCase - api 路径统一前缀 /api/v1 - 状态管理只允许使用 Pinia禁止直接修改 store 外部状态 - 所有时间字段统一保存 UTC前端展示时再转本地时间 ## 注意事项 - 不要在 src/utils 下存放业务相关函数 - 不要手动修改 dist 目录下的文件 - 数据库变更必须先写迁移脚本不要直接改表写完之后你自己先读一遍如果这段话发给一个从不了解项目的程序员他能不能照着干如果能那 Agent 大概率也能。3.2 多层级 CLAUDE.md从全局到子目录Claude Code 支持多个层级的 CLAUDE.md。除了项目根目录子目录也可以放。它进入某个目录处理任务时会同时加载全局、项目根目录和当前目录的三份内容。全局存在~/.claude/CLAUDE.md适合放你自己的通用偏好比如“所有项目都用 pnpm 不用 npm”“统一用单引号”“中文回复”。子目录的 CLAUDE.md 特别适合大项目。我接手的那个后台项目src/api目录下就放了一份专门写“接口封装不要自己拼 URL用 request 工具的 get/post 方法”效果立竿见影。模型一旦进入src/api目录自动就知道这套规矩。3.3 三个常见误区第一个误区把 CLAUDE.md 写成需求文档。有人会把业务背景、目标用户、市场规模写一大堆。模型虽然是语言模型但它执行任务是靠“规则”而非“理解商业”冗长描述只会稀释它对命令和约定的注意力。第二个误区写模糊的期望。像“保持代码风格一致”模型不知道怎么落地。不如写“组件内逻辑代码顺序变量声明、计算属性、生命周期、方法”“CSS 类名统一用 BEM”。具体到能验证模型才能执行。第三个误区不及时更新。CLAUDE.md 是活文档。你改了技术栈、换了命令、发现了新的坑就应该同步更新。否则模型照着过期文档操作反而比没有文档更糟。我一般在每次 git commit 前顺手检查一下这次的改动有没有影响 CLAUDE.md 里的描述有就一并提交。3.4 维护节奏CLAUDE.md 需要像文档一样持续演进新项目第一天CLAUDE.md 可以只有技术栈和命令跑通第一版后补齐目录结构遇到第一个坑后在注意事项里加一条每次模块重构后更新目录约定。这不是额外工作量而是把项目知识从“只在人脑里”沉淀成“团队资产”。我的习惯是让 Claude Code 自己参与维护。每当我让它完成一个较大的改动我会追加一句“更新 CLAUDE.md把这次的约定补充进去。”它自己写的部分我再 review 一遍通常是能用的。4. memory 记忆机制自动学习与主动治理4.1 memory 是怎么产生和写入的Claude Code 的 memory 机制是它区别于普通 AI 编程插件的核心。普通插件换个会话就等于换个新人而 Claude Code 会把对话中明确表达出的偏好沉淀下来。判断依据是内容的稳定性和可复用性。“这个项目用 pnpm”算“今天天气不错”不算。模型会对候选记忆打分只有那些可能对后续会话有用的、跨会话稳定的信息才会写入记忆库。你还可以主动要求它记住。在对话里直接说“记住这个项目的接口统一走 request 封装”它大概率会写入。注意主动说的方式并不是每次都能成功版本不同行为有差异但从我的经验看明确的“记住”句式比隐含偏好可靠得多。4.2 查看、清理与干预记忆防止上下文被垃圾填满记忆长期累积也会出问题。想象一个干了一年活的项目记忆库里塞满了各种临时约定有些已经过时了有些互相矛盾。Claude Code 每次读取记忆时旧信息会干扰它对新命令的理解。这类查询和清理通常在命令面板里完成不同版本命令名会变。你可以在会话中直接问“你记得关于这个项目的哪些约定”或者用/memory相关命令查看。看到明显过时的条目就手动删掉。我个人的清理节奏是每两周扫一眼记忆库把已经完成的一次性约定删掉把仍然有效的沉淀进 CLAUDE.md。这样记忆库始终保持精简召回准确率也高。4.3 memory 与 CLAUDE.md 的联动哪种知识放哪这里有个非常实用的划分原则写进 CLAUDE.md 的所有人、所有会话都应该遵守的显性规范。比如项目命令、命名规则、架构约束。这类知识稳定、可靠应该进版本库共享。写进 memory 的个人工作习惯、临时偏好、项目背景中的隐性细节。比如“我喜欢把新功能放在 modules 目录先实现”“这次重构不要动 auth 模块”。这类知识来源复杂不适合共享。一个常见的反面案例把“不要动 auth 模块”这种一次性提醒写进项目 CLAUDE.md结果三个月后新需求真的需要动 auth 模块Agent 看到 CLAUDE.md 里的规矩就死活不改了。所以判断标准很简单这句约定下个月还有效吗如果只对当前任务有效留在 dialogue 上下文里别放进 CLAUDE.md如果只对你个人有效放 memory如果对团队长期有效才放 CLAUDE.md。4.4 团队协作时的记忆边界团队场景下记忆污染是真实存在的。每个人的 memory 是本地的不会同步给同事而 CLAUDE.md 是共享的。这反而是好事私人的操作习惯不会干扰别人团队的规范又能通过 CLAUDE.md 统一。但有一个坑要注意**不要让 Claude Code 把个人偏好写进共享的 CLAUDE.md。**我有一次让同事跑同一份 CLAUDE.md结果文档里混进了“我习惯用双引号”这种偏好同事的 Agent 也跟着用双引号整个团队的代码风格都乱了。后来我们约定CLAUDE.md 只写“团队都能接受的公约”个人偏好一律放 memory 或用户级~/.claude/CLAUDE.md。5. 配置落地实战安装、接入第三方模型与高频报错5.1 三种安装与集成形态Claude Code 主要有三种使用形态。第一种是命令行版通过 npm 全局安装命令通常是npm install -g anthropic-ai/claude-code安装完在终端里直接敲claude启动。macOS 也可以走 Homebrew。这是最推荐的形态轻量、稳定配置都在~/.claude目录下。第二种是桌面版从官网下载安装包。Windows 和 macOS 都有图形化安装流程。适合不想碰命令行的人但它底层还是调用同一个引擎配置路径一致。第三种是 VS Code 插件。在扩展市场搜“Claude Code”装好后侧边栏有一个面板可以直接在编辑器里对话、看 diff。插件的好处是上下文直接关联打开的代码文件不用手动告诉它“读一下这个文件”。我日常主力是 VS Code 插件终端跑批量任务时切回命令行两种形态共享同一套配置。5.2 第三方模型接入cc switch 与 LM Studio 本地模型Claude Code 官方默认绑定 Anthropic 的服务但社区早就把它玩出了花。热搜里提到的cc switch就是一个小工具专门用来切换 Claude Code 的模型后端支持 DeepSeek、Qwen、GLM 等。它的原理并不神秘Claude Code 支持通过环境变量指定 API 地址和密钥cc switch帮你管理和切换这些配置省得每次手敲。接入后Claude Code 的请求会发到第三方模型的兼容端点。如果你连云端 API 都不想用想跑本地模型就用 LM Studio 这类工具在本地起一个模型服务。但要注意LM Studio 默认提供的是 OpenAI 兼容接口不是 Anthropic 的原生协议所以通常需要一层协议转换。社区常见的做法是装一个claude-code-router之类的中间层把 Anthropic 协议翻译成 OpenAI 协议再指向http://localhost:端口的本地端点。这块我的建议很明确**能用官方 API 就用官方第三方模型适合体验和兜底不适合当生产主力。**原因是工具调用读写文件、执行命令对模型的结构化能力要求极高第三方模型在常规对话上表现不错但一涉及复杂多步工具操作成功率明显下降经常出现“说得好听但动作做错”的情况。5.3 高频报错的排查链路下面这几个报错都是社区里高频出现的问题我按“现象-原因-处理”列一下。报错现象可能原因处理思路提示 organization has disabled claude subscription access企业订阅策略未开放 Claude Code 权限联系管理员在订阅后台放行或改用个人账户登录Windows 下启动报 InternetOpenUrl() failed系统网络组件异常或安全软件拦截检查系统防火墙/安全软件是否拦截重启网络栈后重试提示与 64 位 Windows 版本不兼容下载的安装包架构不对重新从官方渠道下载对应架构的安装包提示服务在所在区域不可用服务商支持范围限制以官方支持范围为准不要使用非官方绕过手段最后一条我特别说明服务商的支持范围是它自己的商业策略任何绕过手段都不符合使用条款我也就不展开讲了。碰上这种情况建议直接看官方文档确认支持范围或者换合规的方式使用。5.4 我的初始配置组合建议如果你从零开始我建议不要一上来就抄复杂配置按以下三步走第一步只加权限白名单。把pnpm *、git *、npm run *放进 allow其他全走确认。先跑一天感受一下权限收敛带来的安全感。第二步写一份极简 CLAUDE.md。只包含技术栈、常用命令、目录结构三块控制在 30 行以内。让 Agent 先“知道路”再“守规矩”。第三步跑一周后看 memory 效果。如果它反复忘记某些事说明你没有明确让它记住或者该沉淀到 CLAUDE.md 了。这套组合足够用两周之后再按岗位需要加 hooks、加子目录 CLAUDE.md、加更细粒度权限。不要试图第一天就配完美配置是要跟着项目长出来的。6. 配置完成后如何验证与持续优化6.1 三项配置是否生效的快速验证方法配置完别急着干活先做三个验证。第一个验证 settings.json。在会话里让它执行一条白名单里的命令比如git status。如果直接执行不再弹确认说明权限生效。再让它执行一条不在白名单的命令比如pwd应该会弹确认。第二个验证 CLAUDE.md。直接问它“根据 CLAUDE.md本项目的测试命令是什么”它如果能准确答出说明自动加载成功。还可以故意让它改一个违反规范的文件看它会不会在动手前提醒你。第三个验证 memory。上一个会话里明确说一句“记住接口文档统一放在 docs/api 目录”然后新开一个会话问它“接口文档应该放哪”。如果能答对说明记忆链路通了。第一次验证 memory 最好手动明确说出来别让它猜。6.2 让配置体系持续演进的三条经验第一条经验每次项目大变更同步改三份配置。换包管理器改 settings 和 CLAUDE.md换目录结构改 CLAUDE.md个人习惯变化改 memory。第二条经验CLAUDE.md 需要 review而且最好让 Claude Code 自己参与 review。我每个季度会让它读一遍项目所有 CLAUDE.md输出一份“哪些过时、哪些缺失、哪些重复”的报告我再决定改哪些。它给自己的文件提意见这个场景本身就好用。第三条经验备份配置。~/.claude/settings.json、~/.claude/CLAUDE.md这些文件我会定期拷贝到自己的配置仓库里。重装环境后几分钟就能恢复完整的工作习惯这个时间成本非常值得。说实话我一开始也以为 Claude Code 的魔力全在模型参数里后来才发现模型只是引擎配置才是方向盘和地图。settings.json、CLAUDE.md、memory 这三样理不顺再强的模型也只是个会写代码的“无头苍蝇”。把这篇文章里的思路过一遍你的 Claude Code 大概率也能从“厉害但失控”变成“厉害且顺手”。

Claude Code配置调优：settings.json、CLAUDE.md与memory三文件实战指南

相关推荐

STM32L041C6驱动MR25H40CDF串行MRAM：工业数据记录新方案

Skills Manager：统一54+AI编程工具技能，打造跨平台桌面中枢

linux-command 之 who 命令详解：查看当前登录用户与登录历史

更多资讯

国内首款SDR AIS基站技术解析：天线到解码链路与实测

Virtuoso从原理图到版图全流程：布局布线验证一次通过指南

行车记录仪碰撞检测全解析：从G-sensor原理到灵敏度调校

OpenAI Astra 模型 249 页论文遭学术不端指控：从 Lean 形式化到 API 复现的验证路径

金融行业的数据中台、大模型与AI Agent：架构落地与实战避坑指南

SPSS预测建模实战：逻辑回归、树模型与广义线性模型选型与解读

今日更新

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本周精选

CMOS设计三大物理效应：体效应、沟道长度调制与亚阈值导电

微信小程序在线阅读毕设全解析：Java后端+MySQL+避坑实战

Android音频问题五层分析法：从App到Codec的系统化诊断

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？