<!-- title: 零基础读透一个陌生代码库 -->

# 用 Claude Code 零基础读透一个陌生代码库

## 概述

本教程面向刚装好 Claude Code 却不知道"第一步该干什么"的新手。不写新代码、不碰配置文件，而是把 Claude Code 当成一个会读代码、会画图、会回答提问的资深同事，带你从零读懂一个完全陌生的 GitHub 项目：从克隆仓库、生成项目说明书、画出架构图，到安全地做一处小修改并自验证。学完后你能独立接手任何陌生代码库。

## 前置条件

- 已安装 Claude Code（任意一种登录方式均可：Claude 订阅、Anthropic Console API、SSO）
- 能在终端执行 `git clone` 与 `claude` 命令
- 装有 Node.js 18+ 或已用原生二进制安装（`claude install stable`）
- 手头有一个想读懂的项目（没有的话，文末实战案例会给你一个）

---

## 第一步：用最简命令启动，确认环境就绪

很多新手卡在"装完之后该怎么开始"。Claude Code 的入口极简：在任意目录敲 `claude` 即可进入交互式会话。先做一个健康检查。

**操作说明：**

```bash
# 1. 确认已登录、有额度
claude auth status

# 2. （可选）查看版本与更新
claude update

# 3. 进入一个空目录启动会话，验证基本可用
cd ~/projects
claude
```

**预期结果：**

- `claude auth status` 返回 JSON，`isLoggedIn: true` 表示登录正常，并显示剩余额度。
- `claude` 进入后出现一个输入框光标，左下角通常显示模型名与权限模式（默认 `default`）。
- 在输入框敲 `hello`，Claude 会回一句问候，说明模型连通。

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

| 现象 | 原因 | 解决 |
|------|------|------|
| `command not found: claude` | 未装或 PATH 未生效 | 重新执行 `claude install stable`；或重启终端让 PATH 生效 |
| `Weekly/Monthly Limit Exhausted` | 订阅额度用尽 | 换 `claude auth login --console` 切到 Console 按量计费 |
| 卡在登录跳转 | 浏览器没弹 | 复制终端里的授权 URL 手动粘贴到浏览器 |

> 关键认知：Claude Code 不是聊天框，而是**会主动读你文件、跑你命令**的代理。它的"记忆"来自当前目录与对话历史——所以**一定要 `cd` 进项目根目录再启动**，否则它看不到你的代码。

---

## 第二步：克隆一个陌生项目，让它进入你的工作目录

读懂代码的前提是让代码出现在 Claude Code 的"视野"里。

**操作说明：**

```bash
# 以一个结构清晰、规模适中的真实项目为例
git clone https://github.com/anthropics/anthropic-sdk-python
cd anthropic-sdk-python

# 在项目根目录启动 Claude Code
claude
```

**预期结果：** Claude Code 启动时会扫描当前目录，识别出这是 Python 项目（看到 `pyproject.toml`、`src/` 等），后续提问无需你重复说明语言和结构。

**常见问题：**

- 项目太大、文件极多：先别急着问复杂问题，先用下一步的 `/init` 让它建立索引式记忆。
- 项目依赖私有子模块克隆失败：暂时跳过子模块，先把主体读懂。

---

## 第三步：用 `/init` 一键生成项目说明书

这是新手最该学的第一个斜杠命令。`/init` 会让 Claude 主动浏览目录、读关键文件，然后写一份 `CLAUDE.md`——相当于给项目建一份"出生证明"，里面记录技术栈、目录结构、构建/测试命令、约定。

**操作说明（在交互会话内输入）：**

```
/init
```

**预期结果：**

Claude 会先读 `README.md`、`pyproject.toml`、目录树等，然后生成 `CLAUDE.md`，内容大致包含：

```markdown
# CLAUDE.md（自动生成，示意）
- 语言：Python 3.8+
- 包管理：uv / pip + pyproject.toml
- 关键目录：src/anthropic（核心源码）、tests/（测试）
- 常用命令：
  - 跑测试：pytest
  - 构建包：python -m build
- 约定：新增公开 API 需在 src/anthropic/__init__.py 导出
```

**为什么这一步最关键：** 官方最佳实践把"写一份有效的 CLAUDE.md"列为重中之重——它是后续每次对话都会自动加载的项目记忆，能显著降低上下文消耗、减少 Claude 的猜测。

**常见问题：**

- `/init` 生成的说明不准：直接在对话里纠正它（"测试命令其实是 `make test`"），让它更新 `CLAUDE.md`。
- 不想让它写文件：加一句"先别写文件，口头总结即可"。

