1. Courses
  2. AI Engineering
  3. Build and Launch a Site with AI
  4. Stop 2

30 minBeginner

Building with an AI agent, one step at a time

An AI coding agent can build a working site from your words, but only if you steer it in small, checkable steps. This lesson starts a real Next.js project with the agent, gives it a briefing file, and shows the loop you will repeat for every feature.

By the end you can

  • Start a Next.js site with the agent and see it running at localhost:3000
  • Write an instructions file (CLAUDE.md or AGENTS.md) the agent reads every time
  • Give instructions with a goal, a place, a limit and a check
  • Read what the agent changed, and recover when it gets stuck

The everyday picture

Picture a new kitchen helper who is fast, keen and has never seen your stall. Say "make the whole menu" and you get twelve dishes, three of them wrong, and no idea which step went bad. Say "make the lentil soup, mild, for four, and call me before you salt it" and you can taste it and fix it.

You also pin a card on the wall: what the stall sells, where things are, what never to do. The helper reads it every morning. The AI agent is that helper, your instruction is the dish, and the card is the instructions file.

The loop: ask, plan, change, check, save

Every feature goes round the same loop. It feels slow for the first hour and saves days later.

  1. Ask for one small thing.
  2. Plan: for anything bigger than a small change, the agent first says what it will do. You read the plan and say yes or adjust it. In Claude Code, Shift+Tab switches to plan mode, where it plans without touching files.
  3. Change: it edits files and may ask to run commands. Approve each one until you trust the pattern.
  4. Check: open the site and test what you asked for, yourself.
  5. Save: make a save point in Git (lw-03), so the next step can never ruin this one.
1. Ask 2. Plan 3. Change 4. Check 5. Save you approve works? next step broken: paste the error
The build loop. A step only gets a save point after you have checked it yourself; when the check fails, the exact error goes back to the agent.

Quick check

The agent says "Done! The recipe page is ready." What do you do before the save point?

The instructions file: the agent's briefing

Agents forget between conversations. An fixes that. Claude Code reads CLAUDE.md; many other agents read AGENTS.md. Kolom has one too, and it grew with every lesson its owner learned.

Keep it short: what the site is, the tools, how to run it, and your rules. Add a rule each time the agent makes the same mistake twice. In Claude Code, the /init command drafts one for you to edit.

Quick check

Twice this week the agent installed a new package without asking. What is the lasting fix?

A good instruction, and reading what changed

A good instruction has four parts: the goal, where it goes, what not to touch, and how you will check. End with "stop after this step and list the files you changed".

Then read the change. You don't need to understand every line:

  • Look at the list of changed files. A recipe card should touch one or two files, not the sign-in page.
  • In VS Code's Source Control panel, click a file to see green (added) and red (removed) lines.
  • Ask "explain this change in plain words" about anything you don't follow.

When it goes wrong, copy the exact error from the terminal or the browser into the chat. "It's broken" gives the agent nothing to work with. If three fixes in a row fail, stop, go back to the last save point and ask for a smaller step.

One big ask Three small asks "Build recipes, offers, search" 14 files changed header broken Recipe list: 2 Recipe page: 2 Offer badge: 1 files changed per step, each checked and saved which step broke it?
The same work as one big instruction and as three small ones. Small steps change one or two files each, so a mistake is easy to find and undo.

Do it

Start the project and give the agent its briefing. Screens and commands change between versions; follow what the agent shows you.

  1. Make the folder

    Create a folder such as Documents/sites. In VS Code choose File, Open Folder and pick it. Open Terminal, New Terminal and type claude to start the agent.

  2. Ask for the project

    Send this instruction. The agent will run Next.js's own setup command and ask for permission first; read what it wants to run, then approve.

    Markdown
    Create a new Next.js project called mangrove-kitchen in this folder,
using the App Router and TypeScript, with the default settings.
Then start it and tell me which address to open.
Don't add any other packages. Explain each command before you run it.

  3. See it running

    The agent runs npm run dev. Open the address it prints in your browser. You should see the Next.js starter page.

    Output
      ▲ Next.js 16.0.1 (Turbopack)
  - Local:        http://localhost:3000
   Ready in 1.8s

    means only you can see it. Going live comes in lw-05.

  4. Write the briefing

    Ask the agent to create CLAUDE.md (or AGENTS.md) with this content, then read it and change anything that isn't true for your site.

    Markdown
    # Mangrove Kitchen
Recipes-and-offers site for Mangrove Market. Members sign in,
save favourite recipes and can get a weekly offers e-mail.

## Stack
Next.js (App Router), TypeScript, plain CSS. Supabase for data
and sign-in (later). Hosted on Vercel.

## Run
npm run dev, then open http://localhost:3000

