先讀懂一個既有專案

返回 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