Claude Code 进阶：CLAUDE.md、Skills、MCP 与任务编排

Claude Code 是一个运行在终端里的 AI 编程辅助工具，它不再只负责回答技术问题，而是可以直接读取项目文件、修改代码、执行命令、提交 Git 变更，把一轮开发迭代压缩在对话里完成。很多团队和个人在第一次启动 Claude Code 时都觉得“能聊、能改文件”已经够用，真正困难的是进入生产项目后，如何让 AI 的行为稳定、可预期、可维护。这时需要面对的就变成了一组具体问题：CLAUDE.md 应该写在项目根目录还是用户目录，Skills 要怎么封装才不会被乱调用，MCP 如何接入外部数据源，Fork 和 Subtask 在长任务里到底承担什么职责。

这篇文章把这组能力收敛成 14 个可落地的进阶配置，按“项目记忆、技能、外部工具、任务编排”四个层次讲，并给出验证方式和排错方法。每个配置都以“解决什么问题、怎么做、容易错在哪”的顺序说明。因为 Claude Code 的功能会随版本调整，文中给出的命令和文件位置可能在不同版本里有差异，落地前要先用帮助命令确认当前版本。

1. 先理解配置体系：CLAUDE.md、Skills、MCP、Fork/Subtask 各管哪一段

1.1 Claude Code 的工作方式决定了配置从哪里入手

Claude Code 在工作时并不是一个空白的模型实例。它会在会话开始阶段读取上下文，然后根据项目状态、用户指令和可调用的工具逐步完成任务。整个过程的稳定性取决于三件事：

• 它知道什么，来自 CLAUDE.md 和项目文件。
• 它能做什么，来自 MCP 连接的外部工具和内置工具。
• 它如何执行长任务，来自会话管理能力，例如 Fork 和 Subtask。

在实际项目里，这三件事如果不配置，AI 还是会工作，但结果会像一个新入职且没有看任何文档的工程师：能做事，但不知道你们的构建命令、代码风格、禁止事项和数据源位置。进阶配置的本质，就是把“团队已经默认知道的信息”显式告诉 AI。

1.2 四个核心概念对应四类配置需求

CLAUDE.md 承担长期记忆和项目规范。它解决的问题是“让 AI 在这个仓库里按你们的规矩做事”，例如使用哪个包管理器、测试入口在哪里、哪些目录不能动。

Skills 承担可复用技能封装。它解决的问题是“同一类重复任务不要每次重新解释”，把操作步骤、判断标准和参考模板打包成一个技能，按需调用。

MCP 承担外部工具和数据源连接。它解决的问题是“AI 如何安全地访问数据库、文件系统、第三方服务”，通过标准协议把外部能力暴露成可调用的工具。

Fork 与 Subtask 承担任务编排。它们解决的问题是“长会话和大任务如何拆解”，让当前工作区可以分叉尝试不同方案，也让复杂任务可以拆成独立子任务执行，避免上下文被中间输出塞满。

1.3 14 个进阶配置速查表

下面的配置清单就是全文的骨架。每一行的详细做法会在对应小节展开。

这 14 项并不是每次都要全部配置。新项目可以先做 1 到 5，让 AI 在正确规则下参与开发；遇到重复操作再加入 6 到 7；需要访问外部系统时再加入 8 到 10；任务复杂度上来后，再考虑 11 到 14。

2. 环境与基础配置：先跑通再谈进阶

2.1 安装、升级和确认版本

Claude Code 的安装方式以官方文档为准。常见方式是通过 npm 全局安装，也可以使用官方提供的安装脚本或包管理器方式。如果本机已经装过，重点是升级到当前团队使用的版本，因为新增配置项通常只出现在较新版本里。

bash复制# 常见安装命令，具体包名和命令以官方文档为准
npm install -g @anthropic-ai/claude-code

# 查看版本
claude --version

# 查看可用参数
claude --help

这里要注意：不要只看版本号，还要确认启动命令。有些版本支持 claude，有些环境的全局命令可能带有前缀。检查方式是执行 claude --help，如果命令不存在，就说明 PATH 或安装位置有问题，需要先修正安装环境。

2.2 CLAUDE.md 的分层加载顺序

CLAUDE.md 是发给 AI 的“项目手册”，可以放在不同层级，加载时会按层级合并。常见分层如下：

• 用户级：位于 ~/.claude/CLAUDE.md，描述个人开发习惯，例如“我始终使用 pnpm”。
• 项目根级：位于仓库根目录的 CLAUDE.md，描述该项目通用的技术栈和规范。
• 子目录级：位于某个子目录的 CLAUDE.md，描述局部模块的特殊规则。