---

## 第四步：先探索、再计划、最后才动手

这是 Anthropic 官方总结的核心心法：**Explore first, then plan, then code**。读懂陌生代码库时，把 90% 的精力放在前两步。

新手常犯的错是直接丢一个模糊问题（"这项目怎么用？"）。更好的做法是给 Claude **具体、可验证的提问**。

**操作说明（按顺序提问）：**

```
1) 这个项目的入口在哪？从命令行到核心逻辑的调用链是怎样的？
2) 列出最核心的 5 个文件，每个用一句话说明职责。
3) 画出主要模块之间的依赖关系图。
```

**预期结果：**

- Claude 会调用只读的 **Explore 子代理**（subagent）去大量翻文件，但只把"结论"带回来，不会把整个文件内容塞满主对话窗口——这正是为了保护宝贵的上下文。
- 你会得到一份带 `file_path:line_number` 引用的清单，引用可直接点击跳转。
- 它会用 Mermaid 给出依赖关系图。

**常见问题：**

- 回答太长、看不到重点：追加"用表格总结，每行≤20字"。
- Claude 说"需要更多信息"：用 `@文件名` 显式喂关键文件，如 `结合 @src/anthropic/client.py 解释重试逻辑`。
- 答非所问：多半是上下文里噪声太多，用 `/compact` 压缩历史，或 `/clear` 重开干净会话。

> 子代理小知识：Explore 是只读搜索代理，适合"扫很多文件、只要结论"的场景。它读片段而非整文件，所以擅长定位代码，不擅长审计细节。复杂追问可以再让主代理读指定文件。

---

## 第五步：盯着上下文，别让它"失忆"

Claude Code 最该盯的资源不是时间，而是**上下文窗口（context window）**。一次深入探索可能就消耗数万 token；窗口越满，Claude 越容易"忘记"早期指令、出错越多。

**操作说明：**

- 随时输入 `/context` 查看当前上下文占用比例。
- 用自定义状态栏（statusline）把占用百分比常驻显示（参考 `/config`）。
- 占用超过 ~70% 时，主动 `/compact` 压缩历史；任务切换时直接 `/clear`。

**预期结果：** 状态栏实时显示如 `ctx: 62%`，你能在它"变笨"之前主动干预。

**常见问题：**

- `/compact` 后感觉丢信息：压缩前先用一句话让它"把当前结论写进 CLAUDE.md"，重要结论落地到文件而非依赖记忆。
- 想回到某个早期状态：用检查点（checkpoint）/ 回放功能回退，或 `claude -r "session名"` 恢复历史会话。

---

## 第六步：给 Claude 一个可自验证的任务，安全地做一处修改

读懂之后，最稳的"第一次动手"是**小而可验证**的改动，比如补一段文档、修一个拼写、加一个测试用例。关键是给 Claude 一个"能跑、能给 pass/fail"的检查方式——这是"你能走开"和"你得盯着"的分水岭。

**操作说明：**

```
请为 src/anthropic/_client.py 里的重试函数补一段中文 docstring。
要求：
1) 说明三个参数的含义与默认值
2) 改完后运行 pytest -k retry，把结果贴给我
3) 不要改动函数逻辑
```

**预期结果：** Claude 改完会自己跑测试、读输出、必要时迭代，最后给你"3 passed"之类的结论。

**新手护栏（非常重要）：**

- 第一次动手建议用 **权限模式** 保护：`claude --permission-mode plan`（只规划不动手）或 `acceptEdits`（接受编辑但不自动跑危险命令）。默认 `default` 模式每次危险操作都会问你，新手保持默认最安全。
- 涉及删除、`git push`、网络请求时，Claude 会请求放行——拿不准就拒绝。

**常见问题：**

- Claude 说"测试通过"但你不确定真假：要求它把命令的**完整输出**贴出来，而不是只说结论。
- 改了不该改的文件：用 `/diff` 查看改动，或直接拒绝、让其重来。

---

## 实战案例：30 分钟读懂一个 Flask 待办 API

把上面六步串成一个完整流程。目标：克隆一个陌生 Flask 项目，10 分钟内能向同事讲清"一个请求从进来到落库经历了什么"。

```bash
# 1. 准备场地
mkdir -p ~/projects && cd ~/projects
git clone https://github.com/gothinkster/flask-realworld-example-app demo
cd demo

# 2. 启动并生成记忆
claude
# 会话内：
> /init
```

