~/.claude 目录结构解析

约 1650 字大约 6 分钟

Claude Code配置

2026-04-07

Claude Code 把所有用户级别的配置、缓存、历史、插件都放在 ~/.claude/ 下。理解这个目录的布局，有助于排查问题、备份重要数据、清理冗余文件，以及更深入地利用 Claude Code 的能力。

下面按"用户可主动操作"和"运行时自动管理"两类，逐一介绍每个文件/目录的作用与使用方式。

整体概览

~/.claude/
├── settings.json          # 全局设置（用户可编辑）
├── CLAUDE.md              # 全局记忆/指令（用户可编辑，可选）
├── commands/              # 自定义斜杠命令
├── skills/                # 用户级 Skills
├── plugins/               # 已安装的插件
├── plans/                 # 实现计划存档
├── projects/              # 各项目的会话与记忆
├── sessions/              # 会话状态
├── history.jsonl          # 全局对话历史
├── todos/                 # TodoWrite 任务持久化
├── tasks/                 # Task 子代理产物
├── backups/               # 自动备份
├── cache/                 # 通用缓存
├── file-history/          # 文件编辑历史快照
├── paste-cache/           # 粘贴内容缓存
├── shell-snapshots/       # Shell 环境快照
├── session-env/           # 每个会话的环境变量
├── telemetry/             # 使用遥测数据
├── debug/                 # 调试日志
├── downloads/             # 下载文件
├── ide/                   # IDE 集成状态
└── stats-cache.json       # 使用统计缓存

一、用户可主动操作的部分

这些文件/目录是你日常会编辑或查看的，直接决定了 Claude Code 的行为。

settings.json — 全局设置

最核心的配置文件，控制权限模式、模型选择、hooks、环境变量、MCP 服务器、状态栏等。

{
    "model": "claude-opus-4-6",
    "permissionMode": "acceptEdits",
    "hooks": {
        "SessionStart": [/* ... */]
    },
    "statusLine": {
        "type": "command",
        "command": "claude-hud"
    }
}

提示

项目级的 .claude/settings.json 会覆盖全局配置。详情见 settings.md。

CLAUDE.md — 全局指令

放在 ~/.claude/CLAUDE.md 的内容会作为系统级指令，注入每一次对话。适合写：

你的语言偏好（例如"始终用中文回复"）
通用编码规范（不写死项目专属规则）
全局禁止行为

项目级的 CLAUDE.md 用于项目特定的指令，二者会叠加。

commands/ — 自定义斜杠命令

每个 .md 文件就是一条 /xxx 命令。文件名 = 命令名，文件内容 = 命令展开后的提示词。

~/.claude/commands/
├── deploy.md      # 输入 /deploy 触发
└── review-pr.md   # 输入 /review-pr 触发

效果：把高频提示词固化为快捷命令，减少重复输入，团队也能共享最佳实践。

skills/ — 用户级 Skills

Skills 是带有 frontmatter 描述的 Markdown 提示词包，Claude 会根据 description 自动判断是否调用。

~/.claude/skills/
└── my-skill/
    ├── SKILL.md         # 主入口（必须）
    └── references/      # 可选的参考文件

效果：把工作流程沉淀为可复用的"超能力"。例如 commit、code-review、kb 都是通过 Skill 实现的。详情见 skill.md。

plugins/ — 已安装插件

通过 /plugin install 安装的插件存放于此。每个插件可以同时提供 commands、skills、agents、hooks 等。

~/.claude/plugins/
├── superpowers/
└── claude-hud/

效果：插件是组织 commands + skills + hooks 的最高级别单位，便于一键安装和分享。

plans/ — 实现计划存档

使用 superpowers:writing-plans 等流程产出的实现计划保存在这里，可在后续会话中通过 superpowers:executing-plans 调用。

使用方式：手动归档/查看长流程任务的设计文档，避免上下文窗口被吃光。

二、运行时自动管理的部分

这些目录由 Claude Code 自行维护，一般不需要手动改动，但了解它们对调试和排错非常有用。

