Planning before you build with Claude Code

“Build me a personal website” leaves Claude to invent the pages, content, and design. I do not start there. I write the decisions down first, as correcting a plan is cheaper than rebuilding the first version.

Not in your head. Written down.

Write a one-page brief

I would not let Claude create files yet. Start the project, then write one short brief first.

Create _docs/requirements.md for a personal website.

Pages:
- Home: name, role, short introduction, and one main action
- About: background and what I care about
- Projects: three examples with a title and short description
- Contact: email address, without a contact form in the first version

Design:
- Dark background and light text
- Clean and simple
- No rounded cards
- Must work on a phone and desktop

Rules:
- Use HTML and CSS without a framework
- Do not invent personal facts or project results
- Do not create files until we agree on the plan

Your pages will differ, but the brief still needs two things: what version one must do, and what stays out.

If you want Claude to work from your CV or profile, paste only the parts you are comfortable sending to the service. Remove private contact details and client information first. Verify every generated claim before publishing it.

Ask Claude to interview you

For a small project, I usually write the first brief myself. When several decisions are still open, I ask Claude to interview me instead:

Interview me about this website one question at a time.
Ask about the audience, pages, content, design, constraints, and how I will check it.
When you have enough information, summarize the agreed requirements in the conversation.
Do not create or edit files yet.

The useful part is not the document format. The questions expose decisions you have not made.

Review the summary. Correct invented assumptions, remove anything outside the first version, and make each page specific enough to check.

Use references carefully

I use screenshots for specific design choices such as spacing, typography, or layout. “Make it like this” is too vague. Paste the image using the shortcut shown for your terminal, or save it in the project and reference the path.

Tell Claude which parts matter:

Use this screenshot as a reference for spacing, type scale, and the quiet color palette.
Keep the copy, branding, images, and page structure original.
Before keeping the result, list anything that still resembles the reference closely.

Claude can still follow a reference too closely. I check the text, branding, images, and layout before keeping the result.

Plan without editing

Enter Plan mode with /plan, or cycle to it with Shift+Tab in the CLI. Other Claude Code interfaces use a mode selector.

Then ask:

Read _docs/requirements.md and inspect the project.
Propose the page structure, files, design approach, and checks.
Do not edit source files.

Plan mode is for reading and proposing. It does not edit the project files. I keep Claude there until the file list, page structure, and checks match the brief. If your reply to the plan is getting long, press Ctrl+G to write it in your normal text editor instead of the terminal input.

Once the plan is agreed, approve it or leave Plan mode. Then ask Claude to save the agreed version:

Save the approved plan to _docs/plan.md.
Do not build the pages yet.

Claude Code's current permission modes vary by interface. Stay in Manual mode while learning if you want to approve each action. Shift+Tab cycles the common modes in the CLI.

If Claude starts editing before the plan is agreed, press Esc to stop it and inspect what changed. /rewind, or pressing Esc twice in supported interfaces, can restore checkpointed file edits. Checkpoints do not undo every side effect of shell commands, so check the working tree before continuing.

Save the recurring project rules

After the brief and plan are stable, create a concise CLAUDE.md:

# Portfolio website

## Project
- Four pages: Home, About, Projects, Contact
- HTML and CSS without a framework

## Design
- Dark background and light text
- No rounded cards
- Responsive from phone to desktop

## Rules
- Keep shared CSS in css/styles.css
- Do not invent personal facts or project results
- Review each page in the browser before calling it complete

I put only the recurring project rules in CLAUDE.md. It gives later sessions the same context, but it is guidance rather than enforcement. Keep it concise and update it when the project changes.

A design plugin is optional

Run /plugin, open Discover, and review the current frontend-design plugin if you want another design direction. Anthropic describes it as guidance for more distinctive frontend work.

The plugin may give you a better first proposal, but I would still keep the brief and check accessibility and the page in a browser. Plugin contents and interfaces change, so use the current installation guide instead of relying on old install counts or key-by-key screenshots.

What you should have

Before building, keep these three things:

my-portfolio/
  CLAUDE.md
  _docs/
    requirements.md
    plan.md

The requirements explain what you want. The plan explains how Claude proposes to build it. CLAUDE.md carries the recurring project rules into the next session.

Review those files once. Then build the home page first.