Claude Code 入门与原理
Claude Code 入门与原理
.claude 目录详解
33 分钟阅读
探索 .claude 目录
Claude Code 读取 CLAUDE.md、settings.json、钩子、技能、命令、子智能体、工作流、规则和自动记忆的位置。探索你项目中的 .claude 目录和主目录中的 ~/.claude。
Claude Code 从你项目目录和主目录中的 ~/.claude 读取指令、设置、技能、子智能体和记忆。将项目文件提交到 git 以与团队共享；~/.claude 中的文件是个人配置，适用于你所有项目。
在 Windows 上，~/.claude 解析为 %USERPROFILE%\.claude。如果你设置了 CLAUDE_CONFIG_DIR，本页上每个 ~/.claude 路径都位于该目录下。
大多数用户只编辑 CLAUDE.md 和 settings.json。目录的其余部分是可选的：根据需要添加技能、规则或子智能体。
探索目录
点击树中的文件以查看每个文件的作用、加载时机和示例。
Unsupported component: <ClaudeExplorer>
未显示的内容
资源管理器涵盖你编写和编辑的文件。一些相关文件位于其他位置：
| 文件 | 位置 | 用途 |
|---|---|---|
managed-settings.json | 系统级别，因操作系统而异 | 企业强制设置，你无法覆盖。请参阅服务器托管设置。 |
CLAUDE.local.md | 项目根目录 | 你对此项目的私人偏好，与 CLAUDE.md 一起加载。手动创建并添加到 .gitignore。 |
| 已安装插件 | ~/.claude/plugins | 克隆的市场、已安装的插件版本和每个插件的数据，由 claude plugin 命令管理。孤立版本在插件更新或卸载后 7 天删除。请参阅插件缓存。 |
~/.claude 还保存 Claude Code 工作时写入的数据：对话记录、提示历史、文件快照、缓存和日志。请参阅下面的应用数据。
选择正确的文件
不同类型的自定义存在于不同的文件中。使用此表查找更改属于何处。
| 你想 | 编辑 | 范围 | 参考 |
|---|---|---|---|
| 给 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 | 仅项目 | MCP |
| 更改 Claude 格式化响应的方式 | output-styles/*.md | 项目或全局 | 输出样式 |
文件参考
此表列出资源管理器涵盖的每个文件。项目范围文件位于你仓库中的 .claude/ 下（或在根目录下存放 CLAUDE.md、.mcp.json 和 .worktreeinclude）。全局范围文件位于 ~/.claude/ 并适用于你所有项目。
点击文件名以在上面的资源管理器中打开该节点。
| 文件 | 范围 | 提交 | 作用 | 参考 |
|---|---|---|---|---|
CLAUDE.md | 项目和全局 | ✓ | 每次会话加载的指令 | 记忆 |
rules/*.md | 项目和全局 | ✓ | 主题范围指令，可选路径限制 | 规则 |
settings.json | 项目和全局 | ✓ | 权限、钩子、环境变量、模型默认值 | 设置 |
settings.local.json | 仅项目 | 你的个人覆盖，Claude Code 创建时自动 gitignored | 设置范围 | |
.mcp.json | 仅项目 | ✓ | 团队共享 MCP 服务器 | MCP 范围 |
.worktreeinclude | 仅项目 | ✓ | 要复制到新 worktree 的 gitignored 文件 | Worktrees |
skills/<name>/SKILL.md | 项目和全局 | ✓ | 用 /name 调用或自动调用的可复用提示 | 技能 |
commands/*.md | 项目和全局 | ✓ | 单文件提示；与技能机制相同 | 技能 |
output-styles/*.md | 项目和全局 | ✓ | 自定义系统提示部分 | 输出样式 |
agents/*.md | 项目和全局 | ✓ | 具有自己提示和工具的子智能体定义 | 子智能体 |
workflows/*.js | 项目和全局 | ✓ | 由 Claude 编写并从 /workflows 保存的动态工作流脚本；每个文件成为 /<name> 命令 | 动态工作流 |
agent-memory/<name>/ | 项目和全局 | ✓ | 子智能体的持久记忆 | 持久记忆 |
~/.claude.json | 仅全局 | 应用状态、OAuth、UI 开关、个人 MCP 服务器 | 全局配置 | |
projects/<project>/memory/ | 仅全局 | 自动记忆：Claude 跨会话的笔记 | 自动记忆 | |
keybindings.json | 仅全局 | 自定义键盘快捷键 | 快捷键 | |
themes/*.json | 仅全局 | 自定义颜色主题 | 自定义主题 |
故障排除配置
如果设置、钩子或文件未生效，请参阅调试你的配置了解检查命令和症状优先查找表。
应用数据
除了你编写的配置外，~/.claude 保存 Claude Code 在会话期间写入的数据。这些文件是纯文本。任何通过工具的内容都会落入磁盘上的对话记录：文件内容、命令输出、粘贴的文本。
自动清理
以下路径中的文件在启动时删除，一旦超过 cleanupPeriodDays。默认是 30 天。
~/.claude/ 下的路径 | 内容 |
|---|---|
projects/<project>/<session>.jsonl | 完整对话记录：每条消息、工具调用和工具结果 |
projects/<project>/<session>/subagents/ | 子智能体 对话记录，随父会话记录过期时删除 |
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 的时间戳副本 |
feedback-bundles/ | 由 /feedback 在第三方提供商上编写的脱敏对话记录存档，用于发送到你的 Anthropic 账户团队 |
todos/, statsig/, logs/ | 旧版本的遗留目录。不再写入。清理会删除其内容，然后删除空目录。 |
保留直到你删除
以下路径不受自动清理覆盖，无限期保留。
~/.claude/ 下的路径 | 内容 |
|---|---|
history.jsonl | 你输入的每个提示，带时间戳和项目路径。用于向上箭头回忆。 |
stats-cache.json | /usage 显示的聚合 token 和成本计数 |
remote-settings.json | 你组织的服务器托管设置的缓存副本。仅当你的组织配置它们时存在。每次启动时刷新。 |
根据你使用的功能，其他小型缓存和锁文件会出现，删除它们是安全的。
纯文本存储
对话记录和历史在静态时不加密。操作系统文件权限是唯一的保护。如果工具读取 .env 文件或命令打印凭证，该值会写入 projects/<project>/<session>.jsonl。要减少暴露：
- 降低
cleanupPeriodDays以缩短对话记录保留时间 - 设置
CLAUDE_CODE_SKIP_PROMPT_HISTORY环境变量以跳过在任何模式下写入对话记录和提示历史。在非交互模式下，你可以改为传递--no-session-persistence和-p，或在 Agent SDK 中设置persistSession: false。 - 使用权限规则拒绝读取凭证文件
清除本地数据
运行 claude project purge 删除 Claude Code 为一个项目持有的状态。该命令需要 Claude Code v2.1.124 或更高版本。它删除：
projects/下的对话记录和自动记忆- 每次会话的
tasks/、debug/和file-history/条目 history.jsonl中的匹配提示行~/.claude.json中的项目条目
该命令打印完整删除计划并在删除任何内容前要求确认。
预览计划而不删除任何内容：
通过单个确认提示删除：
省略路径以从交互列表中选择项目。
跳过脚本中的确认提示：
传递 --all 代替路径以一次性清除每个项目的状态，这会直接删除 history.jsonl 而不是过滤它。传递 -i 以逐项逐步执行删除计划。
该命令保留 shell-snapshots/ 和 backups/ 不变，因为它们不是项目范围的，并在计划输出中警告它们。如果没有状态匹配给定路径，它以状态 1 退出。
你也可以手动删除上述任何应用数据路径。新会话不受影响。下表显示删除过去会话的内容会丢失什么。
| 删除 | 你失去 |
|---|---|
~/.claude/projects/ | 过去会话的恢复、继续和回退 |
~/.claude/history.jsonl | 向上箭头提示回忆 |
~/.claude/file-history/ | 过去会话的检查点恢复 |
~/.claude/stats-cache.json | /usage 显示的历史总计 |
~/.claude/remote-settings.json | 无。下次启动时重新获取。 |
~/.claude/debug/、~/.claude/plans/、~/.claude/paste-cache/、~/.claude/image-cache/、~/.claude/session-env/、~/.claude/tasks/、~/.claude/shell-snapshots/、~/.claude/backups/ | 无用户可见内容 |
~/.claude/todos/、~/.claude/statsig/、~/.claude/logs/ | 无。当前版本不写入的遗留目录。 |
不要删除 ~/.claude.json、~/.claude/settings.json 或 ~/.claude/plugins/：这些保存你的认证、偏好和已安装插件。
相关资源
- 管理 Claude 的记忆：编写和组织 CLAUDE.md、规则和自动记忆
- 配置设置：设置权限、钩子、环境变量和模型默认值
- 创建技能：构建可复用提示和工作流
- 配置子智能体：定义具有自己上下文的专业智能体