01 

设计背景：本地 AI 编程助手的存储痛点

02 

核心设计原则：构建可靠、可管的存储体系

03 

全局目录搭建思路

{"projects": {"/Users/xxx/my-project": {"MCPServers": {"jarvis-tasks": {"type": "stdio","command": "python","args": ["/path/to/run_mcp.py"]}}}},"recentPrompts": ["Fix the bug in auth module","Add unit tests"]}

~/.claude/├── settings.json                    # 全局设置（权限、插件、清理周期）├── settings.local.json              # 本地设置（机器特定，不提交Git）├── history.jsonl                    # 命令历史记录│├── projects/                        # 📁 Session 数据（按项目组织，核心目录）│   └── -Users-xxx-project/          # 路径编码后的项目目录│       ├── {session-id}.jsonl       # 主会话数据（JSONL格式）│       └── agent-{agentId}.jsonl    # 子代理会话数据│├── session-env/                     # Session 环境变量│   └── {session-id}/                # 按Session ID隔离│├── skills/                          # 📁 用户级 Skills（全局可用）│   └── mac-mail/│       └── SKILL.md│├── plugins/                         # 📁 插件管理│   ├── config.json                  # 插件全局配置│   ├── installed_plugins.json       # 已安装插件列表│   ├── known_marketplaces.json      # 市场源配置│   ├── cache/                       # 插件缓存│   └── marketplaces/│       └── anthropic-agent-skills/│           ├── .claude-plugin/│           │   └── marketplace.json│           └── skills/│               ├── pdf/│               ├── docx/│               └── frontend-design/│├── todos/                           # 任务列表存储│   └── {session-id}-*.json          # 关联Session的任务文件│├── file-history/                    # 文件编辑历史（按内容hash存储）│   └── {content-hash}/              # 哈希命名的文件备份目录│├── shell-snapshots/                 # Shell 状态快照├── plans/                           # Plan Mode 计划存储├── local/                           # 本地工具/node_modules│   └── claude                       # Claude CLI 可执行文件│   └── node_modules/                # 本地依赖│├── statsig/                         # 特性开关缓存├── telemetry/                       # 遥测数据└── debug/                           # 调试日志




04 

Claude Code配置文件层级设计
为兼顾全局统一配置和局部定制需求，Claude Code设计了三级配置体系，优先级从高到低依次为：项目级配置 > 本地配置 > 全局配置。


┌─────────────────────────────────────────┐│           项目级配置                      │  优先级最高│    项目/.claude/settings.json            │  项目专属，覆盖其他配置├─────────────────────────────────────────┤│           本地配置                        │  机器特定，不提交版本控制│    ~/.claude/settings.local.json         │  覆盖全局配置├─────────────────────────────────────────┤│           全局配置                        │  优先级最低│    ~/.claude/settings.json               │  基础默认配置└─────────────────────────────────────────┘

各配置文件完整示例如下：
（1） ~/.claude/settings.json（全局设置）
{  "$schema": "https://json.schemastore.org/claude-code-settings.json",  "permissions": {    "allow": ["Read(**)", "Bash(npm:*)"],    "deny": ["Bash(rm -rf:*)"],    "ask": ["Edit", "Write"]  },  "enabledPlugins": {    "document-skills@anthropic-agent-skills": true  },  "cleanupPeriodDays": 30}
（2） ~/.claude/settings.local.json（机器特定，不提交版本控制）
{  "permissions": {    "allow": ["Bash(git:*)", "Bash(docker:*)"]  },  "env": {    "ANTHROPIC_API_KEY": "sk-ant-xxx"  }}
（3）项目/.claude/settings.json（项目专属）
{  "permissions": {    "allow": ["Bash(pytest:*)"]  }}
整体的配置合并与权限规则如下：
合并规则：最终配置 = 全局配置 + 本地配置覆盖 + 项目配置覆盖（后加载的配置覆盖先加载的同字段）；
权限优先级：deny > ask > allow > 默认行为（严格遵循，保障操作安全）。
05
Session数据存储：核心交互数据的持久化设计
Session是Claude Code最核心的数据，存储了所有对话历史和上下文，其设计直接决定了数据可靠性和可追溯性。
（1）存储思路：按项目路径编码隔离
存储路径：~/.claude/projects/ + 路径编码后的项目目录；
路径编码规则：将 /、空格、~ 替换为 -；
示例


/Users/bill/My Project → -Users-bill-My-Project

（2）存储格式：JSONL的优势与示例
Session数据采用JSONL（JSON Lines）格式，而非普通JSON，核心原因如下：

JSONL格式完整示例


{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}

使用JSONL，让每个消息独立一行的核心价值在于：


实时持久化：每条消息生成后立即写入文件，无延迟；


崩溃恢复：已写入的消息不会因后续错误或崩溃丢失；


高效读写：追加写入无需读取历史数据，读写效率高。


（3）Session JSONL数据结构（完整消息类型与示例）
Session文件包含多种消息类型，每种类型承担特定职责：

用户消息完整示例如下


{"type": "user","uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","parentUuid": null,"sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf","timestamp": "2026-01-05T10:00:00.000Z","message": {"role": "user","content": "分析一下这个项目的架构"},"cwd": "/Users/xxx/project","gitBranch": "main","version": "2.0.76"}

助手消息完整示例（含工具调用与token使用）如下


