用 Codex 做出第一个可验收网站

这一课不讲“怎样把需求说清楚”这种空泛方法。你会亲手完成一个单页网站：把真实素材交给 Codex，让它写入文件，启动本地预览，修改一个具体问题，最后得到一份可以逐项打勾的验收结果。

你不需要会写代码。完成后，练习目录里应该有这些文件：

codex-first-site/
├── project-brief.md       # 网站要求
├── content.md             # 页面正文素材
├── acceptance.md          # 验收清单
├── index.html             # Codex 生成的页面
├── styles.css             # Codex 生成的样式
└── review.md              # Codex 生成的验收记录

1. 准备练习目录和输入文件

先下载 Codex 第一个网站练习包。解压后会得到名为 codex-first-site 的文件夹，里面有 3 份素材：

• project-brief.md
• content.md
• acceptance.md

不要先创建 index.html 和 styles.css，这两个文件要由 Codex 生成。

打开文件夹确认只有 3 个 Markdown 文件。如果系统隐藏了扩展名，要特别检查它们没有变成 project-brief.md.txt。

解压后多了一层目录怎么办

选择项目时，以能直接看到这 3 个 Markdown 文件的文件夹为准。不要选择只包含 codex-first-site 子目录的上一级文件夹。

2. 在 Codex 中把文件夹建成项目

1. 打开 Codex 桌面 App。
2. 在左侧进入 Projects（项目）。
3. 点击新建项目；如果首页显示 Open folder 或 使用现有文件夹，也可以直接点击。
4. 选择刚才的 codex-first-site 文件夹。
5. 看对话框附近显示的工作目录，末尾必须是 codex-first-site。

这里不要选择普通的临时对话。项目会持续绑定这个文件夹，后面新开对话时仍能读取同一批文件。

先做一次只读检查

把下面这段原样发送给 Codex：

请先只读检查当前项目，不要创建或修改文件。

请告诉我：
1. 当前目录里有哪些文件；
2. project-brief.md 要求制作什么页面；
3. content.md 提供了哪些可直接使用的正文；
4. acceptance.md 一共有多少项验收要求；
5. 还缺哪些交付文件。

无法从文件确认的内容请写“未提供”，不要自行补充。

这一步应该看到什么

Codex 的回答中至少要出现这 3 个输入文件，并明确缺少 index.html、styles.css 和 review.md。如果它说没有看到文件，先停下，不要继续生成页面。

最常见原因是选错了项目目录。重新点击工作目录，选择包含 3 个 Markdown 文件的那一层，而不是它的上级目录。

3. 先生成能打开的第一版

确认 Codex 已读到素材后，再发送第二段任务：

现在开始实现这个练习网站。

请严格读取 project-brief.md、content.md 和 acceptance.md，只创建：
- index.html
- styles.css

要求：
1. 使用原生 HTML 和 CSS，不安装依赖，不使用外部图片、字体或脚本；
2. 页面文字只取自 content.md，不虚构客户、价格、案例或效果；
3. 按 project-brief.md 的区块顺序实现；
4. 所有按钮都使用页面内锚点，不能出现空链接；
5. 先完成可用版本，不增加轮播、弹窗、表单提交或复杂动画；
6. 完成后列出创建的文件，并说明如何在本地预览。

发送后观察 Codex 的过程。正常情况下，它会读取 3 个素材文件，然后新增 2 个文件。任务结束时，在文件变更区应该看到：

+ index.html
+ styles.css

如果它准备安装 React、Vue、Tailwind 或其他依赖，立即让它停下。本练习的输入已经限定为原生 HTML 和 CSS，引入框架只会增加失败点。

4. 启动本地预览

继续在同一个对话里发送：

请为当前目录启动一个本地静态文件服务器。
优先使用本机已有工具，不要安装新依赖。
启动后告诉我访问地址，并保持服务器运行。

Codex 会根据电脑环境选择可用命令，常见结果之一是：

python3 -m http.server 8000

看到类似下面的信息，表示服务器已经启动：

Serving HTTP on 0.0.0.0 port 8000

打开 Codex 给出的预览地址，通常是 http://127.0.0.1:8000/ 或 http://localhost:8000/。页面至少应出现：

