Claude Code 进阶配置指南：从 CLAUDE.md 到 MCP 的 14 个实用设置

Claude Code 的配置很容易给人“文件很多、不知道改哪个”的感觉。实际上只要把配置分成五类理解，它就没那么复杂：CLAUDE.md 负责告诉 Claude 项目长什么样，Skills 和自定义命令负责把高频动作变成可复用能力，MCP 负责把外部工具接进来，Fork 负责把会话分叉出去，Subtask 负责把独立任务派给子代理。下面按我实际使用的顺序，把近期版本里最常见的 14 个进阶配置拆开讲清楚。这个主题最适合两类人：一类是已经跑通基础对话、开始做项目级配置的开发者；另一类是准备把 Claude Code 引入团队、想统一规范和权限的人。最值得先记住的一句话是：先分清配置放哪里，再看配置怎么写，最后才知道不生效时该查什么。

如果按“14 分钟”来分配，我会这样安排：前 3 分钟看配置地图，5 分钟配置 CLAUDE.md 和 Skills，3 分钟接 MCP，剩下 3 分钟处理 Fork、Subtask、权限和排错。

1. 配置地图：Claude Code 的配置到底分几层

很多人第一次打开 Claude Code 项目，会在根目录看到一堆 .claude、CLAUDE.md、.mcp.json，不知道哪个优先、哪个该提交、哪个该忽略。先把这个地图理清，后面所有配置才有意义。

1.1 三个设置文件的分工

Claude Code 的设置文件通常分三层：

• 全局设置：~/.claude/settings.json，属于你个人，对所有项目生效。
• 项目设置：.claude/settings.json，属于当前项目，可以提交到仓库给团队共用。
• 本地设置：.claude/settings.local.json，属于当前开发者的本地覆盖，不应该提交。

这三层的合并原则比较简单：越具体的越优先。本地设置会覆盖项目设置，项目设置会覆盖全局设置。

为什么这样设计？因为不同层级的职责本来就不一样。全局管个人习惯，比如“我默认喜欢用某个模型、我在所有项目都不希望 Claude 直接执行某类命令”；项目管团队公共规则，比如“本项目默认用哪个权限模式、哪些工具允许执行”；本地管那些不能入库的个人差异，比如你本地的临时目录、个人 API 配置、某些只在开发环境里需要的路径。

这里有个容易犯的错：把个人偏好写进 .claude/settings.json 然后提交，团队里其他人拉下来就会被你的偏好影响。项目公共配置和本地私有配置分开写，才是干净的做法。

1.2 四类 CLAUDE.md 记忆文件

CLAUDE.md 是 Markdown 格式的上下文文件，Claude 在开始任务时会把相关部分读进上下文。它分成几个位置：

• ~/CLAUDE.md：全局记忆，所有项目都会读。
• ./CLAUDE.md：项目根目录记忆，当前项目的主约定。
• 子目录/CLAUDE.md：子目录级记忆，只对该目录及其下内容生效。
• ./CLAUDE.local.md：本地记忆，不入库，适合个人笔记或本机路径。

你不需要把所有东西都塞到根目录那一个文件里。全局放个人习惯，根目录放项目规范，子目录放模块约束，本地放个人差异。分得越清楚，Claude 拿到的上下文越精确。

1.3 14 个进阶配置快速总览

这 14 项不是越多越好的意思。多数个人项目前 6 项就能覆盖日常，后面 8 项是进入团队协作、复杂任务和生产环境时才真正需要的东西。

2. CLAUDE.md：把项目约定写进 Claude 的上下文

CLAUDE.md 是 Claude Code 里最基础、也最容易被写坏的配置。写得好，Claude 从一开始就知道项目用什么包管理器、跑什么测试命令、改动要不要兼容旧接口；写不好，它就是个没人维护的说明书。

2.1 全局、项目、子目录分别写什么

全局 ~/CLAUDE.md 适合放不依赖具体项目的规则。比如“每次改代码前先看现有测试”“不要在没有测试的情况下删除文件”“提交信息用英文”。

项目根目录 ./CLAUDE.md 适合放别人接手时最需要知道的信息。比如：

