你的 .claude 文件夹里都有什么

你的 .claude 文件夹包含两类截然不同的内容:一类是会在每次会话开始时加载进 Claude 上下文的指令(CLAUDE.md、rules/、skills/、agents/),另一类是控制工具行为的配置(settings.json、hooks、MCP 服务器)。这两类内容又分散在两个位置:一个是你会提交到版本库的项目目录,另一个是位于用户主目录下、永远不会被提交的 ~/.claude 目录。

这个文件夹还会自行生长。批准一次权限提示就会写入一个你并没有主动创建的文件,/init 会生成一份 CLAUDE.md,而一个 pull request 最后可能夹带了一份 .claude/settings.local.json,里面塞满了某位开发者个人的 allow 规则。

本文是一次逐文件的巡览:每个路径的作用是什么、当两个文件设置了同一项时谁说了算,以及针对每个文件给出的”该不该提交到仓库”的结论。

两个 .claude 位置分别在哪里?

Claude Code 会读取两个 .claude 根目录。一个位于项目内,随仓库一同分发,面向整个团队;另一个是主目录下的 ~/.claude,只属于你自己,并且会跟随你在这台机器上的每一个项目。这一划分是最值得牢记的一点。Claude Code 目录参考文档也划出了同一条界线:提交项目文件,把主目录里的那些留在原地。Windows 上主目录根位于 %USERPROFILE%\.claude,而把 CLAUDE_CONFIG_DIR 指向别处会让整套配置随之迁移。

my-project/
├── CLAUDE.md                    # instructions loaded every session
├── CLAUDE.local.md              # private preferences, gitignored
├── .mcp.json                    # team-shared MCP servers
└── .claude/
    ├── settings.json            # permissions, hooks, env, model defaults
    ├── settings.local.json      # your personal overrides, gitignored
    ├── rules/*.md               # topic-scoped instructions, optionally path-gated
    ├── skills/<name>/SKILL.md   # reusable prompts invoked with /name
    ├── commands/*.md            # single-file prompts, same mechanism as skills
    ├── agents/*.md              # subagent definitions with their own prompt and tools
    ├── workflows/*.js           # workflow scripts saved from /workflows
    ├── output-styles/*.md       # instruction sets that adjust how Claude works
    └── agent-memory/<name>/     # persistent memory for subagents

~/.claude.json                   # app state, OAuth, personal MCP servers
~/.claude/
├── CLAUDE.md                    # your instructions, across every project
├── settings.json                # personal defaults
├── rules/*.md                   # user-level rules, applied to every project
├── keybindings.json             # custom keyboard shortcuts
├── themes/*.json                # custom colour themes
├── plugins/                     # cloned marketplaces and per-plugin data
├── projects/<project>/memory/   # auto memory Claude writes itself
└── .credentials.json            # login credentials

实际使用中,几乎所有的编辑工作都集中在两个文件上:CLAUDE.md 和 settings.json。其余都是可选项。

CLAUDE.md、导入(imports)与按路径触发的规则

CLAUDE.md 是 Claude Code 在每次会话开始时载入上下文的文件,它会从四个位置读取:托管策略、~/.claude/CLAUDE.md、项目内(./CLAUDE.md 或 ./.claude/CLAUDE.md),以及用于个人笔记的 ./CLAUDE.local.md。memory 文档说得很清楚:这些文件是叠加而非互相竞争的——Claude Code 找到的每个文件都会依次加入上下文,从文件系统根目录开始一路向下直到你的工作目录;在同一个目录内,CLAUDE.local.md 排在 CLAUDE.md 之后。父目录中的文件会在启动时加载;子目录中的文件则要等到 Claude 打开该目录下的文件时才加载。

@path/to/file 语法用于引入另一个文件,路径相对于发起导入的文件解析,最多可嵌套四层。把一个冗长的文件拆成多个导入只是让它更整洁,并不能省回任何上下文,因为被导入的内容同样会在启动时展开。导入解析会忽略反引号内或围栏代码块内的所有内容——这正是你在指令中提到某个路径却不把该文件引入进来的方法。

有两个限制值得注意。200 行这个数字是一个目标而非硬性上限:超过之后,文件会占用更多上下文,而 Claude 遵循它的可靠性也会下降。真正的上限是 4 MiB。Claude Code 会完整加载不超过该大小的 CLAUDE.md,超出则直接跳过。

.claude/rules/*.md 是模块化的替代方案。规则文件会被递归发现,每个文件对应一个主题。如果一条规则没有 frontmatter,它会在启动时加载,优先级与 .claude/CLAUDE.md 同级;如果给它加上 paths 字段,它就会一直待在上下文之外,直到 Claude 接触到匹配该 glob 的文件。

---
paths:
  - "src/components/**/*.tsx"
