先读懂一个既有专案

返回 Codex 教学总目录

目标与准备

开始前先完成第一个小专案。读懂专案不是把所有档案逐行翻译，而是回答「入口在哪、动作经过哪里、资料存在哪、什么证据能确认」。我们先固定一个小网站，再用同一个使用者动作追查，避免只得到一张看似完整却不能指导修改的档名清单。

步骤 1：确认版本、入口与基准

将练习 ZIP 的 expected 中五个档案复制到新的 codex-read-lab，保留原版。这次要读正确版本，不用 start 或 broken。用编辑器开根目录；PowerShell 执行 Get-Location，macOS／Linux 用 pwd，确认直接看得到 index.html、style.css、app.js、core.mjs 与 core.test.mjs。不要为了让专案看起来熟悉就先新增 package.json。

node --version
node --test core.test.mjs

教材预期三项测试通过；先记录实际结果，再请 Codex 做唯读调查。若起点失败，保留错误与版本资讯，不把不明故障夹在「理解架构」中顺手修掉。正式专案若已有未提交修改，先记录哪些是原有工作，读程式阶段不使用全目录重设或自动格式化，避免把观察变成修改。

桌面版先加入 codex-read-lab 为本机专案，再在此专案建立新任务；CLI 从刚核对过的练习终端机执行 codex。确认任务工作路径后，将下列要求送到 Codex 输入框，不是在系统终端机执行。

Read this codex-read-lab without editing any files. Identify the actual entry point, file responsibilities and commands available from the files, not from framework assumptions.
Trace adding a task, marking it complete, changing the filter and reloading the page. Name the relevant functions and DOM elements.
Separate observed code from inferred intent. List what the existing tests cover and what still needs browser verification. If evidence is missing, say so instead of inventing a backend or build step.

步骤 2：建立有证据的档案地图

预期会找到以下分工。看表时同时打开对应档案，确认不是依副档名猜测：index.html 实际载入 style.css 与模组 app.js；app.js 汇入 core.mjs 的功能。core.test.mjs 使用 Node 内建测试，不靠 npm script。本教材没有后端 API、资料库伺服器或 bundler，若回答有这些项目，请它指出证据再修正地图。

再请它对「新增 Read」列出完整顺序：表单 submit 防止预设送出，addTask 检查文字并产生新阵列，tasks 接住结果，persist 将编码后资料写入 localStorage，输入框清空，render 更新清单，最后输入框取得焦点。每个名称都能在 app.js 或 core.mjs 找到，先确认顺序与资料型态，再谈要加什么功能。

这里特别容易混淆「资料」与「画面」：filter.value 只决定 render 显示哪些任务，不应从 tasks 删除被隐藏的项目；完成勾选透过 task.id 找对任务，不依目前画面第几列猜测。若未先理解，后续修 Completed 可能误把未完成任务从储存资料删掉，测到画面变少却破坏功能。

步骤 3：追查保存与错误分支

搜寻 app.js 的 mokaair-codex-todo-v1，可看到本教材使用的 localStorage 键。启动时 decodeTasks 读取 JSON 并检查 version 与栏位；保存时 encodeTasks 包成版本文件。这代表换浏览器来源或储存被封锁会影响资料，但不是云端帐号同步。请 Codex 说明 catch 分支会如何显示暂存状态，不能只解释成功路径。

再读测试中的第三个案例，确认坏 JSON、错误版本、重复识别码及错误栏位会被拒绝。这能证明核心解码规则，但不能单靠此测试证明浏览器真的显示错误讯息、键盘焦点合理或重新整理后仍保存。把「测过资料函式」与「测过使用者操作」分开记录，会让后续测试与审查更容易判读。

步骤 4：用画面核对理解并留下地图

从 codex-read-lab 启动第一个小专案教过的 Python 伺服器：Windows 用下面第一段，macOS／Linux 用第二段，两者只选一个。浏览器开 http://127.0.0.1:4173；若埠被自己的旧练习占用，先回那个伺服器终端机停止后再启动，不能直接沿用不明资料夹的画面。另开终端机执行测试。

