<!-- title: Claude Code数据科学入门全实战 -->
# Claude Code数据科学入门：从数据分析到ML预测全流程实战

## 概述

本教程面向零基础或初学者，教你如何使用 Claude Code 作为数据科学的 AI 结对编程伙伴，从零搭建项目环境、执行数据清洗与探索性分析（EDA），到构建并评估机器学习模型。你将学会 Claude Code 在数据科学场景下的核心工作流——如何通过自然语言指令完成从数据加载到模型部署的完整链路。无需深厚的前端或后端经验，只需基本的 Python 概念即可上手。

**适用人群**：数据分析师转型者、机器学习入门者、希望用 AI 提升数据工作效率的开发者

**学习目标**：
- 完成Claude Code 安装与数据科学项目初始化
- 编写数据驱动的 CLAUDE.md 配置
- 用自然语言驱动数据清洗、EDA、特征工程
- 构建、训练、评估 Scikit-learn 机器学习模型
- 掌握数据科学场景下的 Claude Code 最佳实践

## 前置条件

| 项目 | 要求 |
|------|------|
| 操作系统 | macOS / Linux / Windows (WSL2) |
| Node.js | v18+ |
| Python | 3.10+ |
| 包管理 | uv 或 pip |
| Anthropic 账号 | 有 API 额度或 Claude Pro/Max 订阅 |
| 基础知识 | 了解 Python 基本语法（变量、函数、列表） |

> **为什么选择 Claude Code 而非 Jupyter Notebook？** Claude Code 不是替代 Jupyter，而是增强你的工作流。你可以在终端中直接让 AI 生成代码、运行脚本、分析结果，省去反复搜索 Stack Overflow 的时间。它理解整个项目上下文，而不是只看到单个 cell。

---

## 第一步：安装 Claude Code

### 1.1 安装 Node.js 与 Claude Code CLI

```bash
# 检查 Node.js 版本
node --version   # 需要 v18+

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version
```

**预期输出**：
```
Claude Code v2.x.x
```

### 1.2 首次认证

```bash
# 启动认证流程（浏览器自动打开）
claude

# 或使用 API Key 方式
export ANTHROPIC_API_KEY="sk-ant-xxxxx"
claude
```

认证成功后终端会显示 `Authenticated successfully`。

### 1.3 常见安装问题

| 问题 | 解决方案 |
|------|----------|
| `command not found: claude` | 检查 npm 全局路径是否在 `$PATH` 中，运行 `npm config get prefix` 确认 |
| `EACCES permission denied` | 不要用 `sudo npm install -g`，改用 `npx` 或配置 npm 全局目录 |
| Node 版本过低 | 使用 `nvm install 20` 升级 |
| WSL2 下浏览器不弹出 | 运行 `export BROWSER=/mnt/c/Program\ Files/Google/Chrome/Application/chrome.exe` |

---

## 第二步：创建数据科学项目

### 2.1 初始化项目结构

```bash
# 创建项目目录
mkdir house-price-predictor && cd house-price-predictor

# 初始化 Python 环境（推荐 uv）
uv init
uv add pandas scikit-learn matplotlib seaborn jupyter

# 创建标准数据科学目录结构
mkdir -p data/raw data/processed src notebooks outputs/models outputs/figures
```

项目结构如下：

```
house-price-predictor/
├── CLAUDE.md              # 项目上下文配置
├── pyproject.toml          # Python 依赖管理
├── data/
│   ├── raw/               # 原始数据（不可修改）
│   └── processed/         # 清洗后数据
├── src/
│   ├── __init__.py
│   ├── data_loader.py     # 数据加载模块
│   ├── features.py        # 特征工程模块
│   ├── model.py           # 模型定义
│   └── evaluate.py        # 模型评估
├── notebooks/
│   └── 01_eda.ipynb       # 探索性分析
└── outputs/
    ├── models/            # 保存的模型
    └── figures/           # 可视化图表
```

### 2.2 编写数据科学专属 CLAUDE.md

在项目根目录创建 `CLAUDE.md`，这是 Claude Code 理解你项目的关键配置文件：

