<!-- title: 零基础首项目：CSV数据分析 -->

# Claude Code 入门篇：用 Agentic CLI 完成第一个数据分析项目

## 概述

本教程面向**非专业程序员**——数据分析师、产品经理、运营、科研人员、财务、自媒体作者——只要你手里有一份 CSV/Excel 表格，想让它变成"会说话的图表和结论"，却不想从零学 Python 语法。你将学会：安装 Claude Code、用 uv 建立可复现的 Python 项目、让 AI 自动推断数据结构、生成清洗脚本与可视化图表、输出一份可交付的分析报告。整个过程你几乎不写一行代码，而是用自然语言"指挥"一个项目感知（project-aware）的编码智能体完成。

## 前置条件

- 一台 macOS / Windows / Linux 电脑，能打开终端
- **Node.js 18+**（Claude Code 的运行环境，必装）
- **Python 3.10+**（数据分析的执行环境）
- 一个 **Claude 账号**：Pro 订阅即可零额外成本使用；或用 API Key 按量付费
- 一份你自己的数据（CSV 最简单），没有也行，文末实战案例会自带示例数据

> 与传统"装环境就劝退"的教程不同，本文把"环境"这件事也交给 Claude Code 来处理——这正是 agentic 编程的核心红利。

---

## 步骤一：安装 Claude Code

Claude Code 是一个跑在终端里的命令行工具（CLI）。安装它之前，先确认 Node.js 已就位。

**安装 Node.js（任选其一）：**

```bash
# macOS（Homebrew）
brew install node

# Windows / Linux：到 nodejs.org 下载 LTS 安装包
# 或用 nvm（推荐，便于多版本切换）
nvm install --lts
```

**安装 Claude Code 本体：**

```bash
npm install -g @anthropic-ai/claude-code
```

**预期结果**：终端里输入 `claude --version` 能打印出版本号（当前为 2.x 系列），说明全局命令已就绪。

**常见问题**：

| 现象 | 原因与解决 |
|---|---|
| `command not found: claude` | npm 全局目录不在 PATH 中。运行 `npm config get prefix`，把 `/bin` 子目录加入 PATH |
| 权限错误 EACCES | 不要用 `sudo`。改用 nvm 管理 Node，或执行 `npm config set prefix ~/.npm-global` 后把该路径加入 PATH |
| 公司网络拉不动 npm | 设置镜像：`npm config set registry https://registry.npmmirror.com` |

---

## 步骤二：用 uv 建立 Python 项目

数据分析项目的第一个坑，永远是依赖管理。这里推荐 **uv**——一个用 Rust 写的极速包管理器，比传统 pip+venv 快十倍以上，且能彻底避免"我电脑上能跑、你电脑上报错"的经典灾难。

**安装 uv：**

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**初始化项目骨架：**

```bash
uv init sales-analysis
cd sales-analysis
```

**预装数据分析三件套：**

```bash
uv add pandas numpy matplotlib
```

> **关键技巧**：建议在对话里明确告诉 Claude Code"用 `uv add <包>` 来装包，不要直接改 pyproject.toml"。这样它每次都会拉取最新稳定版，而不是凭训练记忆写死一个可能过时的版本号。

**预期结果**：项目目录下生成 `pyproject.toml`、`.python-version`、`uv.lock` 和 `main.py`，依赖被锁定，可复现。

---

## 步骤三：建立目录结构 + 让 Claude 进场

一个好习惯：**在召唤 Claude 之前，先把项目结构搭好**。Claude Code 会"看见"这个结构，并自然地把产物写到对应位置，而不是把图表乱丢在根目录。

**手动建好目录：**

```bash
mkdir -p src data figures tables
```

结构含义：

```
sales-analysis/
├── src/        # 源代码（清洗、分析脚本）
├── data/       # 原始数据与中间数据
├── figures/    # 生成的图表 PNG
├── tables/     # 汇总表格 CSV
└── pyproject.toml
```

**启动 Claude Code：**

```bash
claude
```

