Ask AI for a spec before you write code

What a spec does for vibe coders

A spec gives the model a shape to work inside.

Without one, you tend to get a mash of guesses, filler, and half-remembered assumptions. With one, you get something the AI can actually reason about: the user, the problem, the constraints, the edge cases, and the finish line.

That matters even more for beginners. New vibe coders often think the first prompt should be "build me an app." It should usually be "help me define the app." That small shift saves a stupid amount of time.

[IMAGE: A simple before-and-after diagram showing a fuzzy prompt turning into a short spec before code starts]

• Type: diagram
• Filename: ai-spec-before-code-flow.png
• Alt text: Workflow showing a fuzzy idea becoming a short spec before code generation
• Caption (optional): The model is better when the shape is clear.

What should go in the spec?

Keep it short. One page is usually enough.

1. The job to be done. What is this thing for?
2. The user. Who is it for, exactly?
3. The happy path. What does success look like?
4. The constraints. Time, stack, budget, devices, permissions.
5. The nasty bits. Auth, errors, data, edge cases, rollback.
6. The output. What format do you want back?
7. The done test. How do you know it is finished?

OpenAI's prompt guidance says the same basic thing in fancier clothes: be clear, split complex tasks, provide reference text, and specify the output format. GitHub's issue template docs point the same way from a different angle. Structure gets better results than vibes alone. Shocking, I know.

A simple spec template

Build this: [one sentence] For: [user] Success looks like: [2-3 bullets] Constraints: [stack, time, budget, device, auth, etc] Edge cases: [3-5 bullets] Output needed: [what you want AI to return] Done when: [clear pass/fail check]

How to prompt AI for the spec

Do not ask for the whole app first. Ask for the brief.

1. Describe the goal in plain English.
2. Ask the model to turn it into a short spec.
3. Tell it to include assumptions and unknowns.
4. Ask for one or two implementation options.
5. Only then ask for code.

A decent prompt looks like this:

Turn this idea into a short build spec. Include the user, the problem, the main flow, edge cases, constraints, and what done looks like. Keep it under 300 words. Then give me one recommended implementation path.

That is better than "make me an app" because it makes the model do the thinking work before the code work.

What to do with the spec after that

Use the spec as the handoff between thought and code.

• Paste it into the coding prompt.
• Use it to write issue templates.
• Use it to check if the build drifted.
• Use it to decide what not to build yet.

If the spec is weak, stop there and fix it. Do not keep adding code to a bad shape. That is how you end up with a fancy mess that is expensive to untangle.

What the finished setup should look like

If you are teaching setup, repo structure, or agent instructions, show the reader the target state they should end up with. That way they can compare their setup against something concrete.

my-project/
├── AGENTS.md
├── CLAUDE.md
├── .github/
│   └── ISSUE_TEMPLATE/
│       ├── bug-report.md
│       └── feature-request.md
├── prompts/
│   └── build-spec.md
└── src/
    └── app.ts

# build-spec.md

Turn this idea into a short build spec. Include the user, the problem, the main flow, edge cases, constraints, and what done looks like.
Keep it under 300 words.
Return:
- the spec
- one recommended implementation path
- any assumptions or unknowns

That gives people something to check. If their AI setup cannot produce that shape, they know exactly what is missing.

What is an AI project brief? A short, structured description of the problem, the user, the constraints, and the definition of done, written before code starts.

FAQ

Why ask for a spec before code? Because it forces clarity early. Bad shape at the start usually means expensive cleanup later.

How long should the spec be? Short. Usually 150 to 300 words is enough for a first pass.

What if I already know what I want? Still write the spec. You may know it, but the model does not unless you spell it out.

When should I skip the spec? Tiny throwaway tasks. If you can finish it in five minutes, writing the spec may be overkill.

CTA

If you want your next vibe-coded build to stop wandering, start with the spec.

Not a manifesto. Not a thesis. Just enough shape that the model can help without guessing.

Related post | More practical Labs guides