```markdown
# House Price Predictor

## 项目概述
房价预测机器学习项目，使用 Scikit-learn 构建回归模型。

## 技术栈
- Python 3.12, uv 包管理
- pandas, scikit-learn, matplotlib, seaborn
- 运行命令: `uv run python src/main.py`

## 代码规范
- 使用 type hints
- 函数有 docstring
- 数据路径使用 pathlib.Path
- 图表保存到 outputs/figures/，不弹出窗口（matplotlib.use('Agg')）
- 模型用 joblib 保存到 outputs/models/

## 数据说明
- 原始数据放在 data/raw/，不可修改
- 处理后数据保存到 data/processed/
- 目标变量: SalePrice（房屋售价）

## 测试
- 运行: `uv run pytest tests/ -v`
- 测试覆盖率目标: >80%
```

> **为什么要写 CLAUDE.md？** Claude Code 在每次对话开始时自动读取此文件。它相当于给 AI 助手一份项目说明书，让它知道技术栈、目录结构、命名规范，从而生成更准确的代码。数据科学项目特别需要指定 matplotlib 的 backend 设置，否则远程环境下会因无法弹出窗口而报错。

### 2.3 准备示例数据

```bash
# 下载经典房价数据集（Ames Housing Dataset 的精简版）
curl -L -o data/raw/housing.csv \
  "https://raw.githubusercontent.com/house-price-prediction/sample-data/main/housing.csv"

# 如果网络不通，让 Claude Code 帮你生成模拟数据
claude "生成一个包含1000条记录的模拟房价数据集CSV，包含字段：
LotArea, OverallQual, YearBuilt, TotalBsmtSF, GrLivArea, FullBath,
GarageCars, Neighborhood, SalePrice。保存到 data/raw/housing.csv"
```

---

## 第三步：数据加载与清洗

### 3.1 启动 Claude Code 开始工作

```bash
# 在项目根目录启动
cd house-price-predictor
claude
```

进入交互式终端后，你将看到 Claude Code 的提示符 `>`。

### 3.2 用自然语言驱动数据加载

输入以下指令：

```
请帮我编写 src/data_loader.py，完成以下功能：
1. 使用 pandas 读取 data/raw/housing.csv
2. 打印数据形状、列名、数据类型
3. 显示缺失值统计
4. 显示数值列的描述性统计
然后运行它，把结果展示给我
```

Claude Code 会自动：
1. 读取 CLAUDE.md 了解项目结构
2. 生成 `data_loader.py` 代码
3. 运行脚本
4. 展示输出结果

**预期输出示例**：
```
数据形状: (1000, 9)
列名: ['LotArea', 'OverallQual', 'YearBuilt', 'TotalBsmtSF', 'GrLivArea', 'FullBath', 'GarageCars', 'Neighborhood', 'SalePrice']

缺失值统计:
LotArea        0
OverallQual    0
YearBuilt      5
TotalBsmtSF    3
GrLivArea      0
FullBath       0
GarageCars     8
Neighborhood   0
SalePrice      0

数值列描述性统计:
         LotArea  OverallQual   YearBuilt  TotalBsmtSF  ...
count   1000.00      1000.00     995.00      997.00  ...
mean   10516.83         6.10    1984.32     1057.43  ...
```

### 3.3 让 Claude Code 执行数据清洗

继续输入：

```
数据中有 YearBuilt 缺失5条、TotalBsmtSF 缺失3条、GarageCars 缺失8条。
请帮我处理：
1. YearBuilt 用中位数填充
2. TotalBsmtSF 用0填充（可能没有地下室）
3. GarageCars 用0填充（可能没有车库）
4. 检查并删除 GrLivArea > 4000 的异常值
5. 保存清洗后数据到 data/processed/housing_clean.csv
然后更新 src/data_loader.py 并运行验证
```

**关键洞察**：Claude Code 的优势在于你可以用领域知识（如"没有地下室"意味着面积应为0）来指导数据清洗，而 AI 负责实现具体代码。这种人机协作模式比纯手动编码效率高3-5倍。

### 3.4 常见数据清洗问题

