先说个我自己的感受同样是用 Claude Code有人把它用成只会改 bug 的终端玩具有人却把它用成了团队里最靠谱的实习生。差别真的不在模型本身而在你往配置文件里塞了什么。Claude Code 的配置体系拆开来看就三块settings.json、CLAUDE.md、memory。一个管行为边界一个管上下文注入一个管跨会话的长期记忆。把这三者的分工、优先级、写法搞清楚配置就是一件一劳永逸的事搞不清楚就会像我最早一样每天都得在对话里重复解释项目背景改个权限还要翻半天文档。这篇文章我就按自己的实操经验把这套体系完整拆一遍。不打算面面俱到地罗列文档而是把三套配置的逻辑讲清楚再把常用参数、编写方法、易错点都给你落到能直接用的程度。1. 三套配置的分工逻辑先搞清楚它们各自管什么很多人一上来就急着改配置结果 settings.json 里写了一堆项目说明CLAUDE.md 里又塞满了权限规则最后发现该生效的没生效不该生效的乱触发。我建议你先别管具体语法把分工这件事想明白。1.1 settings.json控制行为的总开关settings.json 是给 Claude Code 本身用的配置文件它的本质是工具级的行为控制。你在这里告诉 Claude Code用什么模型、单次响应最多输出多少 token、哪些命令可以自动执行、哪些文件不能碰、走什么登录方式、要不要在 git 提交里带上署名。它不负责告诉 Claude Code这个项目是做什么的那根本不是它的职责。settings 是分层存在的用户级、项目级、本地级可以互相覆盖这个细节我在后面单独说。它的加载时机是启动阶段改完配置之后基本都需要重启会话或重载配置才会完全生效。1.2 CLAUDE.md注入上下文的说明书CLAUDE.md 解决的是另一个问题如何让 Claude Code 在每次对话开始时不靠你重复就自动知道项目的地基信息。比如项目是什么、技术栈是什么、测试怎么跑、代码风格有什么约定、哪些目录不能动。你可以把它理解成一份给 AI 同事看的入职手册。新人入职第一天读手册Claude Code 是每次会话开始都会读一遍。它读到的内容会作为系统上下文的一部分参与后续所有对话所以写得越精准你后面要补充解释的就越少。这个文件是大多数用户配置体系里收益最高的一块后面我会给模板。1.3 memory跨会话的经验沉淀池memory 管的是从一次会话带到下一次会话的经验和偏好。Settings 和 CLAUDE.md 更多是你主动写好的静态信息而 memory 是动态沉淀出来的你在这轮对话里反复强调过接口路径尽量用 /api/v2 前缀、你纠正过它三次这个模块不要用相对路径导入类似这样的信息会被记录到记忆里在后续会话中自动调取。这一点我会在第四章详细讲存储位置和管理方法。这里你只需要记住一个大原则三套配置里settings 是骨骼CLAUDE.md 是肌肉memory 是大脑皮层。骨骼定形肌肉给力皮层积累经验。1.4 加载顺序与优先级我自己整理过一个优先级关系虽然官方文档不一定这样表述但按这个理解去配置基本不会出岔子配置层级文件位置优先级用户级 settings~/.claude/settings.json最低基线配置项目级 settings.claude/settings.json覆盖用户级本地级 settings.claude/settings.local.json覆盖项目级通常不进 git用户级 CLAUDE.md~/.claude/CLAUDE.md全局基础上下文项目 CLAUDE.md项目根目录 CLAUDE.md 或 .claude/CLAUDE.md会话内核心上下文memory用户目录与项目目录下的记忆文件自动叠加动态更新优先级从低到高越靠后的配置越贴身。这个顺序决定了你排障时的判断方向配置不生效先看是不是被更低层级的文件覆盖了而不是怀疑工具坏了。2. settings.json一份配置文件的三级落点与高频参数settings.json 是绝大多数人最先接触的配置文件但很多人连该把文件放哪都没搞对。这个文件不是一个而是三级分布。2.1 三个文件的定位与取舍~/.claude/settings.json用户级全局配置。适合放所有项目通用的内容比如默认模型、登录方式、权限基线、全局环境变量。.claude/settings.json项目级配置。放在项目根目录下跟着项目走。适合放这个项目特有的权限规则、额外的模型参数、项目级环境变量。.claude/settings.local.json本地配置。内容通常是不能分享给同事的个人设置比如本地路径、调试用的临时环境变量。这个文件建议加进 .gitignore。我的个人习惯是一条非常朴素的原则能放全局的就不放项目级能放项目级的就不放本地级。本地级能不放就不放因为它是容易丢失的临时补丁用得越多越混乱。2.2 高频配置项拆解settings.json 里有一批我每次配置新机器都会用到的参数我直接给你列个表配置项作用使用示例model指定会话使用的模型model: claude-sonnet-4-20250514maxTokens单次生成的最大 token 数maxTokens: 4096permissions权限规则allow/deny 白名单与黑名单见下方示例env注入环境变量env: { MY_FLAG: 1 }includeCoAuthoredBygit 提交是否附带 Co-Authored-Bytrue / falsecleanupPeriodDays会话记录保留天数30forceLoginMethod强制指定登录方式web / api-keyapiKeyHelper自定义获取 API Key 的方式node ~/.claude/get_key.jshooks事件钩子在特定时机执行脚本见文末补充statusLine自定义终端状态栏显示内容{type:json}model 这个参数值得多说一句。官方模型名是一个长串如果你不写工具会用默认模型但默认模型不一定是最适合当前任务的。模型名写错时会报 model not found 之类的错误你这时的第一反应应该是去确认版本号而不是反复重试。再就是 env。设置环境变量有两种途径一是写在 settings.json 的 env 字段里二是通过系统环境变量或 .env 文件注入。settings.json 里的 env 优先于系统环境变量因为它在进程启动时会被读入。如果你要对接自己公司的代理网关或者内部模型服务通常走 env 配置最干净。2.3 权限规则的粒度与写法权限是 settings.json 里最值得花时间研究的部分也是新手最容易放弃的部分。权限规则的思路很简单把危险操作挡住把高频安全操作放行。常见的权限维度包括文件读写、Bash 命令、网络请求、MCP 工具。规则串的写法大概是操作类型(目标模式){ permissions: { allow: [ Read(logs/**), Read(docs/**), Edit(src/**), Write(src/**), Bash(git:*), Bash(npm test), Bash(npm run build), WebFetch(example.com), mcp__github__get_issue ], deny: [ Bash(rm -rf *), Read(.env), Bash(npm publish), Write(.env) ] } }allow 列表里没写到的操作默认会进入询问模式也就是每次执行前弹确认。如果你希望某些操作直接静默通过就把它们填进 allow希望完全不触发就填进 deny。我的建议是 allow 保持克制宁可多问一次也不要为了省事把Bash(*:*)直接放行。这个习惯能帮你避开很多一觉醒来发现目录被格式化的极端场景。additionalDirectories也值得记一下。默认情况下 Claude Code 能访问的目录是有限制的如果项目需要读取仓库外的另一个目录比如共享配置文件目录你需要在配置里显式声明额外允许访问的目录{ permissions: { additionalDirectories: [ /home/me/shared-configs ] } }2.4 一份可以直接改的完整配置示例我平时新机器上的全局配置大致长这样{ model: claude-sonnet-4-20250514, maxTokens: 8192, includeCoAuthoredBy: true, cleanupPeriodDays: 30, permissions: { allow: [ Read(~/workspace/**), Edit(**), Write(**), Bash(git:*), Bash(npm:*), Bash(node:*) ], deny: [ Read(.env), Read(*.pem), Bash(sudo *), Bash(rm -rf /) ] } }注意这个示例里的 allow 写得比较宽适合自己一个人开发的场景。如果是团队协作我建议把 Edit/Write/Bash 的规则再收紧因为工具的行为会被其他人复用越宽松越容易出不可控的变更。3. CLAUDE.md让工具从会写代码变成懂项目settings.json 管的是工具怎么运行CLAUDE.md 管的是工具怎么理解你的世界。这是我觉得性价比最高的配置也是很多人完全忽略或写成了流水账的一份文件。3.1 CLAUDE.md 的读取机制CLAUDE.md 一般放在项目根目录文件名就固定叫CLAUDE.md。用户主目录下的~/.claude/CLAUDE.md则是全局版本相当于所有项目的通用背景。每次会话开启时工具会读取这些文件把内容作为上下文的基础组成部分。一个容易忽略的细节是CLAUDE.md 支持引用其他文件。你可以在文件里用路径的方式导入其他补充文档# 项目说明 主要说明见 ./docs/PROJECT_OVERVIEW.md 架构细节参考 docs/ARCHITECTURE.md这样一来CLAUDE.md 自身可以保持精简细节都留在 docs 目录里。这个机制的好处是避免单文件过长等于把 AI 的入职手册做了目录拆分。3.2 值得写的四类内容结合我用下来的经验CLAUDE.md 最该包含的是下面这四类内容项目管理信息项目是做什么的、当前处于什么阶段、主要交付物在哪里。技术栈与命令语言版本、包管理器、测试命令、构建命令、代码检查命令。这部分能大幅减少帮我跑一下测试时的来回确认。代码风格与结构约定目录如何组织、命名规范、是否使用类型、错误处理风格、数据库访问方式。Claude Code 知道这些之后生成的代码会更贴项目。限制与注意事项绝对不能改动的目录、遗留的坑、上线前必须做的检查、敏感信息的位置。写的时候有一个核心原则写稳定的、频繁使用的信息不写一次性的、临时的信息。比如当前正忙着重构用户模块这种状态信息不适合写进 CLAUDE.md因为它是会过期的会导致上下文误导。这种内容更适合放到对话里临时说或者用 memory 去沉淀。3.3 一份可复制的 CLAUDE.md 模板我自己的项目 CLAUDE.md 大概是这个结构你可以直接拿去改# 项目名称 基于 Next.js 14 TypeScript 的中台管理系统负责订单、用户、商品三个核心模块。 ## 技术栈 - Next.js 14App Router - TypeScript 5.x - Tailwind CSS - Prisma PostgreSQL ## 常用命令 - 安装依赖pnpm install - 启动开发pnpm dev - 跑测试pnpm test - 构建产物pnpm build - 代码检查pnpm lint ## 目录结构 - app/Next.js 页面路由 - components/通用组件 - lib/与数据库、外部 API 相关的逻辑 - prisma/数据模型与迁移文件 - public/静态资源 ## 代码风格约定 - 组件用函数式写法禁止使用 class 组件 - 所有 API 响应统一走 ApiResponseT 包装 - 日期统一用 ISO 8601 字符串 - 新增依赖必须先评估体积影响 ## 注意事项 - prisma/migrations 目录禁止手动修改 - 任何涉及订单金额的改动都要先过一遍测试 - .env 文件不提交配置项优先走环境变量这个模板的核心操作是把常见问题前置。每个人问 AI 的高频问题就那些你全部写进去后面就不用再重复。3.4 最容易踩的误区我见过最多的问题是把 CLAUDE.md 写成详细文档。文件里全是一大段一大段的背景介绍真正有用的命令和约定反而淹没在文字里。你要知道这份文件是要被快速阅读理解的不是给人写的周报所以尽量用短句、列表、命令块把信息密度提上去。另一个误区是写一次就不管了。项目结构一变CLAUDE.md 里的内容就会变成误导信息。你重构了目录如果文档还写着老路径AI 就会往错误的方向引。我给自己定的规矩是每次调整目录或改核心依赖时顺手把 CLAUDE.md 同步掉花不了三分钟。4. memory长期记忆是如何沉淀和管理的memory 是三套配置里最容易被低估的一个。很多人配完 settings.json 和 CLAUDE.md 就收工了结果发现每次开新会话AI 还是会忘掉你喜欢什么、讨厌什么。这就是 memory 的价值所在。4.1 memory 存在哪里记忆是分层存放的。用户级的记忆通常在用户主目录的.claude目录下以 markdown 或结构化的形式存在对应的是跨项目的个人偏好比如你习惯用 pnpm 而不是 npm提交信息里喜欢用 conventional 格式。项目级的记忆则在项目的.claude目录下记录的是这个项目特有的约定和当前状态。这里有个容易混淆的点~/.claude/CLAUDE.md和 memory 文件是不同的。CLAUDE.md 是你主动写的静态说明书memory 文件是工具在会话过程中自动沉淀的动态记录。前者是出生自带的认知后者是经历多了长出来的经验。4.2 记忆的写入触发记忆不是随便什么对话都记的它的写入有比较明显的行为模式。当你明确说记住 XXX时它大概率会写入当你在对话里反复纠正同一个问题或者在多轮对话末尾表达出偏好时也会触发沉淀。比如你跟它说以后所有组件文件一律放 src/components不要再问我这就会被记下来。需要注意记忆的写入不是 100% 立刻可见的。它会随会话过程逐步整理可能在当前会话内就生效也可能在后续会话中才开始调取。我的体感是显式要求记住的时候可靠性最高隐含的偏好记录有时会有点随机。所以重要的事情我建议你直接明说记住这条。4.3 主动管理记忆的实操方法自动沉淀的好处是不用费心但坏处是时间长了会堆积大量过时信息。所以记忆管理这件事核心不是写入而是整理。我每隔一两周就会做一次记忆清理。流程很简单先扫一遍记忆文件把那些已经不成立的偏好删掉或改写。比如上次项目里约定用相对路径导入这个项目结束了新项目更习惯用 alias 导入那这条旧记忆就应该清掉否则新项目里 AI 会沿用旧约定。另外一个实用技巧是为不同项目建立不同的记忆边界。通用偏好放用户级记忆项目特有约定放项目级记忆不要把所有内容都堆到一处。这样换项目时不至于被上一个项目的遗留记忆污染。4.4 与 CLAUDE.md 的边界怎么划分这是我在实际使用中最常被问到的问题记忆和 CLAUDE.md 好像都在给 AI 喂信息到底该写哪里我的划分标准很简单判断维度写进 CLAUDE.md写进 memory信息稳定性长期有效项目持续推进都要用短期经验或随项目阶段变化来源主动整理团队统一约定会话中自动沉淀或个人偏好使用者谁打开项目都能读到更贴近你自己的使用习惯变更频率低改了要同步团队成员高可随时调整举例来说项目使用 pnpm 这种可以写进 CLAUDE.md因为它是团队的共同事实我更喜欢破坏性变更放在单独提交里这种属于个人偏好更适合靠 memory 沉淀。两者边界清楚了配置就不会重叠冗杂。5. 配置现场最常见的报错与排查流程配置过程很少一次顺滑很多报错其实是配置体系理解偏差导致的。我挑几个高频问题讲讲排查思路。5.1 auto-update failed: no write permission to npm prefix这个是热门问题我第一次遇到时也很懵Claude Code 自动更新时会去改 npm 全局包目录如果该目录属于 root就会报这种权限错误。排查链路其实很简单# 1. 先看 npm 全局目录在哪 npm config get prefix # 2. 看目录属主 ls -la $(npm config get prefix)如果目录显示属主是 root说明权限被系统级包管理锁死了。常见解法有两个用chown把目录归属权还给你自己适合单机开发环境更推荐的做法换用 nvm 管理 node让全局目录落在用户目录里用 nvm 的方案是治本的因为它把整个 node_env 都收进了~/.nvm下面npm 全局目录自然是你有写权限的地方。如果你的 node 本来就由系统包管理器安装那大概率会遇到这种更新失败的问题。如果你暂时不想动环境也可以禁用自动更新改成手动更新。方法是在环境变量里设置DISABLE_AUTOUPDATER1之后需要更新时手动执行npm install -g anthropic-ai/claude-code即可。5.2 配置改了半天不生效这是第二个高频问题我明明改了 settings.json为什么行为没变化大多数时候是三个原因文件放错位置。比如把项目级配置写到了~/.claude/项目根目录下根本没有.claude/settings.json。被更低层级的配置覆盖。我在第一章讲的优先级这里就是实战场景项目级 allow 了一堆规则本地级 deny 了一条更具体的规则实际表现可能和你预想的不一样。改动后没重启会话。配置读取发生在启动阶段正在运行中的会话不会热加载全部配置。改完配置我建议直接重启会话验证。排查的顺序建议先确认文件位置再看优先级覆盖最后重启。按这个链路走基本五分钟内能定位八成的不生效问题。5.3 权限提示与策略调整还有一种情况是一个命令本该能执行却被拦住了提示 permission denied 或 ask for approval。这时候不要直接往 allow 里堆规则先想清楚是这个操作本身不该做还是操作合理但规则遗漏。我见过有人嫌烦直接把Bash(*:*)放进 allow这种省事会带来极大的安全隐患。合理的做法是精确放行{ permissions: { allow: [ Bash(docker compose up*), Bash(pnpm dlx prisma:*) ] } }这种写法只放行你真正高频使用的命令组合其他命令继续保持询问状态。刚开始会多点几次确认但多运行几次之后你就知道哪些需要常驻白名单了配置会越来越顺手。6. 三套配置在真实项目里的协同方案最后用一个实际项目场景把三套配置串起来看。假设你在做一个基于 Next.js 的中台系统团队三人协作。全局 settings.json 放的是个人偏好和底线规则默认模型、co-authorship、token 上限、.env和敏感文件不可读。项目 settings.json 放的是项目级允许的命令和目录范围允许访问/shared-config目录、允许pnpm相关命令、拒绝pnpm publish。项目 CLAUDE.md 放的是项目背景、技术栈、目录结构、测试命令、代码风格、注意事项。如上文模板。用户级 memory 沉淀的是你个人偏好喜欢用 pnpm、提交信息带 emoji 前缀、重构时先过 lint。项目级 memory 沉淀的是项目特有经验这个项目的订单模块对金额判断非常敏感AI 在改单相关代码时会更谨慎上次重构用户模块时踩过数据库索引的坑这次会自动避开。这套配置跑起来之后的效果是你新建会话Claude Code 自带所有项目背景你提一句把用户列表页改一下它知道用哪个路由文件、遵守什么代码风格它知道数据库改动后要提醒你跑迁移它不会去碰.env。你重复解释的频次会断崖式下降。最后再分享一个我踩过几次坑之后的体会三套配置不是一次配完就完事的静态资产而是需要随项目演进的活文档。特别是 CLAUDE.md 和 memory前者跟着架构改后者跟着习惯变。我现在的习惯是每周花十分钟扫一眼配置文件该删的删、该补的补。这十分钟的投入换来的是一周里少说几十句重复的话、少踩几个重复的坑。配置体系这事真没那么玄把三个文件的职责分清楚然后用起来、持续调自然就越用越顺。