---

Prefer function components with explicitly typed props.
Co-locate the test file beside the component it covers.

跨文件出现相互矛盾的指令时,解析结果是不确定的,所以这里没有什么规则可背。运行 /context 或 /memory 查看实际加载了什么;如果某条指令确实必须在固定时点执行,那就把它写成 PreToolUse hook。hook 会在会话中的固定时点以 shell 命令的形式运行,无论 Claude 是否会主动选择这么做。

AGENTS.md 处于什么位置?

如果一个仓库已经为其他编码 agent 准备了 AGENTS.md,那就不需要额外做什么:Claude Code 自己就会读取这些文件,无论它们是单独存在还是与 CLAUDE.md 并存。当工作目录及其各级父目录都没有 CLAUDE.md 时,加载的就是 AGENTS.md。具体加载哪些文件由 /config 中的 “Project instructions” 决定,而该设置项只在能够拉取 Anthropic 特性开关的会话中出现,因此在 Bedrock、Vertex 和 Foundry 上是缺失的。

对于无法加载 AGENTS.md 的会话,或者当你想保留既有的 CLAUDE.md 时,可以在 AGENTS.md 旁边放一份 CLAUDE.md 来导入它:

@AGENTS.md

## Claude Code

Run `pnpm typecheck` before proposing any change under `packages/api/`.

如果你不需要任何 Claude 专属内容,符号链接同样可行:ln -s AGENTS.md CLAUDE.md。Windows 在没有管理员权限或开发者模式的情况下无法创建符号链接,所以在那里用导入更稳妥。直接读取的 AGENTS.md 不会出现在 /context 或 /memory 的 Memory files 条目下,会话会改为打印一行 “AGENTS.md loaded”。

不要把 AGENTS.md 与 CLAUDE.local.md 混为一谈。后者是 CLAUDE.md 的私人、被 gitignore 的伴生文件,与跨工具互操作毫无关系。

skills/、commands/ 和 agents/ 有什么区别?

commands 和 skills 运行在同一套机制上,都响应 /name。目录参考文档建议新工作使用 skills/<name>/SKILL.md,因为 skill 目录可以把配套文件与指令打包在一起,而 command 只是单个 markdown 文件。已有的 commands/*.md 目录仍然可用。关于如何为前端工作组织 skill,参见我们的指南用于前端工作流的 Claude Code skills。

agents/*.md 存放 subagent 定义,每个都有自己的 prompt 和工具列表。这两个目录在项目作用域和 ~/.claude 下都存在,并且都是凭所在位置被识别,而不是靠在某个设置文件中注册。

Claude Code 配置优先级:settings.json 对阵 settings.local.json

settings.json 是共享的项目文件,settings.local.json 是你个人的项目内覆盖文件;当两者设置了同一个键时,本地文件胜出。设置参考文档给出了五个优先级层级,从高到低依次是:托管设置、命令行参数、.claude/settings.local.json、.claude/settings.json、~/.claude/settings.json。你通过 --settings 传入的 JSON 恰好排在托管设置之下、你自己那三个文件之上。

容易让人踩坑的是,并非所有键都遵循这套层级。诸如 permissions.allow、permissions.ask 和 permissions.deny 这类列表型键会跨作用域合并而非相互替换,因此即便你的本地文件允许了某个工具,队友共享的 settings.json 中的 deny 规则依然会生效。有四个模型相关的键是这一合并规则的例外。fallbackModel 是一条有序链,所以设置了它的最高优先级文件会提供整个值。modelPicker 的机制相同,只不过它只读取托管设置、--settings 和用户设置,会忽略项目文件与本地文件中的该键(Claude Code v2.1.242 及以后版本)。托管的 availableModels 列表会原样生效,你自己追加的内容会被丢弃;不过在用户、项目和本地这三个文件之间,这些数组仍然会合并。modelSettings 则是逐个模型分别解析的。

共享文件:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "cleanupPeriodDays": 30,
  "permissions": {
    "deny": ["Read(./.env)"]
  }
}

本地文件:

{
  "cleanupPeriodDays": 7,
  "permissions": {
    "allow": ["Bash(npm run lint)"]
  }
}

最终解析出的会话使用 cleanupPeriodDays: 7,因为在标量键上本地文件的优先级高于共享文件。两条权限规则都保持生效:npm run lint 无需提示即可运行,而读取 .env 仍被阻止。设置文件是严格 JSON:加一个 // 注释或一个尾随逗号都会导致解析失败。$schema 那一行能为你带来编辑器自动补全;由于发布的 schema 有时会落后于最新的 CLI 版本,针对上周才被文档收录的某个键所给出的告警,说明的往往是 schema 的问题而不是你文件的问题。运行 /status 可以确认哪些设置文件被加载了。

hooks 和 MCP 服务器存放在哪里?

hooks 不是独立的文件。它们位于 settings.json 的 hooks 键下,放在你希望它生效的那个作用域中,并且修改后无需重启会话即可生效。MCP 服务器则按受众划分:.mcp.json 位于项目根目录,随仓库一起分发,是团队共享的清单。个人 MCP 服务器位于 ~/.claude.json 中,该文件同时还保存应用状态、OAuth 数据以及按项目路径归类的 local 作用域服务器,因此应把它当作机器状态而非一个供你手工编辑的配置文件。

哪些该提交,哪些该 gitignore

当 Claude Code 首次在一个尚未忽略该本地文件的仓库中写入它时,会向你的全局 git excludes 追加 **/.claude/settings.local.json。这次写入发生的时机,就是你对权限提示回答”Yes, and don’t ask again”的时候。如果你手动创建该文件,系统不会替你添加任何条目,所以要显式写明:

# Claude Code personal config
# settings.local.json is usually auto-excluded already; this covers hand-created files
.claude/settings.local.json
CLAUDE.local.md

共享设置同样是云端会话所看到的内容,因为那些会话是基于全新克隆运行的。用户级文件和本地文件只留在你的机器上,永远不会传到那里。

~/.claude 下的一切都是明文

会话记录、工具输出、粘贴的文本以及 history.jsonl 提示词日志,全部以纯文本形式落盘,唯一的屏障只有文件权限。如果某条命令在会话中打印过一个 token,那个 token 就静静躺在某份记录里。.credentials.json 保存着你的登录凭据,并且不会被保留期清理所删除——该清理机制会在符合条件的文件超过 cleanupPeriodDays 后将其清除:默认 30 天,最低可设为 1,而 0 会被判为无效值而拒绝。

一旦理清脉络,这个文件夹其实没看上去那么庞大:指令是拼接的,设置讲优先级,权限做合并,而主目录永远不进版本控制。对照上面的目录树打开你自己的 .claude/,删掉那些没人有意写入的文件,并在下一个 pull request 替你做出决定之前,先加上那两行 .gitignore 配置。

常见问题

队友提交的 .mcp.json 中带来的 MCP 服务器,我必须逐一批准吗?

是的。在交互式会话中,Claude Code 在使用 .mcp.json 声明的任何项目作用域服务器之前都会询问,而且是每位开发者各自作答,而不是整个仓库只答一次。运行 claude mcp reset-project-choices 可以清除这些回答。非交互式场景无法展示提示:claude -p 运行、Agent SDK 会话和云端会话都会在不询问的情况下加载项目作用域服务器,因此请使用 disabledMcpjsonServers 在所有权限模式下屏蔽某个服务器。

如何在不编辑文件的情况下为单次会话覆盖某项 Claude Code 设置?

传入 --settings,参数可以是 JSON 文件路径,也可以是内联 JSON 字符串。它的优先级低于托管设置,但高于你的用户、项目和本地文件。某些键还有各自的命令行标志或环境变量,谁胜出则要逐键判断:--model 和 /model 胜过 ANTHROPIC_MODEL,而 CLAUDE_CODE_EFFORT_LEVEL 胜过 /effort。

会话进行中编辑 settings.json 会立即生效吗?

有些键会就地重新加载,有些则只在会话启动时读取一次,因此某次修改可能看起来被忽略了,直到下次启动才生效。权限和 hooks 无需重启即可重新加载,而 model、effortLevel 和 modelSettings 只在启动时读取一次。自 v2.1.251 起,outputStyle 的更改会从你的下一条消息开始生效;不过在终端中,会话进行中创建或编辑的样式文件只有在重启后才会被识别。如果重启后某个值看起来仍然不对,运行 /status 并检查优先级:诸如 .claude/settings.local.json 之类更高作用域的文件可能设置了同一个键。

删除 ~/.claude 下的 projects 文件夹会损失什么?

删除 projects/ 会移除已保留的会话记录,并可能导致你无法恢复过往会话,不过新会话不受影响。命令 claude project purge 是更有针对性的替代方案:它会删除某个项目的会话记录、自动记忆、任务和文件历史条目,history.jsonl 中对应的提示词行,以及 ~/.claude.json 中该项目的条目。shell-snapshots/ 和 backups/ 都会原样保留。加上 -i 可逐步查看删除计划。