| 问题 | Claude Code 指令示例 |
|------|---------------------|
| 编码错误 | `"读取CSV时报UnicodeDecodeError，请尝试 latin-1 或 gbk 编码"` |
| 日期解析 | `"将 YearBuilt 列解析为整数，检查是否有异常值如0或负数"` |
| 重复数据 | `"检查数据中是否有重复行，如有则删除并报告删除数量"` |
| 类别型变量 | `"列出所有 object 类型的列及其唯一值数量，建议编码方案"` |

---

## 第四步：探索性数据分析（EDA）

### 4.1 自动化 EDA 图表生成

```
请帮我完成 src/eda.py，生成以下图表并保存到 outputs/figures/：
1. SalePrice 的分布直方图（带KDE曲线）
2. OverallQual 与 SalePrice 的箱线图
3. GrLivArea 与 SalePrice 的散点图（带回归线）
4. 数值变量的相关系数热力图
5. 各 Neighborhood 的房价中位数条形图（降序排列）

要求：图表风格用 seaborn 的 whitegrid 主题，中文字体不报错，
     所有图表 dpi=150，figsize=(10, 6)
```

Claude Code 会生成完整的 EDA 脚本。以下是 `src/eda.py` 的核心逻辑：

```python
import matplotlib
matplotlib.use('Agg')  # 关键：非交互式后端
import matplotlib.pyplot as plt
import seaborn as sns
import pandas as pd
from pathlib import Path

def plot_target_distribution(df: pd.DataFrame, save_path: Path) -> None:
    """绘制目标变量 SalePrice 的分布图。"""
    fig, ax = plt.subplots(figsize=(10, 6))
    sns.histplot(df['SalePrice'], kde=True, ax=ax, color='#2196F3')
    ax.set_title('SalePrice Distribution', fontsize=14)
    ax.set_xlabel('Sale Price ($)', fontsize=12)
    ax.set_ylabel('Count', fontsize=12)
    fig.savefig(save_path / '01_target_distribution.png', dpi=150, bbox_inches='tight')
    plt.close(fig)

def plot_correlation_heatmap(df: pd.DataFrame, save_path: Path) -> None:
    """绘制数值变量相关系数热力图。"""
    numeric_cols = df.select_dtypes(include='number').columns
    corr = df[numeric_cols].corr()
    fig, ax = plt.subplots(figsize=(12, 10))
    sns.heatmap(corr, annot=True, fmt='.2f', cmap='RdBu_r',
                center=0, ax=ax, square=True)
    ax.set_title('Feature Correlation Heatmap', fontsize=14)
    fig.savefig(save_path / '04_correlation_heatmap.png', dpi=150, bbox_inches='tight')
    plt.close(fig)

# ... 其余图表函数
```

### 4.2 让 Claude Code 解读分析结果

```
请运行 src/eda.py，然后根据生成的图表告诉我：
1. SalePrice 的分布是否偏斜？是否需要对数变换？
2. 哪些特征与 SalePrice 的相关性最强（相关系数 > 0.5）？
3. 有没有明显的异常值模式？
4. 你建议选择哪些特征进入模型？
```

Claude Code 会分析输出并给出专业解读，例如：

> "SalePrice 呈右偏分布（偏度约1.8），建议进行 log1p 变换。与 SalePrice 相关性最强的特征为：OverallQual (0.79)、GrLivArea (0.71)、TotalBsmtSF (0.61)、GarageCars (0.64)。建议选用这4个核心特征加上 YearBuilt 和 FullBath 进入基线模型。"

### 4.3 交互式迭代

```
请生成一个 SalePrice 的对数变换前后对比图，
如果 log1p 变换后更接近正态分布，就把变换应用到清洗数据中
```

---

## 第五步：特征工程与模型构建

### 5.1 特征工程

```
请编写 src/features.py，完成以下特征工程：
1. 对 SalePrice 做 log1p 变换
2. 对 Neighborhood 做 Target Encoding（用训练集均值）
3. 创建新特征：HouseAge = YrSold - YearBuilt（假设当前年份2026）
4. 创建新特征：TotalSF = TotalBsmtSF + GrLivArea
5. 对数值特征做 StandardScaler 标准化
6. 使用 train_test_split 划分数据（test_size=0.2, random_state=42）

注意：拟合（fit）只在训练集上做，测试集用 transform
保存特征名称列表供后续使用
```

