.claude 目录详解

项目里的 .claude 与 ~/.claude 各放什么、何时加载：文件速查、按需求选文件、frontmatter 字段、会话产生的本地数据与保留期、纯文本存储风险、claude project purge。

Claude Code 从项目里的 .claude/（以及根目录的 CLAUDE.md、.mcp.json、.worktreeinclude）和你主目录下的 ~/.claude/ 读取指令、设置、hooks、skills、子智能体、工作流、规则和自动记忆。项目级文件提交进仓库与团队共享，全局级文件对你所有项目生效。官方页面有一个可点击的文件树交互展示，这里整理成文字。

官方没放进文件树的几个文件

文件	位置	作用
`managed-settings.json`	系统级，因操作系统而异	企业强制设置，你无法覆盖（极少数例外）
`CLAUDE.local.md`	项目根目录	你对该项目的私人偏好，与 CLAUDE.md 一起加载；需手动创建并加进 `.gitignore`
`AGENTS.md`	项目根、`.claude/` 或任意目录	写给 AI 编码智能体的项目说明，Claude Code 可单独或与 `CLAUDE.md` 一起加载
已安装的插件	`~/.claude/plugins`	克隆的插件市场、已安装插件版本、`installed_plugins.json` 安装记录和各插件数据，由 `claude plugin` 命令管理

该改哪个文件

你想要	编辑	范围
给 Claude 项目上下文和约定	`CLAUDE.md`	项目或全局
允许或阻止某些工具调用	`settings.json` 的 `permissions` 或 `hooks`	项目或全局
在工具调用前后运行脚本	`settings.json` 的 `hooks`	项目或全局
为会话设置环境变量	`settings.json` 的 `env`	项目或全局
让个人覆盖项不进 git	`settings.local.json`	仅项目
添加用 `/name` 调用的提示或能力	`skills/<name>/SKILL.md`	项目或全局
定义有自己工具的专用子智能体	`agents/*.md`	项目或全局
用脚本编排很多子智能体	`workflows/*.js`	项目或全局
通过 MCP 连接外部工具	`.mcp.json`	仅项目
改变 Claude 回复的格式	`output-styles/*.md`	项目或全局

文件速查

项目级文件在仓库的 .claude/ 下（CLAUDE.md、.mcp.json、.worktreeinclude 在根目录），全局级在 ~/.claude/ 下。

文件	范围	提交	作用
`CLAUDE.md`	项目和全局	✓	每个会话加载的指令
`rules/*.md`	项目和全局	✓	按主题划分的指令，可按路径限定
`settings.json`	项目和全局	✓	权限、hooks、环境变量、模型默认值
`settings.local.json`	仅项目		你的个人覆盖，Claude Code 保存设置到这里时会被 gitignore
`.mcp.json`	仅项目	✓	团队共享的 MCP 服务器
`.worktreeinclude`	仅项目	✓	要复制进新 worktree 的、被 gitignore 的文件
`skills/<name>/SKILL.md`	项目和全局	✓	可复用提示，用 `/name` 调用或自动调用
`commands/*.md`	项目和全局	✓	单文件提示；与 skills 是同一机制（新工作流建议用 skills，可附带支持文件）
`output-styles/*.md`	项目和全局	✓	调整 Claude 工作方式的自定义指令集
`agents/*.md`	项目和全局	✓	有自己提示和工具的子智能体定义
`workflows/*.js`	项目和全局	✓	Claude 编写并从 `/workflows` 保存的动态工作流脚本，每个文件成为一个 `/<name>` 命令
`agent-memory/<name>/`	项目和全局	✓	子智能体的持久记忆
`~/.claude.json`	仅全局		应用状态、OAuth、UI 开关、个人 MCP 服务器
`projects/<project>/memory/`	仅全局		自动记忆：Claude 写给自己的跨会话笔记
`keybindings.json`	仅全局		自定义键盘快捷键
`themes/*.json`	仅全局		自定义颜色主题

有几样东西可以覆盖这些文件里写的内容：组织部署的托管设置优先于一切（极少数例外）；--permission-mode、--settings 等 CLI 标志在该会话内覆盖 settings.json；部分环境变量优先于对应的设置，因变量而异。

各文件的 frontmatter 字段

文件	字段
`skills/<name>/SKILL.md`	`name`、`description`、`when_to_use`、`argument-hint`、`arguments`、`disable-model-invocation`、`user-invocable`、`allowed-tools`、`disallowed-tools`、`model`、`effort`、`context`、`agent`、`background`、`hooks`、`paths`、`shell`、`metadata`、`license`、`compatibility`
`commands/*.md`	skill 的字段去掉 `name` 和 `paths`
`agents/*.md`	`name`、`description`、`tools`、`disallowedTools`、`model`、`permissionMode`、`maxTurns`、`skills`、`mcpServers`、`hooks`、`memory`、`background`、`effort`、`isolation`、`color`、`initialPrompt`、`omitClaudeMd`、`experimental`
`output-styles/*.md`	`name`、`description`、`keep-coding-instructions`、`force-for-plugin`
`rules/*.md`	`paths`

