面试官：你说你Vibe Coding手拿把掐，那 Claude Code 用户级、项目级、本地级配置怎么隔离？

Claude Code CLI 配置避坑指南：全局、项目、本地，别再搞混了

本文记录对于 Claude Code 的主要目录及文件的作用，以及一些使用心得，分享给大家，希望帮助大家更好理解与驾驭（Harness） Claude Code CLI。包括 .claude目录、CLAUDE.md、MCP、SKILL、Plugins这几部分。

注：以前发过的安装与介绍的文章，在这里：配置Claude Code CLI及常用工具

重点说明： 1）~/ 代表当前用户的主目录（家目录），在Windows系统中等同于%USERPROFILE% 2）当前日期2026年6月23日，

软件版本：

• • Claude Code CLI：2.1.186 (Claude Code)
• • CC Switch： v3.16.1

1、.claude 目录说明

1.1、用户级（全局）配置

作用范围：对用户电脑上所有的 Claude Code 会话生效。 存储位置：~/.claude/ 目录下，安装后自动创建。

官方中文文档地址见文末

.claude.json
.claude/                  # 用户级（全局）的目录样式参考
├── plugins/              # [目录] 插件及 MCP 服务器安装目录，必须保留
├── skills/               # [目录] 自定义技能定义目录，若有私有技能则必须保留
├── projects/             # [目录] 工作区项目历史记录，可选保留（丢失不影响功能）
├── sessions/             # [目录] 当前会话状态缓存，可选保留（便于中断恢复）
├── file-history/         # [目录] 文件编辑历史版本，可选保留（依赖版本回滚时建议保留）
├── settings.json         # [文件] 用户设置，必须保留
└── CLAUDE.md             # [文件] 全局指令文件，每次会话自动加载，建议保留

• • settings.json： 通用配置
• • settings.local.json： 个人配置（一般排除在.gitignore）

1.2、项目级配置

作用范围：仅对当前所在的项目生效。 存储位置：项目根目录下。默认没有此目录，执行子目录相关操作时会自动创建

CLAUDE.md             # [文件] 项目级核心指令，每次会话自动加载
CLAUDE.local.md       # [文件] 本地个人偏好覆盖，不提交到 git
.mcp.json             # [文件] MCP 服务器配置文件
.worktreeinclude      # [文件] Git worktree 自动包含的文件列表
.claude/
├── settings.json         # [文件] 项目级设置（权限、钩子、环境变量等）
├── settings.local.json   # [文件] 本地个人设置覆盖，不提交到 git【非强制】
├── rules/                # [目录] 按条件加载的模块化规则文件
├── skills/               # [目录] 自定义技能（可通过 / 调用）
├── agents/               # [目录] 子代理定义（专用工具和能力）
├── workflows/            # [目录] 工作流脚本（编排多个子代理）
└── agent-memory/         # [目录] 跨会话持久记忆存储

• • settings.json： 通用配置
• • settings.local.json： 个人配置（一般排除在.gitignore）

2、CLAUDE.md

配置加载优先级（由低到高）：

1. 1. 用户级（~/.claude/CLAUDE.md）—— 基础默认值。
2. 2. 项目级（./CLAUDE.md）—— 覆盖用户级的冲突项。
3. 3. 本地级（./CLAUDE.local.md）—— 最高优先级，覆盖以上所有。

2.1、用户级（全局）

初始化方法：手动创建

文件位置： ~/.claude/CLAUDE.md：存放通用偏好。

• • 示例：请始终使用中文回复等
• • 注意：这里不要放具体项目的技术栈细节。

Github 高star项目：CLAUDE.md参考链接见文末

2.2、项目级

初始化方法： 进入项目，运行 /init 生成 ./CLAUDE.md。

文件位置：./CLAUDE.md（需提交 Git）

• • 存放团队共享的项目规则。
• • 生成方式：在项目目录启动 Claude Code，输入指令 /init，AI 会自动扫描代码生成初版。

2.3、本地项目级（个人）

初始化方法：手动创建

./CLAUDE.local.md（禁止提交 Git）

• • 存放你个人针对此项目的特殊偏好（不干扰团队）。
• • 加载优先级：此文件会覆盖 ./CLAUDE.md 的相同指令。

3、MCP

3.1、用户级（全局）MCP

配置文件路径：~/.claude.json：存放所有项目共用的 MCP 服务器（如浏览器自动化、搜索引擎等）。

作用域：user： 仅您，所有项目。在全局 ~/.claude.json

添加方式：使用 claude mcp add。

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

3.2、项目级MCP

配置文件路径： 项目根目录中的 .mcp.json，需要提交版本控制。

作用域：project： 克隆项目的所有人。仅当前项目需要用到的专用 MCP（如数据库直连、内部 API）。

添加方式：使用 claude mcp add，Claude 会智能识别当前目录，自动生成或更新配置文件。

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

3.3、本地项目级（默认）MCP

配置文件路径： 也是全局的配置文件~/.claude.json ，只是在里面的projects节点中。

作用域：local（默认情况）：仅您， 仅此项目。

添加方式：

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

3.4、MCP 服务器类别：