> **关键原则：防止数据泄漏**。在提示中明确告诉 Claude Code "拟合只在训练集上做"，可以避免数据泄漏——这是数据科学项目中最常见也最致命的错误之一。

### 5.2 构建基线模型

```
请编写 src/model.py，训练以下4个回归模型并比较性能：
1. LinearRegression（基线）
2. Ridge（alpha=1.0）
3. RandomForestRegressor（n_estimators=100, random_state=42）
4. GradientBoostingRegressor（n_estimators=200, learning_rate=0.1）

评估指标：RMSE, MAE, R²（注意：指标要在反变换后的原始价格上计算）
用 matplotlib 画一个模型对比条形图，保存到 outputs/figures/
将最佳模型保存到 outputs/models/best_model.joblib
```

**核心代码结构**：

```python
from sklearn.linear_model import LinearRegression, Ridge
from sklearn.ensemble import RandomForestRegressor, GradientBoostingRegressor
from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
import numpy as np
import joblib

MODELS = {
    "LinearRegression": LinearRegression(),
    "Ridge": Ridge(alpha=1.0),
    "RandomForest": RandomForestRegressor(n_estimators=100, random_state=42),
    "GradientBoosting": GradientBoostingRegressor(
        n_estimators=200, learning_rate=0.1, random_state=42
    ),
}

def train_and_evaluate(X_train, X_test, y_train, y_test):
    """训练多个模型，返回评估结果和最佳模型。"""
    results = {}
    for name, model in MODELS.items():
        model.fit(X_train, y_train)
        y_pred_log = model.predict(X_test)
        # 反变换：从 log1p 空间回到原始价格
        y_pred = np.expm1(y_pred_log)
        y_true = np.expm1(y_test)
        results[name] = {
            "RMSE": np.sqrt(mean_squared_error(y_true, y_pred)),
            "MAE": mean_absolute_error(y_true, y_pred),
            "R2": r2_score(y_true, y_pred),
            "model": model,
        }
    return results
```

### 5.3 运行完整流水线

```
请按顺序运行完整的模型训练流水线：
1. 加载清洗后数据 data/processed/housing_clean.csv
2. 执行特征工程 src/features.py
3. 训练和评估模型 src/model.py
4. 输出各模型的 RMSE、MAE、R² 对比表
5. 保存最佳模型和对比图
```

**预期输出**：

```
╔═════════════════════╦══════════╦═════════╦═══════╗
║ Model               ║ RMSE ($) ║ MAE ($) ║  R²   ║
╠═════════════════════╬══════════╬═════════╬═══════╣
║ LinearRegression    ║ 38,421   ║ 26,153  ║ 0.762 ║
║ Ridge               ║ 37,892   ║ 25,831  ║ 0.769 ║
║ RandomForest        ║ 31,256   ║ 20,417  ║ 0.843 ║
║ GradientBoosting    ║ 28,734   ║ 18,692  ║ 0.867 ║ ← Best
╚═════════════════════╩══════════╩═════════╩═══════╝

最佳模型: GradientBoosting (R²=0.867)
已保存到 outputs/models/best_model.joblib
```

---

## 第六步：模型评估与优化

### 6.1 深入评估最佳模型

```
请编写 src/evaluate.py，对最佳模型做深入评估：
1. 预测值 vs 实际值的散点图（对角线参考线）
2. 残差分布图（直方图 + QQ图）
3. 特征重要性排序条形图
4. 使用 5-fold 交叉验证计算 R² 的均值和标准差
5. 生成评估报告保存到 outputs/evaluation_report.txt
```

### 6.2 超参数调优

```
对 GradientBoosting 模型做超参数调优，使用 GridSearchCV：
- n_estimators: [100, 200, 300]
- learning_rate: [0.05, 0.1, 0.15]
- max_depth: [3, 5, 7]
- min_samples_split: [2, 5]

5-fold CV，评分用 neg_mean_squared_error
报告最佳参数和对应的 CV 分数
保存调优后的模型为 outputs/models/tuned_model.joblib
```

### 6.3 防止过拟合检查

