Claude Code 配置

概述

Claude Code 的配置不在一个文件里。settings.json 只是其中一层，~/.claude.json、CLAUDE.md、.claude/rules/、skills、.mcp.json 也都参与生效。

这些文件一旦混着写，配置很快就会变成大杂烩。常见结果是：明明写了规则，却不知道为什么没生效；团队配置和个人偏好混在一起；MCP 放错位置；所有说明都被塞进 CLAUDE.md，最后自己都不想再打开它。

下文按文件职责、目录位置和作用域展开，重点放在六件事上：

settings.json
~/.claude.json
CLAUDE.md
.claude/rules/ 与 .claude/skills/
.mcp.json
作用域和优先级

配置分层

Claude Code 里常见的配置，可以先拆成下面六类。

程序级配置：`settings.json`

这一层负责客户端行为，是最接近传统意义上“配置文件”的部分。

常见内容包括：

permissions
env
hooks
模型相关默认值
插件相关设置
一部分行为控制项

常见位置有三个：

~/.claude/settings.json
./.claude/settings.json
./.claude/settings.local.json

全局状态与用户级 MCP：`~/.claude.json`

这个文件常被和 settings.json 混为一谈，但两者职责不同。

~/.claude.json 主要保存这些内容：

OAuth 或登录状态
主题和界面偏好
一些项目状态
用户级 MCP
当前项目的 local MCP

先记一条：MCP 的 user 和 local 作用域，通常都保存在 ~/.claude.json，不在 settings.json 里。

长期指令：`CLAUDE.md`

CLAUDE.md 不是客户端配置，它是给 Claude 的长期背景说明。

常见内容包括：

仓库结构
技术栈说明
测试命令
团队约定
模块边界
哪些目录不要碰

它解决的是“项目信息怎么告诉 Claude”，不是“权限怎么强制限制”。

规则拆分：`.claude/rules/`

CLAUDE.md 一长，就该拆。

.claude/rules/ 主要解决两件事：

按主题拆规则
按路径选择性生效

规则从这里开始有了明确作用域。

可复用工作流：`.claude/skills/`

Skills 不是零散 prompt，它是 Claude Code 里的结构化工作流单元。

一个 skill 通常会包含：

说明文字
可选 frontmatter 配置
允许使用的工具
自动触发范围
是否只能手动调用
是否在 fork 的子代理里执行

某类任务如果有固定流程，优先做成 skill，不要继续往 CLAUDE.md 里塞。

外部工具接入：`.mcp.json`

MCP 是另一套独立机制，用来把 Claude Code 接到外部工具和系统。

例如：

GitHub
Sentry
Notion
内部平台
数据库
本地脚本服务

项目级 MCP 配置放在 .mcp.json，不和 settings.json 混用。

配置作用域

配置先看作用域，再看字段，不然很容易配到错误位置。

Claude Code 官方文档把常见配置作用域分成四层：

Managed
User
Project
Local

`Managed`

这是企业或 IT 下发的强制配置，优先级最高。

常见目录：

macOS：/Library/Application Support/ClaudeCode/
Linux / WSL：/etc/claude-code/
Windows：C:\Program Files\ClaudeCode\

常见用途：

安全策略
企业统一规则
企业共享 MCP
合规限制

`User`

用户级配置，只对你自己生效，但跨项目可复用。

常见目录：

~/.claude/settings.json
~/.claude/CLAUDE.md
~/.claude/rules/
~/.claude/skills/
~/.claude/agents/

常见用途：

个人偏好
你的常用 skill
你所有项目都会用到的规则

`Project`

项目级配置，放在仓库里，适合提交到 git 给团队共享。

常见位置：

./CLAUDE.md
./.claude/settings.json
./.claude/rules/
./.claude/skills/
./.claude/agents/
./.mcp.json

常见用途：

团队规范
项目专属 skill
项目共享 MCP
项目 hooks

`Local`

本地项目私有配置，只对你、只对当前仓库生效。

常见位置：

./.claude/settings.local.json
./CLAUDE.local.md

常见用途：

你的本地偏好
临时规则
机器相关路径
不想提交进仓库的说明

配置文件位置

下面这张配置地图，解决的是“文件该放哪”。

项目目录里常见的文件

text

your-project/
├── CLAUDE.md
├── CLAUDE.local.md
├── .mcp.json
└── .claude/
    ├── settings.json
    ├── settings.local.json
    ├── rules/
    │   ├── testing.md
    │   └── api.md
    ├── skills/
    │   └── review-pr/
    │       └── SKILL.md
    ├── agents/
    ├── commands/
    └── output-styles/

