# How to Write a One-Page Feature Spec Before You Build
> How to write a one-page feature spec: the problem in a user's words, appetite, non-goals, a rough flow, edge cases, a success signal and when to stop.

```yaml
url: "https://makerhunt.io/studio/how-to-write-a-one-page-feature-spec"
markdown: "https://makerhunt.io/studio/how-to-write-a-one-page-feature-spec.md"
title: How to Write a One-Page Feature Spec Before You Build
type: studio_article
category: Growth
tags: "feature spec, one-page spec, product spec template, PRD vs spec, scope creep, non-goals, Shape Up appetite, product management, makers, Growth"
featured_image: "https://txmhk1zrnc.ufs.sh/f/xSkWTCqmKWx99V3enzSYksFrxbCcIQZtwhXo1HyLjU3f6O7m"
published_at: "2026-11-03T09:54:20.089Z"
updated_at: "2026-11-03T09:54:20.664Z"
```

## About this studio article

How to write a one-page feature spec: the problem in a user's words, appetite, non-goals, a rough flow, edge cases, a success signal and when to stop.

## Article

To write a one-page feature spec, put eight short answers on a single page before you open your editor: the problem in a user's own words, who it is for, how much time you are willing to spend (your appetite), what you are deliberately not building (non-goals), a rough flow in words or boxes, the edge cases you already know about, the signal that will tell you it worked, and how you will ship it and when you will stop. Keep it to one page so it is cheap to write and cheap to throw away. For anything bigger than a day of work, an hour of writing is the cheapest protection against scope creep you will find.

This guide is for solo makers and teams of two or three who have started coding a feature from a vague idea, then lost a week to rework and the question "wait, what was this actually for?" The worked example near the end is made up. Method details come from their original sources, linked below and checked on 3 November 2026.

## Why write a page instead of a PRD or a ticket?

A ticket is too thin and a PRD is too heavy. A ticket that says "Add rescheduling" tells you nothing about why, for whom or where it ends. A full product requirements document assumes there are people to persuade and a process to feed. When you write it and build it yourself, most of that weight goes nowhere.

One page sits in the middle. It forces the decisions that usually get made by accident halfway through the build, while changing your mind is still cheap. Malte Ubl's write-up of [how design docs work at Google](https://www.industrialempathy.com/posts/design-docs-at-google/) makes the same point at a bigger scale: a 1-3 page "mini design doc" is fine for incremental improvements, and writing design docs is overhead, so you should only write one when the benefit is worth the cost. For a small team, a single page is usually where that trade comes out ahead.

## What goes on a one-page feature spec?

Eight sections, each a few lines long:

1. **Problem.** What is going wrong today, in a user's words.
2. **Who it is for.** The specific kind of user, and who it is not for.
3. **Appetite.** How much time this is worth to you, decided up front.
4. **Non-goals.** Things someone could reasonably expect that you are not doing.
5. **Rough flow.** The screens, buttons and steps, in words or fat boxes.
6. **Edge cases.** The awkward situations you can already see coming.
7. **Success signal.** What you will be able to observe in a week or two if it worked.
8. **Ship and stop.** How it goes out, and what makes you pull it or stop working on it.

If you have read Ryan Singer's [chapter on writing the pitch in Shape Up](https://basecamp.com/shapeup/1.5-chapter-06), this will look familiar. Basecamp's pitch has five ingredients: problem, appetite, solution, rabbit holes and no-gos. The one-page spec borrows that skeleton and adds what a solo maker needs because nobody else is checking: audience, success signal and rollout.

## How do you write the problem so it stays small?

Start with something a real person said or did, not with the feature name. "Students keep emailing me to move lessons, and I lose about an evening a week to it" is a problem. "Rescheduling" is a solution wearing a problem's clothes. Paste the actual message if you have it. If you cannot point to one person who had the problem, notice that before writing anything else.

