刚上手 Claude Code 的时候我一度以为它就是个带终端的聊天框每次开新会话都得把项目背景、技术栈、命令习惯重新讲一遍讲完撑不了几十轮又开始忘。后来认认真真把 settings.json、CLAUDE.md、memory 这三套配置吃透了才发现之前完全用错了方向。这篇文章不聊安装、不贴官方文档链接直接讲三套配置各自负责什么、关键参数怎么填、三者怎么配合以及我在真实项目里踩过的一系列坑。如果你已经装好了 Claude Code 但觉得它记性差不听话这篇应该能帮你省下大量重复解释的时间。1. 为什么你总觉得 Claude Code 记不住事情三套配置的分工逻辑1.1 一个典型场景会话失忆与重复解释我第一次用 Claude Code 是在一个前后端一体的项目上头两天体验很糟糕。每次启动新会话它都要问我一遍这个项目的技术栈是什么测试命令是 npm test 还是 vitestsrc/core 这个目录是干什么的。问完我也不得不答答完几十轮之后它照样忘。最夸张的一回我让它去改一个服务接口它把 controller 和 route 的位置彻底搞混绕了大半天才回到正题。当时我以为是上下文窗口不够用后来才反应过来问题根本不是窗口长度而是我什么都没配。Claude Code 每次启动时真正会主动加载的信息只有三块settings.json 里的运行参数和权限设置CLAUDE.md 里的项目约定和背景知识历史会话沉淀下来的 memory这三块配置是它认识你项目仅有的入口。你如果不提供它就只能在对话里现场问、现场猜表现自然像一个每次都要重新入职的临时工。1.2 三套配置的职责边界用大白话讲这三套配置回答的是完全不同的问题配置回答的问题类比settings.json它能做什么、不能做什么、跑在什么模型上公司规章制度CLAUDE.md这个项目的背景、目录结构、命令约定是什么岗位交接文档memory上次聊到哪、有哪些长期偏好和临时状态个人工作笔记settings.json 管的是刚性动作权限、模型、环境变量、钩子脚本。它决定 Claude 能不能跑命令、能不能改文件、会不会在 git 提交里署名。CLAUDE.md 管的是软性知识你得告诉它项目用什么技术栈、目录怎么组织、命令前缀是 pnpm 还是 yarn、有哪些改动是禁区。这部分不写清楚它就只能靠猜。memory 则是会话之间的粘合剂。它负责把散落在历史对话里的关键状态延续下来避免你每次开新会话都要从头交代进度。很多教程只讲 CLAUDE.md 这一块这是最大的误解。实际用下来三者的关系更像是settings.json 定边界CLAUDE.md 给知识memory 续状态。缺了任何一块体验都会大打折扣。2. settings.json控制 Claude Code 的行为开关2.1 配置文件在哪谁的优先级更高先说路径。settings.json 有两个常见位置用户级~/.claude/settings.json作用于你机器上的所有项目项目级项目根目录下的.claude/settings.json只作用于当前项目只要项目级配置里出现同名配置项它就会覆盖用户级设置。比如你在用户级把 Bash 权限设为 allow但某个项目里改成了 ask那这个项目里执行命令时依然会先询问。除了这两个还有一个容易被忽略的.claude/settings.local.json。我习惯把它当作个人本地覆盖文件团队共享的配置写进.claude/settings.json自己机器上的私有调整放 settings.local.json再通过 .gitignore 排除掉避免把个人环境变量或密钥带进代码库。命令行的-c参数和环境变量的优先级最高会临时覆盖文件里的配置。想快速验证某个模型或某项权限时用命令行临时开关比改文件再改回来省事得多。2.2 最值得关注的配置项permissions 是最容易埋雷也最应该先看的一块。它支持三种形态白名单 allow、黑名单 deny、以及每次询问 ask。只读操作比如 Read、Grep、Glob 放 allow 没有问题但 Bash 和 Edit 这类有副作用的动作我建议至少先 ask跑几天确认它的操作习惯之后再逐步放开不要一上来就全套 allow。model 字段决定默认模型。除了在 settings.json 里指定更常用的是通过环境变量ANTHROPIC_MODEL来设置。如果你用的是本地模型比如通过 LM Studio 起一个兼容服务或第三方 API一般还要同时设置ANTHROPIC_BASE_URL让请求发到对应地址而不是官方默认入口。我试过在切换服务商之后忘了改 base_url结果模型没变、请求全打到了默认端点排查了半天才意识到是环境变量残留。env 字段可以注入自定义环境变量。我常用它来区分运行环境比如告诉 Claude 当前是 staging 环境避免它把测试库当成线上库来改。这一点在多人项目里特别重要。hooks 是我对 Claude Code 最满意的一项能力。它可以在工具调用前后触发脚本典型用法是在 PreToolUse 阶段拦截 Bash 命令检测到rm -rf或git push --force这类危险操作时直接中止。写过几个拦截脚本之后我总算敢把 Edit 权限从 ask 改成 allow 了。另外还有两个小配置也值得知道includeCoAuthoredBy决定 git 提交时是否自动附上 Claude 的 co-author 署名cleanupPeriodDays控制历史会话的清理周期。两个都对日常体验有直接影响但很容易被教程忽略。2.3 一份可直接套用的基础配置模板下面是我现在新项目起步时用的模板权限部分刻意保守{ permissions: { allow: [Read, Grep, Glob], ask: [Edit, Bash], deny: [WebFetch] }, includeCoAuthoredBy: false, cleanupPeriodDays: 30, env: { APP_ENV: staging }, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node .claude/hooks/guard-dangerous-commands.js } ] } ] } }这里我把 Edit 和 Bash 都放在 ask 状态deny 了 WebFetch因为当前项目根本不需要它抓网页。hook 脚本会拦截 Bash 命令匹配到危险模式就返回非零退出码让工具调用被中止。脚本本身不复杂核心逻辑就是从 stdin 读入命令内容做正则匹配命中就告警并退出。重点是 matcher 字段的写法在不同的版本里可能有差异我第一次升版本之后就因为这个字段失效吃过亏后面专门讲。3. CLAUDE.md不是说明书而是给模型看的项目交接文档3.1 CLAUDE.md 长什么样CLAUDE.md 在最简单的情况下就是项目根目录下的一个 Markdown 文件Claude Code 每次在这个目录启动会话时都会加载它把它当作项目的工作手册。但它不是给人看的说明书而是给模型看的交接文档所以写法非常关键。我随便拿一个书店后端项目举例# bookstore-api 这是 Node.js 20 Express Prisma PostgreSQL 的 REST API 项目。 ## 常用命令 - pnpm dev本地开发 - pnpm test运行 vitest - pnpm linteslint 检查 - pnpm db:migrate执行数据库迁移 ## 目录结构 - src/modules按业务模块划分每个模块含 controller/service/repo - prisma/schema.prisma数据库 schema修改后必须生成 migration ## 约定 - API 返回格式统一为 { data, meta } - 错误码使用 HTTP 状态码 业务码字段 bizCode - git 提交信息使用 conventional commits - 只需要改后端时不要动前端目录 src/web这份文档的核心不是信息量大而是能直接被模型执行。它没有大段的背景铺陈全是可操作、可检查的条目。3.2 怎么写才能让模型真的听话我试下来最有效的几条规则第一用祈使句不用描述句。你可以运行 pnpm test和发布前必须运行 pnpm test模型对后者的执行率明显更高。规则文件里不要留商量余地能用必须禁止就不用可以建议。第二命令给到能直接粘贴的程度。别只写跑测试要写pnpm test如果测试需要串行执行就直接写pnpm test -- --runInBand。少让模型做一步推断它就少一次出错机会。第三控制总行数。CLAUDE.md 不是文档仓库超过 100 行之后模型对每一条规则的记忆密度会明显下降。长文档应该拆成细分的文件然后在 CLAUDE.md 里通过相对路径或 语法引用让模型按需读取而不是一股脑全部塞进上下文。第四写清不要做什么。比如不要修改 src/web 下的文件不要在没有 migration 的情况下改 schema。这类负向约束往往比正向约束更有效因为模型的默认行为是尽量满足你的请求你越早亮明禁区它越少自作主张。3.3 全局 CLAUDE.md 与项目级 CLAUDE.md 的配合项目级的 CLAUDE.md 只对当前项目生效。如果你的工作习惯本身很稳定——比如你统一用 pnpm 而不是 npm、commit 信息偏好写中文还是英文、默认希望 Claude 回复简洁一些——这些应该放到~/.claude/CLAUDE.md作为全局偏好。运行时两边的 CLAUDE.md 都会被加载全局的提供个人习惯项目的提供项目事实。这样换到一个新项目时你不需要重新教它别啰嗦只需要写项目特有的上下文就行。这里有一个需要留意的边界全局文件里不要写和某个项目强绑定的信息否则换项目时会串味。比如在 bookstore 项目里数据库统一用 PostgreSQL这种句子出现在全局文件里就会污染所有项目的认知。全局文件只保留与项目无关的个人偏好项目相关的事实一律丢进项目级文件。4. memory跨会话记忆的正确打开方式4.1 Claude Code 里的记忆到底存在哪很多人以为 memory 是像人脑一样自动记住所有对话实际不是。Claude Code 的记忆大概分三层会话内滚动上下文当前对话窗口满了之后早期内容会被截断或压缩这是正常现象会话间持久记忆工具在后台维护的历史状态不同版本实现不同通常提供 /memory 之类的命令来查看和编辑CLAUDE.md 这类显式加载的规则文件其实是最强的一种记忆因为它每次会话都会被完整读入我这样理解memory 是工具提供的草稿笔记它会自动记录一些它认为重要的信息比如你让它记住的偏好、上次任务做到一半的状态。但它的记忆不保证准确也不保证面面俱到它只是尽量维持连续性。正因为它不可靠才需要 CLAUDE.md 来兜底。你把永久为真的信息写进规则文件就是在给自动记忆做备份和对齐。4.2 如何利用记忆减少重复劳动在实践里我建议按这个优先级来管理记忆凡是永久为真的信息写进 CLAUDE.md不要依赖自动记忆。比如技术栈、常用命令、目录约定这些每次会话都要用靠自动记忆既慢又容易丢。中期状态比如正在重构 auth 模块还剩 controller 没改可以显式让模型记住或者用一个 PROGRESS 文件记录然后在对话里 引用它。临时细节比如某个报错信息、某段临时调试代码不需要刻意记住。用完即忘反而更干净省下的记忆资源会留给真正重要的状态。另外如果你发现某个信息在多个会话里被反复强调这就是一个明确信号该把它写进 CLAUDE.md 了。这其实就是记忆从草稿层升级到规则层的过程。4.3 记忆卫生别让过时信息毒害后续会话聊到 memory 我必须提一个词记忆卫生。学术界早就演示过 agent poisoning 的概念——通过往 Agent 的记忆或知识库里投毒让它在后续任务里持续做出错误判断。日常使用中我们也会遇到类似问题只是通常不是恶意攻击而是过时信息残留。举个我亲身踩过的例子有一次我告诉 Claude 后端接口地址是某个内网 IP后来服务换了域名。这条信息留在持久记忆里没有被清理之后每次会话它都会去连那个已经不存在的地址。更麻烦的是因为它记得这个地址它不会主动去求证每次都在同一个坑里打转。我一开始以为是模型能力退化后来才意识到是被旧记忆牵着走了。所以我现在有两个习惯每隔一段时间主动检查一次记忆删除过期条目在 CLAUDE.md 里写明如果记忆和历史记录与本文冲突以本文为准这样即使自动记忆出了问题模型也会回到规则层重新对齐不会被一条过时信息带偏。5. 三套配置协作实战从零搭一套项目配置5.1 新建项目的配置顺序具体操作我一般按这个顺序走创建项目目录并 git init。先写一个 20 行以内的 CLAUDE.md 骨架一句话项目简介、技术栈、常用命令、关键目录。不用追求完整先让模型有个底。在 .claude/settings.json 里做权限最小化配置allow 只给只读操作Edit 和 Bash 先 ask。跑第一轮对话验证问它根据 CLAUDE.md这个项目怎么启动看它能不能准确回答出 pnpm dev 而不是 npm start。用上一两天之后把对话里反复出现的项目知识回填到 CLAUDE.md。检查自动记忆里有没有错误信息有就清理避免它和 CLAUDE.md 打架。我特别想强调第 5 步。很多人配置 CLAUDE.md 是项目一开始一口气写完然后就不管了。其实最有效的时机是使用过程中发现它反复问同一个问题的时候——那个瞬间就是你该把这条信息写进规则文件的时刻。这种做法比一开始憋大文档高效得多也更贴近项目的真实需要。5.2 团队共享与个人私货的目录设计如果是团队协作我建议把目录划分成下面这样project/ ├── CLAUDE.md # 团队共享项目规则入库 ├── .claude/ │ ├── settings.json # 团队共享运行配置入库 │ ├── settings.local.json # 个人本地覆盖gitignore │ ├── hooks/ # hook 脚本入库 │ └── memory/ # 运行生成的记忆/会话存档gitignore └── docs/ ├── architecture.md # 被 CLAUDE.md 引用 └── api.mdsettings.local.json 我基本会 gitignore因为它往往包含个人 API Key、本地路径、个人模型偏好这些进了代码库迟早出事。而 CLAUDE.md 完全可以放心入库并且应该在 code review 里像代码一样被评审。它是团队知识的沉淀不是某个人电脑上的私货。我见过一些团队新成员进来之后靠 CLAUDE.md 就能快速了解项目约定而不是翻半天群聊记录问东问西这个收益是长期且稳定的。6. 我踩过的坑与修复经验6.1 CLAUDE.md 越长模型越笨我第一个项目的 CLAUDE.md 写到将近 300 行把 API 文档、数据库表结构、部署步骤全部塞了进去。结果模型反而开始频繁忽略关键命令而且每次请求的 token 消耗明显上涨。根因很简单模型每次启动都要把整个文件读进上下文内容越长有效注意力越分散。它记得住那些大段架构描述反倒把发布前必须跑 pnpm test这种关键指令给淹没了。修复方式是把 CLAUDE.md 砍到 30-50 行只留高频信息架构细节拆到 docs/architecture.md 并在 CLAUDE.md 里用相对路径引用。实测效果立竿见影响应速度变快命令执行准确率也回来了。6.2 permissions 过松差点把构建目录删了有一次我给 Bash 开了 allow想让 Claude 自由跑构建命令。结果它在改配置时执行了一个清理脚本把构建产物目录整个删了而脚本里写的是rm -rf dist。重构建倒是小事但那次之后我认真想了想如果那天它跑的是带 force 的 git push后果就不是重新构建能解决的了。修复方案有两层。第一层是把 Bash 改回 ask只对高频命令用白名单方式逐步放行。第二层是写 hooks 拦截危险命令宁可误伤也不想漏网。经过这一次我确认了一件事权限配置的成本很低但被人为失误或模型误判搞一次的成本很高。永远不要为了省几次确认点击而把权限全部放开。6.3 切换第三方模型后配置部分失效后来我试过用 cc switch 之类的工具切到第三方模型比如 DeepSeek、Qwen、GLM想在一些简单任务上省点成本。实测下来CLAUDE.md 和 permissions 都还能生效但 hooks 的某些事件触发出现了不一致少数工具调用格式也有差异。这不是配置写错了而是不同模型对工具调用的遵循度不一样。有的模型对必须返回特定 JSON 格式这件事执行得不够严格hook 脚本拿到的输入就会变化。我的建议是核心开发任务用默认模型或能力匹配的模型跑批量、简单的任务可以切轻量模型。但在切换之后一定要跑一轮冒烟测试确认 Bash、Edit、hooks 都正常工作再放心让它干活。6.4 升级带来的配置字段变化Claude Code 版本迭代很快配置字段不是一直稳定的。我经历过 settings.json 里 permissions 的写法从简单字符串数组变成带结构化对象的格式旧配置直接不识别还遇到过 hooks 里的 matcher 字段规则收紧升级后拦截脚本全部失效。最麻烦的是工具不会主动告诉你配置失效——它只会安静地忽略或报错然后你会在某次危险操作后才反应过来。应对办法很简单升级后第一时间看一眼更新日志或者直接跑一遍状态类命令确认配置被正确加载。我吃过一次亏之后现在每次升级完都会先让它执行一次实际动作比如pnpm lint用真实行为验证工具链是否完好而不是只在配置文件里看两眼。新项目的习惯我一直没变先写一个最简 CLAUDE.md哪怕只有十行。因为等你在混乱的会话里想补的时候往往已经回不去那个一开始就把上下文交代清楚的时机了。配置这件事没有一次性做完过它是跟着项目一起迭代的——文档该拆就拆权限该收就收记忆该清就清。你把这三套配置当成一个持续磨合的过程Claude Code 才会真正从每次失忆的临时工变成不用你反复交代的老同事。