首次启动会要求你**登录**：Pro/Max 订阅用户走浏览器 OAuth；按量付费用户粘贴 API Key。Pro 订阅默认用 Sonnet 模型，对日常数据分析绰绰有余；Max 用户可用 `/model` 切换更强模型。

**生成项目记忆文件：**

```
/init
```

执行 `/init` 后，Claude 会扫描项目结构和你写过的说明，自动生成一份 `CLAUDE.md`。**这份文件会被注入到你之后的每一条指令里**，相当于给 AI 一份"项目说明书"。务必打开它审查一遍，确保约定正确。

一个适合数据分析项目的 `CLAUDE.md` 范例：

```markdown
# 项目说明
本项目对 data/ 目录下的销售数据进行清洗与可视化分析。

# 约定
- 所有脚本放在 src/ 下，可独立运行
- 图表保存到 figures/，表格保存到 tables/
- 使用 uv 管理依赖：装包用 `uv add <pkg>`，运行用 `uv run python src/xxx.py`
- 数据源路径从 .env 的 DATA_PATH 读取，不要硬编码
- 图表风格：简洁、中文标签、300 DPI
```

---

## 步骤四：让数据"被看见"

数据分析项目最关键的一步，是**确保 Claude Code 知道数据在哪、长什么样**。有三种做法，按数据规模递进：

**做法 A（小数据）**：直接把 CSV 拖进 `data/` 目录。Claude 会自动看到文件名和内容，能直接读取分析。最省事。

**做法 B（外部数据）**：数据在项目之外（如共享网盘），Claude 默认看不到。两种方案：
- 在 `CLAUDE.md` 里写明绝对路径
- 更干净的方式：用 `.env` + 环境变量

```bash
# 创建 .env（记得加进 .gitignore，别提交！）
echo 'DATA_PATH=/Users/yourname/Dropbox/finance-data' > .env
```

代码里用 `python-dotenv` 读取：

```python
import os
from dotenv import load_dotenv
load_dotenv()
data_path = os.getenv("DATA_PATH")
```

**做法 C（在线数据）**：数据在 API 或学术仓库里，直接让 Claude 写抓取代码，下载到 `data/`，保证可复现。

---

## 步骤五：让 Claude 先"读懂数据"

**这是数据分析的黄金第一步，却被多数新手跳过。** 不要一上来就让它画图，先让它推断数据结构（schema），并写成 Markdown 供你校对。

在 Claude Code 里输入：

> 请读取 `data/` 下的 CSV 前 50 行，推断每一列的字段名、数据类型、是否含缺失值、可能的业务含义，把结论写到 `tables/schema.md`，让我确认后再分析。

**预期结果**：Claude 会写一个临时探查脚本，调用 pandas 的 `df.info()`、`df.head()`、`df.describe()`，并把列含义整理成表格。这一步把"AI 对数据的理解"显式化，避免后续基于错误假设生成一堆废代码。

---

## 步骤六：清洗数据

确认 schema 后，让它写清洗脚本。真实数据几乎都有"脏"：重复行、日期格式混乱、金额带货币符号、空值。

> 请写 `src/clean.py`，完成以下清洗：删除完全重复行；把 `订单日期` 解析为标准 datetime；把 `销售额` 中的 `$` 和逗号去掉转为浮点数；`客户地区` 缺失值填"未知"；清洗后保存到 `data/sales_clean.csv`。运行它并把执行结果告诉我。

Claude 会写出类似下面的代码并**自动执行**，遇到报错会自己读报错信息并修复（这就是 agentic 与普通补全的本质区别）：

```python
import pandas as pd

df = pd.read_csv("data/sales_raw.csv")

# 去重
df = df.drop_duplicates()

# 日期解析
df["订单日期"] = pd.to_datetime(df["订单日期"], errors="coerce")

# 金额清洗
df["销售额"] = (
    df["销售额"].astype(str)
    .str.replace(r"[\$,]", "", regex=True)
    .astype(float)
)

# 缺失填充
df["客户地区"] = df["客户地区"].fillna("未知")

df.to_csv("data/sales_clean.csv", index=False)
print(f"清洗完成，共 {len(df)} 行")
```

