Claude Code配置详解：settings、CLAUDE.md与memory协同实战

写配置教程最怕什么？最怕把几个配置文件并列一摆，读者看完还是一团浆糊：settings.json 是干嘛的、CLAUDE.md 要写多详细、memory 到底存在哪，互相之间又是什么关系。我一开始用 Claude Code 时也这样，三个文件都碰过，结果权限弹窗满天飞、项目规则记不住、跨会话经验一点没沉淀，体验远不如宣传里说的“越用越懂你”。

后来把这三个体系拆开琢磨了一遍，才明白它们其实是三个正交的维度：settings.json 管行为边界，CLAUDE.md 管项目上下文，memory 管长期记忆。这篇文章就把我踩过的坑和最终落地的一套配置方案完整写出来，给正在用 Claude Code 或者刚准备入坑的朋友一个可以直接抄的参考答案。适合想优化现有配置的人，也适合完全没摸过配置文件的新手。

1. 先把三个配置文件的关系理清楚

1.1 一句话定位各自的职责

很多教程喜欢把 settings.json、CLAUDE.md、memory 当成三个并列的“配置文件”来讲，这其实是最大的误解。它们解决的问题完全不同，就像一家公司里同时存在的三样东西：考勤制度、岗位说明书、老员工的经验。

settings.json 解决的是“Claude Code 能做什么、不能做什么”。它管的是权限边界，决定哪些终端命令可以自动执行、哪些文件编辑需要你确认、哪些操作直接禁止。这是安全层面的控制，也是你在面对一个拥有文件读写和命令执行能力的 Agent 时最重要的防线。

CLAUDE.md 解决的是“它应该知道什么”。这是给 Claude Code 看的项目说明书，里面写清楚这个项目是干什么的、目录结构、常用命令、编码规范、架构约定。每次会话启动时它会自动读取这份文档，相当于给模型加载了“项目上下文”，避免它每次都是从零开始猜。

memory 解决的是“它记住什么”。这是跨会话的长期记忆，存放于本地文件系统中。比如你告诉它“这个项目的测试命令是 pnpm test”，它在后续会话里可能还会记得；你纠正过它“不要修改 public 目录下的文件”，这个经验也会沉淀下来。简单说，memory 是让 Claude Code 越用越懂你的关键。

1.2 配置文件的加载顺序与生效范围

这三类配置文件不是孤立的，它们的加载顺序和生效范围决定了你修改一处配置时，到底影响的是全局还是单个项目。

settings.json 分为三层：用户级配置存放在~/.claude/settings.json，作用于你机器上的所有项目；项目级配置存放在项目根目录的.claude/settings.json，跟随代码仓库走，团队成员都能共享；本地级配置是.claude/settings.local.json，只作用于当前机器，适合放个人偏好，通常不会提交到 Git。三层配置的覆盖顺序是本地优先于项目，项目优先于用户，也就是说三处同时配置同一个权限项时，更具体的层级说了算。

CLAUDE.md 的加载逻辑要更细一点。项目根目录的CLAUDE.md是每次会话都会自动加载的，相当于“主说明书”；子目录里也可以放CLAUDE.md，当 Claude Code 进入对应目录工作时会追加加载；用户主目录下还能放一个~/.claude/CLAUDE.md，作为个人全局偏好，不过这个功能目前还在逐步开放中。CLAUDE.md 内部支持用@import语法引用其他 Markdown 文件，这对避免单文件过长非常重要。

memory 的存放位置比较隐蔽：它存储在~/.claude/projects/目录下，每个项目根据路径生成一个子目录，里面有一个自动维护的CLAUDE.md文件。比如你在/Users/name/work/my-project下使用 Claude Code，目录就会以路径的变形命名。这部分内容默认不跨机器同步，属于本地私有数据。

下表可以一目了然地看清楚三者的差异：

1.3 为什么三者的配合比单独配置更重要

单独配好其中一个，都不会有质的提升。settings.json 配得再细，不告诉 Claude Code 项目规则，它还是会用通用习惯写代码；CLAUDE.md 写得再详细，权限不放开，每个操作都要点确认，体验照样崩；memory 记得再多，如果和 CLAUDE.md 的规则冲突，它也可能不知所措。

