Why we specify architecture before we write code

Every system we build begins the same way: with a document, not a line of code.

Before we open an editor, we produce an architecture specification. It names every component that will exist, describes how they communicate, and makes explicit every assumption we are relying on. This document is reviewed, agreed to by the client, and preserved in version control alongside the code it describes.

This is not a formality. It is the point at which most projects go wrong.

The cost of skipping architecture

When work starts without a specification, two things happen. First, the engineer makes architectural decisions under pressure — which tables to use, which services to call, which side-effects to tolerate. These decisions are often good individually but incoherent in aggregate. Second, there is no written record of what was decided or why.

By the time problems appear — and they always do — no one can reconstruct the reasoning. The system has accumulated behaviours that cannot be changed without understanding intentions that were never written down.

What a specification forces

Writing architecture forces precision. You cannot write "it will be fast" in a specification — you must write "queries against this index should return within 200ms under 500 concurrent users." You cannot write "it should be secure" — you must write "session tokens are stored server-side, not in browser localStorage."

Precision exposes conflicts. When two requirements cannot both be true at once, that conflict is better discovered in a document than in a running system that is actively serving customers.

Architecture as a deliverable

We treat the specification document as a client deliverable — not internal documentation. The client does not need to understand every technical decision, but they benefit from knowing what was decided, why, and what they agreed to.

When something needs to change six months later, the specification is the starting point. We assess the proposed change against the original design — not against assumptions we no longer remember making.

This is how we build systems that remain legible over time.