Build your reading list.

You have a plan in docs/flows.md and you know how the app fits together. Now the agent starts building. By the end of this part you’ll be able to add, edit and remove books. The list won’t survive a refresh yet, and that is deliberate.

Why build in stages

It is tempting to ask for the whole app in one message. The agent will attempt it, and you’ll receive a large result containing several guesses, some wrong, tangled together. Finding the problems is slow, and fixing one may disturb another.

A stage is a piece small enough to check in a couple of minutes. After each one you look at the app, try it and respond, so a wrong turn is corrected while it is still small. The epic docs/epics/03-build.md divides this build into four stages, A to D, and the project instructions tell the agent to stop after the one you ask for. This part covers A and B.

A bounded prompt has three elements: what to build, what to leave alone and what to tell you when finished. You’ll see that pattern in every prompt below, and it works just as well for requests you write yourself.

1. Add and show books

Open your project and start the development server if it isn’t running. Asking “start the dev server and give me the URL” is enough. Then paste:

Read CLAUDE.md, docs/brief.md, docs/flows.md and docs/epics/03-build.md. Build Stage A only. Add the book form with a required title, optional author and note, and a reading status, following my Add flow. Reject an empty title with a clear message. Show added books in the list, with a helpful message when the list is empty. Keep the supplied style and Pip. Keep the books in memory only for now; do not add saving yet. When you finish, stop. Give me the local URL, tell me exactly what to try, and wait for my feedback.

The agent may ask permission to edit files or run commands. Read each request; approving edits inside your project folder is expected here.

When it stops, open the URL and follow your own Add flow from docs/flows.md, step by step:

• Add a book you know, with an author and a note. Does it appear as you expected?
• Add another with a title only. That should work, because author and note are optional.
• Submit the form with the title empty. The form should stay open and tell you why.

Now refresh the page. Your books disappear.

Nothing is broken. As Part 3 described, the list currently lives only in the page’s memory, and a refresh starts the page again from nothing. Seeing it happen makes the purpose of saving obvious, and Part 5 adds it. Building in this order also means that if saving misbehaves later, you’ll know the form itself already worked.

2. Give feedback the agent can use

Something in Stage A will probably differ from what you pictured. How you report it decides how well it gets fixed. “Make the form better” gives the agent nothing to aim for or check. Useful feedback has three parts: what you did, what you expected and what happened instead.

I added a book with only a title. I expected the card to show just the title. Instead it shows the word “undefined” where the author would be.

The agent can reproduce that, find the cause and confirm the fix. Keep this pattern to hand:

I tried [exact steps]. I expected [result], but saw [actual result]. Reproduce the problem, explain the cause briefly, then fix it without changing anything else. Tell me how to check the fix myself.

A screenshot helps when the problem is visual, and you can paste an error message exactly as it appears. After a fix, repeat your original steps yourself. The agent’s report that something is fixed is a claim; your own check is the evidence.

Preferences are valid feedback too. If you’d rather the newest book appeared at the top, say so. If you find your flow was wrong, ask the agent to update docs/flows.md first so the plan and the app stay in agreement.

3. Edit, change status and remove

When Stage A does what your flow says, ask for the next piece:

Read CLAUDE.md, docs/flows.md and docs/epics/03-build.md. Stage A is working. Build Stage B only. Let me edit a book's details and move it between Want to read, Reading and Finished. Let me remove a book, with an undo action that restores the most recently removed book with its details, in its old position. Keep keyboard use working: I should be able to move through the form with Tab, and Escape should close it without saving. Do not add saving, search or filters yet. When you finish, stop, tell me what to try and wait for my feedback.

Check it against your Edit and Remove flows:

• Correct a title and save. The card should update, and there should still be one book, not two.
• Open the edit form, change something, then press Escape. The book should be unchanged.
• Change a book’s status to Reading.
• Remove a book, then choose Undo. It should return with the same details, in the same place.

Try one action the prompt didn’t mention. Remove two books in a row, then undo: only the most recent returns, which is what the brief specifies. Exploring beyond the script is how you find what nobody planned for.

4. Save a checkpoint

Ask the agent to inspect the changes and save a Git commit called Add, edit and remove books. If a later stage goes badly, you can return to this working state, which makes it safe to keep experimenting.

FAQ

Next: Save your reading list.