Claude Code 进阶配置指南：CLAUDE.md、Skills、MCP、Fork、Subtask 五大维度

之前做项目时，Claude Code 的默认配置确实够用，但随着仓库变大、工具链变多、任务并行起来，只靠开箱即用的设置会明显吃力———上下文记不住、权限反复弹窗、外部工具接不进来、不同方案改来改去容易乱。网上关于 Claude Code 的教程大多集中在安装和基础用法，真正能落地的进阶配置很少被系统整理过。

这篇文章就把日常工程中用得上的 14 个进阶配置整理成一份清单，按 CLAUDE.md、Skills、MCP、Fork、Subtask 五个维度展开，每个配置都给出用途、写法/命令、注意事项，并配了可复制的配置片段和排错思路。如果你已经跑通 Claude Code 的基础用法，想在真实项目里提升效率和控制力，这份清单可以直接对照着配置；如果你刚开始接触，也可以按顺序过一遍，把配置基础打扎实。

1. 背景与核心概念

1.1 Claude Code 是什么

Claude Code 是 Anthropic 推出的一款终端命令行编程代理工具。它不是简单的聊天机器人，也不是 IDE 里的补全插件，而是可以直接运行在终端中、能够阅读项目文件、执行命令、调用编程工具链的自主编码代理。你只需要用自然语言描述目标，它就会自己规划步骤、读写代码、跑测试、修改文件，并在过程中和你确认关键决策。

在实际使用中，它非常适合这几类场景：

• 跨多个文件的重构和迁移。
• 按需求说明生成完整模块。
• 自动化执行测试、格式化和静态检查。
• 处理重复性较高的工程维护任务。

1.2 为什么要掌握进阶配置

默认的 Claude Code 对单文件任务和小项目足够友好，但真实项目往往会遇到下面这些问题：

• 项目背景复杂，Claude 需要记住大量约定，但每次会话都会丢上下文。
• 需要接入公司内部服务、数据库或自定义命令行工具。
• 多个需求并行开发，一个会话里反复切换方案容易混乱。
• 任务太重时，所有工作挤在一个上下文里处理，效率和准确性都会下降。

这些问题的解法，恰好就是本文要讲的五类配置能力：CLAUDE.md 负责“记忆”，Skills 负责“技能包”，MCP 负责“接外部工具”，Fork 负责“分支探索”，Subtask 负责“任务拆解”。理解这五个关键词，再配合 14 个具体配置点，基本就能把 Claude Code 从“能用的玩具”变成“可控的工程工具”。

1.3 五个关键词速览

2. 环境准备与版本说明

2.1 安装 Claude Code

Claude Code 最常见的安装方式是通过 npm 全局安装。在终端执行：

bash复制npm install -g @anthropic-ai/claude-code

安装完成后，在项目目录下直接执行 claude 即可启动。如果你还没有配置过登录态，首次启动会要求完成 Claude 账号认证。

需要提醒的是，Claude Code 仍处于快速迭代期，不同版本在命令参数、配置目录和功能命名上会有差异。本文中的命令和配置以当前主流版本为例，重点演示配置思路。如果你使用的版本不一致，请以 claude --help、claude mcp --help 以及官方文档为准。

2.2 配置目录结构

Claude Code 的配置主要分布在两个层级：

• 用户级：~/.claude/ 目录，存放用户级 CLAUDE.md、全局 Skills、全局 MCP 配置等。
• 项目级：当前项目下的 .claude/ 目录，以及项目根目录的 CLAUDE.md、.mcp.json、settings.json。

一个典型的项目配置布局如下：

text复制your-project/
├── CLAUDE.md
├── .mcp.json
├── .claude/
│   ├── settings.json
│   ├── skills/
│   └── agents/
└── docs/
    └── architecture.md

项目级配置建议提交到版本库，方便团队成员统一使用；用户级配置则只影响你自己。

2.3 常用 CLI 命令预览

几个高频命令先记一下：

bash复制claude                    # 启动交互式会话
claude --continue         # 继续最近的会话
claude --resume            # 选择历史会话继续
claude --help              # 查看全部可用参数
claude mcp list            # 查看已配置的 MCP 服务器

3. CLAUDE.md 进阶配置

这一节对应配置 1 到配置 5。CLAUDE.md 是 Claude Code 的核心记忆机制，Claude 在启动会话时会把相关 CLAUDE.md 内容作为上下文加载，相当于给它一份“项目说明书”。

