Claude Code .claude 目录结构完整参考

本页目录24

AI 摘要 · 待复核整理于 2026-06-23原文:Explore the .claude directory(Anthropic)Claude Code目录结构配置参考开发工具

要点速览

`.claude/` 目录分为项目级（纳入版本控制）和全局级（`~/.claude/`），相同配置项在两处均有效
`settings.json` 有四个作用域：Managed > 命令行参数 > Local > Project > User，高优先级覆盖低优先级
`CLAUDE.md` 支持 `@path/to/import` 导入语法，`CLAUDE.local.md` 为个人本地指令（gitignored）
Hook 共 30+ 种事件（`PreToolUse`、`Stop`、`SessionStart` 等），支持 command / http / mcp_tool / prompt / agent 五种 handler 类型
Skills 新格式为 `.claude/skills/<name>/SKILL.md`，旧格式 `.claude/commands/<name>.md` 仍兼容，两者均以 `/name` 调用
自动记忆存储于 `~/.claude/projects/<project>/memory/`，`MEMORY.md` 前 200 行或 25KB 在每次会话开始时自动加载

本文是对官方「Explore the .claude directory」参考页的中文整理，完整与最新内容以原文为准：https://code.claude.com/docs/en/claude-directory

概览

.claude 目录是 Claude Code 的配置中心，分为项目级（your-project/.claude/）和全局级（~/.claude/）两个作用域。官方页面以交互式文件树（ClaudeExplorer 组件）呈现全部配置项，涵盖：CLAUDE.md、settings.json、hooks、skills、commands、subagents、workflows、rules、auto memory。

目录结构速览

项目级（`your-project/`）

路径	badge	加载时机	说明
`CLAUDE.md`	committed	每次会话启动时（完整加载）	项目指令，团队共享；可用 `@path` 导入其他文件
`CLAUDE.local.md`	gitignored	每次会话启动时	个人项目本地指令，需加入 `.gitignore`
`.claude/settings.json`	committed	会话启动时	项目级配置，可提交 Git
`.claude/settings.local.json`	gitignored	会话启动时	本地覆盖配置，不提交
`.claude/hooks/`（或在 `settings.json` 中配置）	committed	事件触发时	Hook 脚本（也可在 `settings.json` 的 `hooks` 字段中配置）
`.claude/skills/<name>/SKILL.md`	committed	`/name` 调用或 Claude 自动判断相关时	自定义技能（新格式）
`.claude/commands/<name>.md`	committed	同 `skills/`（旧格式，仍兼容）	旧版命令目录，等效于 `skills/`
`.claude/agents/<name>.md`	committed	Claude 判断任务匹配时	自定义子代理定义
`.claude/workflows/<name>.js`	committed	`/name` 调用时	可复用的动态工作流脚本
`.claude/rules/*.md`	committed	通用规则：会话启动时；路径限定规则：打开匹配文件时	模块化规则文件，支持 YAML frontmatter `paths` 字段
`.claude/memory/`	gitignored	`MEMORY.md` 前 200 行或 25KB 在会话启动时加载	自动记忆存储目录

全局级（`~/.claude/`）

路径	说明
`~/.claude/CLAUDE.md`	个人全局指令，对所有项目生效
`~/.claude/settings.json`	全局配置（User 作用域）
`~/.claude/hooks/`	全局 Hook
`~/.claude/skills/`	全局技能
`~/.claude/commands/`	全局旧版命令
`~/.claude/agents/`	全局子代理
`~/.claude/workflows/`	全局工作流脚本
`~/.claude/rules/`	全局规则（在所有项目中应用个人偏好）
`~/.claude/projects/<project>/memory/`	按项目存储的自动记忆（路径由 git 仓库路径派生）

CLAUDE.md 位置与作用域

加载顺序：从文件系统根向工作目录遍历，宽作用域先于窄作用域；同目录内 CLAUDE.local.md 附加在 CLAUDE.md 之后。