我实际用下来的感受是：settings.json 决定的是“能力边界”，CLAUDE.md 决定的是“工作方式”，memory 决定的是“经验积累”。三者组合起来，才是一个完整的“AI 同事”该有的状态——知道哪些事不能碰，知道活儿该怎么干，也知道上次踩过的坑不要再踩。

所以下面三个章节，我会分别把每个体系的关键细节讲透，最后再给一套三者协同的落地流程。

2. settings.json：管住 Claude Code 的行为边界

2.1 三个层级怎么选，覆盖规则有什么坑

settings.json 用的是 JSONC 格式，也就是 JSON 的超集，允许写注释和尾逗号，这对维护来说非常友好。我建议项目根目录的.claude/settings.json里只放团队共识相关的内容，比如统一的代码检查命令、禁止的危险操作；本地级.claude/settings.local.json放单机偏好，比如你个人的模型偏好、自定义的快捷键映射。用户级配置则放所有项目通用的一套基线规则。

覆盖规则有一个容易被忽略的细节：permissions下面的allow、deny、ask这三类配置，在层级叠加时不是简单互相覆盖，而是取并集。也就是说，用户级设置了拒绝某个操作，项目级即使设置了允许，只要两者的规则没有精确到同一模式，实际上都会参与判断，最终以更严格的规则为准。这个“严格优先”的设计保证了安全底线，但也容易让人困惑——我以为项目级改了就能覆盖全局，结果用户级的deny还在生效。

另一个常见的坑是修改配置后不生效。settings.json 的多数读取是动态的，但某些字段比如model和环境变量，需要在会话启动时读取。如果你改了模型配置发现没变化，先试试退出当前会话重新进入，大部分时候就能解决。

2.2 权限配置：从弹窗地狱到无感协作

permissions是整个 settings.json 里最实用的部分，也是新手最容易忽略的部分。默认情况下，Claude Code 对文件的编辑和命令执行会采取比较保守的确认策略，如果你不主动配置，就会陷入“每走一步都要点确认”的弹窗地狱。

权限配置的核心是三个数组：allow表示直接放行，deny表示坚决拒绝，ask表示弹窗询问。每一项都可以使用通配符来匹配工具调用，比如Bash(npm run build)或者Edit(**/*.md)。语法上是“工具名(参数模式)”的形式，工具包括 Bash、Edit、Write、WebFetch、Glob、Grep 等。

我自己的配置思路是分两步走。第一步，先保持默认状态跑一个完整的开发任务，把所有弹窗内容记下来；第二步，把那些频繁出现且结果是安全的操作加入allow——比如Bash(pnpm lint)、Bash(git status)、Read(**/*.ts)，把偶尔使用但有一定风险的操作放进ask，比如涉及推送、删除、生产环境的命令。这样一来，日常高频操作全自动，高风险操作仍然保留人工确认。

一个特别值得注意的细节是defaultMode字段。把它设置为acceptEdits，可以允许 Claude Code 直接修改文件而不用逐一确认，但终端命令仍然按权限配置走。这个模式对编程效率的提升极其明显，我叫它“半放手模式”，既保证了文件编辑顺畅，又守住了命令执行的安全线。

2.3 model、env 与 hooks：可编程的自动化钩子

除权限外，settings.json 里还有三个值得花时间折腾的模块。

第一个是模型配置。你可以通过model字段指定会话默认模型，也可以设置smallModel给某些轻量任务使用。实际使用中，我更倾向于通过环境变量来控制，比如在.claude/settings.local.json里通过env字段注入自定义变量。如果你有通过兼容网关接入第三方模型的需求，通常也是改这里的ANTHROPIC_BASE_URL和ANTHROPIC_MODEL，社区里那个叫 cc switch 的工具，本质就是在不同 API 端点之间快速切换配置。

第二个是env。它允许你在 Claude Code 启动时注入环境变量，比如 API Key、各类服务的 Token。有一个使用技巧是把不同项目的密钥配置放在各自的.claude/settings.local.json里，这样就不会把所有密钥塞进同一个全局文件，方便管理和隔离。