3.1 配置 1：分层记忆体系

不要把所有的项目信息都塞进根目录的一个 CLAUDE.md 文件。Claude Code 支持多层级 CLAUDE.md，常见分层如下：

• 用户级：~/.claude/CLAUDE.md 或 ~/claude.md，存放个人编码偏好、常用工具链、通用工作流。
• 项目级：项目根目录的 CLAUDE.md，存放项目整体架构、技术栈、目录约定、启动命令。
• 目录级：子目录中的 CLAUDE.md，存放该模块特有的约定和说明。

加载时，离当前工作目录越近的 CLAUDE.md 优先级越高，可以用来覆盖上层级的通用说明。这样设计的好处是：通用信息只写一份，局部信息就近存放，Claude 在进入某个目录时不会把所有无关信息都加载进上下文，既节省上下文空间，也减少信息冲突。

示例：项目根目录 CLAUDE.md 只写整体约定，不要写某个模块的细节；src/services/CLAUDE.md 再写该模块的接口规范和数据流。

3.2 配置 2：指令与背景信息分离

CLAUDE.md 里其实混着两类内容：一类是给 Claude 的行为指令，比如“禁止修改 tests 目录”“提交前必须跑 lint”；另一类是描述性背景，比如“项目使用 pnpm workspace”“认证模块基于 JWT”。

这两类内容建议分开管理。行为指令写得太碎、太多，会让 Claude 在每次对话中都表现得过于死板，容易误伤正常操作；背景信息则应该尽可能客观，帮助 Claude 理解代码结构。

一个实用的写法是在 CLAUDE.md 中把“约定”和“背景”分成两个区域：

markdown复制## 行为约定

- 不要直接改动 dist/ 目录下的生成文件。
- 执行测试时使用 pnpm test，而不是 npm test。

## 项目背景

- 项目使用 pnpm workspace 管理 monorepo。
- 前端使用 Vue 3 + TypeScript，后端使用 NestJS。
- 目录 docs/ 下保存架构决策记录。

这样 Claude 读取时更容易区分“我必须遵守的规则”和“我需要理解的信息”，在具体任务中表现会更稳定。

3.3 配置 3：使用 @path 导入外部文档

CLAUDE.md 并不适合放很长的设计文档。如果项目里有大量架构说明、接口文档或需求文档，可以在 CLAUDE.md 中使用 @path 语法引用外部文件，Claude 在加载时会自动把引用内容带入上下文。

例如，在项目根目录的 CLAUDE.md 中写：

markdown复制项目整体架构说明见 @docs/architecture.md。
数据库表设计文档见 @docs/database-schema.md。

这里需要提醒的是，@path 引用会占用上下文，引用太多会让 Claude 的“注意力”分散。更推荐的做法是：在 CLAUDE.md 中只保留少量高价值引用，比如架构文档、接口约定、CI 流程；把细节文档放到子目录级 CLAUDE.md 中按需引用。这个能力也不只用于 CLAUDE.md，在对话中直接输入 @docs/architecture.md 同样可以在当前会话中引入该文件内容。

3.4 配置 4：通过 settings.json 管理权限白名单

Claude Code 在执行命令时默认会请求授权，频繁弹窗会打断节奏。更高效的方式是在项目级 .claude/settings.json 中配置权限规则，把常见命令加入白名单，把危险命令加入黑名单。

json复制{
  "permissions": {
    "allow": [
      "Bash(pnpm lint)",
      "Bash(pnpm test)",
      "Bash(git status)",
      "Bash(git diff)",
      "Read(.env.example)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force)"
    ]
  }
}

allow 中的规则支持通配符写法，例如 Bash(pnpm test:*) 可以放行一批相似命令。deny 中的规则优先级更高，用于强制拦截某些高风险操作。配置白名单的另一个好处是，Claude 判断某个命令是否可执行时会参考这些规则，减少来回确认，也不会因为误操作执行危险命令。

3.5 配置 5：维护变更记录，防止上下文过期

项目在不断演进，CLAUDE.md 里的信息如果过时，会比没有信息更危险。为了避免 Claude 基于过期的约定做决策，建议在 CLAUDE.md 顶部维护一段“最近更新”记录，或者把变更日志引用进来。

markdown复制## 最近更新

- 2025-06：数据库迁移脚本迁移至 db/migrations 目录。
- 2025-05：CI 流程新增类型检查步骤。

