很多人以为自己在“配置 Claude Code”，其实只是写了一个 CLAUDE.md。这在早期够用，但到了真正的工程实战阶段，已经远远不够了。

最近重新梳理 Claude Code 官方文档后，我对它的配置体系有了一个更明确的判断：

Claude Code 的重点已经不是“某一个配置文件怎么写”，而是“不同层级的配置应该各放在哪”。

如果这个边界没想清楚，就会反复出现几类问题：

所以这篇文章不再把重点放在“单独讲 CLAUDE.md”，而是从工程角度讲透 5 个问题：

  1. Claude Code 现在到底有哪些配置层
  2. CLAUDE.md、settings.json、Skills、MCP 各自负责什么
  3. 团队共享规则和个人偏好应该如何分层
  4. 哪些旧习惯已经不适合现在的 Claude Code
  5. Java 后端团队落地时，一套更稳的目录结构该怎么设计

如果你现在还把 Claude Code 的配置理解成“写个项目说明 + 配几个命令”，这篇文章会帮你把整个模型重新理顺。

一、先纠正一个最常见的误区：Claude Code 已经不是 .clauderc 时代了

先讲结论：

现在 Claude Code 的官方配置主轴，是 settings.json + scoped config + skills + MCP，而不是一个包打天下的 .clauderc。

这点非常重要，因为很多中文资料还停留在“项目里放一个 .clauderc，再写个 CLAUDE.md”的阶段。这样讲并不是完全错误，但已经不能准确反映今天 Claude Code 的配置体系。

按照现在更清晰的官方模型，配置至少分成下面几类：

也就是说，现在真正有价值的问题已经从：

变成了：

这就是配置工程化的起点。

二、先理解作用域：Claude Code 不是只有“全局”和“项目”两层

很多人配置总出问题，不是因为不会写 JSON，而是因为对 scope 没概念。

Claude Code 现在的配置作用域，可以概括成四层：

作用域 典型位置 谁会受到影响 是否共享
Managed 系统托管 / MDM / 受管控配置 机器上的所有用户 是
User ~/.claude/ 你自己，跨所有项目 否
Project .claude/ / 项目根配置 这个仓库的所有协作者 是
Local .claude/settings.local.json 你自己在这个仓库里 否

这四层不是摆设，它直接决定一条配置该放哪里。

1）Managed：安全底线和企业级强制策略

这一层最像“组织规则”。

适合放：

如果某条规则是“任何人在任何项目里都不能绕过”，那它就不该放在 User，更不该放在 Local。

2）User：你的个人长期偏好

适合放：

这一层的关键词是：长期、个人、跨项目。

3）Project：团队共同遵守的工程规则

这是最容易产生价值的一层。

适合放：

凡是“只要在这个仓库里工作，大家都应该遵守”的东西，优先考虑 Project。

4）Local：个人在某个项目里的实验和覆盖

适合放：

Local 的意义不是“随便乱改”，而是让“我的临时需要”和“团队共享规则”解耦。

三、理解优先级，比理解文件路径更重要

配置分层之后，还要理解它们怎么相互覆盖。

Claude Code 当前可以概括为这样的优先级顺序：

  1. Managed（最高，不能被覆盖）
  2. 命令行参数
  3. Local
  4. Project
  5. User

这个顺序非常有工程意义。

一个典型例子

假设：

再比如：

这意味着一个非常重要的实践原则：

安全底线放高优先级，团队协作规则放 Project，个人习惯放 User，实验性调整放 Local。

只要这个原则不乱，配置体系通常就不会太乱。

四、CLAUDE.md 的职责：它不是“万能配置文件”，而是长期行为说明书

很多人把 CLAUDE.md 写成两种极端：

这两种都不对。

CLAUDE.md 最适合放什么

我更推荐把它理解成：

Claude 在这个项目里工作的长期说明书。

它最适合承载的是：

这些内容有个共同点：

CLAUDE.md 不适合放什么

不适合放：

这些东西更应该进 settings.json、Local 配置或其他系统文件，而不是把 CLAUDE.md 变成一个万能收纳箱。

一个更准确的判断方法

如果某条信息回答的是：

这两个问题分清楚，CLAUDE.md 的边界就清楚了。

五、settings.json 的职责：系统行为、权限和默认模式

如果说 CLAUDE.md 解决的是“认知边界”，那 settings.json 解决的就是“运行边界”。

它更像 Claude Code 的系统控制面。

适合放在 settings.json 里的内容

典型包括：

举个最常见的例子：

为什么这层特别重要

因为很多团队会犯一个错误：

把“应该由系统控制的行为”，写成“提示词里的原则”。

例如你在 CLAUDE.md 里写：

这当然有帮助，但这仍然偏“软约束”。

如果这件事真的重要，更稳的做法应该是：

也就是：

认知上提醒一次，系统上再拦一次。

这才是工程化，而不是只靠模型“自觉”。

六、Skills 的职责：别再把“复用工作流”理解成 alias 了

这几年一个很容易过时的认知是：