## Rules
- Small steps. Plan first and wait for my OK if a step
  touches more than 3 files.
- After each step, list the files you changed and explain
  the change in plain words.
- Ask before installing any package.
- Never put keys or passwords in code; read them from
  environment variables. Never ask me to paste a secret key.
- Every database table gets row-level security.
- Don't change files I didn't ask about.

  5. Make the first small change

    Use the four-part shape. Check the result in the browser, then look at the changed files in Source Control.

    Markdown
    Goal: replace the starter home page with a heading
"Mangrove Kitchen" and the line "Recipes built around
this week's offers".
Where: the home page only.
Don't touch: the layout file and the global styles.
Check: I open localhost:3000 and see the heading and line.
Stop after this step and list the files you changed.

Bring it to your team

Whoever helps you build, agree on these:

  • Does every instruction say how we will check it?
  • Did anyone read the list of changed files before saving?
  • Is the instructions file up to date with the mistakes we have fixed?
  • Which commands do we let the agent run without asking, and why?

Red flags

  • "Build the whole site" as one instruction.
  • Approving every command without reading it.
  • Pasting a secret key into the chat "so the agent can set it up".

Practice

Rewrite a vague instruction

Imran's note says: "Make the site nicer and add a way to find recipes." Rewrite it as two separate agent instructions, each with the four parts and the "stop and list files" line. Then send the first one to your agent and check the result.

  • Each instruction asks for one thing only
  • Each names the goal, where it goes and what not to touch
  • Each check is something you can see in the browser
  • "Nicer" is turned into something concrete, such as a font size or spacing
Show a model answer

1. Goal: show the recipe cards in a grid, two per row on phones and three on laptops, with 16 pixels between cards. Where: the home page styles. Don't touch: the header. Check: I resize the browser and see two, then three cards per row. Stop and list the files you changed.

2. Goal: a search box above the cards that filters recipes by name as I type. Where: the home page. Don't touch: the recipe pages. Check: typing "soup" leaves only soup recipes; clearing the box shows all. Stop and list the files you changed.

Check yourself

You ask for a "Print recipe" button. The agent's list of changed files includes the sign-in page. What do you do?

The agent has tried three fixes for the same error and each one fails differently. What is the best next move?

Which line belongs in the instructions file rather than in a single instruction?

Flashcards

Open my review

Key takeaways

  • Repeat one loop for every feature: ask, plan, change, check, save.
  • An instructions file gives the agent your rules every session; add a rule whenever a mistake repeats.
  • Good instructions have a goal, a place, a limit and a check, and ask the agent to stop and list its changes.
  • Read the changed-file list, paste exact errors, and go back to a save point when the agent goes in circles.

Sources and further reading

