.claude 目录到底放了什么：CLAUDE.md、settings、skills、hooks 全梳理

用 Claude Code 久了,你会在项目里看到一个 .claude/ 目录,home目录里还有一个 ~/.claude/。里面 settings.json、skills/、hooks、rules/、agents/ 一堆东西,哪个该提交给团队、哪个是本地私有、哪个会在每次会话都加载——很容易搞混。

这篇就当一张"地图":按项目级(你的项目/)和全局级(~/)两条线,把每个文件/目录讲清楚——它是干什么的、什么时候加载、要不要提交到 git,并给一个最小示例。

先记住一个总原则:

项目级的东西跟着仓库走、和团队共享;全局级的东西是你个人的、对所有项目生效、永远不提交。当两者冲突时,项目级优先。

一、项目级:你的项目根目录

这几个文件直接躺在项目根(注意:有几个不在 .claude/ 里,而在仓库根目录)。

根目录下的三个文件

文件	作用	何时加载	git
`CLAUDE.md`	项目说明,Claude 每次会话都读	每次会话开始载入上下文	提交
`.mcp.json`	团队共享的 MCP 服务器配置	会话开始时连接,工具 schema 按需加载	提交
`.worktreeinclude`	创建 worktree 时要复制进去的 gitignore 文件清单	Claude 建 git worktree 时读取	提交

CLAUDE.md 是最该先建的。把项目约定、常用命令、架构背景写在这,Claude 就和你团队用同一套假设干活。经验法则:控制在 200 行内;只在特定任务才需要的内容,挪去 skill 或带 paths: 的 rule,避免每次会话都占上下文。会话里可以用 /memory 直接打开编辑它。

# Project conventions

## Commands
- Build: `npm run build`
- Test: `npm test`

## Stack
- TypeScript strict mode；React 19，仅函数组件

## Rules
- 一律具名导出，不用 default export
- 测试与源码同目录：`foo.ts` -> `foo.test.ts`

.mcp.json 放团队共用的 MCP 服务器;只有你自己用的服务器用 claude mcp add --scope user 写到 ~/.claude.json。密钥用环境变量引用,别写死:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

`.claude/` 目录里的东西

这才是项目专属配置的主场。大部分文件都该提交给团队共享,个别(如 settings.local.json)会被自动 gitignore。

路径	作用	何时加载	git
`settings.json`	权限、钩子、配置	覆盖全局 settings;被 local/CLI/managed 覆盖	提交
`settings.local.json`	你个人的设置覆盖	用户可编辑层里最高优先	gitignore
`rules/`	按主题拆分的指令,可按文件路径触发	无 `paths:` 开局载入;有 `paths:` 命中文件才载入	提交
`skills/`	你或 Claude 按名字调用的可复用流程	`/skill-name` 或 Claude 匹配任务时	提交
`commands/`	单文件 prompt,用 `/name` 调用	输入 `/command-name` 时	提交
`output-styles/`	团队共享的输出风格(如有)	会话开始、被选中时	提交
`agents/`	有独立上下文窗口的子代理	被调用时在独立窗口运行	提交
`agent-memory/`	子代理的持久记忆	子代理运行时载入其 MEMORY.md	提交

几个要点:

settings.json 是"强制",不是"建议"。CLAUDE.md / rules 是 Claude 读的指引,会不会照做不保证;而 settings.json 里的 permissions、hooks 是 Claude Code 执行的,拦就是拦。比如下面这段:允许 npm test/npm run、禁止 rm -rf、编辑后自动跑 Prettier:

{
  "permissions": {
    "allow": ["Bash(npm test *)", "Bash(npm run *)"],
    "deny": ["Bash(rm -rf *)"]
  },
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
    }]
  }
}

rules/ 是 CLAUDE.md 的"减负工具"。当 CLAUDE.md 接近 200 行,就把内容拆成主题文件。带 paths: 的 rule 只在 Claude 读到匹配文件时才载入,省上下文:

---
paths:
  - "**/*.test.ts"