## 变更记录

详细变更记录见 @CHANGELOG.md。

实际项目中，我会定期把 CLAUDE.md 从头读一遍，删除一次性任务信息，合并重复约定，确保它始终是“稳定事实”的集合，而不是临时备忘录。Claude 的上下文窗口有限，保持文件精简本身就是一种性能优化。

4. Skills 技能配置

第 4 章对应配置 6 和配置 7。Skills 是 Claude Code 的可复用技能包，可以理解为“预置好的 prompt 模板 + 操作流程”，让 Claude 在遇到特定任务时直接套用你的最佳实践。

4.1 配置 6：创建自定义 Skill

一个 Skill 就是包含 SKILL.md 的目录。它支持放在用户级目录和项目级目录：

• 用户级：~/.claude/skills/<skill-name>/SKILL.md
• 项目级：.claude/skills/<skill-name>/SKILL.md

SKILL.md 的头部是 YAML frontmatter，核心字段是 name 和 description：

markdown复制---
name: code-review
description: 在提交合并前对代码变更做一次完整 review，重点检查安全性、边界条件和可维护性。
---

# Code Review 技能

执行以下步骤：

1. 先运行 `git diff` 查看本次变更内容。
2. 逐文件审查变更，关注潜在的空指针、越界、SQL 注入问题。
3. 检查是否有硬编码敏感信息。
4. 给出修改建议，按优先级排序。
5. 如果发现问题，输出具体文件和行号。

目录名和 name 建议使用小写连字符形式，例如 code-review，避免空格和特殊字符。description 是触发判断的关键，Claude 会根据描述判断当前任务是否匹配该技能，所以要写清楚适用场景和触发条件，而不是简单写“review 代码”。

4.2 配置 7：掌握 Skill 的触发与加载机制

Skill 的触发方式主要分两种：

• 自动触发：Claude 根据你的对话内容，结合 description 的语义判断是否加载该技能。
• 显式触发：你在对话中直接点名，例如“使用 code-review 技能检查当前改动”。

从工程经验来看，自动触发依赖描述写得好，但过于宽泛的描述会让 Claude 在无关任务中频繁加载技能。因此 description 应该写得像搜索引擎摘要，把任务类型、使用条件、输出格式都包含进去，例如：

markdown复制description: 当用户要求对 PR 或 commit 进行代码评审时使用，重点关注安全漏洞与边界条件。

还要注意同名冲突问题。项目级 Skill 和用户级 Skill 如果同名，项目级会覆盖用户级。多人协作时，最好在项目文档里登记已有的 Skill 清单，避免成员各自创建重复技能，导致行为不一致。实际使用中，我会把团队通用规范放在用户级 Skill，把特定项目流程放在项目级 Skill，这样既不污染其他项目，也能保证团队内行为一致。

5. MCP 集成配置

第 5 章对应配置 8 到配置 10。MCP 是 Model Context Protocol 的缩写，即“模型上下文协议”。它提供了一套标准化方式，让 Claude Code 能接入外部工具和数据源，比如 GitHub、数据库、文件系统、内部 API 等。

5.1 配置 8：添加 MCP 服务器

MCP 服务器的接入方式是在配置中指定它的启动命令。Claude Code 提供了 claude mcp 命令来管理这些服务器：

bash复制# 添加一个项目级 MCP 服务器
claude mcp add --scope project my-fs -- npx -y @modelcontextprotocol/server-filesystem /tmp

# 查看所有已配置的 MCP 服务器
claude mcp list

# 查看某个 MCP 服务器的配置详情
claude mcp get my-fs

命令中 --scope 用来指定配置归属范围，my-fs 是这个服务器在 Claude Code 中的名称，-- 后面的内容是该服务器的实际启动命令。需要注意的是，不同 MCP server 的启动方式差别很大，有的需要环境变量，有的还需要 API Key，所以添加前要先阅读对应 server 的文档，确认启动命令格式。

如果不想用命令行配置，也可以直接编辑 .mcp.json，把服务器配置以 JSON 形式写入项目：

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

用 .mcp.json 的好处是它可以提交到版本库，团队成员拉取代码后自动获得一致的 MCP 配置。

5.2 配置 9：管理 MCP 的作用域

MCP 服务器的作用域决定了配置对谁生效。常见作用域有三种：

• local：仅对当前用户和当前项目生效，配置不会提交到版本库。
• project：跟随项目，通过 .mcp.json 提交到版本库，团队共享。
• user：作用到当前用户的所有项目，存放在用户级配置中。

