Why We Specify Before We Build

There is a persistent myth in software development that writing code is the productive part and everything else is overhead. Planning, specification, review — these are seen as slowing down delivery. The reality is the opposite. Code written without proper specification is the most expensive code you will ever produce, because the cost of fixing a design error in production is orders of magnitude higher than the cost of identifying it in a specification.

Our specification process starts with the business requirement. What problem are we solving? Who are we solving it for? What does success look like? These questions seem obvious, but they are frequently skipped or answered vaguely. A clear, concise statement of the requirement — not a feature description but a problem description — is the foundation of everything that follows.

From the requirement, we derive the data model. What entities exist? How are they related? What constraints govern them? What states can they be in? The data model is the single most important design artefact. If the data model is wrong, everything built on top of it will be wrong. Getting the data model right is worth whatever time it takes.

Next, we specify the logic. For every operation — create, read, update, delete, calculate, submit — we define the exact sequence of steps, the validation rules, the error conditions, and the expected outcomes. For financial calculations, this includes complete test cases with known inputs and expected outputs. There is no ambiguity. The specification tells a developer exactly what to build and a tester exactly what to verify.

API design follows the logic specification. Every endpoint is defined with its method, path, request schema, response schema, authentication requirements, and error responses. This allows frontend and backend development to proceed in parallel — the frontend team builds against the API specification while the backend team implements it.

Integration specifications cover every interaction with external systems. For Accounted, this includes the HMRC MTD APIs, bank data providers, payment processors, and email services. Each integration is specified completely — authentication flows, data formats, error handling, retry logic, and fallback behaviour. When an external API changes, the impact assessment starts with the specification, not a debugging session.

The specification review is the most valuable step. Every specification is reviewed by at least one person who was not involved in writing it. The reviewer checks for completeness, consistency, and correctness. They ask the questions that the author did not think of. They identify edge cases that are not covered. This review catches design errors that would otherwise become bugs in production.

Does this process slow down delivery? Measured from start to finish, no. The specification typically takes 20% of the total project time. But it eliminates the rework cycles that, in specification-free development, typically consume 40% or more of the total effort. The net result is faster delivery, higher quality, and a codebase that is maintainable rather than fragile.

The specification also enables AI-assisted development. When we use AI to accelerate coding, the specification provides the governance. AI generates code against a clear contract. The specification defines what is correct. Human review verifies that the generated code meets the specification. This is how AI becomes a productivity multiplier rather than a quality risk.

Every product at neart.ai is built this way. It is slower to start and faster to finish. It produces systems that work correctly the first time. And it creates a knowledge base that makes future development, maintenance, and onboarding straightforward. Specification is not overhead — it is the work.