---

## 步骤七：生成可视化

清洗干净后，画图就是一句话：

> 用清洗后的数据，画三张图保存到 figures/：(1) 按月的销售额折线图；(2) 各地区销售额柱状图；(3) 销售额分布直方图。中文标签，配色简洁，300 DPI。

Claude 会用 matplotlib（或 seaborn）生成脚本并运行。产物是三张 PNG，路径在 `figures/` 下。

---

## 步骤八：产出可交付报告

最后让它把结论沉淀成文字：

> 基于 figures/ 的图表，写一份 `REPORT.md`：用 3-5 条要点总结销售趋势、最强/最弱地区、整体规模，并在每条要点后用 Markdown 引用对应图表路径。

这份 `REPORT.md` 配合图表，就是你交付给老板/同事的成品——全部由你用自然语言指挥完成。

---

## 实战案例：销售数据全流程（可运行）

下面是一个完整、自包含的示例，从无到有跑通。你可以逐段复制到终端执行。

**1. 建项目并造一份示例数据（约 120 行）：**

```bash
uv init sales-demo && cd sales-demo
uv add pandas matplotlib python-dotenv
mkdir -p src data figures tables
```

让 Claude 生成示例数据，或自己粘一段：

```python
# src/make_data.py
import pandas as pd
import numpy as np

np.random.seed(42)
regions = ["华东", "华南", "华北", "西南", "未知"]
dates = pd.date_range("2025-01-01", "2025-12-31", freq="D")
rows = []
for d in dates:
    for _ in range(np.random.randint(1, 4)):
        rows.append({
            "订单日期": d.strftime("%Y/%m/%d"),
            "客户地区": np.random.choice(regions, p=[.3,.25,.2,.2,.05]),
            "销售额": f"${np.random.lognormal(7, .6):,.2f}",
        })
pd.DataFrame(rows).to_csv("data/sales_raw.csv", index=False)
print("已生成 data/sales_raw.csv")
```

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

**2. 启动 Claude Code 并一次性下达任务：**

```bash
claude
```

在交互框输入这段"指挥词"：

> 这是一个销售数据分析项目。请按以下步骤执行：
> 1. 读取 data/sales_raw.csv，把 schema 写到 tables/schema.md。
> 2. 写 src/clean.py：解析日期、清洗金额、填充缺失，输出 data/sales_clean.csv。
> 3. 写 src/analyze.py：按月销售额折线图、各地区柱状图、分布直方图，存 figures/。
> 4. 写 REPORT.md，3 条要点 + 图表引用。
> 用 uv run 执行脚本，报错自己修，全做完把 figures 里的图和 REPORT.md 内容给我看。

**3. 预期产出：**

```
sales-demo/
├── data/sales_clean.csv        # 清洗后 ~300 行
├── figures/monthly_trend.png   # 月度折线
├── figures/region_bar.png      # 地区柱状
├── figures/sales_hist.png      # 分布直方
├── tables/schema.md            # 字段说明
└── REPORT.md                   # 结论报告
```

`REPORT.md` 会形如：

```markdown
# 销售数据分析报告
- 全年销售额呈上升趋势，Q4 为旺季（见 figures/monthly_trend.png）
- 华东为最强区域，占约 30%；"未知"地区提示数据录入需治理（见 figures/region_bar.png）
- 销售额呈右偏对数正态分布，存在少量大额订单拉高均值（见 figures/sales_hist.png）
```

整个过程你**没有手写任何 pandas 或 matplotlib 代码**，只做了需求描述与结果校对——这就是 agentic CLI 的价值。

---

## 工作流程图