“我给 Claude 配几个快捷命令 / aliases，不就等于工作流复用了？”

现在这个理解已经明显不够了。

根据官方最新方向，自定义命令已经逐步并入 Skills 体系。旧的命令方式可能仍然兼容，但真正更有扩展性的路径，是 Skill。

Skill 比“命令别名”强在哪

一个 Skill 不只是把一句 prompt 起个名字，它可以有：

换句话说：

Skill 更像“可复用能力模块”，而不是“命令缩写”。

哪些东西适合写成 Skill

例如：

这些都不只是“一句 prompt”，而是一个相对稳定、可多次复用、最好还能携带模板与参考资料的工作流。

Skill 最适合解决什么问题

它解决的是：

所以今天更推荐的思路，不是：

而是：

这两者在工程可维护性上差很多。

七、MCP 的职责：连接外部世界，而不是替代项目规范

MCP 也经常被误放位置。

有的人把 MCP 配得很热闹，结果 Claude 还是总做错事；有的人把所有项目上下文都想塞给 MCP，结果配置复杂度越来越高。

原因通常是：没有把 MCP 的职责想清楚。

MCP 更适合回答的问题是：

它不适合替代的是：

所以我更推荐这样理解：

这四层各司其职，系统才稳定。

八、一个最实用的分层原则：四类信息，分别放到四个地方

如果你觉得前面还是抽象，我给你一个非常落地的分法。

第一类：长期规则 → CLAUDE.md

例如：

第二类：运行行为 → settings.json

例如：

第三类：复用流程 → Skills

例如：

第四类：外部接入 → MCP

例如：

这套分法最大的优点是：

九、Java 后端团队的一套推荐目录结构

如果你是 Java 后端团队，我更推荐从下面这样的结构开始：

project-root/
├── CLAUDE.md
├── .claude/
│   ├── settings.json
│   ├── settings.local.json        # 本地覆盖，不提交
│   ├── skills/
│   │   ├── review-java-pr/
│   │   │   └── SKILL.md
│   │   ├── write-service-tests/
│   │   │   └── SKILL.md
│   │   └── trace-transaction/
│   │       └── SKILL.md
│   └── agents/
│       ├── code-reviewer.md
│       └── debugger.md
├── .mcp.json
├── docs/
│   ├── api-standards.md
│   ├── error-codes.md
│   └── database-conventions.md
└── src/

这个结构为什么更稳

CLAUDE.md

放核心规则：

.claude/settings.json

放仓库级运行规则：

.claude/skills/

放团队高频可复用工作流：

.mcp.json

放项目级外部连接：

这样以后团队里有人加一条新规则，不会再陷入“这条到底该写到哪”的混乱。

十、最容易犯的 6 个错误

错误一：把 CLAUDE.md 写成 README

README 是给人快速理解项目的，CLAUDE.md 是给 Claude 执行工作时长期遵守的。

两者可以相关，但不应该混为一谈。

错误二：把项目规范写进 User 层

结果就是你切项目以后，Claude 还带着上一个仓库的习惯。

项目规范应该尽量沉淀在仓库里，而不是个人全局配置里。

错误三：把安全底线只写在 prompt 里

“不要读 secrets”如果真的重要，就应该进入 permissions deny，而不是只靠提醒。

错误四：把 Skill 当成 alias

这样你会低估它的能力，也会让工作流沉淀始终停留在低水平复用阶段。

错误五：所有东西都往 CLAUDE.md 里堆

结果通常是：

错误六：团队共享规则和个人实验不分层

本来只是你本机的一个试验性 Hook，结果直接进了项目配置；或者反过来，本该全团队遵守的规则，却只放在你自己的 Local。

这两种都很常见，也都很伤协作效率。

十一、一个简单但高价值的配置审计清单

如果你准备整理团队的 Claude Code 配置，可以按下面这个顺序审一次：

1）CLAUDE.md 审什么

2）Project settings 审什么

3）Local settings 审什么

4）Skills 审什么

5）MCP 审什么

只要能把这 5 步跑一遍，很多配置混乱问题都会明显减少。

十二、结语：真正成熟的配置，不是文件更多，而是边界更清楚

很多人一听“配置工程化”，第一反应是：

但真正成熟的配置工程化，从来不是“文件数量变多”，而是：

每种信息终于被放到了它该在的位置。

这会带来几个非常实际的好处：

这也是我这轮重新学习后最明确的一个结论：

今天真正值得花时间优化的，不只是 CLAUDE.md 本身，而是整个 Claude Code 配置架构。

如果你现在要开始整理自己的配置，我建议按这个顺序来：

  1. 先收敛 CLAUDE.md，只保留长期有效的项目规则
  2. 再把权限和运行行为迁到 settings.json
  3. 把重复使用的 prompt 升级成 Skills
  4. 最后再接入真正高频有价值的 MCP 系统

这样搭出来的，不是一堆零散配置，而是一套能长期演进的 Claude Code 工程底座。

这比单纯“写一个更长的 CLAUDE.md”，重要得多。