Claude Code教程 -03- 文件目录解析及运行逻辑

Lison<dreamlison@163.com>,v1.0.0,2026.06.21

Claude Code教程 -03- 文件目录解析及运行逻辑

Claude Code 本地目录结构解析

当你第一次运行claude命令时，系统会在你的主目录下创建~/.claude文件夹。让我们先看看这个目录里藏着什么秘密：

目录解析如下：

核心目录详解

projects目录：项目数据的大本营

每个项目都有一个独立的子目录，命名规则是将项目路径转换为目录名（斜杠替换为连字符）。例如：

~/.claude/projects/ ├── -Users-lison-tutorial-claude-code-tutorial-xxx/ │ ├── .timelines/# 时间线数据│ ├── 364a3124-a230-4546-87e7-056454e7eb9f.jsonl# 对话会话记录│ └── settings.json# 项目级配置（如果存在）

每个.jsonl文件记录了完整的对话历史，包括：

• 用户输入的命令和问题
• Claude 的回复和工具调用
• 上下文管理和 token 使用情况
• 时间戳和会话元数据

history.jsonl：全局命令索引

这个文件记录你在所有项目中执行过的命令，格式如下：

{"display":"run /login","pastedContents":{},"timestamp":1773820339943,"project":"/Users/lison/work/workspace/project_a/test-project","sessionId":"xxxxxx"}

重要提示：这个文件包含你的项目路径信息，如果共享账号，其他人可以看到你曾经访问过哪些项目目录。

todos目录：任务追踪系统

Claude Code 的任务管理功能会在这里存储 JSON 文件，每个文件对应一个任务列表。文件命名格式：

<session-id>-agent-<agent-id>.json

项目级配置目录：.claude

在你的项目根目录下，Claude Code 还会创建.claude/配置目录：

your-project/ └── .claude/ ├── settings.json ├── settings.local.json ├── CLAUDE.md ├── .mcp.json └── commands/ ├── review.md └── test.md

配置文件层次结构与优先级

Claude Code 使用分层配置系统，优先级从高到低如下：

配置示例：settings.local.json

{"permissions":{"allow":["Read(//Users/lison/Library/**)","Read(//Users/lison/.config/**)","WebFetch(domain:code.claude.com)","WebSearch"],"deny":["Read(./.env)","Read(./secrets/**)"],"ask":[]},"env":{"ANTHROPIC_API_KEY":"your-api-key-here"}}

配置项完整说明

参考文档：Claude Code Settings

一条命令的完整数据流程

让我们追踪一条简单的命令claude "帮我创建一个 README.md 文件"的完整生命周期。

命令解析与会话初始化

用户输入 → CLI 解析 → 加载配置层次 → 检查权限 → 创建会话 ID

本地文件操作：

1. 读取 ~/.claude/settings.json 和 .claude/settings.local.json
2. 加载 .claude/CLAUDE.md（如果存在）作为上下文
3. 在 ~/.claude/projects// 创建新的 .jsonl 会话文件
4. 向 ~/.claude/history.jsonl 追加命令记录

网络请求与 API 交互

构建 API 请求 → 发送到 Anthropic 服务器 → 流式接收响应

上传到服务器的数据：

• 用户的提示词：“帮我创建一个 README.md 文件”
• 系统提示词：包含 Claude Code 的工具定义和行为规则
• 上下文内容：
  • claude/CLAUDE.md 的内容（如果存在）
  • 之前的对话历史（如果是继续会话）
  • 读取的文件内容（如果 Claude 请求读取）
• 权限配置：允许/拒绝的工具列表

不会上传的数据：

• 本地文件系统的完整结构
• 未被 Claude 明确请求读取的文件内容
• 其他项目的会话历史
• 你的 API Key 或敏感环境变量

工具调用与本地执行

Claude 可能会请求使用以下工具（取决于权限配置）：

关键安全点：

• Claude 必须先调用Read工具才能看到文件内容
• 你可以通过permissions.deny阻止访问敏感文件
• 每个工具调用都会记录在.jsonl会话文件中

响应处理与本地更新

接收流式响应 → 显示在终端 → 记录到会话文件 → 更新 token 统计

本地文件写入：

1. 会话记录保存到~/.claude/projects/<project-hash>/<session-id>.jsonl
2. 如果执行了Write或Edit，修改历史保存到~/.claude/file-history/
3. Token 使用统计更新到~/.claude/statsig/

隐私和安全

共享账号是否会导致本地数据泄漏？

不会。Claude CLI / Claude Code 的本地配置、历史记录 和项目文件（如 ~/.claude/*）
只存在于当前机器，不会因为共享账号或 API Key 而同步到其他设备。

如果你在机器 A 使用 Claude， 即使他人在机器 B 使用同一账号或 Key， 也无法看到你机器 A 上的任何本地文件或历史记录。

共享账号会泄漏什么？

共享账号或 API Key 的风险，不在本地文件，而在你“发送出去的内容”

简单理解：Key = 你的身份，共享 Key 就是共享“你本人”。

本地使用时仍需注意的风险

以下风险只影响当前机器，与其他设备无关：

推荐的最小安全配置

禁止读取敏感文件

{"permissions":{"deny":["Read(./.env)","Read(./secrets/**)","Read(./**/*.key)","Read(./**/*.pem)"]}}

