Claude Code .claude 目录详解 - CLAUDE.md / 设置 / Hooks 文件结构
Claude Code 读取 CLAUDE.md、settings.json、hooks、skills、commands、subagents、rules 和自动内存的位置。
Claude Code 读取 CLAUDE.md、settings.json、hooks、skills、commands、subagents、rules 和自动内存的位置。探索项目中的 .claude 目录和主目录中的 ~/.claude。
探索目录
.claude/ 目录在两个地方存在：
- 项目级：仓库根目录中的
.claude/，与团队共享并提交到 git - 用户级：主目录中的
~/.claude/，这是您的个人配置
每个文件根据其用途以不同的方式加载。请参阅官方文档获取浏览器中每个文件作用的详细解释、何时加载以及示例。
主要文件结构
your-project/
├── CLAUDE.md # 项目说明（每次会话都加载）
├── .mcp.json # 项目级 MCP 服务器
├── .worktreeinclude # 复制到新 worktrees 的 gitignored 文件
└── .claude/
├── CLAUDE.md # CLAUDE.md 的替代位置
├── settings.json # 项目设置（已提交）
├── settings.local.json # 个人覆盖（已 gitignored）
├── rules/*.md # 主题范围的规则
├── skills/<name>/SKILL.md # 可重用的提示
├── commands/*.md # 单文件提示（旧版机制）
├── output-styles/*.md # 自定义系统提示部分
├── agents/*.md # Subagent 定义
└── agent-memory/<name>/ # Subagents 的持久内存
~/.claude/ # 全局用户级
├── CLAUDE.md # 全局说明
├── settings.json # 全局设置
├── rules/*.md # 全局规则
├── skills/<name>/SKILL.md # 全局 skills
├── output-styles/*.md # 全局输出样式
├── agents/*.md # 全局 subagents
├── keybindings.json # 自定义快捷键
├── themes/*.json # 自定义颜色主题
├── projects/<project>/memory/ # 自动内存
└── ~/.claude.json # 应用状态、OAuth、个人 MCP 服务器
未显示的内容
浏览器涵盖您创作和编辑的文件。一些相关文件位于其他位置：
| 文件 | 位置 | 用途 |
|---|---|---|
managed-settings.json | 系统级别，因操作系统而异 | 企业强制执行的设置，您无法覆盖。请参阅服务器管理的设置 |
CLAUDE.local.md | 项目根目录 | 您对此项目的私人偏好，与 CLAUDE.md 一起加载。手动创建它并将其添加到 .gitignore |
| 已安装的 plugins | ~/.claude/plugins | 克隆的市场、已安装的 plugin 版本和每个 plugin 的数据，由 claude plugin 命令管理。孤立版本在 plugin 更新或卸载后 7 天被删除 |
~/.claude 还保存 Claude Code 在您工作时写入的数据：记录、提示历史、文件快照、缓存和日志。请参阅下面的应用数据。
选择正确的文件
不同类型的自定义位于不同的文件中。使用此表找到更改应该放在哪里。
| 您想要 | 编辑 | 范围 | 参考 |
|---|---|---|---|
| 为 Claude 提供项目上下文和约定 | CLAUDE.md | 项目或全局 | 内存 |
| 允许或阻止特定工具调用 | settings.json permissions 或 hooks | 项目或全局 | 权限 |
| 在工具调用前后运行脚本 | settings.json hooks | 项目或全局 | Hooks |
| 为会话设置环境变量 | settings.json env | 项目或全局 | 设置 |
| 将个人覆盖保留在 git 之外 | settings.local.json | 仅项目 | 设置范围 |
添加使用 /name 调用的提示或功能 | skills/<name>/SKILL.md | 项目或全局 | Skills |
| 定义具有自己工具的专门 subagent | agents/*.md | 项目或全局 | Subagents |
| 通过 MCP 连接外部工具 | .mcp.json | 仅项目 | MCP |
| 更改 Claude 格式化响应的方式 | output-styles/*.md | 项目或全局 | 输出样式 |
文件参考
此表列出浏览器涵盖的每个文件。项目范围的文件位于您的仓库中的 .claude/ 下（或 CLAUDE.md、.mcp.json 和 .worktreeinclude 的根目录）。全局范围的文件位于 ~/.claude/ 中，适用于所有项目。
ℹ️ 有几件事可以覆盖您在这些文件中放入的内容：
- 您的组织部署的托管设置优先于所有内容
- CLI 标志（如
--permission-mode或--settings）在该会话中覆盖settings.json- 某些环境变量优先于其等效设置，但这会有所不同：检查环境变量参考以了解每个变量
请参阅设置优先级以了解完整顺序。
| 文件 | 范围 | 提交 | 作用 | 参考 |
|---|---|---|---|---|
CLAUDE.md | 项目和全局 | ✓ | 每个会话加载的指令 | 内存 |
rules/*.md | 项目和全局 | ✓ | 主题范围的指令，可选择路径门控 | Rules |
settings.json | 项目和全局 | ✓ | 权限、hooks、环境变量、模型默认值 | 设置 |
settings.local.json | 仅项目 | 您的个人覆盖，自动 gitignored | 设置范围 | |
.mcp.json | 仅项目 | ✓ | 团队共享的 MCP 服务器 | MCP 范围 |
.worktreeinclude | 仅项目 | ✓ | Gitignored 文件以复制到新的 worktrees | Worktrees |
skills/<name>/SKILL.md | 项目和全局 | ✓ | 可重用的提示，使用 /name 调用或自动调用 | Skills |
commands/*.md | 项目和全局 | ✓ | 单文件提示；与 skills 相同的机制 | Skills |
output-styles/*.md | 项目和全局 | ✓ | 自定义系统提示部分 | 输出样式 |
agents/*.md | 项目和全局 | ✓ | Subagent 定义及其自己的提示和工具 | Subagents |
agent-memory/<name>/ | 项目和全局 | ✓ | Subagents 的持久内存 | 持久内存 |
~/.claude.json | 仅全局 | 应用状态、OAuth、UI 切换、个人 MCP 服务器 | 全局配置 | |
projects/<project>/memory/ | 仅全局 | 自动内存：Claude 在会话间对自己的笔记 | 自动内存 | |
keybindings.json | 仅全局 | 自定义快捷键 | 快捷键 | |
themes/*.json | 仅全局 | 自定义颜色主题 | 自定义主题 |
排查配置问题
如果设置、hook 或文件未生效，请参阅”调试您的配置”以获取检查命令和症状优先查找表。
应用数据
除了您创作的配置外，~/.claude 还保存 Claude Code 在会话期间写入的数据。这些文件是纯文本。通过工具传递的任何内容都会在磁盘上的记录中：文件内容、命令输出、粘贴的文本。
自动清理
下面路径中的文件在启动时被删除，一旦它们的年龄超过 cleanupPeriodDays。默认值为 30 天。
~/.claude/ 下的路径 | 内容 |
|---|---|
projects/<project>/<session>.jsonl | 完整的对话记录：每条消息、工具调用和工具结果 |
projects/<project>/<session>/tool-results/ | 大型工具输出溢出到单独的文件 |
file-history/<session>/ | Claude 更改的文件的编辑前快照，用于检查点恢复 |
plans/ | 在计划模式期间写入的计划文件 |
debug/ | 每个会话的调试日志，仅在您使用 --debug 启动或运行 /debug 时写入 |
paste-cache/、image-cache/ | 大型粘贴和附加图像的内容 |
session-env/ | 每个会话的环境元数据 |
tasks/ | 由任务工具写入的每个会话的任务列表 |
shell-snapshots/ | 由 Bash 工具使用的捕获的 shell 环境。在正常退出时删除。扫描清理任何在崩溃后留下的内容 |
backups/ | 在配置迁移前获取的 ~/.claude.json 的时间戳副本 |
保留直到您删除它们
以下路径不受自动清理覆盖，并无限期保留。
~/.claude/ 下的路径 | 内容 |
|---|---|
history.jsonl | 您输入的每个提示，带有时间戳和项目路径。用于向上箭头回忆 |
stats-cache.json | 由 /usage 显示的聚合令牌和成本计数 |
todos/ | 旧版每个会话的任务列表。不再由当前版本写入；可以安全删除 |
其他小缓存和锁定文件根据您使用的功能而出现，可以安全删除。
纯文本存储
记录和历史在静止时未加密。操作系统文件权限是唯一的保护。如果工具读取 .env 文件或命令打印凭证，该值将写入 projects/<project>/<session>.jsonl。要减少暴露：
- 降低
cleanupPeriodDays以缩短记录的保留时间 - 设置
CLAUDE_CODE_SKIP_PROMPT_HISTORY环境变量以跳过在任何模式下写入记录和提示历史。在非交互模式下，您可以改为在-p旁边传递--no-session-persistence，或在 Agent SDK 中设置persistSession: false - 使用权限规则拒绝读取凭证文件
清除本地数据
运行 claude project purge 以删除 Claude Code 为一个项目保存的状态：
projects/下的记录和自动内存- 每个会话的
tasks/、debug/和file-history/条目 history.jsonl中的匹配提示行~/.claude.json中的项目条目
该命令打印完整的删除计划，并在删除任何内容之前要求确认。
预览计划而不删除任何内容：
claude project purge ~/work/my-repo --dry-run
通过单个确认提示删除：
claude project purge ~/work/my-repo
省略路径以从交互式列表中选择项目。
跳过确认提示以在脚本中使用：
claude project purge ~/work/my-repo --yes
传递 --all 而不是路径以一次清除所有项目的状态，这会直接删除 history.jsonl 而不是过滤它。传递 -i 以逐项逐步执行删除计划。
该命令不理会 shell-snapshots/ 和 backups/，因为这些不是项目范围的，并在计划输出中警告它们。如果没有状态与给定路径匹配，它以状态 1 退出。
您也可以手动删除上面的任何应用数据路径。新会话不受影响。下表显示您对过去会话失去的内容。
| 删除 | 您失去 |
|---|---|
~/.claude/projects/ | 恢复、继续和倒回过去的会话 |
~/.claude/history.jsonl | 向上箭头提示回忆 |
~/.claude/file-history/ | 过去会话的检查点恢复 |
~/.claude/stats-cache.json | 由 /usage 显示的历史总计 |
~/.claude/debug/、~/.claude/plans/、~/.claude/paste-cache/、~/.claude/image-cache/、~/.claude/session-env/、~/.claude/tasks/、~/.claude/shell-snapshots/、~/.claude/backups/ | 没有面向用户的内容 |
~/.claude/todos/ | 没有。旧版目录不由当前版本写入 |
不要删除 ~/.claude.json、~/.claude/settings.json 或 ~/.claude/plugins/：这些保存您的身份验证、偏好和已安装的 plugins。
相关资源
- 管理 Claude 的内存：编写和组织 CLAUDE.md、rules 和自动内存
- 配置设置：设置权限、hooks、环境变量和模型默认值
- 创建 skills：构建可重用的提示和工作流
- 配置 subagents：定义具有自己上下文的专门代理
本文翻译自 Anthropic Claude Code 官方文档，最近一次同步：2025-05-01。