第 20 章：场景一：理解陌生项目

从本章开始，我们进入第五篇：实战篇。前面的四篇分别覆盖了基础概念、核心功能、进阶机制和扩展生态——你已经掌握了 Claude Code 的完整技术栈。但从"知道"到"会用"，中间隔着一道鸿沟，这道鸿沟只能用真实的项目场景来填平。

本章是实战篇的第一个场景，也是一个开发者职业生涯中反复遇到的经典难题：接手一个完全陌生的项目。代码量不小、文档几乎没有、原来的团队已经离开——你需要在短时间内理解这个项目，并具备维护和修改的能力。

在没有 AI 助手的时代，这个过程需要数周甚至数月。你要逐文件阅读代码、用纸笔画出调用关系、反复调试才能摸清一个模块的逻辑。但有了 Claude Code，相同的目标可以在几天内达成——前提是你知道怎么正确地引导它。

本章目标：学会使用 Claude Code 的四步法快速理解一个陌生代码库——从建立全局认知，到追踪核心业务流程，到生成项目文档，最后识别技术债务。掌握每一步的具体操作方法和关键技巧。

20.1 场景描述

先把这个场景具象化，让你能代入其中。

时间是周五下午 4:30。你的技术负责人走过来，表情有些抱歉："有个事需要你帮忙。市场部那边有一个内部使用的电商后台系统，原来负责的两个同事上个月离职了。最近运营反馈了几个 Bug，需要有人去修。你看能不能先了解一下这个项目？"

你打开项目仓库，看到的是这样的景象：

代码量：约 5 万行，分布在 200+ 个文件中
技术栈：后端是 Express.js + Sequelize ORM，前端是 React 16 + Redux，数据库是 MySQL
文档：README.md 只有三行——项目名称、npm start、没了
注释：零星几个中文注释，大部分代码是裸的
Git 历史：最近三个月没有提交，最后一个有意义的消息是 "update"
依赖：package.json 中 60+ 个依赖，其中一半你都没见过

你尝试运行项目——报错了。错误信息指向一个环境变量 DATABASE_URL，但你不知道它应该是什么格式，也不知道还有哪些环境变量需要配置。

此时你的心情可能介于"挑战感"和"绝望感"之间。但深呼吸，你打开了 Claude Code。

这就是本章的场景。接下来，我将带你用 Claude Code 的四步法，从零开始理解这个项目。

前提假设：为了演示清晰，本章中的示例假设该项目使用了 Express + React + MySQL 的经典架构。你实际面对的项目技术栈可能不同，但方法论是通用的——无论项目用什么语言、什么框架，理解陌生代码库的四个步骤是一致的。

20.2 Step 1：建立全局认知

理解一个陌生项目，最忌讳的就是一上来就钻到某个文件里去读代码。你花两个小时读懂了一个 500 行的 service 文件，结果发现它是三个月前就该被删除的废弃模块。这种挫败感足以毁掉你一天的工作热情。

正确的方法是先宏观，后微观。先搞清楚项目的整体轮廓——它是什么、用了什么技术、有哪几个核心模块、它们之间怎么连接。有了这张"地图"，你再深入任何一个局部，都知道自己站在哪里。

20.2.1 第一个对话：了解项目全貌

打开 Claude Code，启动你的第一个对话。不需要复杂的提示词，从最简单的开始：

你：介绍一下这个项目的整体结构。

Claude Code 会自动执行一系列的探索操作——读取 package.json、列出目录结构、查看主要的配置文件。如果项目根目录有 CLAUDE.md，它会在会话启动时自动加载。如果没有，Claude 会通过 Glob 和 Read 工具自行探索。

Claude 的回答可能是这样的（以我们的示例项目为背景）：

Claude：通过分析项目结构，这是一个电商后台管理系统，技术栈如下：
后端 (Express.js + Sequelize)：
server/routes/ — 路由层：/api/products（商品）、/api/orders（订单）、/api/users（用户）、/api/auth（认证）
server/controllers/ — 控制器层：每个路由文件对应一个控制器
server/services/ — 服务层：业务逻辑封装
server/models/ — 数据模型：User、Product、Order、OrderItem 等
server/middleware/ — 中间件：认证、错误处理、日志
前端 (React 16 + Redux)：
client/src/pages/ — 页面组件：商品管理、订单管理、用户管理、登录
client/src/components/ — 通用组件
client/src/store/ — Redux 状态管理
client/src/api/ — API 请求封装
数据库：MySQL，使用 Sequelize ORM，配置文件在 server/config/database.js
项目约有 50,000 行代码，前端和后端各占约一半。

注意 Claude 的第一次回答：它已经为你建立了项目的第一层认知框架。你知道了有哪些模块、每个模块的职责、前后端的目录组织方式。这个回答花了不到 30 秒——如果你自己读代码来达到相同的理解程度，至少需要半天。

20.2.2 追问：技术栈和架构细节

有了第一层框架，接下来往深一层追问：

你：这个项目主要用了哪些技术栈？数据库怎么设计的？帮我画出项目架构图。

这里的技巧是一个问题包含多个子问题——Claude Code 可以并行处理，不需要等你一个个问。同时，直接要求它画出架构图——Mermaid 图比文字描述直观得多。