当多层文件存在时，越靠近当前工作目录的配置，优先级通常越高。也就是说，子目录的说明会比项目根的说明更贴近当前任务，项目根的说明又比用户全局说明更贴近当前仓库。如果不同层级的规则冲突，实际行为以当前版本的处理逻辑为准。为了降低风险，建议在配置时避免冲突，而不是依赖优先级去覆盖。

2.3 配置文件的常见放置位置

不同类型的配置通常放在不同位置，整理成一张表方便对照：

在继续往下配置之前，建议先完成一次“最小闭环”：打开终端，进入一个空项目目录，执行 claude 启动会话，输入一条简单指令，确认能正常读取文件并返回结果。基础链路不通的情况下，直接配 MCP 和 Skills 只会让排错更难。

3. CLAUDE.md 层：让 AI 按项目规则说话

3.1 项目 CLAUDE.md 应该写什么

项目根目录的 CLAUDE.md 是 AI 与仓库之间的“第一份合同”。它不需要很长，但必须覆盖关键信息：技术栈、目录结构、常用命令、测试方式、代码约定、禁止事项。

一个最小示例：

markdown复制# 项目级 CLAUDE.md 示例

## 项目说明

- 前端：Vite + Vue 3
- 后端：Node.js + Express
- 包管理器：pnpm
- 构建产物输出目录：dist/

## 常用命令

- 启动开发服务：pnpm dev
- 构建：pnpm build
- 运行测试：pnpm test
- 类型检查：pnpm typecheck

## 代码约定

- 组件文件使用 PascalCase 命名
- 提交信息使用 Conventional Commits 规范
- 新增接口必须先补充类型定义
- 不要直接修改 dist/ 下的产物文件

这段配置的目的是减少 AI 在每次任务中重新猜测。它不会替代工具本身，但会让工具的输出更贴近项目习惯。例如不知道包管理器时，AI 可能执行 npm install，而项目要求的是 pnpm install。CLAUDE.md 写清楚后，这类问题会明显减少。

3.2 全局 CLAUDE.md 应该写什么

全局 CLAUDE.md 是个人级配置，适合放“无论做什么项目都成立的习惯”。例如：

markdown复制# 全局 CLAUDE.md 示例

- 默认使用 pnpm，不使用 npm 安装依赖
- 修改代码前先查看对应测试文件
- 生成代码时优先保持现有目录结构
- 不要在提交信息里添加非技术性内容

全局配置不要写太多项目相关内容，否则会在不同仓库里造成前后矛盾。一个好的判断标准是：如果某条规则换一个项目仍然成立，才适合放到全局；如果它只适用于当前仓库，那就放到项目根 CLAUDE.md。

3.3 禁止项与边界规则要具体

AI 在自由执行任务时，最常见的风险不是“做错”，而是“做得太多”。禁止项写得越具体，越容易被遵循。

错误示例是“请谨慎操作生产环境”，AI 无法判断“谨慎”的边界。推荐写法是：

markdown复制## 禁止事项

- 不要删除 docs/ 目录下的历史文档
- 不要直接 push 到 main 分支
- 不要修改 .env 和 .env.local 文件
- 不要在没有测试覆盖的情况下重构核心模块
- 不要在代码中写入真实的 API 密钥

边界规则本质上是在给 AI 划定“可控操作范围”。它不需要覆盖所有可能性，只需要覆盖高风险路径。

3.4 用 .claudeignore 控制读取范围

Claude Code 在读取项目文件时，应该避开依赖目录、构建产物、日志和敏感文件。类似 .gitignore，可以准备一份 .claudeignore：

gitignore复制node_modules/
dist/
build/
coverage/
*.log
.env*
.DS_Store

.claudeignore 解决的核心问题是信息污染和信息安全。如果 AI 每次搜索都扫描 node_modules，不仅响应变慢，还会把无意义的依赖内容混入上下文。把构建产物和配置文件排除后，回答会更聚焦，误读敏感文件的风险也会降低。

4. Skills 层：把重复工作封装成技能

4.1 Skills 是什么

Skills 是一组可复用的能力包，通常包含一个说明文件和若干辅助资源。说明文件描述“什么时候用这个技能”，辅助资源提供模板、示例和步骤。

和 CLAUDE.md 的区别在于触发方式。CLAUDE.md 里的规则是每次会话都会加载的长期上下文；Skills 更像是“按需调用”的专业工具，AI 看到匹配场景时才会加载对应说明。如果一个流程很长、步骤很多，全部写进 CLAUDE.md 会让每次会话的上下文变重，更适合封装成 Skill。

4.2 SKILL.md 的基本结构

一个技能目录的结构可以参考下面这种组织形式：

text复制.skills/
└── commit-message/
    ├── SKILL.md
    └── examples/
        └── conventional-commit.md

