What is a build specification?

A build specification is an approved document that says exactly what a piece of software must do, written before anyone starts building it. It covers the goal, the people who will use it, the rules it must follow, the data it keeps, the systems it connects to, and how everyone will know it works.

It is the thing a developer, a development team or an AI coding tool builds from. If a question about the software can be answered by reading the spec, nobody has to stop the build to ask it.

What goes in a build specification?

A useful build specification covers:

• The problem and the goal: what is wrong today, and what should be true once the software exists.
• Scope: what the software will do, and just as important, what it won't.
• People and roles: who uses it, what each role is allowed to do, and who makes decisions about it.
• Requirements: each thing the software must do, one per line, each with its own ID so it can be traced and tested.
• Business rules and exceptions: approval limits, deadlines, calculations, and the odd cases experienced staff handle from memory.
• Data: the information the software keeps and how the pieces relate to each other.
• Connected systems: what it reads from or sends to, such as accounting, payroll or a customer database.
• Security and access: who can see and change what.
• Acceptance criteria: how anyone can check that each requirement was built correctly.
• Decisions and open questions: what was decided, by whom and why, and anything still unresolved.
• Ownership: who will run, support, secure and eventually retire the software once it is built.
• Approval: who signed off, and when.

How is it different from a requirements document?

Many requirements documents are written once, by one person, after a series of meetings, and then filed. A build specification is meant to be built from, so it has to meet a higher bar:

• Every requirement can be tested. "Easy to use" is a wish; "a technician can check out a tool in under three taps" is a requirement.
• Every requirement traces back to a person or a decision, so anyone can answer "why is this here?"
• Contradictions are settled before the build, not discovered during it. If operations says managers can approve purchases up to one limit and finance says a lower one, the spec records which rule wins and who decided.
• The people who own the business process approve it, not just the person who wrote it.

Why does it matter more now that AI writes code?

AI coding tools build what they are told, quickly. Give one a vague idea and you get the wrong software sooner. Give it a clear, structured specification and it has what it needs to build the right thing, and a way to check its own work against the acceptance criteria.

That is why many build specifications now come in two forms: a readable document for the people who approve it, and a structured version that AI coding tools can read directly.

Who writes it, and who approves it?

The knowledge comes from the people who do the work: operations, finance, the front line, IT. Someone has to gather it, compare what different people said, and write it down. That can be a business analyst, a consultant, the developer, or a guided process. The project's sponsor approves it, and the experts confirm the parts they supplied.

When is a specification ready to build?

A good test: there are no open contradictions, every requirement can be tested, someone has agreed to own the software after it is built, and the sponsor has signed off. If any of those is missing, the build will stop to find the answer, at a much higher cost than finding it now.

Mochlion produces build specifications this way. You can read a complete sample specification for a made-up company.