<!-- title: Claude Code零基础：读透并改造首个开源项目 -->

## 概述

本教程面向**完全零基础**的开发者，教你用 Claude Code 做一件比"Hello World"更接近真实工作场景的事：**把一个你不认识的开源项目读懂，并成功改一行代码、跑通测试**。学完后你将掌握安装认证、`/init` 项目初始化、架构提问、代码追踪、小步改造与验证的完整闭环，理解 AI 编程助手的真实价值边界。适用人群：会用命令行、写过一点代码、但从未用过 AI 编程工具的新手。

## 前置条件

- **操作系统**：macOS、Linux 或 Windows（Windows 推荐 WSL2）
- **基础技能**：会打开终端、能用 `cd`/`ls`/`git` 三条命令即可
- **Node.js 18+**：仅在走 npm 安装路径时需要（原生安装路径不需要）
- **一个 GitHub 账号**：用于克隆开源项目
- **心态准备**：把 Claude Code 当成一个**会读代码的同事**，而不是"自动写完整个项目"的魔法

---

## 为什么零基础的第一课不是"造轮子"，而是"读项目"

市面上 90% 的 Claude Code 入门教程都在教"从零创建一个新项目"。这有一个隐藏的坑：**新项目里没有"已有代码"需要理解，AI 的核心能力——读懂上下文——根本没被触发**。

而你真正会遇到的工作场景，恰恰相反：

- 入职第一天，前辈丢给你一个 5 万行的仓库说"先熟悉熟悉"
- 想给某个开源项目提一个 PR，却看不懂它的目录结构
- 接手一个离职同事留下的"祖传代码"

这些场景的共同点是：**代码已经存在，你的任务是先理解，再动手**。所以本教程的反直觉选择是——第一课就用 Claude Code 去啃一个**别人写好的**项目。这才是它真正不可替代的能力。

---

## 第一步：安装 Claude Code

Claude Code 在 2026 年提供两条安装路径，任选其一。

### 路径 A：原生安装（推荐，无需 Node）

macOS / Linux / WSL：

```bash
curl -fsSL https://claude.ai/install.sh | bash
```

Windows（PowerShell）：

```powershell
irm https://claude.ai/install.ps1 | iex
```

原生安装会把二进制装到 `~/.local/bin/`（或 Windows 的用户目录），并自动配置 `PATH`。

### 路径 B：npm 全局安装（适合已有 Node 环境）

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

### 验证安装

```bash
claude --version
```

能看到版本号（如 `2.x.x`）即安装成功。

**常见问题与解决：**

| 问题 | 原因 | 解决 |
|------|------|------|
| `command not found: claude` | PATH 未生效 | 重开终端；或手动 `export PATH="$HOME/.local/bin:$PATH"` |
| npm 报权限错误 `EACCES` | 全局目录无写权限 | 改用原生安装路径 A，或配置 npm prefix 到用户目录 |
| 公司网络下载失败 | 防火墙拦截 | 配置 `HTTPS_PROXY` 代理环境变量后重试 |

---

## 第二步：认证登录

第一次运行 `claude`，会进入交互式引导：

```bash
claude
```

你会看到两个登录选项：

