# 用 Codex 完成第一个小网页（60–90 分钟）

这个工作区是一份中文待办清单练习。它只用 HTML、CSS 和 JavaScript，不安装依赖；成品不需要服务器。课程的手工验收阶段会临时启动一个只供本机预览的静态服务器，并在验收后停止。完成后，你会知道怎样把一个目标交给 Codex、怎样验证它，以及怎样把不满意的结果改回正确范围。

在线体验：[待办清单](https://codex-todo-smzdsg.pages.dev/) · [网页说明](https://codex-todo-smzdsg.pages.dev/readme.html)

## 开始前：认识桌面界面（5 分钟）

在 Codex 桌面版中，先选择或打开这个**工作区（workspace）**，再新建一个**任务（task）**。任务就是一次持续的协作对话：它知道你当前的目标，也能在获准范围内查看和修改工作区文件。

你会用到：

- **终端（terminal）**：让 Codex 或你自己运行检查命令；看不懂输出时，直接请它解释。
- **Diff（改动对比）**：显示每个文件的增删改。完成前一定要读它，而不是只看“已完成”。
- **权限（permissions）**：Codex 读写文件、联网或执行某些命令时可能请求许可。只同意你理解、且与当前小任务有关的请求；这份练习不需要联网或安装，只有阶段 3 会临时启动本机静态预览服务器。

可复制提示词：

```text
请先说明这个工作区里有哪些文件、各自用途是什么。不要修改文件、不要联网、不要启动服务器。
```

预期结果：你得到一个简短的文件地图。若结果超出范围，请说：“只回答文件地图，不要执行改动。”

## 阶段 1：先审查现状，再写计划（10 分钟）

一个能落地的提示词通常是：**目标 + 上下文 + 限制 + 完成标准**。

- 目标：用户最终能得到什么。
- 上下文：相关文件、现在的行为和已有约定。
- 限制：允许改哪里；不要添加什么；能否联网或安装依赖。
- 完成标准：看得见的行为、边界情况、要运行的检查和交付内容。

先不要让 Codex 直接动手。把需求、当前行为和可验证标准说清楚后，要求它只阅读、澄清和规划。

可复制提示词：

```text
我想加入一个学习用的新需求：不允许添加与已有事项同名的重复待办，比较时忽略输入文本首尾空格。这不是当前基线的缺陷。
请只检查 app.js 和 tests/todo.test.js，说明 addTodo 的当前行为、需要覆盖的边界情况，并给出最小的 RED→GREEN 计划和测试方案。
不要修改文件、不要运行会修改状态的命令、不要启动浏览器或服务器。
```

预期结果：当前 `addTodo` 会先去掉首尾空格、但仍允许同名事项；Codex 给出先增加失败测试、再最小修改 `app.js` 的计划，且没有改动文件。需求还模糊、要比较多个方案、或改动跨多个文件时，先用 **Plan mode**：让 Codex 写出步骤、风险和验收办法，再批准实施。只改一处文案、修一个拼写时，通常直接给出范围明确的提示即可。

## 阶段 2：先测试，后实现（15–20 分钟）

让 Codex 遵循“测试先失败，再实现”的节奏。失败不是坏事：它证明测试真的能发现缺失的行为。

先发送下面的 RED 提示词，等 Codex 展示真实失败后，再发送 GREEN 提示词。两步不要合并；这样你才能亲眼确认测试确实能抓住新需求。

### RED：只加失败测试并停下

```text
按刚才确认的计划执行 RED 阶段。这是学习用的新需求，不是现有功能缺陷。只修改 tests/todo.test.js：添加一个 addTodo 测试，已有“写学习笔记”时，addTodo(items, "  写学习笔记  ") 必须抛出“已存在”相关错误。
运行测试并展示这条新测试因当前仍允许重复项而失败的输出，然后立刻停下。不要修改 app.js、不要启动浏览器或服务器。
```

本项目的精确检查命令如下（若 `node` 不在 PATH，就使用内置 Node）：

```sh
/Users/hanzhifengyun/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node --test tests/todo.test.js
/Users/hanzhifengyun/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node --check app.js
```

预期 RED 结果：在当前成品上，新加的重复项测试会失败，因为 `addTodo` 目前允许同名事项；这正是这次练习要推动的新行为。

### GREEN：确认后再做最小实现与全量检查

```text
我已确认 RED 输出。现在只做最小 GREEN 实现：修改 app.js，让 addTodo 在去掉首尾空格后拒绝与已有事项文本相同的重复项，并给出“已存在”相关错误。不要改 UI、存储格式、样式或 README。
运行 tests/todo.test.js 的全量测试和 app.js 语法检查，报告命令、结果和改动范围。
```

预期 GREEN 结果：第一条测试命令显示 `pass` 且 `fail 0`；第二条语法检查成功时没有输出，退出码为 0。若你机器上已有 Node，也可以用 `node --test tests/todo.test.js` 和 `node --check app.js`。

## 阶段 3：手工验收页面（15 分钟）

测试覆盖数据逻辑；页面的视觉和键盘体验还应由人检查。主流程是让 Codex 在终端启动只供本机预览的静态服务器：

```sh
python3 -m http.server 8000 --bind 127.0.0.1
```

然后在浏览器打开 `http://127.0.0.1:8000/`。`127.0.0.1` 只允许这台电脑访问，不需要互联网，也不会部署网站。验收结束后，在运行服务器的终端按 Ctrl+C 停止它。若无法使用终端，双击 `index.html` 是可用的备选方式。然后按这个清单验收：

1. 初始筛选是“全部”；添加两项，按 Enter 也能添加。
2. 只输入空格时，看到简短提示，列表不增加项目。
3. 勾选一项，分别点“全部 / 未完成 / 已完成”，内容正确。
4. 删除一项、清除已完成项；未完成项和其顺序保持不变。
5. 刷新页面，项目顺序与完成状态仍在。
6. 只用 Tab、Shift+Tab、Enter 和空格完成添加、勾选、删除、筛选和清除；焦点轮廓清楚，操作后焦点没有消失。
7. 用手机窄窗口或浏览器响应式模式查看；页面不应横向滚动。

可复制提示词：

```text
我已手工检查到：[写下具体步骤和实际结果]。请只分析最可能的原因，列出最小修复方案；先不要改文件。
```

## 阶段 4：读 Diff 与做一次纠偏（10–15 分钟）

在桌面版的 Diff 视图逐个检查变更：文件是否都在任务范围内？新增逻辑是否解释得通？有没有意外的依赖、配置或大范围重写？不要因为测试通过就跳过这一步。

故意练习一次“范围明确的纠正”：

```text
只检查 app.js 中本地存储不可用时的提示。若文案不够清楚，只修改这条提示；不要改 HTML、CSS、README、测试、存储键或其他行为。完成后运行 app.js 语法检查并展示 Diff 摘要。
```

预期结果：若确实需要改文案，Codex 只触及允许的文件和那一小段文字；若检查后认为无需改动，也应明确说明。它若提议联网、安装包、启动服务或大范围改动，应拒绝或收窄权限；若确实需要特殊权限，先要求它解释“为什么需要、会影响什么”。

## 阶段 5：收尾与复盘（10 分钟）

请 Codex 跑最终检查并简洁汇报：

```text
请运行以下两条命令，不启动浏览器或服务器：
/Users/hanzhifengyun/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node --test tests/todo.test.js
/Users/hanzhifengyun/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/bin/node --check app.js
然后列出每个改动文件的用途、测试结果、仍需我手工确认的事项。不要提交 Git。
```

复盘三个问题：我给出的完成标准是否可验证？我是否真的读过 Diff？下一次我会把哪条重复规则写得更清楚？

一次性需求（本次功能、临时范围、验收内容）放在当前提示词里。长期、反复适用的工作区规则才放进 `AGENTS.md`，例如测试命令、代码风格、目录约定和“不要修改生成文件”。不要把一次性功能要求固化成长期规则。

## 万用提示词模板

```text
目标：在 [文件/功能] 中实现 [用户可见结果]。
上下文：[当前行为、相关文件、已有约定]。
限制：只改 [范围]；不要 [依赖/联网/启动服务器/改动其他文件]。
完成标准：
1. [可观察行为]
2. [边界情况]
3. 先写并运行失败的测试，再做最小实现；运行 [检查命令]。
4. 交付改动摘要、测试结果和仍需我确认的风险。
```