Writing specs that hold up when the build starts

Why we bother

Every non-trivial feature we build starts with a spec. Not a Jira ticket. Not a Figma frame with a caption. A written document that says what the feature does, what it doesn't do, and how we'll know when it's done.

We didn't always work this way. Early on, we ran with lightweight tickets and Figma files, the way a lot of studios do. It looked faster: fewer meetings, less writing, more coding. In practice, it wasn't. Same speed, more rework, because edge cases only surfaced after the engineer had built the happy path.

Writing specs is a small tax up front that pays back tenfold later. Below is the shape of one of our specs, and the parts most teams skip.

What goes in a spec

A good spec has six sections. Not five, not seven. If any of these are missing, we don't start.

1. Context

Two paragraphs answering: why are we building this? Not the JIRA title. The actual reason. What business problem does this solve? What happens if we do nothing?

You'd be surprised how often the answer to "why" only surfaces after someone tries to write it down. Half the time, writing this paragraph kills the feature before it starts — because the answer turns out to be "a stakeholder mentioned it once."

2. User story

Who is this for? What are they trying to do? What's the outcome they want? One paragraph per user type. If you have more than three user types, you probably haven't scoped the feature tightly enough.

3. Behavior

The heart of the spec. Every meaningful action, described concretely.

Not: "users can filter their orders." That's a Figma caption, not a spec.

Yes: "When a user opens the orders page, they see all their orders sorted by date descending. A filter bar at the top has three dropdowns: status (all, pending, shipped, delivered, canceled), date range (last 30 days, last 90 days, last year, custom), and value (any, over $100, over $500, over $1,000). Filters combine with AND. Selected filters persist in the URL. Sharing the URL preserves the filter state. Clearing all filters returns the default view."

That's a spec. The engineer knows exactly what to build. QA knows exactly what to test.

4. Edge cases

The section every team skips. What happens when:

• The data is empty?
• The data is very large (>10,000 records)?
• The user is offline?
• Two users edit the same record simultaneously?
• The network drops mid-request?
• The user hits back after submitting?
• The API returns a 500?
• The user is unauthenticated?
• The user is authenticated but not authorized?
• The user's session expires mid-action?

Not all of these apply to every feature. Most apply to more features than teams realize. Every one of these caught early is a bug not shipped later.

5. Non-goals

What this feature explicitly does not do. This is where scope creep dies quietly.

"Non-goals: exporting filtered results to CSV. Saving filter presets. Filtering by custom fields. Multi-user shared filters."

Written down like that, everyone agrees. Left unwritten, someone inevitably says "wait, doesn't it also…?" halfway through the build.

6. Acceptance criteria

The list of concrete things that must be true when the feature is "done." Written as checkboxes. If you can't tick every box, you're not done.

"- [ ] Filter dropdowns render correctly on mobile, tablet, and desktop. - [ ] All 4 status options work correctly. - [ ] Custom date range uses two date pickers. - [ ] Filter state persists in URL. - [ ] Empty result state shows a friendly message with a "clear filters" CTA. - [ ] Error state on API failure shows a retry button. - [ ] Loading state shown while filters recalculate."

Ship-ready when every box is ticked. Not before.

What specs are not

Specs are not the design. Figma files stand alongside; they don't replace the spec.

Specs are not architecture. How you'll build it goes in a separate technical doc if the feature warrants one. Most don't.

Specs are not immutable. Halfway through the build, we sometimes realize the spec is wrong. We update it, get sign-off from whoever owns the feature, and keep going. The spec is the source of truth — but it's a living document, not a monument.

Specs are not project plans. Timelines, dependencies, and milestones belong somewhere else. The spec answers "what are we building," not "when will it be done."

The parts most teams skip

Three sections, in our experience, are the ones that get skipped most: edge cases, non-goals, and acceptance criteria. Each corresponds to a specific failure mode.

Skipping edge cases means bugs found during QA — or worse, in production. Every hour spent thinking through edge cases up front saves five hours later.

Skipping non-goals invites scope creep. It's much easier to tell a stakeholder "that's a non-goal for this feature" than "we don't have time for that." Non-goals are the diplomatic no.

Skipping acceptance criteria invites "done-ish." The feature works in the happy path, so we ship it, and three days later somebody notices the loading state is broken. Explicit criteria mean the engineer and QA and the PM all agree what "done" looks like, before work starts.

How long a spec takes

A good spec for a two-week feature is 1–2 pages of prose. It takes 2–4 hours to write. If it takes longer, the feature is probably too big — split it.

A spec for a one-day feature is a paragraph. Half a page at most. The overhead scales with the size of the work.

If someone tells you writing specs is slow, ask when they last had to throw away code and rebuild because the spec was vague. That is slower.

What we've stopped doing

We don't rely on tickets alone. Tickets are pointers to specs, not substitutes.

We don't rely on Figma. Figma tells you what it looks like. It doesn't tell you what it does.

We don't rely on standups. Verbal alignment evaporates within a week. Written specs don't.

The rule

If it's worth building, it's worth writing down. If it's not worth writing down, it's not worth building.

That's the whole discipline. Everything else is variation on the same theme.