用户目录里常见的文件

text

~/.claude/
├── CLAUDE.md
├── settings.json
├── rules/
├── skills/
├── agents/
└── projects/

还有一个非常容易被忽略的文件

text

~/.claude.json

它不是通用设置文件，而是全局状态和一部分 MCP 配置的存放位置。

普通配置的优先级

这一条主要适用于 settings.json 这条配置链。

也就是说，同一个设置项如果在多个地方同时存在，通常按下面的顺序决定最终结果：

Managed
CLI 参数
Local
Project
User

实际写配置时，记住两点就够了：团队共享内容放项目级；个人试验性设置放 settings.local.json。

`settings.json` 负责什么

Claude Code 的程序级设置，默认从 settings.json 这条线开始看。

三个最常见的配置文件

~/.claude/settings.json
./.claude/settings.json
./.claude/settings.local.json

最常见的字段

常见字段主要有这些：

permissions
env
hooks
模型默认值
一些运行行为选项

例如，一个比较克制的项目级配置可以写成：

json

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Read"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "NODE_ENV": "development"
  }
}

这个例子主要是为了划清边界：

想控制权限，用 permissions
想注入环境变量，用 env
想做钩子处理，用 hooks

这些内容写进 CLAUDE.md 并不会变成硬限制。

`settings.json` 和 `~/.claude.json` 的边界

这两个文件最容易被混写。

`settings.json` 是正式配置

它是你主动维护的设置文件，适合放：

权限白名单和黑名单
环境变量
hooks
运行行为

`~/.claude.json` 更像运行状态仓库

可以直接当成：

Claude Code 自己维护的一部分状态
用户级和 local 级 MCP 的存放位置
界面偏好和认证信息

~/.claude/settings.json 不是 ~/.claude.json。前者放设置，后者存状态和一部分 MCP。

`CLAUDE.md` 的边界

CLAUDE.md 最容易被写成“万能说明书”。文件一胖，效果通常就开始打折。

`CLAUDE.md` 适合写什么

更合适的内容是长期稳定、且确实属于项目背景的信息：

项目结构
技术栈
开发约束
测试和构建命令
代码组织方式
哪些目录不要改

一个极简例子：

# Project Notes

- 前端在 `apps/web`
- API 在 `apps/api`
- 提交前运行 `pnpm lint && pnpm test`
- 不要修改 `generated/`
- 数据库变更先看 `docs/database.md`

`CLAUDE.md` 不适合写什么

下面这些应该放进硬配置，而不是 CLAUDE.md：

敏感文件访问限制
工具权限边界
真正的拒绝规则
需要确定生效的安全策略

原因很简单：CLAUDE.md 是长期指令，不是客户端层的强制执行规则。

`CLAUDE.local.md`

只在本地生效、又不想提交进仓库的说明，可以放到：

text

CLAUDE.local.md

它适合放：

你的本地工作习惯
当前机器上的特殊路径
只对你有意义的临时说明

通常配合 .gitignore 一起用。

`.claude/rules/` 的作用

CLAUDE.md 写大以后，继续往下堆通常不是好主意，拆到 .claude/rules/ 更好维护。

为什么要拆规则

规则天然有两个维度：

主题不同
适用目录不同

全塞进一个文件里，Claude 每次都会读到一堆和当前任务无关的内容。

规则目录示例

text

.claude/rules/
├── frontend.md
├── backend.md
└── testing.md

`paths` 是规则真正的作用域

规则文件可以带 frontmatter，让它只在某些路径下生效。

例如：

---
paths:
  - "src/api/**/*.ts"
---

# API Rules

- 所有输入都要做校验
- 错误返回统一格式
- 新接口必须补 OpenAPI 注释

这样它只会在 API 代码相关任务里出现，不会污染整个仓库。

`@import`

如果仓库里已经有其他规范文档，也可以在 CLAUDE.md 里通过 @import 引入，而不是复制粘贴。

例如：

@docs/architecture.md

# Claude Notes

- billing 相关修改先读架构文档

大型项目里，这种拆法很省心：入口文件短，细节文档各管各的。

Skills 的配置和作用域

CLAUDE.md 管项目背景，skill 管任务流程。两者分工不同，不该混写。

Skills 放哪

最常见的三个来源是：