```
请检查调优后的模型是否存在过拟合：
1. 比较训练集和测试集上的 R² 差值
2. 如果差值 > 0.1，说明存在过拟合，请：
   - 减小 max_depth
   - 增加 min_samples_leaf
   - 添加 subsample=0.8
3. 重新训练并比较
```

---

## 完整实战案例：房价预测主程序

以下是将所有步骤串联起来的完整 `src/main.py`：

```python
"""房价预测项目主程序 - 从数据加载到模型评估的完整流水线。"""

from pathlib import Path
import pandas as pd
import numpy as np
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
from sklearn.ensemble import GradientBoostingRegressor
from sklearn.metrics import mean_squared_error, mean_absolute_error, r2_score
import joblib

# 路径常量
ROOT = Path(__file__).resolve().parent.parent
DATA_RAW = ROOT / "data" / "raw"
DATA_PROCESSED = ROOT / "data" / "processed"
FIGURES = ROOT / "outputs" / "figures"
MODELS = ROOT / "outputs" / "models"


def load_data(filepath: Path) -> pd.DataFrame:
    """加载原始数据。"""
    df = pd.read_csv(filepath)
    print(f"数据形状: {df.shape}")
    print(f"缺失值:\n{df.isnull().sum()[df.isnull().sum() > 0]}")
    return df


def clean_data(df: pd.DataFrame) -> pd.DataFrame:
    """清洗数据：填充缺失值、移除异常值。"""
    df = df.copy()
    df["YearBuilt"] = df["YearBuilt"].fillna(df["YearBuilt"].median())
    df["TotalBsmtSF"] = df["TotalBsmtSF"].fillna(0)
    df["GarageCars"] = df["GarageCars"].fillna(0)
    df = df[df["GrLivArea"] <= 4000]
    return df


def engineer_features(df: pd.DataFrame) -> tuple:
    """特征工程：创建新特征、编码、标准化。"""
    df = df.copy()
    df["SalePrice"] = np.log1p(df["SalePrice"])
    df["HouseAge"] = 2026 - df["YearBuilt"]
    df["TotalSF"] = df["TotalBsmtSF"] + df["GrLivArea"]

    feature_cols = [
        "LotArea", "OverallQual", "YearBuilt", "TotalBsmtSF",
        "GrLivArea", "FullBath", "GarageCars", "HouseAge", "TotalSF",
    ]
    X = df[feature_cols]
    y = df["SalePrice"]

    X_train, X_test, y_train, y_test = train_test_split(
        X, y, test_size=0.2, random_state=42
    )

    scaler = StandardScaler()
    X_train_scaled = scaler.fit_transform(X_train)
    X_test_scaled = scaler.transform(X_test)

    return X_train_scaled, X_test_scaled, y_train, y_test, scaler, feature_cols


def train_model(X_train, y_train) -> GradientBoostingRegressor:
    """训练梯度提升回归模型。"""
    model = GradientBoostingRegressor(
        n_estimators=200, learning_rate=0.1,
        max_depth=5, random_state=42
    )
    model.fit(X_train, y_train)
    return model


def evaluate_model(model, X_test, y_test) -> dict:
    """评估模型性能（反变换回原始价格）。"""
    y_pred = np.expm1(model.predict(X_test))
    y_true = np.expm1(y_test)
    return {
        "RMSE": np.sqrt(mean_squared_error(y_true, y_pred)),
        "MAE": mean_absolute_error(y_true, y_pred),
        "R2": r2_score(y_true, y_pred),
    }


def main():
    """运行完整流水线。"""
    # 确保输出目录存在
    FIGURES.mkdir(parents=True, exist_ok=True)
    MODELS.mkdir(parents=True, exist_ok=True)

    # 1. 加载
    print("=" * 50)
    print("Step 1: 加载数据")
    df = load_data(DATA_RAW / "housing.csv")

    # 2. 清洗
    print("=" * 50)
    print("Step 2: 清洗数据")
    df_clean = clean_data(df)
    df_clean.to_csv(DATA_PROCESSED / "housing_clean.csv", index=False)
    print(f"清洗后数据形状: {df_clean.shape}")

    # 3. 特征工程
    print("=" * 50)
    print("Step 3: 特征工程")
    X_train, X_test, y_train, y_test, scaler, features = engineer_features(df_clean)
    print(f"训练集: {X_train.shape}, 测试集: {X_test.shape}")

    # 4. 训练
    print("=" * 50)
    print("Step 4: 训练模型")
    model = train_model(X_train, y_train)

    # 5. 评估
    print("=" * 50)
    print("Step 5: 评估模型")
    metrics = evaluate_model(model, X_test, y_test)
    print(f"RMSE: ${metrics['RMSE']:,.0f}")
    print(f"MAE:  ${metrics['MAE']:,.0f}")
    print(f"R²:   {metrics['R2']:.4f}")

    # 6. 保存
    joblib.dump(model, MODELS / "best_model.joblib")
    print(f"\n模型已保存到 {MODELS / 'best_model.joblib'}")


if __name__ == "__main__":
    main()
```

