Sitting down in front of a blank page to write a product spec can feel overwhelming. You don't know where to start, and as you write, you keep discovering things you missed.
But a shift in perspective makes it much easier. A good spec comes from a template that's easy to fill in, not from great writing skills. And the quality of AI output depends more on template quality than on your prompts.
The Template Is What Matters#
If you just tell an AI "write me a spec," you'll get something plausible but useless. But if you fill in the necessary information based on your team's template and hand that over, the AI produces a genuinely usable draft within that structure.
So your job isn't to become a better writer — it's to build a frame you only need to fill in.
The Workflow#
The whole flow has three stages: input → AI draft → review and issue creation.
1) Input Stage#
Write down the features you want as user stories, then structure them from large units down to small ones.
- Write user stories — describe the features you want from the user's perspective
- Define domains — divide features into their areas
- List pages — enumerate the pages each domain needs
- List components per page — break each page into its building blocks
- Detail features, states, and edge cases per component — go down to the smallest unit
Since the structure flows from domain → page → component → component behavior, filling it in from the top naturally reveals what's missing.
2) AI Draft Generation#
Hand the AI what you organized in the input stage, along with your template. The AI plays three roles here:
- Auto-writing the document based on the template
- Automatically checking for missing items
- Suggesting implementation priorities
3) Review and Issue Creation#
Don't ship the AI draft as-is. A human review step covering business, UX, and technical risks is essential.
Once the review is done, create issues at every level from domain down to feature, and connect them to your sprint board. Your spec turns directly into an actionable task list.
What Your Template Must Include#
I said template quality is the key, right? Make sure these items never get left out:
- Problem definition
- User stories
- Acceptance criteria (AC)
- Edge and failure cases
- Screen structure
- Data structure
- Events and state changes
- Success metrics
Edge cases and success metrics in particular tend to get dropped during planning — bake them into the template and the AI will check for their absence on your behalf.
Any Tool Works#
For writing, VSCode is fine, and terminal- or chat-based workflows work too. Two things matter more than the tool:
- Keep a single format that every collaborator can access
- Keep the output under Git-based version control
Version-control your specs like code, and you get change history plus natural code-review-style feedback.
Wrapping Up#
Instead of struggling to write the perfect spec, start by polishing one team template. Once the frame improves, AI helps with the filling-in, and you get to focus on review and judgment.
Sooner or later, those who win are those who think they can.
— Richard Bach