{"type": "assistant","uuid": "e684816e-f476-424d-92e3-1fe404f13212","parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","message": {"role": "assistant","model": "claude-opus-4-5-20251101","content": [{"type": "thinking","thinking": "用户想了解项目架构，我需要先查看目录结构..."},{"type": "text","text": "让我先看一下项目结构。"},{"type": "tool_use","id": "toolu_01ABC","name": "Bash","input": {"command": "ls -la"}}],"usage": {"input_tokens": 1500,"output_tokens": 200,"cache_read_input_tokens": 50000}}}

（4）消息链结构（完整链路示例）如下
消息通过 uuid（自身唯一标识）和 parentUuid（父消息标识）形成完整链式结构，支持全链路回溯：


file-history-snapshot (messageId: A)↓user (uuid: A, parentUuid: null)     ← 用户提问（链路起点）↓assistant (uuid: B, parentUuid: A)   ← AI思考 + 文本回复↓assistant (uuid: C, parentUuid: B)   ← AI工具调用（如Bash命令）↓user (uuid: D, parentUuid: C)        ← 工具执行结果（如Bash输出）↓assistant (uuid: E, parentUuid: D)   ← AI基于工具结果继续回复↓summary (leafUuid: E)                ← 会话摘要（关联链路终点）

06
file-history-snapshot：实现操作可撤销的核心机制
这是Claude Code保障代码修改可恢复的关键设计，核心逻辑是修改前备份原始内容，撤销时恢复，所有细节如下：
（1）核心定义：什么是Checkpoint，作用如何？
每当用户发送新消息时，Claude Code会自动创建 file-history-snapshot，专门记录「即将被修改的文件的原始内容」，作为撤销操作的数据源：


用户提问 → 创建snapshot（备份原始内容） → Claude修改文件 → 用户不满意 → Esc+Esc撤销↑                                              ↓存储原始内容  ←─────────────────────────────── 从snapshot恢复原始内容

（2）完整数据结构示例


{"type": "file-history-snapshot","messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","snapshot": {"messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348","trackedFileBackups": {"/path/to/file1.py": "原始文件内容ndef hello():n    print('old')","/path/to/file2.js": "// 原始内容..."},"timestamp": "2026-01-05T10:00:00.000Z"},"isSnapshotUpdate": false}

（3）关键步骤：备份修改前的内容
trackedFileBackups 存储的是文件修改前的原始内容，而非修改后的内容。这是撤销功能的核心建设思路：


┌──────────────────┐│  修改前 app.py    ││  print("old")    │───────→ 备份到 snapshot 的 trackedFileBackups└──────────────────┘↓┌──────────────────┐│  Claude 修改后    ││  print("new")    │───────→ 写入磁盘（覆盖原文件）└──────────────────┘↓┌──────────────────┐│  用户执行撤销    ││  按下 Esc + Esc  │───────→ 从 snapshot 恢复 "old" 内容到磁盘└──────────────────┘

（4）完整工作流程


用户发送消息：触发创建空的 file-history-snapshot 记录；


Claude 准备修改文件：系统自动扫描即将修改的文件，将其原始内容备份到 trackedFileBackups；


执行修改操作：Claude 执行 Edit/Write 指令，将修改后的内容写入磁盘；


用户发起撤销：按下 Esc + Esc 快捷键，触发撤销流程；


恢复原始内容：系统从 trackedFileBackups 中读取备份的原始内容，覆盖当前文件，完成撤销。


（5）存储位置与保留策略


快照记录存储：与对应Session绑定，存储在 ~/.claude/projects/-path-to-project/{session-id}.jsonl 中；


文件内容备份：原始文件内容按哈希存储在 ~/.claude/file-history/{content-hash}/ 目录；


默认保留期：30天（与全局 cleanupPeriodDays 配置一致）；


配置方式：可通过 ~/.claude/settings.json 中的 cleanupPeriodDays 字段调整保留天数。


（6）相关命令

07
其他重要目录
（1）plugins/ – 插件管理


~/.claude/plugins/├── config.json插件全局配置（如启用/禁用规则）├── installed_plugins.json已安装插件列表（含版本、状态）├── known_marketplaces.json插件市场源配置（如Anthropic官方市场）├── cache/插件下载缓存（避免重复下载）└── marketplaces/市场源存储目录└── anthropic-agent-skills/官方插件市场├── .claude-plugin/│   └── marketplace.json市场元信息└── skills/市场提供的Skills├── pdf/PDF处理相关Skill├── docx/Word文档处理相关Skill└── frontend-design/前端设计相关Skill

（2）skills/ – 分层存储
Skills 按使用范围做分层存储，适配不同场景的功能定制，层级关系如下：

（3）todos/ – 任务列表存储


存储路径：~/.claude/todos/{session-id}-*.json；


关联关系：文件名包含对应Session ID，确保任务与对话上下文绑定；


内容类型：存储TodoWrite工具生成的任务列表（含任务描述、状态、优先级等）。


（4）local/ – 本地工具存储


核心内容：claude 可执行文件（CLI工具入口）、node_modules/（本地运行依赖）；


作用：保障Claude Code在本地环境独立运行，无需依赖外部服务。


（5）其他补充目录


shell-snapshots/：存储Shell会话的状态快照（如当前目录、环境变量），支持Shell操作回溯；


plans/：存储Plan Mode生成的执行计划（如多步骤编程任务的分解流程）；


statsig/：缓存特性开关配置（如是否启用新功能），减少重复请求；


telemetry/：存储匿名遥测数据（如功能使用频率），用于产品优化；


debug/：存储调试日志（含错误堆栈、执行流程），方便问题排查。