作用域	路径	用途	共享对象
托管策略（Managed）	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br>Linux/WSL: `/etc/claude-code/CLAUDE.md`<br>Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`	组织级全局指令，IT 统一管理，不可被排除	机器上所有用户
用户级（User）	`~/.claude/CLAUDE.md`	个人偏好，适用所有项目	仅自己（所有项目）
项目级（Project）	`./CLAUDE.md` 或 `./.claude/CLAUDE.md`	团队共享项目指令，通过版本控制分发	通过 Git 共享
本地级（Local）	`./CLAUDE.local.md`	个人项目偏好，加入 `.gitignore`	仅自己（当前项目）

@import 导入语法

CLAUDE.md 内用 @path/to/file 导入额外文件，导入内容在会话启动时展开。

支持相对路径（相对于包含导入的文件）和绝对路径
支持递归导入，最多 4 层
用反引号包裹（如 `@README`）则不触发导入，保留为字面文本
Block 级 HTML 注释（）在注入上下文前被剥离，不消耗 token

托管策略中内嵌 CLAUDE.md

可将 CLAUDE.md 内容直接写入 managed-settings.json 的 claudeMd 字段，无需单独部署文件：

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

排除特定 CLAUDE.md

在 .claude/settings.local.json 中设置 claudeMdExcludes，使用 glob 匹配绝对路径：

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

托管策略的 CLAUDE.md 不可被排除。

.claude/rules/ 路径限定规则

frontmatter 字段	类型	说明
`paths`	array	glob 模式列表；无此字段则对所有文件通用加载

glob 示例	匹配范围
`*/.ts`	任意目录下的 TypeScript 文件
`src/*/`	`src/` 下所有文件
`*.md`	项目根目录的 Markdown 文件
`src/components/*.tsx`	特定目录下的 React 组件

用户级规则位于 ~/.claude/rules/，先于项目级规则加载（项目规则优先级更高）。

settings.json 字段参考

配置文件路径与作用域

作用域	路径	是否团队共享
User	`~/.claude/settings.json`	否
Project	`.claude/settings.json`	是（可提交 Git）
Local	`.claude/settings.local.json`	否（gitignored）
Managed	系统级（plist/registry/`managed-settings.json`）	是（IT 部署）

优先级（高 → 低）：Managed → 命令行参数 → Local → Project → User

字段列表

字段名	类型	默认值	说明
`advisorModel`	string	未设置	服务端 advisor 工具使用的模型
`agent`	string	未设置	将主线程作为指定子代理运行
`agentPushNotifEnabled`	boolean	`false`	允许主动推送通知（Remote Control）
`allowAllClaudeAiMcps`	boolean	未设置	使用托管 MCP 配置时加载 claude.ai 连接器
`alwaysThinkingEnabled`	boolean	未设置	默认启用扩展思考
`autoCompactEnabled`	boolean	`true`	上下文达限制时自动压缩
`autoMemoryEnabled`	boolean	`true`	启用自动记忆
`autoMemoryDirectory`	string	未设置	自动记忆的自定义存储路径（绝对路径或 `~/` 开头）
`autoScrollEnabled`	boolean	`true`	全屏渲染时跟随新输出
`autoUpdatesChannel`	string	`"latest"`	更新渠道：`"stable"` 或 `"latest"`
`awaySummaryEnabled`	boolean	`true`	返回时显示离开期间的会话摘要
`axScreenReader`	boolean	未设置	渲染屏幕阅读器友好的输出
`cleanupPeriodDays`	number	`30`	会话文件保留天数
`claudeMd`	string	未设置	将 CLAUDE.md 内容直接嵌入 managed-settings.json（仅 managed 作用域生效）
`claudeMdExcludes`	array	未设置	排除特定 CLAUDE.md 文件（glob 匹配绝对路径），可跨层合并
`disableAgentView`	boolean	未设置	禁用后台代理和代理视图
`disableAllHooks`	boolean	未设置	禁用所有 Hook 和自定义状态栏
`disableArtifact`	boolean	未设置	禁用 Artifact 工具
`disableAutoMode`	string	未设置	阻止 auto mode 激活
`disableBundledSkills`	boolean	未设置	禁用内置技能和工作流
`disableClaudeAiConnectors`	boolean	未设置	禁用 claude.ai MCP 连接器
`disableRemoteControl`	boolean	未设置	禁用 Remote Control 功能
`disableWorkflows`	boolean	`false`	禁用动态工作流
`editorMode`	string	`"normal"`	键位绑定：`"normal"` 或 `"vim"`
`effortLevel`	string	未设置	推理强度：`"low"` / `"medium"` / `"high"` / `"xhigh"`
`env`	object	`{}`	所有会话的环境变量
`fileCheckpointingEnabled`	boolean	`true`	编辑前快照文件（支持 `/rewind`）
`forceLoginMethod`	string	未设置	限制登录方式：`"claudeai"` 或 `"console"`
`language`	string	未设置	首选回复语言
`model`	string	未设置	Claude Code 默认模型
`outputStyle`	string	未设置	输出风格调整
`permissions.allow`	array	未设置	允许的操作（权限规则列表）
`permissions.deny`	array	未设置	拒绝的操作（权限规则列表）
`preferredNotifChannel`	string	`"auto"`	通知方式
`respectGitignore`	boolean	`true`	文件选择器遵守 `.gitignore`

注：官方文档记录了 100+ 个字段，上表为最常用字段。完整列表以原文为准。

Hook 事件参考

Hook 配置于 settings.json（或 settings.local.json、managed settings、插件 hooks/hooks.json）的 hooks 字段下。

所有事件名

事件名	触发时机
`SessionStart`	新会话启动或恢复时
`Setup`	`--init-only` 或 `--init`/`--maintenance` 模式时
`UserPromptSubmit`	用户提交 prompt 时
`UserPromptExpansion`	用户命令展开为 prompt 时
`PreToolUse`	工具执行前
`PermissionRequest`	出现权限对话框时
`PermissionDenied`	auto mode 拒绝工具时
`PostToolUse`	工具成功执行后
`PostToolUseFailure`	工具执行失败后
`PostToolBatch`	并行工具调用全部完成后
`Stop`	Claude 完成响应时
`SubagentStart`	子代理启动时
`SubagentStop`	子代理完成时
`TaskCreated`	`TaskCreate` 创建任务时
`TaskCompleted`	任务标记完成时
`TeammateIdle`	团队代理即将空闲时
`Notification`	发送通知时
`MessageDisplay`	助手文本显示时
`ConfigChange`	会话期间配置文件变更时
`CwdChanged`	工作目录变更时
`FileChanged`	被监视文件在磁盘上变更时
`PreCompact`	上下文压缩前
`PostCompact`	上下文压缩后
`WorktreeCreate`	worktree 创建时
`WorktreeRemove`	worktree 删除时
`Elicitation`	MCP 服务器请求用户输入时
`ElicitationResult`	用户响应 MCP 输入时
`InstructionsLoaded`	CLAUDE.md 或规则文件加载时
`SessionEnd`	会话终止时
`StopFailure`	因 API 错误结束时（非阻塞）

Handler 类型

`type` 值	描述
`"command"`	stdin/stdout 上的 shell 脚本
`"http"`	HTTP POST 到指定端点
`"mcp_tool"`	调用 MCP 服务器工具
`"prompt"`	单轮 LLM 评估
`"agent"`	带工具的子代理（实验性）

Matcher 模式规则

模式类型	匹配规则	示例
`"*"` 或省略	匹配所有工具/事件	任意触发
仅含字母/数字/下划线/竖线	精确字符串列表	`Bash`、`Edit\|Write`
含其他字符	正则表达式	`^Notebook`、`mcp__memory__.*`

常用输出字段

字段	用途
`decision: "block"`	阻止该操作（大多数事件）
`hookSpecificOutput`	事件特定控制（权限、重写等）
`additionalContext`	向 Claude 传递上下文
`systemMessage`	向用户显示警告信息
`terminalSequence`	桌面通知/窗口标题
退出码 `0`	成功（解析 JSON 输出）
退出码 `2`	阻塞性错误（显示 stderr）
其他退出码	非阻塞错误

路径占位符

占位符	含义
`${CLAUDE_PROJECT_DIR}`	项目根目录
`${CLAUDE_PLUGIN_ROOT}`	插件安装目录
`${CLAUDE_PLUGIN_DATA}`	插件持久化数据目录

Skills（技能）与 Commands（命令）

Commands 和 skills 现已合并为同一机制。新工作流建议使用 skills/ 格式（相同的 /name 调用方式，且可附带支持文件）。旧版 .claude/commands/ 仍完全兼容。

路径	作用域	格式	调用方式
`.claude/skills/<name>/SKILL.md`	项目级（新格式）	目录 + `SKILL.md`	`/name` 或 Claude 自动
`.claude/commands/<name>.md`	项目级（旧格式，兼容）	单文件 `.md`	`/name`
`~/.claude/skills/<name>/SKILL.md`	全局用户级（新格式）	目录 + `SKILL.md`	`/name`
`~/.claude/commands/<name>.md`	全局用户级（旧格式）	单文件 `.md`	`/name`

Subagents（子代理）

每个子代理在独立上下文窗口中运行，拥有自定义系统提示、指定工具访问权限和独立权限控制。

路径	作用域
`.claude/agents/<name>.md`	项目级
`~/.claude/agents/<name>.md`	全局用户级

Workflows（动态工作流）

工作流脚本以 JavaScript 编写，由 Claude 自动生成后可保存复用。

路径	作用域	说明
`.claude/workflows/<name>.js`	项目级，团队共享	通过 Git 提交分发
`~/.claude/workflows/<name>.js`	全局用户级	个人专用，所有项目可用

调用方式：/name（保存后自动出现在 / 自动补全中）
内置工作流：/deep-research <question> — 多角度并行搜索，交叉核实来源，返回带引用的报告
禁用方式："disableWorkflows": true（settings.json）或 CLAUDE_CODE_DISABLE_WORKFLOWS=1（环境变量）

自动记忆（Auto Memory）

需要 Claude Code v2.1.59 或更高版本。

路径	说明
`~/.claude/projects/<project>/memory/MEMORY.md`	记忆索引，每次会话加载前 200 行或 25KB（以先到为准）
`~/.claude/projects/<project>/memory/*.md`	主题记忆文件（如 `debugging.md`），按需加载

<project> 由 git 仓库路径派生；同仓库所有 worktree 和子目录共享同一记忆目录
非 git 目录时，以项目根目录作为 key
自动记忆为本机存储，不跨机器或云环境同步

主题	文档页
settings.json 完整字段	`/en/settings`
Hook 完整参考	`/en/hooks`
CLAUDE.md 与自动记忆	`/en/memory`
Skills 完整参考	`/en/skills`
子代理完整参考	`/en/sub-agents`
动态工作流完整参考	`/en/workflows`
配置调试	`/en/debug-your-config`

Claude Code .claude 目录结构完整参考

概览

目录结构速览

项目级（`your-project/`）

全局级（`~/.claude/`）

CLAUDE.md 位置与作用域

@import 导入语法

托管策略中内嵌 CLAUDE.md

排除特定 CLAUDE.md

.claude/rules/ 路径限定规则

settings.json 字段参考

配置文件路径与作用域

字段列表

Hook 事件参考

所有事件名

Handler 类型

Matcher 模式规则

常用输出字段

路径占位符

Skills（技能）与 Commands（命令）

Subagents（子代理）

Workflows（动态工作流）

自动记忆（Auto Memory）

相关设置

相关文档链接

设置项	类型	说明
`autoMemoryEnabled`	boolean	启用/禁用自动记忆（默认 `true`）
`autoMemoryDirectory`	string	自定义存储路径（绝对路径或 `~/` 开头）

概览

目录结构速览

项目级（your-project/）

全局级（~/.claude/）

CLAUDE.md 位置与作用域

@import 导入语法

托管策略中内嵌 CLAUDE.md

排除特定 CLAUDE.md

.claude/rules/ 路径限定规则

settings.json 字段参考

配置文件路径与作用域

字段列表

Hook 事件参考

所有事件名

Handler 类型

Matcher 模式规则

常用输出字段

路径占位符

Skills（技能）与 Commands（命令）

Subagents（子代理）

Workflows（动态工作流）

自动记忆（Auto Memory）

相关设置

相关文档链接

项目级（`your-project/`）

全局级（`~/.claude/`）