Understanding an existing codebase

Back to the Codex learning hub

Goal and preparation

Complete your first project. Understanding a codebase means finding its entry point, action path, storage and evidence, not translating every line. Follow one user action through a fixed small website instead of producing an impressive-looking file list that cannot guide edits.

Step 1: Verify version, entry point and baseline

Copy the five expected files from the practice ZIP into new codex-read-lab and preserve the original. Use the correct reference, not start/broken. Open the root and check Get-Location on PowerShell or pwd on macOS/Linux. It directly contains index.html, style.css, app.js, core.mjs and core.test.mjs. Do not add package.json merely to make the project look familiar.

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

Expect three passing tests; record actual results before the read-only investigation. If baseline fails, retain error and version rather than silently fixing an unknown defect during orientation. In a real project, record pre-existing uncommitted changes and avoid whole-directory resets or formatting while reading.

In desktop, add codex-read-lab as a local project and create a task there. In CLI, run codex from the verified lab terminal. Confirm the task directory, then send the prompt inside Codex, not the system shell.

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.

Step 2: Build an evidence-based file map

Check the expected responsibilities below against actual files, not extensions alone. index.html loads style.css and module app.js, which imports core.mjs. core.test.mjs uses Node's built-in tests, not an npm script. This fixture has no backend API, database server or bundler. Ask for evidence if the response invents them.

Trace adding Read completely: submit prevents default submission, addTask validates text and returns a new array, tasks receives it, persist writes encoded data to localStorage, input is cleared, render updates the list, then input receives focus. Verify names in app.js/core.mjs and the sequence and data types before proposing features.

Distinguish data from display: filter.value selects what render shows without deleting hidden tasks from tasks. Completion targets task.id, not a guessed visible row index. Otherwise, a Completed “fix” might delete unfinished records and appear visually correct while corrupting behavior.

Step 3: Trace persistence and error paths

Find mokaair-codex-todo-v1 in app.js: it is the localStorage key. Startup decodeTasks checks JSON version and fields; encodeTasks produces the stored versioned document. Browser origin and blocked storage matter; this is not cloud-account sync. Ask how catch branches report temporary state rather than explaining only success.

Read the third test for invalid JSON, version, duplicate IDs and field types. It validates core decoding, not actual browser error messages, keyboard focus or reload persistence. Record data-function tests separately from user-interaction checks so later testing and review can assess coverage.

Step 4: Verify understanding in the browser and record it

Start the familiar Python server from codex-read-lab: use the first command on Windows or the second on macOS/Linux, not both. Open http://127.0.0.1:4173. If your earlier practice server occupies the port, stop it in its terminal first rather than reusing an unknown folder's page. Run tests in another terminal.

py -m http.server 4173 --bind 127.0.0.1

python3 -m http.server 4173 --bind 127.0.0.1

Preserve any earlier practice records you need, then use Reset practice data under About this exercise. Select All tasks and confirm an empty list before adding Read/Build and completing only Read. All shows both, Active only Build, Completed only Read. Return to All and reload to verify persistence. This checks core/UI integration, not every error branch. Clear only this fixture data afterwards.

Save project-map.md in your editor using the skeleton below, filling actual tests and unchecked items. This new document needs no changes to the five original files. If asking Codex to write it, explicitly permit only that new file and require original-file comparison afterwards, ending the earlier read-only phase without authorizing refactoring.

# 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.

Trace failure paths and identify the evidence

Find the submit handler in app.js and compare it with addTask in core.mjs. Whitespace trims to length zero, so addTask throws title-length; the handler's catch displays a message and returns, skipping persist, input clearing and render for that submission. This is a code-derived path, not evidence that you clicked the button. Similarly trace a failed localStorage write: storageAvailable becomes false, allowing temporary in-tab work without promising persistence after reload.

Check two tempting but incorrect map claims: “Changing the filter saves data” and “Three passing tests prove the buttons work.” The filter's change listener only calls render, and core-function tests do not exercise the DOM. Append the section below to project-map.md, leaving unperformed checks as NOT RUN. If a cited function is missing, verify that you opened the expected copy, then correct the map while leaving the five source files unchanged.

## 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.

Common mistakes, stopping and acceptance

For package installation, ask which file declares the dependency. For a directory-only report, request one submit trace. If passing tests are equated with perfect UI, request unchecked boundaries. Verify the root before searching broadly. Distinguish same-named functions by actual path, so expected findings are not applied to broken.

Finish by tracing add, toggle, filter and reload through the map and naming at least one unverified behavior. Stop the server with Ctrl+C, retain the map and compare all five files to original expected. Restore only an accidentally edited file, not the entire project. Diagram 1 is baseline, 2 tracing, 3 evidence checks; then proceed to feature implementation.

Back to the Codex learning hub

Read the full description

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

• AI tools
• Tutorials
• Codex