Claude：项目的详细技术栈：
后端依赖：
Express 4.17 — Web 框架
Sequelize 5.21 — ORM（操作 MySQL）
jsonwebtoken 8.5 — JWT 认证
bcrypt 3.0 — 密码加密
multer 1.4 — 文件上传
express-validator 6.3 — 参数验证
morgan 1.9 — HTTP 请求日志
前端依赖：
React 16.13 + react-router-dom 5.1
Redux 4.0 + react-redux 7.1
Ant Design 3.26 — UI 组件库
axios 0.19 — HTTP 请求
moment 2.24 — 日期处理
数据库设计（共 8 张表）：
erDiagram User ||--o{ Order : places User { int id PK string username string password_hash string role datetime created_at } Order ||--|{ OrderItem : contains Order { int id PK int user_id FK decimal total_amount string status datetime created_at } Product ||--o{ OrderItem : includes Product { int id PK string name decimal price int stock int category_id FK } OrderItem { int id PK int order_id FK int product_id FK int quantity decimal unit_price } Category ||--o{ Product : has Category { int id PK string name int parent_id } User ||--o{ Address : has Address { int id PK int user_id FK string detail bool is_default } Product ||--o{ CartItem : in_cart CartItem { int id PK int user_id FK int product_id FK int quantity } User ||--o{ CartItem : owns
项目架构图：
graph TB subgraph Frontend["Frontend (React 16 + Redux)"] Pages["Pages 商品/订单/用户管理"] Components["Components 通用组件"] Store["Redux Store 状态管理"] ApiClient["API Client axios"] end subgraph Backend["Backend (Express.js)"] Routes["Routes 路由层"] Controllers["Controllers 控制器层"] Services["Services 服务层"] Models["Models Sequelize ORM"] Middleware["Middleware 认证/错误/日志"] end subgraph Infra["Infrastructure"] MySQL[("MySQL 数据库")] FileStorage[("本地文件存储 上传图片")] end Pages --> ApiClient ApiClient -->|"HTTP /api/*"| Routes Routes --> Controllers Controllers --> Services Services --> Models Models --> MySQL Routes --> Middleware Services --> FileStorage

这一轮追问之后，你得到了三个关键信息：

技术栈清单：每个依赖的版本号和作用
数据库 ER 图：8 张表的结构和关系一目了然
系统架构图：前后端的分层结构、数据流向

这三样东西，在没有 AI 助手的时代，你可能需要花两到三天才能梳理清楚——从翻 package.json 查版本、到读每个 Model 文件画 ER 图、到逐个文件追踪调用关系。而 Claude Code 在几分钟内就交付了。

20.2.3 全局认知阶段的技巧

不要一次性问太多。虽然 Claude 可以处理复杂问题，但在探索阶段，分两步走更高效：第一步问"整体结构"获得框架；第二步问"技术栈 + 数据库 + 架构图"填充细节。两步之间的间隔，也是你消化第一步信息的时间。

先看架构图，再看文字。Claude 给出的 Mermaid 架构图是你的"地图"。花 2-3 分钟认真看这张图——理解每一层是做什么的、请求是从哪里流到哪里的。这张图是后续所有深入探索的导航。

追问有疑问的部分。如果 Claude 的回答中有你不理解的模块（比如 "morgan 是什么？"），立刻追问：

你：morgan 是什么？这个项目为什么需要它？

不要觉得问基础问题是浪费——在这个阶段，任何不理解的点都是一颗地雷，你越早排除它，后续的理解越顺畅。

记住这个原则：宏观理解的成本远低于微观阅读的成本。先花 30 分钟把全局搞清楚，比直接花 8 小时逐文件阅读的效率高得多。

20.3 Step 2：梳理核心业务流程

有了全局认知，你已经知道项目由哪些模块组成。下一步是理解项目最核心的业务流程——一个用户的请求是如何穿越各层到达数据库，再原路返回的。

20.3.1 选一个最核心的流程

不要试图同时理解所有业务流程。你的关注点应该落在最高频、最核心的那个流程上——在电商系统中，这个流程显然是"用户下单"。

你：用户从浏览商品到下单的完整流程是怎样的？帮我追踪代码。

这个提示词的关键在于：你说的是"追踪代码"，而不是"描述流程"。前者会让 Claude 去实际读取路由、控制器、服务层、数据模型的代码，给出一个基于代码的分析而不是一个泛泛的概括。后者可能只是一个概念性的回答——"用户选商品、加购物车、结账、付款"——这些你本来就知道。

Claude：我追踪了项目中的下单流程，以下是完整的代码路径：
1. 路由定义 — server/routes/orders.js
javascript
router.post('/api/orders', authMiddleware, orderController.create);
创建订单需要认证（authMiddleware），调用 orderController.create。
2. 控制器层 — server/controllers/orderController.js
javascript
exports.create = async (req, res) => {
 try {
 const { items, addressId } = req.body;
 const userId = req.user.id;
 const order = await orderService.createOrder(userId, items, addressId);
 res.json({ code: 0, data: order });
 } catch (err) {
 next(err);
 }
};
从 JWT 中解析用户 ID，获取请求体中的商品列表和地址 ID，调用服务层。
3. 服务层 — server/services/orderService.js 核心业务逻辑（我追踪了 createOrder 方法）：
验证商品：逐一查询每个 SKU 是否存在
检查库存：if (product.stock < item.quantity) 返回"库存不足"
计算金额：total = sum(item.quantity * item.unitPrice)
开启事务：使用 sequelize.transaction()
创建 Order 记录
批量创建 OrderItem 记录
扣减 Product 库存（product.stock -= item.quantity）
清空用户的 CartItem
返回订单：包含订单详情和状态（status: 'pending'）
4. 数据模型 — server/models/Order.js, server/models/OrderItem.js Order 和 OrderItem 是一对多关系，Order 关联 User。
注意：支付功能只有状态更新逻辑（updateStatus），没有对接第三方支付网关。库存扣减在高并发下存在超卖风险（没有使用乐观锁或悲观锁）。

注意 Claude 最后的"注意"部分——它不仅追踪了代码，还自动识别了潜在问题："没有对接支付接口"、"库存扣减存在超卖风险"。这是一个非常重要的附赠品——在追踪代码的过程中，Claude 会发现不符合预期的设计，并提醒你。

20.3.2 用序列图可视化流程

理解了代码路径后，让 Claude 用序列图画出来：

你：用 Mermaid 序列图画出用户下单的完整流程。

Claude：
sequenceDiagram actor User as 用户 participant React as React 前端 participant Router as Express Router participant Auth as Auth 中间件 participant Ctrl as OrderController participant Svc as OrderService participant DB as MySQL User->>React: 点击"提交订单" React->>Router: POST /api/orders {items, addressId} Router->>Auth: 验证 JWT Token Auth-->>Router: userId = 42 Router->>Ctrl: orderController.create(req, res) Ctrl->>Svc: createOrder(userId, items, addressId) Svc->>DB: SELECT * FROM products WHERE id IN (...) DB-->>Svc: 商品列表（含价格、库存） alt 库存不足 Svc-->>Ctrl: Error: 商品 "xxx" 库存不足 Ctrl-->>User: { code: 1, msg: "库存不足" } else 库存充足 Svc->>DB: BEGIN TRANSACTION Svc->>DB: INSERT INTO orders ... Svc->>DB: INSERT INTO order_items ... (批量) Svc->>DB: UPDATE products SET stock = stock - ? ... Svc->>DB: DELETE FROM cart_items WHERE user_id = 42 Svc->>DB: COMMIT Svc-->>Ctrl: { id: 1234, status: 'pending', total: 299.00 } Ctrl-->>User: { code: 0, data: { orderId: 1234 } } end

序列图的价值在于它把时间维度的调用关系可视化——谁先调用谁、每一步从哪里流到哪里、分支条件在哪里出现。当你需要向其他同事解释这个流程时，这张图比任何文字描述都有效。

20.3.3 第二个核心流程：认证

理解了下单流程后，再快速看一个辅助流程——用户认证。这是几乎所有功能的前置条件：

你：用户登录认证的完整流程是怎样的？包括 JWT 的生成和验证逻辑。

Claude：我追踪了认证相关代码，流程如下：
登录流程（POST /api/auth/login）：
接收 { username, password }
authController.login → authService.authenticate
authService 查询 User 表 → 用 bcrypt.compare 验证密码
生成 JWT：jwt.sign({ id: user.id, role: user.role }, SECRET, { expiresIn: '7d' })
返回 { token, userInfo }
验证流程（authMiddleware）：
从 Authorization: Bearer <token> 中提取 token
jwt.verify(token, SECRET) → 解码出 { id, role }
将 req.user = { id, role } 注入请求对象
后续的控制器可以直接通过 req.user.id 获取当前用户
发现：JWT Secret 硬编码在 server/config/auth.js 中（'mysecretkey2020'），且没有刷新机制。Token 有效期 7 天，即使改了密码，旧 Token 仍然有效。

又是一个"附赠品"——Claude 自动指出了安全风险：硬编码的 JWT Secret 和缺少 Token 刷新机制。这些发现会在后面的 Step 4（技术债务识别）中有用。

20.3.4 核心流程阶段的技巧

一次只追踪一个流程。不要同时让 Claude 分析"下单、退款、发货、对账"四个流程。一个流程的完整追踪已经涉及 5-10 个文件、跨越 3-4 层代码——把这些信息全部吃透后再进行下一个。

阅读序列图。Claude 生成的序列图是理解流程的最佳入口。花 5 分钟仔细阅读它——追踪每一步的参与者、消息内容和分支逻辑。理解这张图胜过阅读 500 行代码。

标记疑问点。追踪代码的过程中，Claude 可能会指出一些"奇怪"的地方（如前面提到的"没有支付接口"、"硬编码 Secret"）。把这些点记录下来——它们会在 Step 4 的技术债务识别中派上用场。

选择流程的优先级：

优先级	流程类型	示例
1	核心业务流程	下单、支付、退款
2	前提性流程	登录认证、权限校验
3	辅助流程	数据导出、消息通知、日志

前两个优先级的流程追踪完后，你对项目的理解就已经超过 90% 的同事了。

20.4 Step 3：生成项目文档

到现在为止，你对项目的理解已经相当深入——你知道它由哪些模块构成、核心业务流程怎么走、数据库是怎么设计的。但所有这些知识，都只在你的大脑里和当前的 Claude Code 对话中。

下一步是把这些知识外化——生成结构化的文档。文档的价值不仅是"方便后面自己查阅"，更在于：当你需要拉同事一起参与这个项目的维护时，文档是他们快速上手的唯一途径。

20.4.1 生成项目 README

先从最基础的开始——一份像样的 README：

你：帮我生成一份项目 README，包含以下内容：
项目简介（一句话说清楚这个系统是干什么的）
技术栈（前后端分别列出）
目录结构（主要目录和文件的职责）
启动方式（需要的环境变量、数据库初始化步骤、启动命令）
用中文编写，保持简洁专业。

Claude 会基于它在前两步中积累的对项目的理解，生成一份完整的 README。它不需要重新探索——同一个会话中，Claude 对项目的认知是持续的。

关键在于：你给出的指令要明确章节要求。不要只说"帮我写个 README"——Claude 可能输出一个泛泛的模板。指定章节结构后，输出的质量会高一个档次。

拿到 README 后，你需要在项目中创建或更新 README.md 文件，把 Claude 生成的内容写入。从此以后，这个项目不再是"没有文档"的项目了。

20.4.2 生成 API 接口文档

接口文档是后续维护和调试工作的必需品。当运营反馈一个 Bug 说"某个接口返回的数据不对"，你不需要先去翻代码看接口的请求参数和返回格式——文档会告诉你一切。

你：帮我梳理所有 API 接口，生成一份接口文档。每个接口包含：
路径和方法
功能说明（一句话）
请求参数（Path/Query/Body，标注必填）
返回格式（成功和失败各给一个示例）
是否需要认证

Claude 会逐个读取路由文件，提取接口定义：

Claude：项目共有 19 个 API 接口，按模块分组如下：
认证模块 /api/auth
方法路径功能认证
POST /api/auth/login 用户登录否
POST /api/auth/register 用户注册否
GET /api/auth/me 获取当前用户信息是
POST /api/auth/login
请求体：
json
{
  "username": "admin",
  "password": "123456"
}
成功响应 (200)：
json
{
  "code": 0,
  "data": {
    "token": "eyJhbGciOi...",
    "user": { "id": 1, "username": "admin", "role": "admin" }
  }
}
失败响应 (401)：
json
{
  "code": 1,
  "msg": "用户名或密码错误"
}
商品模块 /api/products（5 个接口）
订单模块 /api/orders（6 个接口）
用户模块 /api/users（4 个接口）
（后续内容类似，此处省略完整输出）

方法	路径	功能	认证
POST	`/api/auth/login`	用户登录	否
POST	`/api/auth/register`	用户注册	否
GET	`/api/auth/me`	获取当前用户信息	是

你可能会想："这么多接口，生成的文档靠谱吗？"答案是：基本靠谱，但需要人工抽查。Claude 从代码中提取的接口信息（路径、方法、参数）是准确的——它是从路由定义和控制器代码中逐行读取的。但返回格式的"示例"是它根据代码逻辑推断的——可能在边缘情况下与实际不完全一致。操作方法：对核心接口（登录、下单、支付相关的 5-6 个）逐一通过 Postman 或 curl 验证；对其他接口，抽查 3-5 个。

20.4.3 梳理环境变量

遗留项目最常见的运行障碍就是环境变量——你拿到了代码，但不知道需要配置哪些环境变量，更不知道每个变量的作用。npm start 直接报错。

你：找出项目中所有环境变量，说明每个的用途、是否必填、示例值。

Claude：我在项目中找到了 7 个环境变量，分别在以下文件中被引用：
变量名用途必填示例值引用文件
DATABASE_URL MySQL 连接字符串 ✅ mysql://root:pass@localhost:3306/ecommerce server/config/database.js
JWT_SECRET JWT 签名密钥 ✅ 至少 32 字符的随机字符串 server/config/auth.js
PORT 后端服务端口 ❌（默认 3000） 3001 server/index.js
UPLOAD_DIR 文件上传存储路径 ❌（默认 ./uploads） /data/uploads server/config/upload.js
CORS_ORIGIN 允许的前端跨域来源 ❌（默认 *） http://admin.example.com server/index.js
LOG_LEVEL 日志级别 ❌（默认 info） debug server/config/logger.js
REDIS_URL Redis 连接（会话存储） ⚠️ 可选但推荐 redis://localhost:6379 server/config/session.js
建议创建 .env.example：
bash
DATABASE_URL=mysql://root:password@localhost:3306/ecommerce
JWT_SECRET=your-secret-key-change-in-production
PORT=3000
UPLOAD_DIR=./uploads
CORS_ORIGIN=http://localhost:8080
LOG_LEVEL=debug
# REDIS_URL=redis://localhost:6379（可选）

变量名	用途	必填	示例值	引用文件
`DATABASE_URL`	MySQL 连接字符串	✅	`mysql://root:pass@localhost:3306/ecommerce`	`server/config/database.js`
`JWT_SECRET`	JWT 签名密钥	✅	`至少 32 字符的随机字符串`	`server/config/auth.js`
`PORT`	后端服务端口	❌（默认 3000）	`3001`	`server/index.js`
`UPLOAD_DIR`	文件上传存储路径	❌（默认 `./uploads`）	`/data/uploads`	`server/config/upload.js`
`CORS_ORIGIN`	允许的前端跨域来源	❌（默认 `*`）	`http://admin.example.com`	`server/index.js`
`LOG_LEVEL`	日志级别	❌（默认 `info`）	`debug`	`server/config/logger.js`
`REDIS_URL`	Redis 连接（会话存储）	⚠️ 可选但推荐	`redis://localhost:6379`	`server/config/session.js`

别忘了最后一步：把 .env.example 文件创建出来，提交到 Git。即使里面是假的值，它也让下一个接手的人知道有哪些变量需要配置。这是一个成本极低但价值极高的善举。

20.4.4 文档化阶段的技巧

不要一次性要求太多。一天内要求 Claude 生成 README + API 文档 + 环境变量说明 + 数据库文档 + 部署文档——Claude 不会拒绝你，但输出质量会下降（上下文窗口被大量输出占满，后续推理空间被挤压）。按以下节奏分三批进行：

批次	内容	时间
第一批	README + 环境变量	Day 1
第二批	API 接口文档	Day 2
第三批	数据库设计文档 + 核心流程文档	Day 3

文档应该放在项目中。不要把 Claude 的输出只留在对话历史里——创建实际的 .md 文件，放在项目的 docs/ 目录下。这样，当你下一次打开 Claude Code（新会话），Claude 可以自己读取这些文档来理解项目。

人工审查，不能盲信。API 文档中的返回格式、数据库文档中的字段类型——这些是 Claude "推断"出来的，不是"验证"过的。对核心接口和核心表，你需要亲自验证。原理很简单：Claude 读的是代码，不是运行中的系统。代码写的和实际运行的不一定一致。

在项目根目录也补上 CLAUDE.md。如果你还希望后续用 Claude Code 维护这个项目，花 20 分钟写一份 CLAUDE.md（参考第 12 章：CLAUDE.md）。把项目架构、常用命令、关键约定写进去——这是留给你自己和未来同事的"AI 入职文档"。

20.5 Step 4：识别技术债务

理解了一个项目的现状之后，下一个自然的问题是：这个项目的代码质量怎么样？有什么问题需要解决？

原始团队已经离开，没有人能告诉你"哪段代码是临时的、哪个依赖该升级了、哪里有隐藏的 Bug"。但 Claude Code 可以帮你系统性地做这件事——通过静态分析代码，识别潜在的技术债务。

20.5.1 代码质量审查

你：帮我审查 server/ 目录的代码质量，重点找出以下问题：
重复代码
缺少错误处理的地方
TODO/FIXME/HACK 注释
使用了过时的 API 或反模式
潜在的性能问题
按严重程度分类：🔴 紧急、🟡 需要关注、🟢 长期改善。

注意这个提示词的结构：先指定范围（server/），再列出关注的维度，最后要求按严重程度分类。前两点让 Claude 的搜索有明确的方向，第三点让你拿到结果后能立刻规划优先级。

Claude：审查完成，共发现 23 个问题，分类如下：
🔴 紧急（建议尽快修复）
SQL 注入风险 — server/controllers/productController.js:45
搜索功能使用了字符串拼接构造 SQL 查询：db.query('SELECT * FROM products WHERE name LIKE "%' + keyword + '%"')
改为使用 Sequelize 的参数化查询或 Op.like
缺少事务的订单创建 — server/services/orderService.js:67-82
库存扣减和订单创建之间没有事务保护，如果库存扣减成功但订单创建失败，库存已经被扣了但订单没有生成
已在上面的流程分析中确认：此处在 Step 2 中实际上有事务，但另一个下单入口 /api/orders/quick 缺少事务
明文存储用户密码 — server/models/User.js:23
password 字段没有使用 bcrypt 加密存储，直接存了明文
虽然有 authService 中的登录验证使用了 bcrypt.compare，但注册接口 authController.register 调用了另一个没有 hash 的服务方法
🟡 需要关注
全局错误处理器缺失 — 9 个控制器中的 catch 块直接 res.status(500).send(err)，暴露了内部错误信息
重复的参数验证逻辑 — 订单和购物车模块各有一份几乎完全相同的商品库存验证代码（约 40 行），应提取为公共函数
TODO 注释共 7 处 — 涉及退款逻辑、导出报表、短信通知
数据库连接没有重连机制 — Sequelize 默认配置，数据库断开后不会自动重连
日志中使用 console.log — 12 处，没有使用 morgan 或统一日志模块
🟢 长期改善
N+1 查询问题 — server/services/orderService.js:112 — 获取订单列表时对每个订单逐个查询用户信息，应使用 include eager loading
缺少单元测试 — 整个项目没有测试文件
Redux store 结构扁平化不足 — 前端存在深层嵌套的状态树
React 16 的类组件应迁移到函数组件 + Hooks
...（共 23 项）

这份清单为你提供了清晰的"排雷地图"。你不需要一次性修复所有问题——按优先级分批次处理：🔴 紧急的先修（涉及安全漏洞和数据一致性的），🟡 需要关注的安排到下个迭代，🟢 长期改善的记在 Backlog 里。

20.5.2 依赖版本审查

在技术审查的基础上，再做一个依赖审计——这可能是前任开发者最后一次 npm install 后就没再碰过的东西。

你：帮我检查 package.json 中所有依赖的版本，对比当前最新版本，标注哪些已经严重过时。

Claude：对比分析完成。package.json 中有 62 个依赖，其中 18 个 已停止维护或存在已知安全漏洞：
依赖当前版本最新版本差距风险
react 16.13.0 18.3.1 2 个主版本 🔴 React 16 已于 2021 年停止维护
sequelize 5.21.0 6.37.0 1 个主版本 🟡 5.x 已于 2022 年 EOL
antd 3.26.0 5.22.0 2 个主版本 🟡 3.x 已不再接收安全修复
jsonwebtoken 8.5.1 9.0.2 1 个主版本 🟡 8.x 有已知漏洞 (CVE-2022-23529)
moment 2.24.0 2.30.1 小版本 🟢 团队推荐迁移到 day.js
... ... ... ... ...
立即需要处理的：jsonwebtoken（安全漏洞）和 sequelize（不再维护）
升级路径建议：
先升级 jsonwebtoken 到 9.x（影响较小，API 兼容）
升级 sequelize 5→6（有破坏性变更，需要仔细测试）
React 16→18 和 antd 3→5 跨多个主版本，建议在功能稳定后再做

依赖	当前版本	最新版本	差距	风险
react	16.13.0	18.3.1	2 个主版本	🔴 React 16 已于 2021 年停止维护
sequelize	5.21.0	6.37.0	1 个主版本	🟡 5.x 已于 2022 年 EOL
antd	3.26.0	5.22.0	2 个主版本	🟡 3.x 已不再接收安全修复
jsonwebtoken	8.5.1	9.0.2	1 个主版本	🟡 8.x 有已知漏洞 (CVE-2022-23529)
moment	2.24.0	2.30.1	小版本	🟢 团队推荐迁移到 day.js
...	...	...	...	...

依赖审查的价值不仅在于"发现有问题的依赖"，更在于知道哪些升级的破坏性最大，从而规划升级顺序。

20.5.3 技术债务识别阶段的技巧

不要期望 Claude 找出所有问题。Claude 的审查是基于静态代码分析的——它能找出你能通过读代码发现的问题，但不能找出运行时的问题（如内存泄漏、竞态条件）。对于隐藏得更深的问题，你需要运行时监控和实际的 Bug 反馈。

关注"安全"和"数据一致性"类别.不是因为它们最常见（重复代码可能更多），而是因为它们的危害最大。一个 SQL 注入漏洞可以让你的数据库被拖走；一个缺少事务的写操作可以导致数据不一致。这两类问题应该排在修复队列的最前面。

手动审查高优先级项。Claude 标记为"🔴 紧急"的每一项，你都需要亲自去确认——它是真实问题还是误报。Claude 的分析可能在某些情况下出错（比如它误判了一个已加密的密码为明文）。确认的方式很简单：打开对应的文件，看对应的代码行。

依赖升级单独建分支。当你决定升级一个依赖时，不要和功能修复混在同一个 PR 里。一个依赖升级可能导致项目完全跑不起来（尤其是跨主版本的升级），在一个独立分支中处理并充分测试，比在一个混合 PR 中焦头烂额地改要安全得多。

20.6 复盘与技巧总结

经过了四个步骤——全局认知 → 核心流程 → 文档化 → 技术债——你已经用了大约 3-4 天时间（每天 3-4 小时的有效工作时间），对这个陌生项目建立了足以开始维护的理解深度。对比没有 AI 助手时可能需要 2-3 周才能达到相同水平的局面，效率提升是实实在在的。

但在结束本章之前，我们需要做一件更重要的事情：把这次经验提炼成可复用的方法论。因为你会一次又一次地面对陌生项目——今天的电商后台、明天的金融系统、后天的 IoT 平台。掌握了方法，你面对任何项目都有章可循。

20.6.1 理解陌生项目的四步法

全局认知 → 核心流程 → 文档化 → 技术债
  (半天)     (1天)      (1天)     (半天)

第一步：全局认知（半天）

第一个对话："介绍这个项目的整体结构"
追问：技术栈清单、数据库设计、项目架构图
目标：拥有项目的"地图"——知道有什么模块、它们怎么连接

第二步：核心流程（1 天）

选一个最核心的业务流程（如用户下单）
让 Claude 逐层追踪代码：路由 → 控制器 → 服务层 → 数据层
用序列图可视化
再追踪 1-2 个辅助流程（如认证）
目标：深度理解 1-2 条请求的完整生命周期

第三步：文档化（1 天）

生成项目 README（架构 + 技术栈 + 启动方式）
梳理 API 接口文档
整理环境变量说明
创建 .env.example
目标：将理解外化为结构化的可查阅文档

第四步：技术债（半天）

代码质量审查（安全、重复、错误处理、TODO）
依赖版本审计
按严重程度分类：🔴 紧急 → 🟡 关注 → 🟢 长期
目标：识别最危险的债务，规划修复优先级

这四步走的不是直线，而是螺旋线——每一步都在前一步的基础上深入一层。你不需要严格按照这个顺序，但建议不要跳过第一步（直接开始追踪代码）或跳过第三步（文档化）。

20.6.2 关键技巧回顾

以下是在这个场景中反复出现、值得提炼的技巧：

1. 先宏观，后微观：不要在第一个对话里让 Claude 读某个具体的文件。先了解全局架构，知道你在整个系统中的位置，再深入细节。

2. 一个流程一个流程地追踪：不要同时要求 Claude 分析多个流程。一个流程的完整追踪涉及 5-15 个文件——把信息吃透再开始下一个。

3. 用图表可视化：Mermaid 架构图和序列图是你的"理解加速器"。一个复杂流程的文字描述可能需要 10 分钟消化，但序列图只需 2 分钟。

4. 追问每一个不理解的点：不要因为害怕问基础问题而跳过。Claude 不会评判你的问题——而你不问，这个盲点就永远留在那里。

5. 文档要落地：Claude 生成的文档不是让你"看看就好"的——创建实际的 .md 文件，存入项目的 docs/ 目录。外化的知识不会丢，记忆会。

6. 技术债按优先级排序：不要试图一次性修复所有问题。先处理安全漏洞和数据一致性风险（🔴），再处理代码质量和维护性问题（🟡），最后才是长期的架构改进（🟢）。

7. 验证，不要盲信：Claude 的分析有出错的可能——尤其是"推断"出的部分（如返回格式、字段类型）。对核心模块和核心接口，你需要亲自验证。

20.6.3 常见陷阱

这些是新手在使用 Claude Code 理解项目时最常见的错误：

陷阱一：一次性问太多

你：帮我分析这个项目的：架构、技术栈、数据库设计、所有业务流程、代码质量问题、依赖版本、测试覆盖率、部署方式、权限系统……

你期待 Claude 在一条消息中给出所有这些分析。Claude 会尝试回答，但输出的是浅层的、泛泛的概述——每个话题都只涉及了最表层的信息。正确的做法是：分步进行，每一步深入一个话题，逐步往下挖掘。

陷阱二：跳过宏观，直接看代码

你：打开 server/controllers/orderController.js，逐行解释这段代码。

你花了 30 分钟理解了 orderController.js 的每一行。然后你发现这个文件调用了 orderService.js，你又去读 orderService.js——它又调用了好几个 Model 文件。三个小时后，你已经读了 15 个文件，但没有形成对项目的整体认知。你迷失在细节的海洋里。正确做法：先看架构图，再追踪完整流程，最后才深入单个文件。

陷阱三：只读不问

你：（默默地把 Claude 的输出扫一遍，没有进一步追问）

Claude 的第一轮回答是它认为最重要的信息的摘要。其中可能有一些它没展开的细节，或者它认为不重要的背景。但这些"被省略的"信息可能恰好是你最需要的。追问是理解过程的核心环节——问清楚每个你不确定的地方。

陷阱四：不验证 Claude 的理解

Claude：这个项目的用户下单流程是：选择商品 → 加入购物车 → 结算 → 支付 → 发货

这个回答听起来很合理。但如果你没有追问"帮我追踪代码"，Claude 给出的可能是一个它基于常识推断的流程，而不是这个项目实际实现的流程——可能这个项目根本没有实现支付和发货。区别在于：基于代码的回答是可靠的，基于推断的回答不一定。务必让 Claude "追踪代码"，而不是"描述流程"。

陷阱五：文档写了但没放到项目中

你让 Claude 生成了 README、API 文档、环境变量说明。你觉得很有用，截了图发到团队群里。然后这些文档就留在了 Claude Code 的对话历史里。两周后你 /clear 了对话——文档全没了。文档要存为 .md 文件并提交到 Git。

陷阱六：拿到了技术债清单就开始改

你拿到了一份 23 项的技术债清单，热情满满地想全部修掉。你开始改代码——重构一个 service、升级一个依赖、重写一个组件。一天后发现项目跑不起来了，也说不清是哪一步改坏的。正确做法：每次只修一个问题，修完就提交；依赖升级单独建分支。

20.6.4 延伸场景：更大型的项目

本章的项目是 5 万行。如果你面对的是一个 50 万行的大型系统（如微服务架构、多仓库），方法论需要调整：

调整 1：多会话、分模块。不能在一个会话中理解整个项目——上下文窗口不够。每个模块（服务）用一个独立会话，配合该模块的 CLAUDE.md。

调整 2：先看架构文档。大型项目通常会有一些架构文档（即使不完整）。优先让 Claude 阅读已有文档，再由它补充缺失的部分。

调整 3：先定位修改的目标。大型项目中，你不太可能需要理解全部 50 万行代码。运维反馈的 Bug 通常指向特定模块。以 Bug 为入口点——修复一个 Bug 的过程中你会遍历该模块的核心代码，比漫无目的地"理解项目"高效得多。

调整 4：生成架构 Wiki。对于大型项目，前面的文档化步骤产出的是一个架构 Wiki（而非一个 README）。包含：总览图、每个服务的职责、服务间调用关系、数据流图、运维手册。

方法论的核心不变——全局 → 流程 → 文档 → 债务——但在每个步骤上的时间投入和技术手段会不同。

20.7 本章小结

本章是实战篇的第一个场景：理解陌生项目。你以一个遗留的电商后台系统为切入点，学习了用 Claude Code 快速理解陌生代码库的完整四步法。

核心知识回顾

四步法：全局认知（宏观架构）→ 核心流程（深度追踪 1-2 条请求）→ 文档化（将理解外化为结构化文档）→ 技术债（识别和排序代码问题）。四步之间是螺旋深入的关系，不是线性完成。
第一步的关键：先用一个简单的问题获得框架（"介绍项目结构"），再用追问填充细节（技术栈、数据库、架构图）。用 Mermaid 图可视化——架构图是你在后续探索中的"地图"。
第二步的关键：选最核心的一个业务流程，让 Claude 追踪代码（不是描述流程）。用序列图可视化调用关系。在这个过程中，Claude 会自动发现不合理的设计并提醒你。
第三步的关键：将外化的知识落地为实际的 .md 文件——README、API 文档、环境变量说明。文档写到项目中而不是留在对话历史里。.env.example 是一个成本极低但价值极高的交付物。
第四步的关键：让 Claude 按严重程度（🔴 紧急 → 🟡 关注 → 🟢 长期）分类技术债务。首先解决安全漏洞和数据一致性问题。依赖升级要独立建分支，不要和功能修复混合。
五个常见陷阱：一次性问太多（输出浅层概括）、跳过宏观直接看代码（迷失在细节中）、只读不问（错过关键信息）、不验证 Claude 的理解（推断不可靠）、文档不存为文件（对话清空后丢失）。
可复用性：这个四步法适用于任何技术栈——无论是 Java + Spring、Python + Django、Go + Gin，方法论的四个步骤是通用的。技术栈只影响第二步中追踪的代码路径，不影响方法论本身。

从理解到修改

本章你的成果是——对一个 5 万行的陌生项目建立了理解。但理解不是终点。下一步是从"理解"到"修改"——在理解的基础上，安全地在遗留代码中添加新功能、修复 Bug、重构旧逻辑。这正是下一章的主题：场景二：在遗留代码中安全添加新功能。

一个价值 5 万行的项目现在对你不那么陌生了。带着你的"地图"、序列图、API 文档和技术债清单——你不再是在黑暗中摸索，而是带着手电筒在地下室整理。虽然还有很多东西要修，但你至少知道每样东西在哪里。

章节小结：本章通过一个真实的电商后台遗留项目场景，完整展示了用 Claude Code 理解陌生代码库的"四步法"——全局认知、核心流程、文档化、技术债。每一步都配有具体的 Claude 对话示例、操作技巧和注意事项。在复盘部分，将经验提炼为可复用的方法论，并指出了新手的六个常见陷阱。无论你面对什么技术栈的陌生项目，这个方法论都是你的可靠起点。

下一章，我们将进入实战篇的第二个场景：如何利用 Claude Code 在遗留代码中安全地添加新功能——理解只是第一步，真正的挑战在于不破坏已有的东西。

第 20 章：场景一：理解陌生项目

20.1 场景描述

20.2 Step 1：建立全局认知

20.2.1 第一个对话：了解项目全貌

20.2.2 追问：技术栈和架构细节

20.2.3 全局认知阶段的技巧

20.3 Step 2：梳理核心业务流程

20.3.1 选一个最核心的流程

20.3.2 用序列图可视化流程

20.3.3 第二个核心流程：认证

20.3.4 核心流程阶段的技巧

20.4 Step 3：生成项目文档

20.4.1 生成项目 README

20.4.2 生成 API 接口文档

认证模块 `/api/auth`

商品模块 `/api/products`（5 个接口）

订单模块 `/api/orders`（6 个接口）

用户模块 `/api/users`（4 个接口）

20.4.3 梳理环境变量

20.4.4 文档化阶段的技巧

20.5 Step 4：识别技术债务

20.5.1 代码质量审查

🔴 紧急（建议尽快修复）

🟡 需要关注

🟢 长期改善

20.5.2 依赖版本审查

20.5.3 技术债务识别阶段的技巧

20.6 复盘与技巧总结

20.6.1 理解陌生项目的四步法

20.6.2 关键技巧回顾

20.6.3 常见陷阱

20.6.4 延伸场景：更大型的项目

20.7 本章小结

核心知识回顾

从理解到修改

第 20 章：场景一：理解陌生项目 ​

20.1 场景描述 ​

20.2 Step 1：建立全局认知 ​

20.2.1 第一个对话：了解项目全貌 ​

20.2.2 追问：技术栈和架构细节 ​

20.2.3 全局认知阶段的技巧 ​

20.3 Step 2：梳理核心业务流程 ​

20.3.1 选一个最核心的流程 ​

20.3.2 用序列图可视化流程 ​

20.3.3 第二个核心流程：认证 ​

20.3.4 核心流程阶段的技巧 ​

20.4 Step 3：生成项目文档 ​

20.4.1 生成项目 README ​

20.4.2 生成 API 接口文档 ​

认证模块 /api/auth ​

POST /api/auth/login ​

商品模块 /api/products（5 个接口） ​

订单模块 /api/orders（6 个接口） ​

用户模块 /api/users（4 个接口） ​

20.4.3 梳理环境变量 ​

20.4.4 文档化阶段的技巧 ​

20.5 Step 4：识别技术债务 ​

20.5.1 代码质量审查 ​

🔴 紧急（建议尽快修复） ​

🟡 需要关注 ​

🟢 长期改善 ​

20.5.2 依赖版本审查 ​

20.5.3 技术债务识别阶段的技巧 ​

20.6 复盘与技巧总结 ​

20.6.1 理解陌生项目的四步法 ​

20.6.2 关键技巧回顾 ​

20.6.3 常见陷阱 ​

20.6.4 延伸场景：更大型的项目 ​

20.7 本章小结 ​

核心知识回顾 ​

从理解到修改 ​

第 20 章：场景一：理解陌生项目

20.1 场景描述

20.2 Step 1：建立全局认知

20.2.1 第一个对话：了解项目全貌

20.2.2 追问：技术栈和架构细节

20.2.3 全局认知阶段的技巧

20.3 Step 2：梳理核心业务流程

20.3.1 选一个最核心的流程

20.3.2 用序列图可视化流程

20.3.3 第二个核心流程：认证

20.3.4 核心流程阶段的技巧

20.4 Step 3：生成项目文档

20.4.1 生成项目 README

20.4.2 生成 API 接口文档

认证模块 `/api/auth`

POST /api/auth/login

商品模块 `/api/products`（5 个接口）

订单模块 `/api/orders`（6 个接口）

用户模块 `/api/users`（4 个接口）

20.4.3 梳理环境变量

20.4.4 文档化阶段的技巧

20.5 Step 4：识别技术债务

20.5.1 代码质量审查

🔴 紧急（建议尽快修复）

🟡 需要关注

🟢 长期改善

20.5.2 依赖版本审查

20.5.3 技术债务识别阶段的技巧

20.6 复盘与技巧总结

20.6.1 理解陌生项目的四步法

20.6.2 关键技巧回顾

20.6.3 常见陷阱

20.6.4 延伸场景：更大型的项目

20.7 本章小结

核心知识回顾

从理解到修改