第三个是hooks，这是最强大也最容易被忽略的能力。hooks 可以在工具调用前、后以及停止、通知等时机触发外部脚本。比如我配了一个PreToolUse钩子，在 Claude Code 执行编辑操作前自动运行代码格式化脚本；还配了一个PostToolUse钩子，在运行完测试后自动把测试结果追加到日志文件。hooks 的配置项包含matcher（匹配哪些工具调用）、hooks（要执行的命令数组）以及timeout（超时时间）。注意脚本执行是可能卡死的，必须设置合理的超时。

2.4 一份适合日常开发的 settings.json 示例

这是我当前在多个项目里都在用的一套基础配置（不含密钥等敏感信息），你可以直接复制后根据项目调整：

{ "permissions": { "defaultMode": "acceptEdits", "allow": [ "Bash(git status)", "Bash(git diff)", "Bash(git log*)", "Bash(pnpm lint)", "Bash(pnpm typecheck)", "Bash(pnpm test -- --run)", "Read(**/*)", "Glob(**/*)" ], "ask": [ "Bash(git push*)", "Bash(pnpm deploy*)", "Bash(rm -rf *)", "Bash(curl *)", "WebFetch(*)", "Write(/etc/**)" ], "deny": [ "Bash(shutdown*)", "Bash(reboot*)", "Bash(sudo rm -rf *)" ] }, "model": "sonnet", "hooks": { "PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\"", "timeout": 30 } ] } ] } }

配置里的model字段我写了sonnet，你可以根据自己的订阅或 API 对应关系替换。permissions.ask里我特意把curl和WebFetch都留为询问状态，因为我发现 AI 在网络请求上偶尔会做出出乎意料的动作，尤其是涉及外部 URL 时。

3. CLAUDE.md：给 Claude Code 写“项目说明书”

3.1 文件位置与自动加载机制

CLAUDE.md 的官方定位是“Claude Code 的指南文件”，它存放在项目根目录时，每次会话启动都会自动加载。这意味着你写在里面的内容，会占用模型输入的上下文窗口，所以“写什么”和“写多少”都需要克制。

子目录的 CLAUDE.md 是另一个层级。当 Claude Code 涉及某个子目录时，会读取那个子目录的 CLAUDE.md，然后与根目录的内容进行合并。这种层级结构很适合大型仓库：根目录写全局约定，各业务模块单独写自己的规范。

除了项目文件，你还可以在~/.claude/CLAUDE.md里写跨项目的个人偏好，比如“总是使用 pnpm 而不是 npm”“默认不生成 JSDoc 注释”这类通用习惯。项目级 CLAUDE.md 和用户级 CLAUDE.md 会同时生效，当两者冲突时，项目级的优先级更高。

还有一个省事的技巧是@import引用。你可以在 CLAUDE.md 里写一行@import ../../docs/commands.md，把详细内容拆分到其他文档里。这能有效控制主文件的长度，同时让上下文按需加载。我通常把“常用命令”“架构说明”“编码规范”拆成三个独立文件，主 CLAUDE.md 只保留一句话的概述和三个@import。

3.2 该写什么，不该写什么

CLAUDE.md 的核心目标是“让 Claude Code 在最短时间内理解项目怎么做”，所以内容必须高度结构化、命令必须可执行、规则必须无歧义。我的推荐结构包含四个部分：项目概述、常用命令、架构约束、编码约定。

项目概述两到三句话即可，说明这个项目做什么、用了什么技术栈、入口在哪。不用长篇大论，那是给人类看的设计文档，不是给模型看的操作手册。常用命令必须写成可以直接执行的形式，比如：

## 常用命令 - 启动开发服务：`pnpm dev` - 运行测试：`pnpm test -- --run` - 类型检查：`pnpm typecheck` - 构建产物：`pnpm build` - 提交前检查：`pnpm lint && pnpm typecheck`

不要写“运行测试”这种没头没尾的话，模型会困惑到底用什么工具、怎么跑。命令写清楚，它能直接执行，省掉一轮又一轮的猜测。

架构约束是项目的核心规则，比如“后端 API 代码在src/server目录”“所有数据库访问必须经过src/db模块”“不要在public目录下放动态生成的文件”。这些内容越具体越好，因为 Claude Code 对项目的了解完全依赖于你喂给它的信息。

