先说个很多新手容易忽略的事实Claude Code 不是一个“装完就能起飞”的工具它的体验天花板基本由三套配置决定——settings.json、CLAUDE.md 和 memory 体系。我见过太多人装好之后直接开始聊结果发现它记不住项目上下文、动不动弹权限窗口、换一个任务又要重新解释一遍背景。今天不聊虚的把我实际在项目里用下来验证过的配置方式、优先级关系、操作步骤和踩坑记录一次性整理出来。这套内容适合谁刚装好 Claude Code 但不知道从哪下手的人已经在用但觉得“它不够懂我的项目”的人以及想给团队统一 AI 使用规范、减少重复沟通成本的人。你可以直接照着抄也可以先看完每一层配置背后的设计逻辑再决定自己到底需要哪几样。1. 先把三大配置体系的分工捋清楚1.1 三个层级对应三种“记忆”很多人第一次听到 settings.json、CLAUDE.md、memory 三个词会以为它们是三个不同名字的同一种东西。实际完全不是。我用一个比较生活化的类比说明settings.json 是“系统设置”管的是 Claude Code 这个工具本身的行为边界。比如用哪个模型、哪些命令允许执行、哪些路径不能碰、要不要带 hook、要不要注入环境变量。CLAUDE.md 是“项目交接手册”管的是“这个项目是干什么的、用什么命令跑、有什么架构约束、哪些事千万别做”。它面向的是具体业务和代码库。memory 体系管的是“跨会话的长期记忆”。Claude Code 每次对话本质上是一次独立会话如果没有记忆机制它不会自动记得你上次定了什么技术决策、你个人偏好什么风格、哪些命令是你反复用的。三者之间的关系可以理解成settings.json 决定“AI 能做什么”CLAUDE.md 决定“AI 在该项目里该怎么做”memory 决定“AI 下次见面还记不记得你是谁、项目走到哪一步”。1.2 为什么官方要把配置拆成三份而不是塞进一个文件这不是故意造概念而是三种信息的生命周期完全不同。工具级配置很少变装好一次可以沿用半年项目级约定跟着代码仓库走换人、换机器都要同步而个人记忆和会话历史则是动态增长的。如果全部揉进一个文件要么升级覆盖时全丢要么团队协作时互相踩踏。从工程角度看这个拆分还有一个好处可以针对不同环境做不同组合。同一个全局 settings.json配合不同项目的 CLAUDE.md出来的行为就完全不同。项目 A 不需要允许执行数据库迁移命令项目 B 需要这些差异写在项目级文件里而不是改全局配置既安全又干净。我用一个表格把三个层级的核心差异列出来方便你对照配置层级典型位置管什么变更频率生效范围settings.json用户级~/.claude/settings.json模型、权限、hooks、env低全局所有项目settings.json项目级项目根目录 .claude/settings.json覆盖或补充全局配置中仅当前项目CLAUDE.md项目级项目根目录 CLAUDE.md项目背景、命令、约束随项目演化当前项目的会话CLAUDE.md用户级~/.claude/CLAUDE.md个人偏好、通用工作流低所有项目memory会话/记忆会话历史、记忆服务跨会话上下文、决策记录高按会话恢复使用2. settings.json决定工具行为的关键入口2.1 配置文件的位置与优先级关系settings.json 主要存在于两个位置用户级~/.claude/settings.json作用于这台机器上的所有 Claude Code 项目。项目级当前工作目录下的.claude/settings.json只作用于当前项目。当两个文件同时存在时项目级配置会与用户级配置合并。合并的单位是“配置项”不是整个文件覆盖。也就是说项目级配置里写了 permissions用户级配置里的 model 依然生效两者不冲突。这个设计方便你在全局设置好模型和环境变量在项目级只聚焦权限差异。我建议的默认做法是用户级只放稳定且与业务无关的配置比如默认模型、全局环境变量、输出格式项目级放与项目绑定的权限、命令白名单、以及会随项目变化的开关。这样换项目时全局配置不用动项目级配置跟着仓库走团队成员拿到的行为是一致的。2.2 核心配置项逐条解读下面是一份我在真实项目中使用的配置模板去掉敏感信息后结构如下{ model: claude-sonnet-4-0, permissions: { allow: [ Bash(npm run *), Bash(python scripts/*.py), Read(backend/**), Write(backend/**) ], deny: [ Bash(rm -rf *), Write(.env) ], ask: [ Bash(git push *), Edit(node_modules/**) ] }, env: { MY_SERVICE_URL: http://localhost:8080 }, includeCoAuthoredBy: true, statusLine: { type: fixed, text: coding-agent }, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node scripts/audit.js \$CLAUDE_TOOL_USE_INPUT_JSON\ } ] } ] } }逐项说明一下model指定当前对话使用的模型。不同项目可以选用不同模型成本敏感的用轻量模型复杂重构用更强模型。注意这个字段也可以不写直接用环境变量或对话内切换。permissions是三个字段里最重要的一个。它决定 Claude 在执行工具调用前是直接放行、直接拒绝还是弹窗问你。很多人抱怨“为什么我的 Claude 每执行一个命令都要问我”原因就是你只用了默认配置。把常用命令写进allow日常操作会顺畅很多。但我不建议把权限放开到Bash: true这种全量放行后面问题排查部分会讲我因为这个写法吃过什么亏。deny优先级高于allow。就算你 allow 了Bash(*只要 deny 里有Bash(rm -rf *)删除命令依然会被拦下。这个优先级设计很关键我建议把危险命令、敏感文件路径都放进 deny。env用来给工具进程注入环境变量。如果你的项目在本地需要一些自定义配置比如服务地址、功能开关写在 settings.json 里比写在 shell profile 里更可控而且会随项目配置一起分发。includeCoAuthoredBy控制在提交信息里是否带上 AI 协作署名。团队协作时这个字段很有用方便追溯哪些代码是 AI 生成或深度参与的。statusLine是自定义状态栏显示。多项目并行时我靠它在终端里快速分辨当前会话属于哪个项目。hooks是高级用法可以在工具调用前或调用后执行自定义脚本。我在 PreToolUse 里挂了审计脚本每次 Claude 准备执行 bash 命令时脚本会把命令内容发给内部门禁服务做检查命中高危指令直接拦截。这个对生产环境敏感项目非常有用。2.3 用第三方推理服务时的环境变量配置很多团队不直接用官方服务而是通过兼容 Anthropic API 的网关或第三方推理服务来接入模型比如社区里常见的 DeepSeek、Qwen、GLM 等模型。Claude Code 本身支持通过环境变量指定 API 地址和密钥export ANTHROPIC_BASE_URLhttps://your-gateway.example.com export ANTHROPIC_AUTH_TOKENyour-token export ANTHROPIC_MODELdeepseek-chat claude这三个环境变量也可以写进 settings.json 的env字段里效果相同。社区里流行的 cc-switch 这类工具本质就是帮你在这几组环境变量之间快速切换省去每次手动改配置的麻烦。我要提醒两句。第一不是所有第三方模型都能完美兼容 Anthropic 的工具调用格式实际使用中经常出现“对话正常但工具返回空结果”的情况遇到这种问题先换回官方模型验证别急着改业务代码。第二第三方 API 的密钥安全级别通常比官方低不要把生产环境的 .env 文件放在 Claude Code 默认读取的路径下更不要让权限配置允许 AI 随意读取密钥文件。3. CLAUDE.md把项目背景写成 AI 的“操作手册”3.1 CLAUDE.md 放在哪里、什么时候生成CLAUDE.md 是 Claude Code 的项目记忆文件。默认情况下会在当前工作目录寻找CLAUDE.md文件并在每次会话启动时将其内容作为项目上下文的一部分读入。一个很实用的命令是/init。在项目根目录启动 Claude Code 后输入/init它会扫描项目结构、读取主要代码文件、识别技术栈然后自动生成一版初始的 CLAUDE.md。我建议把这版当作草稿因为它通常偏泛真正有价值的内容还是需要你基于对项目的理解去补充。另外你可以在对话中通过#命令手动引入其他文件比如# docs/architecture.md这等于临时把某份文档作为上下文导入。但要注意这种导入只对当前会话生效下次对话不会自动加载。想持久生效还得写进 CLAUDE.md。3.2 一份高价值 CLAUDE.md 应该写什么我见过太多把 CLAUDE.md 写成“项目吹嘘文档”的。真正好用的 CLAUDE.md 不是给人类看的而是给 AI 看的操作手册。核心内容包括七个要素项目定位这个项目是干什么的属于什么系统边界在哪里。常用命令启动、测试、构建、迁移、代码检查全部给出可直接执行的命令。技术栈与目录结构让 AI 不至于去错误的目录找代码。架构约束哪些层可以依赖哪些层哪些模式禁止使用。工作流新增功能、修 bug、发版分别要走什么流程。已知问题与决策记录项目里有哪些“历史包袱”为什么当时做了这个决定。不要做清单明确禁止 AI 触碰的文件和操作。下面是我某个订单中台项目里的精简示例# Project: order-service ## 项目定位 - 订单中台服务负责下单、支付回调、履约状态机。 - 只处理交易域不处理用户注册、商品管理。 ## 常用命令 - 启动make dev - 测试make test - 单测单个文件pytest tests/test_order.py -k resubmit - 数据库迁移alembic upgrade head - 代码检查ruff check . ## 架构约束 - 六边形架构业务逻辑不依赖 Flask/Django ORM。 - 对外只暴露 REST API禁止直接暴露内部队列。 - 新增功能必须带 migration 与测试。 ## 代码风格 - Python 3.11类型标注必须完整。 - 错误码统一格式SVC_模块_编号。 ## 常见任务 - 新增支付渠道先扩展 PayProvider 接口再注册到 Factory。 - 遇到幂等冲突检查 idempotency_key不要直接改库。 ## 不要做 - 不要修改 db/migrations 已发布的版本文件。 - 不要在异步任务里同步调用外部 HTTP。如果 CLAUDE.md 写成这样Claude Code 拿到任务时基本不会跑偏。它知道先跑哪个命令验证、在哪个目录改代码、哪些约束不能破坏。3.3 让 CLAUDE.md 真正“被读到”的三个技巧第一个技巧是要诚实面对 token 预算。CLAUDE.md 不是越长越好它会在每次会话启动时被载入上下文直接影响可用的上下文长度。文件太长重要信息反而被淹没。我个人的经验是控制在 100 行以内只保留高频依赖的信息细节放其他文档通过#按需引入。第二个技巧是让文件里的命令和约定“可验证”。AI 会倾向于相信文件里的描述如果命令写错了它会基于错误命令反复尝试浪费大量时间。所以每一条命令都应该在真实环境里跑通后再写进去。第三个技巧是处理“为什么不生效”的排查。如果 CLAUDE.md 内容没效果先确认文件是不是在正确的位置再确认权限配置是否阻止了它对文件的读取最后检查会话内是否有用户指令覆盖了文件中的约定。用户在当前会话里临时给出的指令优先级高于文件这不是 bug是设计。你可以在对话里问一句“按照 CLAUDE.md 里的约定我应该怎么做”就能验证它是否真的读到了。4. memory记忆体系跨会话记住的正确姿势4.1 先纠正一个误解Claude Code 没有“一个 memory 文件”很多人在找类似memory.json的单文件来存记忆这是个误解。Claude Code 的 memory 由几个不同部分构成用户级 CLAUDE.md~/.claude/CLAUDE.md存个人偏好和通用工作流。比如“所有提交信息使用 Conventional Commits 规范”“遇到不确定的架构问题时先列方案再动手”这些偏好应该在这里。项目级 CLAUDE.md存项目状态、约定和决策记录在第 3 节里已经详细讲了。会话历史Claude Code 支持恢复历史会话通过claude --continue继续最近的会话或者用claude --resume指定具体会话。此外还有第三方工具和 MCP 生态提供的记忆服务比如把关键信息写入外部向量库的 memory server。这类方案更适合“跨项目、跨场景的海量记忆”需求对大多数开发者来说先把手动维护 CLAUDE.md 学会比引入外部记忆服务更实用。4.2 把项目的“长期决策”写进 CLAUDE.mdClaude Code 每个新会话都是干净的它不会自动记得上个会话你拍板了什么方案。最常见的痛点是连续开发三天后突然发现AI 还在用三天前已经废弃的接口。我的解决办法是每次做了影响后续开发的技术决策立刻追加到 CLAUDE.md 的决策记录区。举个例子## 决策记录2025-06 - 缓存客户端从 Redis Cluster 切换到 Valkey新代码一律使用 valkey-py。 原因集群运维成本高社区重心已经迁移。 影响历史缓存 key 需要在首次访问时做双读迁移。 - 支付回调接口的签名算法改为 HMAC-SHA256。 原因SHA1 已不再被安全团队接受。 影响旧商户需要重新生成密钥。这样做的原理很简单CLAUDE.md 是项目会话的共享记忆每次新会话都会自动加载决策一旦写进去后续所有对话都能看到。不需要依赖 AI 的“记忆能力”而是把记忆工程化。这种“决策记录”格式有固定的模板包括做了什么、为什么、影响什么。我坚持了几个月最大的价值是当有人问“这个接口为什么要这么设计”时直接翻 CLAUDE.md 就能看到当时的背景不用考古 Git 历史。4.3 会话恢复、续写与记忆清理命令行里有两个常用参数claude --continue和claude --resume。前者恢复最近一次会话适合昨天没干完的活今天继续后者可以指定更早的会话比如claude --resume 重构支付模块适合多个任务并行时切换到指定上下文。我的习惯是跨天开发同一任务时优先--continue而不是新开一个干净会话。因为任务相关的中间结论、已经排查过的方向都在历史里新会话意味着重新建立上下文。但也不是所有场景都适合继续如果任务方向已经发生了大调整继续旧会话反而会被过时的上下文带偏这时候就应该新开会话并且只引入当前需要的 CLAUDE.md 内容。记忆清理同样重要。CLAUDE.md 里的旧决策可能会和新需求冲突比如决策记录说“用 A 方案”但业务已经转向 B 方案AI 读到旧记录就会给出过时建议。我建议每两周左右 review 一次项目级 CLAUDE.md删除已经完成的临时记录更新过时的决策。这个习惯比任何第三方记忆工具都有效。5. 安装、升级与编辑器接入的完整流程5.1 安装与升级从命令行到团队机器Claude Code 官方推荐的安装方式是通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后用claude --version验证是否成功。macOS 和 Ubuntu 走这条命令基本没有坑Windows 建议在 WSL 里使用原生 PowerShell 下的表现要差一些。升级也很简单。Claude Code 自带在线升级命令claude update如果你的权限不够npm 全局安装目录可能会报 EACCES 错误这时候不要偷懒加 sudo而是检查 npm 的全局安装目录是否属于当前用户或者用 nvm 管理 Node 版本从根上解决权限问题。官方文档里保留了很完整的配置说明关键词可以直接搜Claude Code settings documentation、Claude Code memory documentation、CLAUDE.md guide。配置类的文档建议以官方最新版本为准因为这个工具迭代速度很快社区里半年前的教程很可能已经过时。5.2 与 VS Code 集成在编辑器里直接使用Claude Code 默认跑在终端里但很多人更习惯在 VS Code 里工作希望 AI 能直接看到当前打开的文件、选中的代码、项目侧边栏。官方提供了 VS Code 插件装上之后可以直接在命令面板里唤起 Claude Code也可以放到侧边栏或底部面板用。实操上我推荐的方式是保留一个终端专门跑 Claude Code同时打开 VS Code 作为文件查看器。插件最大的好处是能把编辑器上下文带给 AI你在编辑器里选中一段代码AI 能更准确地理解你指的是哪部分。但这也有一个副作用就是上下文来源变多之后AI 可能混淆“当前打开的文件”和“项目实际需要的文件”所以要适当约束它的关注范围。和 VS Code 配合时一个小注意点编辑器里改了文件后记得先保存再让 Claude 操作。它读取的是磁盘上的文件内容不是编辑器内存里的未保存版本。我踩过几次“AI 生成的代码基于旧内容”的坑后面学乖了先把文件保存好再发指令。5.3 终端命令的非交互式执行与账号模式Claude Code 不只是交互式聊天工具也可以直接在命令行里传任务claude -c 运行测试并总结失败用例或者配合管道使用cat error.log | claude --print 根据日志分析线上故障原因这种非交互模式很适合接进 CI 流程、定时任务、自动化脚本。比如我在提交代码前会跑一个检查脚本把 diff 内容发给 Claude Code 做初步 review再把结果挂到评论里。这个流程不需要人工坐在终端前效率提升非常明显。关于注册和不注册的区别事实是这样如果你走官方渠道需要登录 Claude 账号并配置相应订阅权限正常交互使用。如果团队接的是第三方推理服务则通过ANTHROPIC_AUTH_TOKEN配置第三方服务的密钥这种情况下不需要登录 Claude 官方账号但你需要自己管理密钥、额度以及配套的环境变量。两种模式我用表格对比一下对比项官方账号模式第三方 API 模式登录要求需要 Claude 账号并登录不需要配置密钥即可密钥管理官方统一管理自己管理注意泄露风险模型选择官方模型全家桶取决于第三方服务提供的模型工具调用兼容性官方最优取决于服务实现可能不稳定适用场景个人使用、生产环境团队网关、成本敏感场景6. 常见问题排查与避坑经验6.1 问题速查表以下这些问题是我自己在使用过程中以及帮同事排查时遇到的高频问题整理成表格方便检索问题现象常见原因解决办法终端里找不到claude命令npm 全局目录不在 PATH检查 npm 全局路径把它加到 shell profile安装或升级报 EACCES 权限错误npm 全局目录权限不对重新配置 npm 全局目录归属不要用 sudo 硬扛启动时出现区域可用性提示账号状态或支持地区问题核对官方文档可用性说明确认订阅状态合规使用官方渠道修改 settings.json 后无效文件路径写错或 JSON 语法错误先确认实际加载路径再用 JSON 解析器验证语法permissions 疯狂弹窗允许规则覆盖范围太小把高频操作的正则写进 allow危险操作留在 ask项目级配置不生效目录层级选错.claude/settings.json必须在项目根目录下CLAUDE.md 没起到作用文件位置不对或写法太泛确认在项目根目录内容要具体到命令和约束第三方模型返回空工具结果模型不兼容工具调用格式换回官方模型定位确认是模型还是配置问题hooks 没有触发matcher 写错或脚本退出码异常逐个 hook 调试先验证脚本本身能独立执行6.2 排查思路三连遇到问题不要一个配置来回改。我习惯按三步走第一步先确认“配置真的被加载了吗”。用最小的改动做验证比如在 settings.json 里加一个明显的 statusLine 文本启动后如果界面没变化说明这份配置压根没被读。第二步采用最小化复现。把所有自定义配置清空只保留问题相关的配置项看问题是否仍然出现。比如权限弹窗问题先用一个最简单的 permissions 配置测试如果正常再逐步把规则加回去定位是谁导致的冲突。第三步搞清楚干预的时机。有些“不生效”其实是优先级问题项目级配置覆盖了用户级配置会话中临时指令覆盖了文件配置模型本身能力不满足需求。确认一下当前行为是被哪一层决定的再去改对应那一层比盲目改文件有效得多。6.3 我踩过的几个坑第一个坑是给权限放了全量 allow。早期图省事直接把 Bash 权限全开结果有一次 AI 在重构时误执行了清理脚本虽然没造成严重后果但把我吓得够呛。建议无论如何deny 里都要保留高危命令的兜底规则。第二个坑是把 CLAUDE.md 写得太长。第一次用的时候恨不得把整个项目说明都塞进去结果每条指令都要烧掉大量 token响应也变慢。后来改成“高频信息放 CLAUDE.md低频信息放 docs 里按需引入”体感立刻不一样。第三个坑是项目级配置覆盖全局导致 hooks 失效。因为合并规则是“配置项级合并”我在项目级 settings.json 里只写了 permissions理论上不该影响全局 hooks但实际排查时发现全局 hooks 确实没跑。后来发现是项目级配置文件里 hooks 字段写成了空数组直接把全局值覆盖了。这提醒我写配置文件时要清楚字段的合并策略不确定就尽量别写该字段。第四个坑是升级后旧配置失效。Claude Code 迭代速度很快版本升级时个别配置字段会被改名或废弃。我养成了一个习惯每次升级完先跑一遍核心任务确认关键配置都还生效再进入正常工作流。最后再分享一点个人体会这套配置体系里投入产出比最高的不是 settings.json也不是那些花哨的 hooks而是 CLAUDE.md。它等于把项目里那些只存在于你脑子里的上下文变成了一个团队共享的、AI 可读取的持久记忆。先花半小时把 CLAUDE.md 写扎实再回头调权限和记忆你会明显感觉到 Claude Code 从一个“问答工具”变成一个“默认懂行”的协作伙伴。