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.1 file-history/ 有 332 个文件

这意味着 Claude Code 为每次文件修改都保存了历史快照。如果你不小心让 AI 改坏了文件，可以在这里找回之前的版本。

4.2 projects/ 有 199 个项目记录

每当你 cd 到一个新目录使用 Claude Code，它就会在 projects/ 下创建一个以项目路径哈希命名的子目录，存储该项目的专属上下文。这也是为什么 Claude Code 能"记住"你每个项目的偏好。

4.3 skills/ 27 个文件 vs agents/ 1 个文件

这说明用户更倾向于用 Skill 而不是 Agent 来扩展能力。Skill 更轻量、一个 Markdown 文件就能搞定，适合快速试错；Agent 适合需要完整工具权限和工作流定义的复杂场景。

---

五、你应该先关注什么

如果你是第一次探索 .claude，按这个顺序来：

1. 读 settings.json → 理解当前模型配置和插件状态
2. 读 settings.local.json → 理解权限白名单和环境变量
3. 看 agents/ → 有没有自定义 Agent？怎么写的？
4. 翻 skills/ → 你的自定义 Skill 长什么样？
5. 扫一眼 plans/ → Plan Mode 的计划文档是什么格式？

不要手动改 daemon/、sessions/、telemetry/ 里的任何文件——那是 Claude Code 的运行时状态，乱动会导致不可预期的行为。

---

下一篇预告

下一篇我们深入 settings.json 和 settings.local.json，逐行解读每项配置的含义、最佳实践和常见陷阱——包括那个让很多人困惑的 ANTHROPIC_BASE_URL 和权限白名单的精确写法。

---

你在 .claude 目录里发现过什么让你困惑的文件吗？评论区聊聊。