目录
- [1 claude 目录分类](#1 claude 目录分类)
- [2 📁 项目级目录](#2 📁 项目级目录)
-
- [2.1 .worktreeinclude](#2.1 .worktreeinclude)
- [3 📁 用户级目录](#3 📁 用户级目录)
-
- [3.1 .claude.json](#3.1 .claude.json)
-
- [3.1.1 主要作用](#3.1.1 主要作用)
- [3.1.2 跳过首次登录验证](#3.1.2 跳过首次登录验证)
- [3.2 自动清理](#3.2 自动清理)
- [3.3 持久存储的路径](#3.3 持久存储的路径)
- [3.4 清除本地数据](#3.4 清除本地数据)
Claude Code 目录结构 ------ 了解Claude Code的目录下的文件及其作用
Claude Code 通过读取项目根目录下的
.claude文件夹以及用户主目录下的~/.claude文件夹，来获取CLAUDE.md、settings.json、hooks、skills、commands、subagents、rules 以及自动内存等配置信息。
1 claude 目录分类
Claude Code 的目录分为两类：项目级目录、用户级目录，如下表所示：
| 名称 | 路径 |
|---|---|
| 项目级目录 | <PROJECT>/.claude/ |
| 用户级目录 | ~/.claude，在 Windows 系统中，~/.claude 对应的实际路径为 %USERPROFILE%\.claude，例如：C:\Users\qtz\.claude |
配置范围与团队协作
Claude Code 会综合加载来自项目目录与主目录的指令、设置、技能、子智能体及记忆数据。
- 团队协作：建议将项目目录下的配置文件提交至 Git 仓库，以便团队成员共享统一的开发规范。
- 个人配置 ：
~/.claude目录下的文件属于个人全局配置，适用于您当前用户下的所有项目。
路径说明
- 在 Windows 系统中，
~/.claude对应的实际路径为%USERPROFILE%\.claude。 - 如果您设置了环境变量
CLAUDE_CONFIG_DIR，则文档中所有提及的~/.claude路径均会指向该变量指定的目录。
使用建议
对于大多数用户而言，通常只需编辑 CLAUDE.md（项目说明与指令）和 settings.json（基础设置）。目录中的其余部分均为可选配置，您可以根据实际开发需求，按需添加 skills、rules 或 subagents。
2 📁 项目级目录
<project>/
│
├── CLAUDE.md # 📝 项目级共享指令（提交 Git，每次会话自动加载）
├── CLAUDE.local.md # 🔒 项目级私人偏好（不提交，需手动创建并加入 .gitignore）
├── .mcp.json # 🔗 项目级 MCP 服务器配置（团队共享）
├── .worktreeinclude # 🌿 Git 忽略但需复制到新 worktree 的文件列表
│
└── .claude/
├── settings.json # ⚙️ 项目共享设置（权限、hooks、环境变量、模型默认）
├── settings.local.json # 🔒 项目本地覆盖设置（自动被 git 忽略）
│
├── commands/ # 💬 自定义斜杠命令（/project:xxx 触发）
│ ├── review.md # → /project:review
│ ├── fix-issue.md # → /project:fix-issue
│ └── ccguide/ # 支持子目录分组
│ ├── daily.md # → /project:ccguide/daily
│ └── search-docs.md # → /project:ccguide/search-docs
│
├── rules/ # 📏 模块化行为规则（自动注入系统提示，无需显式引用）
│ ├── api-rules.md # 始终加载（无路径限定符）
│ ├── frontend/ # 路径限定规则
│ │ └── **.tsx.md # 仅匹配 frontend/ 下的 .tsx 文件时加载
│ └── **/test_*.py.md # 匹配任意路径下的 test_*.py 文件时加载
│
├── skills/ # 🧠 可复用技能模块（Skills 2.0，支持热重载）
│ └── <skill-name>/ # 每个 Skill 是独立目录
│ ├── SKILL.md # 技能定义文件（必须）
│ ├── SKILL.md.tmpl # 技能模板（可选）
│ ├── scripts/ # 技能附带的脚本
│ ├── fixtures/ # 测试固定数据
│ ├── references/ # 参考文档
│ ├── assets/ # 静态资源
│ └── eval-viewer/ # 评估查看器
│
├── agents/ # 🤖 自定义子代理定义（独立提示 + 工具权限）
│ ├── code-reviewer.md # 代码审查 Agent
│ ├── security-auditor.md # 安全审计 Agent
│ └── ... # Markdown + YAML frontmatter 格式
│
├── agent-memory/ # 💾 子代理的持久化记忆
│ └── <agent-name>/ # 按代理名分目录
│
├── hooks/ # 🪝 Hook 脚本存放目录
│ ├── pre-commit.sh # 在 settings.json 中声明后生效
│ ├── security-check.py # 支持 shell/python/js 脚本
│ └── ...
│
├── output-styles/ # 🎨 自定义输出格式样式
│ └── *.md # 控制响应格式的系统提示段落
│
└── memory/ # 🧠 自动捕获的会话事实（v2.1.59+）
└── ... # 不提交 Git2.1 .worktreeinclude
在 Claude Code 中，
.worktreeinclude文件的作用是精准控制在创建新的 Git Worktree 时，需要自动复制哪些被 Git 忽略的文件 。它的核心价值在于解决了 Worktree 的一个"副作用"：因为 Worktree 是全新的代码检出副本，默认不会带上.gitignore里列出的文件（比如环境变量配置文件.env、本地配置等）。如果你希望在新工作环境里继续使用这些配置，就需要借助这个文件。
在项目根目录创建 .worktreeinclude 文件后，它的工作遵循两条核心规则：
-
双重条件 ：一个文件要被复制，必须同时满足两个条件：
-
被
.worktreeinclude文件中的模式匹配。 -
被
.gitignore文件忽略。
-
-
安全优先 ：这个机制被设计为只复制未被追踪的文件。任何已经被 Git 版本控制的文件，都不会被复制，从而确保了工作区的干净和安全，避免意外覆盖.
配置示例
.worktreeinclude 文件使用与 .gitignore 。你可以像下面这样配置，将环境变量和本地设置文件自动带入新的工作树：
# 匹配 .env 及其相关文件
.env
.env.local
.env.*
# 匹配 Claude Code 的本地配置文件
**/.claude/settings.local.json3 📁 用户级目录
.claude.json # 📝 全局状态存储文件，记录项目索引、首次标记等
~/.claude/
│
├── CLAUDE.md # 📝 全局指令（适用于所有项目）
├── settings.json # ⚙️ 全局设置（权限、hooks、环境变量、模型默认）
├── settings.local.json # 🔒 全局本地覆盖设置（优先级最高）
├── keybindings.json # ⌨️ 自定义键盘快捷键
├── remote-settings.json # 🏢 组织的服务器管理设置缓存（每次启动刷新）
├── credentials.json # 🔑 认证凭据（自动生成，⚠️ 不要手动编辑）
├── .claudesignature # ✍️ 内部签名文件（自动管理，验证完整性）
│
├── commands/ # 💬 全局自定义命令 → /user:xxx 触发
│ └── *.md
│
├── rules/ # 📏 全局规则（对所有项目生效）
│ └── *.md
│
├── skills/ # 🧠 全局 Skills
│ ├── autoplan/
│ ├── benchmark/
│ ├── browse/
│ └── <skill-name>/
│ ├── SKILL.md # 技能定义
│ ├── SKILL.md.tmpl # 技能模板
│ ├── scripts/ # 脚本目录
│ ├── fixtures/ # 测试固定数据
│ ├── references/ # 参考文档
│ ├── assets/ # 静态资源
│ ├── docs/ # 文档
│ ├── extension/ # 扩展
│ ├── test/ # 测试
│ ├── hosts/ # Hosts 配置
│ └── supabase/ # Supabase 配置
│
├── agents/ # 🤖 全局自定义 Agent
│ └── *.md
│
├── agent-memory/ # 💾 全局子代理持久化记忆
│ └── <agent-name>/
│
├── output-styles/ # 🎨 全局输出样式
│ └── *.md
│
├── themes/ # 🎨 自定义颜色主题
│ └── *.json
│
├── plugins/ # 🔌 插件系统（由 claude plugin 命令管理）
│ ├── installed_plugins.json # 已安装插件列表
│ ├── install-counts-cache.json # 安装计数缓存
│ ├── known_marketplaces.json # 已知市场源
│ ├── cache/ # 插件缓存
│ │ └── <marketplace-name>/
│ ├── data/ # 插件数据
│ │ └── <plugin-name>/
│ └── marketplaces/ # 市场源仓库
│ ├── claude-plugins-official/
│ └── superpowers-marketplace/
│
├── projects/ # 📂 项目级记忆存储
│ └── <path-encoded>/ # 项目路径编码后的目录名
│ ├── <session>.jsonl # 完整对话记录（每条消息、工具调用及结果）
│ ├── <session>/ # 会话子目录
│ │ ├── subagents/ # 子代理对话记录
│ │ └── tool-results/ # 大型工具输出的溢出文件
│ └── CLAUDE.md # 个人对特定项目的私有记忆
│
│ # 示例路径编码映射：
│ # C:\Users\qtz → C--Users-qtz
│ # E:\WorkSpace\HisCode → e--WorkSpace-HisCode
│ # E:\obsidian-wiki → E--obsidian-wiki
│
├── file-history/ # 📜 文件编辑历史（用于检查点恢复）
│ └── <session-uuid>/ # 按会话 UUID 分目录
│ ├── <hash>@v1 # 文件编辑前快照（版本1）
│ ├── <hash>@v2 # 文件编辑前快照（版本2）
│ └── ...
│
├── sessions/ # 🗂️ 会话元数据
│
├── session-env/ # 🌐 每会话环境元数据
│ └── <session-uuid>/ # 按会话 UUID 分目录
│
├── shell-snapshots/ # 🐚 Bash 工具捕获的 shell 环境快照
│ ├── snapshot-bash-<timestamp>-<id>.sh # 正常退出时删除
│ └── ...
│
├── tasks/ # ✅ 每会话任务列表（由任务工具写入）
│ └── <session-uuid> # 按会话 UUID 存储
│
├── plans/ # 📋 计划模式下写入的计划文件
│ └── <session-uuid> # 按会话 UUID 存储
│
├── cache/ # 💨 运行时缓存（可安全删除，自动重建）
│ └── changelog.md # 更新日志缓存
│
├── backups/ # 🔄 配置迁移前 ~/.claude.json 的时间戳备份
│ └── .claude.json.backup.<timestamp> # 备份文件
│
├── ide/ # 💻 IDE 集成数据（VS Code、JetBrains）
│ └── <pid>.lock # IDE 进程锁文件
│
├── telemetry/ # 📊 遥测数据
│ └── 1p_failed_events.*.json # 失败的事件上报
│
├── paste-cache/ # 📋 大型粘贴内容缓存
├── image-cache/ # 🖼️ 附件图片缓存
├── debug/ # 🐛 每会话调试日志（仅 --debug 或 /debug 时写入）
├── feedback-bundles/ # 📦 /feedback 生成的脱敏对话归档（发送给 Anthropic）
├── statsig/ # 🧪 A/B 测试和功能标志配置（灰度发布）
├── tempo/ # ⏱️ 会话运行时临时数据
├── todos/ # 📝 旧版任务列表（当前版本不再写入，可安全删除）
│
├── history.jsonl # 📜 所有输入过的提示（含时间戳和项目路径，用于↑回忆）
├── stats-cache.json # 📊 聚合的 token 和费用统计（/usage 显示）
├── .last-cleanup # 🧹 上次自动清理时间戳
└── .update.lock # 🔒 更新锁文件3.1 .claude.json
用户级目录下的 ~/.claude.json 文件是 Claude Code 的全局状态存储文件 ，用于记录工具的运行状态、项目索引和首次设置标记。它与 ~/.claude/settings.json（用于配置规则和行为）不同，前者存储的是状态数据 ，后者存储的是配置信息。
3.1.1 主要作用
| 功能 | 说明 |
|---|---|
| 跳过初始引导 | 设置 "hasCompletedOnboarding": true 可跳过 Anthropic 官方的首次登录验证流程。 |
| 存储项目索引 | 以绝对路径为键，记录所有使用过的项目信息，用于会话恢复和工作树管理-6 |
| 记录完成状态 | 标记用户是否已完成初始配置，避免重复弹出设置向导 |
3.1.2 跳过首次登录验证
这是最常用的配置场景。当你不想进行 Anthropic 官方登录时，可以编辑该文件
json
{
"hasCompletedOnboarding": true
}该设置告诉 Claude Code 用户已完成初始化引导，从而跳过登录验证步骤.
3.2 自动清理
下面路径中的文件在启动时被删除，一旦它们的年龄超过 cleanupPeriodDays。默认值为 30 天。
~/.claude/ 下的路径 |
内容 |
|---|---|
projects/<project>/<session>.jsonl |
完整的对话记录：每条消息、工具调用和工具结果 |
projects/<project>/<session>/subagents/ |
Subagent 对话记录，当父会话记录过期时被删除 |
projects/<project>/<session>/tool-results/ |
大型工具输出溢出到单独的文件 |
file-history/<session>/ |
Claude 更改的文件的编辑前快照，用于检查点恢复 |
| debug/ | 每个会话的调试日志，仅在您使用 --debug 启动或运行 /debug 时写入 |
paste-cache/、image-cache/ |
大型粘贴和附加图像的内容 |
| session-env/ | 每个会话的环境元数据 |
| tasks/ | 由任务工具写入的每个会话的任务列表 |
| shell-snapshots/ | 由 Bash 工具使用的捕获的 shell 环境。在正常退出时删除。扫描清理任何在崩溃后留下的内容。 |
| backups/ | 在配置迁移前获取的 ~/.claude.json 的时间戳副本 |
| feedback-bundles/ | 由 /feedback 在第三方提供商上写入的编辑后的记录存档，用于发送到您的 Anthropic 账户团队 |
3.3 持久存储的路径
以下路径不受自动清理覆盖，并无限期保留。
~/.claude/ 下的路径 |
内容 |
|---|---|
| history.jsonl | 您输入的每个提示，带有时间戳和项目路径。用于向上箭头回忆。 |
| stats-cache.json | 由 /usage 显示的聚合令牌和成本计数 |
| remote-settings.json | 服务器管理的设置的缓存副本，用于您的组织。仅在您的组织配置了这些设置时才存在。在每次启动时刷新。 |
| todos/ | 旧版每个会话的任务列表。不再由当前版本写入；可以安全删除。 |
3.4 清除本地数据
- 运行
claude project purge可以删除 Claude Code 为特定项目保存的所有状态数据，包括：
-
projects/目录下的记录和自动记忆（Auto Memory） -
每个会话中的
tasks/、debug/和file-history/条目 -
history.jsonl中与该项目相关的提示行 -
~/.claude.json中的项目条目
该命令会先打印完整的删除计划，并在实际删除任何内容之前要求你确认。
- 仅预览删除计划而不实际删除任何内容：
shell
claude project purge ~/work/my-repo --dry-run- 使用单个确认提示删除指定项目：
shell
claude project purge ~/work/my-repo-
跳过确认提示以在脚本中使用：
claude project purge ~/work/my-repo --yes
-
不要删除
~/.claude.json、~/.claude/settings.json或~/.claude/plugins/：这些保存您的身份验证、偏好和已安装的 plugins。
秋堂主 · 倚楼听风雨，淡看江湖路！