py -m http.server 4173 --bind 127.0.0.1

python3 -m http.server 4173 --bind 127.0.0.1

先保留仍需要的旧练习纪录，再于 About this exercise 使用 Reset practice data。选 All tasks、确认空清单后，新增 Read 与 Build，只勾选 Read。All 应显示两项，Active 只有 Build，Completed 只有 Read；切回 All 重新整理，确认资料仍在。这是核心资料与画面的串接验证，未涵盖每个错误分支。完成后只清本例资料，不清整个浏览器。

最后用编辑器另存 project-map.md，把以下地图作为骨架，填入你真正执行的测试与尚未验证的项目。这是新增说明文件，不需要修改五个原始程式。若请 Codex 写入，明确限定只能新增此文件，并要求完成后核对原始五档没有差异；前面的唯读调查要求也要明确结束，避免以为已授权任何重构。

# Small Steps project map

## Entry and runtime
index.html loads style.css and app.js as a browser module.
app.js imports core.mjs. Local HTTP preview; no dependency installation.

## Flow
submit -> addTask -> tasks -> persist -> input clear -> render -> input focus
checkbox change -> toggleTask by ID -> persist -> render with focus restoration
filter change -> render -> visibleTasks; hidden tasks stay in tasks
reload -> localStorage -> decodeTasks -> tasks -> render

## Storage
Key: mokaair-codex-todo-v1. Versioned JSON; invalid data is rejected.
Browser storage failures leave a temporary session and a visible message.

## Verification
node --test core.test.mjs: fill actual result and date.
Browser filters, reload, keyboard and storage errors: record separately.
Do not claim checks you did not perform.

## Change boundaries
Filter logic: core.mjs visibleTasks.
DOM and storage orchestration: app.js.
Layout and controls: style.css and index.html.
Unknowns and next task: fill from evidence.

读懂失败路径：每个判断都指出依据

在 app.js 找 submit 事件，再对照 core.mjs 的 addTask。只输入空白时，trim 后长度为 0，addTask 会抛出 title-length；事件的 catch 显示讯息并 return，因此这次不会执行后面的 persist、清空输入或 render。这是阅读程式得到的路径，不能填成已亲自按过按钮。以相同方法追一次 localStorage 写入失败，确认它会设 storageAvailable 为 false，后续资料仍可在这个分页暂存，却不保证重载后保留。

再检查两个容易写错的导览结论：「切换筛选会保存资料」与「三项测试通过就证明按钮正常」。前者不符 filter 的 change 只呼叫 render；后者把核心函式测试扩张为 DOM 实测。将下面段落补进 project-map.md，并把尚未实测的栏位保留 NOT RUN。若找不到所引函式，先核对是否开了 expected 副本，再修正导览，仍不更动五个程式档。

## Evidence and limits
- Blank input: core.mjs/addTask throws; app.js/submit catches and returns before persist.
- Filter change: app.js connects change to render; that handler does not persist.
- Count: app.js/render counts all tasks, not only the displayed subset.
- Storage failure: app.js/persist disables further writes after a failed setItem.
- Automated baseline: node --test core.test.mjs; record actual exit and totals.
- Browser submit/filter/reload checks: NOT RUN until performed.

常见误判、停止与验收

Codex 说需要安装套件时，要求指出哪个档案宣告相依；只列目录却不能说明资料流，就指定追查一次 submit；把测试全过等同画面全正常，就要求列出未测边界。若找不到档案先核对根目录，不在整台电脑任意搜寻。同名函式出现在其他副本时，要用实际路径辨认，避免读 expected 却把结论套到 broken。

能依地图指出新增、勾选、筛选及重新整理各经过哪个函式，并说明至少一项仍未验证的行为，才算读懂这次范围。最后在伺服器终端机 Ctrl+C 停止，保留地图并核对五档与原始 expected 一致。若意外修改，只从保留原版还原那个档案，别重设整个专案。图中 1 是基准，2 是追查，3 是用证据核对；接下来才能实作功能。

返回 Codex 教学总目录

阅读完整文字说明

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 工具
• 教程
• Codex