• 包管理器是 npm、pnpm 还是 yarn。
• 启动命令、测试命令、构建命令分别是什么。
• 代码风格约定，比如错误处理用 throw 还是返回 Result。
• 目录结构的简要说明，哪个目录是入口，哪个目录不能动。
• 已有的测试和文档在哪里。

子目录的 CLAUDE.md 适合放边界更窄的约束。比如 src/api/CLAUDE.md 只写“这个目录下的接口必须兼容旧版本，新参数不破坏已有调用”。Claude 处理这个目录里的文件时，会优先读到这个局部约束，而不是把根目录的大规范全部套上来。

./CLAUDE.local.md 则适合写你自己知道、但不想影响别人的信息。比如本机的某个路径映射、你习惯的调试方式、你要临时做的实验性改动。

2.2 一份可以直接改的项目 CLAUDE.md 示例

markdown复制# 项目约定

## 环境
- 包管理器：pnpm
- Node 版本：>= 20
- 本项目是前端 monorepo，不要单独在子包目录执行 install

## 常用命令
- 安装依赖：pnpm install
- 开发：pnpm dev
- 单测：pnpm test --runInBand
- 类型检查：pnpm typecheck
- 构建：pnpm build

## 代码规范
- 组件命名使用 PascalCase，文件名与组件名一致
- 提交信息使用 conventional commits 格式
- 新增函数必须补充单测，异常场景至少覆盖一种
- 不要把 .env 内容写入任何文档或代码

## 目录说明
- packages/core：通用逻辑，禁止依赖 UI 层
- packages/web：页面和组件
- scripts：工程脚本，改动前先看 README

写 CLAUDE.md 的核心原则是短、准、可验证。每条规则最好都能被当成检查项，而不是空泛的口号。“代码要整洁”这种话没有用，“改完代码必须跑类型检查并把结果贴出来”才是 Claude 能执行的东西。

2.3 写 CLAUDE.md 最容易踩的三个坑

第一个坑是写太长。CLAUDE.md 会进入上下文，太长会挤占实际任务的上下文空间。我看到有人把整份技术方案贴进去，结果 Claude 处理正常任务时还要反复翻看无关章节。更好的做法是只保留“必须遵守”和“高频使用”的信息，细节放到文档目录里按需读取。

第二个坑是放密钥或绝对路径。CLAUDE.md 通常会提交到仓库，里面写死本机路径或者密钥，等于把这些信息暴露给所有能访问仓库的人。敏感配置应该走环境变量或本地设置文件。

第三个坑是把 CLAUDE.md 当成设置文件。它管的是“上下文和约定”，不是权限。能不能执行某个命令、用什么模型、允许哪些工具，这些要交给 settings 和权限配置。搞混之后会出现一种现象：明明 CLAUDE.md 里写了“不要删除 dist 目录”，Claude 还是问了权限说要做删除——因为这不是记忆能阻止的，是权限该管的。

3. Skills 和自定义命令：把高频动作变成可复用能力

CLAUDE.md 解决“Claude 知道项目是什么”，Skills 和自定义命令解决“Claude 知道怎么做一类事情”。两者经常被混淆，但触发方式和使用场景差别很大。

3.1 Skills 的目录结构

Skills 是一组能力包的目录。典型位置有两种：

• 个人技能：~/.claude/skills/<技能名>/SKILL.md
• 项目技能：.claude/skills/<技能名>/SKILL.md

每个 Skills 文件夹里必须有一个 SKILL.md 作为入口，开头用 YAML frontmatter 写 name 和 description。description 特别重要，因为 Claude 会根据任务内容判断当前任务是否匹配这个技能，描述写得越清晰，它越知道什么时候该启用。

markdown复制---
name: code-review
description: 对指定文件或当前改动做代码审查，重点检查错误处理、性能风险和可维护性。
---

# Code Review

使用这个技能时按以下步骤执行：

1. 先读取目标文件和对应测试。
2. 检查错误处理、边界条件、资源释放。
3. 检查是否引入明显性能问题。
4. 输出 Markdown 清单，按严重程度排序，每条给出文件位置和修复建议。

除了 SKILL.md，这个目录里还可以放参考文档、脚本、模板。技能需要多步操作时，把步骤写清楚比让 Claude 自由发挥更稳定。

