‹ 返回笔记 · Back to notes

现场手记

《Codex 使用手册》· 第 11 章|接手并改好一个已有小项目

用同一个“待确认”需求在 v1.0 上得到退出 1,再做四处最小修改得到 v1.1 退出 0。

CHAPTER 11 · 公开候选

接手不是先改代码。你会先让“待确认必须独立统计和筛选”在 v1.0 上确定失败,把直接退出码写入 red.log;再只改状态列表、页面选项、统计卡和布局,得到可回退的 v1.1。

打开第 11 章练习入口。完整任务位于练习包内 tasks/chapter-11.md;网站只提供下载与阅读,不会替你执行本地文件。

1. 起点

记录页 v1.0 已通过旧检查。新需求只增加“待确认”状态,并要求它独立统计,不计入“进行中”。

先理解问题

没有 RED 的 GREEN 只能说明某段代码当前没报错,不能说明新测试抓住了需求缺口。这里用同一探针打旧版和新版,让失败原因、最小差异与回归边界都能被第三方复查。

2. 只读输入

  • checkpoints/chapter-10-v1.0/tracker-app/
  • inputs/chapter-11/change-card.md
  • 第 10 章行为基线和通过记录

建议阅读顺序

先读变更卡和第 10 章行为基线,再读探针要验证什么;只有确认“待确认不受支持”是预期失败,才打开工作副本准备修改。

3. 唯一写入位置

只修改 workbench/tracker-app/,并把证据写入 workbench/chapter-11/。checkpoint 永远只读。

写入位置是本章的安全边界。Codex 可以创建目录,但不能扩大到 inputs、checkpoint 或别章输出。

4. 本章唯一成果

交付记录页 v1.1,以及 change-card.mdred.loggreen.logregression.mdrollback.md

成果必须能打开、能回查、能由本章检查验证。只有一句“已经完成”不算交付。

5. 可复制给 Codex 的任务

先读 inputs/chapter-11/change-card.md 和第 10 章基线。不要先修改代码:先用 scripts/run-change-test.mjs 在只读 v1.0 checkpoint 上运行新需求测试,必须因不支持“待确认”而失败,并把命令、直接退出码和失败原因写入 workbench/chapter-11/red.log。`run-change-test.mjs` 是外层命令封装器;日志中的 `COMMAND` 会记录它实际调用的底层探针,所以两行命令不同是预期,不是证据错位。确认 checkpoint 哈希未变后,只在 workbench/tracker-app 修改状态集合、表单选项、筛选和统计,增加独立“待确认”计数。不要改字段或无关样式。旧版合同必须用 `node checks/chapter-10.mjs checkpoints/chapter-10-v1.0` 对只读 checkpoint 运行;不要在已经升级为 v1.1 的 workbench 上执行默认 `npm run check:10`。workbench 中的 v1.1 和四状态回归由 `npm run check:11` 验证。把 GREEN 与回归结果写入对应文件。

把代码块整段复制,不要拆掉输入范围、停止条件和检查命令。Codex 的总结不能代替产出文件。

6. 你必须亲手完成

先打开 red.log,判断它是否真的因“待确认不受支持”失败,而不是路径或语法错误。GREEN 后在页面新增一条“待确认”,确认该卡只进入待确认统计;再筛选“进行中”,确认它没有混入。

人工动作为什么不能省

你要亲手判断 red.log 是否因正确原因退出 1。GREEN 后,在 v1.1 新增“确认下一轮维护频率/待确认”,筛选待确认只见 T-004,并确认它没有混入进行中。

7. 你应该看到

  • RED 的直接退出码为 1,错误明确指向未支持的新状态。
  • v1.0 checkpoint 前后哈希一致。
  • GREEN 后有四个独立状态计数。
  • 第 10 章的新增、三种旧筛选和空标题检查仍通过。
  • node checks/chapter-10.mjs checkpoints/chapter-10-v1.0 退出 0;workbench 的 v1.1 由 check:11 退出 0 证明。

跟着做:从输入到可观察结果

1. 得到正确 RED

运行 node scripts/run-change-test.mjs --expect-red checkpoints/chapter-10-v1.0/tracker-app/app-core.mjs workbench/chapter-11/red.log。这是外层命令封装器;red.log 的 COMMAND 记录它实际调用的底层探针,两行不同是预期。

你应看到:red.log 写有 UNSUPPORTED_STATUS: 待确认 与直接退出码 1。

2. 检查最小修改

比较 v1.0 与 v1.1,只应涉及状态集合、HTML 选项和统计卡、统计布局、README。

**你应看到:**字段、数据方式和无关界面没有被重构。

3. 用同一探针变绿

