4.11 练习：拿到一个陌生项目，五分钟说清它在干什么

一、本节你会做出什么

你会拿到一套五分钟流程和一张速查卡模板，并用它真刀真枪读完一个你完全没见过的项目。

📷 效果位：一张填好的项目速查卡

这是第 4 章的毕业考。 前面十节学的东西，在这一节合成一个能力：

面对一堆陌生代码，不慌，而且知道从哪儿下手。

这个能力的实际用处比你想的多：

场景	为什么需要
你自己的项目放了两周	回来一看全忘了——你自己的项目也会变成陌生项目
AI 一次生成了二十个文件	得先看懂它给了什么，才能验收
想抄一个开源项目的做法	第 12.2 节「竞品拆解」
接外包活儿，接手别人的代码	第 12.4 节

---

二、开始前你需要

• 已完成 4.1 到 4.10（本节是这十节的综合运用）
• 练习项目 nextjs-practice 还留着（用来对比）
• AI 工具能用

---

三、跟着做

第 1 步：先说清不要怎么做

新手读陌生项目的三个典型死法：

❌ 死法	为什么死
从第一个文件开始逐行读	几百个文件，读到第三个就放弃了。而且读完也不知道整体在干什么
被 node_modules 吓到	看到几万个文件以为项目有多复杂——那不是项目的代码（4.5 讲过）
从配置文件开始看	tsconfig.json、next.config.ts 这些最不重要，却因为排在目录顶上先被点开

正确的方向是反的：

从外往里看，从结果往代码看。

先知道“这是个什么网站”（跑起来看），再知道“有哪些页面”（看路由），最后才看“某个页面怎么实现的”（读代码）。

而且绝大多数时候，你根本不需要读到最后一层。

第 2 步：五分钟流程

每步一分钟，按顺序来，不要跳。

① 读 package.json      → 这是什么技术栈？怎么启动？
② 跑起来看             → 这是个什么网站？
③ 看 app/ 目录结构      → 有哪些页面？
④ 打开两个文件          → 数据在哪？有哪些组件？
⑤ 让 AI 补齐并对照      → 验证我理解得对不对

① 第 1 分钟：package.json（4.5 学的）

cat package.json

只看三样：

看什么	得到什么
scripts	怎么启动（有没有 dev？是 pnpm dev 还是别的）
dependencies 前几个	技术栈（有 next 就是 Next.js，有 react 没 next 就是纯 React）
有没有眼熟的包	用了什么数据库、UI 库、工具

顺便确认用哪个包管理器（4.5 提过 lock 文件）：

看到哪个文件	用什么命令
pnpm-lock.yaml	pnpm install
package-lock.json	npm install
yarn.lock	yarn

⚠️ 用错包管理器是接手项目的头号坑：会生成第二个 lock 文件，然后依赖版本打架。看 lock 文件决定用哪个命令。

② 第 2 分钟：跑起来看

pnpm install        # 按上一步确认的命令
pnpm dev

浏览器打开，然后做三件事：

• 看首页：这是个什么网站？
• 点一遍导航：有哪些页面？
• 开着控制台（4.10）：有没有红字？

🔑 这一分钟的信息量最大。 代码能骗你，页面不会。

跑不起来也是重要信息——记下报错，这往往是项目最大的问题所在（缺 .env.local、Node 版本不对、依赖装不上）。

③ 第 3 分钟：看 app/ 目录（4.8 学的）

ls -R app | head -40

4.8 那条规则现在派上用场了：文件夹就是网址。

看一眼目录，你就知道这个网站有哪些页面：

app/
├── page.tsx              →  /              首页
├── about/page.tsx        →  /about         关于
├── attractions/
│   ├── page.tsx          →  /attractions   列表
│   └── [id]/page.tsx     →  /attractions/1 详情（动态路由）
└── api/                  →  后端接口（第 7 章）

更快的办法（4.8 第 9 步提过）：

pnpm build

build 的输出直接给你一张完整路由表——这是现成的网站地图。

💡 看到 api/ 目录就知道：这个项目有后端代码。那是第 7 章的内容，现在跳过。

④ 第 4 分钟：打开两个文件

只打开两个（4.5 学的那两个最重要的）：

文件	找什么
app/layout.tsx	每页都有的东西：导航、页脚、字体、整体结构
app/page.tsx	首页长什么样，以及它用到了哪些组件