Skills 和命令的关键区别是触发方式：命令要用户输 /xxx 主动触发，Skills 由 Claude 在看懂任务后自行判断是否调用。所以 Skills 适合描述明确的“能力区间”，比如代码审查、日志分析、接口文档生成；命令适合固定入口的操作，比如给自己定义一套 /commit 规范流程。

3.2 自定义斜杠命令

自定义命令放在 .claude/commands/ 目录，文件名去掉 .md 就是命令名。比如 .claude/commands/review.md 对应 /review。

markdown复制---
description: 对当前改动做一次快速代码审查
argument-hint: <可选范围，如 packages/web>
---

运行 git diff HEAD 获取当前改动，然后按这个流程审查：

1. 列出改动涉及的文件。
2. 检查是否破坏已有接口兼容性。
3. 检查是否有明显性能和安全隐患。
4. 输出结果，每个问题标注严重程度。

命令的 frontmatter 里，description 是稳定的基础字段，部分版本还支持 argument-hint 用来提示参数格式。如果你想限制某个命令能用哪些工具，先确认你安装的版本是否支持对应的 allowed-tools 字段，不确定就不要写，写错了反而报错。

3.3 Skills、命令、子代理到底有什么区别

理解这个区别后，就不会出现“把该做成命令的流程写成 Skills，结果 Claude 老是不主动调用”这类问题了。

4. MCP：让 Claude Code 能够操作外部数据和服务

MCP 是 Claude Code 扩展工具边界的主要方式。没有 MCP 时，Claude 能碰到的数据基本来自项目文件和命令行；接上 MCP 后，它能读写外部服务、查询数据库、调用特定工具链。

4.1 命令行配置 MCP

在命令行里可以直接管理 MCP server：

bash复制# 添加一个 MCP server
claude mcp add my-server -- npx -y some-mcp-server

# 查看当前已配置的 server
claude mcp list

# 查看某个 server 的详细配置
claude mcp get my-server

# 移除
claude mcp remove my-server

这里的关键是搞清楚 scope。你加的 server 可能是用户级，也可能属于当前项目。团队项目里，MCP server 配置最好统一放到项目级，这样每个人拉下来跑的 server 一致；个人实验用的 server 放用户级，避免污染团队配置。

MCP server 不一定只能跑在本地。远程 server 也可以配置，但涉及认证时，密钥、token 这类敏感信息要走环境变量或密钥管理，不要写进配置文件提交到仓库。

4.2 项目级 .mcp.json

项目级的 MCP 配置通常放在根目录的 .mcp.json，格式大致是这样：

json复制{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/tmp/demo"
      ]
    }
  }
}

.mcp.json 的好处是跟着仓库走，新同事 clone 下来之后，Claude Code 能自动识别项目需要的 MCP server。坏处也在这：如果里面有个人凭证，就会跟着仓库泄露。所以比较稳妥的项目级配置是只声明 server 和参数，把敏感值留在本地环境变量里。

4.3 MCP 排查顺序

MCP 出问题时，现象通常是“Claude 说工具不可用”或者“调用工具时一直没结果”。我的排查顺序是：

1. 先在交互界面里执行 /mcp，看 server 状态是 connected 还是 failed。
2. 检查启动命令能不能手动跑通。比如 npx -y some-mcp-server 在你当前 Node 版本下是否正常，如果它一启动就报错，Claude Code 这边当然连不上。
3. 检查配置文件的 JSON 语法和路径是否有误。command、args、env 任何一个写错，server 都可能起不来。
4. 检查权限。MCP 工具一旦注册，具体执行时也会受到权限模式约束。工具被拒绝不等于配置坏了，点开权限提示看原因。
5. 检查版本差异。不同版本的 Claude Code 对 MCP 配置字段支持程度不完全一样，老版本可能不认某个字段。

不要一上来就删掉配置重加。先看 server 能不能独立启动，能省掉一半排查时间。

5. Fork 和 Subtask：会话分叉与子任务派发

前面几类配置主要解决“Claude 知道什么、能用什么”，Fork 和 Subtask 解决的是“长任务怎么组织”。这两个能力用得好，能让复杂任务从一条直线变成可管理的小分支。

