Claude Code 如何实现多项目隔离配置?

文章导读
同一台开发机上同时维护多个 Claude Code 项目,最先出问题的往往不是模型回答本身,而是配置互相串。A 项目里加的项目说明,跑到 B 项目里也生效;B 项目封掉的工具权限,在 A 项目里照样拦。这类情况基本可以断定配置放在了错误层级。排查时建议先判断配置落在哪一层,再决定改哪里,直接去改全局用户目录反而会让更多项目受影响。
📋 目录
  1. Ⅰ 先别急着改配置,定位配置落在哪一层
  2. Ⅱ 把项目配置收进项目根目录
  3. Ⅲ 环境变量和 local 文件也会绕过项目隔离
  4. Ⅳ 权限排除规则写太宽,项目会丢上下文
  5. Ⅴ 改完以后用两个项目对照验证
  6. Ⅵ 常见问题:local 文件和普通 settings 同时存在
A A

同一台开发机上同时维护多个 Claude Code 项目,最先出问题的往往不是模型回答本身,而是配置互相串。A 项目里加的项目说明,跑到 B 项目里也生效;B 项目封掉的工具权限,在 A 项目里照样拦。这类情况基本可以断定配置放在了错误层级。排查时建议先判断配置落在哪一层,再决定改哪里,直接去改全局用户目录反而会让更多项目受影响。

先别急着改配置,定位配置落在哪一层

判断当前配置作用于哪个项目,最直接的办法是查看项目根目录是否存在 .claude/settings.json 和 CLAUDE.md。Claude Code 的配置读取顺序是 enterprise 全局配置、用户目录 ~/.claude/ 下的配置,再到项目目录 .claude/ 下的配置,后者会覆盖前者。如果你在 A 项目里改过项目提示词,却在 B 项目也看到同样行为,通常是因为配置放到了用户级而非项目级。

这个顺序给排查圈定了一个范围:同时影响所有项目的变化,优先查用户级目录下的配置;只在单个项目出现的异常,再查项目根目录。enterprise 全局配置一般由团队统一维护,个人开发环境下较少遇到,但如果公司有统一下发策略,本地无法直接覆盖,需要先分清是策略行为还是本地配置行为,再决定要不要向团队申请调整。

把项目配置收进项目根目录

推荐把每个项目的系统提示和工具权限放在项目根目录的 .claude/ 目录内,而不是全局用户目录。具体操作是先在项目里创建 .claude/settings.json,把权限和模型参数写进去;再在项目根目录放一个 CLAUDE.md,写明该项目的技术栈和约定。Claude Code 每次启动时会把这两个文件当作项目上下文,离开项目目录就不会加载这些内容。

两个文件的职责可以拆开:settings.json 放工具权限、模型参数这类机器可校验的键;CLAUDE.md 写项目技术栈、目录结构、构建命令等上下文说明。示例配置:

{
  "model": "claude-sonnet-4-5",
  "permissions": {
    "allow": ["Bash(npm run lint)", "Read(src/**)"],
    "deny": ["Bash(rm -rf)"]
  }
}

模型字段名和权限写法在不同版本里并不完全一致,配置后要用实际会话来确认字段被读取,不要假设设置一定生效。

环境变量和 local 文件也会绕过项目隔离

把配置放进项目目录之后,还要排查两类绕过项目级隔离的入口。第一类是环境变量:模型参数在项目级 settings.json 中可以覆盖全局,但 shell 配置文件里的 ANTHROPIC_BASE_URL、ANTHROPIC_MODEL 这类变量会直接作用于所有项目,优先级高于 settings 文件。检查方法是进入项目目录运行 env | grep ANTHROPIC,看到非空输出就说明环境变量层有干扰,需要回 .bashrc 或 .zshrc 里调整。

Claude Code 如何实现多项目隔离配置?

第二类是 settings.local.json。像个人 API key 这类需要跨项目差异化、又不能写进代码仓库的配置,可以放在项目根目录的 .claude/settings.local.json,并加入 .gitignore。local 文件的优先级高于同目录 settings.json,两处不要重复定义同一个键,否则排错时很难判断实际生效的是哪一份。

权限排除规则写太宽,项目会丢上下文

权限粒度是配置隔离里最容易被忽略的一环。settings.json 的 permissions 支持 include 和 exclude 路径,排除规则写太宽,Claude Code 可能读不到项目关键文件,表现为回答缺少上下文,或者反复要求补充信息。配置完成后,先让 Claude 列出当前项目根目录的文件清单,再和实际目录对照。文件缺失时优先检查 permissions.deny 是否覆盖了 src、docs 这类关键目录。

改完以后用两个项目对照验证

验证隔离是否生效,最稳妥的办法是分别在两个项目里运行 Claude Code,并问同一个问题:根据当前项目的 CLAUDE.md,请列出你正在使用的规则。如果回答的内容分别是各自项目文件中的描述,说明隔离成功;如果回答混入了另一个项目的信息,多半是全局 CLAUDE.md 或者用户级 settings 里写了不该写的内容。

验证通过后,把 CLAUDE.md 和 .claude/settings.json 随项目一起提交,settings.local.json 留在本地。之后如果两个项目再次出现相同的行为变化,回查顺序仍然是先环境变量,再用户级目录,最后才是项目目录,这样可以避免重复踩坑。

常见问题:local 文件和普通 settings 同时存在

问:项目根目录同时存在 .claude/settings.json 和 .claude/settings.local.json 时,哪一份生效?答:按通用优先级,settings.local.json 更高。实际使用时建议只把差异键放进 local 文件,同样的键两边都写,会让后续排查变得困难。