运行命令：

```bash
uv run python src/main.py
```

---

## 工作流程全景图

```mermaid
flowchart TB
    subgraph 准备阶段
        A[安装 Claude Code CLI] --> B[创建项目结构]
        B --> C[编写 CLAUDE.md]
        C --> D[安装 Python 依赖]
    end

    subgraph 数据阶段
        D --> E[加载原始数据]
        E --> F[检查缺失值/异常值]
        F --> G[数据清洗与填充]
        G --> H[保存清洗后数据]
    end

    subgraph 分析阶段
        H --> I[EDA: 分布/相关性/箱线图]
        I --> J[Claude Code 解读图表]
        J --> K{分布偏斜?}
        K -- 是 --> L[log1p 变换]
        K -- 否 --> M[保持原样]
        L --> N[特征工程]
        M --> N
    end

    subgraph 建模阶段
        N --> O[划分训练/测试集]
        O --> P[训练多个候选模型]
        P --> Q[交叉验证评估]
        Q --> R[选择最佳模型]
        R --> S[超参数调优]
        S --> T[过拟合检查]
    end

    subgraph 交付阶段
        T --> U[保存最终模型]
        U --> V[生成评估报告]
        V --> W[输出预测结果]
    end

    style 准备阶段 fill:#e3f2fd
    style 数据阶段 fill:#f3e5f5
    style 分析阶段 fill:#e8f5e9
    style 建模阶段 fill:#fff3e0
    style 交付阶段 fill:#fce4ec
```

---

## Claude Code 数据科学最佳实践

### 7.1 上下文管理技巧

数据科学项目上下文窗口容易被大量数据输出填满。以下是保持 Claude Code 高效工作的策略：

**策略一：分阶段工作**

```
# 不要一次性要求所有分析，分步骤进行
# 第1步：只做数据加载
> 请帮我加载 housing.csv 并显示基本信息

# 第2步：确认无误后再做清洗
> 基于以上信息，请执行数据清洗

# 第3步：清洗完成后再做EDA
> 数据清洗完成，请生成EDA图表
```

**策略二：使用 `/compact` 管理上下文**

```
# 当对话变长时，压缩历史上下文
> /compact

# 或带提示的压缩
> /compact 保留特征工程和数据清洗的关键决策，删除中间输出
```

**策略三：用 `/clear` 开始新阶段**

```
# 进入建模阶段时清空上下文
> /clear

# 重新加载项目上下文
> 请阅读 CLAUDE.md 和 src/ 目录下的文件，准备开始建模
```

### 7.2 高效提示词模板

| 场景 | 提示词模板 |
|------|-----------|
| 数据概览 | `"读取 {file}，显示 shape、dtypes、describe()、缺失值统计"` |
| 数据清洗 | `"处理 {col} 列的缺失值，策略是 {strategy}，理由是 {reason}"` |
| 可视化 | `"画 {chart_type} 展示 {x} 和 {y} 的关系，保存到 {path}"` |
| 特征工程 | `"创建新特征 {name} = {formula}，并说明物理含义"` |
| 模型训练 | `"训练 {model_name}，评估用 {metrics}，注意防止 {issue}"` |
| 调优 | `"用 {search_method} 调优，参数空间为 {params}，CV={k}折"` |

### 7.3 关键 Slash 命令速查

