Planning & specification

What this layer solves

Without a shared picture of what “done” means, you get endless tweaks, wrong features, and confused AI assistants. Planning turns a vague idea into something you can build and test.

Two approaches: spec-driven vs vibe coding

There are two valid ways to start a project with AI, and knowing when to use each saves time.

Spec-driven development

What it is: Write a clear spec (goals, screens, data, non-goals) before touching code. Give the spec to your AI assistant as context. Build methodically.

Best for:

Anything with authentication, payments, or user data
Products you’ll maintain for more than a few weeks
Collaborative projects (even if the collaborator is an AI agent)
Anything with external dependencies (APIs, databases, third-party services)

The process:

Write the spec (see outline below)
Give it to your AI editor as project context (e.g. Cursor Rules, spec.md in the repo)
Build feature by feature, checking against the spec
Update the spec as you learn — it’s a living document, not a contract

Vibe coding

What it is: Describe what you want in natural language, let AI generate code, iterate by feel. No formal spec — just conversation and feedback loops.

Best for:

Throwaway spikes and experiments
UI exploration (“show me what this could look like”)
Personal tools where you’re the only user
Learning — seeing what AI generates teaches you patterns fast

The risk: Without a spec, scope creeps invisibly. You end up with an app that kind of works but has no clear definition of done. Fine for experiments, dangerous for products.

The practical rule

If people will depend on it (or pay for it), write a spec. If it’s just for you or it’s an experiment, vibe code it.

The MVP and north-star feature

MVP (Minimum Viable Product) — the smallest version that proves your idea works. Not the smallest version you can build — the smallest version that delivers enough value that someone would use it.

North-star feature — the one thing that makes your product worth trying. Everything else is support for this. Identify it early and protect it from scope creep.

Concept	Question to ask	Example
North star	”If the app did only ONE thing, what would it be?”	For a recipe app: “find dinner ideas from what’s in your fridge”
MVP scope	”What’s the minimum that delivers the north star?”	Search by ingredient → show matching recipes → save favorites. That’s it.
Not v1	”What can wait for v2?”	Social features, meal planning, grocery lists, custom recipes

How to capture intent

Approach	Best for	Tradeoffs
One-pager — problem, user, success metric	Solo or tiny teams	Easy to skip edge cases
User stories — “As a … I want … so that …”	Agile product teams	Needs prioritization discipline
Lightweight spec / RFC — flows, data, non-goals	Anything you’ll hand to collaborators or AI	Takes a few focused hours
design.md — visual system, components, colors	UI-heavy apps	See Frontend design for the full approach

Default for NK Wiki: a short spec — bullet goals, out of scope, acceptance checks, and rough data the app touches.

Outline: what to write before `create-next-app`

Who is the user and one primary job-to-be-done.
North-star feature — the core interaction that makes the app valuable.
Screens or flows — list them; don’t design every pixel yet.
Entities — user, post, order… what gets stored.
Non-goals — what you will not build in v1. Be explicit.
Definition of done — e.g. “deployed URL, login works, CRUD on X.”

Official & further reading

Shape Up — product shaping without infinite backlogs
Writing good prompts for AI mirrors good specs: role, constraints, success criteria (see Start here)

When to pick an alternative

Heavier PRD when compliance or many stakeholders need audit trails.
No written spec only for throwaway spikes — still jot a paragraph so future-you remembers.

Frontend design — the design.md approach and visual planning
Stacks & boilerplates — pre-configured starting points
Editor & AI — where specs meet implementation

Last reviewed: April 2026.