We write the README before we write any code. Here’s why.

What the README actually is

It's one page. Sometimes two. Written in plain English, not spec-speak. It describes the product as if it already existed and someone was explaining it to a new user.

Four sections, every time:

• What this thing is, in one paragraph
• Who uses it, and what problem it solves for them
• The three things a user can do with it
• What we’re deliberately not building in v1

That last section is the most valuable. Writing down what you're not doing is the only way to keep a team from quietly doing it anyway.

Why it works

It surfaces disagreements early. Nine times out of ten, the founder and the engineer have slightly different pictures of the product in their heads. A Figma file can hide that. A paragraph can't. If two people read the README and describe different apps, we've found the misalignment in hour one, not month three.

It forces a hierarchy. If you can't name the top three things a user can do, you don't have a product — you have a feature bucket. Every blog post about 'shipping focused MVPs' is really about this: naming the three things and cutting everything else.

It becomes the spec. By the time design starts, we're not interpreting a brief from scratch — we're illustrating a document everyone already agreed on. Figma becomes faster because the arguments already happened in the README.

What people push back on

Founders sometimes think this is a waste of the first day. It isn't — it's a replacement for the two weeks of 'discovery' most agencies would charge them for. Ninety minutes of careful writing compresses a lot of meetings.

The other pushback: 'it feels too simple to be useful.' That's the point. If your product needs a 40-page spec to be understood, your product is the problem, not the spec.

Try it on your next project

You don't need us for this. Before your next feature, write the README. One page. Share it with whoever will build it. Wait for their questions.

If their questions surprise you, that's the bug. You just found it for free.