| 命令 | 用途 | 数据科学场景 |
|------|------|-------------|
| `/compact` | 压缩对话上下文 | EDA输出过多时 |
| `/clear` | 清空对话历史 | 切换分析阶段 |
| `/cost` | 查看Token用量 | 控制API消耗 |
| `/init` | 初始化CLAUDE.md | 新项目启动 |
| `/plan` | 进入计划模式 | 复杂特征工程设计 |
| `/review` | 代码审查 | 检查数据泄漏 |
| `/status` | 查看上下文状态 | 确认Token使用情况 |

### 7.4 使用 Plan Mode 做复杂决策

面对复杂的建模决策时，进入 Plan Mode 让 Claude Code 先制定方案：

```
> /plan

# Plan Mode 下，Claude Code 会分析而非执行
# 请帮我设计一个完整的特征工程方案：
# - 考虑类别变量的编码方式（OneHot vs Target Encoding）
# - 考虑是否需要多项式特征
# - 考虑特征选择策略
# - 给出理由和预期效果
```

Plan Mode 的优势：Claude Code 会读取项目文件、分析数据特征，然后输出方案让你确认。确认后再退出 Plan Mode 执行，避免盲目修改代码。

### 7.5 让 Claude Code 写测试

```
请为 src/features.py 编写单元测试 tests/test_features.py：
1. 测试缺失值填充是否正确（填充前后数量对比）
2. 测试异常值过滤是否正确（GrLivArea > 4000 被移除）
3. 测试新特征 HouseAge 计算是否正确
4. 测试标准化后均值为0、标准差为1
5. 测试 train/test 划分比例是否正确

使用 pytest，运行命令: uv run pytest tests/ -v
```

---

## 常见陷阱与解决方案

### 陷阱一：数据泄漏

```python
# 错误：在整个数据集上做标准化
scaler.fit(X)  # ← 测试集信息泄漏到训练过程

# 正确：只在训练集上 fit
scaler.fit(X_train)
X_train_scaled = scaler.transform(X_train)
X_test_scaled = scaler.transform(X_test)
```

**Claude Code 防泄漏提示**：
```
请检查 src/features.py 中是否存在数据泄漏：
- 所有 fit/fit_transform 是否只在训练集上
- Target Encoding 是否用了测试集的目标值
- 特征选择是否在划分前执行
如果有问题请修复并解释
```

### 陷阱二：评估指标在错误空间计算

```python
# 错误：在 log 变换空间计算 RMSE
rmse = np.sqrt(mean_squared_error(y_test, y_pred_log))

# 正确：在原始价格空间计算
y_pred = np.expm1(y_pred_log)
y_true = np.expm1(y_test)
rmse = np.sqrt(mean_squared_error(y_true, y_pred))
```

### 陷阱三：Matplotlib 弹窗导致脚本挂起

确保 CLAUDE.md 中包含 `matplotlib.use('Agg')` 配置，或在所有脚本开头设置：

```python
import matplotlib
matplotlib.use('Agg')  # 必须在 import pyplot 之前
import matplotlib.pyplot as plt
```

---

## 进阶：从本地到自动化

### 8.1 使用 `-p` 模式自动化批量分析

```bash
# 非交互模式：自动生成 EDA 报告
claude -p "运行 src/eda.py 并总结关键发现" \
  --output-format json > outputs/eda_summary.json

# 批量处理多个数据集
for dataset in data/raw/*.csv; do
  claude -p "分析 $dataset 的数据质量，生成缺失值报告和分布图"
done
```

### 8.2 配置 Hooks 自动运行测试

在 `.claude/settings.json` 中配置 Hook，让 Claude Code 每次修改代码后自动运行测试：

```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "cd $PROJECT_DIR && uv run pytest tests/ -v --tb=short 2>&1 | tail -20"
          }
        ]
      }
    ]
  }
}
```

这样每次 Claude Code 修改 Python 文件后，会自动运行测试并显示结果。

### 8.3 使用 Headless Mode 集成到数据流水线

```bash
# 完全自动化的每日数据质量报告
claude -p "加载数据/raw/daily_data.csv，检查数据质量，生成报告，如果有异常则发送邮件通知" \
  --allowedTools "Bash,Read,Write" \
  --model claude-sonnet-4-6
```