日常使用建议遵循最小范围原则：个人的调试工具用 local，团队共享的工具用 project，几乎每个项目都要用的通用工具才用 user。

如果某个 MCP 服务器不需要了，可以用下面命令移除：

bash复制claude mcp remove my-fs

在交互式会话中，也可以直接使用 /mcp 命令查看和切换 MCP 服务器，适合在调试阶段快速验证某个 server 是否可用。

5.3 配置 10：权限与安全边界

MCP 服务器能访问外部系统，权限失控会带来真实风险。安全配置的核心是“最小权限”，可以从几个角度入手：

• 只添加真正需要的 MCP 服务器，不用的及时移除。
• 对不信任或临时使用的服务器，使用 local 作用域，避免影响团队成员。
• 通过 settings.json 的 deny 规则禁用某些敏感操作能力。

例如，如果某个 MCP 服务器暴露了文件写入能力，而你只想让它提供读取能力，可以在 settings.json 中做限制：

json复制{
  "permissions": {
    "deny": [
      "MCP(fs:writeFile)",
      "MCP(fs:deleteFile)"
    ]
  }
}

需要特别说明的是，MCP 工具的具体名称取决于 server 实现，上面只是示例思路。在团队项目中接入任何 MCP 服务器之前，都应该先审查它的源码和权限范围，确认它不会读取敏感文件、不会向外发送数据。尤其是第三方提供的 MCP server，尽量通过 local 单独调试，确认行为安全后再推广到团队。

6. Fork 分支会话配置

第 6 章对应配置 11 和配置 12。Fork 是 Claude Code 的会话分叉能力，解决的是“同一个项目，多种实现方案，容易互相污染”的问题。

6.1 配置 11：使用 /fork 创建分支

当你在会话中已经做了一部分修改，突然想尝试另一种方案，但又不想丢掉当前进度，可以使用 /fork 命令创建当前会话的分支。

在 Claude Code 交互界面中直接输入：

text复制/fork

它会基于当前会话的历史和上下文创建一个新会话，两个会话彼此独立。你也可以在启动时通过参数从某个历史会话分叉，具体参数名称因版本而异，可以用 claude --help 查看，通常类似：

bash复制claude --fork <session-id>

会话 ID 可以通过 claude --resume 选择历史会话时看到。Fork 创建出的会话保留父会话的上下文，因此子会话不用重新解释项目背景，直接继续讨论新方案即可。

6.2 配置 12：分支上下文与并行方案管理

Fork 最常见的用法是“方案对比”。举个例子：重构某个核心模块时，你可以在同一个节点 fork 出两个会话，一个走依赖注入方案，一个走事件驱动方案，两边并行实现，分别跑测试，最后根据结果决定合并哪一条。

这种工作方式比在一个会话里反复改来改去更可靠，因为每个分支都保留了完整的决策上下文，Claude 不会被前一个方案的实现细节带偏。使用分支时注意几点：

• 分支不要开太多，否则管理成本和上下文费用都会增加。
• 每个分支的任务目标要明确，避免多个分支都在做同样的边缘修改。
• 分支产出的代码合并回主分支后，要及时清理掉不需要的分支会话，保持会话列表整洁。

如果你在会话中来回切换到不同分支，Claude Code 会保留各自独立的 transcript，后续可以用 --resume 重新进入任意一个分支继续工作，这对长周期开发非常有用。

7. Subtask 子任务配置

第 7 章对应配置 13 和配置 14。Subtask 是 Claude Code 的子任务委派机制，适合把大任务拆成多个小任务，交给多个代理并行或独立处理。

7.1 配置 13：使用子代理进行任务委派

Claude Code 在处理复杂任务时，会自动创建子代理（subagent）来执行局部任务。主代理负责拆解任务、编写任务描述，再把任务委派给子代理，子代理在独立上下文中执行完成后，把结果回报给主代理。

除了自动创建，你也可以在项目 .claude/agents/ 目录中定义“预定义子代理”，用于固定某种专业角色。以代码审查代理为例：

markdown复制---
name: reviewer
description: 负责安全审计和代码评审，重点关注认证、授权、数据和错误处理。
---

你是一名资深代码审查员。你只负责审查，不直接修改代码。

审查时重点关注：
1. 认证和授权逻辑是否正确。
2. 是否有敏感信息硬编码。
3. 异常处理是否覆盖边界条件。

