Claude Code 核心加载机制详解

一文搞懂 Claude Code 如何组织、加载、协调各类能力模块

一张图看懂全局

复制代码

┌─────────────────────────────────────────────────────────────────────────┐
│                         Claude Code 启动流程                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   1. 加载配置                                                            │
│      ~/.claude/settings.json ──────→ 全局设置（权限、环境变量）           │
│      ./.claude/settings.local.json → 项目设置（覆盖全局）                 │
│                                                                         │
│   2. 加载指令                                                            │
│      ~/.claude/CLAUDE.md ──────────→ 全局指令（你的工作风格、偏好）        │
│      ./.claude/CLAUDE.md ──────────→ 项目指令（项目规范、技术栈）          │
│                                                                         │
│   3. 加载记忆                                                            │
│      ~/.claude/projects/{hash}/memory/MEMORY.md → 项目记忆索引           │
│                                                                         │
│   4. 启动扩展                                                            │
│      ~/.claude/.mcp.json ──────────→ MCP Servers（外部能力）             │
│      ~/.claude/plugins/ ───────────→ 插件（功能扩展）                     │
│      ~/.claude/hooks/ ─────────────→ 钩子（事件拦截）                     │
│                                                                         │
│   5. 发现技能                                                            │
│      ~/.claude/skills/ ────────────→ 全局技能                            │
│      ./.claude/skills/ ────────────→ 项目技能                            │
│      ./.claude/commands/ ──────────→ 项目命令                            │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

核心概念：全局 vs 项目级

Claude Code 的设计哲学：全局配置通用能力，项目配置特定需求。

复制代码

~/.claude/                    # 全局级（所有项目共享）
├── CLAUDE.md                 # 你的工作风格
├── settings.json             # 全局设置
├── .mcp.json                 # MCP 配置
├── skills/                   # 通用技能
├── hooks/                    # 全局钩子
└── plugins/                  # 插件

./.claude/                    # 项目级（仅当前项目）
├── CLAUDE.md                 # 项目规范
├── settings.local.json       # 项目设置
├── skills/                   # 项目特定技能
└── commands/                 # 项目命令

加载顺序：全局 → 项目级（后者覆盖前者）

一、CLAUDE.md：你的指令书

是什么

CLAUDE.md 是一个 Markdown 文件，告诉 Claude "你希望它怎么工作"。

两层结构

复制代码

~/.claude/CLAUDE.md          # 全局：你的角色、风格、偏好
./CLAUDE.md                  # 项目：这个项目的技术栈、规范

全局 CLAUDE.md 示例

markdown 复制代码

# CLAUDE.md

## 角色定义
我是技术统筹者，职责是指挥与协调，而非堆砌代码。

## 工作原则
1. 先想后动 --- 不假设、不隐瞒困惑
2. 简洁至上 --- 只写解决问题所需的最少代码
3. 精准手术 --- 只改必须改的
4. 验证驱动 --- 定义成功标准，循环验证

项目 CLAUDE.md 示例

markdown 复制代码

# CLAUDE.md

## 项目概述
这是 Python 技能库，用于查询监控和数据平台。

## 技能列表
| 技能 | 功能 |
|------|------|
| /query-arius | 查询 Arius ES 数据 |
| /query-odin | 查询 Odin 监控指标 |

## 代码风格
- 使用 Python 标准库，无外部依赖
- 输出 JSON 格式

加载时机

每次对话开始时自动加载，常驻上下文。

二、Memory：跨会话记忆

是什么

Memory 让 Claude 能"记住"之前对话中的重要信息，即使开始新会话也能回忆起来。

存储位置

复制代码

~/.claude/projects/{project-hash}/memory/
├── MEMORY.md                 # 索引文件（自动加载）
├── user_preferences.md       # 用户偏好
├── project_progress.md       # 项目进度
└── feedback_history.md       # 反馈记录

四种记忆类型

类型	用途	示例
`user`	用户角色、知识背景	"用户是资深 Go 工程师，React 新手"
`feedback`	工作方式指导	"测试必须用真实数据库，不要 mock"
`project`	项目进度、决策	"预算V3 开发完成，待配置"
`reference`	外部资源引用	"Bug 追踪在 Linear INGEST 项目"

记忆文件格式

markdown 复制代码

---
name: 测试规范
description: 测试相关的反馈和偏好
type: feedback
---

## 规则
集成测试必须使用真实数据库。

**Why:** 上季度 mock 测试通过但生产环境失败，造成事故。

**How to apply:** 涉及数据库的测试，不要使用 mock。

加载机制

复制代码

MEMORY.md（索引）────→ 每次对话自动加载
     │
     └─→ 具体记忆文件 ────→ 按需读取（节省 token）

