Three weeks ago I was staring at a Notion page at half ten at night. A client had sent a brief for a custom booking platform. The brief was four bullet points and an emoji. Literally just: "like Calendly but for dog groomers 🐶". That was it. No user flows. No edge cases. No idea whether they wanted a SaaS or a one-tenant install. And they needed a spec by Friday.
I used to dread those moments. Now I almost look forward to them.
Because I've built a workflow around Claude that turns that kind of chaos into a structured, defensible spec inside a couple of hours. I've refined it across maybe 40-odd projects at Seahawk over the last year and a half, and it's saved me from at least three "but I thought it would do X" rewrites that would have cost real money.
Let me walk you through it properly.
---
Why a Vague Brief Is Actually a Good Starting Point
Here's the thing about vague briefs: they contain signal. The dog groomer Calendly thing tells you industry, comparison product, and implied scale (small business, not enterprise). That's not nothing.
The mistake I used to make was immediately trying to flesh out the brief myself. I'd make assumptions, bake them into a doc, and then a client would sign off on something that was 40% my guesses. That's a disaster waiting to happen.
Claude doesn't have that problem. It asks. Or rather, when you prompt it correctly, it generates the questions you should have been asking.
My first move on any new project is to paste the raw brief into Claude and ask it to identify every assumption I'd have to make in order to build the thing. Not features. Assumptions. The output is usually 15-25 questions, and about a third of them are ones I'd have glossed over.
For the dog groomer project, Claude surfaced things like: does the groomer have multiple staff members, or is it a solo operation? Does booking need to account for pet size affecting appointment length? Is there a deposit or payment capture at booking time? I hadn't thought about the pet size thing at all. Neither had the client, as it turned out. We caught that in the discovery call instead of sprint three.
---
The Prompt Structure That Actually Works
I've tried a lot of different ways to prompt for spec work. Generic stuff like "help me design a booking app" gets you generic rubbish. What works is a structured input that gives Claude enough context to constrain its output.
Here's the rough template I use now:
- Role definition. I tell Claude it's acting as a senior product manager who has shipped B2B SaaS before and is allergic to scope creep.
- Raw brief. Paste it verbatim, however rough it is.
- Constraints. Budget range, tech stack if known (we default to WordPress/WooCommerce for most client sites, custom Laravel for anything heavier), timeline, team size.
- Output format. I ask for a structured doc with specific sections: problem statement, user personas, core user flows, feature list (MVP vs. post-launch), open questions, and risks.
The constraints part is the bit most people skip. It matters enormously. "Budget: £8,000, timeline: 8 weeks, two developers and a part-time designer" produces a very different spec to the same brief with no constraints. Without them, Claude will happily spec a product that would take six months and £60k to build. Which is fun to read and useless to ship.
---
Iterating on the Spec With Adversarial Prompting
Getting a first-draft spec is the easy bit. The real value is in the iteration.
After Claude produces the initial document, I run what I call an adversarial pass. I literally ask it: "Now argue against this spec. Where is scope creep most likely to happen? What have we underestimated? What feature on this list will cause the most technical debt in 12 months?"
Seahawk had a fintech client back in 2022 who wanted a dashboard for tracking micro-investment portfolios. The first spec looked solid. The adversarial pass flagged that the "real-time price updates" feature in the MVP was doing a lot of heavy lifting and would probably require a WebSocket architecture that none of our timeline or budget accounted for. We caught it. We scoped it to polling every 60 seconds for MVP, with real-time as a phase two feature. Client was fine with it. Would we have caught that without the adversarial pass? Maybe. But probably not until someone was three weeks into build.
The adversarial step adds maybe 20 minutes to the process. It's worth it every time.
---
Translating Spec Into User Stories
Once the spec is solid enough that I'm not embarrassed by it, I move into user story generation. This is where Claude genuinely shines, because writing good user stories is tedious and easy to do badly.
I feed the spec back to Claude and ask for user stories in the standard format: "As a [role], I want [action] so that [outcome]." I also ask it to flag acceptance criteria for anything non-trivial, because "as a groomer I want to block out holiday time" has a surprising number of edge cases (recurring blocks? what timezone? does it notify clients with existing bookings?).
A few things I insist on:
- Stories should be written for a specific persona, not a generic "user"
- Each story gets a rough complexity estimate (S/M/L, nothing more granular than that at this stage)
- Anything in the "L" bucket gets flagged for further decomposition before it goes into Jira
That last point matters. An L story in a sprint planning meeting is basically a grenade. Getting Claude to surface them early means we have a conversation before someone starts building.
---
Where I Draw the Line With Claude
I want to be honest about this, because I see a lot of breathless takes about AI doing everything now.
Claude is not good at deciding things. It's excellent at laying out options and trade-offs, but the actual decision about whether to build a custom notification system or use Novu (which we've used on three projects now and would recommend) still requires someone who knows the project, the client, and the team's capabilities.
I've also found it unreliable on anything involving specific library versions or niche API behaviours. For broad architecture discussions it's fine. For "will this specific version of WPGraphQL handle this specific query pattern under load," I'd rather test than trust.
And honestly? The prompting itself takes skill. A junior on my team tried to use the same workflow and got mediocre specs back, because the constraint and role framing wasn't tight enough. The tool amplifies whoever's using it. That's not a criticism, just worth being realistic about.
---
Organising the Output Into a Living Document
The spec Claude produces isn't the final artefact. It's input.
My actual deliverable to a client is a Notion document that gets built from the Claude output but reorganised into a format that makes sense for sign-off. Typically:
- Executive summary (3-4 sentences, no jargon)
- Scope (what's in, what's explicitly out)
- User personas (2-3 max, any more is noise at this stage)
- Core flows (written as numbered steps, not prose)
- Feature table (columns: feature, MVP or phase 2, rough effort, owner)
- Open questions (anything that blocks a decision, with a named person responsible for answering it)
- Risks and mitigations
That open questions section is something I started doing after a project in 2020 went sideways because everyone assumed someone else had figured out the data retention policy. Naming a person against each open question means it doesn't just sit there indefinitely.
The Notion doc gets shared with the client, they comment directly in it, and we do a 45-minute call to walk through it. Nothing goes to a developer until every open question has an answer.
---
The Actual Time Savings, Honestly Stated
Before this workflow, a spec for a medium-complexity project (say, a membership portal or a custom e-commerce build) would take me a day and a half. Writing, second-guessing, rewriting. Sending a draft to a colleague, getting comments, incorporating them.
Now it's closer to two to three hours for the Claude-assisted draft, then maybe another hour of human editing and client-facing polish. Call it three to four hours total.
That's not a trivial saving across a year. At Seahawk we're delivering specs on maybe two or three projects a month. Even at a conservative estimate, that's 50-70 hours a year I'm not spending writing first-draft specs from scratch.
But the bigger win, honestly, is quality. The adversarial pass in particular catches things I'd have missed. The assumption-surfacing at the start means discovery calls are more productive because we're discussing real decisions, not me scrambling to fill gaps I hadn't noticed.
---
FAQ
Does this workflow work for internal tools as well as client projects?
Yes, and sometimes it works better for internal stuff because you know the user better than any client brief can tell you. I used essentially the same process when we were speccing out Seahawk's own internal time-tracking tool last year. The constraint input was easy because I knew the budget (£0 in external spend, one developer, three weeks) and the personas were literally people in the office.
Can a non-technical founder use this without a developer?
To a point. The assumption-surfacing and user story steps work fine without technical knowledge. Where it gets tricky is the adversarial pass and the effort estimation. You need some experience to know when Claude is underestimating complexity. If you're non-technical, do that step with someone who's shipped software before, even if it's just a one-hour call.
How do you handle confidential client information when using Claude?
I anonymise anything sensitive before it goes into a prompt. Client names become "[Client]", any personally identifiable data gets stripped. I also use Claude via the API for anything genuinely sensitive, where Anthropic's enterprise data handling terms apply, rather than the consumer product. Worth reading Anthropic's usage policy before you decide what's appropriate for your context.
Does the spec always survive first contact with developers?
No. And it shouldn't. The spec is a forcing function for having the right conversations early, not a contract that freezes thinking. What I tell clients is: the spec is a shared understanding of what we're building today. It will change. What it does is make those changes visible and deliberate instead of accidental.
---
A spec isn't a document. It's an argument. You're arguing that you understand the problem well enough to build something worth building. Claude doesn't make that argument for you. But it makes a remarkably useful sparring partner while you figure out what you actually want to say.
That's worth two hours of anyone's time.