输出格式：按严重程度列出问题清单，并给出文件路径和建议修复思路。

在对话中，你需要显式调用这个子代理，例如“@reviewer 请审查当前改动”。需要注意，预定义子代理和 Skill 不同，它不会自动触发，必须在对话中显式引用。这样设计的意图是不让额外代理干扰主流程，只有你明确需要专业角色介入时才启用。

7.2 配置 14：子任务结果回溯与并发控制

子代理执行任务后，会产生独立的会话记录和输出文件，主代理会读取关键结果并继续处理。从工程角度，使用子任务时要关注三个问题：

• 任务粒度：子任务拆得太细，创建代理的通信开销会超过收益；拆得太粗，单个子代理的上下文又会过载。一般以“一个子代理只完成一个内聚的模块/检查项”为宜。
• 结果验证：子代理返回的结果不能直接信任，主代理在整合前最好让子代理附上关键证据，比如修改的文件列表、测试输出、失败原因。
• 并发控制：并行发起多个子任务时，可能触发 API 速率限制。如果遇到限流，可以减少并行数量，或者把子任务改成逐个排队处理。

另一个实用技巧是在 TASK.md 中描述子任务时，明确写出输入、输出、验收标准和不许触碰的文件范围。子代理在独立上下文中无法看到主代理的所有背景，任务描述写得越具体，结果偏差越小。审计方面，每个子代理的独立 transcript 都会保留，需要排查问题时可以定位到具体子任务记录。

8. 常见问题与排查思路

排查这类问题有一个通用套路：先确认配置是否被正确加载，再确认命令或路径是否匹配当前版本，最后怀疑上下文冲突。大部分配置问题都可以通过“重启会话 + 查看帮助 + 最小化复现”三步定位。

9. 最佳实践与工程建议

9.1 配置随仓库走

项目级 CLAUDE.md、.mcp.json、.claude/settings.json 都建议提交到版本库。这样新成员克隆仓库后，不需要手动复制配置就能获得一致的开发体验。用户级配置只放个人偏好，不要把项目特有的信息放到全局配置中。

9.2 分层维护，避免“大而全”

无论是 CLAUDE.md 还是 Skills，最忌讳在一个文件里堆全部内容。分层维护能减少上下文占用，也能降低信息冲突概率。通用规则放上层，局部规则放子目录或子模块。

9.3 MCP 和权限遵循最小化原则

新增 MCP 服务器前先问三个问题：真的需要吗？它能访问什么？团队其他人需要吗？权限配置也是一样，只放行必要命令，危险命令一律进 deny。特别是引入第三方 MCP server 时，务必先审查再接入。

9.4 用 Fork 和 Subtask 控制复杂度

方案未定时用 Fork，任务太大时用 Subtask。这两种能力本质上都是“控制上下文复杂度”的手段。一个会话只干一件事、一个子代理只负责一个内聚任务，是长期使用后最值得养成的习惯。

9.5 搭配 Hooks 做自动化门禁

Claude Code 的 Hooks 可以在特定时机自动执行脚本，常见场景是代码生成后自动跑 lint 或格式化。这样可以把静态检查前置到 Claude 修改文件的瞬间，减少人工介入。Hooks 配置同样在 settings.json 中维护，需要根据自身项目定制，重点保证脚本稳定、退出码正确。

10. 总结与学习路线

这 14 个配置点覆盖了 Claude Code 工程化使用的五个关键维度：用 CLAUDE.md 管理记忆，用 Skills 沉淀技能，用 MCP 接入工具，用 Fork 控制探索路径，用 Subtask 拆分复杂任务。建议按顺序逐步配置，不要一次性全部铺开。

下一步的实践路线可以这样安排：

• 第一周：只配置 CLAUDE.md，把项目背景写清楚，观察 Claude 的任务理解是否改善。
• 第二周：把重复性工作沉淀为 Skills，比如代码审查、测试编写、发布检查。
• 第三周：接入真正需要的 MCP 服务器，并用 settings.json 管好权限。
• 第四周：尝试用 Fork 做方案对比，用 Subtask 拆解一个真实的大型任务，记录整体效率变化。

Claude Code 的功能更新很快，每次升级后建议用 claude --help 顺手确认哪些命令发生了变化。如果你在配置过程中遇到其他问题，欢迎在评论区留言，后续我也会继续整理新版功能和踩坑记录。