.claude 目录详解

Claude Code 在项目与 ~/.claude 中读取配置、规则、技能、子代理与自动记忆的目录。

是什么

.claude 是 Claude Code 读取项目专属与个人配置的目录体系，分两层：项目层（仓库内 .claude/，外加根目录的 CLAUDE.md、.mcp.json、.worktreeinclude）和全局层（家目录 ~/.claude/ 与 ~/.claude.json，对所有项目生效且永不提交）。它涵盖你亲手编写、可提交给团队共享的文件（如 CLAUDE.md、settings.json、skills、agents），以及 Claude 自动写入的数据（自动记忆、会话记录、快照等）。区分两类内容：CLAUDE.md 与 rules 是 Claude 阅读的「指引」（不强制），settings.json 的 permissions/hooks 是 Claude Code 直接「执行/强制」的配置，无论 Claude 是否遵守都会生效。

怎么工作

项目 CLAUDE.md 与全局 ~/.claude/CLAUDE.md 在每次会话开始时一起加载进上下文；指令冲突时项目级优先。建议控制在 200 行内。
settings.json 按 key 合并并有优先级：全局 < 项目 settings.json < 项目 settings.local.json < CLI flags < 企业 managed-settings。数组类（如 permissions.allow）跨作用域合并，标量类（如 model）取最具体值。
rules/ 中无 paths: 前置元数据的规则在会话开始加载（类似 CLAUDE.md）；带 paths: glob 的规则仅当 Claude 读到匹配文件时才加载；子目录会被自动发现。
skills/<name>/SKILL.md 与 commands/*.md 都通过 /name 调用、也都可被 Claude 自动调用；同名时 skill 优先；技能可在目录内捆绑参考文档、模板、脚本。
agents/*.md 定义子代理，运行在独立上下文窗口，可用 tools: 限制工具、description 决定 Claude 何时自动委派。
自动记忆（~/.claude/projects/<project>/memory/）由 Claude 自行写入维护，MEMORY.md 作为索引在会话开始加载（前 200 行或 25KB，先到为准），主题文件按需读取；默认开启，可用 /memory 切换。
子代理记忆按 frontmatter 的 memory: 字段分流：project 写入 .claude/agent-memory/、local 写入 .claude/agent-memory-local/、user 写入 ~/.claude/agent-memory/，与主会话自动记忆相互独立。
~/.claude 还保存 Claude 工作时写入的明文数据（transcripts、history、快照、缓存、日志）；部分按 cleanupPeriodDays（默认 30 天）自动清理，部分需手动删除。

怎么配置 / 用法

your-project/
├── CLAUDE.md              # 每次会话加载的项目指令（也可放 .claude/CLAUDE.md）
├── CLAUDE.local.md        # 个人私有偏好，需手动建并加入 .gitignore
├── .mcp.json             # 团队共享的项目级 MCP 服务器（位于项目根，非 .claude/）
├── .worktreeinclude      # 拷入新 worktree 的 gitignored 文件清单（项目根）
└── .claude/
    ├── settings.json          # 权限/hooks/statusLine/model/env/outputStyle（committed）
    ├── settings.local.json    # 个人覆盖，自动 gitignored
    ├── rules/*.md             # 主题指令，可用 paths: 按文件路径门控
    ├── skills/<name>/SKILL.md # /name 调用的技能（可捆绑 checklist.md 等）
    ├── commands/*.md          # 单文件 /name 命令（新工作流建议改用 skills）
    ├── output-styles/*.md     # 项目级输出风格（通常放全局）
    ├── agents/*.md            # 子代理定义（独立上下文/工具）
    ├── workflows/*.js         # 动态工作流脚本，每个文件成为 /<name>
    └── agent-memory/<agent>/MEMORY.md  # 子代理持久记忆（Claude 自写）

~/
├── .claude.json          # 应用状态/OAuth/UI 开关/个人 MCP 服务器（local）
└── .claude/
    ├── CLAUDE.md              # 跨所有项目的个人偏好
    ├── settings.json          # 所有项目的默认设置
    ├── keybindings.json       # 自定义快捷键（/keybindings 生成）
    ├── themes/*.json          # 自定义配色主题（/theme）
    ├── rules/  skills/  commands/  output-styles/  agents/  workflows/  # 个人级
    ├── agent-memory/          # memory: user 的子代理跨项目记忆
    └── projects/<project>/memory/MEMORY.md  # 自动记忆：Claude 跨会话自记笔记

# 系统级（不在用户目录）：managed-settings.json 企业强制，优先级最高

什么时候用

给 Claude 项目上下文与约定 → 写 CLAUDE.md（项目或全局）。
允许/拦截特定工具调用，或在工具调用前后跑脚本 → 改 settings.json 的 permissions 或 hooks。
保留个人覆盖且不进 git → 用项目 settings.local.json。
新增可用 /name 调用的提示或能力 → 建 skills/<name>/SKILL.md；定义带专属工具的子代理 → agents/*.md。
连接外部 MCP 工具（团队共享）→ 项目根 .mcp.json；仅自己用 → claude mcp add --scope user 写入 ~/.claude.json。

限制 / 坑

CLAUDE.md 与 rules 只是 Claude 阅读的指引、不强制；要保证行为请用 hooks 或 permissions。
.worktreeinclude 仅对 git 生效；若为其他 VCS 配了 WorktreeCreate hook，则该文件不被读取，需在脚本里自行拷贝。
transcripts 与 history 明文存储、未加密，仅靠操作系统文件权限保护；工具读到的 .env 或打印的凭据会写入会话 jsonl。
会话数据有清理边界：部分路径超过 cleanupPeriodDays（默认 30 天）自启动时删除，history.jsonl/stats-cache.json 等则保留至手动删除。
Ctrl+C、Ctrl+D、Ctrl+M、Caps Lock 为保留键，无法在 keybindings.json 中重绑。

硬事实速查（21 条）

CLAUDE.md（项目根或 .claude/）：每次会话加载的项目指令，建议 <200 行，可用 /memory 编辑
CLAUDE.local.md（项目根）：个人私有偏好，需手动创建并加入 .gitignore
~/.claude/CLAUDE.md：跨所有项目的个人偏好，与项目 CLAUDE.md 同时加载，冲突时项目级优先
.mcp.json（项目根）：团队共享的项目级 MCP 服务器，秘钥用 ${ENV} 引用
.worktreeinclude（项目根）：列出要拷入新 worktree 的 gitignored 文件（.gitignore 语法）
settings.json（.claude/）：permissions/hooks/statusLine/model/env/outputStyle，Claude Code 直接强制执行
settings.local.json（.claude/）：个人覆盖，自动 gitignored，schema 同 settings.json
rules/*.md（.claude/）：主题指令，带 paths: glob 时按文件路径条件加载
skills/<name>/SKILL.md（.claude/）：/name 调用的可复用提示，可捆绑支持文件，frontmatter 控制调用方式
commands/*.md（.claude/）：单文件 /name 命令，与 skills 同机制，同名时 skill 优先
output-styles/*.md：追加到系统提示的自定义风格，默认会去掉内置编码指令
agents/*.md（.claude/）：子代理定义，独立上下文窗口，tools: 限工具、description 决定自动委派
workflows/*.js（.claude/）：动态工作流脚本，由 /workflows 保存，每个文件成为 /<name>
~/.claude.json：应用状态/OAuth/per-project trust/UI 开关/个人 MCP，主要经 /config 管理
~/.claude/keybindings.json：自定义快捷键，/keybindings 生成，热重载
~/.claude/themes/*.json：自定义配色主题，base 预设+overrides，/theme 创建
~/.claude/projects/<project>/memory/MEMORY.md：自动记忆索引，Claude 自写，会话开始加载前 200 行/25KB
~/.claude/agent-memory/：memory:user 子代理的跨项目持久记忆
managed-settings.json（系统级）：企业强制设置，优先级高于一切
~/.claude/projects/<project>/<session>.jsonl：完整会话 transcript，按 cleanupPeriodDays 清理
~/.claude/history.jsonl：所有输入过的 prompt，用于上箭头召回，保留至手动删除

官方出处：https://code.claude.com/docs/en/claude-directory

.claude 目录详解 ​

是什么 ​

怎么工作 ​

怎么配置 / 用法 ​

什么时候用 ​

限制 / 坑 ​