• “一诺 AI 工作流陪跑”主标题；
• “适合谁”“怎么进行”“开始前准备”三个内容区块；
• 页面底部的“预约一次沟通”按钮；
• 白底正文、深色标题和蓝色主按钮。

如果地址打不开，先看 Codex 的终端任务是否仍在运行。端口被占用时，让 Codex 换一个端口，例如 8001，不要反复安装服务器工具。

5. 做第一次人工检查

不要看到页面出现就算完成。先手动执行 4 个动作：

动作	应看到的结果	失败时记录什么
点击顶部“查看服务流程”	页面滚动到“怎么进行”	按钮文字、跳转后的区块
点击底部“预约一次沟通”	页面滚动到联系区	是否没有反应或跳到空白页
把窗口缩窄到手机宽度	内容变成单列，没有横向滚动	哪个标题、按钮或卡片越界
刷新页面	页面仍能正常显示	是否出现 404 或样式丢失

假设你发现手机上两个按钮挤在一行，不要只说“手机端不好看”。给 Codex 一个可复现的问题：

请只修复一个问题：页面宽度约 390px 时，首屏两个操作按钮挤在同一行，文字显示不完整。

期望结果：
- 390px 下两个按钮纵向排列并占满可用宽度；
- 按钮文字完整显示；
- 768px 及以上保持横向排列；
- 不修改正文、颜色和其他区块。

修改后说明改了 styles.css 的哪条规则。

刷新预览页，重新缩放窗口。只在问题确实消失后进入下一步。

6. 让 Codex 按清单验收

现在让 Codex 读取真正的验收文件，而不是让它自己宣布“已经完成”：

请读取 acceptance.md，对当前 index.html 和 styles.css 做交付前检查。

执行要求：
1. 能通过读取代码确认的项目，写出依据；
2. 能用本地命令检查的项目，实际运行命令；
3. 必须人工看页面才能确认的项目，标记“待人工检查”，不能猜测通过；
4. 不要为了让清单通过而修改文件；
5. 把结果写入 review.md，使用“通过 / 未通过 / 待人工检查”三种状态；
6. 最后汇总未通过项和待人工检查项。

完成后打开 review.md。一份可信的结果不会全部写“通过”，视觉层级、手机宽度和按钮点击通常需要标记为“待人工检查”，再由你填写结果。

在 review.md 末尾补上自己的检查记录，例如：

人工检查结果：
- 390px：通过，无横向滚动，按钮文字完整。
- 1440px：通过，正文未被拉成过宽长行。
- 两个页面内按钮：通过，均跳转到目标区块。

7. 最终核对文件

回到 codex-first-site 文件夹，核对 6 个文件都存在：

project-brief.md
content.md
acceptance.md
index.html
styles.css
review.md

最后再问 Codex：

请不要再修改文件。给我一份最终交付摘要：
- 输入文件
- 生成文件
- 本地预览命令和地址
- 已完成的自动检查
- 我完成的人工检查
- 仍未验证的事项

当文件齐全、预览可打开、按钮可点击、390px 没有横向滚动，并且 review.md 记录了自动检查和人工检查，这个任务才算完成。

常见失败与恢复

现象	先检查	给 Codex 的恢复指令
Codex 看不到素材	项目绑定的文件夹层级	“不要修改文件，重新列出当前工作目录和其中的文件。”
页面出现了虚构内容	是否忽略了 content.md	“删除无法在 content.md 找到依据的文字，不补充新事实。”
样式完全没加载	index.html 中 CSS 路径	“检查本地文件名和 stylesheet href 是否一致，只修复引用路径。”
预览地址打不开	服务器是否仍运行、端口是否占用	“检查静态服务器进程；若端口占用，换一个端口重新启动。”
一次改动很多地方	修改指令没有限定范围	“停止继续修改，先列出为解决当前问题真正需要改的规则。”
Codex 自称全部通过	没有区分代码检查和视觉检查	“把视觉与交互项改为待人工检查，不要根据代码推测页面效果。”

这一课真正练会了什么

你已经走完一次完整操作：选择项目目录、让 Codex 读取真实文件、生成本地网页、启动预览、描述一个可复现问题，并用独立清单完成验收。下一课再进入现有代码库，学习如何查看 diff、运行测试和控制修改范围。