设计智慧： 索引常驻，详情按需。既保证 Claude 知道"有什么记忆"，又不会浪费上下文。

三、Skills：技能包

是什么

Skill 是一个封装好的能力模块，通过 /skill-name 调用。可以是工作流程、最佳实践、或特定任务的处理方法。

目录结构

复制代码

~/.claude/skills/             # 全局技能
└── my-skill/
    └── SKILL.md              # 技能定义文件

./.claude/skills/             # 项目技能
└── project-skill/
    └── SKILL.md

SKILL.md 格式

markdown 复制代码

# my-skill

## 触发条件
用户说"帮我分析代码"或代码审查场景。

## 技能描述
执行代码审查，提供改进建议。

## 使用示例
/my-skill path="src/main.py"

加载机制

复制代码

对话开始
    │
    ├─→ 扫描 ~/.claude/skills/
    │
    ├─→ 扫描 ./.claude/skills/
    │
    └─→ 生成技能列表，注入系统提示

Skills 是按需调用的，不会所有加载。 只有当用户触发（/skill 或匹配触发条件）才会运行。

四、Commands：快捷命令

是什么

Commands 是简化的 skill，用于快速执行常用操作。

目录结构

复制代码

./.claude/commands/
├── test.md                   # /test 命令
├── lint.md                   # /lint 命令
└── deploy.md                 # /deploy 命令

命令文件示例

markdown 复制代码

# test

运行项目的测试套件。

```bash
pytest tests/ -v

复制代码

### 与 Skills 的区别

| 特性 | Command | Skill |
|------|---------|-------|
| 复杂度 | 简单、单一 | 可复杂、多步骤 |
| 参数 | 无或简单 | 支持复杂参数 |
| 定义文件 | 单个 .md | SKILL.md + 可选脚本 |

---

## 五、Hooks：事件钩子

### 是什么

Hook 让你在特定事件发生时自动执行命令，实现"拦截"和"增强"。

### 配置位置

```json
// ~/.claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "command": "/path/to/check.sh" }]
      }
    ],
    "PostToolUse": [...],
    "Stop": [...],
    "Notification": [...]
  }
}

内置钩子事件

事件	触发时机	用途
`PreToolUse`	工具调用前	参数检查、权限验证、命令重写
`PostToolUse`	工具调用后	结果处理、日志记录
`Stop`	对话结束时	清理、通知
`Notification`	需要用户关注时	桌面通知

实际例子：RTK 命令

json 复制代码

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "command": "~/.claude/hooks/rtk-rewrite.sh" }
        ]
      }
    ]
  }
}

效果： git status 自动重写为 rtk git status，节省 token。

六、MCP：外部能力连接器

是什么

MCP (Model Context Protocol) 让 Claude 能连接外部系统（数据库、API、知识库等）。

架构图

复制代码

┌─────────────────────┐
│   Claude Code       │
│   (Host)            │
├─────────────────────┤
│  对话开始时：        │
│  1. 读取 .mcp.json  │
│  2. 启动 Server 进程│
│  3. 发现可用工具    │
├─────────────────────┤
│  对话中：           │
│  需要时调用工具     │
└──────────┬──────────┘
           │ stdio (JSON-RPC)
           ▼
┌─────────────────────┐
│   MCP Server        │
│   (独立进程)        │
├─────────────────────┤
│  暴露工具：         │
│  • search_wiki      │
│  • read_document    │
│  • send_message     │
└─────────────────────┘

配置示例

json 复制代码

// ~/.claude/.mcp.json
{
  "mcpServers": {
    "cooper": {
      "command": "python3",
      "args": ["/path/to/sql_query.py"],
      "env": {
        "COOPER_API_KEY": "xxx"
      }
    }
  }
}

加载流程

复制代码

1. Claude Code 启动
   └─→ 执行 python3 sql_query.py

2. Server 启动，监听 stdin
   └─→ 等待 Claude 的 JSON-RPC 请求

3. Claude 发送: {"method": "tools/list"}
   └─→ Server 返回可用工具列表

4. 工具注入到 Claude 可用工具集
   └─→ 如: sql_query__search_pages

5. 用户提问时，Claude 决定是否调用
   └─→ 调用时发送: {"method": "tools/call", "name": "search_pages", ...}

关键理解： MCP 注册的是进程，不是文件或函数。Server 通过协议声明自己提供什么工具。

七、Plugins：功能插件

是什么

Plugin 是扩展 Claude Code 核心功能的模块，可以添加新的能力或修改现有行为。

与其他机制的关系

机制	用途	扩展性
Plugin	核心功能扩展	高（可添加新工具类型）
MCP	外部系统集成	中（通过协议连接）
Skill	工作流程封装	低（基于现有工具）
Hook	事件拦截	中（修改行为）

