Planning Your App — Writing a one-page spec

Why Planning Matters

When you give Claude Code vague instructions, you get vague results. When you give it a clear spec, you get something close to what you actually want.

Ten minutes of planning saves hours of rebuilding. Before you write a single prompt, you're going to write a short, plain-language description of what you're building. This isn't a business plan — it's the context Claude needs to build the right thing.

---

The One-Page App Spec

Fill this out before you start. It can be rough. The point is to make decisions now — on paper — instead of mid-build, when changing direction is expensive.

Template: Your App Spec

## App Name
[What will you call it?]

## Problem It Solves
[In 1-2 sentences: what problem does this solve, and for whom?]

## Who Uses It
[Just you? Customers? Colleagues? What do they need?]

## Core Features (the MVP)
List only what's essential for the first working version. Be ruthless.
- Feature 1:
- Feature 2:
- Feature 3:
(Keep this to 3–5 features. You can add more later.)

## Pages / Screens
What pages will the app have? What's on each one?
- Page 1 (e.g. Home): [description]
- Page 2 (e.g. Dashboard): [description]
- Page 3 (e.g. Settings): [description]

## Data
What information needs to be stored?
- Example: User accounts (name, email, password)
- Example: Tasks (title, due date, done/not done, assigned user)

## What It Should Look Like
Describe the vibe: clean/minimal, bold/colorful, professional/friendly?
Any colors, fonts, or designs you like?

## What It Should NOT Do (Scope Guard)
List things that are tempting to add but you're deliberately leaving out:
- Not building: [Feature X]
- Not building: [Feature Y]

The Scope Guard section is the most important part. It's the list you point to when you feel the urge to add "just one more thing."

---

Example Spec: Personal Dashboard

## App Name
Focus Dashboard

## Problem It Solves
I waste time every morning figuring out what to work on. I need a single
page that shows me my priorities and lets me check things off.

## Who Uses It
Just me (for now).

## Core Features
- Daily task list: add tasks, mark as done, delete
- A "Top 3" section: my 3 most important tasks for today
- A simple note section: free-form text area for notes

## Pages / Screens
- Home (the only page): shows Top 3, task list, and notes section
- No other pages needed for now

## Data
- Tasks: title, done (true/false), date created
- Daily note: text

## What It Should Look Like
Clean and minimal. White or very light gray background. Sans-serif font.
Calm, focused feel — like Notion but simpler.

## What It Should NOT Do
- Not building: user accounts or login (just for me)
- Not building: recurring tasks or scheduling
- Not building: mobile app (web only for now)

---

Example Spec: Freelance Client Portal

## App Name
Client Hub

## Problem It Solves
My freelance clients always ask me for project status updates via email.
I want a simple portal where they can log in and see current status
without emailing me.

## Who Uses It
My freelance clients. They're non-technical. They just need to see status.

## Core Features
- Project list: show each project with current status (Active/Review/Complete)
- Project detail: description, timeline, deliverables
- Status updates: short text updates I can post to each project

## Pages / Screens
- Login page: simple email/password login
- Dashboard: list of all projects for the logged-in client
- Project page: detail view for one project with status history

## Data
- Clients: name, email, password
- Projects: name, description, status, client it belongs to
- Updates: text, date, project it belongs to

## What It Should Look Like
Clean and professional. Navy blue and white. Feels trustworthy.

## What It Should NOT Do
- Not building: payments or invoicing
- Not building: file uploads
- Not building: client messaging/chat

Notice how both specs are short. Notice how both have a clear "NOT" list. That's the discipline you're building.

---

Choosing Your Tech Stack

For this app, we're using a standard, modern stack that Claude Code knows inside out:

You don't need to understand these deeply. Just know this is the stack, and that you'll tell Claude Code to use it when you hand over your spec.

---

Scope Creep: Your Biggest Enemy

The most common reason people never finish their app: they keep adding features before finishing the ones they started.

Signs you're scope-creeping:

• "While you're at it, can you also add..."
• "Actually, wouldn't it be cool if..."
• "Let me add one more feature before I move on."

The antidote: keep a "Future Features" list. When a new idea strikes, write it down there — then keep building the core. Don't let a good idea derail a working app.

Your goal is a working app, not a feature-complete one.

---

Before You Move On

Write your app spec. Actually write it — don't just think it through in your head. The act of writing forces you to make decisions, and decisions made on paper are cheap.

If you're stuck on what to build, just build the Focus Dashboard from the example above. It's real, it's useful, and it exercises every concept in this module.

---

Summary

• A clear spec turns vague results into the app you actually wanted.
• Use the one-page template: problem, users, features, pages, data, look, and a "NOT" list.
• Keep your MVP to 3–5 features — be ruthless about what's essential.
• The Scope Guard ("what it should NOT do") protects you from scope creep.
• The stack is Next.js + Tailwind now, Supabase + Vercel later — Claude Code knows it all.
• Write the spec down before you prompt; the goal is working, not perfect.