使用环境变量存放 API Key

exportANTHROPIC_API_KEY="sk-ant-xxx"

限制本地目录权限

chmod600~/.claude/settings.jsonchmod700~/.claude/projects/

一句话总结：

本地文件不会跨设备泄漏，真正泄漏的，永远是你“主动发出去的内容”。

数据流动可视化示意图

─────────────────────────────────────────────────────────────── 用户输入命令 claude "帮我创建文件" ───────────────────────────┬─────────────────────────────────── │ ▼ ─────────────────────────────────────────────────────────────── 本地配置加载 ~/.claude/settings.json ─┐ .claude/settings.json ├─→ 合并配置 → 权限检查 .claude/CLAUDE.md ─┘ ───────────────────────────┬─────────────────────────────────── │ ▼ ─────────────────────────────────────────────────────────────── 创建本地会话记录 ~/.claude/projects/<project>/ └── <session-id>.jsonl ← 开始记录 ───────────────────────────┬─────────────────────────────────── │ ▼ ─────────────────────────────────────────────────────────────── 构建 API 请求并发送 上传内容： • 用户提示词 • 系统提示词（工具定义） • CLAUDE.md 内容 • 权限配置 HTTPS → Anthropic API 服务器 ───────────────────────────┬─────────────────────────────────── │ ▼ ─────────────────────────────────────────────────────────────── Claude 流式响应 可能包含工具调用： • Read("/path/to/file") → 读取文件 • Write(...) → 创建 / 修改文件 • Bash("ls -la") → 执行命令 ───────────────────────────┬─────────────────────────────────── │ ▼ ─────────────────────────────────────────────────────────────── 本地工具执行 权限检查 → 执行操作 → 返回结果 结果上传到服务器 ← 供 Claude 下一步推理使用 ───────────────────────────┬─────────────────────────────────── │ ▼ ─────────────────────────────────────────────────────────────── 最终响应与本地保存 • 显示在终端 • 保存到 .jsonl 会话文件 • 更新 file-history/（如有文件修改） • 更新 history.jsonl ───────────────────────────────────────────────────────────────

常见问题解答

Claude Code 会上传我的整个代码库吗？

不会。Claude 只能访问你明确授权的文件。它需要先调用Read工具才能看到文件内容，且每次调用都会受到权限系统的控制。

我可以完全离线使用 Claude Code 吗？

不可以。Claude Code 的核心推理能力依赖于 Anthropic 的云端 API。但你可以控制哪些数据被发送到服务器。

共享账号安全吗？

不推荐。虽然 Anthropic 服务器端的数据是隔离的，但本地的~/.claude/目录会包含所有用户的项目路径和对话历史。如果多人共用同一台机器和账号，存在隐私泄漏风险。

如何彻底删除我的对话历史？

# 删除所有项目会话rm-rf~/.claude/projects/# 删除全局命令历史rm~/.claude/history.jsonl# 如果要完全重置rm-rf~/.claude/

permissions.deny真的可靠吗？

根据第三方测试（参考 eesel.ai 博客），deny 规则偶尔会被忽略。最佳实践：

• 使用多层防护（文件权限 + deny 规则）
• 不要将敏感文件放在项目目录
• 定期审查 debug 日志

实战技巧

使用 CLAUDE.md 减少重复上传

如果你有固定的项目上下文（如编码规范、架构说明），写入.claude/CLAUDE.md：

# 项目上下文 ## 技术栈 - 后端：Python + FastAPI - 数据库：PostgreSQL - 测试：pytest ## 编码规范 - 使用 Black 格式化 - 类型提示必填 - 测试覆盖率 > 80%

这样 Claude 会自动在每次会话开始时加载这些信息，无需每次对话都重新说明。

配置 Hooks 自动化流程

在.claude/settings.json中配置钩子，在工具执行后自动运行命令：

{"hooks":{"after:Write":[{"command":"black {file_path}","if":"{file_path} matches **/*.py"}]}}

参考文档：Claude Code Hooks

自定义斜杠命令加速工作流

在.claude/commands/review.md创建命令：

请对当前项目的代码进行审查，重点关注： 1. 安全漏洞 2. 性能问题 3. 代码风格一致性 输出 Markdown 格式的报告。

使用：

claude /review

附参考资料：

• Claude Code 官方文档：https://code.claude.com/docs
• Claude Code Settings 配置指南： https://code.claude.com/docs/en/settings
• Claude Code CLI 速查表（Shipyard）： https://shipyard.build/blog/claude-code-cheat-sheet/
• settings.json 开发者指南（eesel.ai）： https://www.eesel.ai/blog/settings-json-claude-code
• Anthropic 隐私政策 ：https://www.anthropic.com/legal/privacy
• Claude Code 社区配置示例： https://github.com/feiskyer/claude-code-settings