八、Projects：项目隔离

是什么

Claude Code 为每个项目创建独立的存储空间，实现会话和记忆的隔离。

目录结构

复制代码

~/.claude/projects/
├── -项目名1/
│   ├── {session-id}.jsonl        # 会话历史
│   └── memory/                   # 项目记忆
│       ├── MEMORY.md
│       └── *.md
├── -项目名2/
│   ├── {session-id}.jsonl
│   └── memory/
└── ...

作用： 不同项目之间的会话、记忆完全隔离，互不干扰。

九、Sessions：会话管理

是什么

每次启动 Claude Code 或新建对话，都会创建一个 Session。

两层存储

复制代码

~/.claude/sessions/               # 运行时注册表
├── 38051.json                    # pid → sessionId 映射
└── 83947.json

~/.claude/projects/{hash}/        # 会话数据
├── session-a.jsonl               # 完整对话历史
└── session-b.jsonl

没啥牛的，就是存pid到session id的映射，让你的命令行知道，应该去拿哪个session会话记录。

会话隔离

场景	行为
新建会话	不加载任何历史
恢复会话	只加载对应 session-id 的历史
多终端	各自独立，通过 sessions/ 注册表协调

十、完整加载流程

复制代码

┌─────────────────────────────────────────────────────────────────────────┐
│                        Claude Code 完整启动流程                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  第一步：加载配置                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  ~/.claude/settings.json                                        │   │
│  │  ├─ 权限配置                                │   │
│  │  ├─ 环境变量                                           │   │
│  │  └─ 钩子配置                                           │   │
│  │                                                                  │   │
│  │  ./.claude/settings.local.json                                  │   │
│  │  └─ 覆盖全局配置                                                 │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│                              ▼                                          │
│  第二步：加载指令                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  ~/.claude/CLAUDE.md ───→ 全局指令（常驻上下文）                  │   │
│  │  ./.claude/CLAUDE.md ───→ 项目指令（常驻上下文）                  │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│                              ▼                                          │
│  第三步：加载记忆                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  ~/.claude/projects/{hash}/memory/MEMORY.md                     │   │
│  │  └─ 索引常驻，具体文件按需读取                                   │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│                              ▼                                          │
│  第四步：启动扩展                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  ~/.claude/.mcp.json ───→ 启动 MCP Servers                      │   │
│  │  ~/.claude/plugins/ ────→ 加载插件                               │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│                              ▼                                          │
│  第五步：发现技能                                                        │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  ~/.claude/skills/ ────→ 全局技能列表                            │   │
│  │  ./.claude/skills/ ───→ 项目技能列表（合并）                     │   │
│  │  ./.claude/commands/ ─→ 项目命令列表                             │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                              │                                          │
│                              ▼                                          │
│  第六步：注入系统提示                                                    │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  将以上内容组装成系统提示，注入到 LLM 上下文                      │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

十一、设计智慧总结

1. 分层设计

复制代码

全局级（通用）→ 项目级（特定）→ 会话级（临时）

好处：共享通用配置，隔离项目差异。

2. 常驻 vs 按需

常驻（每次加载）	按需（需要时加载）
CLAUDE.md	Memory 具体文件
MEMORY.md 索引	MCP tool 调用
Skills 列表	Skill 执行
MCP tools 列表

好处：节省上下文，按需获取。

3. 进程隔离

复制代码

MCP Server = 独立进程
    │
    ├─→ 崩溃不影响 Claude Code

4. 文件即配置

复制代码

CLAUDE.md    → Markdown 文件
SKILL.md     → Markdown 文件
MEMORY.md    → Markdown 文件
.mcp.json    → JSON 文件
settings.json → JSON 文件

好处：易读、易编辑、可版本控制。

十二、实践建议

1. 全局 CLAUDE.md 放什么

你的角色定位
工作风格和原则
通用的代码规范
常用的工具偏好

2. 项目 CLAUDE.md 放什么

项目概述和技术栈
目录结构说明
项目特定的规范
常用命令

3. Memory 放什么

用户偏好（user）
工作反馈（feedback）
项目进度（project）
外部引用（reference）

4. Skills 放什么

通用工作流 → 全局级
项目特定流程 → 项目级

5. MCP 用于什么

连接外部 API
访问数据库
集成内部系统

结语

Claude Code 的加载机制设计精巧，核心理念是：

分层管理 --- 全局共享，项目隔离
按需加载 --- 索引常驻，详情按需
文件驱动 --- 配置即代码，易读易改
扩展灵活 --- MCP、Skill、Hook、Plugin 多层扩展

理解这些机制，能让你更好地配置和使用 Claude Code，免得开黑盒，被这家伙瞎改全局配置。