Vibe coding with Claude Code course Β· Module 2: A Next.js project with Claude Code

Plan first: a mini PRD for Kraken's Call

10 min read Β·
In this lesson11

Ahoy! Kraken's Call has a hero section, a crew page and a logbook on GitHub. By the end of this location you will turn that into a landing page: a home page that tells a visitor in a few seconds what the game is and invites them aboard. But before the first order to build is given, you will draw the map.

The problem: four sections and a hundred guesses

The request "make a landing page for Kraken's Call" sounds specific, but it leaves Claude dozens of decisions. How many sections should the page have? Will the crew cards land on the home page or stay at the /crew address? What does the "Join the crew" button do? Does the footer have links? From lesson 0_4 you know that Claude fills such gaps its own way. After a quarter of an hour you get a page with animations, a newsletter sign-up form and a new npm package, and then you spend another quarter of an hour cutting out what you never asked for.

The cure is as old as sailing: before you weigh anchor, write down where you are heading, what you are not doing and how you will know the port.

A mini PRD, or SPEC.md

A PRD (Product Requirements Document) is a document of product requirements. In companies it describes what is to be built, for whom and how to tell that it is done. Ours will be mini: a single SPEC.md file in the main project folder, with five parts:

  • goal: one sentence about why the page exists;
  • audience: who will visit it and from what device;
  • page sections: what stands on the page, from top to bottom;
  • what we do not do: the limits Claude does not cross;
  • how we will check: the commands and observations that say "done".

You met the interview and SPEC.md in lesson 0_5 with a single HTML file. Here the same technique plans a real project, and the file stays in the repository as a map for the next lessons.

The request: an interview

Open the krakens-call folder in Cursor, start claude in the terminal and switch the session to Manual. The interview itself changes nothing: Claude will ask for consent only when it wants to save a file.

Request for Claude Code:

I want to turn the home page @app/page.tsx into a landing page for the
Kraken's Call game. The hero section already exists, and the crew cards
are in @app/crew/page.tsx. Interview me: ask questions one after
another, at most three at a time, until you can write a specification.
Save it in SPEC.md in five parts: goal, audience, page sections, what
we do not do, how we will check. Do not change any other files.

The request points to files with @, so Claude knows at once what already stands on deck. It also dictates the shape of the specification and closes the road to changes in the code: at this stage only the map is made.

What the interview looks like

The Claude Code documentation describes that in an interview Claude asks questions, often with multiple-choice answers, about things you have not thought through yet, including what stays out of scope. The first round might look like this:

1. Who will visit the page most often?
   a) players hearing about the game for the first time  b) current players
2. How many steps should the "How to play" section have?  a) three  b) five
3. What does the "Join the crew" button do?
   a) nothing for now  b) leads to a sign-up form

Your questions will sound different, and their number depends on how much you left unsaid. Answer briefly. When you do not know, write: "propose an answer and justify it in one sentence". The captain's advice: the most valuable answers are "we do not do that", because each of them cuts an hour of work from the future plan.

What Claude wrote: SPEC.md

When the interview ends, Claude will ask for consent to save. Open SPEC.md in Cursor. Your file will have different words but the same parts. At the top stand the goal and the audience:

# SPEC: the Kraken's Call home page

## Goal
A visitor knows within seconds what the game is and clicks "Join the crew".

## Audience
Players who land on the site for the first time, most often from a phone.

The goal is one sentence that can be checked, not "a nice page". An audience with a phone recalls the rule from lesson 1_3: the narrow screen first. Neither the goal nor the audience says anything about code yet.

Next the page sections, listed in the order in which a visitor will see them from top to bottom:

## Page sections (from the top)
1. Hero: the name of the game, one sentence of description, a "Join the crew" button.
2. Crew: three pirate cards, the same as on the /crew page.
3. How to play: three steps, each with a title and one sentence.
4. Footer: the name of the game, the year and a link to the repository on GitHub.

Every section has content and numbers: "three steps", not "a few". The note "the same as on the /crew page" tells Claude to use the existing cards, not to write new ones.

At the end stand two parts you will return to most often, because they guard the limits of the build and say when the voyage ends:

## What we do not do
- login, a database or forms;
- animations and new npm packages;
- an action for the button: for now it only looks the part;
- changes in next.config.ts, Cache Components stay off.

## How we will check
- npm run build, npm run lint and npx tsc --noEmit without errors;
- the page is readable at phone width;
- every text clearly stands out from the background.

"What we do not do" is the list against which you will compare the plan in a moment. "How we will check" gathers the checks from lessons 1_2 and 1_4 and two things that no command will judge: a narrow screen and contrast. When the file suits you, ask for a commit with a message and read the commands before you agree.

First "what", then "how"

Notice what SPEC.md does not contain: file names, components or the order of work. The specification answers the questions "what" and "what for", and the plan answers "how and in what order". You separate them on purpose. You approve the specification as the captain who knows the goal of the voyage, and the plan is laid out by Claude, who reads the code. When the plan fails, you throw out the plan and the specification stays. You will divide the plan into small steps and end each with a check: if the build falls over after step three, you know at once where to look for the culprit.

A fresh session and plan mode

The conversation from the interview is full of ideas you rejected along the way. Claude Code best practices advise starting a build from the specification in a fresh session: with a clean context and a written definition of "done". Type /clear: that command starts a new conversation, and the old one can be resumed later. Then give a request with the /plan prefix from lesson 0_4, which switches the session to plan mode:

Request for Claude Code:

/plan Based on @SPEC.md, plan the landing page in small steps: one
step is one section or one change in the files. For every step list
the files you will change and end it with npm run build. Do not plan
anything outside SPEC.md. After approval, append the plan at the end
of SPEC.md as the "Build plan" part and stop there.

The last sentence is new: a plan from a conversation vanishes after /clear, and a plan in a file survives every session. The build will start only in lesson 1_8, step by step, and today only the route map is made.

What Claude prepared: the plan

In plan mode Claude reads SPEC.md, the files of both pages and the project configuration, then shows the plan and asks what next. Your plan may have different words but a similar shape:

Build plan
1. Move the CrewRole and CrewMember types, the crew data and CrewCard
   from app/crew/page.tsx to a new file components/crew.tsx; the /crew
   page imports them from there and looks the same. npm run build.
2. app/page.tsx: the hero as the first section, below it a "Crew"
   section with CrewCard cards. npm run build.
3. app/page.tsx: a "How to play" section with three steps. npm run build.
4. app/page.tsx: a footer with the name of the game, the year and a link. npm run build.
5. app/layout.tsx: the title and description of the page, lang="en".
   npm run build and npm run lint.
No new packages and no changes in next.config.ts.

The first step creates a new file, but for a good reason: the crew cards will now be shown by two pages, and shared code should lie in one place. Every step lists its files and ends with a check. Nothing has changed on disk yet.

A correction before approval

Suppose your plan contains the step "I will install an animation library so that the cards glide onto the screen". That is a typical agent mistake: a "just in case" plan that adds things nobody asked for. Here it directly breaks the ban on new packages from SPEC.md. Choose No, keep planning and write:

Remove the step with the animation library: SPEC.md rules out new
packages. Leave the rest of the plan unchanged.

Claude will show the corrected plan, and the files still stand untouched. You can also make a small correction yourself: Ctrl+G opens the plan in the default text editor. When the plan passes the review, choose Yes, manually approve edits: approval ends plan mode, and you approve every edit yourself. Claude will ask for consent to append the plan to SPEC.md and stop there.

Captain's review

Before you approve the plan, check four things:

  1. Files: every step lists its files, and every new file has a reason.
  2. Limits: nothing outside SPEC.md: no new packages, no login, no changes in next.config.ts.
  3. A check: every step ends with npm run build.
  4. Step size: one step is one section. A step like "build the rest of the page" is a signal that the plan must be cut up.

After approval open Source Control: only SPEC.md has changed, and the diff shows the new "Build plan" part at the end of the file.

Next step

Ask for a commit with a message, for example "SPEC.md: build plan for the landing page". The map lies in the logbook. In the next lesson you will teach the ship to remember the rules of the project, and in lesson 1_8 you will start the build. In the editor below waits a ready SPEC.md with a plan and a second file with a "just in case" plan: find in it the steps that break the specification and the one that is too big.

Remember: a map drawn before the voyage costs a quarter of an hour, and wandering without it costs a whole day.

Code for this lesson: SPEC.md
# SPEC: the Kraken's Call home page

## Goal
A visitor knows within seconds what the game is and clicks "Join the crew".

## Audience
Players who land on the site for the first time, most often from a phone.

## Page sections (from the top)
1. Hero: the name of the game, one sentence of description, a "Join the crew" button.
2. Crew: three pirate cards, the same as on the /crew page.
3. How to play: three steps, each with a title and one sentence.
4. Footer: the name of the game, the year and a link to the repository on GitHub.

## What we do not do
- login, a database or forms;
- animations and new npm packages;
- an action for the button: for now it only looks the part;
- changes in next.config.ts, Cache Components stay off.

## How we will check
- npm run build, npm run lint and npx tsc --noEmit without errors;
- the page is readable at phone width;
- every text clearly stands out from the background.

## Build plan
1. Move the CrewRole and CrewMember types, the crew data and CrewCard
   from app/crew/page.tsx to a new file components/crew.tsx; the /crew
   page imports them from there and looks the same. npm run build.
2. app/page.tsx: the hero as the first section, below it a "Crew"
   section with CrewCard cards. npm run build.
3. app/page.tsx: a "How to play" section with three steps. npm run build.
4. app/page.tsx: a footer with the name of the game, the year and a link. npm run build.
5. app/layout.tsx: the title and description of the page, lang="en".
   npm run build and npm run lint.
No new packages and no changes in next.config.ts.

Spotted a mistake in this lesson?

Check yourself

Answer the questions from this lesson. Pick an answer to see right away whether it is correct.

  1. 1. Why do you write a mini PRD in SPEC.md with Claude before building the landing page?

  2. 2. Which step of the landing page plan is built best?

  3. 3. Claude's plan assumes installing an animation library, and SPEC.md rules out new packages. What do you do?

Hands-on tasks in the game

  • Vertical ordering

    Arrange the steps from a finished specification to a build plan saved in the file:

  1. QuestionQuiz: Why SPEC.md before the build
  2. QuestionQuiz: A good plan step
  3. Put in orderOrdering: From SPEC.md to a plan in the file
  4. QuestionQuiz: A library outside SPEC in the plan

Useful articles