SKILL.md 的核心字段通常包括名称、描述和指令。描述决定了 AI 什么时候调用它，因此要写出“触发条件”，而不是空泛的“这是一个提交信息技能”。

markdown复制---
name: commit-message
description: 当用户要求生成 Git 提交信息或检查提交信息格式时使用。
---

# 生成提交信息

1. 执行 git status 和 git diff --staged 查看变更内容。
2. 判断变更类型：feat、fix、refactor、docs、chore、test 等。
3. 生成 subject，控制在 72 字符以内。
4. 需要完整格式时，参考 examples/conventional-commit.md。

落地的关键是确认当前版本支持的 Skills 目录和文件命名。不同版本的加载路径可能不同，建议以官方文档或 claude --help 的输出为准。上面的示例是为了说明组织思路，不是通用的固定写法。

4.3 一个最小技能示例能跑通什么

假设团队经常发布周报，可以把“周报生成”做成一个技能。技能目录里放一份说明文档和一个模板文件。当用户发出“整理本周周报”指令时，AI 先读取说明，再按模板组织内容。

这种封装的价值在于：把重复性的判断逻辑固定下来，减少每次沟通成本。技能写好后，同一团队的不同成员使用时，得到的结果格式会一致。

4.4 Skills 最常见的坑

Skills 的核心价值是“把你知道但不想重复说的话，变成可复用规则”。一个技能如果能用一个段落说清楚，就不要写成十页文档。

5. MCP 层：连接外部工具和数据源

5.1 MCP 解决的问题

MCP 是一套让 AI 接入外部工具和数据源的标准方式。通过 MCP，AI 可以调用本地命令、查询数据库、读取外部服务，而不需要把每个工具的细节写死在模型里。

它的典型交互方式是通过 user 配置声明一个 server，然后由 Claude Code 在会话中启动并连接这个 server。连接成功后，AI 会把 server 暴露出来的能力当作工具调用。这个机制解决的问题是：AI 需要访问“当前对话上下文之外”的数据时，不能靠空想，而要通过真实工具查回来。

5.2 .mcp.json 配置示例

在项目根目录创建 .mcp.json，声明需要连接的 MCP server。一个通用结构如下：

json复制{
  "mcpServers": {
    "local-docs": {
      "command": "uvx",
      "args": ["serve-local-docs", "--dir", "./docs"],
      "env": {
        "LOCAL_DOCS_ROOT": "./docs"
      }
    }
  }
}

注意这里的 command、args、env 都要替换成实际环境中的启动方式。配置完成后，在 Claude Code 会话中通常可以通过 /mcp 类命令查看 server 列表，确认连接状态。具体命令名称以当前版本支持的命令为准。

5.3 本地数据源和外部服务应该怎么区分

本地数据源适合用文件路径和本地命令连接，例如读取内部文档目录、查询本地 SQLite 文件。外部服务则涉及网络请求、认证和权限，配置时要更加谨慎。

5.4 作用域最小化和权限裁剪

MCP 配置不是越多越好。连接一个数据源，就意味着 AI 多了一组可调用工具。如果项目中同时配置了开发库、测试库、日志服务和文档服务，AI 在复杂任务里可能会用到超出预期的工具。

推荐的裁剪方式：

• 每个环境单独定义一个 server，不混用。
• 环境变量里不写真实密钥，生产环境的密钥通过密钥管理工具注入。
• 数据源只开放任务所需的最小范围，例如只读、限定库名、限定表名。
• 定期检查和撤销不再使用的 server。

MCP 让 AI 的能力边界从“模型知识”扩展到“真实系统”，但边界越宽，权限越要收紧。

6. Fork 和 Subtask 层：管理长会话和复杂任务

6.1 /fork 的适用场景

如果当前会话已经进行了一段时间，上下文里的历史内容对后续工作有影响，而你又想尝试一个不同的方案，使用 /fork 可以创建一个新的会话分支。新会话会带着原来的对话上下文，但后续操作独立展开。

典型场景：

• 一个修复方案还不确定，想保留当前思路，同时验证另一种写法。
• 当前主线任务进行到一半，需要先排查一个临时问题，但不想污染主线上下文。
• 想对比“方案 A”和“方案 B”的执行结果，再用结果决定最终方向。

Fork 不是代码分支，而是对话上下文的分支。它可以避免“一条线索走到底”导致上下文过多、结果不可控的问题。

6.2 Subtask 子任务拆分的意义

长任务最容易出现的问题是主上下文被中间结果塞满。比如要完成“检查日志、定位故障、修复代码、补充测试”四个步骤，如果每一步的输出都堆在同一会话中，AI 会在后面阶段被无关信息干扰。

Subtask 的核心思路是把一个大任务拆成独立子任务，每个子任务只负责一个明确目标，完成后把结果回传给主任务。给 AI 的任务描述可以写成：

