.claude 配置层级

全局、项目、本地——每一层归谁管，该放什么内容

🎯 三个层级

Claude Code 会从三个位置读取配置，并按照从宽到窄的顺序合并：

层级	位置	是否提交到 git	归属	用途
全局	~/.claude/	否（存在本机）	你个人	应用于你机器上所有项目的默认设置
项目	<仓库>/.claude/	是	团队	这个仓库的共享规范、rules、skills 与权限
本地	<仓库>/.claude/settings.local.json	否（已 gitignore）	你个人	你在这个仓库里的个人覆盖配置

💡 判断原则

如果这份配置应该对团队里每个在这个仓库工作的人都一样 → 项目级。如果这是关于你个人机器或跨所有仓库的个人偏好 → 全局级。如果这是仅针对这个仓库的个人例外（比如你给自己预先放行了某个同事还没批准的命令）→ 本地级。

🌐 全局层：~/.claude/

~/.claude/
├── CLAUDE.md          # 每个项目都会加载的个人默认设置
├── settings.json       # 全局权限、hooks、环境变量
└── skills/             # 个人技能，任何项目都能用

这一层用来放"关于你"而不是"关于某个仓库"的内容：你偏好的 commit message 风格、个人快捷方式、到处都会用到的 MCP server（见 MCP），或者像"我喜欢的 PR 描述怎么写"这类技能。

📁 项目层：.claude/（提交到 git）

这是整个工程团队共享的一层。它有两套很容易混淆的机制：

rules/ —— 按文件路径自动加载

.claude/rules/ 下的每个文件都通过 frontmatter 声明自己适用于哪些文件路径。当 Claude Code 涉及匹配的文件时，规则会自动加载——不需要任何触发词。

.claude/rules/
├── controller.md    # paths: ["**/controller/*.java"]
├── service.md       # paths: ["**/service/**/*.java"]
├── mapper.md        # paths: ["**/mapper/*.java"]
└── entity.md        # paths: ["**/entity/*.java"]

---
paths:
  - "**/controller/*.java"
---

# Controller 控制器规范

## 类定义模板
​```java
@RestController
@RequiredArgsConstructor
@RequestMapping("/example")
public class ExampleController {
    private final ExampleService exampleService;
}
​```

## 必须遵守
- 仅使用构造函数注入，禁止 `@Autowired`
- 所有返回值使用 `R<T>` 包装
- Controller 禁止编写业务逻辑——委派给 Service 层

💡 rules 适合分层式的固定模式

在分层架构里（controller/service/mapper/entity，或者前端的 components/hooks/api），每一层都有明确、机械化的约定，rules 就特别好用。按路径匹配意味着正确的规范会自动加载，不用 AI（或你）去猜该用哪一条。

skills/ —— 按任务匹配按需加载

和 rules 不同，skills 不跟文件路径绑定——它们跟任务内容本身绑定，通过技能的 description 来匹配。完整介绍见 Claude Skills。

.claude/skills/
├── coding-standards/SKILL.md      # 写代码/评审代码时触发
├── unit-testing/SKILL.md          # 写测试时触发
├── security-standards/SKILL.md    # 涉及鉴权、输入校验、敏感信息时触发
└── database/SKILL.md              # 涉及表结构/迁移/查询时触发

settings.json —— 共享的权限与 hooks

{
  "permissions": {
    "allow": [
      "Bash(mvn test:*)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ]
  }
}

把团队公认安全的默认配置提交在这里：大家都应该能不经确认就运行的命令（测试命令、只读的 git 命令、lint 检查）。

🔒 本地层：settings.local.json（已 gitignore）

个人、仅针对这个仓库的覆盖配置——永远不提交。常见内容：你给自己预先放行的额外权限、个人的 MCP server 凭证，或者和团队默认略有不同的白名单。

{
  "permissions": {
    "allow": [
      "WebFetch(domain:github.com)",
      "Bash(gh api:*)",
      "Read(//Users/you/.claude/plugins/cache/**)"
    ]
  }
}

⚠️ 绝不能提交 settings.local.json

它本来就该是个人的、跟机器绑定的——务必确认 .claude/settings.local.json 已经在 .gitignore 里。如果不小心提交了，为某个人的工作流量身定制的权限（更糟的话，还有本地路径/凭证）就会泄露到共享的项目配置里。

🧩 综合起来：一次请求是怎么解析的

当你让 Claude Code"给 controller 加个校验"时，加载顺序如下：

1. 全局 ~/.claude/CLAUDE.md —— 你的个人默认设置（始终加载）
2. 项目 AGENTS.md / CLAUDE.md —— 这个仓库的架构与技术栈（始终加载，见 AGENTS.md）
3. 项目 .claude/rules/controller.md —— 因为你在编辑 controller/ 目录下的文件而自动加载
4. 项目 .claude/skills/dto-validation/SKILL.md —— 因为"校验"匹配到了它的描述而加载
5. 合并后的权限 —— 项目 settings.json 与你个人 settings.local.json 的合并结果

🎉 效果

每一层都恰好贡献它该负责的部分：全局层给出你的个人偏好，项目层给出共享的架构与规范，本地层给出你个人的权限微调——不会有任何一个文件变成无法维护的大杂烩。