1. 三类 .md 文件到底谁管谁从一次权限误判说起Claude Code 里最容易让人踩坑的不是模型能力而是规则文件的作用域。我见过太多人把团队规范写进CLAUDE.local.md结果同事拉下来一脸懵也见过有人把个人调试路径塞进CLAUDE.md提交上去CI 直接报错。核心问题就一句话哪条规则在哪个目录、对谁生效、能不能被add-dir带进来。先把三类文件摆清楚。CLAUDE.md是项目级配置放在项目根目录跟着 Git 走团队共享CLAUDE.local.md是个人本地配置同样在项目根目录但必须进.gitignore只对当前机器当前用户生效~/.claude/CLAUDE.md是全局配置对这台机器上所有项目生效适合放通用代码规范、常用工具链。这三者的加载优先级和覆盖关系直接决定了你写的permissions规则到底会不会被执行。而add-dir是另一条线。它把外部目录挂进当前会话上下文让 Claude 能读到那个目录里的代码和配置。但注意add-dir引入的目录里的CLAUDE.md不会自动变成当前项目的规则文件它只是被当作可读内容。很多人以为add-dir ../shared-utils之后shared-utils/CLAUDE.md里的 permissions 就生效了这是典型误解。权限边界要单独划。这篇就按「目录结构 → 配置片段 → 逐条验证」的顺序把三类 .md 和add-dir的权限边界讲透。适合多目录协作、monorepo、以及需要本地私有配置的开发者。下面所有命令和配置都可以直接复制跟做。2. TaoToken 前置把 Claude Code 的接入底座搭好在讨论规则文件之前得先让 Claude Code 能正常跑起来。Claude Code 本身是 Anthropic 的 CLI 工具但接入层可以用兼容 Anthropic API 协议的服务来承载TaoToken 就是这类接入底座。它的作用是提供统一的 Base URL 和 Key让 Claude Code 的请求有地方发。你需要准备三样东西Base URL、API Key、Model ID。这三件套在 Claude Code 的配置里缺一不可。Base URL 用https://taotoken.net/api注意这个地址不带任何查询参数Key 在控制台的 API Keys 页面生成Model ID 按你实际要用的模型填。配置方式有两种。第一种是环境变量适合临时验证export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_MODELclaude-sonnet-4-20250514第二种是写进 Claude Code 的 settings 文件适合长期使用。路径通常是~/.claude/settings.json内容如下{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Codex 系的工具配置落在~/.codex/auth.json结构类似把 Base URL 和 Key 填进去即可。Cline 或 CC Switch 这类客户端则在各自的 MCP 或 provider 配置里填同样的三件套。这里有个关键点接入配置和规则文件是两层。接入配置决定请求发到哪规则文件决定 Claude 在当前项目里能做什么、读什么。两者不要混在一个文件里。我建议把接入配置放在全局 settings把项目规则放在项目CLAUDE.md把个人偏好放在CLAUDE.local.md。搭好之后先用一条最简单的命令验证接入是否通claude -p 回复 ok如果返回ok说明 Base URL 和 Key 没问题。如果报 401先查 Key 是否复制完整如果报连接失败查 Base URL 是否写成了带路径的形式。这一步过了再往下谈规则文件才有意义。3. 可复制配置三类 .md 的目录结构与 permissions 片段先看目录结构。假设你有两个项目frontend和backend外加一个共享模块shared-utils~/.claude/ └── CLAUDE.md # 全局配置所有项目生效 projects/ ├── frontend/ │ ├── CLAUDE.md # frontend 项目规则提交 Git │ ├── CLAUDE.local.md # 个人本地规则进 .gitignore │ └── src/ ├── backend/ │ ├── CLAUDE.md │ ├── CLAUDE.local.md │ └── src/ └── shared-utils/ ├── CLAUDE.md # 共享模块说明被 add-dir 读取 └── index.js~/.claude/CLAUDE.md放全局规范比如缩进、命名、包管理器# 全局配置 ## 代码规范 - 使用 2 个空格缩进 - 变量命名用 camelCase - 提交信息用英文 ## 工具链 - 包管理器统一用 pnpm - Node 版本 20.xfrontend/CLAUDE.md放项目专属规则提交到 Git# frontend 项目配置 ## 构建 - 构建命令pnpm build - 测试命令pnpm test ## 目录约定 - 组件放 src/components - 工具函数放 src/utilsfrontend/CLAUDE.local.md放个人路径和调试偏好必须加进.gitignore# 本地个人配置 ## 调试 - 本地日志目录/Users/me/logs/frontend - 调试端口9229 ## 个人别名 - 快速构建pnpm build:fast现在说permissions。Claude Code 的权限配置写在 settings 里控制 Claude 能执行哪些命令。项目级权限建议放在项目根目录的.claude/settings.json而不是塞进CLAUDE.md正文。因为CLAUDE.md是给模型读的自然语言指令settings.json才是机器解析的权限清单。frontend/.claude/settings.json示例{ permissions: { allow: [ Bash(pnpm build), Bash(pnpm test), Bash(git status), Bash(git diff:*) ], deny: [ Bash(git push:*), Bash(rm -rf:*) ] } }这段配置的含义是允许 Claude 执行构建、测试、查看 git 状态和 diff禁止它执行 push 和危险删除。注意Bash(git diff:*)里的:*表示允许带任意参数。add-dir的用法是在会话里执行/add-dir ../shared-utils执行后shared-utils目录下的文件对当前会话可读。但它的CLAUDE.md不会覆盖当前项目的规则也不会把shared-utils/.claude/settings.json里的 permissions 合并进来。add-dir只解决「读得到」不解决「规则生效」。这是权限边界的第一条铁律。如果你希望共享模块的规则也生效正确做法是在当前项目的CLAUDE.md里显式引用## 共享模块 - 共享工具位于 ../shared-utils - 使用前先执行 /add-dir ../shared-utils - 共享模块的代码规范见 ../shared-utils/CLAUDE.md这样模型会主动去读但权限仍然由当前项目的 settings 决定。4. 验证请求逐条确认规则在哪生效配置写完必须逐条验证。下面给出一套可复制的验证流程。第一步验证全局配置是否加载。在任意项目里执行claude -p 当前项目用几个空格缩进如果全局~/.claude/CLAUDE.md写了 2 个空格模型应该回答 2 个空格。如果项目CLAUDE.md覆盖成 4 个空格则回答 4 个。这一步确认的是覆盖优先级项目 全局。第二步验证CLAUDE.local.md是否只对本地生效。在frontend目录执行claude -p 本地日志目录在哪应该返回/Users/me/logs/frontend。然后把这个文件临时改名再问一次应该返回「未配置」或类似回答。这一步确认CLAUDE.local.md确实被加载且不影响其他机器。第三步验证add-dir的读取范围。先不加目录问claude -p shared-utils 里有哪些导出函数模型应该回答读不到。然后进入交互模式执行/add-dir ../shared-utils再问同样的问题这次应该能列出函数。这一步确认add-dir解决的是上下文读取。第四步验证 permissions 是否生效。在frontend目录让 Claude 执行一个被 deny 的命令claude -p 帮我执行 git push如果 settings 里 deny 了Bash(git push:*)Claude 应该拒绝或提示无权限。再试一个 allow 的命令claude -p 执行 pnpm test应该正常执行。这一步确认权限清单按项目生效。第五步验证add-dir目录的 permissions 不生效。在shared-utils/.claude/settings.json里写一条 allowBash(node:*)然后回到frontend执行/add-dir ../shared-utils再让 Claude 执行node -v。如果frontend的 settings 没允许这条命令应该被拦。这一步确认权限不跨目录合并。把这五步跑完你对三类 .md 和add-dir的边界就有实感了。实测下来最容易出错的是第四步和第五步因为大家习惯性认为「读得到就能执行」。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth接入和权限配置过程中有几类报错反复出现。逐个拆。401 Unauthorized。最常见的原因是 Key 没填对或 Base URL 写错。检查ANTHROPIC_API_KEY是否完整ANTHROPIC_BASE_URL是否写成https://taotoken.net/api而不是带/v1或其他路径。如果用的是 settings.json确认 JSON 没有语法错误比如多了逗号。改完重启终端再试。local proxy failed。这个报错通常出现在本地有代理层拦截请求时。检查环境变量里有没有残留的HTTP_PROXY、HTTPS_PROXY如果有先 unset 掉再试。另外确认 Base URL 是直连可达的不要经过额外的转发层。reading choices 相关报错。这类错误一般出现在模型返回结构不符合预期时常见于 Model ID 填错。确认ANTHROPIC_MODEL是有效的模型标识不要自己拼写。如果用的是兼容层确认该模型在服务端可用。OAuth 相关报错。Claude Code 某些版本会走 OAuth 流程如果你用的是 API Key 模式需要在 settings 里明确关闭 OAuth 或指定认证方式。检查~/.claude/settings.json里是否有冲突的认证字段必要时清空重配。还有一个高频坑把CLAUDE.local.md提交到了 Git。检查.gitignore是否包含CLAUDE.local.md如果已经提交用git rm --cached CLAUDE.local.md移除跟踪。另一个坑在add-dir引入的目录里放敏感配置。因为add-dir后该目录内容对会话可读不要把密钥、token 放在共享目录的CLAUDE.md里。共享目录只放代码和通用说明。排查时建议按「接入层 → 规则层 → 权限层」的顺序查。接入层看 Base URL 和 Key规则层看三类 .md 的加载顺序权限层看 settings 的 allow/deny。大部分问题在接入层就能定位。6. 语义一致 CTA把接入和权限配置落到实操三类 .md 的边界可以总结成一句话CLAUDE.md管项目、CLAUDE.local.md管个人、~/.claude/CLAUDE.md管全局add-dir只管读不管权限。把这套规则跑通多目录协作和本地私有配置就不会互相打架。如果你还没搭好接入底座先去 TaoToken API Keys 生成 Key再对照 接入文档 把 Base URL 和 Model ID 填进 settings。想先验证模型对话是否正常可以用 模型对话 发一条测试消息。长期做编码和 Agent 协作的话Coding Plan 更适合持续使用。配置过程中遇到权限问题回看第 5 节的排查顺序基本能覆盖 401、proxy、choices、OAuth 这几类报错。