Free template
Turn an AI brief into something you can build and test
Eight parts that every AI system specification needs, two questions to ask any brief first, and a one-page summary the business owner can read and sign.
A brief is true, and not yet buildable
A typical brief reads: "An AI that summarises incoming complaints and drafts a reply. Target 40% less handling time. Escalate anything about refunds." Every word is true. None of it can be built or tested yet.
What counts as a complaint? Summarise for whom, to what length? Draft with access to which facts? And "anything about refunds" is a classification problem with its own error rate.
The specification is the step between the brief and the build. It is where most AI projects go wrong before a line of code is written.
Two questions that prevent most rework
What is the unit of work, and how does the system know one has arrived? "A complaint" is not a unit of work. A ticket, an email or a form submission is.
What does the system do when it cannot do the task? Every system meets inputs it cannot handle. "Do nothing and say so", "guess" and "pass it to a person with the context" are three different designs, with three different costs. The specification has to choose.
What a specification contains
Usually under ten pages. Its job is to be read and tested against, not to impress.
The task
One paragraph. What goes in, what comes out, for whom, and what happens with the output.
The inputs
Exactly what the system is given, from where, and what it must not see. Including the awkward cases.
The acceptable output
What good means, concretely enough to grade. The hardest part, and the one that becomes the test set.
The level and pattern
Which level of AI and which workflow pattern or agent design, with the reason.
The failure modes
How it can be wrong, what each kind of wrong does, and what it should do instead.
The limits on what it can do
What it may do alone, what needs a person, and who can stop it.
The evaluation plan
Where the first fifty real cases come from, who writes the answers, and the threshold the owner sets.
The operating plan
Cost per task, volume, speed, what is logged, who is on call, and when it is switched off.
The summary the owner signs
The template ends with a single page in the business owner's words: the brief, the specification in brief, the workflow, the tools and their limits, the data boundary, the evaluation and its threshold, the running cost, what was bought and what was built, and who is accountable.
If it cannot be written on one page, the system is not yet understood.
The owner's signature matters. It confirms that "acceptable output" is what they meant, and that the system will be judged against it. Writing it usually exposes any disagreement early, when it is cheap to fix.
Write down why, not only what
When an assistant writes much of the code, the code no longer carries the engineer's reasoning. Keep a short, numbered record of each decision a later change could quietly undo: a data boundary, a choice of code over a model, a permission. Keep it where the coding assistant will read it.
The specification is also a contract with the evaluation. Every sentence in the acceptable output becomes a check, and every failure mode becomes a test case. See the evaluation set starter.
From specification to system
ENGINEER chapter 6 goes further, with worked decisions from a real build. Or we can write the specification with you, and build to it.