阅读 green.log,并在浏览器新增待确认记录。

**你应看到:**直接退出码 0,四种状态各为 1。

4. 回归与回退

筛选待确认和进行中,运行 npm run check:11,再读 rollback.md

**你应看到:**旧三状态、自动 ID、空标题均通过,checkpoint 哈希不变。

第11章同一需求在v1.0退出1、v1.1退出0的真实日志
真实日志:同一“待确认”探针在旧版预期失败,在最小修复后的 v1.1 直接通过。
第11章记录页v1.1新增并筛选待确认T-004
真实浏览器操作:四个状态各为 1,筛选“待确认”后只显示 T-004;待确认没有并入进行中。

参考完成态:本地实跑记录

  • red.log 保留旧版直接退出码 1,没有被 GREEN 覆盖。
  • green.log 记录直接退出码 0。
  • 浏览器中四状态各为 1,筛选待确认只显示 T-004。

证据文件:completed-example/chapter-11/red.log。这些记录只证明虚构练习在本地按规则跑通,不代表网站已发布、现实用户已使用或作者已批准。

8. 三个真实坑

坑 1:没读基线就改

新测试若没有先在 v1.0 上失败,就无法证明它能抓住需求缺口。检查要求精确的 RED 原因和 checkpoint 哈希。

坑 2:顺手重构无关部分

允许差异只涉及状态集合、选项、筛选和统计。检查器会验证 checkpoint 未变和 v1.1 行为,但不会自动判断所有无关重构;你必须亲手比较文件清单与差异。字段、数据方式或大段样式一旦超出变更卡,就停止并从只读 checkpoint 重建工作副本。

坑 3:把 v1.0 检查指向 v1.1

默认 check:10 的目标是 workbench,但第 11 章完成后那里已经是四状态 v1.1,直接运行会预期退出 1。旧版合同要明确指向只读 checkpoint;旧行为在 v1.1 上是否仍成立,则由 check:11 的回归探针判断。

这三个坑都由练习材料、代码或检查实际暴露,不是提醒语。

先看信号,再做补救

**识别信号:**RED 是路径或语法错误、文件差异扩出状态相关逻辑,或旧版检查被指向 v1.1,说明测试顺序或比较对象错了。**补救动作:**保留日志,恢复工作副本到只读 v1.0;先让同一需求探针因 UNSUPPORTED_STATUS 变红,再只改状态集合、选项、筛选和统计,并人工核对差异清单。

补救后仍不能让本章检查因正确原因通过,就按第 10 节停止并回退;不要手改日志或复制参考完成态绕过。

9. 复选框验收

  • RED 在未改 checkpoint 上因正确原因出现。
  • v1.0 checkpoint 哈希未变。
  • v1.1 的待确认独立计数正确。
  • 第 10 章全部旧行为仍通过。
  • 旧版合同检查明确指向 checkpoints/chapter-10-v1.0,没有把 v1.1 的预期差异误报为回归失败。
  • npm run check:11 通过。

每一项都要靠打开文件或完成动作后再勾选;不要只凭 Codex 报告的 PASS。

10. 停止、回退与交接

RED 因路径、语法或缺文件失败时停止,不进入修改;差异超出变更卡时也停止。回退按 rollback.md 用 v1.0 checkpoint 重建工作副本。交给第 12 章的是 v1.1、RED/GREEN 和回归结论;第 12 章只读接收,不继续改记录页。

**停止条件:**RED 原因不是新需求缺失、修改扩到变更卡外、旧行为回归失败、或 checkpoint 哈希变化。

**回退动作:**移走 v1.1 工作副本,从只读 v1.0 checkpoint 重建;保留 RED/GREEN 和失败现场。

**交接文件:**v1.1、red.log、green.log、regression.md、rollback.md;第 12 章只读接收,不继续改记录页。

本页目录
  1. 1. 起点
  2. 先理解问题
  3. 2. 只读输入
  4. 建议阅读顺序
  5. 3. 唯一写入位置
  6. 4. 本章唯一成果
  7. 5. 可复制给 Codex 的任务
  8. 6. 你必须亲手完成
  9. 人工动作为什么不能省
  10. 7. 你应该看到
  11. 跟着做:从输入到可观察结果
  12. 参考完成态:本地实跑记录
  13. 8. 三个真实坑
  14. 坑 1:没读基线就改
  15. 坑 2:顺手重构无关部分
  16. 坑 3:把 v1.0 检查指向 v1.1
  17. 先看信号,再做补救
  18. 9. 复选框验收
  19. 10. 停止、回退与交接

继续读下去

这些是同一条线索附近的记录。也可以继续追问、回到目录,或从标签进入同一主题。

追问这篇 回到目录 浏览标签