探秘Claude Code的“.claude”目录：那些藏在背后的配置与记忆

如果你曾经用过Claude Code，或许会发现项目根目录下突然多出一个名为.claude的文件夹，又或者在User Home目录下也存在一个同样的隐藏目录。对于大多数开发者而言，这只是一个不起眼的配置文件夹，但它其实大有玄机------它是Claude Code理解项目、记住偏好、甚至执行复杂任务的核心所在。

这篇文章将以第三方的视角，带大家走进这个神秘的.claude目录，看看里面到底存放着什么，以及它们是如何影响Claude Code的日常行为的。

一、这个目录到底在哪儿？

Claude Code会从两个地方读取配置和指令：

• 项目目录 ：即当前代码仓库下的 .claude/ 文件夹（以及项目根目录下的几个特定文件）。这部分内容通常会被提交到Git仓库中，以便团队成员共享相同的配置。
• Home目录 ：即 ~/.claude/。这里的配置属于个人专属，会跨项目生效，不会被同步给团队。

简单来说，项目中的 .claude服务于团队协作，而Home目录中的 .claude则服务于个人习惯。

对于大多数普通用户而言，日常打交道最多的其实是 CLAUDE.md 和 settings.json 这两个文件。目录下的其他部分（如 skills、rules、subagents 等）则属于"按需启用"的高级功能，用到了才会发挥威力。

二、文件全景图：一张表看懂每个文件是干嘛的

为了让大家有一个直观的认识，这里先把.claude目录下可能遇到的各类文件整理成一张表格。表格中包含了文件的作用、作用域（项目级还是全局级）以及是否需要提交到Git。

文件	作用域	是否提交	作用描述
CLAUDE.md	项目 & 全局	✓	每次会话都会加载的核心指令文件。
rules/ *****.md	项目 & 全局	✓	根据主题或路径加载的"规则"文件。
settings.json	项目 & 全局	✓	权限、钩子（hooks）、环境变量、模型默认配置。
settings.local.json	项目		个人覆盖配置，通常被 .gitignore 忽略。
.mcp.json	项目	✓	团队共享的MCP（模型上下文协议）服务器配置。
.worktreeinclude	项目	✓	指定需要复制到新工作树（worktree）中的被忽略文件。
skills/****/SKILL.md	项目 & 全局	✓	可通过 /name 调用或自动调用的"技能"提示词。
commands/*.md	项目 & 全局	✓	单文件形式的快捷命令，机制与技能类似。
output-styles/*.md	项目 & 全局	✓	自定义的输出样式，影响系统提示的呈现方式。
agents/*.md	项目 & 全局	✓	子代理的定义文件，包含特定的提示词和工具集。
agent-memory/****/	项目 & 全局	✓	子代理的持久化记忆存储位置。
~/.claude.json	全局		应用状态、OAuth认证、UI开关、个人MCP服务器。
projects/****/memory/	全局		自动记忆：Claude跨会话记录给自己的笔记。
keybindings.json	全局		自定义键盘快捷键。

注意 ：除了表格中的内容，还有像 managed-settings.json（系统级，由组织强制下发，用户无法覆盖）和 CLAUDE.local.md（项目根目录下的个人偏好文件，需手动创建并加入 .gitignore）等文件未在表格中列出，但在实际使用中也会遇到。

三、核心文件详解：它们什么时候起作用？

上述文件虽然多，但真正决定Claude Code"性格"的，主要是以下几个。让我们逐一拆解。

1. CLAUDE.md：项目的"说明书"

如果只能选一个文件来配置Claude，那一定是 CLAUDE.md。这个文件在每一次会话启动时都会被加载到上下文（Context）中。

它的作用是告诉Claude当前项目的"规矩"：比如用什么命令构建、用什么框架、代码风格是什么。开发者通常会把团队约定写在里面，这样Claude在写代码或提建议时，就会遵循这些约定，仿佛它就是这个团队的老成员。

使用建议 ：内容尽量控制在200行以内。虽然文件可以更长，但过长的指令反而可能让模型难以严格遵守。如果某些内容只在特定任务中需要，更好的做法是将其移到 rules（规则）或 skills（技能）中，按需加载。

示例内容（假设是一个TypeScript+React项目）：

# 项目约定

## 常用命令
- 构建: `npm run build`
- 测试: `npm test`
- 代码检查: `npm run lint`

