Writing technical specs with AI: process, prompt, template

Every technical specification for a developer starts the same way: the client pictures the result but can't state it clearly. The easiest way to write a spec with AI is an interview: the model asks clarifying questions and then assembles the answers into a structured document. Below are prompts for each step, API code, common mistakes and a review checklist.

Why you need this

A good spec saves the developer from guessing what you meant and cuts down on clarifications along the way.

Without a spec, the developer writes code, then it turns out something else was intended, and part of the work is redone. With a spec, requirements are agreed before work starts. The model helps at the idea stage: it asks questions you didn't think of and points out contradictions while they cost nothing.

Process structure

1. You describe the idea — the main goal and basic requirements.
2. The model asks clarifying questions. You answer.
3. The model generates a spec based on your answers. You review and edit.
4. Result: a ready document for the developer.

At each stage, you stay in control; the model is an assistant that remembers details and flags what you've left unsaid.

Step 1: the interview prompt — writing a spec with AI

Give the model the role of interviewer. Here's a sample prompt:

Open the browser chat↗ and paste this prompt. If you want to run the interview from a terminal or build it into your own tool, use the API — below is a simple loop that keeps the conversation history:

from openai import OpenAI

client = OpenAI(
    base_url="https://api.zukko.pro/v1",
    api_key="fetch_your_key"
)

prompt = """You are an experienced tech lead. Your job is to interview me about a new project 
and draft a technical specification based on my answers.

Ask 5–7 clarifying questions to understand:
1. What exactly needs to be built (goal and outcome)
2. Who will use it (users)
3. What constraints exist (budget, time, technology)

Step 2: answer the questions

The model will start asking. Answer honestly and in detail. If you don't know something yet — say so.

Good answers:

• "A project management system for small teams (2–10 people)"
• "Integrates with Slack, main work in a web interface"
• "Budget ~$50k, timeline 4 months, stack React + Node.js"

Bad answers:

• "Like ChatGPT, but better" (what do you mean by "better"?)
• "In Python" (why?)
• "Fast, cheap, beautiful" (specific numbers?)

The model will dig deeper. The more concrete your answers, the less the model has to fill in on its own.

Step 3: generate the spec

After the interview, ask the model to draft a spec. Here's a prompt:

Send this prompt in the same conversation where the interview took place. The model returns a draft spec — a draft that still has to be reviewed.

Step 4: review and edit

Never send a spec to the developer without review. Look for:

1. Logical gaps. "The system automatically sends notifications" — to whom exactly? If that's not described, it's a gap.
2. Invented details. The model might invent a feature you never discussed. Verify each point.
3. Wrong technologies. If you didn't mention React, the model might suggest it. Clarify.
4. Insufficient detail. "Slack integration" — what does that mean? Notifications? Two-way sync?

Ask the model to redo sections that raised questions:

Common mistakes and how to avoid them

Mistake 1: Too vague description

Wrong: "Social network for programmers"

Right: "A social network where programmers share solutions to technical problems. Core features: tag-based search (language, topic), popular answer caching, GitHub profile integration. Target audience: freelancers and employees at small startups who need answers faster than Googling Stack Overflow."

With a vague description, the model fills the gaps with guesses. Give it material to work with.

Mistake 2: Ignoring contradictions

Sometimes requirements conflict: "I want maximum affordability and high reliability at a million users." The model might promise both, but you have to choose the priorities.

Model question: "What's more important — cost or reliability?"

Your answer: "Reliability is critical. We can increase budget if needed."

After that answer, ask the model to revise the architecture section.

Mistake 3: Insufficient user information

The model can't guess who will use it. Tell it:

• How many users?
• Which region?
• What's their tech level?
• How often will they use it?

"Project management system" vs "Project management system for 50 developers at a startup used to Jira but want simpler" — these are completely different specs.

Mistake 4: Trusting invented justifications

The model might write: "Use language X for max performance because Y." It sounds convincing but might be wrong.

Verify:

• Is this a real feature of the language?
• Did you even mention this language?
• Is it confirmed by documentation or your own experience?

If unsure, ask the model a leading question:

Ready template for your first spec

Here's the full process in one prompt:

Copy this template, fill in your answers, send to the model.

Where to get the model: chat or API

For your first time, use the browser chat:

• https://zukko.pro/app/chat↗
• Open it, paste the prompt, answer the questions.
• It is charged to the same balance as API requests.

When you need automation (e.g., generate specs for 100 ideas):

• Use the API via Python or curl.
• Save results to files or a database.

The API needs a key: create one on the API keys↗ page and connect it following the quick start↗.

What it costs: an interview plus a draft spec is a few dozen messages. Suppose the whole conversation, with the history resent each turn, took 60,000 input and 8,000 output tokens (see the exact numbers in the response usage or in the "Usage" section of the dashboard). On claude-sonnet-5 that is (60,000 × 0.3 + 8,000 × 0.3) / 1,000,000 = $0.0204.

Checklist before sending spec to the developer

• Every requirement verified — is it from our talk, not invented?
• Architecture is concrete — components not fuzzy?
• Timeline and budget specified?
• APIs/integrations described with examples?
• Acceptance criteria clear (can you verify completion against them)?
• No contradictions (like "cheap and reliable at a million scale")?
• Can the developer read it without extra questions?

If all yes, the spec is ready.

FAQ

Can the model replace a product manager?

Partially. It can draft, find gaps, structure chaos. But strategic decisions — what's the priority, what risks to take — stay with you.

Does the model hallucinate when writing specs?

Yes. So always verify. It might suggest a feature you never discussed or a technology out of nowhere. Ask: "Where did you get this? Did we discuss it?"

How often should I ask the model to double-check?

Once per major spec section. Ask: "Which of these requirements didn't we discuss? What did you add on your own?" Check the model's answer against the conversation too — it can be wrong here as well.

Which model for the interview — Claude or GPT?

You can't know in advance. Run the same interview on claude-sonnet-5 and gpt-5.6-sol (both $0.3 per 1M tokens) and compare whose questions are more useful and whose draft contains less invented material. The current list is at GET https://api.zukko.pro/v1/models or in the models reference↗.