`/init` 后，Claude 给出项目画像：Flask + SQLAlchemy + SQLite/Postgres，入口在 `app.py`，路由集中在 `.../api/`，用 `flask` CLI 启动。

继续提问（探索阶段）：

```
> @app.py 一条 POST /api/articles 的请求，从进来到写库，
  完整的函数调用链是什么？给出 file:line。
> 用 Mermaid 画这条调用链的时序图。
```

Claude 用 Explore 子代理翻完代码，回你一段带行号引用的调用链和时序图。你在对话里追问：

```
> 这条链路里最容易出问题的是哪一步？为什么？
> 如果我要给 article 加一个 "置顶" 字段，要改哪些文件？先列清单，别动手。
```

进入计划阶段，它给出改动清单（model、schema、路由、迁移各一处）。你确认后，给它一个可验证的小任务：

```
> 只在 model 和 schema 里加 is_pinned 布尔字段。
> 改完跑 pytest，把输出贴给我。不要碰路由和迁移。
```

测试通过，你用 `/diff` 复核，满意后退出。整个过程中你没有逐行读源码，却已经能讲清架构并安全地改了一处。这就是"用 Claude Code 读透陌生代码库"的标准动作。

### 整体工作流程图

```mermaid
flowchart TD
    A[克隆项目到本地] --> B[cd 进根目录启动 claude]
    B --> C[/init 生成 CLAUDE.md 记忆/]
    C --> D[探索: 问入口/调用链/核心文件]
    D --> E{上下文 > 70%?}
    E -- 是 --> F[/compact 压缩或 /clear 重开/]
    E -- 否 --> G[计划: 列改动清单/画图]
    F --> G
    G --> H[动手: 小而可验证的任务]
    H --> I[Claude 自跑测试迭代]
    I --> J{检查 pass?}
    J -- 否 --> I
    J -- 是 --> K[/diff 复核 + 权限护栏把关/]
    K --> L[读懂并安全改完一处]
```

---

## 延伸阅读

- **官方最佳实践**（Explore→Plan→Code 心法、上下文管理、子代理用法）：https://code.claude.com/docs/en/best-practices
- **CLI 命令完整参考**（`-c`/`-r`/`-p`、`claude install`、`auth`、`agents`）：https://code.claude.com/docs/en/cli-reference
- **.claude 目录与 CLAUDE.md 详解**：https://code.claude.com/docs/en/claude-directory
- **Claude Code 全栈解析（2026）**——MCP/Skills/Subagents/Hooks 如何叠加：https://alexop.dev/posts/understanding-claude-code-full-stack/
- **Claude Code 速查表（2026）**——快捷键、命令、技巧：https://computingforgeeks.com/claude-code-cheat-sheet/

---

## 训练营适用性评估

- **适合类型**：AI 编程入门营、新人入职 Bootcamp、开源贡献入门营。本教程不要求写复杂代码，门槛低、产出感强，非常适合作为"第一次接触 Claude Code"的开场实验。
- **教学时长**：建议 1.5–2 小时。其中讲解 30 分钟，学员动手克隆 + `/init` + 探索提问约 60 分钟，安全修改与复盘 30 分钟。
- **评估标准**：学员能口头复述陌生项目的入口与一条调用链，并用 `/diff` 展示一处通过测试的小改动即算达标。
- **延伸方向**：达标后可顺势衔接进阶主题——编写 CLAUDE.md 模块化规则、用 Explore 之外的自定义子代理做并行调研、用 `-p` 无头模式批量审查多个项目。

---

## 参考来源

1. [Best practices for Claude Code — Claude Code Docs](https://code.claude.com/docs/en/best-practices) — 官方核心心法：探索优先、给可验证任务、激进管理上下文、用子代理调研
2. [CLI reference — Claude Code Docs](https://code.claude.com/docs/en/cli-reference) — `claude`、`-c`、`-r`、`-p`、`claude install`、`auth status`、`agents` 等命令与 flags 全表
3. [Claude Code Explained (2026): MCP, Skills, Subagents, Hooks & Plugins — alexop.dev](https://alexop.dev/posts/understanding-claude-code-full-stack/) — 2026 特性栈全景与 Deferred Tool Loading 等新机制
4. [Explore the .claude directory — Claude Code Docs](https://code.claude.com/docs/en/claude-directory) — CLAUDE.md 加载顺序与项目记忆机制
5. [Claude Code Cheat Sheet (2026) — ComputingForGeeks](https://computingforgeeks.com/claude-code-cheat-sheet/) — 新手快捷键、斜杠命令与权限模式速查

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