5.1 用 /fork 在分岔口保留两条路径

Fork 和 Git 里的 fork 仓库没关系，它指会话分叉。当 Claude 在某次对话里走了一条你不完全确定的路线，你不想直接砍掉这条线，又不想失去下一次尝试的机会，就可以用它保留分叉点。

交互模式里通常直接输入 /fork，它会把当前会话在某个消息节点处分出新的会话。老会话还在，新会话从分叉点带着已经形成的上下文继续走。这样你就可以做对比：同一批需求，让两条分支各自给出方案，哪个合适用哪个。

什么时候该用 Fork？我一般这样判断：

• 当前方案已经花了很多工夫，但还想试一个风险更高的替代方案。
• 任务做到一半发现方向可能错了，不适合继续在主线程里来回改。
• 想保留一条“当前进度”的稳定版本，另一条做实验性调整。

分叉之后，给不同会话填上清楚的名字或备注很重要。不然过了一晚上再看会话列表，根本分不清哪条是稳定线、哪条是实验线。

命令行场景下，部分版本支持通过会话参数从一个已有会话继续或者分叉。具体参数名每个版本不一定相同，最稳的办法是运行 claude --help 看你当前版本支持什么，不要照抄网上旧命令。

5.2 用 Subagent 处理可以独立派发的子任务

Subagent 是 Claude Code 里可以定义的特殊子代理。它有自己的系统提示、工具范围和模型选择，适合处理那些和当前主任务相关、但可以单独拆出来的工作。

自定义 Subagent 通常放在 .claude/agents/ 目录，格式如下：

markdown复制---
name: frontend-reviewer
description: 专门审查前端组件代码，关注组件结构、状态管理和样式问题。
tools: Read, Grep, Glob, Bash
model: sonnet
---

你是一名前端审查专家。收到任务后，只关注组件设计、状态管理和样式问题，不讨论后端逻辑。输出必须按问题严重程度排序，并给出文件位置和修改建议。

description 决定 Claude 会不会派任务给这个子代理，tools 决定它手头有多少能力。工具范围给得越小，越能保证它专注在职责边界里。

典型用法是把“大任务”拆成“主任务 + 几个子代理”。比如主任务写一个新功能模块，同时让一个子代理收集接口文档、另一个子代理生成基础测试、第三个子代理做类型检查。每个子代理只做一件事，最后主线程汇总结果。

5.3 实战建议：什么时候别急着开子代理

子代理不是越多越好。任务如果只有几百行代码，主线程直接做完比派发快得多；只有任务明显可以切分成独立模块，或者主任务里反复出现重复性工作，才值得开子代理。

更重要的是先确认每个子代理的职责边界。描述写得含糊，Claude 就会把不属于它的任务也派进去，结果每个子代理都在做类似的事，反而拖慢整体。先定义清楚“谁负责什么、输出什么格式”，再谈并行。

另外，给子代理配置工具时也克制一点。不需要 Bash 的子代理就不要给它 Bash，能少暴露一个权限就少一个风险。

6. 权限、忽略文件和环境变量：配置生效前的安全检查

配置不只是“让 Claude 能做更多事”，也包括“让它不做不该做的事”。权限、忽略文件和环境变量这组配置，就是安全边界。

6.1 权限模式与 allow/deny

settings.json 里可以用 permissionMode 控制交互方式，常见模式大概有这几种：

• default：每次执行需要确认，适合日常交互使用。
• acceptEdits：文件编辑不需要逐次确认，适合写代码为主的任务。
• plan：只做分析和计划，不实际修改，适合需求拆解阶段。
• bypassPermissions：跳过大部分权限确认，只在受信任的项目里使用。

除了模式，还能声明 permissions 的 allow 和 deny 列表。比如：

json复制{
  "permissionMode": "default",
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff)"
    ],
    "deny": [
      "Bash(rm -rf)"
    ]
  }
}

这个配置的意思是：git status 和 git diff 这种只读命令可以直接执行，不用每次问；rm -rf 明确拒绝。allow 和 deny 的好处是让高频命令少打断你，同时把危险命令卡住。

