Spec First: Why Writing a Specification Before Asking AI to Implement Leads to More Consistent Results
What Happens When You Ask AI to Implement Without a Specification
“Please add a contact form to this page.” When I give AI an instruction like this without further definition, AI implements whatever it interprets a contact form to be. It decides the fields to include, what happens after submission, how errors are shown, and everything else based on its own judgment.
When the result arrives, problems like these emerge: there is no email address field, clicking submit sends the user to a thank-you page rather than displaying a confirmation on the same page, or the design does not match what I had in mind. Each revision request triggers further adjustments, and arriving at something close to the original intent takes multiple rounds of back-and-forth.
This cycle happens because the initial instruction did not define what to build.
The Spec First Approach
Spec First is the principle of writing a specification before asking AI to implement. The specification does not need to follow a formal document format. Writing three things is enough: what to build, how it should behave, and what it should not do. When these three points are established first, the understanding between me and AI is aligned before implementation begins.
When I add new features to this site, I always work through these three points before issuing an implementation request. For the contact form example, it might look like this.
## Contact Form Specification
### What to build
- A form with fields for name, email address, and message
- One submit button
### How it should behave
- After submission, display "Your message has been sent" as text on the same page
- Validation: name and email address are required; email address format is checked
### What it should not do
- No integration with external services (no post-submission processing in this implementation)
- No changes to the design (use existing styles as-is)What Changes When a Specification Exists
Understanding is aligned at the start
When I provide a specification, AI either confirms it will proceed as described or asks a clarifying question before starting. Mismatches in understanding are surfaced before implementation rather than after, which reduces the situation where “the finished result was not what I intended.”
Review has a clear standard
After implementation is complete, I only need to verify that the result matches what the specification describes. Without a specification, each review requires me to re-establish what the correct behavior should be.
Revisions stay scoped
When a revision is needed, I can refer to the specification: “I would like to change this part of the specification.” Without a specification to anchor changes, AI sometimes makes adjustments that are inconsistent with earlier decisions.
Balancing the Cost of Writing a Specification
Writing a specification takes time. Small changes—updating text, adjusting a color—do not need a specification every time.
A specification is most useful for implementation work that involves multiple components, work where AI has meaningful choices to make, and work that is likely to change after the initial implementation. I decide based on the scope and complexity of the task.
Summary
Spec First is the principle of writing a specification first to reduce the number of revisions after implementation. Three points are sufficient: what to build, how it should behave, and what it should not do. Before refining how to phrase instructions for AI, clarifying what I want to build for myself is the starting point for making AI collaboration more consistent.