编码约定要写“硬规则”，不写“软建议”。比如“组件命名使用 PascalCase”“每个函数都必须有返回值类型声明”“禁止在组件内直接使用window对象”。当然，它遵循这些规则的前提是规则清晰且可判断，如果你的约定本身含糊，那就别指望它能稳定执行。

常见的反面教材是两种。一种是把它写成项目百科，动不动几千字，结果所有会话的上下文都被占满，模型反而抓不住重点。另一种是写完之后再也不更新，项目目录变了、命令改了，CLAUDE.md 还停留在三个月前，这比不写还糟糕。

3.3 一份可以抄的 CLAUDE.md 模板

下面是我现在新建项目时默认用的模板，你可以直接套用：

# 项目名称与简介 这是一个 xxx 项目，技术栈为 React + TypeScript + Vite，后端使用 pnpm workspace 管理。 ## 常用命令 - 启动开发服务：`pnpm dev` - 测试：`pnpm test -- --run` - 类型检查：`pnpm typecheck` - 检查与修复：`pnpm lint --fix` ## 项目结构 - `src/`：前端源码，入口为 `src/main.tsx` - `src/components/`：通用组件，按功能分子目录 - `src/services/`：接口请求封装，禁止在组件内直接调用 fetch - `server/`：后端服务，入口为 `server/index.ts` - `config/`：配置文件目录 ## 编码约束 - 使用函数组件 + Hooks，禁止使用 Class 组件 - 所有业务错误必须通过 `src/utils/error.ts` 统一处理 - 修改接口类型时，必须同步更新 `openapi.ts` - 不要直接操作 `public/` 目录下的文件，静态资源统一放 `src/assets/` ## 常用工作流 - 新增页面：在 `src/pages` 下建目录，同时在 `router.tsx` 注册路由 - 新增接口：先在 `server/routes` 定义，再在 `src/services` 封装调用

模板和最终形态会有差异，但骨架就是这个。注意每一条都尽量用“必须”“禁止”这类明确词汇，而不是“尽量”“建议”，因为模型对模糊指令的处理方差很大。

4. memory 体系：让 Claude Code 记住跨会话的经验

4.1 三种记忆形态，分别放在哪

memory 在 Claude Code 里是个容易被误解的词。它不是一个独立的配置文件，而是一套分布在文件系统里的记忆机制。我把它理解为三种形态。

第一种是项目记忆，存储在~/.claude/projects/<项目路径 slug>/CLAUDE.md。这个文件是 Claude Code 自动维护的，Memory Tool 写入的内容都往这里沉淀。项目路径 slug 是原始路径经过格式化处理后的结果，比如/Users/name/work/my-app可能变成--Users-name-work-my-app这样的目录名，实际以你机器上的目录为准。

第二种是用户记忆，也就是上一章提到的~/.claude/CLAUDE.md，存放跨项目的个人偏好。这里写的东西对所有项目生效，比如“默认用 pnpm”“代码注释使用中文”这类个人习惯。

第三种是会话内记忆，存在于当前对话的上下文里，会话结束就不复存在。它虽然不落盘，但也很重要，因为很多记忆的沉淀路径是“会话内形成的共识”最终通过 Memory Tool 变成“跨会话记忆”。

4.2 Memory Tool 什么时候会自动写入

很多人以为 memory 是全自动的，用了一段时间后发现它啥也没记住，就很困惑。实际上 Memory Tool 的触发是有条件的，它主要在这三种场景下自动落盘：

你明确要求它记住某些信息，比如“记住这个项目的测试必须用 vitest”；你纠正了它的行为并且它识别出这是长期偏好，比如“以后不要用any类型”；它在处理任务过程中发现了项目里值得固化的约定，比如“项目中所有 mock 数据统一放在src/mocks目录”。

但这不是百分之百会发生的。如果它在任务中没有把某个信息判定为“值得长期记忆”，就不会写入。如果你希望某个经验一定被记住，最可靠的方式是直接对它说“记住这个：xxx”。这句话是触发 Memory Tool 最有效的指令，比你说“你应该记住这一点”要稳定得多。