1. **Claude 账号登录**（claude.ai 订阅用户）——浏览器自动打开，确认授权即可。Pro/Max 订阅会消耗你的对话额度。
2. **API Key 登录**（按 token 计费）——去 [console.anthropic.com](https://console.anthropic.com) 创建 Key，然后：

```bash
export ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
```

新手建议先用**订阅账号**，因为按 token 计费在你不熟悉时容易超支。

登录成功后，终端底部会出现输入框，光标闪烁，说明 Claude Code 已就绪。

---

## 第三步：找一个"对新手友好"的开源项目来读

不要一上来就挑战 Kubernetes 这种百万行仓库——上下文会被撑爆，你会怀疑人生。新手练手项目的三个标准：

- **代码量小**（500~5000 行）
- **有 README 和测试**
- **你大致知道它是干嘛的**

推荐练手项目（任选其一）：

- **Python**：一个 Flask/ FastAPI 的小型 REST API（如一个 todo list 后端）
- **Node.js**：一个 Express 写的短链接服务
- **通用**：`cowsay`、`figlet` 这类单一功能 CLI 工具

下面用一个**极简的 Express Todo API**作为贯穿全篇的示例。先克隆：

```bash
git clone https://github.com/example/express-todo-api.git
cd express-todo-api
```

> 提示：你也可以换成任意本地已有的小项目，只要 `cd` 进它的根目录即可，后续步骤完全通用。

---

## 第四步：`/init` —— 让 AI 先把项目"读薄"

进入项目根目录后，启动 Claude Code：

```bash
claude
```

然后在输入框敲第一条命令：

```
/init
```

**发生了什么？** Claude Code 会扫描整个目录结构、读取关键配置文件（`package.json`/`requirements.txt`、`tsconfig.json`、`README.md`、测试目录），然后在项目根目录生成一个 **`CLAUDE.md`** 文件。

`CLAUDE.md` 是 Claude Code 的"项目记忆"，内容大致如下：

```markdown
# CLAUDE.md

本项目是一个基于 Express 的 Todo REST API。

## 开发命令
- 安装依赖：`npm install`
- 启动开发服务器：`npm run dev`
- 运行测试：`npm test`
- 代码检查：`npm run lint`

## 架构概览
- 入口：`src/app.js`
- 路由层：`src/routes/todos.js`
- 数据层：`src/store/memory.js`（内存存储）
- 测试：`test/todos.test.js`（使用 Jest）

## 约定
- 所有路由返回 JSON
- 错误统一走 src/middleware/errorHandler.js
```

**为什么这一步如此关键？**

没有 `CLAUDE.md`，Claude Code 每次都要重新扫一遍目录，又慢又贵；有了它，后续每次对话都带着这份"项目说明书"，**回答准确度大幅上升，token 消耗显著下降**。这是从"一次性问答玩具"升级为"长期项目助手"的分水岭。

**常见问题：**

- **项目太大，`/init` 很慢** → 先让它跑完；超大仓库可以手动在 `CLAUDE.md` 里写明"忽略 `node_modules`、`dist`、`vendor` 目录"。
- **生成的 `CLAUDE.md` 不准** → 它是草稿，你应该手动修正。这是正常的协作过程，不是 bug。

---

## 第五步：提问式架构理解

`/init` 之后，开始像问同事一样提问。新手最该问的不是"这段代码啥意思"，而是**结构性问题**——这类问题的答案能一次性建立全局认知。

在输入框依次问：

**提问 1（全局）：**
```
用三段话概括这个项目的整体架构：它由哪几层组成？数据从请求进来到响应出去，经过哪些环节？
```

**预期输出：** Claude Code 会读取 `src/app.js`、路由文件、中间件，给你一个分层描述：路由层 → 控制器 → 存储层 → 响应封装，并指出关键文件路径。

**提问 2（入口定位）：**
```
应用启动的入口在哪一行？它注册了哪些中间件、按什么顺序？
```

**提问 3（依赖与约束）：**
```
这个项目用了哪些关键依赖？测试框架是什么？有没有数据库？数据存在哪？
```

这三个问题问完，你对项目的认知，应该比单纯读 README 深一个量级。

> 技巧：用 `@` 引用文件能让提问更精准，例如 `@src/app.js 里 app.use 的顺序有什么讲究？`。Claude Code 会优先聚焦该文件。

---

## 第六步：追踪一条真实请求的代码流

理解架构之后，下一步是"顺着一条真实请求走一遍"。这是读代码最有效的方法——**不要横着读（一个个文件看），要纵着读（一个功能贯穿多层）**。

**提问：**
```
当我用 curl 发起 GET /api/todos 这个请求时，从 HTTP 进入到返回 JSON，代码依次执行了哪些文件、哪些函数？请按执行顺序列出调用链。
```

**预期输出**（示意）：

```
1. src/app.js: app.listen(3000) — Express 服务器监听端口
2. src/app.js: 日志中间件 logRequest 记录请求
3. src/app.js: JSON 解析中间件 express.json()
4. src/routes/todos.js: router.get('/', todosController.list)
5. src/controllers/todosController.js: list() 调用 store
6. src/store/memory.js: getAll() 返回数组
7. src/app.js: errorHandler（本次无错误，不触发）
8. 响应: res.json(todos) 返回给客户端
```

这种"调用链"答案，比任何文档都直观。你可以继续追问任意一环：

```
src/store/memory.js 里的数据是存在哪的？服务重启会丢失吗？
```

Claude Code 会告诉你数据存在模块级变量里，进程重启即丢失——这正是它叫 `memory.js` 的原因。

---

## 第七步：动手改一行，并跑通测试

读到这里你已经理解了项目。现在做一件有成就感的事：**加一个真实功能，并验证它生效**。

**需求：** 给每个 todo 的响应增加一个 `createdAt` 字段，返回 ISO 格式时间戳。

**提问：**
```
我想让 GET /api/todos 返回的每个 todo 对象都带上 createdAt 字段（ISO 时间字符串）。
请先告诉我要改哪个文件、怎么改，再帮我改。
```

注意这个提问的两个要点：**先说方案，再动手**。这能让你保持对修改的掌控，而不是被动接受一大段 diff。

**预期交互：**
1. Claude Code 先回答："需要修改 `src/store/memory.js`，在创建 todo 时写入 `createdAt: new Date().toISOString()`。这是只读改动，不影响已有数据结构。"
2. 它请求权限修改该文件——**此时终端会弹出确认提示，按 `y` 同意**（这是安全机制，务必看清要改什么）。
3. 修改完成。

**接着让它跑测试：**
```
运行测试，确认改动没有破坏现有功能。
```

Claude Code 会执行 `npm test`，并告诉你测试结果。如果通过，说明你的第一个开源项目改造**闭环成功**——从看不懂，到读懂，到改对，到验证。

**常见问题：**

| 现象 | 原因 | 处理 |
|------|------|------|
| 改完测试报错 | 改动影响了断言 | 让 Claude Code "分析测试失败原因并修复"，它会读测试代码 |
| Claude Code 拒绝修改 | 权限模式为只读 | 启动时确认未用 `--read-only`；或在确认提示选同意 |
| 改动涉及多个文件它只改一个 | 需求描述太笼统 | 明确说"列出所有要改的文件并逐一修改" |

---

## 实战案例：从零读透并改造一个 Express Todo API（完整复盘）

把前面七步串成一个完整可复现的流程，作为你的"第一次实战"模板。

### 0. 准备

```bash
git clone https://github.com/example/express-todo-api.git
cd express-todo-api
npm install
claude
```

### 1. 生成项目记忆

```
/init
```

检查生成的 `CLAUDE.md`，手动补一句约定："所有新增字段需同步更新 `test/todos.test.js`。"

### 2. 建立全局认知（3 个问题）

```
- 三段话概括架构
- 入口在哪、注册了哪些中间件
- 依赖、测试框架、数据存储位置
```

### 3. 追踪请求流（1 个问题）

```
- GET /api/todos 的完整调用链
```

### 4. 小步改造（先方案后动手）

```
- 给每个 todo 加 createdAt 字段，先说方案再改
```

### 5. 验证

```
- 运行 npm test
- 用 curl 启动服务并发一个请求，看响应里有没有 createdAt
```

启动服务并验证：

```bash
# 在另一个终端
npm run dev
curl http://localhost:3000/api/todos
```

预期响应里出现：

```json
[
  { "id": 1, "title": "学习 Claude Code", "createdAt": "2026-06-14T08:30:00.000Z" }
]
```

看到 `createdAt`，闭环完成。整个过程，**你只写了提问，没有手动改一行代码**——但你完全知道改了什么、为什么改、改对没有。这才是 AI 编程助手正确的打开方式。

---

## 工作流程图

```mermaid
flowchart TD
    A[安装 Claude Code] --> B[认证登录]
    B --> C[克隆/进入开源项目]
    C --> D[/init 生成 CLAUDE.md 项目记忆/]
    D --> E[手动校准 CLAUDE.md]
    E --> F[结构性提问: 架构/入口/依赖]
    F --> G[追踪一条请求的调用链]
    G --> H{是否理解清楚?}
    H -- 否 --> F
    H -- 是 --> I[提出小改造需求: 先方案后动手]
    I --> J[确认权限, 应用修改]
    J --> K[运行测试验证]
    K --> L{测试通过?}
    L -- 否 --> M[让 AI 分析失败并修复]
    M --> K
    L -- 是 --> N[✅ 读透并改造成功]
```

---

## 新手最常踩的 5 个坑

1. **上来就让它"重构整个项目"** —— 必翻车。AI 在没有充分上下文时做大改动，错误率高。**铁律：先理解，再小步改，每步验证。**
2. **不读 `/init` 生成的 `CLAUDE.md` 就开始问** —— 它是协作契约，错的契约会带偏所有后续回答。
3. **忽视权限确认弹窗直接按回车** —— 安全网。养成"看清要改哪个文件"的习惯，避免误删。
4. **大项目一直聊不压缩上下文** —— 对话越长越贵越慢。读大型仓库时，阶段性用 `/compact` 压缩历史，或 `/clear` 重开。
5. **把 AI 当搜索引擎用** —— 问"Express 怎么写路由"会得到泛泛通用答案（这类该查文档）；问"**本项目**的路由在哪个文件、怎么注册的"才能榨出价值。**永远把问题锚定到你的具体代码上。**

---

## 进阶信号：什么时候你该升级到下一篇

当你能稳定完成上述闭环，并且出现以下信号时，说明该进入下一阶段：

- 你开始需要**让 AI 记住跨会话的项目约定** → 学习记忆体系（`CLAUDE.md` 分层、记忆文件）
- 你想**让 AI 自动执行某些动作**（如提交前自动跑测试）→ 学习 Hooks
- 你需要**批量处理多个文件/多个任务** → 学习无头模式 `-p` 与子 Agent 编排
- 你想**封装自己的提示词复用** → 学习自定义命令 `/commands`

这些正是后续教程的主题，按需推进即可。

---

## 延伸阅读

- **官方文档**：[docs.anthropic.com/en/docs/claude-code](https://docs.anthropic.com/en/docs/claude-code) —— 命令参考、配置项、最佳实践的一手来源
- **官方快速上手**：[Claude Code Quickstart](https://docs.anthropic.com/en/docs/claude-code/quickstart) —— 安装与首跑的权威步骤
- **老金 10 万字中文教程**：[Claude-Code-Guide-Zh](https://zhuanlan.zhihu.com/p/2005266124917477580) —— 10 个完整教程、70+ 代码示例、120 个 FAQ，中文社区最全开源资料
- **GitHub 仓库**：[anthropics/claude-code](https://github.com/anthropics/claude-code) —— Issue、示例与社区讨论

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合的训练营类型** | 零基础转码营、前端/后端新手营、开源贡献入门营、企业新人 onboarding 训练 |
| **建议教学时长** | 1 个半天（约 3~4 小时）：1 小时讲解 + 2~3 小时动手完成实战案例 |
| **前置门槛** | 低。会用命令行即可，不要求精通某门语言 |
| **考核标准** | 学员能独立完成"克隆项目 → `/init` → 提问理解 → 改一行 → 跑通测试"全流程，并口述调用链 |
| **延伸方向** | 完成本篇后衔接 Skills 开发、Hooks 自动化、无头模式批量任务三篇进阶教程 |

---

## 参考来源

1. [Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) — Anthropic 官方安装、命令、配置与最佳实践权威来源
2. [Claude Code解惑：零基础入门如何让 Claude Code 帮你读懂复杂的开源代码](https://blog.csdn.net/l35633/article/details/157400516) — 专门针对"读开源项目"场景的中文实操讲解
3. [Claude Code 项目初始化 - 菜鸟教程](https://www.runoob.com/claude-code/claude-code-init.html) — `/init` 命令与 `CLAUDE.md` 生成的中文说明
4. [Claude Code 基础使用完整指南：从启动到精通](https://www.aiking.dev/blog/claude-code-%E5%9F%BA%E7%A1%80%E4%BD%BF%E7%94%A8%E5%AE%8C%E6%95%B4%E6%8C%87%E5%8D%97-%E4%BB%8E%E5%90%AF%E5%8A%A8%E5%88%B0%E7%B2%BE%E9%80%9A%E7%9A%84%E5%AE%9E%E6%88%98%E6%89%8B%E5%86%8C) — 围绕 `CLAUDE.md` 与会话管理的系统性实战手册
5. [mali9527/claude-code-full-guide-for-beginners](https://github.com/mali9527/claude-code-full-guide-for-beginners) — 17 万字、27 章、44 张思维导图的零基础中文开源入门书

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