## 技术栈
- TypeScript 严格模式
- React 19，仅使用函数组件

## 规则
- 使用具名导出（Named exports），禁止默认导出（default exports）
- 测试文件紧挨源文件：`foo.ts` -> `foo.test.ts`
- 所有API路由返回 `{ data, error }` 格式

2. rules/*.md：按需加载的"专项规则"

与 CLAUDE.md 总是加载不同，rules 文件夹下的文件只有在涉及特定主题或特定文件路径时才会被读取。这让规则管理变得更加高效。

例如，当用户打开一个测试文件时，Claude可能会自动加载 testing.md 中的规则；当编辑API接口时，可能加载 api-design.md 中的规则。这种机制避免了全局上下文的浪费。

3. settings.json：权限与行为的"控制面板"

settings.json 是用来控制Claude Code"能不能做某件事"的文件。它包括权限管理（比如是否允许自动运行命令）、钩子（在特定事件前后执行自定义脚本）、环境变量和模型默认参数。

值得注意的是，如果存在 settings.local.json，它会覆盖 settings.json 中的同名配置，且通常不会提交到Git，非常适合存放个人的临时调试配置。

4. Skills & Commands：给Claude的"技能书"

Skills 和 Commands 机制非常相似，都存放在 .claude/ 下，用于定义可复用的提示词工作流。区别在于，Skills通常更复杂，可能包含多个文件（如 SKILL.md 和辅助文件），而Commands通常是单个 .md 文件。

用户可以在会话中输入 /skill-name 来调用这些技能。对于重复性高的工作流（比如"代码安全审查"、"生成提交信息"），将其封装为Skill可以大大提升效率。

5. Agents & Agent-Memory：专事专办的"子代理"

Agents（子代理）是Claude Code中一个非常强大的概念。开发者可以为特定任务定义专门的子代理，子代理拥有独立的提示词和工具集，拥有自己的上下文窗口，完成任务后返回结果给主会话。

例如，可以定义一个 code-reviewer.md 的子代理，让它只加载代码审查相关的提示词和工具，专心审查代码，而不受主会话中其他无关指令的干扰。

而 Agent-Memory 则是为了给这些子代理提供"记忆力"。如果某个子代理需要记住上次运行时的状态或结论，信息就会存放在 agent-memory/<agent-name>/MEMORY.md 中。

6. 自动记忆（Auto Memory）：Claude的"私人便签"

这是一个非常有趣的特性。它位于全局目录下的 projects/<project>/memory/ 中。Claude 会在需要时自动记录一些笔记，用于跨会话的记忆。比如，如果用户在一个会话中纠正了Claude对某个模块的理解，Claude可能会将这次纠正记入自动记忆，下一次开启新会话时，它就会记得这件事。

四、如何查看当前加载了哪些配置？

面对这么多配置文件，有时候会好奇：当前这一次会话，到底加载了哪些东西？

Claude Code提供了一系列内置命令，供用户随时检查状态：

命令	作用
/context	查看上下文（Token）使用情况概览，包括系统提示、记忆文件、技能、MCP工具和消息量。
/memory	显示哪些 CLAUDE.md 和 rules 文件被加载，以及自动记忆条目。
/agents	显示配置好的子代理及其设置。
/hooks	显示当前激活的钩子（Hook）配置。
/mcp	查看已连接的MCP服务器及其状态。
/skills	列出项目、用户和插件来源中可用的技能。
/permissions	查看当前的允许和拒绝规则。
/doctor	对安装和配置进行诊断。

建议先运行 /context 看个全貌，再根据需要运行具体的命令深入排查。

五、写在最后：关于优先级

需要特别注意的是，配置文件之间存在"优先级"关系。组织下发的托管设置（managed settings）优先级最高 ，用户无法覆盖。其次是CLI标志 （如 --permission-mode），它们会覆盖 settings.json 中的对应项。最后才是环境变量和配置文件本身。

理解了这个优先级顺序，在遇到"为什么改了配置不生效"的问题时，排查起来就会更有方向感。

.claude 目录就像是Claude Code的大脑配置文件。从简单的 CLAUDE.md 定义项目规范，到高级的 subagents 拆分复杂任务，这个目录承载了让AI工具真正适配开发者工作流的所有可能性。与其说这是一个配置文件夹，不如说它是连接人类开发习惯与AI执行能力的一座桥梁。