Why we write it down before we build it

There is a faster version of this studio. A client describes what they want on a call, we open an editor, and something is on a screen by Friday. We have worked that way. It is genuinely quicker, for about three weeks.

What happens after three weeks is that nobody can say what the thing was supposed to do. The client remembers one conversation, the developer remembers another, and the code remembers neither. Every disagreement from that point on is expensive, because there is no document to be wrong.

So we write it down first, on every kind of work we take on. Three artefacts, all of them short:

a brief,
a design spec,
a list of guards.

What actually gets written

The brief

One page, answering three questions:

Who is this for, and what are they trying to do?
What would count as success, in a sentence someone outside the project could check?
What are we deliberately not building?

The last question is the one people skip, and it is the one that saves the project. A scope with no stated edges grows until the budget stops it.

The design spec

What each screen is, which states it can be in, and what a first time visitor reads first. It carries mockups you can open in a browser before a line of the real thing exists. Changing a layout there costs an hour. Changing it after the build costs a week.

The guards

This is the part clients find odd, so here is a real one, lifted from the specification for the site you are reading:

Archivo is served through next/font from the site's own origin; the response security policy keeps font-src 'self' and the built page makes no request to a font host. Fails when someone adds a Google Fonts <link> or loosens font-src.

A guard is a sentence written so that it can fail. Every one of ours finishes the words fails when someone, because a rule with no failure mode is a preference, and preferences do not survive a deadline.

We number them, and they travel into the build as the list a reviewer checks:

G7 Archivo is served through next/font from this origin.
G8 Dark mode follows the reader's system setting, from CSS alone.
G11 Exactly one authored animation on the whole site.
G13 Accessibility and best practice both score 90 or better.

Guards are not only about code. One of them governs these notes: a post is markdown, and any markup in it is published as characters rather than as elements, so writing <script> here produces the word and not a script. The build refuses a post carrying a bare tag at all, and only a quoted one, like that opening tag and its </script>, ever reaches a page.

By the time anyone reviews code, the argument about what finished means has already happened, in writing, weeks earlier.

What it costs

Two to four days at the front of a project, and a real amount of discipline afterwards, because a document nobody updates is worse than no document at all. Our rule is that the specification is amended in the same pull request as the code that contradicted it. Never afterwards. Never in a follow up that nobody opens.

For a business that has been burned by a template site, the front loaded cost is also the reassuring part. You see the screens and the scope before the build budget is spent, and if the shape is wrong it is wrong on a page you can mark up rather than in software you have already paid for.

The overhead does not follow the writing into publishing. This post is one file, and its whole header is five lines:

---
title: Why we write it down
date: 2026-09-12
description: Why we write things down.
author: Kelvin Mwega
---

Adding the next one is a pull request against that file and nothing else. No console, no database, no editor seat.

Where we have watched it fail

Once, on a project where the writing was good and nobody read it. The brief was approved, filed, and never opened again. Three months later the team was building from a memory of the meeting about the document rather than from the document.

The fix was not more writing. It was making the writing load bearing: the guards became the review checklist, so a change that ignored the specification could not merge. If nothing in your process breaks when the document is wrong, the document is decoration.

We use AI throughout this, for drafting, for review, and for the tedious parts. It has made the writing cheap enough that there is no longer an excuse to skip it. It has not changed who is accountable. One engineer signs off every line, and their name is on the merge.