Lisondreamlison163.com,v1.0.0,2026.06.21Claude Code教程 -03- 文件目录解析及运行逻辑文章目录Claude Code教程 -03- 文件目录解析及运行逻辑Claude Code 本地目录结构解析核心目录详解projects目录项目数据的大本营history.jsonl全局命令索引todos目录任务追踪系统项目级配置目录.claude配置文件层次结构与优先级配置项完整说明一条命令的完整数据流程命令解析与会话初始化网络请求与 API 交互工具调用与本地执行响应处理与本地更新隐私和安全共享账号是否会导致本地数据泄漏共享账号会泄漏什么本地使用时仍需注意的风险推荐的最小安全配置禁止读取敏感文件使用环境变量存放 API Key限制本地目录权限数据流动可视化示意图常见问题解答Claude Code 会上传我的整个代码库吗我可以完全离线使用 Claude Code 吗共享账号安全吗如何彻底删除我的对话历史permissions.deny 真的可靠吗实战技巧使用 CLAUDE.md 减少重复上传配置 Hooks 自动化流程自定义斜杠命令加速工作流附参考资料Claude Code 本地目录结构解析当你第一次运行claude命令时系统会在你的主目录下创建~/.claude文件夹。让我们先看看这个目录里藏着什么秘密目录解析如下目录备注debug调试日志和错误信息file-history文件修改历史记录history.jsonl全局命令历史跨项目ideIDE 集成相关配置projects项目级别的会话数据shell-snapshotsShell 命令执行快照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团队共享配置应提交到 Gitsettings.local.json个人配置不应提交需加入 .gitignoreCLAUDE.md项目上下文和指令.mcp.jsonMCP 服务器配置commands/自定义斜杠命令配置文件层次结构与优先级Claude Code 使用分层配置系统优先级从高到低如下配置层级文件路径用途是否提交 Git托管配置由 IT 部门管理企业级策略无法覆盖-命令行参数claude --modelopus临时会话覆盖-本地项目配置.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-namemarketplace”: 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 KeyexportANTHROPIC_API_KEYsk-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/docsClaude Code Settings 配置指南 https://code.claude.com/docs/en/settingsClaude Code CLI 速查表Shipyard https://shipyard.build/blog/claude-code-cheat-sheet/settings.json 开发者指南eesel.ai https://www.eesel.ai/blog/settings-json-claude-codeAnthropic 隐私政策 https://www.anthropic.com/legal/privacyClaude Code 社区配置示例 https://github.com/feiskyer/claude-code-settings