在 page.tsx 里，用 4.6 第 8 步那五样东西扫一遍：

找	意味着
首字母大写的标签	这是组件，去 components/ 找同名文件
const xxx = [...]	数据写死在代码里（内容型网站常见）
useState	这里有会变的状态
.map(	数据在这里变成界面
await fetch(...) 或 await db...	数据是从外部来的（后端/数据库）

🔑 最有价值的一个判断：数据从哪来？

看到什么	说明
数组写死在文件里	静态内容站，改内容 = 改代码
fetch / await 调接口	有后端或第三方 API
从数据库读	全栈项目

这一条决定了整个项目的性质（4.1 讲的静态 vs 动态）。

然后看一眼 components/（4.9 学的）：

ls components

组件名就是功能清单。看到 AttractionCard.tsx、SearchBar.tsx、LoginForm.tsx，你立刻知道这个项目有卡片、有搜索、有登录。

⑤ 第 5 分钟：让 AI 补齐，并对照你的理解

关键：先自己说，再让 AI 说，然后对照。 顺序反了就变成“AI 替你理解”，练不出能力。

先把你的理解写下来（第 3 步那张卡），然后问 AI：

先不要改任何文件。请用中文回答，我是零基础：

1. 这个项目是干什么的？一句话。
2. 技术栈是什么？怎么启动（确切命令）？
3. 有哪些页面，分别对应哪个文件？
4. **数据从哪来**——写死在代码里、调接口、还是读数据库？
5. 有哪些组件，各自负责什么？
6. 这个项目里**有没有现在就坏的、或者明显有问题的地方**？
7. 如果我想改【某个具体东西】，该动哪个文件？

每条都要基于你实际读到的内容，**不确定的明确说不确定，不要猜**。

对照你自己的答案。 不一致的地方就是你的盲区——那正是这个练习的收获。

第 3 步：项目速查卡（本节交付物）

复制这张卡，读任何项目时填一遍。包括你自己两周没碰的项目。

## 项目速查卡：________________

**一句话这是什么**：____________________________

### 怎么跑
- 包管理器：☐ pnpm  ☐ npm  ☐ yarn   （依据：看到了 ______ lock 文件）
- 启动命令：____________
- 构建命令：____________
- 需要 .env 吗：☐ 不需要  ☐ 需要，缺的变量是：____________

### 技术栈
- 框架：____________（Next.js / React / 其他）
- 路由方式：☐ app/  ☐ pages/  ☐ 其他
- 样式：☐ Tailwind  ☐ CSS 文件  ☐ 其他
- 有后端吗：☐ 没有  ☐ 有（app/api/ 目录）
- 有数据库吗：☐ 没有  ☐ 有：____________

### 页面清单
| 网址 | 对应文件 | 这页干什么 |
| --- | --- | --- |
|  |  |  |

### 数据从哪来（最重要的一条）
☐ 写死在代码里（文件：____________）
☐ 调第三方接口
☐ 自己的后端接口
☐ 数据库

### 组件清单
| 组件 | 干什么 |
| --- | --- |
|  |  |

### 当前状态
- 能跑起来吗：☐ 能  ☐ 不能，报错：____________
- 控制台有红字吗：☐ 没有  ☐ 有：____________
- `pnpm build` 能过吗：☐ 能  ☐ 不能

### 如果我要改东西
- 改首页内容 → ____________
- 改导航/页脚 → ____________
- 改某个页面的样式 → ____________

第 4 步：实战演练（计时五分钟）

让 AI 给你出一道题。 这是本节最有意思的部分。

cd ~/Documents/ai-course
mkdir mystery-project && cd mystery-project

在这个空目录里启动 AI 工具，说：

请在当前目录生成一个完整的、能跑起来的 Next.js 小项目，用来给我做"读陌生项目"的练习。

要求：
1. 你自己决定做什么主题，**不要告诉我是什么**；
2. 至少 3 个页面，其中要有一个动态路由的详情页；
3. 至少 3 个组件，放在 components/ 目录；
4. 数据写死在代码里（不要接数据库，不要用需要密钥的接口）；
5. 用 Tailwind；
6. **故意留下一个小问题**（样式问题或控制台警告），不要告诉我是什么；
7. 生成完只回复"生成好了，依赖已装完"，**不要做任何说明**。

之后我会自己读这个项目，再来问你对不对。

然后计时五分钟，按第 2 步的流程走，填完速查卡。

五分钟到了，再问 AI：

我读完了，这是我的理解：
【粘贴你填好的速查卡】

请逐条告诉我：
1. 哪些判断是对的；
2. 哪些是错的或遗漏了，正确的是什么；
3. 我故意让你留的那个问题，我有没有发现？如果没发现，它在哪里、我应该怎样才能发现它？
4. 对我读项目的方法，有什么建议？

📷 截图位 1：填好的速查卡 + AI 的批改结果

🔑 这个练习可以反复做。 每次让 AI 换个主题、换个难度（比如“这次加上 app/api 接口”“这次故意把组件起成烂名字”）。这是本课唯一一个能自己无限出题的自测方式。

第 5 步：读项目的三条心法

① 不懂的先跳过，往下走

读到一段看不懂的代码，标记一下，继续往下。读完整体再回来，十次有八次你会发现那段其实不重要。

新手最容易卡在第一个不懂的地方，然后再也没往下走。

② 问“这个文件为什么存在”，而不是“这行代码在干什么”

❌ 低效的问题	✅ 高效的问题
这个 useMemo 是干什么的	这个文件在整个项目里扮演什么角色
第 47 行为什么要这样写	这个组件被谁用了

③ 用改动来验证理解

最可靠的验证方式：改一个小东西，看会不会按你预期变化。

git add -A && git commit -m "读项目前的存档点"

然后改掉一行文字，刷新看看是不是你以为的那个位置变了。

不对，说明你理解错了——这正是最有价值的信息。然后 git restore .（2.3）回去。

🔑 这就是 3.5 讲的「验收」能力反过来用： 验收是“AI 改了，我判断对不对”； 读项目是“我改一点，看项目的反应符不符合我的预期”。

两件事用的是同一块肌肉。

---

四、完成的标志是

• 我知道读项目不要逐行读、不要被 node_modules 吓到、不要从配置文件开始
• 我记住了五分钟流程的顺序（package.json → 跑起来 → 目录 → 两个文件 → AI 对照）
• 我知道看 lock 文件决定用哪个包管理器
• 我知道 pnpm build 的输出就是一张现成的路由表
• 我知道只需打开 layout.tsx 和 page.tsx 两个文件就能摸清骨架
• 我知道最重要的那条判断是「数据从哪来」
• 我知道 components/ 的文件名就是功能清单
• 我知道要先自己理解、再让 AI 补齐，顺序不能反
• 我存好了项目速查卡模板
• 我完成了第 4 步的计时演练，并让 AI 批改了我的速查卡
• 我找到了（或知道了）AI 故意留下的那个问题
• 我理解三条心法：跳过不懂的、问为什么存在、用改动验证理解

---

五、卡住了看这里

Q：五分钟根本不够。 第一次不够是正常的，三五个项目之后就够了。而且“五分钟”不是指搞懂所有代码——是指说清这个项目在干什么、改东西该去哪。这两件事五分钟确实够。

Q：项目跑不起来，流程走不下去。 跑不起来本身就是重要信息，不是失败。按顺序查：① 包管理器用对了吗；② Node 版本（有的项目在 package.json 的 engines 里写了要求）；③ 缺 .env.local（看项目里有没有 .env.example 这类模板文件）；④ 把完整报错给 AI。然后把这些记在速查卡的“当前状态”里。

Q：项目结构和课程里讲的完全不一样（没有 app/，有 pages/，或者是 Vue）。 正常。五分钟流程里只有第 ③ 步是 Next.js 专属的，其余四步对任何前端项目都适用。pages/ 是 Next.js 的旧路由方式（4.7 第 2 步提过），思路一样：文件即路由。换成 Vue 等其他框架，就用第 ⑤ 步让 AI 给你讲它的结构约定。

Q：代码里有很多我完全没见过的东西。 心法 ①：跳过，往下走。 真实项目里永远有你没见过的东西，连资深开发者也一样。读项目的目标是拿到地图，不是认识每一块砖。

Q：我读完了但不确定对不对，又不想让 AI 直接告诉我答案。 用心法 ③：改一个小东西验证。 比如你判断“首页标题在 app/page.tsx 第 12 行”，就去改掉它，刷新看是不是那个位置变了。这是最硬的验证。 记得先 commit。

Q：这个练习有必要反复做吗？ 有，而且成本很低（让 AI 出题，五分钟一轮）。建议在第 5 章开始前再做一轮，那时你会明显感觉比第一次快。

---

六、本节提示词

① 项目导览（4.5 提示词 ① 的升级版，这是最终形态，以后一直用这条）：

先不要修改任何文件。请用中文回答，我是零基础：

1. 这个项目是干什么的？一句话。
2. 技术栈是什么？**确切的**启动命令是什么（从 lock 文件判断包管理器，从 package.json 读 scripts，不要猜）？
3. 有哪些页面？给我一张表：网址 / 对应文件 / 这页干什么。
4. **数据从哪来**——写死在代码里 / 调第三方接口 / 自己的后端 / 数据库？具体在哪个文件？
5. components/ 里有哪些组件，各自负责什么？
6. 跑起来需要什么前置条件（环境变量、数据库、Node 版本）？缺了会怎样？
7. 这个项目**现在有没有坏的地方**，或者明显的问题？
8. 如果我想改【首页文案 / 导航栏 / 某个页面的样式】，分别该动哪个文件？

每条都基于你实际读到的内容，**不确定的明确说不确定，不要编**。
跳过 node_modules 和构建产物。

② 生成练习项目（第 4 步那条，可以反复用）：

请在当前目录生成一个完整、能跑起来的【Next.js / 你指定的技术栈】小项目，
给我做"读陌生项目"的练习。

1. 主题你定，**不要告诉我**；
2. 难度：【简单（3 页 3 组件）/ 中等（加 app/api 接口）/ 偏难（组件命名故意起得含糊）】；
3. 数据写死在代码里，不要用需要密钥的接口；
4. **故意留下 1~2 个小问题**（样式问题 / 控制台警告 / 命名混乱），不要告诉我；
5. 生成完只回复"生成好了"，不做任何说明。

我会自己读，然后把我的理解贴给你批改。

③ 批改我的理解（演练完用）：

我按五分钟流程读完了这个项目，这是我填的速查卡：
【粘贴速查卡】

请逐条批改：
1. 哪些判断正确；
2. 哪些错了或漏了，正确答案是什么，**以及我应该看哪里才能发现**；
3. 你故意留的问题我发现了吗？没发现的话它在哪、怎样才能发现；
4. 对我的读项目方法有什么具体建议（不要说"很好，继续努力"这种话）。

---

🎉 第 4 章完成

11 课时，你从“看到代码就发慌”走到了“拿到陌生项目能说清它在干什么”。

回头看这一章给了你什么——注意，没有一条是“会手写代码”：

能力	来自
判断问题在哪一层，并把话说准	4.1、4.10
看懂 HTML 结构、CSS 样式、JS 逻辑	4.2、4.3、4.4
知道项目里哪些文件能碰、哪些别动	4.5
看懂 React 组件、props、map 渲染	4.6、4.9
建页面、做详情页、让页面互相跳转	4.7、4.8
在浏览器里先试出答案，再让 AI 改	4.10
读懂任何陌生项目	4.11

这些加起来，就是 3.5 讲的“验收能力”从“看效果”升级到了“看得懂”。

接下来：第 5 章

第 5 章开始做真正的项目——成都文旅网站「遇见成都」，7 课时，做完会是一个真正上线、能发给朋友看的网站。

本章学的东西会一个一个被用上：

项目模块	用到本章的
Header 导航	HTML 结构、Flex 布局、layout.tsx
Hero 首屏	图片、文字层级、Tailwind
景点卡片 ×6	数组 + map + 组件化（4.4、4.6、4.9）
旅行路线	Grid 布局
景点详情页	动态路由（4.8）
手机端适配	响应式断点 + 设备工具栏（4.3、4.10）

🔁 进第 5 章之前，建议重读 3.5 一遍。

那一节当时让你“第一遍吸收不了很正常”——现在你有项目了，再读一遍会完全不同。 需求五要素、任务拆分、先方案后动手、四种验收，马上就要连续用七课时。

上一节 ← 4.10 浏览器开发者工具 下一章 → 5.1 项目介绍与最终效果演示