1. 配置体系整体设计先搞懂谁在管什么接触 Claude Code 一段时间后你会发现它的配置逻辑其实非常清晰就三条线settings.json管“怎么跑”CLAUDE.md管“怎么想”memory管“怎么记住”。这三者各司其职但很多人第一次上手就栽在混用上——把本该写进CLAUDE.md的项目说明塞进了settings.json或者在 memory 里堆了一堆每个会话都能从代码里直接看到的东西结果配置越写越长AI 的行为却越来越飘。我最初也走过这个弯路。当时为了约束输出格式我在CLAUDE.md里写了一大段“请始终使用 TypeScript 严格模式”又在 settings 里开了几个相关开关结果发现它在不同目录下表现不一致排查半天才发现是项目级与全局的CLAUDE.md叠加后规则被重复和矛盾的信息冲淡了。从那以后我把这三者的定位彻底分开行为才稳定下来。简单说settings.json是运行参数类似你的开发环境配置——它决定终端行为、权限边界、默认模型、钩子脚本是“引擎参数”。CLAUDE.md是工作记忆的启动盘类似团队的 onboarding 文档——它告诉 Claude 当前代码库的背景、命令、约束、架构是“任务上下文”。memory是长期经历沉淀类似你笔记本里的经验摘要——它记录跨项目的偏好、已知坑点、个人风格是“个人经验库”。一句话概括settings 管机器CLAUDE.md 管项目memory 管人。搞懂这个分工后面所有配置都顺理成章。1.1 三个配置文件的生命周期差异理解三者的另一个角度是看它们的读取时机和作用范围。settings.json在每次启动会话时被读取属于“进程级”配置。你改完参数后通常需要重启 Claude Code 会话才能完全生效因为像权限模式、钩子函数这类东西在初始化阶段就已经绑定。它又分两层用户级~/.claude/settings.json和项目级.claude/settings.json后者覆盖前者这一点和很多工具的设计思路一致。CLAUDE.md则是在每个会话自动加载的上下文文件。它的作用范围同样分全局~/.claude/CLAUDE.md和项目级项目根目录或.claude目录下的CLAUDE.md而且项目级文件会自动与全局文件组合。这里有个关键点CLAUDE.md中对指令的描述方式直接影响 AI 的遵循度写得太抽象、太笼统AI 就会“自由发挥”。比如你写“代码要规范”它就很难拿捏尺度但写“函数命名使用 camelCase禁止超过 80 字符的行”它就完全能执行。memory的读取机制和前两者不一样它不是启动时一次性加载而是按需读取。也就是说AI 会判断当前任务是否需要翻阅历次总结的“经验”再决定是否把相关记忆调入上下文。这个特性决定了 memory 里的内容应当是信息密度高、可独立理解的短句而不是长篇大论。1.2 配置优先级与覆盖关系实际使用中很多人会困惑我明明在全局 settings 里设了permissionMode: acceptEdits怎么进某个项目后还是问我确认这多半是项目级 settings 覆盖了全局配置。优先级从低到高是全局 settings 项目 settings 命令行参数。CLAUDE.md 同理全局文件先加载项目文件追加在后两个都会生效但如果语义冲突后面的指令在模型中更占权重。你可以在项目级文件开头写一句“以下规则优先于全局规则中与本文冲突的部分”来强化这一点实测下来对减少“二选一”式的犹豫很有帮助。Memory 则不存在覆盖关系它是增量累积的按“相关度”参与决策。所以记忆碎片之间如果矛盾AI 会倾向于相信最近写入的那条——因此定期整理、删掉过时记忆比不断追加更重要。2. settings.json 核心配置精讲从入门到够用settings.json是三个配置里最“工程化”的一个它直接决定 Claude Code 怎么跟你的终端、编辑器、Git 仓库打交道。我第一次打开这个文件时里面只有几行默认配置当时没觉得有什么好调的后来遇到几个具体场景才意识到它的分量。2.1 权限模式与安全边界Claude Code 默认在操作文件前会向你请求确认但对于熟悉命令行的人来说每个操作都弹确认会严重打断思路。permissionMode就是用来控制这个行为的{ permissionMode: acceptEdits, allowedTools: [Bash(npm run test)], denyTools: [Bash(rm -rf *)] }我一般开发阶段用acceptEdits允许自动改文件这样它改代码前不用我逐个确认但在执行高风险命令时仍然弹窗询问属于安全性和效率的折中。如果是在 CI 或无人值守环境才会考虑bypassPermissions但那个模式下出过事的人都知道后果——有一次朋友在容器里配了这个Claude 直接执行了一条清空命令还好目标目录是空的不然哭都来不及。建议权限配置遵循两个原则能用acceptEdits解决就不要轻易上bypassPermissions给 AI 留一个“需要问人”的边界反而能避免大部分连环操作失误allowedTools和denyTools要写得足够具体优先用带参数匹配的写法例如Bash(git push)只允许执行 git push不允许其他 bash 命令避免白名单变成“任意执行许可”。2.2 环境、编辑器与外观参数另一类常用配置是关于集成体验的。很多人问 Claude Code 在 VS Code 里怎么用最顺手其实核心就是把编辑器的env和model调对。{ env: { CLAUDE_CODE_ENABLE_TELEMETRY: 0, EDITOR: code }, model: claude-sonnet-4-20250514, includeCoAuthoredBy: false }env里可以注入环境变量比如关掉遥测、指定编辑器。model用于切换模型版本这里我要多说一句模型选型直接影响成本和质量上限Opus 级别擅长复杂架构推理Sonnet 则在日常编码时响应更快。按任务切换模型是很常见的做法比如架构设计时用 Opus写 CRUD 用 Sonnet这比一个模型走到黑实用得多。另外有两个细节容易被忽略。一个是includeCoAuthoredBy它会把 GitHub Copilot 风格的“Co-Authored-By”尾注加到提交信息里不需要的话显式关掉不然每次 commit 都会被修改。另一个是cleanupPeriodDays用于清理历史会话我一般设置 30 天防止本地积累太多缓存。2.3 钩子Hooks配置工作流自动化的关键如果你只把 settings 当配置文件就亏了它真正的杀手级能力是 Hooks。通过hooks字段可以在事件发生时自动执行脚本比如提交前自动跑测试、消息发送前注入额外上下文、收到错误时截图。{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: node scripts/check-bash-command.js \$CLAUDE_SAFE_COMMAND\ } ] } ], PostToolUse: [ { matcher: Edit, hooks: [ { type: command, command: node scripts/lint-after-edit.js } ] } ] } }PreToolUse和PostToolUse是最常用的两个事件前者可以在命令真正执行前拦一道做安全检查或环境准备后者则可以在编辑后自动触发格式化或 lint。需要注意钩子脚本的 stdout 会返回给 Claude所以脚本输出最好只放必要信息别把一堆日志灌进去否则会稀释真正有用的内容。3. CLAUDE.md 编写方法论让 AI 真正读懂你的项目如果说 settings.json 是给工具调参那么 CLAUDE.md 就是给 AI 做“上岗培训”。这个文件的质量直接决定 AI 在这个仓库里是不是 “顺手”。3.1 结构模板每个项目都应该有的几个区块我一般把 CLAUDE.md 组织为五个区块项目概述两句话说明这个项目干什么、技术栈是什么。命令速查build/test/lint/dev 四个最常用命令。代码风格约束命名、缩进、禁用特性。架构地图核心目录各自职责数据流大致走向。常见任务流程比如“改一个 API 接口要走哪几步”。下面是一个精简实例# Website Backend ## 项目概述 基于 FastAPI 的电商后端提供商品、订单、用户三个核心模块。 使用 PostgreSQL Redis部署在 Docker Compose 环境中。 ## 常用命令 - 启动开发服务器: uvicorn app.main:app --reload - 运行测试: pytest tests/ -v - 代码检查: ruff check . - 提交前检查: ruff check . pytest ## 代码风格 - Python 版本 3.12使用 from __future__ import annotations - 数据库字段命名一律 snake_caseAPI 路由命名一律 kebab-case - 禁止在业务逻辑层直接操作 session必须通过 repository 层 - 异常必须定义在 app/exceptions.py并注册全局处理器 ## 架构地图 - app/api/路由与请求模型 - app/services/业务逻辑禁止 import api 层 - app/repositories/数据访问只操作 ORM 对象 - app/models/SQLAlchemy 模型禁止写业务逻辑 ## 修改一个订单状态接口的流程 1. 在 app/models/order.py 找到 Order 模型 2. 在 app/repositories/order_repo.py 新增状态变更方法 3. 在 app/services/order_service.py 调用 repo 方法并附加状态机校验 4. 在 app/api/routes/order.py 暴露路由 5. 补充测试到 tests/test_order_status.py写完这个文件后AI 在执行“给订单增加取消功能”时会主动按你的目录规范往正确位置放代码而不是直接在路由文件里堆出一坨业务逻辑。3.2 写得“具体”而非“抽象”是关键CLAUDE.md 最常见的失败原因是写了太多废话比如“代码要优雅”“注意性能”“遵循最佳实践”。这类描述看起来没问题但模型执行时无法量化说了等于没说。写得具体的标准是换一个人来读能不能不追问就执行。同样是描述数据库操作你看这两种写法的差别抽象版“操作数据库时要规范。”具体版“使用 SQLAlchemy 2.0 的 session 模式禁止使用session.execute(text(...))查询必须走模型类更新必须通过 ORM 实例的字段赋值并 commit。”后者即便你没有逐条解释为什么模型也能照做。如果你发现 AI 的输出风格反复偏离预期回头检查 CLAUDE.md十有八九是规则写得太“感觉化”。另外还有一个实用技巧CLAUDE.md 里可以引用其他文件用path/to/file的语法把额外文档拉进上下文。这样你就不需要把所有细节堆到主文件里把架构细节写进docs/architecture.md然后在 CLAUDE.md 里引用它既保证上下文聚焦又能在需要时自动读取细节。3.3 全局与项目级的搭配策略全局 CLAUDE.md 最适合放你个人的通用偏好比如“回复一律用中文”“代码提交信息使用 Conventional Commits 格式”“遇到不确定的 API 先查文档不要猜”。而项目级文件放仓库专属规则。经验是全局文件不要超过 40 行否则会侵占比重影响对具体项目的专注度。项目级文件可以长一些但也要控制在 150 行以内更长的内容应该拆到 docs 里用引用。我见过有人把整本架构文档塞进 CLAUDE.md 里结果上下文被吃掉了很大一块AI 反而忽略了真正重要的当前任务细节这种“什么都想告诉它”的做法最后反而是什么都记不住。4. Memory 机制详解把经验沉淀到该沉淀的地方Memory 是很多人用得最模糊的一块它不像 settings 那样有明确的字段可调也不像 CLAUDE.md 那样写下来就必然参与上下文。它的工作方式更像“带有衰减的长期缓存”。4.1 Memory 的存储结构与读写策略在 Claude Code 中memory 基于一个可配置的目录默认在~/.claude/memory由配置项memoryPath指定。每个记忆条目被设计成小而独立的 Markdown 文件文件名就是记忆的关键词内容就是记忆正文。{ memoryPath: ~/.claude/memory }目录里的文件长这样# python-project-structure - Django 项目不要再手动创建 migration用 python manage.py makemigrations - settings/base.py 区分 dev 与 prod新增环境变量需要写到 .env.example读的时候AI 会根据任务关键词做检索例如当前任务是“修改 Django 模型”它检索到python-project-structure、django-migrations这类相关文件后会把内容临时并入上下文。这个“按需读取”的设计决定了记忆条目必须做到两点文件名要像标签一样精准内容要像便签一样短。既不能把所有经验混进一个“general.md”大杂烩也不能写成几百字的小作文否则按需检索会失效或者内容挤占上下文窗口。4.2 如何让记忆条目发挥跨项目价值这里涉及一个问题记忆写进 memory是真的“所有项目通用”吗按我的理解是的。memoryPath是全局路径意味着它会把你在 A 项目里踩过的坑自动用于 B 项目。这既是优势也是风险。所以我的建议是把 memory 只写“与具体项目无关的经验”。比如“Windows 上路径大小写不敏感但 Linux 敏感跨平台脚本用 pathlib 处理路径。”“Vue 3 的组合式函数命名用 use 前缀返回 ref 而不是裸对象。”而不要把“订单模块的 state 机在 xxx 文件”写进去——那应该落在 CLAUDE.md 里。Memory 装的是“我对技术的偏好认知”CLAUDE.md 装的是“这个仓库的客观事实与约定”。两者一旦颠倒AI 会在每个项目里都尝试套用上一个项目的结构表现得非常拧巴。4.3 记忆整理节奏与“遗忘”的艺术Memory 也是需要定期做减法的。我每隔一两周翻一次 memory 目录做三件事合并重复条目删除已经过时的经验比如某旧版本库的坑在新版本已经修复把条目按当前技术栈重新分类。这里有个我在实际中踩过的坑早期我把“使用 yarn 而不是 npm”写进了 memory后来某个新项目内部强制使用 npm因为 team 里有人用 npm workspaces结果 AI 在生成命令时反复建议 yarn导致项目脚本风格不一致。后来我删掉了那条记忆在对应项目的 CLAUDE.md 里覆盖为“本项目一律使用 npm”冲突才消失。所以说memory 是“你个人默认”CLAUDE.md 是“项目特例”。当两者冲突项目特例应该赢。5. 实操中常见的坑与排查思路配置体系单独看都简单组合起来问题就多了。下面这些是我实际遇到过的、以及社区里高频出现的问题整理成速查表按图索骥能省不少时间。5.1 配置不生效排查速查表症状可能原因解决办法settings 改了但行为没变会话未重启重启 Claude Code 再验证项目内规则反复违反项目 CLAUDE.md 与全局内容冲突在项目文件开头声明“本项目规则优先”memory 内容没有起作用文件名与任务关键词不匹配用更贴近业务的关键词重命名记忆文件命令被拦截或误杀allowedTools 匹配过宽或过窄用带参数匹配的最小白名单钩子没有触发脚本退出码非 0 被静默吞掉把脚本改成显式 echo 错误查看 hook 调试输出项目级配置被忽略目录层级不对确认.claude/在仓库根目录而非嵌套子目录这里特别提醒一个容易忽略的点CLAUDE.md 的命名和路径在不同版本有过变化早期版本用的可能是CLAUDE.md在根目录后来生态里也出现了.claude/CLAUDE.md的形式。建议按官方文档确认当前版本约定的路径然后保持一致。一大类“怎么不生效”的问题其实就出在这里。5.2 关于 memory 文件命名与检索的实战经验我在 memory 目录里总结了这么几个目录memory/ git-workflow.md python-style.md frontend-build.md testing-habits.md terminal-aliases.md每个文件都很短最多十条要点。命名上我刻意只取了 top-level 的宽泛关键词避免太具体导致检索不到。比如python-style.md比django-rest-framework-style.md适用范围更广后者我宁愿放进对应项目的 CLAUDE.md。另外我发现一个很有用的技巧在 memory 文件的标题里附上“负面清单”也很有效比如python-style.md里直接写“不要用typing.Any作为函数参数注解除非调用方明确为动态数据”。负面约束比正面要求更能减少 AI 的自由发挥因为模型对“不要做什么”的执行往往更稳定。5.3 版本升级后的配置兼容性Claude Code 更新频率高配置字段也会调整。我在升级后遇到过两次配置全失效的情况最后发现是旧字段被重命名了。应对方法就一条升级后先跑一遍官方迁移命令或查看 changelog比对着旧教程排查快得多。对于配置文件本身强烈建议纳入版本管理。把.claude/目录提交到 Git 仓库团队里的每个人拉下来就获得一致的配置基础全局的~/.claude也可以定期备份至少把 settings 和 CLAUDE.md 复制一份省得重装环境后一切从零开始。注意不要把 memory 目录提交到仓库。它包含大量个人经验与偏好不一定适合团队共享而且有些内容可能涉及个人工作习惯没必要暴露给所有人。6. 三套配置的有机联动我目前的最终实践最后分享一下我目前在自己机器上形成的最终配置组合算是把前面所有点串联成一个完整示例。全局settings.json保持精简{ permissionMode: acceptEdits, model: claude-sonnet-4-20250514, env: { CLAUDE_CODE_ENABLE_TELEMETRY: 0 }, includeCoAuthoredBy: false, memoryPath: ~/.claude/memory }全局CLAUDE.md只有十几行写我的通用偏好比如中文回复、Conventional Commits、遇到模糊需求先问再动手。每个项目再各自维护一份 CLAUDE.md按照前面说的五个区块来写内容在首次进入项目时花十分钟补全之后每次大改动顺手更新一两行。Memory 目录保持十个文件以内定期合并整理。用这套组合我实际感受到最明显的变化是AI 在陌生仓库里的“首发命中率”明显变高。以前它总是先乱猜一通再慢慢修正现在基本第一次生成就符合项目规范跨项目切换时也不会带着上一个项目的坏习惯。尤其是 memory 和 CLAUDE.md 配合后它能区分“你个人偏好”和“这个项目的要求”这是单靠一个配置永远做不到的效果。配置体系的维护成本其实不高核心是养成两个习惯一是只在正确的地方写正确的信息二是定期回头看删掉过时的规则与记忆。我个人的体会是配置不是一次写完就一劳永逸它更像是给 AI 持续培训的过程你投入多少清晰度它就还你多少稳定性。