Claude Code 配置完全指南（一）：.claude 目录结构全景解析
系列第 1 篇 | 2026-07-22
配套仓库：C:\Users\zhang\.claude
前言
Claude Code 的配置全部藏在~/.claude目录下。这个目录不像 VS Code 的settings.json那样一目了然——它包含 19 个子目录、超过 1,300 个文件，结构复杂但设计精妙。理解这个目录，是你定制 Claude Code 行为、编写 Agent、搭建工作流的第一步。
本文带你遍历整个.claude目录，看清每个角落放什么、怎么用。
一、目录树一览
在我的 Windows 环境中，C:\Users\zhang\.claude结构如下：
.claude/ ├── .last-cleanup # 上次清理时间戳 ├── .last-update-result.json # 最近一次更新结果 ├── daemon.log # 守护进程日志（1KB） ├── history.jsonl # 对话历史（148KB） ├── settings.json # 全局配置（云端同步） ├── settings.local.json # 本地配置（不同步，2KB） ├── stats-cache.json # 统计缓存 │ ├── agents/ (1 file) # 自定义 Agent 定义 ├── backups/ (5 files) # settings 自动备份 ├── cache/ (1 file) # 更新日志缓存 ├── daemon/ (3 files) # 守护进程状态 ├── debug/ (1 file) # 调试信息 ├── downloads/ (1 file) # 下载的安装包 ├── file-history/ (332 files) # 文件修改历史（用于 undo） ├── ide/ (空) # IDE 集成 ├── jobs/ (6 files) # 后台任务 ├── paste-cache/ (8 files) # 粘贴缓存 ├── plans/ (3 files) # Plan Mode 计划文档 ├── plugins/ (650 files) # 插件系统 ├── projects/ (199 files) # 项目级上下文 ├── session-env/ (空) # 会话环境变量 ├── sessions/ (2 files) # 会话状态 ├── shell-snapshots/ (4 files) # Shell 快照 ├── skills/ (27 files) # 自定义 Skill ├── tasks/ (43 files) # 后台任务定义 └── telemetry/ (64 files) # 遥测数据二、三层架构：全局 → 本地 → 项目
Claude Code 的设计遵循三层配置模型：
| 层级 | 文件 | 同步 | 用途 |
|---|---|---|---|
| 全局 | settings.json | 云端同步 | 多设备共享的通用配置 |
| 本地 | settings.local.json | 不同步 | 设备特有的权限、环境变量 |
| 项目 | projects/<hash>/ | 不同步 | 单项目的上下文和配置覆盖 |
这套设计的精妙之处：你可以在公司电脑和家用电脑之间同步 Agent 定义，但每台电脑的 Python 路径和权限策略保持独立。
三、五大核心子系统
按功能划分，.claude可以归纳为五个子系统：
3.1 配置引擎
| 目录/文件 | 作用 | 优先级 |
|---|---|---|
settings.json | API 地址、模型选择、插件开关 | 低 |
settings.local.json | 权限白名单、本地环境变量 | 最高 |
settings.local.json的优先级最高，这意味着你可以在本地覆盖全局配置。
3.2 能力扩展
| 目录 | 文件数 | 作用 |
|---|---|---|
agents/ | 1 | 自定义 Agent，如fullstack-developer.md |
skills/ | 27 | 自定义 Skill，每个 Skill 是一个 Markdown 指令集 |
plugins/ | 650 | 官方和社区插件，如frontend-design、superpowers |
这三者构成了 Claude Code 的能力扩展体系：
- Agent→ 定义"谁来做"（角色、工具权限、工作流）
- Skill→ 定义"怎么做"（专项指令和领域知识）
- Plugin→ 提供底层工具和集成（MCP 服务、命令、钩子）
3.3 运行时状态
| 目录 | 作用 |
|---|---|
daemon/ | 守护进程的 PID、管道密钥、控制套接字 |
sessions/ | 当前会话的上下文和对话状态 |
session-env/ | 会话级环境变量（运行时注入） |
tasks/ | 后台任务定义和状态（如定时任务） |
jobs/ | 任务执行日志 |
这些文件在 Claude Code 运行时持续更新，不建议手动修改。
3.4 数据持久化
| 目录 | 作用 |
|---|---|
history.jsonl | 所有对话的完整记录 |
file-history/ | 文件修改历史，支持 undo/redo |
projects/ | 项目级.claude配置（199 个项目记录） |
plans/ | Plan Mode 中制定的计划文档 |
paste-cache/ | 粘贴内容的缓存 |
3.5 运维工具
| 目录/文件 | 作用 |
|---|---|
backups/ | settings.json的自动备份（5 个历史版本） |
debug/ | 最后一份调试日志 |
telemetry/ | 使用统计和遥测数据 |
cache/ | 更新日志缓存 |
.last-cleanup | 清理时间戳 |
四、值得关注的细节
4.1file-history/有 332 个文件
这意味着 Claude Code 为每次文件修改都保存了历史快照。如果你不小心让 AI 改坏了文件，可以在这里找回之前的版本。
4.2projects/有 199 个项目记录
每当你cd到一个新目录使用 Claude Code，它就会在projects/下创建一个以项目路径哈希命名的子目录，存储该项目的专属上下文。这也是为什么 Claude Code 能"记住"你每个项目的偏好。
4.3skills/27 个文件 vsagents/1 个文件
这说明用户更倾向于用 Skill 而不是 Agent 来扩展能力。Skill 更轻量、一个 Markdown 文件就能搞定，适合快速试错；Agent 适合需要完整工具权限和工作流定义的复杂场景。
五、你应该先关注什么
如果你是第一次探索.claude，按这个顺序来：
- 读
settings.json→ 理解当前模型配置和插件状态 - 读
settings.local.json→ 理解权限白名单和环境变量 - 看
agents/→ 有没有自定义 Agent？怎么写的？ - 翻
skills/→ 你的自定义 Skill 长什么样？ - 扫一眼
plans/→ Plan Mode 的计划文档是什么格式？
不要手动改daemon/、sessions/、telemetry/里的任何文件——那是 Claude Code 的运行时状态，乱动会导致不可预期的行为。
下一篇预告
下一篇我们深入settings.json和settings.local.json，逐行解读每项配置的含义、最佳实践和常见陷阱——包括那个让很多人困惑的ANTHROPIC_BASE_URL和权限白名单的精确写法。
你在.claude目录里发现过什么让你困惑的文件吗？评论区聊聊。