1. 先搞清楚 Claude Code 到底把文件放在哪Claude Code 是 Anthropic 推出的命令行编程助手它能读项目、改代码、跑命令还能通过 MCP 接外部工具。但很多人第一次用它的时候最困惑的不是怎么提问而是它到底把配置、记忆、会话记录放在哪些目录里为什么我改了 settings.json 没生效为什么换个项目 CLAUDE.md 就不一样了这些问题的答案全都藏在 Claude Code 的目录结构里。它不像普通 CLI 工具只有一个配置文件而是分成了项目级目录和用户级目录两套体系两套配置会同时加载、按优先级合并。你如果不理清这个结构后面接第三方 API、写 hooks、做团队协作都会踩坑。这篇文章面向刚接触 Claude Code 的开发者我会把项目级和用户级目录逐层拆开给出可以直接复制的目录树和关键配置片段最后再讲怎么把请求接到 TaoToken 这类兼容 Anthropic 协议的服务上并验证目录配置真的生效了。看完你至少能做到三件事知道每个文件该放哪、知道改哪个文件能影响哪个范围、知道怎么用一条命令确认配置被读进去了。Claude Code 的目录设计核心逻辑是「分层覆盖」用户级是全局默认项目级是团队约定本地文件是个人覆盖。理解了这个优先级后面所有配置问题都能自己推理出来。2. 项目级目录逐层拆解与 CLAUDE.md 加载规则项目级目录指的是你当前代码仓库根目录下的.claude/文件夹以及根目录下几个散落的配置文件。它的特点是可以提交到 Git团队成员拉下来就共享同一套规范。先看完整的项目级目录树你可以直接对照自己的仓库project/ ├── CLAUDE.md # 项目级共享指令每次会话自动加载 ├── CLAUDE.local.md # 个人偏好不提交需手动加进 .gitignore ├── .mcp.json # 项目级 MCP 服务器配置团队共享 ├── .worktreeinclude # 指定哪些被忽略的文件要复制到新 worktree └── .claude/ ├── settings.json # 项目共享设置权限、hooks、环境变量、默认模型 ├── settings.local.json # 本地覆盖设置自动被 git 忽略 ├── commands/ # 自定义斜杠命令/project:xxx 触发 │ ├── review.md │ └── ccguide/ │ └── daily.md ├── rules/ # 模块化行为规则自动注入系统提示 │ ├── api-rules.md │ └── frontend/ │ └── **.tsx.md ├── skills/ # 可复用技能模块 │ └── skill-name/ │ └── SKILL.md ├── agents/ # 自定义子代理定义 │ └── code-reviewer.md ├── agent-memory/ # 子代理持久化记忆 ├── hooks/ # Hook 脚本目录 │ └── pre-commit.sh ├── output-styles/ # 自定义输出格式 └── memory/ # 自动捕获的会话事实这里面最常打交道的是CLAUDE.md。它是项目级共享指令每次会话启动时自动加载相当于你给 Claude Code 的一份「项目说明书」。写法上建议包含项目是干什么的、技术栈、目录约定、代码风格、禁止事项。比如# 项目说明 这是一个基于 FastAPI 的订单服务Python 3.11使用 Poetry 管理依赖。 ## 代码规范 - 所有接口必须有 Pydantic 模型校验 - 数据库操作统一走 repository 层禁止在 router 里直接写 SQL - 提交前必须跑 poetry run pytest ## 目录约定 - app/api/ 放路由 - app/services/ 放业务逻辑 - app/models/ 放 ORM 模型CLAUDE.local.md是个人偏好比如你本地想让它用中文回复、或者临时加个调试说明就写这里然后把它加进.gitignore避免污染团队仓库。rules/目录值得单独说。它和CLAUDE.md的区别是支持路径限定。文件名带路径模式时只有匹配到对应文件才会加载。比如frontend/**.tsx.md只在处理frontend/下的.tsx文件时注入**/test_*.py.md只在碰到测试文件时生效。这样你就能把「React 组件规范」和「Python 测试规范」分开写不用全塞进一个大文件里。commands/目录放自定义斜杠命令。文件名就是命令名review.md对应/project:review支持子目录分组ccguide/daily.md对应/project:ccguide/daily。命令文件里写的是提示词模板可以用$ARGUMENTS接收参数。settings.json是项目共享设置权限、hooks、环境变量、默认模型都在这。它和settings.local.json的关系是后者覆盖前者且settings.local.json会被自动 git 忽略适合放个人 token 之类的敏感信息。.worktreeinclude这个文件比较冷门但很实用。当你用 Git Worktree 开新工作区时默认不会带上.gitignore里的文件比如.env。这个文件让你指定哪些被忽略的文件要复制过去规则是双重条件既要被.worktreeinclude匹配又要被.gitignore忽略而且只复制未被追踪的文件保证安全。# .worktreeinclude 示例 .env .env.local .env.* **/.claude/settings.local.json3. 用户级目录与 settings.json 可复制配置片段用户级目录在~/.claude/Windows 下对应%USERPROFILE%\.claude比如C:\Users\你的用户名\.claude。如果你设置了环境变量CLAUDE_CONFIG_DIR所有~/.claude路径都会指向那个变量指定的目录。这一层是全局配置对你当前用户下的所有项目生效。用户级目录结构比项目级复杂得多因为它还存会话记录、缓存、插件等运行时数据~/.claude/ ├── CLAUDE.md # 全局指令适用所有项目 ├── settings.json # 全局设置 ├── settings.local.json # 全局本地覆盖优先级最高 ├── keybindings.json # 自定义快捷键 ├── credentials.json # 认证凭据自动生成别手动改 ├── commands/ # 全局命令/user:xxx 触发 ├── rules/ # 全局规则 ├── skills/ # 全局 Skills ├── agents/ # 全局子代理 ├── agent-memory/ # 全局子代理记忆 ├── output-styles/ # 全局输出样式 ├── themes/ # 自定义主题 ├── plugins/ # 插件系统 ├── projects/ # 项目级记忆存储 │ └── path-encoded/ │ ├── session.jsonl # 完整对话记录 │ └── CLAUDE.md # 个人对该项目的私有记忆 ├── file-history/ # 文件编辑历史用于检查点恢复 ├── sessions/ # 会话元数据 ├── shell-snapshots/ # shell 环境快照 ├── tasks/ # 每会话任务列表 ├── plans/ # 计划模式写入的计划 ├── cache/ # 运行时缓存可安全删除 ├── backups/ # 配置迁移前的备份 ├── history.jsonl # 所有输入过的提示 └── stats-cache.json # token 和费用统计~/.claude.json是另一个关键文件注意它不在.claude/目录里而是在用户主目录下。它存的是状态数据不是配置。最常用的场景是跳过首次登录引导{ hasCompletedOnboarding: true }projects/目录的路径编码规则值得一提。它把项目绝对路径里的分隔符替换成-比如C:\Users\qtz变成C--Users-qtzE:\WorkSpace\HisCode变成e--WorkSpace-HisCode。你如果想找某个项目的对话记录就按这个规则去projects/下找对应目录。自动清理机制也要知道projects/下的会话记录、file-history/、debug/、paste-cache/、image-cache/、tasks/、shell-snapshots/、backups/这些超过cleanupPeriodDays默认 30 天会在启动时被删除。而history.jsonl、stats-cache.json、remote-settings.json是持久保留的。现在讲怎么把请求接到 TaoToken。TaoToken 提供兼容 Anthropic 协议的接口Claude Code 可以通过环境变量指向它。你需要在~/.claude/settings.json里配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的 TaoToken API Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这里三件套必须齐全Base URL指向https://taotoken.net/apiKey填你在控制台生成的 API KeyModel ID填你要用的模型标识。少任何一个都会报错。API Key 的获取入口在 TaoToken API Keys接入细节可以对照 接入文档。如果你不想改全局配置也可以只在项目级.claude/settings.json里写这样只对当前项目生效。团队协作时建议把 Base URL 和 Model ID 提交Key 放settings.local.json里不提交。4. 验证目录配置生效的完整操作步骤配置写完了不代表生效Claude Code 的加载顺序是用户级settings.json→ 用户级settings.local.json→ 项目级settings.json→ 项目级settings.local.json后者覆盖前者。你要验证配置真的被读进去了可以按下面几步操作。第一步确认环境变量被正确注入。启动 Claude Code 后在会话里输入/env这个命令会列出当前生效的环境变量。你应该能看到ANTHROPIC_BASE_URL指向https://taotoken.net/apiANTHROPIC_MODEL是你配置的模型 ID。如果没看到说明配置文件路径写错了或者 JSON 格式有问题。第二步验证CLAUDE.md被加载。在项目根目录启动 Claude Code然后问它请复述一下你当前加载的项目指令里关于代码规范的部分。如果它能说出你写在CLAUDE.md里的内容说明项目级指令加载成功。如果它说没有相关指令检查文件名是不是CLAUDE.md大小写敏感以及是不是在项目根目录。第三步验证自定义命令。如果你在.claude/commands/下建了review.md在会话里输入/project:review看它是否触发。触发不了通常是文件名或目录层级不对。第四步发一个真实请求确认 API 通路。直接问用一句话说明当前使用的模型是什么。如果返回正常说明 Base URL、Key、Model ID 三件套都通了。如果报错对照下一节的排查表。第五步检查会话记录是否落盘。退出后去~/.claude/projects/path-encoded/下看有没有.jsonl文件生成有就说明目录结构工作正常。这里给一个完整的项目级settings.json示例包含权限和 hooks你可以直接复制改{ permissions: { allow: [ Bash(poetry run pytest:*), Bash(git status), Read(**) ], deny: [ Bash(rm -rf:*), Read(.env) ] }, hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: .claude/hooks/pre-commit.sh } ] } ] }, env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }注意permissions.deny里禁止读取.env这是防止密钥被带进上下文的基本操作。hooks 的matcher指定匹配的工具类型command指向脚本路径。5. 目录与接入常见报错排查配置过程中最容易撞上的几类报错我按真实错误信息整理成对照表你遇到时直接查。401 错误返回401 Unauthorized或authentication_error。原因通常是 API Key 没填、填错或者ANTHROPIC_AUTH_TOKEN和ANTHROPIC_API_KEY用混了。Claude Code 读的是ANTHROPIC_AUTH_TOKEN如果你只设了ANTHROPIC_API_KEY它可能读不到。检查settings.json里 env 段的键名确认 Key 没有多余空格。local proxy failed报local proxy failed或连接被拒。这通常是 Base URL 写错比如漏了/api后缀或者写成了带 UTM 参数的完整地址。Base URL 应该是干净的https://taotoken.net/api不要带查询参数。另外检查本地有没有其他工具占用了端口。reading choices 报错出现error reading choices或响应解析失败。这多半是 Model ID 写错了或者你用的模型标识在服务端不存在。确认ANTHROPIC_MODEL填的是服务端支持的模型 ID不要自己编。OAuth 相关报错提示需要登录或 OAuth 流程失败。如果你已经配了第三方 Base URL就不该再走 Anthropic 官方登录。检查~/.claude.json里hasCompletedOnboarding是否为true以及有没有残留的credentials.json干扰。必要时删掉credentials.json让它重新生成。配置不生效改了settings.json但行为没变。先确认文件路径对不对项目级是project/.claude/settings.json用户级是~/.claude/settings.json。再确认 JSON 没有语法错误可以用python -m json.tool settings.json校验。最后确认优先级settings.local.json会覆盖settings.json别改错了文件。CLAUDE.md 没加载检查文件名大小写必须是全大写CLAUDE.md。检查位置必须在项目根目录不是.claude/里面。如果你用了CLAUDE_CONFIG_DIR确认它没把路径指偏。worktree 里配置丢失新建 worktree 后.env不见了。这是正常的因为 worktree 是全新检出不带被忽略的文件。用.worktreeinclude指定要复制的文件注意它只复制未被 Git 追踪的文件。排查时有个通用技巧用claude --debug启动它会把配置加载过程打到~/.claude/debug/下的日志里你能看到每个配置文件是否被读取、有没有解析错误。这比盲猜快得多。6. 把目录结构用起来从配置到长期编码理清目录结构之后你会发现 Claude Code 的配置能力其实是一套分层系统。用户级管全局默认项目级管团队约定本地文件管个人覆盖。你完全可以根据团队规模来决定配置放哪一层。个人开发者重点维护~/.claude/settings.json和~/.claude/CLAUDE.md把常用的模型、Base URL、个人偏好写进去所有项目通用。项目里只放必要的CLAUDE.md说明技术栈。团队协作把项目级.claude/settings.json、CLAUDE.md、commands/、rules/提交到 Git让所有人共享同一套规范和命令。敏感信息放settings.local.json加进.gitignore。如果你打算长期用 Claude Code 做编码和 Agent 任务可以了解下 Coding Plan它更适合高频调用场景。想先验证模型效果可以直接在 模型对话 里试。配置过程中要生成或管理 Key去 控制台 操作。最后提醒一个实用技巧定期清理~/.claude/cache/和~/.claude/todos/前者可安全删除会自动重建后者是旧版遗留不再写入。如果你要彻底清掉某个项目的状态用claude project purge 项目路径 --dry-run先预览删除计划确认无误再去掉--dry-run执行。这个命令不会动~/.claude.json、settings.json和plugins/你的认证和偏好是安全的。