用户级：~/.claude/skills/<skill-name>/SKILL.md
项目级：./.claude/skills/<skill-name>/SKILL.md
插件内自带的 skill

这三类来源，本身就是 skill 的第一层作用域。

Skills 的存储作用域

从“放在哪”这个角度看，skill 可以分成三类：

user 作用域：只对你自己生效，跨项目可用
project 作用域：团队共享，跟着仓库走
plugin 作用域：由插件分发，安装插件后可用

团队工作流放项目级；个人习惯放用户级。

一个最小可用的 `SKILL.md`

---
name: review-pr
description: 审查 Pull Request，输出风险、回归点和缺失测试
disable-model-invocation: true
allowed-tools: Bash(gh *), Read, Grep
---

请审查这个 PR：

1. 总结改动目标
2. 找出潜在 bug 和行为回归
3. 指出缺失的测试
4. 输出简洁 review

Skills 的关键字段

常见字段有这些：

name
description
argument-hint
disable-model-invocation
user-invocable
allowed-tools
paths
context
agent
hooks

Skills 的调用作用域

Skills 比较绕的地方，不在存放位置，而在调用条件。

先看四个关键开关。

`user-invocable`

它决定这个 skill 能不能被用户显式调用。

适合手动触发的流程，例如：

review
release
migration check

`disable-model-invocation: true`

它决定模型能不能自动调用这个 skill。

有副作用的 skill，通常应设成 true。例如：

deploy
commit
发通知
改数据库

这样它就不会被模型自动调起来。

`paths`

这是 skill 的文件路径作用域。

例如：

---
name: react-ui-review
description: 审查 React UI 代码质量
paths:
  - "src/**/*.tsx"
  - "components/**/*.tsx"
---

这样它更容易在这些路径相关的上下文里被发现和触发。

`context: fork` 与 `agent`

这是 skill 最接近 agent 工作流的一块。

例如：

---
name: explore-auth
description: 调研认证模块实现并输出风险点
context: fork
agent: Explore
---

这表示 skill 会在 fork 出来的子代理上下文里执行，而不是直接消耗你当前会话的全部上下文。

常见场景：

大范围只读扫描
深度调研
风险分析
PR 结构化总结

Skills 和 `CLAUDE.md` 的边界

判断标准很简单：项目背景写 CLAUDE.md；任务流程写 skill。

MCP 的配置和作用域

MCP 单独成一套配置链，和 settings.json 不是同一路。

MCP 是做什么的

MCP 用来把 Claude Code 接到外部工具和系统。

例如：

GitHub
监控平台
工单系统
内部 API
数据库
本地服务

Claude Code 接上 MCP 后，才算真正接进外部环境。

MCP 有三个常见作用域

local
project
user

这里先别背概念，先记文件位置。

`local` 作用域

这是默认作用域，常见场景包括：

只想自己用
只想在当前项目用
带私密凭据
还在试验

最容易写错的点就在这里：MCP 的 local 作用域不在 ./.claude/settings.local.json，通常写进 ~/.claude.json，并按项目路径组织。

`project` 作用域

项目级 MCP 会保存在项目根目录的：

text

.mcp.json

常见用途：

团队共享服务
项目统一工具
所有人都需要的外部能力

例如：

claude mcp add --transport http github --scope project https://example.com/mcp

生成后的项目配置一般是：

json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

项目级 .mcp.json 第一次使用时，Claude Code 一般会要求审批。

`user` 作用域

用户级 MCP 跨项目可用，但只对你自己生效。

它通常也保存在：

text

~/.claude.json

常见用途：

你自己的常用外部工具
不适合共享给团队的服务
带个人凭据的 MCP

MCP 的优先级和普通 settings 不一样

普通设置常见优先级是：

Managed > CLI 参数 > Local > Project > User

但 MCP 的同名 server 优先级通常是：

local > project > user

同一个 MCP 服务如果三个地方都定义了，一般以 local 为准。

`.mcp.json` 支持环境变量

这对团队共享配置很有用：结构进仓库，敏感值留在环境变量里。

例如：

json

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

这样团队共享的是接入方式，不是每个人的 token。

团队配置和个人配置怎么拆

这一节只说一个原则：团队共享和个人私有分开写。

适合进仓库的内容

这些内容一般放项目级，并提交到 git：

CLAUDE.md
./.claude/settings.json
./.claude/rules/
./.claude/skills/
./.claude/agents/
./.mcp.json

不适合进仓库的内容

这些内容更适合留在用户级或 local：