还有一个手动管理的方法：直接编辑~/.claude/projects/<项目路径 slug>/CLAUDE.md。这个文件是纯文本，你可以自己添加、修改、删除记录。我通常每两周检查一次，把已经过时的记忆清掉，把仍然有效的经验做一次整理和合并。

4.3 值得记与不值得记

记忆空间看着很大，实际不是无限的。项目记忆会随每次会话加载进上下文，记忆越多，占用越重、噪声越大。所以我在实际使用中总结了一套“记忆筛选标准”。

值得记的包括：项目约定的命令与工作流，用户明确的偏好，调试了很久才解决的 bug 及原因，项目的敏感目录或不可触碰的区域，某些第三方接口的返回格式等。这些信息的共同点是“会重复用到”且“无法轻易从代码里推断出来”。

不值得记的包括：一次性的临时任务，大量代码片段，与项目无关的闲聊，已经写在 CLAUDE.md 里的内容，敏感凭据如密码和 API Key。最后一条要格外强调，memory 是纯文本文件，里面的所有内容在会话中被加载给模型看，把密钥写进去等于明文泄露。

安全上还有一个容易被忽视的点：既然记忆文件是纯文本，那么任何能写入文件的内容都可能污染它。业界已经出现过针对 LLM 记忆与知识库的投毒攻击研究，也就是往记忆或知识库里注入恶意内容，让 Agent 在后续任务中被带偏。虽然这种攻击在实际使用中还没有成为普遍威胁，但你至少应该养成定期查看记忆文件的习惯，发现异常内容及时清理。

4.4 如何有意识地塑造记忆

memory 的妙处在于它是可以被“训练”的。每次会话结束时，我会花十几秒做一次简单的回顾：这次任务里有没有以后会重复用到的信息？如果有，就直接命令它“记住这个”。这比让 AI 自己判断要靠谱得多。

举个例子，有一次我让 Claude Code 调试一个奇怪的 CSS 兼容问题，花了很长事件才定位到是某个浏览器版本的 bug。解决后我立刻对它说“记住这个浏览器版本在 flex 布局下会 overflow，解决方案是添加min-width: 0”。这个经验在后续若干个前端项目里都派上了用场，因为它属于“跨项目可用”的一般性经验。

这种有意识地塑造记忆，才是让 Claude Code 从“每会话失忆”变成“越来越懂你”的关键。你不用把所有东西都喂给它，只需要把值得沉淀的判断交给自己。

5. 三者协同：一份完整的配置落地流程

5.1 一个项目从零到顺畅的七个步骤

讲完三大体系各自的细节，落到实处时最常被问到的问题是：拿到一个新项目，到底应该按什么顺序配置？我下面给出一套我在实际工作中反复使用过的流程，七个步骤，每一步都有明确的产出。

第一步，观察。先不急着写任何配置，直接以默认状态在项目里跑一个真实任务，全程留意弹窗内容和 Claude 的表现。这个阶段的目标是收集信息：哪些操作它频繁询问、哪些地方它明显不知道、哪些行为让你觉得需要约束。

第二步，搭 settings.json 的权限框架。根据观察结果，把高频安全操作加入allow，把危险操作明确deny，其余保持ask。同时设置defaultMode: acceptEdits让文件编辑流程顺畅起来。

第三步，写 CLAUDE.md 初版。不要追求一步到位，先写项目概述、常用命令、项目结构和核心编码约束。写完之后跑一个任务，看看它是否遵循了 CLAUDE.md 里的规则，如果有偏差，多半是写得不够明确，继续迭代。

第四步，跑一个完整的日常任务。用真实工作流验证配置，比如让它在现有代码库上完成一个新功能。这一步你会发现权限配置还有哪些遗漏，CLAUDE.md 里哪些规则它没有理解到位。

第五步，收敛权限。把第四步里频繁出现且安全的允许操作持续加入allow，把依然有风险的操作留在ask。这个过程会持续几天，直到弹窗频率降到可接受范围。

第六步，主动沉淀记忆。在每次任务结束前，主动对它说“记住这个：xxx”。把那些跨会话需要保留的经验固化到 memory 里，而不是指望它自动领悟。