projects/ — 项目会话与记忆

按工作目录路径哈希组织，每个项目下保存：

历史会话（恢复对话用）
memory/：自动记忆系统的存放位置（user/feedback/project/reference 类型的 markdown 文件 + MEMORY.md 索引）

效果：跨会话保留对项目的认知。可以手动浏览查看 Claude "记得"了什么。

sessions/ + session-env/ — 会话状态

sessions/：当前/历史会话的状态快照，支持 claude --resume 恢复
session-env/：每个会话的环境变量隔离

history.jsonl — 全局历史

按行存储所有交互的 jsonl，可以用 jq 检索过往对话。

jq 'select(.cwd == "/path/to/project")' ~/.claude/history.jsonl

todos/ — TodoWrite 持久化

TodoWrite 工具创建的任务列表保存在这里，按会话隔离。

tasks/ — 子代理产物

Task 工具（子代理）的输入输出归档，便于回看子代理执行细节。

file-history/ — 文件编辑快照

每次 Edit/Write 操作都会生成快照，相当于 Claude Code 自带的"文件级时光机"。

实用场景：误删/误改文件时，可以从这里恢复。

ls -lt ~/.claude/file-history/ | head

backups/ — 自动备份

settings、CLAUDE.md 等关键配置的滚动备份。改坏配置时可以从这里回滚。

shell-snapshots/ — Shell 环境快照

Bash 工具启动子 shell 时使用的 PATH/alias 快照，保证执行环境与你的 shell 一致。

paste-cache/ — 粘贴缓存

粘贴大段文本或图片时，先缓存到此处再被 Claude 读取，避免污染对话流。

debug/ — 调试日志

开启调试模式（claude --debug）后产生的日志。报 bug 时附上这里的内容最有用。

telemetry/ + stats-cache.json — 使用统计

记录 token 用量、命令使用频率等。/stats 查看的统计数据来源于此。

cache/ + downloads/ + ide/ — 杂项

cache/：通用缓存，可以安全清理
downloads/：Claude 通过工具下载的文件
ide/：与 VS Code/JetBrains 等 IDE 集成时的中间状态

三、常见使用场景

1. 备份与同步

值得纳入版本控制 / 同步到云端的：

~/.claude/settings.json
~/.claude/CLAUDE.md
~/.claude/commands/
~/.claude/skills/
~/.claude/plans/

不要同步：history.jsonl、projects/、sessions/、cache/、telemetry/、file-history/（包含敏感对话和大量临时数据）。

2. 清理磁盘

体积容易膨胀的目录：

du -sh ~/.claude/* | sort -rh | head

通常 file-history/、projects/、history.jsonl、telemetry/ 占用最多。可以定期清理：

# 清理 30 天前的文件历史
find ~/.claude/file-history -mtime +30 -delete

3. 排查问题

配置不生效 → 检查 settings.json 与项目级 .claude/settings.json 的合并结果
Skill/命令没被调用 → 检查 skills/ 和 commands/ 下的 frontmatter 是否正确
对话异常 → 查看 debug/ 下的日志
Hook 没触发 → 确认 hook 配置写在 settings.json 而非别处

4. 跨设备迁移

把以下目录打包就能在新机器上恢复 80% 的个人化配置：

tar -czf claude-config.tar.gz \
    ~/.claude/settings.json \
    ~/.claude/CLAUDE.md \
    ~/.claude/commands \
    ~/.claude/skills \
    ~/.claude/plans

小结

~/.claude/ 目录的设计哲学是：用户可控的配置和运行时数据严格分离。

想定制 Claude Code 的行为 → 改 settings.json、CLAUDE.md、commands/、skills/
想看 Claude 记住了什么 → 翻 projects/*/memory/
想恢复误改的文件 → 找 file-history/
想报 bug → 附上 debug/
想清理空间 → 优先清 file-history/、telemetry/、cache/

理解了这些目录，你就拥有了 Claude Code 的"系统视角"，可以更自由地把它塑造成趁手的工具。

Claude Code

OpenAI

Qwen Code