~/.claude/settings.json
~/.claude/CLAUDE.md
~/.claude/skills/
~/.claude.json
./CLAUDE.local.md
./.claude/settings.local.json

判断标准很直接：所有协作者都该看到的，放项目级；只有你自己需要的，别进仓库。

排错入口

排错时，先看 Claude Code 实际加载了什么。

排错时可以优先看这些命令：

/status：看当前状态和一部分配置来源
/memory：看加载了哪些 CLAUDE.md、规则和记忆
/mcp：看 MCP 服务连接情况
/hooks：看当前 hooks
/doctor：做整体诊断
/help：查看当前可用命令

如果某条规则没生效，先确认它是否真的被加载。
如果某个 MCP 没连上，先确认它到底写在 ~/.claude.json 还是 .mcp.json。
如果某个 skill 没被调用，先检查它的 description、user-invocable、disable-model-invocation 和 paths。

Claude Code 配置 ​

概述 ​

配置分层 ​

程序级配置：settings.json ​

全局状态与用户级 MCP：~/.claude.json ​

长期指令：CLAUDE.md ​

规则拆分：.claude/rules/ ​

可复用工作流：.claude/skills/ ​

外部工具接入：.mcp.json ​

配置作用域 ​

Managed ​

User ​

Project ​

Local ​

配置文件位置 ​

项目目录里常见的文件 ​

用户目录里常见的文件 ​

还有一个非常容易被忽略的文件 ​

普通配置的优先级 ​

settings.json 负责什么 ​

三个最常见的配置文件 ​

最常见的字段 ​

settings.json 和 ~/.claude.json 的边界 ​

settings.json 是正式配置 ​

~/.claude.json 更像运行状态仓库 ​

CLAUDE.md 的边界 ​

CLAUDE.md 适合写什么 ​

CLAUDE.md 不适合写什么 ​

CLAUDE.local.md ​

.claude/rules/ 的作用 ​

为什么要拆规则 ​

规则目录示例 ​

paths 是规则真正的作用域 ​

@import ​

Skills 的配置和作用域 ​

Skills 放哪 ​

Skills 的存储作用域 ​

一个最小可用的 SKILL.md ​

Skills 的关键字段 ​

Skills 的调用作用域 ​

user-invocable ​

disable-model-invocation: true ​

paths ​

context: fork 与 agent ​

Skills 和 CLAUDE.md 的边界 ​

MCP 的配置和作用域 ​

MCP 是做什么的 ​

MCP 有三个常见作用域 ​

local 作用域 ​

project 作用域 ​

user 作用域 ​

MCP 的优先级和普通 settings 不一样 ​

.mcp.json 支持环境变量 ​

团队配置和个人配置怎么拆 ​

适合进仓库的内容 ​

不适合进仓库的内容 ​

排错入口 ​

参考 ​

Claude Code 配置

概述

配置分层

程序级配置：`settings.json`

全局状态与用户级 MCP：`~/.claude.json`

长期指令：`CLAUDE.md`

规则拆分：`.claude/rules/`

可复用工作流：`.claude/skills/`

外部工具接入：`.mcp.json`

配置作用域

`Managed`

`User`

`Project`

`Local`

配置文件位置

项目目录里常见的文件

用户目录里常见的文件

还有一个非常容易被忽略的文件

普通配置的优先级

`settings.json` 负责什么

三个最常见的配置文件

最常见的字段

`settings.json` 和 `~/.claude.json` 的边界

`settings.json` 是正式配置

`~/.claude.json` 更像运行状态仓库

`CLAUDE.md` 的边界

`CLAUDE.md` 适合写什么

`CLAUDE.md` 不适合写什么

`CLAUDE.local.md`

`.claude/rules/` 的作用

为什么要拆规则

规则目录示例

`paths` 是规则真正的作用域

`@import`

Skills 的配置和作用域

Skills 放哪

Skills 的存储作用域

一个最小可用的 `SKILL.md`

Skills 的关键字段

Skills 的调用作用域

`user-invocable`

`disable-model-invocation: true`

`paths`

`context: fork` 与 `agent`

Skills 和 `CLAUDE.md` 的边界

MCP 的配置和作用域

MCP 是做什么的

MCP 有三个常见作用域

`local` 作用域

`project` 作用域

`user` 作用域

MCP 的优先级和普通 settings 不一样

`.mcp.json` 支持环境变量

团队配置和个人配置怎么拆

适合进仓库的内容

不适合进仓库的内容

排错入口

参考