ClaudeCode Local/Project/User Scope 有什么区别？
Claude Code 的所有配置都遵循同一套三层作用域规则。
- User：存在
~/.claude/，仅本机生效但跨项目共享 - Project：存在
.claude/，通过 git 同步给所有团队成员 - Local：存在
.claude/settings.local.json，git 忽略，仅本机生效
优先级：Local > Project > User。所有层级的配置都会加载，相同 key 时高优先级覆盖。
核心原则：越私有、越具体的配置，优先级越高。
实操：团队规范走 Project，个人偏好走 User，本机调试/密钥走 Local。
一句话理解三层作用域
Claude Code 的三层作用域，本质是回答「这条配置归谁管」。
- User：归我管，跟我走，换电脑就消失
- Project：归团队管，进 git 就能同步
- Local：归当前这台机器管，能覆盖 Project 但不进 git
CLAUDE.md、settings.json、skills/、commands/、hooks/ 全都遵循同一套规则，不存在「这个文件只能用 User 作用域」之类的特例。
三层作用域详解
| 作用域 | 物理位置 | 共享范围 | 典型场景 |
|---|---|---|---|
| User | ~/.claude/ | 本机、跨项目 | 个人快捷键、个人 prompt 偏好 |
| Project | <repo>/.claude/ | git 共享，团队可见 | 团队 coding style、项目专属 skill |
| Local | <repo>/.claude/（gitignored） | 仅本机 | 临时调试、本地密钥、覆盖团队配置 |
举几个具体例子：
~/.claude/settings.json—— 个人偏好（语言、模型、主题）<repo>/.claude/settings.json—— 团队约定（必须用 pnpm、commit 规范）<repo>/.claude/settings.local.json—— 本机额外配置（个人 API key 、个人 hook）
CLAUDE.md 同理：
~/.claude/CLAUDE.md—— 个人备忘录<repo>/CLAUDE.md—— 团队 onboarding 必读<repo>/.claude/CLAUDE.local.md—— 我在这个项目上的私人补充
关键区别：User 和 Local 都是「不进 git 的私人配置」，但 User 跨项目、Local 只在本项目。新人最容易把这俩混为一谈。
优先级：Local > Project > User
合并顺序是从低到高加载，冲突时高优先级覆盖：
简单说：所有作用域的配置都会加载，相同 key 时 Local 赢，再次是 Project，再次是 User。不是「选一个生效」，而是「叠加生效」。
记忆口诀：越私有、越具体，优先级越高。
踩过的坑
坑 1：改了 Project 配置不生效
症状：在 <repo>/.claude/settings.json 里改了某个 key，Claude Code 表现却没变。
原因：之前生成过一个 settings.local.json，里面的同名 key 把它覆盖了。
解决：cat .claude/settings.local.json 看看有没有遗留；删掉再试。
坑 2：skill 加完团队成员看不到
症状：本地 ~/.claude/skills/my-skill/ 测试能用，commit 上去别人 clone 下来却用不了。
原因：你放在了 User 作用域，git 里根本没有这个文件。
解决：把 skill 移到 <repo>/.claude/skills/，User 作用域只放纯个人用的。
坑 3：Local 越堆越多
症状：.claude/settings.local.json 写了几十行，已经分不清哪些是必要的。
原因：Local 设计上是「临时覆盖」，不是「私人配置主阵地」。很多人图省事什么都往里塞。
解决：定期 review，长期需要的配置升级到 User 或 Project。
实操建议
CLAUDE.md 分层写法：
~/.claude/CLAUDE.md：个人习惯（"我用 zsh、习惯 ripgrep、Tab 用 2 空格"）<repo>/CLAUDE.md：项目事实（"这是 pnpm workspace monorepo，主包在 packages/core"）<repo>/.claude/CLAUDE.local.md：本机私货（"我本地 8080 端口被占用，用 8081"）
settings.json 同理：
- User：个人模型选择、主题、快捷键
- Project：team-wide lint/format 命令、必装 hooks
- Local：临时 API endpoint、个人 token（注意安全！）
安全警告：Local 作用域虽然不进 git，但别把长期 token 放这里。换机器、pnpm clean 误删、rm -rf .claude 都可能让它消失。真正敏感的密钥用环境变量或专用 secret 管理工具。
一张图总结
| 我想配置什么 | 放哪里 | 进 git 吗 |
|---|---|---|
| 我个人的偏好 | User ~/.claude/ | 不进 |
| 团队要遵守的规范 | Project <repo>/.claude/ | 进 |
| 本机临时调试 | Local <repo>/.claude/ | 不进（自动 gitignore） |
记住一件事：配置位置决定它的归属，决定谁能改它，决定它会不会跟着团队走。犹豫放哪的时候，先问自己一句：「这条配置换一个同事的电脑还有意义吗？」有，就放 Project；没有，就看它是不是跨项目通用——是放 User，否 则放 Local。
References
- Claude Code Documentation —— Anthropic, 2025