交互界面里也可以用 /permissions 查看当前哪些工具被允许、哪些被拒绝。我建议项目刚上手时先用 default 模式跑几天，观察哪些确认是多余的，再精简 allow 列表。不要第一天就开 bypassPermissions，会失去一次审视风险的机会。

6.2 .claudeignore 文件

.claudeignore 的用途类似 .gitignore，声明哪些目录和文件不应该被 Claude 读取或处理。我在配置时通常会忽略这些东西：

• node_modules、dist、build 这类生成目录。
• 日志文件和大体积数据文件。
• .env、密钥文件、本地证书。
• 临时目录和备份目录。

忽略大型目录最直接的价值是省钱省时间。Claude 在处理项目时会频繁搜索文件，如果把 node_modules 和 dist 都塞进去，每次扫描都可能把上下文塞满，还会让响应变慢。忽略敏感文件的逻辑就更简单：读不到就是最好的保护。

6.3 环境变量与 hooks

环境变量是配置里的另一块内容。常见需求包括设置 API Key、指定模型、指定请求地址。在脚本或 CI 环境里，通常用 ANTHROPIC_API_KEY、ANTHROPIC_MODEL、ANTHROPIC_BASE_URL 这类变量注入。具体变量名会随版本变化，最好先确认你安装版本的文档。

另外，很多版本支持 hooks，可以在某些事件前后执行脚本，比如文件写入后自动格式化、命令执行后记录日志。hooks 的字段和触发事件在不同版本里差异比较大，不建议在还不清楚版本规则时直接套网上的完整配置。先用最小脚本验证一次事件能不能触发，再逐步加复杂逻辑。

7. 配置改完怎么确认生效：验证与排查链路

配置写完之后，真正的考验是“它到底生没生效”。很多人卡在这里：CLAUDE.md 改了一大段，MCP server 加了好几个，结果怎么知道 Claude 真的在按这些规则跑？

7.1 在交互界面里快速确认

Claude Code 的交互界面里通常有查看状态的方式。启动一个新会话后，你可以通过 /status 查看上下文、通过 /model 查看当前模型、通过 /permissions 查看工具权限，通过 /mcp 查看 MCP server 状态。每个命令先跑一遍，能确认很多表面问题。

需要注意，CLAUDE.md 这类记忆文件在新会话启动时加载。如果改完文件后发现当前会话还在按旧规则跑，优先新开一个会话再验证，而不是在旧会话里反复试。

7.2 一套固定的排查顺序

配置不生效时，我基本固定按这个顺序排查：

1. 看现象。是完全没有被识别，还是识别了但行为不对。前者多半是位置或命名问题，后者多半是内容写得不明确。
2. 看文件位置。文件放错了目录等于没配置。比如项目命令放到用户级目录，只有你自己能用，团队其他人就看不懂。
3. 看优先级覆盖。是不是三层设置之间有冲突，某个更具体的配置把预期配置覆盖了。
4. 看语法。JSON 少个逗号、YAML 缩进不对，Claude Code 一般会报错，但报错信息不一定直接指出是哪个文件。
5. 看权限。工具存在但不代表被允许执行，权限拦截也可能表现为“配置无效”。
6. 看版本。Claude Code 更新很勤，字段和命令名的兼容性不能只看三个月前的文章。

这六步里，前两步解决了大部分问题。我自己遇到“配置没用”时，十次里有七八次其实是路径错了或优先级覆盖。

7.3 版本更新频繁，配置要怎么保持稳定

Claude Code 的功能迭代速度很快，今天能用的字段，一个版本后可能改名或废弃。比较稳妥的做法是保持配置精简，只写你用得到的字段；看到新功能先在小项目验证，再决定要不要应用到团队配置。

还要注意一点：配置文件的注释能力有限，JSON 里放不了太多说明。你可以把配置字段的说明写在项目文档里，或者用 CLAUDE.md 单独记录“这个配置为什么这么写”。这样换人维护时，不容易出现“这段配置没人敢动”的局面。

最后我给一句实在的建议：14 个配置不用一次性全部配齐。先从 CLAUDE.md 和权限模式开始，把单项目跑稳；然后再上 Skills 和 MCP；最后再考虑 Subagent 和 Fork。配置本身不是目的，让 Claude Code 在一个可控、可复现的环境里稳定帮你干活，才是目的。