第七步，定期维护。我按周和按月两个周期维护：每周检查一次 memory 文件，清理过期内容；每月审视一次 CLAUDE.md，确保它和项目的实际状态同步。

这套流程最大的价值是把三个体系串成了闭环：settings 让你能无感协作，CLAUDE.md 让它上手项目，memory 让它越用越熟。三者一起迭代，而不是今天改改权限、明天补补文档、后天拍拍脑袋加记忆。

5.2 优先级冲突时怎么处理

三个体系之间偶尔会出现规则冲突，这时候需要一套明确的裁决逻辑。我的经验是按照“安全 > 明确 > 习惯”的优先级来执行。

安全优先级最高。无论 CLAUDE.md 里写了什么，只要 settings.json 的deny里明确列出的操作，一律禁止执行。比如你在 CLAUDE.md 里写了“发布命令是 pnpm publish”，但 settings.json 里deny了Bash(pnpm publish)，那这个命令就不会被执行。这是设计底线，不应该试图绕过。

明确优先级次之。CLAUDE.md 里的规则比 memory 沉淀的经验更有权威性，因为前者是项目主动定义的契约，后者是模型被动记录的经验。如果 memory 里记录的内容与 CLAUDE.md 冲突，以 CLAUDE.md 为准。

习惯优先级最低。用户级偏好如~/.claude/CLAUDE.md里写的个人习惯，在遇到项目级规则时让路。一个人可以习惯于用 yarn，但如果项目 CLAUDE.md 明确写了命令统一是 pnpm，那就按项目规则来。

这套裁决逻辑我在团队协作时也会跟成员同步，避免大家各自理解各自的优先级，最后产生莫名其妙的冲突。

5.3 团队协作时哪些配置入库、哪些不入库

多人协作时，配置文件的共享边界一定要提前划分清楚，否则很容易出现“我这边配置的好好的，换台机器全变了”的问题。

随仓库共享的包括：.claude/settings.json项目级配置、项目根目录的CLAUDE.md、子目录的CLAUDE.md、以及用@import引用的文档。这些内容定义了团队统一的规则和上下文，是所有成员协作的基础。

不随仓库共享的包括：.claude/settings.local.json、~/.claude/settings.json用户级配置、~/.claude/projects/下的 memory 目录、~/.claude/CLAUDE.md个人偏好。这些都是本地私有数据，如果强制入仓库反而会污染团队配置。

团队协作还有一个加分项：维护一份 CLAUDE.md 模板库。我在团队内部建了一个claude-config-templates仓库，里面按项目类型放了几套 CLAUDE.md 模板，比如前端项目、Node 服务、Python 工具库。新项目直接复制模板再改几行就能用，新成员拉代码后也能立刻获得一致的配置体验。

6. 常见问题与排查实战录

6.1 权限配置不生效，还是不停弹确认

这大概是遇到最多的问题。改了 settings.json 加了allow，结果弹窗还是一个接一个。排查顺序建议如下。

先确认文件格式是否正确，settings.json 虽然是 JSONC，但语法错误会导致整份配置无法解析，可以用 VS Code 打开看有没有红色波浪线。然后确认你改的是不是正在生效的层级，如果你当前在项目 A 里运行，但改的是全局配置且项目配置里对该操作设置了ask，那项目级会覆盖全局的allow，弹窗依旧。最后别忘了有些字段需要新会话才会重新读取，改完配置重启一次会话再试。

还有一种隐蔽的情况：权限匹配是模式匹配，不是简单的命令前缀匹配。比如你写了Bash(pnpm lint)，但如果 Claude 实际执行的命令是pnpm lint --fix，这个模式可能就匹配不上，需要写Bash(pnpm lint*)这类带通配符的形式。

6.2 CLAUDE.md 太长，上下文被严重占用

上下文窗口是有限的，CLAUDE.md 写得越长，留给实际任务的令牌就越少。我见过把整个项目文档都搬进 CLAUDE.md 的，结果模型每一轮响应都变得拖沓，偶尔还会出现上下文截断。