Then narrow it. Shape Up warns about [grab-bags in its chapter on setting boundaries](https://basecamp.com/shapeup/1.2-chapter-03): a "redesign" or "refactoring" not driven by a single problem or use case is a grab-bag, not a project. "Improve the calendar" is a grab-bag. "Let a student move their own lesson to another open slot in the same week" is a project.

Then add one line on who it is for and one on who it is not for. Naming who is left out stops the feature from quietly growing to fit everyone.

## What is an appetite, and why set it before you design?

An appetite is the amount of time you want to spend on something, as opposed to an estimate of how long it will take. Shape Up puts it neatly: estimates start with a design and end with a number, while appetites start with a number and end with a design. The book calls this principle "fixed time, variable scope". Basecamp uses two sizes, a small batch of one or two weeks and a big batch of six weeks, for a team of one designer and one or two programmers.

Your sizes will differ, but the idea transfers. Before you sketch anything, decide what the feature is worth: two evenings, a weekend, a week. Then design something that fits that box. If the only version you can imagine takes three weeks and the feature is worth three days, the answer is a smaller version or no version, not a longer schedule.

Write it as a sentence: "This is worth four evenings. If it is not live by Friday, I stop and rethink." That does more against scope creep than any amount of discipline later.

## Why do non-goals matter more than goals?

Because goals are easy to agree with and non-goals are where the decisions live. Ubl's Google write-up describes a goals and non-goals section and makes a sharp distinction: non-goals are not negated goals like "the system shouldn't crash", but things that could reasonably be goals and are explicitly chosen not to be. Shape Up calls the same thing no-gos and suggests you [declare cases out of bounds](https://basecamp.com/shapeup/1.4-chapter-05) so the work stays well within the appetite.

Good non-goals are things a user or your future self would plausibly ask for halfway through:

- No recurring rescheduling rules in this version.
- No moving lessons across weeks.
- No teacher approval step; open slots are fair game.
- No changes to reminder emails; they simply use the new time.

Three to six lines is plenty. When a tempting idea shows up on day two, check this list first. If it is on the list, it goes in a "later" note, not into the branch.

![A top view of hand-drawn sketches with boxes, arrows and notes on paper, with a pink marker and two pens lying on top](https://images.pexels.com/photos/3782032/pexels-photo-3782032.jpeg?auto=compress&cs=tinysrgb&w=1200&h=800&fit=crop)

## How rough should the flow be?

Rough enough that you cannot get stuck on pixels. The goal is to decide which screens exist, what the user can press on each one and where each press takes them. Shape Up's [chapter on finding the elements](https://basecamp.com/shapeup/1.3-chapter-04) warns that starting with wireframes or specific layouts gets you stuck on unnecessary details, and offers two lighter tools.

### Breadboard it in words

A breadboard, borrowed from electrical engineering, uses places (screens, dialogs, menus), affordances (buttons, fields, even interface copy) and connection lines showing where each affordance takes the user. Everything is written in words. On a spec page:

- **Lesson page:** "Reschedule" button, goes to slot picker.
- **Slot picker:** list of open slots this week, "Confirm" button, goes to confirmation.
- **Confirmation:** new time, "Back to my lessons" link; teacher gets a notification.

### Use a fat marker when layout is the point

When the arrangement on screen really matters, Shape Up suggests a fat marker sketch: a sketch drawn with such broad strokes that adding detail is difficult or impossible. Photograph it and add it to the page.

## Which edge cases should you think through?

Not all of them. Spend ten minutes on these prompts and write one line for each that applies:

- **Empty:** what does the user see when there is nothing to show, such as no open slots this week?
- **Many:** what happens with 200 items instead of 5?
- **Permissions:** who is allowed to do this, and what does everyone else see?
- **Failure:** what if the save fails or two people grab the same slot at once?
- **Undo:** can the user take it back? If deleting or overwriting is involved, the MakerHunt guide to [adding undo and a trash folder](https://makerhunt.io/studio/how-to-add-undo-and-a-trash-folder-to-your-product) covers the patterns.
- **Mobile:** does the flow survive a phone screen and a thumb?
- **Existing data:** what happens to records created before this feature existed?

For each line, write the decision, not just the question: "Two students pick the same slot: first confirm wins, the second sees a clear message." Edge cases decided now cost a sentence. Edge cases found in production cost an evening.

Mark any deep unknown, a technical question you cannot answer in a minute, as a risk. Shape Up calls these rabbit holes. Answer it before you start or cut the part that depends on it.

## How will you know it worked?

Pick one signal you can observe within a week or two of shipping, and write it down before you build. One sentence, not a dashboard: "Students start moving lessons on their own, and the move-my-lesson emails slow down." Skip target percentages you have no basis for; a direction and a count you can check by hand are more honest. What matters is deciding in advance what "worked" means, so you cannot quietly redefine it later.

## How will you ship it, and when will you stop?

Write two or three lines. Does it go to everyone, to a few friendly users first, or behind a switch you can turn off? If you want the switch, the MakerHunt playbook on [shipping risky changes behind feature flags](https://makerhunt.io/studio/how-to-ship-risky-changes-behind-feature-flags) shows how.

Then the stop rule, the line most people skip. Shape Up describes a [circuit breaker](https://basecamp.com/shapeup/2.2-chapter-08): if a project does not ship within the time that was bet on it, by default it does not get an extension, and the team goes back to rethink the problem instead. Your version can be one sentence: "If it is not live by the end of the appetite, I stop, cut scope or drop it. No silent extra week." Add a kill line too: "If it causes double bookings, I turn it off the same day."

## How do you use the spec with an AI coding agent?

Paste it in. A one-page spec already says what to build, what not to build and which edge cases matter, and the non-goals list helps keep an agent from adding things you never asked for. Ask it to work on one part of the flow at a time and check the result against the edge case lines. For the wider workflow, SideHunt's guide to [using AI coding agents on a side project without the mess](https://sidehunt.io/studio/how-to-use-ai-coding-agents-on-a-side-project) covers task size, rules files and reviewing diffs.

## How do you review a spec in 15 minutes?

Send the page to one or two honest people, a user who has the problem or a maker friend, and ask three questions:

1. Is the problem real for you, and is this how you would describe it?
2. Is anything in the non-goals something you would actually miss?
3. Reading the flow, where would you get stuck?

Fifteen minutes on a call, or a few replies in a message, is enough. You are not looking for approval; you are looking for the one sentence that changes the plan while it is still cheap. Watching someone use the finished thing is a separate step for later.

## What goes at the bottom after you ship?

Five lines, written a week or two after launch, directly under the spec:

1. What shipped, compared with what the page said.
2. How long it really took, compared with the appetite.
3. What the success signal showed.
4. Which edge case surprised you.
5. What you would cut or add next time.

After a handful of features you will know whether your "two evenings" usually means three, and you can plan with that in mind.

## When should you skip the spec?

Skip it for bug fixes, copy changes, small tweaks and anything you can finish in an afternoon; a page for those is pure overhead. When the problem is truly unknown, write one line instead, "two hours to find out whether this is possible", and write the real page once you know.

## A made-up example: Metrowren adds self-service rescheduling

Metrowren is an invented product: a lesson-booking app for independent music teachers, run by a made-up solo founder called Ilka. Teachers keep asking for "a better calendar". Here is Ilka's page.

- **Problem:** "I spend an evening a week answering 'can I move Thursday?' emails," from a piano teacher. Students cannot move a lesson themselves.
- **For:** students of teachers who publish open slots. Not group classes.
- **Appetite:** four evenings. Live by Friday or stop and rethink.
- **Non-goals:** no moving across weeks, no recurring changes, no teacher approval step, no changes to reminder emails beyond using the new time.
- **Flow:** Lesson page, "Reschedule" button, slot picker for this week, confirm, confirmation screen; teacher gets a notification.
- **Edge cases:** no open slots shows a message-your-teacher note; two students on one slot, first confirm wins; lessons within 24 hours cannot move; existing bookings unchanged.
- **Success signal:** fewer move-my-lesson emails within two weeks.
- **Ship and stop:** three friendly teachers first, behind a switch; any double booking turns it off.

The non-goals took Ilka five minutes and removed the two ideas that would have doubled the work. Her after-ship note said five evenings, not four, and the surprise edge case was students in a different time zone from their teacher.

## What does weak vs better look like?

Section

Weak

Better

Problem

"Users want rescheduling."

"Students email to move lessons; one teacher loses an evening a week to it."

Appetite

"Should take a few days, hopefully."

"Worth four evenings. Live by Friday or stop."

Non-goals

"Keep it simple."

"No cross-week moves, no approval step, no recurring changes."

Edge cases

"Handle errors."

"Same slot picked twice: first confirm wins, second sees a clear message."

Success signal

"Engagement goes up."

"Fewer move-my-lesson emails within two weeks."

Ship and stop

"Release when ready."

"Three teachers first, behind a switch; off the same day if it double books."

## What traps catch small teams?

- **Writing the solution in the problem line.** If the problem section names a button, rewrite it.
- **Treating the appetite as an estimate.** When you run over, the move is to cut scope, not to quietly add a week.
- **Skipping non-goals because they feel negative.** They are the section that saves the most time.
- **Letting the page grow to five pages.** If it does not fit on one, the feature is probably two features.
- **Never looking at it again.** Keep the page open while you build.

![An open blank notebook with a pencil on a white desk, beside a laptop, a phone and a green folder](https://images.pexels.com/photos/3975575/pexels-photo-3975575.jpeg?auto=compress&cs=tinysrgb&w=1200&h=800&fit=crop)

## A copy-paste one-page spec template

Copy this into a note or the top of your issue and fill in each line in plain sentences.

Section

What to write

Prompt if you are stuck

Problem

One to three sentences, ideally a real quote.

Who said this, and what were they trying to do?

For / not for

One line each.

Who would be surprised to get this?

Appetite

A fixed amount of time and a stop date.

What is this worth, not what will it take?

Non-goals

Three to six bullets.

What will someone ask for halfway through?

Rough flow

Places, buttons, where each goes; or a fat marker photo.

Could someone else build the right screens from this?

Edge cases and risks

One decided line per case; risks marked.

Empty, many, permissions, failure, undo, mobile, existing data.

Success signal

One thing you can observe in a week or two.

What would make you say it was worth it?

Ship and stop

Who gets it first, the off switch, the kill line.

What would make you turn it off today?

After shipping (later)

Five lines: shipped, time taken, signal, surprise, next time.

How far off was the appetite?

## Feature spec FAQ

### What should a one-page spec include?

The problem in a user's words, who it is for, the appetite, non-goals, a rough flow, known edge cases, a success signal and how you will ship and stop.

### How is a spec different from a PRD?

A PRD is usually a long document written to align many people. A one-page spec is a thinking tool for the people building the feature: short, clear about what is out of scope, and cheap to throw away.

### Do solo founders need specs?

For anything bigger than a day, yes, a short one. The main reader is you, halfway through the build and tempted to add one more thing.

### How long should writing a spec take?

As a rough guide, under an hour for a feature worth a few days. If it takes much longer, the problem is not clear yet, or it is really two features.

## Write the page, then build

The page will not be perfect, and it does not need to be. It only needs to make the big decisions on purpose instead of by accident. And when the feature ships on time and does what the page said, [MakerHunt](https://makerhunt.io/) is a good place to show it to other makers.

## Links

- Article (HTML): https://makerhunt.io/studio/how-to-write-a-one-page-feature-spec
- AI-friendly Markdown: https://makerhunt.io/studio/how-to-write-a-one-page-feature-spec.md

## Explore

- [Studio index](https://makerhunt.io/studio)
- [Blog](https://makerhunt.io/blog)
- [Browse projects](https://makerhunt.io/projects)

_HTML version: https://makerhunt.io/studio/how-to-write-a-one-page-feature-spec_