# 第一个项目：用对话做一个番茄钟

> 从一个空文件夹开始，用四五轮对话做出能在浏览器里运行的番茄钟网页。你会练到描述需求、审阅计划、提出修改、让智能体自己验证，并学会处理第一次报错。

- 网址：https://coding.chengyu.dev/learn/start/first-project/
- 学习路径：起步：第一次让 AI 写出能跑的东西
- 预计用时：40 分钟；核实日期：2026-10-25
- 官方来源：[Best practices for Claude Code（Claude Code 官方文档）](https://code.claude.com/docs/en/best-practices)，[Quickstart（Claude Code 官方文档）](https://code.claude.com/docs/en/quickstart)，[Terminal guide for new users（Claude Code 官方文档）](https://code.claude.com/docs/en/terminal-guide)，[Permission modes（Claude Code 官方文档）](https://code.claude.com/docs/en/permission-modes)，[Interactive mode（Claude Code 官方文档）](https://code.claude.com/docs/en/interactive-mode)

## 学习目标

- 能用一段清晰的话向智能体描述需求，并要求它先给计划
- 能判断一份计划是否合理，并在动手前修正它
- 能把做出来的网页在浏览器里打开并按清单验收
- 遇到页面空白或功能异常时，知道怎么收集信息并让智能体修复

装好了工具，该做点真东西了。这一课我们做一个**番茄钟网页**：25 分钟专注、5 分钟休息，能开始、暂停、重置，时间到了提醒你。

选它有几个原因：需求你一句话就能说清；只要浏览器就能运行，不需要服务器和数据库；对错一眼能看出来；而且里面藏着几个新手一定会遇到的小坑，正好练习处理。

整个过程分成五步：建文件夹、说需求并看计划、在浏览器里验收、处理问题、小步提出修改，其中穿插着让它自己验证。每一步我都给你准备了可以直接复制的提示词。

## 第 0 步：准备一个空文件夹

在终端里（上一课教过怎么打开），创建一个文件夹并进入，然后启动 Claude Code。macOS、Linux 和 Windows PowerShell 都能这样做：

```text
$ mkdir pomodoro
$ cd pomodoro
$ claude
```

建议放在容易找到的位置，比如桌面或「文档」文件夹里，等会儿你要在文件管理器里找到它。

关于权限模式：这是你第一次让它**创建文件**，所以它会请求许可（手动模式下）。你看到 Write 或创建 index.html 这样的提示，选允许即可。如果觉得每次都问太烦，可以按 `Shift + Tab` 切到「接受编辑」模式，它会自动通过文件编辑，但命令仍会问你。我建议这一课全程保持在手动或接受编辑，看清它做的每件事。

> **把这一课当作一场练习，而不是一次出题**
>
> 智能体每次的输出都会略有不同，你的结果不会和我的一模一样，这是正常的。重点是学会**提出要求、读懂反馈、再提要求**的节奏。

## 第 1 步：说需求，但先别让它写代码

新手最常见的错误是一句「帮我做个番茄钟」就让它开工。它会默默做很多决定：用什么框架、加不加登录、界面长什么样。做出来的未必是你要的，你还得从一堆你没打算要的东西里找问题。

更好的方式：**把需求说清楚，同时明确说「先别写代码，先给计划」。** 还有个技巧：连续按 `Shift + Tab` 直到状态栏显示 plan mode，这是官方的「计划模式」，它只读不改，直到你批准计划。

**提示词 1：说需求并要求先给计划**

```text
我想做一个网页版番茄钟，放在当前这个空文件夹里。

要求：
1. 只用 HTML、CSS 和原生 JavaScript，不用任何框架，也不需要安装依赖；做完后我直接双击 index.html 就能打开使用。
2. 专注 25 分钟，休息 5 分钟，到时间后自动切换。
3. 有「开始」「暂停」「重置」三个按钮；页面中间显示大号的 mm:ss 倒计时，并标明当前是「专注」还是「休息」。
4. 时间到时有声音提醒。
5. 界面简洁，浅色背景，手机上也能正常显示。

现在先不要写任何代码。请先告诉我：
- 你打算创建哪些文件，每个文件负责什么；
- 实现思路（尤其是计时是怎么做的）；
- 有哪些地方你不确定、需要我拍板；
- 做完后，我该怎么验证每一个功能是对的。
```

它会返回一份计划，大致像这样：

```text
> （提示词 1）
⏺ 计划如下：
  文件：index.html（结构）、style.css（样式）、app.js（计时逻辑）
  计时：记录「应结束的时间点」，每 250ms 刷新一次显示剩余时间
  声音：用浏览器内置的 Web Audio 生成一声提示音，不需要音频文件
  需要你确认：
  1. 专注结束后是否自动开始休息的倒计时？
  2. 休息结束后是否自动开始下一轮专注？
  验证：按清单逐项点击；把专注时间临时改成 5 秒观察切换和声音
```

### 怎么审阅一份计划

不用看懂每个技术名词，核对这四点就够：

1. **范围**：有没有加你没要的东西（登录、数据库、统计图表）？有就让它删掉。
2. **技术栈**：和你的要求一致吗（这次是不用框架、不装依赖）？
3. **它的疑问**：它列的「需要你确认」是不是真问题？回答它，别回一句「随便」。
4. **验证方式**：它有没有说清楚怎么验证？没有的话，要求补上。

对上面这份计划，我会这样回复：

**提示词 2：回答疑问并批准动手**

```text
计划没问题，回答你的疑问：
1. 专注结束后自动进入休息，但不要自动开始计时，等我点「开始」；
2. 休息结束后同理，回到专注并停在 25:00，等我点「开始」。

另外补充两条：
- 页面的标题栏（浏览器标签页）要显示剩余时间，例如「24:31 专注」，这样我切到别的标签也能看到；
- 把专注和休息的时长作为 app.js 顶部的两个常量，方便我以后修改。

请开始实现。做完后：
1. 检查三个文件之间的引用是否正确（HTML 里引用 style.css 和 app.js 的路径）；
2. 如果你能在这台电脑上运行 JavaScript（例如已安装 Node.js），把倒计时的计算逻辑单独抽成一个函数，写一个小脚本验证它的结果；如果不能，就给我一份手动验收清单。
3. 最后告诉我怎么在浏览器里打开它。
```

注意最后那一段：**我们要求它自己验证。** 这是和智能体协作的核心习惯，第 5 课会专门讲。

## 第 2 步：在浏览器里打开

它做完后，打开方式有三种，选最顺手的：

- 在文件管理器里找到 pomodoro 文件夹，**双击 index.html**；
- 或者让它帮你打开：对它说「帮我在浏览器里打开 index.html」，它会执行对应系统的打开命令（macOS 是 `open`，Windows 是 `start`，Linux 是 `xdg-open`），可能会再次请求你的许可；
- 把文件拖进浏览器窗口。

### 验收清单

别只看一眼「有个数字在走」就算通过。按下面这张表逐项点一遍：

| 检查项 | 预期 |
|---|---|
| 初始状态 | 显示 25:00 和「专注」，计时没有开始 |
| 点「开始」 | 数字每秒减一，浏览器标签页标题同步变化 |
| 点「暂停」 | 数字停住；再点「开始」从停住处继续 |
| 点「重置」 | 回到当前阶段的初始时间 |
| 时间到 | 响一声，切换到下一阶段并停在初始值 |
| 缩小浏览器窗口 | 界面不错位，按钮可点 |

时间到这一项不可能真等 25 分钟。让它帮你**临时把时长改短**来测试：

**提示词 3：为测试临时缩短时长**

```text
为了方便我测试，请把专注时长临时改成 5 秒，休息时长改成 3 秒，我测完会让你改回来。改完告诉我具体改了哪几行。
```

测完别忘了让它改回 25 和 5。这个「临时改值再还原」的动作，也是一种验证手段。

## 第 3 步：出问题怎么办

多半会遇到下面这些情形，解法都很机械。

**页面一片空白，或按钮点了没反应。** 打开浏览器的开发者工具：在 Chrome 或 Edge 里按 `F12`（macOS 上是 `Option + Command + I`），切到 Console（控制台）标签，红色文字就是报错。把它**原样复制**给智能体：

**提示词 4：把报错交给智能体**

```text
我在浏览器里打开 index.html，点「开始」没有反应。按 F12 打开控制台，里面有这条报错：

（把红色报错原文粘贴在这里）

请先说明原因，再修复，修复后告诉我你是怎么确认问题已解决的。
```

**声音不响。** 浏览器要求用户先和页面互动（比如点过按钮），才允许播放声音。如果你点过「开始」声音仍不响，检查电脑是否静音，再把现象告诉它。

**切到别的标签页再回来，倒计时不准了。** 这是一个经典问题：浏览器会降低后台标签页里定时器的触发频率。如果代码是「每秒减一」，切走后就会变慢。可靠的做法是记录「应该结束的时间点」，每次刷新时用它减去当前时间。我们在第 1 步的计划里已经看到它这样设计，如果你的版本不是这样，就是一个很好的修改要求：

**提示词 5：修一个计时不准的问题**

```text
我发现一个问题：点「开始」后切换到别的标签页待一两分钟再回来，倒计时比实际时间慢了。

请检查 app.js 里的计时实现是不是依赖「每秒减一」。如果是，请改为：开始计时时记录结束时间点，每次刷新用「结束时间点减去当前时间」计算剩余秒数，暂停时保存剩余秒数。

只改计时相关的代码，不要改界面。改完告诉我怎么验证：我想要一个不用等很久的验证办法。
```

**中文显示成乱码。** 让它检查 index.html 开头有没有声明 UTF-8 编码。

## 第 4 步：小步提出修改

做完基础版，试着再加一两个功能，**一次只提一个**：

- 「加一个设置区，可以修改专注和休息的分钟数」；
- 「完成一个专注就累计一个番茄，在页面上显示今天完成了几个」；
- 「用更醒目的颜色区分专注和休息」。

每提一个，都做三件事：看它说改了什么、在浏览器里点一遍、确认没把已有功能弄坏。如果它改坏了，别急着在原地反复修补：按 `Esc` 打断，连按两次 `Esc` 或输入 `/rewind` 就能把代码退回去（细节见第 6 课）。

## 本课学到了什么

回头看这几步，你其实练了四个动作：

1. **说清要求**：目标、限制、怎样算完成（第 5 课系统讲）；
2. **审阅计划**：在花钱花时间写代码之前，先把方向对齐；
3. **带证据地验收**：自己点一遍清单，让它也拿出验证；
4. **出错就收集信息再交回去**：别只说「坏了」，要给报错、现象、你做了什么。

现在你的文件夹里有三个文件。下一步先别急着继续加功能，在第 6 课里我们会给它加上 git，让你每一步都有存档。

> 小测：下面哪种开场方式最能避免「做出来的不是我要的」？

> 小测：你切到别的标签页再回来，发现番茄钟的倒计时明显比实际慢。最合理的处理是？

## 动手试一试

- [ ] 新建 pomodoro 文件夹，在里面启动 claude
- [ ] 发送提示词 1，读懂它的计划并找出至少一处你想调整的地方
- [ ] 批准实现后，在浏览器里打开 index.html，按验收清单逐项检查
- [ ] 把专注时长临时改成 5 秒，亲耳听到提示音，再让它改回 25 分钟
- [ ] 故意制造一次问题（例如让它删掉某个按钮的点击代码），打开 F12 控制台读报错，再让它修好
- [ ] 再提一个小功能（例如统计今天完成的番茄数），确认旧功能没被弄坏
- [ ] 把你的文件夹留着，第 6 课会用它来练习 git