---
# Testing Rules
- 测试名要描述清楚："should [预期] when [条件]"
- 只 mock 外部依赖，不 mock 内部模块

skills/ 与 commands/ 现在是同一套机制。commands/deploy.md 产生 /deploy,和 skills/deploy/SKILL.md 等价;区别是 skill 用目录,能把参考文档、模板、脚本一起打包。新东西优先写成 skill。同名时 skill 优先。
agents/ 是子代理,每个 markdown 文件定义一个有独立上下文、独立工具权限的子代理,用 tools: 限制它能用哪些工具。它在新的上下文窗口跑,不污染主对话。

二、全局级:家目录 `~/`

这些是你个人的配置,对所有项目生效,永远不进任何仓库。

路径	作用	git
`~/.claude.json`	应用状态、UI 偏好、个人 MCP、各项目信任记录	本地
`~/.claude/CLAUDE.md`	跨所有项目的个人偏好	本地
`~/.claude/settings.json`	所有项目的默认设置	本地
`~/.claude/keybindings.json`	自定义快捷键	本地
`~/.claude/themes/`	自定义配色主题	本地
`~/.claude/projects/`	自动记忆:Claude 给自己记的笔记,按项目分	本地
`~/.claude/rules`、`skills`、`commands`、`agents` 等	与项目级同名,但作用于全局	本地

几个值得说的:

~/.claude.json vs ~/.claude/settings.json 别搞混。前者是应用状态(主题、OAuth 会话、IDE 开关 autoConnectIde、个人 MCP),主要通过 /config 管理;后者才是和项目 settings.json 同结构的设置(权限、钩子、model、env),作为你的默认值——项目级会覆盖这里的同名键。
全局 CLAUDE.md 会和项目 CLAUDE.md 同时进上下文,不是二选一。冲突时项目级优先。所以这里只放"放之四海皆准"的偏好(回复风格、commit 格式),并保持简短。
~/.claude/projects/ 是自动记忆(auto memory),默认开启。Claude 一边干活一边把构建命令、调试心得、架构笔记记下来,不用你写。每个项目一个目录,MEMORY.md 是索引(每次会话读前 200 行/25KB),太长时拆成 debugging.md 这类主题文件按需读取。这些都是纯 markdown,可随时编辑或删除。

# Memory Index
## Project
- [build-and-test.md](build-and-test.md): npm run build (~45s)，Vitest，dev 端口 3001
## Reference
- [debugging.md](debugging.md): 鉴权 token 轮换、数据库连接排查

个人快捷键 ~/.claude/keybindings.json,跑 /keybindings 生成;themes/ 里每个 .json 是一个自定义主题,/theme 创建。

三、两个最容易踩的"优先级"问题

.claude 体系里有两种完全不同的叠加逻辑,记混就会 debug 半天:

settings.json 是按键合并 + 覆盖:全局 → 项目 → local → CLI → managed,逐级覆盖同名键。数组类(如 permissions.allow)跨层合并,标量类(如 model)取最具体的值。
CLAUDE.md 是全部叠加进上下文:全局和项目的 CLAUDE.md 都会被读进来,不是覆盖,而是"都在场",冲突时 Claude 以更具体的项目级为准。

一句话区分:settings 是"配置合并",CLAUDE.md 是"上下文叠加"。

小结

把这套目录在脑子里建成两张表就清楚了:

项目级(跟仓库走、团队共享):CLAUDE.md 定约定,.claude/settings.json 定强制规则,skills/+commands/ 放可调用流程,rules/ 给 CLAUDE.md 减负,agents/ 放子代理,.mcp.json 连外部工具。
全局级(个人、所有项目生效、不提交):~/.claude/ 是项目级的镜像,外加 ~/.claude.json(应用状态)和 ~/.claude/projects/(自动记忆)。

需要"强制"的规则就写进 settings.json 的 hooks/permissions;需要"指引"的就写 CLAUDE.md 或 rules;需要"可复用流程"的就做成 skill。各归各位,.claude 目录自然不再是一团乱麻。

关于

关注我获取更多资讯

📢 公众号

💬 个人号