Skip to content
freecode

AI coding for beginners: build a reading list

By the freecode team · Published · Updated

An AI coding agent can turn a plain-language request into files, but learning to check those files is part of learning to code. This project gives you a small, visible result: a reading list where you can add titles, mark them as read, and remove them.

You will need a browser and a coding agent. This walkthrough uses freecode in a local terminal so you can open the generated file on your computer; the brief and checks also work with other agents. For installation on an Apple silicon Mac or Windows x64, follow the getting-started guide.

freecode also offers a web workspace and desktop preview builds. You can use the same project brief there, but opening files and previews differs from the local terminal steps below.

Start with a result you can describe

Keep your first project to one page and one job. A local reading list needs no login, payment provider, server, or API key. That leaves fewer moving parts to debug.

Our working reference example shows the intended behavior. It is a reference implementation prepared for this guide, not a recorded freecode generation or a claim that every run produces the same result. You can also download its HTML to inspect the code.

1. Create a workspace

After installing freecode, open Terminal on macOS or PowerShell on Windows. Run these lines separately and complete the browser sign-in when prompted:

freecode login
mkdir reading-list
cd reading-list
freecode

Give the agent this brief:

Build a personal reading list in one self-contained index.html file.

Requirements:
- A labeled text field and Add button for a book title.
- Reject blank titles, including spaces-only input.
- Show each title with a checkbox to mark it read and a Remove button.
- Save the list in localStorage so refreshing keeps it.
- Show a useful empty state.
- Work on a phone and with only a keyboard.
- Treat titles as plain text, not HTML.
- Use no external dependencies or network requests.

Explain how to open it locally. List the files you changed and the checks you actually ran.

The brief names the behavior, storage, and constraints. It gives you something concrete to verify when the agent says it is finished.

2. Open the page and try to break it

Open the generated index.html in your browser. Check each item yourself:

  1. Add “The Left Hand of Darkness.” It should appear once and clear the input.
  2. Add a second title, mark the first one read, and refresh. Both titles and the read state should remain.
  3. Submit an empty title, then a spaces-only title. Neither should create a blank entry.
  4. Enter <b>plain text</b>. The angle brackets should remain visible; the title should not become bold.
  5. Remove one title. Only that title should disappear, including after a refresh.
  6. Use Tab, Enter, and Space to add, check, and remove an item without a mouse.
  7. Narrow your browser to a phone-sized window. Controls should remain visible and the page should not scroll sideways.

Local storage belongs to this browser, not an account. It does not sync between devices and can be cleared by the browser. Storage behavior for a directly opened file can vary; if persistence fails, ask the agent to help serve the folder locally and repeat the refresh check.

3. Report an observable failure

If a check fails, describe the steps, what happened, and what you expected. For example:

When I enter three spaces and press Add, a blank row appears. I expected no row to be added. Fix that case without changing saved titles, then tell me how you checked the fix.

Retest the failed case and one previously working case. A fix for blank input should not break saving a normal title.

4. Learn one piece of the code

Ask the agent to explain how the form submission becomes a new row and then a saved value. Open the file while reading its explanation. Look for the HTML form, the JavaScript event handler, and the storage operation.

Next, ask for one improvement: a count of unread books, an edit button, or a clear-completed action. Define what should happen before asking for the change. Keep a copy of the working file so you can recover if the next version breaks.

Before you share it

Repeat the checklist on the version you intend to share. This example stores only titles on your device; adding accounts or shared data would need a different design. For a first project, a working local page is a useful finish line.