Episode transcriptFourteen files and a missing header · about 8 minutes · tap any line to play from there
  1. NadiaImran, you once typed one instruction to an AI agent: build the recipe pages with offers and search. What happened?
  2. ImranIt changed fourteen files. The header vanished, search crashed on one recipe, and I had no idea which part broke what.
  3. NadiaThat story is today's lesson. Building with an AI agent, one step at a time.
  4. ImranSo the agent wasn't bad. My instruction was too big.
  5. NadiaMostly, yes. Let me give you a picture first.
  6. NadiaImagine a new kitchen helper. Fast, keen, and has never seen your stall. Say make the whole menu, and you get twelve dishes, three of them wrong.
  7. ImranAnd if I say make the lentil soup, mild, for four, and call me before you salt it?
  8. NadiaThen you can taste it and fix it. And you pin a card on the wall: what the stall sells, where things are, what never to do. The helper reads it every morning.
  9. ImranThe helper is the agent, the soup is one instruction, and the card is the instructions file.
  10. NadiaExactly. Let's start with the loop you'll repeat for every feature. Ask, plan, change, check, save.
  11. NadiaIf you can see your screen, the first diagram shows the five steps as a circle. If not, picture five boxes going round: ask at the top, plan on the right, change at the bottom right, check at the bottom left, save on the left.
  12. ImranWalk me round it.
  13. NadiaYou ask for one small thing. For anything bigger than a small change, the agent plans first and tells you what it will do. You read the plan and approve it or adjust it.
  14. ImranIn Claude Code there's a plan mode for that, right?
  15. NadiaYes. Shift and Tab switches to plan mode, where it plans without touching any files. Then it makes the change, and it asks before running commands. Approve each one until you trust the pattern.
  16. ImranThen I check, and then a save point.
  17. NadiaAnd the check is yours. The agent saying done is a claim, not a test. Open the page and try exactly what you asked for.
  18. ImranWhat if the check fails?
  19. NadiaThere's a dashed arrow on the diagram for that, from check back to change. You paste the exact error, and the agent tries again.
  20. ImranLet me guess a trap. I could do two features, then test both together to save time.
  21. NadiaThat's the trap. When something breaks, you can't tell which feature caused it. One step, one check, one save point.
  22. ImranNow the card on the wall. The instructions file.
  23. NadiaAgents forget between conversations. Claude Code reads a file called CLAUDE dot md at the start of every session, and many other agents read AGENTS dot md.
  24. ImranWhat goes in it?
  25. NadiaWhat the site is, the tools, how to run it, and your rules. Small steps. Plan first if a step touches more than three files. List the files you changed. Ask before installing a package. Never put keys in code. Row-level security on every table.
  26. ImranAnd Kolom has one of these?
  27. NadiaIt does, and it grew with every lesson its owner learned. That's the habit: when the agent makes the same mistake twice, add a rule.
  28. ImranSo if it installs packages without asking twice in a week, I don't keep repeating myself in every instruction.
  29. NadiaRight. One line in the file covers every future request. And in Claude Code, the init command drafts the file for you to edit.
  30. ImranOkay. What does a good single instruction look like?
  31. NadiaFour parts. The goal. Where it goes. What not to touch. And how you will check it. Then end with: stop after this step and list the files you changed.
  32. ImranAnd then I read what it changed. But I can't read code.
  33. NadiaYou don't need every line. Look at the list of changed files first. A recipe card should touch one or two files, not the sign-in page.
  34. ImranAnd if it did touch the sign-in page?
  35. NadiaAsk why, and undo that part if there's no good reason. It's the first sign of a wrong turn. In VS Code's Source Control panel you can also click a file and see added lines in green and removed lines in red.
  36. ImranAnd I can always ask, explain this change in plain words.
  37. NadiaYes. The second diagram puts your fourteen-file story side by side with the fix. On the left, one big ask, fourteen files changed, header broken. On the right, three small asks.
  38. NadiaThat's what happened next at Mangrove. Show a list of recipes from a sample file with three recipes: two files. Make each card open its own page: two files. Add an on offer this week badge: one file.
  39. ImranAbout ten minutes each, a browser check each, and a save point each.
  40. NadiaAnd one new line in the instructions file that day. Plan first, and wait for my OK, for any step that touches more than three files.
  41. ImranWhat about when the agent gets stuck?
  42. NadiaCopy the exact error from the terminal or the browser into the chat. It's broken gives the agent nothing to work with.
  43. ImranAnd if three fixes in a row fail?
  44. NadiaStop. It's going in circles. Go back to the last save point and ask for a smaller step. Begging it to try harder doesn't help.
  45. ImranOne more worry. The agent sometimes asks me for things. What if it asks for my database key so it can set things up?
  46. NadiaNever paste a secret key into the chat. You put keys into a settings file yourself, and the code reads them from there. Your rules file says so, and next lesson keeps that file out of GitHub.
  47. ImranSo what do I actually do today?
  48. NadiaMake a folder, open it in VS Code, open the terminal and start the agent. Ask it to create a Next.js project with the App Router and TypeScript, and to explain each command before running it.
  49. ImranIt runs the setup and starts the site.
  50. NadiaThen you open localhost, port three thousand, in your browser and see the starter page. Localhost means your own computer. Only you can see it until we go live.
  51. ImranThen the briefing file, and the first small change.
  52. NadiaThe heading Mangrove Kitchen on the home page, with the four parts and a browser check.
  53. ImranIf someone helps me build, what do we agree on?
  54. NadiaDoes every instruction say how we'll check it? Did someone read the changed files before saving? Is the instructions file up to date? And the red flags: build the whole site as one instruction, approving commands without reading them, and pasting a secret key into the chat.
  55. NadiaA question for you. Which belongs in the instructions file: never put keys in code, or make the offer badge orange? Take a second.
  56. ImranNever put keys in code. It applies to every change. The orange badge is a one-off task.
  57. NadiaRight.
  58. ImranMy three takeaways. One, the same loop for everything: ask, plan, change, check, save. Two, the instructions file carries my rules into every session. Three, every instruction has a goal, a place, a limit and a check.
  59. NadiaAnd the nuance: reading the changed-file list is your best early warning. It takes ten seconds and catches most wrong turns.
  60. ImranThe practice turns a vague note, make the site nicer and add a way to find recipes, into two proper instructions.
  61. NadiaNext time, those save points get a home that survives your laptop. Git and GitHub.
Finished reading?Mark it complete to fill in its stop on your course line.

Use it at work

PRD for a new feature

Problem with numbers, users, goals and non-goals, measurable metrics with a guardrail, user stories with acceptance criteria, scope, risks and launch.

Open in the Product & BA Lab
Next stopSave points with Git and GitHub
Was this lesson helpful?
Questions and discussion

Loading the discussion…