插件里自带的智能体只支持子智能体字段的一个子集。某个设置、hook 或文件没生效时，用官方的「Debug your configuration」页里的检查命令和按症状查找表。

应用数据

除了你编写的配置，~/.claude 还存放 Claude Code 在会话中写入的数据。这些文件是明文的：任何经过工具的内容，包括文件内容、命令输出、粘贴的文本，都会写进磁盘上的转录。

自动清理

超过 cleanupPeriodDays（默认 30 天，最小 1）的下列路径会被删除：

`~/.claude/` 下的路径	内容
`projects/<project>/<session>.jsonl`	完整对话转录：每条消息、工具调用和工具结果
`projects/<project>/<session>/subagents/`	子智能体对话转录，随父会话转录一起清理
`projects/<project>/<session>/tool-results/`	溢出到单独文件的大工具输出，以及 MCP 工具返回图片的完整副本
`file-history/<session>/`	Claude 修改过的文件的编辑前快照，用于检查点恢复（保留最近 100 个检查点）
`plans/`	计划模式下写的计划文件
`debug/`	开启调试日志时的每会话调试日志
`paste-cache/`	大段粘贴的内容
`uploads/<session>/`	从网页或手机 App 附加到 Remote Control 会话的文件
`session-env/`、`tasks/`、`shell-snapshots/`、`backups/`	会话环境元数据、任务列表、启动时捕获的 shell 别名/函数、`~/.claude.json` 的旧版本（保留最近 5 个）
`feedback-bundles/`、`feedback/drafts/`	`/feedback` 写出的脱敏转录包；待你审阅的 Claude 起草的反馈
`usage-data/`	`/insights` 写出的报告及缓存的分析数据

另有几类遵循自己的保留规则：sessions/（每个运行中会话一个小文件，会话退出时移除）、自动记忆（projects/<project>/memory/，清理不会删其中的记忆文件）、Claude Desktop 和 Cowork 转录（保留，除非设置 desktopSessionCleanupPeriodDays）。以下情形会跳过清理：claude -p --bare 模式；Claude Code 无法安全确定保留期时会暂停清理。

会话 scratchpad 目录

scratchpad 是 Claude Code 给 Claude 存放临时文件（中间结果、辅助脚本、不属于项目的草稿）的每会话目录，位于 Claude Code 的临时目录下，不在 ~/.claude：

macOS：/private/tmp/claude-<uid>/<project>/<session-id>/scratchpad/
Linux：/tmp/claude-<uid>/<project>/<session-id>/scratchpad/（系统设置了 $TMPDIR 时同形状放在它下面）
Windows：%TEMP%\claude\<project>\<session-id>\scratchpad\

<project> 是工作目录路径，把字母和数字以外的字符都替换为 -。设置了 CLAUDE_CODE_TMPDIR 则整棵树移到该目录下。scratchpad 与会话转录同寿命。只有满足以下全部条件时才有 scratchpad：用 claude.ai 账号登录（非 API Key）、会话使用 Anthropic API（非 Bedrock、Vertex、Foundry）、enableArtifact 没被设为 false。

保留到你删除为止

路径	内容
`history.jsonl`	你输入的每个提示词，含时间戳和项目路径，用于上箭头回溯、`Ctrl+R` 历史搜索和 `!` 命令补全
`stats-cache.json`	`/usage` 显示的聚合 token 和成本计数
`remote-settings.json`	服务端托管设置的缓存副本
`cache/changelog.md`	`/release-notes` 显示的变更日志缓存
`policy-limits.json`	组织的功能策略缓存（部分账号类型才有）

其他文件取决于你用的功能。缓存和锁文件可以放心删除，但要保留这些状态文件：.credentials.json（登录凭据）、agent-memory/（子智能体记忆）、jobs/ 和 daemon/（后台会话状态）。

明文存储

转录和历史不加密，唯一保护是操作系统的文件权限。工具读了 .env 文件或命令打印了凭据，值就会写进转录。降低暴露的办法：

调低 cleanupPeriodDays 缩短保留时间
设置 desktopSessionCleanupPeriodDays 给 Desktop 和 Cowork 转录加年龄限制
设置 CLAUDE_CODE_SKIP_PROMPT_HISTORY 环境变量，在任何模式下都不写转录和提示历史（非交互模式也可以 -p 加 --no-session-persistence）
用权限规则拒绝读取凭据文件

清除本地数据

claude project purge 删除 Claude Code 为某个项目保存的状态：projects/ 下的转录和自动记忆、每会话的 tasks/、debug/、file-history/ 条目、history.jsonl 里该项目的提示行、以及 ~/.claude.json 里该项目的条目。粘贴/附加的图片和 scratchpad 存放在临时目录，不会被它清除。命令会先打印完整的删除计划并要求确认；用 --dry-run 只预览不删除：

claude project purge ~/work/my-repo --dry-run

没有匹配状态时命令打印错误并以状态 1 退出。shell-snapshots/ 不属于项目范围，不会被动，backups/ 里可能还有旧快照，会自动轮换。