解决办法首先是精简主文件，只保留核心规则和命令，详细内容全部用@import拆到单独文档。其次是按需加载，利用子目录 CLAUDE.md 的机制，把特定模块的规则放在对应目录里，而不是全部堆在根目录。最后要克制“面面俱到”的冲动，CLAUDE.md 的使命是提供关键上下文，不是完整存档。

6.3 Memory Tool 没有自动写入，跨会话什么都记不住

这个问题的根源通常不是配置，而是触发时机。Memory Tool 不是无条件的自动写入，如果你从来没有明确要求它记住任何东西，它自然也不会主动记录。

我的解决方案是建立“记忆习惯”：在每个任务收尾时，主动说一句类似“记住这个：这个项目的部署脚本是pnpm deploy”。只要你用“记住”这个指令，它大概率会触发 Memory Tool 写入。如果还是没有写入，直接手动编辑~/.claude/projects/<路径>/CLAUDE.md，把这个经验补进去。文件是纯文本，手动维护完全可行。

6.4 接入第三方模型时的配置要点

如果你想把 Claude Code 接到第三方模型上，社区里常见的做法是通过 cc switch 这类工具切换 API 端点，或者直接在配置与系统环境变量里设置ANTHROPIC_BASE_URL和ANTHROPIC_MODEL。这里的本质是让 Claude Code 把 API 请求发往兼容端点，而不是官方默认端点。

这个方案的适用性取决于第三方服务是否提供 Claude 兼容的 API 格式。DeepSeek、Qwen、GLM 等模型都有各自的接口服务，是否能够无缝接入需要看服务商的兼容支持情况。配置时我建议用.claude/settings.local.json来保存这类端点配置，不要在项目级文件里写死，因为不同成员可能使用不同的接入方案。

6.5 hooks 脚本报错或卡住任务

hooks 虽然强大，但也可能成为任务卡住的源头。最常见的问题是脚本执行时间过长，导致工具调用迟迟没有结果。我一般会在每个 hooks 命令上设置合理的timeout，比如编辑后格式化脚本给 30 秒，再长的操作单独处理。

另一个建议是在 hooks 脚本里加上日志输出，比如将脚本的标准输出写入/tmp/claude-hooks.log。这样一旦出问题，你可以直接查看日志定位脚本本身是不是有 bug，而不是对着 Claude Code 的黑盒行为干瞪眼。

6.6 安装与登录阶段的一些通用提醒

如果你在安装或登录阶段遇到“不可用”之类的提示，先别急着怀疑配置。Claude Code 对运行环境和账号来源有官方要求，请确认你使用的网络和账号在官方支持范围内。安装前也确认 Node.js 版本满足要求，常见的安装方式是使用 npm 全局安装或官方提供的安装脚本，装完以后在终端里输入claude验证版本号。这类基础问题排查清楚，后面配置的时候才能少踩坑。

最后，几个我自己的配置习惯

写到这里，三大体系的原理和实操讲得差不多了。最后分享三个我坚持了很长时间的个人习惯，虽然不在任何官方文档里，但对实际体验的提升非常明显。

第一个习惯是给 CLAUDE.md 做“瘦身运动”。每次新项目，我先写完完整版，再用@import把详细内容拆走，主文件永远控制在一屏能看完的长度。这样模型能快速抓住重点，详细规则按需加载，上下文占用也控制得住。

第二个习惯是每周花十分钟“清理记忆”。直接打开~/.claude/projects/下对应项目的 CLAUDE.md，把已经失效的记录删掉，把重复的内容合并，把仍然生效的经验重新措辞一遍。定期整理的记忆文件，才是真正高质量的记忆文件。

第三个习惯是永远不让敏感信息进入配置。无论 CLAUDE.md、settings.json 还是 memory，都不应该出现实际密码、Token 或密钥。配置和记忆文件随时可能被分享或迁移，一旦敏感信息混进去，就意味着凭据泄露。我会用环境变量注入的方式来处理所有秘密，配置文件里只保留占位符。

把这三个习惯坚持下去，Claude Code 的使用体验会越来越顺，它不是“越用越懂你”的魔法，而是你主动塑造出来的工作伙伴。希望这篇配置详解能帮你少走一些我走过的弯路。