```mermaid
flowchart TD
    A[安装 Node + Claude Code] --> B[uv init 建项目<br/>预装 pandas/matplotlib]
    B --> C[建目录结构<br/>src data figures tables]
    C --> D[claude 启动 + /init 生成 CLAUDE.md]
    D --> E[准备数据<br/>data 目录 / .env / 在线抓取]
    E --> F[让 Claude 推断 schema<br/>写 tables/schema.md 供校对]
    F --> G[写清洗脚本 clean.py<br/>Claude 自动运行并修错]
    G --> H[生成可视化<br/>figures/*.png]
    H --> I[产出 REPORT.md<br/>要点 + 图表引用]
    I --> J{满意?}
    J -->|否| K[自然语言追加修改<br/>如换个配色/补个维度]
    K --> H
    J -->|是| L[交付]
```

---

## 常见问题与排查

| 问题 | 解决思路 |
|---|---|
| Claude 生成的图中文乱码（方块） | matplotlib 默认字体不含中文。让它设置 `plt.rcParams['font.sans-serif']=['Arial Unicode MS']`（Mac）或 `SimHei`（Win） |
| Claude 改不动包、报 ModuleNotFound | 强制要求用 `uv run python xxx.py` 而非裸 `python`，确保用项目虚拟环境 |
| 报错后 Claude 卡住不修 | 直接说"读上面的报错，分析原因并修改脚本重跑"，或贴报错文本给它 |
| 大数据（几十万行）跑不动 | 让它改用 `chunksize` 分块读取，或加 `dtype` 指定列类型降内存 |
| 重复分析后产物混乱 | 在 `CLAUDE.md` 固定输出目录约定，禁止往根目录写文件 |

---

## 延伸阅读

- **Anthropic 官方 Claude Code 文档**：CLI 标志位、`/init`、`/model`、权限模式等权威说明，是查命令的第一手来源。
- **uv 官方文档**（astral.sh/uv）：理解 `uv.lock`、虚拟环境与可复现构建。
- **pandas 官方 Cookbook**：当 Claude 给的方案你拿不准时，对照官方用法做二次校验，防止"看起来对其实有坑"。
- 进阶方向：用 MCP（Model Context Protocol）给 Claude Code 接入数据库、在线 API；用 Hooks 给数据项目加"改动前先备份 data/"的自动护栏。

---

## 训练营适用性评估

- **数据分析启蒙营（面向非程序员）**：高度契合。2–3 小时可带零基础学员从装环境走到出报告，成就感强、门槛低。建议作为开营第一课。
- **运营/财务 AI 提效营**：高度契合。学员自带真实工作表格，当堂完成自己业务的可视化，落地感强。教学时长 3 小时（含数据清洗常见坑）。
- **程序员入门营**：契合度中等。开发者更关心代码质量与工程化，本文可作为"先体验 agentic 工作流"的破冰，随后转入更工程化的主题。
- **科研/论文营**：契合度高。科研人员常被数据处理卡住，本文方法直接复用于实验数据分析，建议加一节"统计检验（scipy/statsmodels）"延伸。

总体定位：**最适合作为零基础学员的"第一份有产出的项目"**，避免抽象语法学习，让 AI 替学员扛起实现细节，学员专注业务洞察与结果验证。

---

## 参考来源

1. [Claude Code for Data Analysis – Vincent Codes Finance](https://vincent.codes.finance/posts/claude-code-data-analysis/) — 系统讲解 Claude Code 数据分析工作流：uv 初始化、目录约定、CLAUDE.md、数据可达性与 MCP 扩展
2. [Data analysis with Claude Code: 500,000 rows without writing code – VelvetShark](https://velvetshark.com/data-analysis-with-claude-code) — 真实 50 万行 Excel 从清洗到报告的端到端实操，含可复制提示词与报错自愈过程
3. [anthropics/claude-code – GitHub](https://github.com/anthropics/claude-code) — Claude Code 官方仓库，安装命令、CLI 标志位与最新特性权威来源
4. [Claude Code Cheat Sheet – ComputingForGeeks](https://computingforgeeks.com/claude-code-cheat-sheet/) — 2.x 版本速查表：模型选择、斜杠命令、CLI 参数一览
5. [zebbern/claude-code-guide – GitHub](https://github.com/zebbern/claude-code-guide) — 从入门到进阶的命令、工作流与技巧合集，适合作为目录式参考资料

> [!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)