"It is obvious what needs building" is the sentence that comes before many end-of-project reviews. Writing a specification before starting is not bureaucracy: it is the moment when you discover that two people, convinced they had understood, had understood different things.
A phased flow with a checkpoint for each
Phase 1, specify. You write what is being built and why. Phase 2, plan. You decide how, with which architectural choices. Phase 3, break down. You divide the work into verifiable tasks. Phase 4, build. You build one task at a time. You do not move to the next phase until the previous one has been reviewed by whoever decides.
What a specification contains
Six elements, in a few pages:
- Goal. What is being built and why, for whom, and what it means for it to have succeeded.
- Commands. The full commands with options to build, test, start: not just the names of the tools.
- Project structure. Where the code lives, where the tests, where the documentation.
- Code style. A real example is worth more than three paragraphs of description: names, formatting, conventions.
- Test strategy. Which framework, where the tests are, what coverage is expected, which levels of tests for which risks.
- Three-level boundaries. What you always do, what you ask first, what you never do.
You add the success criteria (verifiable conditions) and the open questions, until somebody closes them.
The three-level boundaries
They are the part that is most often missing and that most often saves. "Always" are the actions that are safe to take without asking (running the tests before handing over). "Ask first" are those with consequences (changing the data schema, adding a dependency). "Never" are the forbidden ones (writing secrets in the repository, touching production). A collaborator, human or agent, thus knows where they can move on their own.
A living specification
The specification is not written once and archived. When a decision changes, the document is updated; when the code diverges, you decide which of the two is right. A specification frozen on day one becomes another source of errors.
The most common excuses
| Excuse | Reality |
|---|---|
| "It's a small change" | Small changes with ambiguous requirements are the ones that come back. A short specification is enough. |
| "It's obvious what's needed" | If it is obvious, writing it costs ten minutes. If it is not, you have just found the problem. |
| "I'll start and see" | Fine for exploring, not for delivering: the exploration code gets thrown away. |
Warning signs
- Code is written with no written requirement.
- You ask "can I start?" before clarifying what "finished" means.
- You build features that appear in no specification or task list.
- Architectural decisions taken and not documented.
- Specification skipped because "it's obvious".
An example
A request: "add report export". A half-page specification asks: in which format, for whom, with which data, how soon the file must arrive, who may export. Two lines on the boundaries: always filter by the user's permissions, ask first before including personal data, never export the complete archive. The answers change the solution before there is a line of code.
When to use it
At the start of a project, a feature or a significant change when there is no specification, the requirements are ambiguous or they exist only as an idea.
This method derives from the open-source agent-skills family by Addy Osmani (MIT licence), rewritten and adapted.
This article is an OIAR skill
What you have just read is the content of a skill from the OIAR catalogue, written for people. Knowledge like this, but richer and deeper, written for the agents, drives the interviews, the analysis and the report inside the platform. Skills are used in OIAR: to try this one on a project of yours you need an account.
spec-driven-developmentA method for writing a short, living specification before building: goal, commands, structure, style, test strategy, three-level boundaries (always, ask first, never), success criteria, open questions; a phased flow of specify, plan, break down, build. Use it at the start of a project or a feature with no specification, or with ambiguous requirements.