A working specification answers seven questions: why the product exists (the business goal), who uses it, which scenarios it covers, what roles and permissions it has, which systems it exchanges data with, what goes into the first phase — and, as a separate list, what does NOT. You can write it in plain words: the client's job is to describe the business, not the architecture. The contractor builds the technical side on top of that, and that's exactly what they're accountable for.
Contents
Why a spec, if you can "just explain it"
The temptation to skip this stage is understandable: it all seems clear, and writing takes time. But practice is simple: until a task is written down, the client and the contractor each hold a different version of it — and the difference surfaces at acceptance, when rework costs the most.
Until a task is written down, the client and the contractor each hold a different version of it — and the difference surfaces at acceptance, when rework costs the most.
The document's second purpose is comparing proposals. Without a spec, three contractors will price three different products, and choosing on price becomes impossible: the cheapest will be whoever understood the least.
The seven blocks of a working spec
A structure that's enough for most projects:
Business goal
- What to write
- What problem the product solves and how you'll know it works (leads, hours saved, fewer errors)
Users
- What to write
- Who exactly uses it and in what context — a customer on a phone on the go and an accountant at a desk need different things
Scenarios
- What to write
- Step by step, what a person does from entry to result. The most valuable part of the document
Roles and permissions
- What to write
- Who sees and changes what — a typical source of hidden complexity
Integrations and data
- What to write
- Which systems it exchanges data with (1C, CRM, payments, Kaspi), where data comes from, where the source of truth lives
First phase
- What to write
- What must be in the first release
What's NOT included
- What to write
- An explicit list of what's postponed — the budget's and timeline's chief protector
Write in business terms, not technology
A common mistake is trying to phrase the spec in development language: "we need a microservice architecture on Kubernetes". The moment the client takes on choosing technical solutions, they take on responsibility for the consequences — and usually have no way to verify those choices.
Compare two phrasings:
An instruction in technology terms
- "Build a REST API for synchronization"
- The contractor will carry it out literally
A requirement in business terms
- "Warehouse stock must match on the website and in 1C within 15 minutes"
- An engineer derives the solution from it — and stays accountable for the result
Common mistakes
What most often breaks even a carefully written spec:
- Everything at once: a hundred features with no priorities. The estimate becomes unaffordable and the project endless.
- Vague wording: "convenient", "modern", "fast" can't be checked at acceptance. Replace with measurable: "the page loads in under two seconds".
- No "not included" list — the project's boundaries will get drawn during a dispute.
- A copied spec from someone else: it describes another business, and you'll be the one paying for it.
- No decision owner: if a department of five approves the spec with no one responsible, every iteration doubles.
- Forgotten non-functional requirements: load, availability, data-storage rules — they surface at the end, and expensively.
If there's no one to write the spec
That's normal, especially for a first product. There are three paths:
A brief with what you have
- What to do
- Bring the idea, examples of other products, a description of the process in your own words to the brief
- What you get
- A capable contractor will draw out the rest with questions
Design
- What to do
- Order design as a separate stage
- What you get
- A document, a prototype and an estimate you can take to any builder
MVP
- What to do
- Start with an MVP: narrow the task down to the core scenario, where there's little to describe
- What you get
- The details emerge from real users
At InterLAB, unpacking the task is part of the brief: come with an idea, leave with a "first phase / second phase" map and an estimate after reviewing the task. Even if you build elsewhere, the document stays with you.