• • remote HTTP server： 远程 HTTP 服务器，是连接到远程 MCP 服务器的推荐选项。
• • remote SSE server：远程 SSE 服务器，SSE (Server-Sent Events) 传输已弃用。
• • local stdio server： 本地 stdio 服务器，Stdio 服务器作为您机器上的本地进程运行。
• • remote WebSocket server： 远程 WebSocket 服务器，保持持久的双向连接，适合于向 Claude 主动推送事件的远程 MCP 服务器。

4、 技能 Skill

4.1、全局 Skill 目录

创建一个 SKILL.md 文件，其中包含说明，Claude 会将其添加到其工具包中。 配置文件名称 ~/.claude/skills/： 存放你个人常用的“万能技能”。

• •
  1. 1. 创建文件夹：mkdir -p ~/.claude/skills
• •
  1. 2. 将你收集的 Skill 文件夹放进去（每个文件夹需包含 SKILL.md）。
• • 注意：全局的 Skill 在所有项目中都能调用。

1）使用方式一： 软链接方式

【推荐】使用软链接方式， 作用就是在 Claude 技能目录下创建一个“快捷方式”，指向实际存放技能文件的文件夹。

# Linux/Mac
ln -s [源路径] [链接名]

ln -s /path/to/your/skill ~/.claude/skills/my-skill

# Windows
mklink /d [链接名] [源路径]

mklink /d "C:\Users\你的用户名\.claude\skills\my-skill" "D:\path\to\your\skill"

2） 使用方式二： 直接复制

直接按照目录路径规范，复制放到对应目录即可。

3） 使用cc-switch优雅管理

通过cc-switch进行管理，其支持的目录有~/.cc-switch/skills/和~/.agents/skills/。同时支持软链接和复制两种方式。

4.2、项目 Skill 目录

目录路径 ./.claude/skills/。

• • 存放该项目专属的技能（与业务强相关，其他项目用不上）。
• • 管理方式：同样支持软链接，但建议直接复制进项目，便于团队同步（如果技能是团队资产）。

5、 插件 Plugins

插件通过 skills、agents、hooks 和 MCP servers 扩展 Claude Code。

5.1、使用插件的步骤（示例）：

# 1） 添加社区插件市场
/plugin marketplace add anthropics/claude-plugins-community

# 2） 使用 `claude-community` 市场名称从中安装插件
/plugin install <plugin-name>@claude-community

安装常用插件：

# 安装 Superpowers 插件
/plugin install superpowers@claude-plugins-official

# 安装成功之后，使用这个命令去重载。
/reload-plugins

5.2、 添加插件市场的方式

1）从 GitHub 添加

/plugin marketplace add anthropics/claude-code

2）从其他 Git 主机添加

/plugin marketplace add https://gitlab.com/company/plugins.git

/plugin marketplace add git@gitlab.com:company/plugins.git

3）从本地路径添加

/plugin marketplace add ./my-marketplace

/plugin marketplace add ./path/to/marketplace.json

4）从远程 URL 添加

/plugin marketplace add https://example.com/marketplace.json

5.3、安装插件

添加市场后，您可以直接安装插件（默认安装到用户范围）：

• • 用户范围（默认）：在所有项目中为自己安装
• • 项目范围：为此存储库上的所有协作者安装（添加到 .claude/settings.json）
• • 本地范围：仅在此存储库中为自己安装（不与协作者共享）

/plugin install plugin-name@marketplace-name

6、注意事项与实操

6.1、需要特别注意的遗漏点

• • 不要把密钥提交到 Git：无论是 ~/.claude.json、./.mcp.json 还是 ./CLAUDE.local.md，只要包含敏感信息，务必加入 .gitignore。
• • 指令长度限制：CLAUDE.md 建议控制在 200 行以内，太长了 AI 容易“失忆”，导致指令不生效。
• • 常用终端命令补充（你第 6 点提到的）：
  • • claude mcp list —— 查看当前配置的所有 MCP 服务。
  • • claude mcp remove <name> —— 移除某个 MCP。
  • • 在 Claude Code 会话中输入 /mcp —— 查看当前连接状态和工具列表。

6.2、建议的实操步骤（按顺序）

1. 1. 先配置全局：编辑 ~/.claude/CLAUDE.md，写入语言偏好。
2. 2. 项目初始化：进入项目，运行 /init 生成 ./CLAUDE.md。
3. 3. 完善项目规则：手动编辑 ./CLAUDE.md，补全具体技术栈约束。
4. 4. 添加个人覆盖：如果有个性化需求，创建 ./CLAUDE.local.md。
5. 5. 按需添加 MCP：全局通用用 claude mcp add（不加路径），项目专用则在项目目录下执行。
6. 6. 挂载 Skills：通用的软链到 ~/.claude/skills/，项目的直接放进 ./.claude/skills/。

7、相关链接

• • Claude Code 目录介绍： https://code.claude.com/docs/zh-CN/claude-directory
• • Github高星的CLAUDE.md参考：https://github.com/multica-ai/andrej-karpathy-skills
• • AI 必备工具CC-Switch：https://ccswitch.io/zh/