text复制请把这个维护任务拆成三个独立子任务：

子任务一：统计日志文件中的 ERROR 数量，按文件输出。
子任务二：根据统计结果定位可疑模块，给出优先级。
子任务三：将定位结果和证据路径写入 result.md。

首先执行子任务一，完成后回传结构化结果，再继续子任务二。

子任务的重点是结果要结构化。如果结果是一大段自然语言，主任务后续使用时的成本并不低。比较合适的结果格式是表格、关键字段列表或明确的文件路径。

6.3 与 CLAUDE.md 和 MCP 的配合

子任务虽然独立执行，但仍然处于同一个工作环境，因此通常会继承项目里的 CLAUDE.md、Skills 和 MCP 配置。前提是项目根目录的配置已经覆盖了执行子任务所需的边界。如果某个子任务需要访问特定数据源，需要在任务描述里明确指出，而不是期待 AI 自动联想到。

配合建议：

• 把子任务的输出格式写在指令里，避免回传内容不可用。
• 每个子任务的目标尽量独立，不要让两个子任务互相等待。
• 关键文件写入操作要指定精确路径，降低误写风险。
• 如果子任务涉及敏感操作，仍然要遵守权限批准策略。

7. 验证与排查：配置改了为什么不生效

7.1 配置生效前需要确认的顺序

遇到“配置改了但没有效果”，按下面的顺序排查，不要先怀疑工具本身：

1. 文件路径是否正确。CLAUDE.md 是否放在项目根目录，.mcp.json 是否放在预期位置。
2. 文件格式是否正确。JSON 是否可解析，YAML 缩进是否一致，Markdown 的 frontmatter 是否完整。
3. 当前版本是否支持。部分配置项可能是较新版本才加入，旧版本会静默忽略。
4. 会话是否需要重启。有些配置只在会话启动时读取，修改后要退出重新进入目录。
5. 是否有更高优先级配置覆盖。检查用户级配置是否和项目级配置冲突。
6. 查看状态和日志。通过帮助命令、状态命令查看当前启用项，MCP 类问题查看启动输出。

7.2 常见问题排查表

7.3 验证命令与状态确认

每个版本的命令清单会有差异，所以首先要通过 claude --help 或会话内的 /help 查看。常见能力包括：

• 查看帮助信息。
• 查看当前会话配置。
• 查看 MCP server 列表。
• 查看权限策略。
• 查看上下文使用情况。

这些验证动作要成为日常操作的一部分。配置完成后，先用一条简单命令确认配置生效，再进入真实任务，比直接跑大任务更容易定位问题。

8. 最佳实践与落地方案

8.1 从最小配置开始，不要一次配满

配置项的复杂度会叠加。如果第一次使用就把 14 项全部配齐，出了问题很难判断是哪一项引起的。推荐的顺序是：

每个阶段先跑通最小用例，再扩展到全量配置。例如 Skills 先做一个“生成提交信息”的小技能，跑通后再做周报、代码审查等复杂技能。

8.2 发布前检查清单

在把配置写进团队仓库之前，先用下面的清单检查一遍：

发布前检查清单：

1. 项目 CLAUDE.md 是否覆盖技术栈、常用命令、代码约定和禁止事项。
2. 全局 CLAUDE.md 是否只保留跨项目通用规则。
3. .claudeignore 是否排除 node_modules、dist、coverage、.env、日志等目录。
4. MCP 配置文件中是否存在明文密钥。
5. 每个 MCP server 是否只开放任务所需的最小范围。
6. Skills 的 description 是否能在正确场景触发。
7. Skills 的指令步骤是否可以被 AI 按清单执行。
8. Fork 和 Subtask 的输出是否做了结构化约束。
9. Hooks 的触发范围是否过宽，是否会阻塞合法操作。
10. 权限批准策略是否遵循最小化原则。

8.3 下一步扩展方向

配置体系稳定后，可以继续向三个方向扩展：

• 把 CLAUDE.md 和 Skills 纳入版本控制，让新成员拉下仓库后就拥有同样的配置。
• 总结团队内部的高频任务，沉淀成共享 Skills 仓库。
• 结合自动化钩子，在 AI 操作前后执行格式检查、测试和通知，让 AI 行为纳入现有工程流程。

Claude Code 的配置价值不在于把所有能力都打开，而在于让 AI 在正确的边界内高质量工作。最需要花时间维护的不是某个炫目的 MCP 服务，而是那份一页纸就能读完的项目 CLAUDE.md。它决定了 AI 在这个仓库里是“乱试”还是“按规矩来”。如果只保留一条建议，那就是先建好项目根目录的 CLAUDE.md，其他所有能力都在这个根上生长。