---

## 项目工作流总览

```mermaid
sequenceDiagram
    participant U as 用户
    participant CC as Claude Code
    participant FS as 文件系统
    participant PY as Python 运行时

    U->>CC: 启动 claude
    CC->>FS: 读取 CLAUDE.md
    CC-->>U: 准备就绪

    Note over U,PY: 数据加载与清洗阶段
    U->>CC: "加载 housing.csv 并清洗"
    CC->>FS: 写入 src/data_loader.py
    CC->>PY: uv run python src/data_loader.py
    PY-->>CC: 数据统计输出
    CC->>FS: 保存 housing_clean.csv
    CC-->>U: 清洗结果摘要

    Note over U,PY: EDA 阶段
    U->>CC: "生成 EDA 图表"
    CC->>FS: 写入 src/eda.py
    CC->>PY: uv run python src/eda.py
    PY-->>CC: 图表已保存
    CC-->>U: 分析解读

    Note over U,PY: 建模阶段
    U->>CC: "训练模型并评估"
    CC->>FS: 写入 src/model.py
    CC->>PY: uv run python src/model.py
    PY-->>CC: 评估指标
    CC->>FS: 保存 best_model.joblib
    CC-->>U: 模型性能报告

    Note over U,PY: 优化阶段
    U->>CC: "调优超参数"
    CC->>FS: 更新 src/model.py
    CC->>PY: 运行 GridSearchCV
    PY-->>CC: 最佳参数
    CC-->>U: 调优结果
```

---

## 延伸阅读

- [Anthropic 官方文档 - Claude Code Overview](https://docs.anthropic.com/en/docs/claude-code/overview) — Claude Code 官方使用指南
- [Claude Code Best Practices - DataCamp](https://www.datacamp.com/tutorial/claude-code-best-practices) — 生产级 Claude Code 最佳实践
- [Getting Started with Claude Code for Data Scientists - DataQuest](https://www.dataquest.io/blog/getting-started-with-claude-code-for-data-scientists/) — 数据科学家视角的入门教程
- [Claude Code for Data Analysis - Vincent Codes Finance](https://vincent.codes.finance/posts/claude-code-data-analysis/) — 金融数据分析实战
- [Claude Code Cheat Sheet 2026 - ComputingForGeeks](https://computingforgeeks.com/claude-code-cheat-sheet/) — 命令速查手册

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| 适合训练营类型 | 数据科学训练营、AI 应用入门营、Python 实战营 |
| 预计教学时长 | 4-6小时（含动手练习） |
| 学员基础要求 | Python 基本语法、了解 pandas 概念 |
| 硬件要求 | 4GB+ RAM，能运行 Node.js 18+ 和 Python 3.10+ |
| 分节建议 | 第1-2节（1h）→ 第3-4节（1.5h）→ 第5节（1h）→ 第6-8节（1.5h） |
| 考核方式 | 学员独立完成一个新数据集的 EDA + 基线模型构建 |
| 常见教学风险 | API 额度不足、网络问题无法下载依赖、matplotlib 后端配置 |

## 参考来源

1. [Getting Started with Claude Code for Data Scientists - DataQuest](https://www.dataquest.io/blog/getting-started-with-claude-code-for-data-scientists/) — 数据科学家视角的完整入门指南，涵盖 CLAUDE.md 配置和项目结构
2. [Claude Code Best Practices: Planning, Context Transfer, TDD - DataCamp](https://www.datacamp.com/tutorial/claude-code-best-practices) — 生产团队的最佳实践，包含 Plan Mode 和上下文管理技巧
3. [45 Claude Code Tips: From Basics to Advanced - GitHub](https://github.com/ykdojo/claude-code-tips) — 社区贡献的45条实用技巧，从基础到高级
4. [The Complete Claude Code Testing Workflow Guide - jmliu6](https://www.jmliu6.com/en/blog/claude-code-testing) — 系统化的测试工作流指南，涵盖 TDD 到 CI/CD 集成
5. [How to Use Claude Code for Python & Data Science - GetBeam](https://getbeam.dev/blog/claude-code-python-data-science.html) — Python 数据科学工作流的实战教程

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)