Claude Code教程 -03- 文件目录解析及运行逻辑
·
Lison <dreamlison@163.com>, v1.0.0, 2026.06.21
Claude Code教程 -03- 文件目录解析及运行逻辑
文章目录
Claude Code 本地目录结构解析
当你第一次运行 claude 命令时，系统会在你的主目录下创建 ~/.claude 文件夹。让我们先看看这个目录里藏着什么秘密：
目录解析如下：
| 目录 | 备注 |
|---|---|
| debug | 调试日志和错误信息 |
| file-history | 文件修改历史记录 |
| history.jsonl | 全局命令历史（跨项目） |
| ide | IDE 集成相关配置 |
| projects | 项目级别的会话数据 |
| shell-snapshots | Shell 命令执行快照 |
| statsig | 统计和特性开关数据 |
| todos | 任务列表的 JSON 数据 |
核心目录详解
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
| 文件 | 描述 |
|---|---|
| settings.json | 团队共享配置（应提交到 Git） |
| settings.local.json | 个人配置（不应提交，需加入 .gitignore） |
| CLAUDE.md | 项目上下文和指令 |
| .mcp.json | MCP 服务器配置 |
| commands/ | 自定义斜杠命令 |
配置文件层次结构与优先级
Claude Code 使用 分层配置系统，优先级从高到低如下：
| 配置层级 | 文件路径 | 用途 | 是否提交 Git |
|---|---|---|---|
| 托管配置 | 由 IT 部门管理 | 企业级策略（无法覆盖） | - |
| 命令行参数 | claude --model=opus |
临时会话覆盖 | - |
| 本地项目配置 | .claude/settings.local.json |
个人项目设置（如 API Key） | 否 |
| 共享项目配置 | .claude/settings.json |
团队共享设置 | 是 |
| 用户全局配置 | ~/.claude/settings.json |
个人全局默认 | - |
| 遗留配置 | ~/.claude.json |
旧版配置文件 | - |
配置示例：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"
}
}
配置项完整说明
| 配置项 | 类型 | 说明 | 示例 |
|---|---|---|---|
| permissions.allow | 数组 | 允许的工具和路径（支持通配符） | “Read(./src/**)” |
| permissions.deny | 数组 | 拒绝访问的工具和路径 | “Read(./.env)” |
| permissions.ask | 数组 | 需要确认的操作 | “Bash(*)” |
| env | 对象 | 环境变量设置 | {“API_KEY”: “xxx”} |
| commit.attribution | 字符串 | Git 提交署名 | “Co-Authored-By: Claude” |
| pr.attribution | 字符串 | PR 描述附加信息 | “Generated by Claude” |
| enabledPlugins | 对象 | 启用的插件列表 | {“plugin-name@marketplace”: true} |
| model | 字符串 | 默认模型选择 | “claude-sonnet-4-5-20250929” |
参考文档：Claude Code Settings
一条命令的完整数据流程
让我们追踪一条简单的命令 claude "帮我创建一个 README.md 文件" 的完整生命周期。
命令解析与会话初始化
用户输入 → CLI 解析 → 加载配置层次 → 检查权限 → 创建会话 ID
本地文件操作：
- 读取 ~/.claude/settings.json 和 .claude/settings.local.json
- 加载 .claude/CLAUDE.md（如果存在）作为上下文
- 在 ~/.claude/projects// 创建新的 .jsonl 会话文件
- 向 ~/.claude/history.jsonl 追加命令记录
网络请求与 API 交互
构建 API 请求 → 发送到 Anthropic 服务器 → 流式接收响应
上传到服务器的数据：
- 用户的提示词：“帮我创建一个 README.md 文件”
- 系统提示词：包含 Claude Code 的工具定义和行为规则
- 上下文内容：
- claude/CLAUDE.md 的内容（如果存在）
- 之前的对话历史（如果是继续会话）
- 读取的文件内容（如果 Claude 请求读取）
- 权限配置：允许/拒绝的工具列表
不会上传的数据：
- 本地文件系统的完整结构
- 未被 Claude 明确请求读取的文件内容
- 其他项目的会话历史
- 你的 API Key 或敏感环境变量
工具调用与本地执行
Claude 可能会请求使用以下工具（取决于权限配置）：
| 工具名称 | 作用 | 本地操作 | 数据上传 |
|---|---|---|---|
Read |
读取文件 | 读取指定文件内容 | 文件内容发送到服务器 |
Write |
写入文件 | 创建或覆盖文件 | 仅记录操作，不上传文件内容 |
Edit |
编辑文件 | 字符串替换操作 | 仅记录操作 |
Bash |
执行命令 | 运行 Shell 命令 | 命令输出发送到服务器 |
Glob |
搜索文件 | 匹配文件路径 | 文件路径列表发送到服务器 |
Grep |
搜索内容 | 搜索文件内容 | 匹配的行内容发送到服务器 |
关键安全点：
- Claude 必须先调用
Read工具才能看到文件内容 - 你可以通过
permissions.deny阻止访问敏感文件 - 每个工具调用都会记录在
.jsonl会话文件中
响应处理与本地更新
接收流式响应 → 显示在终端 → 记录到会话文件 → 更新 token 统计
本地文件写入：
- 会话记录保存到
~/.claude/projects/<project-hash>/<session-id>.jsonl - 如果执行了
Write或Edit，修改历史保存到~/.claude/file-history/ - Token 使用统计更新到
~/.claude/statsig/
隐私和安全
共享账号是否会导致本地数据泄漏？
不会。 Claude CLI / Claude Code 的本地配置、历史记录 和项目文件（如 ~/.claude/*）
只存在于当前机器，不会因为共享账号或 API Key 而同步到其他设备。
如果你在机器 A 使用 Claude， 即使他人在机器 B 使用同一账号或 Key， 也无法看到你机器 A 上的任何本地文件或历史记录。
共享账号会泄漏什么？
共享账号或 API Key 的风险，不在本地文件，而在你“发送出去的内容”
| 泄漏场景 | 会泄漏的内容 |
|---|---|
| 共享账号 / API Key | 你发送给 Claude 的 Prompt、代码、业务描述 |
| 使用第三方中转或代理 | 请求中的全部明文内容 |
| API Key 被他人持有 | 他人可完全冒充你调用 Claude |
简单理解：Key = 你的身份，共享 Key 就是共享“你本人”。
本地使用时仍需注意的风险
以下风险 只影响当前机器，与其他设备无关：
| 数据 | 存储位置 | 风险 |
|---|---|---|
| 对话历史 | ~/.claude/projects/ |
机器被共用或入侵时可被读取 |
| 使用记录 | ~/.claude/history.jsonl |
暴露项目路径与使用习惯 |
| API Key | 本地配置或环境变量 | 被读取后可被完全滥用 |
推荐的最小安全配置
禁止读取敏感文件
{
"permissions": {
"deny": [
"Read(./.env)",
"Read(./secrets/**)",
"Read(./**/*.key)",
"Read(./**/*.pem)"
]
}
}
使用环境变量存放 API Key
export ANTHROPIC_API_KEY="sk-ant-xxx"
限制本地目录权限
chmod 600 ~/.claude/settings.json
chmod 700 ~/.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
欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。
更多推荐
1
0- 0
已为社区贡献3条内容
所有评论(0)