diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b349d46
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,117 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+基于 Rust + Axum 的配置驱动型 Mock 服务。在 `mocks/` 目录下通过 YAML 文件定义 API 行为，无需修改代码即可添加/修改接口。
+
+**核心特性：**
+- YAML 驱动的请求匹配（method、path、query_params、headers、body）
+- 热重载：`mocks/*.yaml` 变更自动生效，无需重启服务
+- 大文件流式响应：通过 `file://` 协议从磁盘流式读取
+- 文件上传端点：`POST /api/upload`
+
+## 构建与测试命令
+
+```bash
+cargo build              # 构建项目
+cargo run                # 启动服务 http://127.0.0.1:8080
+cargo test               # 运行所有测试
+cargo test <pattern>     # 运行匹配的测试（如 `cargo test router`）
+cargo clippy             # 代码检查
+cargo fmt                # 格式化代码
+```
+
+## 架构
+
+```
+┌─────────────┐    ┌──────────────┐    ┌────────────────┐
+│  loader.rs  │───▶│   router.rs  │───▶│   handler.rs   │
+│ YAML → 索引 │    │ HashMap 索引  │    │  请求/响应处理  │
+└─────────────┘    └──────────────┘    └────────────────┘
+       ▲                                       │
+       │         ┌──────────────────┐          │
+       └─────────│   main.rs        │◀─────────┘
+         热重载   │ AppState(RwLock)│
+                 └──────────────────┘
+```
+
+**数据流：**
+1. `MockLoader` 扫描 `mocks/` 目录，解析 YAML 为 `MockRule` 结构体
+2. 规则按路径首段建立索引（如 `/api/users` → key: `api`）存储于 `MockRouter`
+3. 请求匹配顺序：method → path → query_params → headers → body
+4. `AppState` 使用 `RwLock` 包装 router，支持线程安全的热重载
+
+**核心类型 (config.rs)：**
+- `MockRule`: 完整规则（id, request, response, settings）
+- `RequestMatcher`: 请求匹配条件（method, path, query_params, headers, body）
+- `MockResponse`: 响应配置（status, headers, body）
+- `MockSource`: 枚举类型，支持单接口/多接口 YAML 格式
+
+**请求匹配 (router.rs)：**
+- 路径首段 HashMap 查找，O(1) 获取候选规则
+- 候选集内线性扫描进行精确匹配
+- Body 匹配：支持 JSON 对象和字符串两种比较方式
+
+**响应处理 (handler.rs)：**
+- 内联 body：直接返回
+- `file://` 前缀：从磁盘流式读取文件（低内存占用）
+- `settings.delay_ms`：模拟网络延迟
+
+## YAML 配置示例
+
+**单接口模式：**
+```yaml
+id: "login"
+request:
+  method: "POST"
+  path: "/api/login"
+  body: { "username": "test" }
+response:
+  status: 200
+  body: '{"token": "xxx"}'
+settings:
+  delay_ms: 100
+```
+
+**多接口模式（数组）：**
+```yaml
+- id: "get-users"
+  request: { method: "GET", path: "/api/users" }
+  response: { status: 200, body: '{"users": []}' }
+
+- id: "create-user"
+  request: { method: "POST", path: "/api/users" }
+  response: { status: 201, body: '{"id": 1}' }
+```
+
+**文件响应模式：**
+```yaml
+response:
+  body: "file://./data/large-file.pdf"
+```
+
+## 文件结构
+
+```
+src/
+├── main.rs      # 入口，热重载监听，Axum 路由配置
+├── config.rs    # 数据结构定义（MockRule, RequestMatcher 等）
+├── loader.rs    # YAML 解析，目录扫描
+├── router.rs    # 路径首段索引，匹配逻辑
+├── handler.rs   # 统一请求处理器，文件流式响应
+└── upload.rs    # Multipart 文件上传处理
+
+tests/           # 集成测试（每个模块一个测试文件）
+mocks/           # YAML Mock 配置文件
+storage/         # 上传文件存储（按 YYYY-MM-DD 分目录）
+```
+
+## 开发注意事项
+
+- **Rust Edition 2024**，Axum 0.8.8
+- 测试使用 `tempfile` crate 处理临时文件
+- 请求体大小限制：10MB (handler.rs:30)
+- 热重载防抖时间：200ms (main.rs:46)
+- Header 匹配大小写不敏感 (router.rs:75)